企业官网建设流程全解析

1. 小遥搜索 v1.6.0 云端嵌入模型到底解决了什么问题

小遥搜索 v1.6.0 云端嵌入模型支持，简单说就是让本地知识库检索不再被本地算力绑死。它是一款面向本地文件与知识库的搜索工具，v1.6.0 之前只能用本地 BGE-M3 这类嵌入模型，向量维度固定、语义召回上限也固定。这个版本新增了 OpenAI 兼容的云端嵌入接口，你可以把「文本转向量」这一步交给云端模型，本地只负责存索引和检索。

适合谁用？三类人最明显：一是本地机器显存不够、跑 BGE-M3 时索引慢到想砸键盘的；二是知识库里混了大量中英夹杂、专业术语，本地小模型语义召回总差一口气的；三是已经在用 OpenAI 或兼容接口做 RAG，希望搜索环节和现有技术栈对齐的。我试过把一批技术文档从本地模型切到 text-embedding-3-small，语义查询的命中率提升是能直接感知到的。

但这里有个必须先讲清楚的坑：切换嵌入模型不是改个下拉框就完事。不同模型产出的向量空间完全不兼容，768 维的 BGE 向量和 1536 维的 OpenAI 向量没法放在同一个 Faiss 索引里比对。所以 v1.6.0 把「重建索引」做成了切换模型的强制配套动作，设置页保存后必须去索引管理页重建，否则搜索要么报错要么返回一堆无关结果。

这篇就按真实操作顺序走：先讲清楚云端嵌入的接入配置，再给可复制的参数片段，然后演示重建索引前后的检索命中对比，最后把 401、维度不匹配、重建卡住这些常见错一次性排掉。全程围绕「小遥搜索 v1.6.0 云端嵌入模型 + 重建索引 + OpenAI 接入」这条主线，你跟着做就能完成从本地到云端的平滑切换。

2. TaoToken 前置：给云端嵌入模型准备一个稳定可用的 OpenAI 兼容入口

小遥搜索 v1.6.0 的云端嵌入走的是 OpenAI 兼容协议，也就是标准的/v1/embeddings端点。这意味着你填的端点地址必须能被小遥搜索的 aiohttp 客户端正常访问，并且返回 OpenAI 格式的向量响应。很多人在这一步卡住，不是小遥搜索的问题，而是端点本身不稳定或者鉴权格式对不上。

TaoToken 在这里的角色就是一个 OpenAI 兼容的 API 接入层。它的 API 地址是https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 Base URL 填进小遥搜索的「端点地址」即可。小遥搜索内部会拼接成https://taotoken.net/api/v1/embeddings去请求，所以你在配置里不要自己再补/v1，否则会变成/api/v1/v1/embeddings直接 404。

为什么建议先用 TaoToken 跑通再考虑其他端点？因为嵌入模型接入最怕两件事：一是鉴权头格式不对，二是端点对批处理大小有限制。TaoToken 的接口对 OpenAI 标准兼容度比较高，Authorization: Bearer <key>这种头能直接过，批处理 32 条一批也不会被拒。你可以在模型对话页面先确认 key 是活的，再去小遥搜索里填，能省掉一半排障时间。

具体要准备三样东西，这三件套缺一不可：

如果你还没生成 key，去 API Keys 页面创建一个，权限选嵌入或全量都行。生成后先别急着关页面，复制下来，小遥搜索的设置页只显示一次输入框，填错了要重新粘贴。另外提醒一句：嵌入模型的调用是按 token 计费的，重建索引时会把知识库里所有文本重新过一遍，文件多的话先在模型对话页面小批量测一下，确认端点和模型名都对，再全量重建。

3. 可复制配置：小遥搜索 v1.6.0 云端嵌入模型接入片段

这一节给的是能直接抄的配置。小遥搜索 v1.6.0 的设置入口在「设置 → 嵌入模型」标签页，里面有一个「模型类型」单选，选「云端 API」后展开三个输入框：API 密钥、端点地址、模型名称。下面按这个界面顺序给配置。

先给一份 JSON 形式的配置快照，方便你对照字段名。小遥搜索本身不直接读这个 JSON，但它的后端配置结构大致长这样，你填界面的三个框时心里有数：

