企业官网建设流程全解析

1. FAQ 机器人为什么需要查询路由

做客服 FAQ 机器人时，最容易踩的坑就是「所有问题都丢给同一个大模型」。用户问「怎么查物流」，你调一次旗舰模型，等三秒、花掉一笔 token；用户问「我上周买的 OTG 到货就坏了，还被重复扣款，收货地址也写错了」，你还是调同一个模型，结果它只回答了损坏问题，另外两个诉求直接漏掉。慢和贵只是表象，真正的问题是：简单问题和复杂问题需要的处理策略根本不一样。

我试过把 FAQ 机器人拆成两段：第一段做查询路由，只判断「这个问题该走哪条路」；第二段才是回答生成。路由阶段不读全文，只看 Elasticsearch 返回的元数据——相关性评分、问题类别、复杂度标签、产品分类。这些结构化信号足够判断：是命中单篇 FAQ 直接改写，还是需要跨多篇文章综合。路由用便宜的小模型跑，回答阶段再按复杂度分流到不同模型。

这套思路落地时有两个现实障碍。一是模型接入：Mistral、Claude 这类模型各自有 API Key、各自的鉴权头、各自的计费口径，散落在代码里很难维护。二是链路验证：路由决策对不对，最终要看 Elasticsearch 检索结果有没有正确回填到回答里，中间任何一环断了都很难定位。TaoToken 在这里的作用是把多模型调用收敛成一个统一 Key 的 API 通道，让路由层和回答层用同一套接入方式，配置集中、切换成本低。

这篇面向已经在用 Elasticsearch 做检索、想加一层 LLM 意图分流的开发者。我会给出 config.toml 与 settings.json 骨架、统一 Key 的通道配置，以及一次可复现的路由命中验证动作，目标是把「查询分流 → 检索 → 结果回填」这条链路跑通并确认正确。

2. TaoToken 前置：统一 Key 与通道配置

TaoToken 的定位是模型调用的统一入口。官网在 https://taotoken.net ，API 端点是 https://taotoken.net/api ，兼容 OpenAI 风格的/v1/chat/completions调用方式。也就是说，你原来写openaiSDK 的地方，把base_url换掉、api_key换成 TaoToken 的 Key，就能调用到不同厂商的模型。对查询路由这种「同一份代码要调多个模型」的场景，这一点很关键——路由用小模型、回答用大模型，不需要维护两套 SDK 初始化逻辑。

先拿 Key。登录后进控制台，在 API Keys 页面创建一个 Key，复制出来。这个 Key 就是后面 config.toml 和 settings.json 里要填的东西。控制台地址是 https://taotoken.net/console ，API Keys 页面在 https://taotoken.net/api-keys 。创建时建议按用途命名，比如faq-router-dev，方便后面区分环境。

模型选择上，路由层建议用轻量模型，比如 Mistral Small 这类；回答层按复杂度分流，简单 FAQ 继续用轻量模型，复杂多源综合再切到能力更强的模型。TaoToken 的模型对话页面可以直接试跑，确认某个模型名能不能调通、返回格式对不对，地址是 https://taotoken.net/models 。这一步别省，模型名写错是后面最常见的报错来源。

如果你后面要把这套路由逻辑接到长期运行的编码或 Agent 流程里，可以看 Coding Plan，地址是 https://taotoken.net/coding-plan ，它更适合持续调用的场景。接入文档在 https://taotoken.net/doc ，里面有各语言 SDK 的接入示例和参数说明，遇到鉴权或请求体格式问题先查这里。

注意：Key 只放在服务端配置或环境变量里，不要写进前端代码或提交到仓库。路由层和回答层可以用同一个 Key，也可以按环境拆成两个，取决于你的密钥轮换策略。

3. 可复制配置：config.toml 与 settings.json 骨架

配置分两块：一块是模型通道（config.toml），一块是 Elasticsearch 连接与索引设置（settings.json）。分开的原因是模型通道可能按环境切换，而索引结构相对稳定。

先看 config.toml。这里定义 TaoToken 的 base_url、Key 的读取方式，以及路由模型和回答模型的名称。Key 不直接写死在文件里，用环境变量注入，避免泄露。

