1. 从.env里两个变量说起知识库问答接 LLM 的真实卡点给腾讯开源的文档知识库问答项目填 LLM API Key 和 API 地址时最容易卡住的往往不是向量库选型也不是分块参数而是配置文件里LLM_API_KEY和LLM_BASE_URL到底写谁。以知识库平台工程师的视角看部署完文档解析、切片、Embedding、检索、Rerank 之后最后一步一定会落到“调用哪个 LLM API”。这一步如果配错前端表现通常是上传文档正常、检索也有命中但生成答案时报401 Unauthorized、404 model not found、Connection timeout或者答案完全不引用文档。本文把这条链路拆成可复现的配置动作TaoToken 只管 Key 和 Base URLKey 去官网获取Base URL 固定用https://taotoken.net/api。官网入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentkb_qa_intro拿到 Key 后按本文示例填入知识库服务、Claude Code、Codex 和 CC Switch。这里先把边界说透TaoToken 不负责 PDF 解析、不负责文本切片、不负责向量化策略、不负责召回排序也不负责 Prompt 模板。它负责的是“调用 LLM 时的入口凭证与 API 地址”。换句话说知识库问答系统里文档怎么变成索引归知识库项目管索引怎么被检索归检索模块管检索结果怎么变成答案才轮到 LLM API。Key 和 Base URL 就是这个 LLM API 的两把钥匙。把这两件事分开排障会清晰很多。2. 知识库问答链路图TaoToken 只出现在 LLM 调用段先给一张文字版链路图方便你在部署时逐段核对。注意这不是 Mermaid只是普通文本可以直接贴到项目 README 或排障记录里。┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ 上传文档 │ - │ 解析清洗 │ - │ 分块切片 │ - │ Embedding │ └──────────┘ └──────────┘ └──────────┘ └────┬─────┘ | v ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ 前端展示 │ - │ 答案引用 │ - │ LLM 调用 │ - │ Prompt │ └──────────┘ └──────────┘ └────┬─────┘ │ 拼装 │ ^ └────┬─────┘ | ^ TaoToken Key/Base | URL 只影响这一段 | | ┌──────────┐ │ Rerank │ │ 召回排序 │ └────┬─────┘ ^ | ┌──────────┐ │ 向量检索 │ │ 全文检索 │ └──────────┘把这张图拆开看上传文档用户把 PDF、Word、Markdown、HTML 或网页链接交给知识库服务。解析清洗知识库项目调用解析器把文档转成纯文本去掉页眉页脚、乱码和无关标签。分块切片按标题、段落、语义或固定长度切 chunk决定后续召回粒度。Embedding把 chunk 转成向量。如果使用远程 Embedding也可能走 OpenAI 兼容接口如果使用本地模型则不走 TaoToken。向量检索/全文检索根据用户问题召回候选 chunk。Rerank对候选 chunk 重新排序取 top_k 作为上下文。Prompt 拼装把系统提示、历史对话、检索结果、用户问题拼成 messages。LLM 调用把 Prompt 发给 LLM API这时才需要 API Key 和 Base URL。答案引用把模型输出和引用来源返回前端。所以当你在知识库项目里看到“LLM 配置”时要分清它到底在配哪一段。大多数项目会把 LLM 配置抽成环境变量例如LLM_API_KEY、LLM_BASE_URL、LLM_MODEL。其中LLM_API_KEY填YOUR_API_KEYLLM_BASE_URL填https://taotoken.net/api。不要把 Base URL 写成前端页面地址也不要写成控制台地址。控制台是拿 Key、看用量、创建 Key 的地方Base URL 是给程序调用的 API 入口。如果项目同时支持远程 Embedding常见配置会拆成EMBEDDING_API_KEY和EMBEDDING_BASE_URL。这时你可以继续使用同一个 TaoToken Key 和https://taotoken.net/api但模型 ID 要换成 Embedding 模型。不要用聊天模型去做 Embedding也不要以为换了 Base URL 就会自动切换模型。模型 ID 必须由配置文件或控制台明确指定。3. Key 与 Base URL 边界哪些配置不该甩给 TaoToken很多排障现场会把问题混在一起检索不准怪 Key回答超时怪 Base URL模型不存在怪知识库。其实只要画一张边界表责任就清楚了。事项归属具体配置/动作常见错误文档上传知识库服务前端上传接口、对象存储上传失败怪 API KeyPDF/Word 解析知识库服务解析器、OCR、清洗规则解析乱码怪 Base URL分块切片知识库服务chunk_size、overlap、标题层级召回不准怪模型Embedding知识库服务或远程模型本地模型或 Embedding API用聊天模型做向量向量库知识库服务Milvus、pgvector、Elasticsearch 等检索为空怪 KeyRerank知识库服务重排模型、规则、score 阈值排序差怪 LLMPrompt 拼装知识库服务system prompt、上下文长度、引用格式答案不引用怪 APILLM API KeyTaoTokenYOUR_API_KEY没替换占位符、多了空格LLM Base URLTaoTokenhttps://taotoken.net/api填成控制台或前端地址模型 IDTaoToken 项目从模型对话页或控制台复制手写模型名、拼错大小写Token 用量TaoToken按 Key 统计多项目混用一个 Key这张表里最关键的一行是 Base URL。TaoToken 的 Base URL 是https://taotoken.net/api不加 UTM 参数也不要额外拼接/v1/v1。如果某个客户端要求 OpenAI 兼容路径通常只需把 Base URL 填成https://taotoken.net/api由 SDK 自己拼接后续路径。你不需要在.env里写控制台地址也不需要把官网首页地址填进去。官网首页是获取 Key、查看文档和创建 Key 的入口例如https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentkb_qa_key_boundary但程序调用只认https://taotoken.net/api。另一个常见边界是 Key 的复用。知识库问答至少有两个阶段可能消耗 Token索引阶段和在线问答阶段。索引阶段如果启用文档摘要、关键词抽取、自动标签可能会调用 LLM在线问答阶段会调用 LLM 生成答案。如果两个阶段共用一个 Key用量会混在一起出问题很难定位。建议在 TaoToken 控制台创建独立 Key例如kb-index-key、kb-qa-key、kb-eval-key。Key 只是字符串但归属清晰后Token 消耗、限流影响、轮换范围都会清晰。4. 知识库后端配置OpenAI 兼容的 Key 与 Base URL 写法大多数腾讯开源文档知识库问答项目会提供.env、config.yaml或 Docker Compose 环境变量。下面给出一个通用 OpenAI 兼容配置示例。你需要把YOUR_API_KEY换成从 TaoToken 官网获取的 Key把YOUR_CHAT_MODEL_ID换成模型对话页里选定的模型 ID。# .env LLM_PROVIDERopenai-compatible LLM_API_KEYYOUR_API_KEY LLM_BASE_URLhttps://taotoken.net/api LLM_MODELYOUR_CHAT_MODEL_ID LLM_TEMPERATURE0.2 LLM_MAX_TOKENS2048 LLM_TIMEOUT60 LLM_MAX_RETRIES2 # 如果 Embedding 也走远程单独配置 EMBEDDING_API_KEYYOUR_API_KEY EMBEDDING_BASE_URLhttps://taotoken.net/api EMBEDDING_MODELYOUR_EMBEDDING_MODEL_ID如果项目使用 Docker Compose可以这样把环境变量传给知识库服务services: kb-api: image: your-kb-image:latest env_file: - .env environment: - LLM_API_KEY${LLM_API_KEY} - LLM_BASE_URL${LLM_BASE_URL} - LLM_MODEL${LLM_MODEL} ports: - 8080:8080 restart: unless-stopped如果你要在自己的代码里验证 Key 和 Base URL 是否可用可以用 OpenAI SDK 写一个最小调用。注意下面代码里的base_url就是https://taotoken.net/api不要加 UTM不要加多余路径。import os from openai import OpenAI client OpenAI( api_keyos.environ[LLM_API_KEY], base_urlos.environ[LLM_BASE_URL], ) def answer_question(question: str, contexts: list[str]) - str: context_text \n\n.join( f[{i 1}] {ctx} for i, ctx in enumerate(contexts) ) system_prompt ( 你是知识库问答助手。只依据给定资料回答 无法从资料中确定时直接说明不知道。 回答末尾列出引用编号。 ) user_prompt f资料\n{context_text}\n\n问题{question} resp client.chat.completions.create( modelos.environ.get(LLM_MODEL, YOUR_CHAT_MODEL_ID), messages[ {role: system, content: system_prompt}, {role: user, content: user_prompt}, ], temperature0.2, max_tokens2048, timeout60, ) return resp.choices[0].message.content or if __name__ __main__: print(answer_question( 这份文档的接入流程是什么, [第一步获取 Key第二步配置 Base URL第三步验证调用。], ))这个例子里知识库项目负责检索出contextsLLM 只负责根据上下文生成答案。如果答案没有引用先检查contexts是否为空、Prompt 是否要求引用而不是先怀疑 Key。如果报401先检查YOUR_API_KEY是否替换、是否复制了多余空格、是否误用了其他平台的 Key。如果报404先检查 Base URL 是否写成https://taotoken.net/api再检查模型 ID 是否存在于当前账号可用列表。如果报超时先减少top_k、缩短上下文、开启流式输出再检查网络和超时设置。5. Claude Code、Codex、CC Switch三套配置不要串知识库平台工程师通常不只配后端还会用 Claude Code 写代码、用 Codex 做 CLI 辅助或者用 CC Switch 管理多个供应商。这里最容易犯的错是把ANTHROPIC_*环境变量套到 Codex 上或者反过来把 Codex 的config.toml格式写到 Claude Code 里。协议不同配置字段也不同。5.1 Claude Codesettings.json 与 ANTHROPIC_*Claude Code 使用settings.json管理环境变量。可以在用户级配置或项目级配置里设置ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN。Base URL 仍然填https://taotoken.net/apiKey 填YOUR_API_KEY。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: YOUR_CLAUDE_MODEL_ID } }如果你的 Claude Code 版本读取的是ANTHROPIC_API_KEY把它设为同一个YOUR_API_KEY即可。但不要同时从多个文件、多个 shell profile 里注入不同 Key否则会出现“改了配置但不生效”的假象。验证时可以在终端查看当前变量echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_MODEL不要打印完整 Key。确认 Base URL 是https://taotoken.net/api模型 ID 与 TaoToken 模型对话页中选择的一致。Claude Code 文档入口见文末 CTA。5.2 Codexconfig.toml 不要写 ANTHROPIC_*Codex 使用config.toml供应商配置和 Claude Code 完全不同。不要把ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN写进 Codex 配置。下面是一个可复制的 Codex 配置骨架model YOUR_CODEX_MODEL_ID model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY然后在 shell 里设置环境变量export TAOTOKEN_API_KEYYOUR_API_KEYCodex 读取的是TAOTOKEN_API_KEY调用地址来自base_url。如果你的config.toml里还残留其他供应商的model_providerCodex 会优先使用当前选中的 provider。切换后建议重启终端避免旧环境变量干扰。5.3 CC Switch 三件套CC Switch 的核心是三件套配置名称、Base URL、API Key。你可以为知识库项目建一个独立配置避免和日常聊天配置混用。配置名称taotoken-kbBase URLhttps://taotoken.net/apiAPI KeyYOUR_API_KEY在 CC Switch 中选择目标客户端时要区分 Claude Code 和 Codex选 Claude Code生成或写入settings.json风格的ANTHROPIC_*配置。选 Codex生成或写入config.toml风格的 provider 配置。不要把 Claude Code 的字段直接粘到 Codex也不要把 Codex 的env_key粘到 Claude Code。CC Switch 只是切换器不改变协议。它帮你管理多套 Key 和 Base URL但最终调用仍然遵循各自客户端的配置格式。5.4 验证配置是否生效验证顺序建议固定先用后端 Python SDK 调一次 chat.completions确认 Key 和 Base URL 可用。再启动 Claude Code问一个简单问题确认ANTHROPIC_BASE_URL生效。再启动 Codex确认config.toml中的model_provider指向taotoken。最后回到知识库问答服务上传一篇文档提问并检查日志中的模型 ID、Base URL 主机、请求耗时。日志里不要打印完整 Key只打印前几位和后几位即可。Base URL 可以完整打印方便确认是否为https://taotoken.net/api。6. Token 消耗归属知识库问答为什么比单轮聊天更吃 Token知识库问答的 Token 消耗通常不是“用户问一句模型答一句”这么简单。一次在线问答可能包含单次在线问答 Token ≈ 系统提示 Token 多轮历史 Token 查询改写/扩展 Token Σ 命中 chunk Token 用户问题 Token 模型输出 Token如果开启 Rerank、摘要、自动标签、多路召回还会有额外调用。索引阶段也可能消耗 Token例如对长文档做摘要、抽取关键词、生成问答对。这些消耗最终都会归属到发起请求的 API Key 上。谁拿着 Key 发请求就算在谁头上。所以建议按用途拆 Keykb-index-key文档解析后的摘要、标签、索引阶段 LLM 调用。kb-qa-key在线问答生成答案。kb-eval-key离线评测、回归测试、批量问答。kb-dev-key本地开发调试。在 TaoToken 控制台创建 Key 后把对应 Key 写入不同环境的.env。例如开发环境用kb-dev-key生产问答服务用kb-qa-key。这样当用量异常时你能快速判断是索引任务跑批还是在线问答流量上涨还是评测脚本失控。创建 Key 的入口在https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentkb_qa_api_keys。另外知识库问答的上下文长度直接决定 Token。检索 top_k 从 5 调到 10Token 可能翻倍多轮历史从 3 轮调到 10 轮也会显著增加。建议给在线问答设置上下文预算例如限制命中 chunk 总长度、限制历史消息条数、超长时先摘要再拼 Prompt。这些优化发生在知识库服务侧不需要改 Key 或 Base URL。7. 排障清单401、404、429、超时、答案不引用分别查什么现象优先检查处理动作401 UnauthorizedKey 是否替换YOUR_API_KEY、是否多了空格、是否误用其他平台 Key在 API Keys 页面重新创建更新.env重启服务404 model not foundBase URL 是否为https://taotoken.net/api、模型 ID 是否正确修正 Base URL从模型对话页复制模型 ID404 Not Found路径错误是否自己拼接了多余/v1/v1Base URL 保持https://taotoken.net/api429 Too Many Requests并发过高、批量任务占用、Key 限流降低并发增加退避重试拆分索引和问答 Key连接超时上下文过长、top_k 过大、网络抖动、客户端超时太短减少 top_k缩短 Prompt设置timeout60和重试答案不引用文档检索为空、Prompt 未要求引用、上下文被截断检查召回结果修改 system prompt限制上下文长度回答与文档无关召回不准、Rerank 阈值过低、模型温度过高调 chunk、score 阈值降低 temperatureClaude Code 不生效ANTHROPIC_*是否写对、是否被旧环境变量覆盖检查settings.json重启终端确认 Base URLCodex 不生效是否误写ANTHROPIC_*、model_provider是否指向taotoken使用config.toml设置TAOTOKEN_API_KEYCC Switch 切换后仍走旧配置三件套是否完整、是否切换到了正确客户端重新保存配置重启对应客户端这张表的核心逻辑是401和404优先看 Key 与 Base URL429和超时优先看并发与上下文答案质量优先看检索与 Prompt。不要把检索问题当成 API 问题也不要把 API 配置问题当成模型能力问题。8. 可复现验证三步跑通文档问答第一步部署知识库服务。按项目文档启动 API、前端、向量库和必要的解析服务。确认前端可以上传文档解析任务可以完成索引状态从“处理中”变成“已完成”。第二步配置 TaoToken Key 和 Base URL。在知识库服务的.env中写入LLM_API_KEYYOUR_API_KEY LLM_BASE_URLhttps://taotoken.net/api LLM_MODELYOUR_CHAT_MODEL_ID重启服务让环境变量生效。然后在你自己的本地终端执行一次最小调用确认 Key 可用。不要在前端暴露 Key也不要把.env提交到代码仓库。第三步上传一篇结构清晰的文档例如产品说明或接口文档等索引完成后提问一个文档中明确存在的问题。观察三条日志检索日志召回了哪些 chunkscore 是多少。Prompt 日志最终拼进模型的上下文有多少 Token。LLM 日志请求的 Base URL 主机、模型 ID、耗时、返回 token 用量。如果答案正确且带引用说明链路已经跑通。如果答案不对先回到检索日志不要急着换 Key。如果报错按上一节排障表逐项检查。此时你已经得到三个可复现产出问答链路图、Key 与 Base URL 边界说明、Token 消耗归属。9. 文末落地顺序模型对话 → Coding Plan → 创建 Key → Claude Code 文档如果你现在就要把知识库问答服务接起来建议按这个顺序走先到模型对话页验证模型效果确认回答风格和上下文能力符合知识库场景https://taotoken.net/models/detail/chat?utm_sourcetaotoken_aicg_blog_endutm_contentkb_qa_chat如果你还需要 Coding Plan 支撑开发、调试和批量评测可以查看https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentkb_qa_coding_plan为知识库项目创建独立 Key建议按kb-index、kb-qa、kb-eval拆分https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentkb_qa_api_keys如果你同时使用 Claude Code 写知识库后端配置细节看这里https://taotoken.net/doc/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentkb_qa_claude_code_doc最后再强调一次知识库问答链路里TaoToken 只管 Key 和 Base URL。Key 使用YOUR_API_KEYBase URL 使用https://taotoken.net/api。官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentkb_qa_final_cta把文档解析、切片、检索、Rerank 留给知识库服务把 LLM 调用入口统一到 TaoToken Key 和 Base URL排障会从“到处猜”变成“按链路查”。