{ "embedding": { "provider": "cloud", "api_key": "sk-你的TaoToken密钥", "base_url": "https://taotoken.net/api", "model": "text-embedding-3-small", "batch_size": 32, "timeout": 30, "max_retries": 3 } }

对应到界面上的填写：

API 密钥：sk-你的TaoToken密钥 端点地址：https://taotoken.net/api 模型名称：text-embedding-3-small

填完点「保存设置」，然后重启应用。注意 v1.6.0 的模型切换是「重启生效」，不重启的话后端还是加载旧的本地模型配置，你会以为配置没生效。重启后回到「索引管理」页面，这时候旧索引还是本地模型建的，必须重建。

重建索引的入口在索引管理页，「添加路径」按钮左边有一个红色「重建索引」按钮。点下去会弹确认框，确认后系统做四件事：清空所有现有 Faiss 索引文件和 Whoosh 索引目录、查询历史已完成的索引任务、按 folder_path 去重、为每个唯一路径创建新的 IndexJob 并排队。重建期间旧索引已经清空了，所以搜索会暂时不可用，进度条会显示百分比和已处理/总文件数。

如果你用的是 Claude Code 或 Cline 这类工具配合小遥搜索做知识库检索，建议把三件套也同步过去，保持嵌入模型一致，否则两边向量空间不同，检索结果会对不上：

# 以 Cline MCP 配置为例，保持嵌入模型与 TaoToken 端点一致 [mcp_servers.xiaoyao] command = "npx" args = ["-y", "xiaoyao-search-mcp"] env = { EMBEDDING_BASE_URL = "https://taotoken.net/api", EMBEDDING_API_KEY = "sk-你的TaoToken密钥", EMBEDDING_MODEL = "text-embedding-3-small" }

这里的三件套就是 Base URL、Key、Model ID，任何一处不一致都会导致检索时向量维度或语义空间对不上。配置完先别全量重建，拿一个小文件夹试跑，确认能出结果再铺开。

4. 验证请求：重建索引前后的检索命中对比

配置填完、重启、重建索引跑完之后，怎么确认云端嵌入真的生效了？不能只看设置页显示「云端」，要看检索结果。这一节给一个可复现的对比验证动作。

准备一个测试查询，选那种「关键词不完全匹配但语义相关」的句子，比如你的知识库里有一篇讲「向量数据库选型」的文档，但里面没出现「向量数据库」这五个字，而是写「Faiss 与 Milvus 的取舍」。用本地 BGE-M3 时，这种查询可能召回不到；换成 text-embedding-3-small 后，语义空间更宽，召回概率明显上升。

验证步骤：

第一步，重建索引前，先在搜索框输入这个测试查询，记下返回结果的数量和第一条的标题。如果本地模型召回为 0 或第一条不相关，记下来。

第二步，按第 3 节完成云端配置和重建索引，等进度条到 100%。

第三步，用同一个查询再搜一次，对比结果数量和第一条标题。实测下来，语义类查询的命中率提升最明显，精确关键词查询反而可能因为阈值调整略有变化。

这里要解释一下 v1.6.0 修的那个 bug，它直接影响你的验证结果。旧版本全文搜索的阈值写死 0.5，对高维模型太严格，导致 1536 维的 text-embedding-3-large 搜全文时返回空。v1.6.0 改成按维度动态设阈值：

所以你用 text-embedding-3-small（1536 维）时，阈值是 0.1，比本地模型的 0.2 宽松，召回会更多。如果你验证时发现结果突然变多但有点杂，这是阈值放宽的正常表现，不是 bug。混合搜索算法也调了，精确关键词查询优先走全文搜索，语义查询优先走语义搜索，两种都匹配的结果会被加权提前。

验证通过的标准很简单：同一个语义查询，重建后能召回重建前召不到的那条文档，且第一条就是你要找的。如果重建后反而全空，先别怀疑模型，去第 5 节对照报错。

5. 本篇常见错排查：401、维度不匹配、重建卡住怎么解

这一节按真实报错来。小遥搜索 v1.6.0 云端嵌入接入过程中，下面几个错出现频率最高，每个都给定位方法和修复动作。

报错一：401 Unauthorized 或 invalid api key