# config.toml [llm] base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" timeout_seconds = 30 max_retries = 2 [llm.router] # 路由层：只做复杂度分类，用轻量模型 model = "mistral-small-latest" temperature = 0.0 max_tokens = 256 [llm.answer_simple] # 简单 FAQ：单篇文章改写 model = "mistral-small-latest" temperature = 0.3 max_tokens = 512 [llm.answer_complex] # 复杂多源综合：需要更强模型 model = "claude-sonnet-4-6" temperature = 0.2 max_tokens = 1024 [elasticsearch] hosts = ["https://your-es-endpoint:9200"] index_name = "support-knowledge-base" top_k = 5

temperature = 0.0给路由层，是因为分类任务要稳定，同样的输入最好给同样的判断。回答层可以稍微放开一点，让措辞自然些。top_k = 5和后面检索步骤保持一致，路由分类只看这 5 条的元数据。

再看 settings.json，这里放 Elasticsearch 索引映射和语义字段配置。核心是用copy_to把对话内容和问答摘要聚合成一个可搜索字段，再用semantic_text做语义检索。

{ "index": "support-knowledge-base", "mappings": { "properties": { "conversation": { "type": "text", "copy_to": "semantic_content" }, "qa": { "type": "text", "copy_to": "semantic_content" }, "issue_area": { "type": "keyword" }, "issue_category": { "type": "keyword" }, "issue_complexity": { "type": "keyword" }, "product_category": { "type": "keyword" }, "semantic_content": { "type": "semantic_text", "inference_id": ".jina-embeddings-v5-text-small" } } }, "search": { "field": "semantic_content", "size": 5 }, "routing": { "simple_threshold": 0.85, "complex_labels": ["medium", "high"] } }

issue_complexity和issue_category这两个 keyword 字段是路由决策的关键输入。如果索引里这两个字段缺失或标注不一致，路由准确率会明显下降——这是后面排障部分要重点检查的地方。simple_threshold是我自己加的一个经验阈值：当最高分命中超过这个值、且复杂度标签是 low 时，倾向判为简单查询。

把两份配置放到项目里，环境变量设好：

export TAOTOKEN_API_KEY="你的Key" export ES_ENDPOINT="https://your-es-endpoint:9200"

4. 验证请求：一次可复现的路由命中验证

配置写完不能直接上生产，先做一次最小可复现验证：发一个查询，看路由分类结果、看检索命中、看回答有没有正确回填检索内容。下面这段 Python 把三步串起来。

import os import json import requests from elasticsearch import Elasticsearch TAOTOKEN_BASE = "https://taotoken.net/api" API_KEY = os.environ["TAOTOKEN_API_KEY"] ES = Elasticsearch(os.environ["ES_ENDPOINT"]) def search_kb(query, top_k=5): resp = ES.search( index="support-knowledge-base", size=top_k, query={"semantic": {"field": "semantic_content", "query": query}}, ) return resp["hits"]["hits"] def classify(query, hits): # 只传元数据，不传全文 meta_lines = [] for i, h in enumerate(hits): src = h["_source"] meta_lines.append( f"{i+1}. score={h['_score']:.3f}, " f"category={src.get('issue_category')}, " f"complexity={src.get('issue_complexity')}, " f"product={src.get('product_category')}" ) prompt = ( "你是客服查询分类器。根据查询和以下命中元数据，" "只返回 JSON：{\"complexity\": \"simple\" 或 \"complex\", \"reasoning\": \"一句话\"}。\n" f"查询：{query}\n命中元数据：\n" + "\n".join(meta_lines) ) r = requests.post( f"{TAOTOKEN_BASE}/v1/chat/completions", headers={"Authorization": f"Bearer {API_KEY}"}, json={ "model": "mistral-small-latest", "temperature": 0.0, "max_tokens": 256, "messages": [{"role": "user", "content": prompt}], }, timeout=30, ) r.raise_for_status() content = r.json()["choices"][0]["message"]["content"] return json.loads(content) def answer(query, hits, complexity): model = "mistral-small-latest" if complexity == "simple" else "claude-sonnet-4-6" docs = [h["_source"] for h in hits] if complexity == "complex" else [hits[0]["_source"]] prompt = ( f"根据以下知识库内容回答客户问题，注明引用来源。\n" f"问题：{query}\n知识库：{json.dumps(docs, ensure_ascii=False)}" ) r = requests.post( f"{TAOTOKEN_BASE}/v1/chat/completions", headers={"Authorization": f"Bearer {API_KEY}"}, json={ "model": model, "temperature": 0.2, "max_tokens": 1024, "messages": [{"role": "user", "content": prompt}], }, timeout=60, ) r.raise_for_status() return r.json()["choices"][0]["message"]["content"] if __name__ == "__main__": q = "How do I track my order?" hits = search_kb(q) print("命中数:", len(hits), "最高分:", hits[0]["_score"]) route = classify(q, hits) print("路由结果:", route) print("回答:", answer(q, hits, route["complexity"]))

