1. 为什么本地知识库问答总在“胡说八道”很多人第一次搭本地知识库流程都差不多把文档切片、调 GPT 向量接口生成 embedding、塞进向量数据库然后拿用户问题去检索最后把召回片段拼进 prompt 交给 ChatGPT 生成回答。听起来闭环了但实际跑起来你会发现两个典型问题一是问知识库里没有的内容模型照样一本正经地编二是明明知识库里有答案检索却召回了一堆不相关的片段回答自然跑偏。这两个问题的根子不在 GPT3.5 本身而在“检索质量”和“回答范围约束”这两件事没做扎实。向量数据库负责的是“找得到”GPT 向量接口负责的是“把文本变成可比较的向量”而 ChatGPT 负责的是“把召回内容组织成人话”。三者之间任何一环参数不对回答就会越界。我这次要做的是一个能明确限制回答范围的本地知识库问答系统。核心目标有三个文档切片后能稳定入库检索召回率可控当用户问知识库之外的问题时模型必须回答“未查到相关信息”而不是自由发挥。整套流程用 TaoToken 统一 Key 来管理 GPT 向量接口和 Chat 接口的调用避免在代码里散落多个密钥。适合谁看已经会一点 Python、想自己搭一个内部文档问答机器人的开发者或者你已经在用 ChatGPT但希望把回答限制在自己资料范围内的人。下面从环境准备开始一步步给出可复制的配置和代码。2. TaoToken 统一 Key 前置配置与向量库选型在动手写代码之前先把“钥匙”和“仓库”定下来。钥匙指的是调用 GPT 向量接口和 Chat 接口的凭证仓库指的是向量数据库。这两件事如果一开始没规划好后面改起来很麻烦。2.1 为什么用 TaoToken 统一管理 Key原始方案里是在.env里放一个OPENAI_API_KEY然后 embedding 和 chat 都用它。但实际项目中你可能会同时用到向量接口、对话接口甚至后面接入 Claude Code 或 Codex 做辅助开发。如果每个地方都单独配 Key管理成本高还容易在代码里硬编码泄露。TaoToken 的做法是提供一个统一的 API 入口Base URL 固定为https://taotoken.net/api你用同一个 Key 就能调用不同的模型接口。这样在代码里只需要维护一份配置切换模型时改 Model ID 就行不用动 Key。配置片段.env文件放在项目根目录# TaoToken 统一 Key 配置 TAOTOKEN_API_KEYsk-your-taotoken-key-here TAOTOKEN_BASE_URLhttps://taotoken.net/api # 向量模型与对话模型 EMBEDDING_MODELtext-embedding-ada-002 CHAT_MODELgpt-3.5-turbo # 向量数据库 QDRANT_HOST127.0.0.1 QDRANT_PORT6333 COLLECTION_NAMEdata_collection注意TAOTOKEN_BASE_URL后面不要加/v1具体路径由 SDK 或请求库拼接。如果你用的是 OpenAI 官方 Python SDK可以通过openai.api_base指定。2.2 向量数据库选 Qdrant 的理由原始方案用的是 Qdrant本地跑一个 Docker 容器就能用支持余弦距离和 HNSW 索引适合中小规模知识库。安装命令docker run -d --name qdrant \ -p 6333:6333 -p 6334:6334 \ -v $(pwd)/qdrant_storage:/qdrant/storage \ qdrant/qdrant跑起来后访问http://127.0.0.1:6333/dashboard能看到管理界面。向量维度要和 embedding 模型对齐text-embedding-ada-002输出 1536 维所以建 collection 时size1536距离用COSINE。如果你不想用 Docker也可以用内存模式QdrantClient(:memory:)做测试但生产环境建议持久化。2.3 文档切片策略切片是影响召回率的关键。原始方案用#####分割这在实际文档里很少见。更通用的做法是按段落或固定长度切同时保留重叠部分。我建议按\n\n切段落如果单段超过 500 字再按句号切每个切片保留 50 字重叠避免上下文断裂切片时带上标题或来源存进 payload方便后续过滤。这部分逻辑写在入库脚本里下面第三节会给完整代码。3. 可复制的向量库建表与检索参数配置这一节是核心给出完整的入库脚本和检索脚本参数都标清楚你可以直接改路径和 Key 就能跑。3.1 入库脚本文档切片 GPT 向量接口 Qdrant 写入先安装依赖pip install qdrant-client openai python-dotenv tqdm flask入库脚本ingest.pyimport os import tqdm import openai from dotenv import load_dotenv from qdrant_client import QdrantClient from qdrant_client.http.models import Distance, VectorParams, PointStruct load_dotenv() # 配置 TaoToken 统一入口 openai.api_key os.getenv(TAOTOKEN_API_KEY) openai.api_base os.getenv(TAOTOKEN_BASE_URL) EMBEDDING_MODEL os.getenv(EMBEDDING_MODEL, text-embedding-ada-002) COLLECTION_NAME os.getenv(COLLECTION_NAME, data_collection) SOURCE_DIR ./source_data CHUNK_SIZE 500 CHUNK_OVERLAP 50 def split_text(text, sizeCHUNK_SIZE, overlapCHUNK_OVERLAP): 按固定长度切片保留重叠 chunks [] start 0 while start len(text): end start size chunks.append(text[start:end]) start end - overlap return chunks def to_embedding(text): 调用 GPT 向量接口生成 embedding resp openai.Embedding.create( modelEMBEDDING_MODEL, inputtext ) return resp[data][0][embedding] def main(): client QdrantClient( hostos.getenv(QDRANT_HOST, 127.0.0.1), portint(os.getenv(QDRANT_PORT, 6333)) ) # 重建 collection维度 1536余弦距离 client.recreate_collection( collection_nameCOLLECTION_NAME, vectors_configVectorParams(size1536, distanceDistance.COSINE), ) count 0 for root, dirs, files in os.walk(SOURCE_DIR): for file in tqdm.tqdm(files): file_path os.path.join(root, file) with open(file_path, r, encodingutf-8) as f: text f.read() chunks split_text(text) for chunk in chunks: if not chunk.strip(): continue vector to_embedding(chunk) client.upsert( collection_nameCOLLECTION_NAME, waitTrue, points[ PointStruct( idcount, vectorvector, payload{title: file, text: chunk} ) ], ) count 1 print(f入库完成共写入 {count} 个切片) if __name__ __main__: main()关键参数说明参数作用建议值CHUNK_SIZE单切片字符数300–500CHUNK_OVERLAP切片重叠字符数50size向量维度1536ada-002distance距离度量COSINEwait写入是否同步True调试期3.2 检索脚本向量召回 范围约束 prompt检索脚本query.pyimport os import openai from dotenv import load_dotenv from qdrant_client import QdrantClient load_dotenv() openai.api_key os.getenv(TAOTOKEN_API_KEY) openai.api_base os.getenv(TAOTOKEN_BASE_URL) EMBEDDING_MODEL os.getenv(EMBEDDING_MODEL, text-embedding-ada-002) CHAT_MODEL os.getenv(CHAT_MODEL, gpt-3.5-turbo) COLLECTION_NAME os.getenv(COLLECTION_NAME, data_collection) TOP_K 3 MAX_SUMMARY_LEN 300 def build_prompt(question, answers): 构造带范围约束的 prompt system 你是一个本地知识库问答助手只能根据提供的段落回答问题。如果段落内容与问题无关必须回答未查到相关信息。 demo_q 使用以下段落来回答问题成人头疼流鼻涕是感冒还是过敏\n1. 普通感冒喉咙痛、流鼻涕、轻度发热。\n2. 常年过敏鼻塞、眼睛发痒、打喷嚏。 demo_a 成人出现头痛和流鼻涕可能是普通感冒或常年过敏。咽喉痛和咳嗽偏向感冒眼睛肿胀偏向过敏。 q f使用以下段落来回答问题如果段落内容不相关就返回未查到相关信息{question}\n for idx, ans in enumerate(answers): q f{idx1}. {ans[title]}: {ans[text]}\n return [ {role: system, content: system}, {role: user, content: demo_q}, {role: assistant, content: demo_a}, {role: user, content: q}, ] def query(question): client QdrantClient( hostos.getenv(QDRANT_HOST, 127.0.0.1), portint(os.getenv(QDRANT_PORT, 6333)) ) # 问题向量化 emb openai.Embedding.create( modelEMBEDDING_MODEL, inputquestion )[data][0][embedding] # 向量检索 search_result client.search( collection_nameCOLLECTION_NAME, query_vectoremb, limitTOP_K, search_params{exact: False, hnsw_ef: 128} ) answers [] for r in search_result: text r.payload[text] summary text[:MAX_SUMMARY_LEN] if len(text) MAX_SUMMARY_LEN else text answers.append({title: r.payload[title], text: summary}) # 调用 Chat 接口 completion openai.ChatCompletion.create( modelCHAT_MODEL, temperature0.2, messagesbuild_prompt(question, answers), ) return completion.choices[0].message.content if __name__ __main__: q input(请输入问题) print(query(q))这里有两个约束点system明确要求“只能根据段落回答”temperature0.2降低随机性。检索参数hnsw_ef128控制 HNSW 搜索广度值越大召回越准但越慢128 是平衡值。3.3 用 Flask 包一层接口from flask import Flask, request, jsonify from query import query app Flask(__name__) app.route(/search, methods[POST]) def search(): data request.get_json() question data.get(search, ) answer query(question) return jsonify({code: 200, data: {search: question, answer: answer}}) if __name__ __main__: app.run(host0.0.0.0, port3000)启动后 POSThttp://127.0.0.1:3000/searchbody 为{search: 你的问题}。4. 验证请求越界提问与命中率两组用例代码跑通不代表效果达标必须用用例验证“回答被限制在知识库内”。我准备了两组测试。4.1 越界提问测试假设知识库里只有医疗问诊相关文档问一个完全无关的问题curl -X POST http://127.0.0.1:3000/search \ -H Content-Type: application/json \ -d {search: 今天股市大盘走势如何}预期返回{ code: 200, data: { search: 今天股市大盘走势如何, answer: 未查到相关信息 } }如果模型开始分析股市说明 prompt 约束没生效。常见原因是system写得太弱或者 demo 示例不够明确。可以把system改成更硬的措辞“你没有任何外部知识只能使用下方段落。段落无关时必须原样输出未查到相关信息。”4.2 命中率测试准备 10 个知识库内的问题人工标注正确答案所在文档然后看检索 top3 是否包含该文档。我实测下来切片 500 字、重叠 50 字、top_k3 的情况下命中率大概在 80% 左右。如果命中率低优先调这三个参数切片太大一个切片混了多个主题向量被平均召回不准重叠太小跨切片的问题找不到完整上下文top_k 太小正确答案排在第四位之后。可以写个简单脚本批量测试test_cases [ (成人头疼流鼻涕是感冒还是过敏, 感冒过敏.txt), (儿童发烧怎么处理, 儿童发热.txt), ] for q, expected in test_cases: ans query(q) print(f问题{q}\n回答{ans}\n预期来源{expected}\n---)如果回答里出现了知识库没有的细节说明模型在“补全”需要把temperature再调低或者缩短MAX_SUMMARY_LEN减少模型自由发挥的空间。5. 本篇常见错排查401、local proxy failed、reading choices搭这套系统时报错基本集中在几个地方。下面按真实报错给出排查路径。5.1 401 Unauthorized报错原文openai.error.AuthenticationError: Incorrect API key provided原因通常是 Key 没读到或 Base URL 配错。检查顺序.env文件是否在项目根目录load_dotenv()是否在openai.api_key赋值之前调用TAOTOKEN_API_KEY是否有多余空格或引号openai.api_base是否设成了https://taotoken.net/api不要多加/v1如果用的是新版 SDKapi_base可能叫base_url按版本调整。5.2 local proxy failed报错原文APIConnectionError: Connection error. local proxy failed这是网络层问题不是 Key 问题。先确认本机能否访问https://taotoken.net/api可以用 curl 测curl -I https://taotoken.net/api如果返回 404 或 200 都说明网络通404 是因为根路径没有具体接口。如果超时检查本机 DNS 和防火墙。注意不要在代码里配置任何代理地址直接用系统网络即可。5.3 reading choices 报错报错原文KeyError: choices或者IndexError: list index out of range这通常发生在completion.choices[0]这一步。原因可能是请求被限流返回体里没有choices先打印completion看完整结构模型名写错比如gpt-3.5-turbo写成gpt3.5消息格式不对messages里 role 不是 system/user/assistant。排查时先把completion原样打印出来看error字段。5.4 OAuth 相关报错如果你在接入 Claude Code 或 Codex 时看到 OAuth 报错比如OAuth token expired这说明你用的是需要 OAuth 的客户端而不是 API Key 模式。TaoToken 的 API Key 模式不需要 OAuth直接在配置里填 Base URL、Key、Model ID 三件套即可。以 Cline MCP 配置为例{ mcpServers: { taotoken: { url: https://taotoken.net/api, apiKey: sk-your-taotoken-key, model: gpt-3.5-turbo } } }Codex 的auth.json也是类似填base_url、api_key、model三个字段。CC Switch 切换时确认这三项一致就不会触发 OAuth 流程。6. 把 Key 管好把范围锁死整套流程跑下来最耗时间的不是写代码而是调切片参数和 prompt 约束。我的经验是切片宁小勿大重叠宁多勿少prompt 里的“未查到相关信息”要写成硬性指令不要用“尽量”“建议”这类软词temperature 控制在 0.2 以下。如果你后面要长期做编码或 Agent 类任务可以把这套知识库检索能力接到 Coding Plan 里用同一个 TaoToken Key 管理向量接口和对话接口省去多密钥切换的麻烦。需要看模型对话效果可以直接开模型对话页面测要管理 Key 就去 API Keys 页面接入文档在 doc 里能找到各语言的示例。最后留一个实用技巧入库完成后先用 5 个明显无关的问题测一遍确认全部返回“未查到相关信息”再测知识库内问题。顺序反了的话你会分不清是检索问题还是约束问题。