这是鉴权没过。先确认 API 密钥填的是 TaoToken 生成的sk-开头那串，没有多余空格。然后确认端点地址是https://taotoken.net/api，没有自己补/v1。如果还报 401，去 API Keys 页面确认这个 key 没被删、没过期、权限包含嵌入。小遥搜索的 aiohttp 客户端发的是Authorization: Bearer <key>，标准格式，一般不会错在头上。

报错二：local proxy failed 或 connection refused

这个错说明小遥搜索连不上你填的端点。检查端点地址能不能在浏览器或 curl 里通：

curl -X POST https://taotoken.net/api/v1/embeddings \ -H "Authorization: Bearer sk-你的密钥" \ -H "Content-Type: application/json" \ -d '{"model":"text-embedding-3-small","input":"测试文本"}'

如果这条 curl 返回向量数组，说明端点没问题，问题在小遥搜索的配置或网络环境。如果 curl 也失败，检查端点地址拼写。注意不要在任何配置里出现代理相关设置，小遥搜索直连即可。

报错三：reading choices 或 response parse error

这个错通常出现在端点返回的不是标准 OpenAI 嵌入格式时。小遥搜索期望的响应结构是{"data":[{"embedding":[...]}],"model":"..."}。如果端点返回了别的结构，解析就会失败。确认模型名称填的是端点真正支持的嵌入模型，比如text-embedding-3-small，不要填成对话模型名。填错模型名有时端点会返回一个错误对象而不是嵌入数组，表现就是 reading choices 失败。

报错四：重建索引卡在 0% 或进度不动

先看后端日志，重建走的是 IndexJob 任务系统和 run_full_index_task 后台任务。卡住常见原因有两个：一是某个文件夹路径权限不足，后台任务读文件时抛异常但没中断；二是批处理时某批请求超时，tenacity 重试三次后仍失败，用零向量填充，导致该批文件索引质量差。解决办法是检查路径权限，并把 batch_size 从 32 调小到 16 试一次。重建支持多路径同时进行，如果只有一个路径卡住，其他路径会继续，不用整体重来。

报错五：切换模型后搜索返回空或维度不匹配

这是没重建索引的典型症状。向量空间不兼容，旧索引是 1024 维，新模型是 1536 维，Faiss 直接比对会出错或返回空。回索引管理页点「重建索引」，等完成再搜。记住：每次切换嵌入模型，无论本地换云端还是云端换云端，都必须重建。

报错六：OAuth 或 token 过期类提示

如果你用的是带 OAuth 的端点，token 过期会导致 401。TaoToken 的 key 是长期有效的，一般不会遇到。如果遇到，重新生成 key 并更新小遥搜索配置，然后重启应用。

排查顺序建议：先 curl 验端点，再查小遥搜索配置三件套，再看后端日志，最后才怀疑模型本身。大部分问题出在端点地址多写了/v1或 key 复制带了空格。

6. 从本地到云端嵌入的平滑切换，关键在重建索引这一步

小遥搜索 v1.6.0 把云端嵌入模型接进来之后，本地知识库检索的上限确实被抬高了，但整个切换过程里最容易被低估的就是重建索引。配置三件套填对只是入场券，真正决定检索质量的是重建有没有跑完、跑干净。我踩过的坑是第一次切换时以为保存设置就生效了，搜出来一堆空结果，折腾半天才发现旧索引没清。

给你一个实用技巧：重建之前先把知识库按文件夹分个优先级，先重建最常用的那个路径，验证检索命中没问题，再重建其余路径。这样即使某个路径的云端调用出问题，也不会影响你已经验证过的那部分。另外，重建期间虽然旧索引已清空，但如果你保留了原始文件，随时可以回退到本地模型重新建一次，不会丢数据。

最后把入口再理一遍：配置云端嵌入需要 Base URL、API Key、Model ID 三件套，Base URL 用https://taotoken.net/api，Key 在 API Keys 页面生成，Model ID 填text-embedding-3-small。接入文档里有完整的端点说明和参数示例，遇到鉴权或端点问题先去那里对照。验证模型是否可用，可以在模型对话页面发一条测试请求，确认返回正常再回小遥搜索重建。如果你打算长期用云端嵌入配合编码或 Agent 工作流，Coding Plan 那边有更完整的接入方案，能把这套嵌入配置复用到更多工具里。