跑之前确认三件事：TAOTOKEN_API_KEY已导出、Elasticsearch 里support-knowledge-base索引有数据、semantic_content字段能正常做语义检索。运行后你应该看到类似输出：

命中数: 5 最高分: 0.912 路由结果: {'complexity': 'simple', 'reasoning': 'top hit matches single FAQ with high score'} 回答: 你可以在「我的订单」页面点击对应订单查看物流...

关键验证点是「路由结果」和「回答内容」是否一致。如果路由判为 simple，回答应该只基于第一篇文档；如果判为 complex，回答里应该能看到多篇文档的引用痕迹。再换一个复杂查询试：

q = "我上周买的 OTG 到货就坏了，还被重复扣款，收货地址也写错了"

这条涉及三个诉求，正常应该被判为 complex，回答里三个问题都要有对应处理步骤。如果只回答了其中一个，说明检索回填或回答阶段的文档拼接有问题，往下看排障部分。

5. 本篇常见错排查

报错一：401 Unauthorized 或 invalid api key。先确认TAOTOKEN_API_KEY环境变量在当前 shell 里真的存在，echo $TAOTOKEN_API_KEY看一下。如果用的是配置文件里的api_key_env，确认读取逻辑没写错。Key 本身在控制台 API Keys 页面可以重新生成，注意别把前后空格带进去。

报错二：model not found。模型名写错了。路由层和回答层用的模型名必须和 TaoToken 支持的名称一致。去模型对话页面确认一下你要用的模型名，别凭记忆写。mistral-small-latest和claude-sonnet-4-6这类名称区分大小写和连字符。

报错三：路由总是判成 complex。大概率是元数据字段缺失。检查索引里issue_complexity和issue_category是不是有值，GET support-knowledge-base/_search看几条文档的_source。如果这两个字段是空的，分类器拿不到有效信号，只能保守判 complex。另一个可能是_score分布太集中，最高分和第五名差距很小，这时候可以调simple_threshold。

报错四：回答里没有引用检索内容。检查回答阶段的 prompt 有没有把hits的_source真正拼进去。常见错误是只传了_id或只传了标题。另外确认json.dumps用了ensure_ascii=False，否则中文会变成转义序列，模型理解会受影响。

报错五：语义检索返回空。确认semantic_content字段的inference_id配置正确，且索引时确实写入了内容。copy_to的字段名要和semantic_content完全一致，拼写错了内容就不会聚合进去。

报错六：超时。复杂查询走大模型时耗时会长一些，timeout给到 60 秒。如果还是超时，检查max_tokens是不是设太大，或者检索返回的文档太长导致 prompt 过大。路由层保持max_tokens = 256就够，别给它传全文。

6. 把链路固定下来

这套结构跑通之后，建议把路由决策和检索命中一起打日志，格式大概是「查询 → 最高分 → 路由结果 → 使用的模型 → 回答长度」。这样出问题时能快速定位是检索没命中、路由判错、还是回答阶段丢内容。日志里不要打完整 Key，打 Key 的前几位做标识就行。

模型通道这块，TaoToken 的统一 Key 让路由层和回答层共用一套接入配置，换模型只改 config.toml 里的模型名，不用动代码。接入细节和参数说明在 https://taotoken.net/doc ，模型试跑在 https://taotoken.net/models ，Key 管理在 https://taotoken.net/api-keys 。如果后面要把这套路由接到持续运行的 Agent 流程，Coding Plan 在 https://taotoken.net/coding-plan ，适合长期调用场景。

最后留一个实用习惯：每次改完 config.toml 或索引映射，先跑一遍第 4 节那段验证脚本，用同一个简单查询和同一个复杂查询各测一次，确认路由结果和回答回填都符合预期，再往上层接。链路稳定比模型选型更重要。