1. 检索增强LLM到底解决什么问题从幻觉到私有知识库检索增强LLMRetrieval Augmented LLM更常见的叫法是检索增强生成RAG说白了就是给大模型配一个外挂知识库。你问它问题它先去你的资料库里翻一翻找到相关段落再结合这些段落生成回答。适合谁适合手头有私有文档、产品手册、内部Wiki又想让大模型基于这些内容准确回答的开发者。我最早接触RAG是因为一个很具体的痛点让模型回答公司内部API文档的问题它张口就来编得头头是道但接口名和参数全是假的。这就是典型的幻觉Hallucination。大模型的参数里记的是训练数据中的通用知识你的私有文档它压根没见过没见过就只能靠猜猜出来的东西自然不可信。RAG的核心价值就在这儿不改模型参数不重新训练把外部知识在推理时喂进上下文窗口。它解决四类问题。第一是长尾知识训练数据覆盖不到的冷门内容检索能补上。第二是私有数据企业内部文档不可能拿去预训练检索让模型临时查阅。第三是数据新鲜度模型知识有截止日期检索能拿到最新内容。第四是来源可追溯生成结果能附上参考链接可解释性大大增强。一个常见的误解是现在上下文窗口都到128K甚至更长了直接把整本手册塞进去不就行了实测下来不行。一是窗口再长也有上限二是研究表明上下文里塞太多不相关的文档模型准确率反而下降这就是Lost in the Middle现象——关键信息被淹没在中间。三是token越多推理成本越高。所以检索这一步不是可有可无而是必须的过滤和聚焦。RAG的完整链路可以拆成三个模块数据与索引、查询与检索、回复生成。数据侧要把各种格式的文档读进来、切块、向量化、建索引检索侧要把用户问题也向量化去索引里找最相似的块生成侧把检索到的块拼进Prompt让模型基于这些内容回答。下面我就按这条链路一步步搭一个能跑的原型并且用TaoToken的统一API来调用模型。2. TaoToken统一API接入前置一个Key打通检索增强LLM的生成环节搭RAG原型时生成环节要调大模型。如果你同时试几个模型对比效果每个厂商一套SDK、一个Key、一套鉴权切换起来很烦。TaoToken的思路是提供一个统一的OpenAI兼容接口一个Key、一个Base URL改个model名就能换模型。对RAG这种需要反复调参、对比不同模型生成质量的场景省事不少。先说清楚它是什么TaoToken是一个大模型API聚合网关对外暴露OpenAI兼容的HTTP接口。你拿到的API Key可以调用它支持的多个模型。它的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API端点统一在 https://taotoken.net/api 这个地址不加UTM参数。接入前你需要准备三样东西我把它叫做三件套缺一不可Base URLhttps://taotoken.net/api所有请求都发到这里。API Key在控制台创建形如sk-xxxx放在请求头的Authorization: Bearer里。Model ID你要调用的模型标识比如对话用gpt-4o-mini这类具体以控制台模型列表为准。获取Key的路径打开 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 登录后在API Keys页面点创建复制生成的Key。注意Key只在创建时完整显示一次先存到环境变量里别硬编码进代码。为什么RAG场景特别适合用统一网关因为检索增强的效果很大程度取决于生成模型的理解和归纳能力。你可能想先用便宜的小模型跑通链路再用强模型验证上限或者中文文档用某个模型、代码文档用另一个。统一接口下你只需要改配置里的model字段检索代码一行不用动。这就是把生成这一层解耦出来的好处。需要提醒的是TaoToken是API接入层不是编辑器也不是向量数据库。它负责的是RAG链路最后那一步——把检索到的上下文和问题一起发给模型拿回生成结果。向量化、检索、索引这些还是在你自己的代码或向量库里完成。下面进入实操。3. 可复制配置RAG检索链路与TaoToken接入的完整代码这一节给你能直接复制运行的配置和代码。整体分两部分检索侧用本地向量检索先用numpy简单可控生成侧走TaoToken。先建一个配置文件把三件套和检索参数集中管理。先建config.json{ taotoken: { base_url: https://taotoken.net/api, api_key: sk-你的Key填这里, model_id: gpt-4o-mini, temperature: 0.2, max_tokens: 1024 }, retrieval: { chunk_size: 300, chunk_overlap: 50, top_k: 3, embedding_model: text-embedding-3-small } }注意temperature设成0.2RAG场景要的是忠实于检索内容不是发挥创意温度低一点更稳。top_k先设3后面验证阶段再调。然后是检索和生成的主程序rag_demo.py。为了不依赖外部向量库我用numpy做余弦相似度检索文档量在几万块以内完全够用import json import numpy as np from openai import OpenAI # 读取配置 with open(config.json, r, encodingutf-8) as f: cfg json.load(f) # 统一客户端Base URL 指向 TaoToken client OpenAI( base_urlcfg[taotoken][base_url], api_keycfg[taotoken][api_key], ) def get_embedding(texts): 调用嵌入模型把文本转成向量 resp client.embeddings.create( modelcfg[retrieval][embedding_model], inputtexts, ) return [d.embedding for d in resp.data] def chunk_text(text, size, overlap): 按字符切块带重叠保持语义连贯 chunks [] start 0 while start len(text): end start size chunks.append(text[start:end]) start end - overlap return chunks # 模拟一份知识库文档 doc TaoToken 提供统一的 OpenAI 兼容接口。 所有请求发送到 https://taotoken.net/api。 鉴权使用 Bearer Token放在 Authorization 请求头。 创建 API Key 后请立即保存页面刷新后不再完整显示。 调用对话模型时model 字段填写控制台给出的模型标识。 chunks chunk_text(doc, cfg[retrieval][chunk_size], cfg[retrieval][chunk_overlap]) chunk_vecs np.array(get_embedding(chunks)) def retrieve(query, top_k): 检索把问题向量化算余弦相似度取 top_k q_vec np.array(get_embedding([query])[0]) # 余弦相似度 sims chunk_vecs q_vec / ( np.linalg.norm(chunk_vecs, axis1) * np.linalg.norm(q_vec) 1e-8 ) idx np.argsort(sims)[::-1][:top_k] return [(chunks[i], float(sims[i])) for i in idx] def generate(query): 生成检索 拼 Prompt 调 TaoToken hits retrieve(query, cfg[retrieval][top_k]) context \n---\n.join([h[0] for h in hits]) prompt f请仅根据下面的上下文回答问题。如果上下文没有相关信息直接说资料中没有。 上下文 {context} 问题{query} resp client.chat.completions.create( modelcfg[taotoken][model_id], messages[{role: user, content: prompt}], temperaturecfg[taotoken][temperature], max_tokenscfg[taotoken][max_tokens], ) return resp.choices[0].message.content, hits if __name__ __main__: answer, hits generate(TaoToken 的 API Key 创建后还能再看到吗) print(检索命中) for c, s in hits: print(f 相似度 {s:.3f} | {c[:40]}...) print(\n生成回答) print(answer)这段代码的关键点OpenAI客户端的base_url指向https://taotoken.net/api这样所有请求都走统一网关。嵌入和对话用的是同一个客户端、同一个Key只是model不同。检索用余弦相似度1e-8是防止除零。如果你用Cline或Claude Code这类工具做开发配置方式类似核心还是三件套。以Cline的MCP配置为例在cline_mcp_settings.json里{ mcpServers: { taotoken-rag: { command: python, args: [rag_demo.py], env: { OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: sk-你的Key, MODEL_ID: gpt-4o-mini } } } }这里Base URL、Key、Model ID三件套齐全缺任何一个都会连不上。装好依赖pip install openai numpy就能跑。4. 验证请求与成功结果检索命中率和响应延迟怎么测代码跑通只是第一步RAG原型能不能用得看两个硬指标检索命中率和响应延迟。这一节给你可执行的验证动作。先跑上面的脚本正常输出应该长这样检索命中 相似度 0.812 | TaoToken 提供统一的 OpenAI 兼容接口。... 相似度 0.756 | 创建 API Key 后请立即保存页面刷新后不再完整显示。... 相似度 0.701 | 鉴权使用 Bearer Token放在 Authorization 请求头。... 生成回答 资料中提到API Key 创建后请立即保存页面刷新后不再完整显示。看到相似度分数和基于检索内容的回答说明链路通了。如果回答是资料中没有但文档里明明有那就是检索没命中往下看排障。检索命中率验证准备一组测试问题每个问题标注它应该命中的文档块。写个小脚本算命中率test_cases [ (API Key 创建后还能看到吗, 创建 API Key 后请立即保存), (请求发到哪个地址, https://taotoken.net/api), (怎么鉴权, Bearer Token), ] hit 0 for q, expected in test_cases: hits retrieve(q, cfg[retrieval][top_k]) top_texts [h[0] for h in hits] if any(expected in t for t in top_texts): hit 1 else: print(f未命中: {q}) print(f命中率: {hit}/{len(test_cases)} {hit/len(test_cases):.0%})命中率低于80%就要调参chunk_size太大导致块内噪声多太小导致语义被切断top_k太小可能漏掉正确块。我一般从chunk_size300, overlap50, top_k3起步按命中率微调。响应延迟验证RAG的延迟由检索和生成两部分组成。加个计时import time t0 time.time() q_vec get_embedding([测试问题]) t1 time.time() # ... 检索 ... t2 time.time() # ... 生成 ... t3 time.time() print(f嵌入耗时: {t1-t0:.2f}s) print(f检索耗时: {t2-t1:.3f}s) print(f生成耗时: {t3-t2:.2f}s)实测下来本地numpy检索几万块通常在毫秒级延迟大头在生成。如果生成超过5秒可以换更快的模型或者把max_tokens调小。检索侧如果块数上了百万numpy就不够了得换Faiss或向量数据库。验证时还要看一个指标上下文相关性。把检索到的块打印出来人工扫一眼如果top_k里混进了明显不相关的块说明嵌入模型对你的领域不敏感可以考虑换嵌入模型或者加一层关键词过滤。5. 本篇常见错排查401、local proxy failed、reading choices 逐个解决搭RAG原型时踩的坑八成集中在接入和检索两块。这一节按真实报错来排查。报错一401 Unauthorized。这是最常见的。原因通常是Key没填对、Key过期、或者请求头格式错。检查三点api_key是不是完整的sk-开头字符串有没有多余空格base_url是不是https://taotoken.net/api注意结尾不要多加/v1或斜杠路径拼错也会导致鉴权失败。如果用的是环境变量确认echo $OPENAI_API_KEY能打印出来。报错二local proxy failed / connection error。这类是网络层问题。先确认base_url拼写无误再确认本机网络能正常访问外网。如果你在代码里设了http_proxy之类的环境变量先清掉再试。有些公司内网需要走特定出口这种情况找运维确认。注意不要用任何非正规的网络工具正常的企业网络配置即可。报错三reading choices / KeyError: choices。这个报错说明请求发出去了但返回结构里没有choices字段。常见原因是模型名写错了网关返回了错误信息而不是正常响应或者max_tokens设得过大超过了模型上限。打印完整响应体看看resp client.chat.completions.create(...) print(resp) # 先看原始返回如果返回里带error字段按里面的 message 提示改。模型ID一定要和控制台列表里的一致大小写敏感。报错四OAuth / 鉴权方式混淆。有些工具默认走OAuth流程但TaoToken用的是Bearer Token。如果你在Claude Code或Codex这类工具里配置注意选API Key模式而不是OAuth登录模式。Codex的auth.json里要填的是API Key字段不是OAuth token。配置时三件套Base URL、Key、Model ID必须同时正确只填Key不填Base URL请求会发到默认地址自然失败。报错五检索结果为空或全是无关内容。这不是接入问题是检索问题。检查文档有没有成功切块打印len(chunks)嵌入有没有返回打印向量维度相似度计算有没有因为向量全零导致结果异常。如果文档是中文确认嵌入模型支持中文有些英文模型对中文效果很差。排查顺序建议先确认能单独调通一次对话不带检索再加检索最后加生成。分层定位比一上来跑全链路快得多。6. 从原型到可用检索增强LLM的下一步原型跑通后往生产走还有几件事要做。第一是换掉numpy检索文档量上去后用Faiss或向量数据库支持增量更新和持久化。第二是加查询改写用户的问题往往口语化先用模型改写成更适合检索的形式命中率能提一截。第三是加元数据过滤比如按文档时间、来源筛选避免检索到过期内容。生成侧的Prompt也值得打磨。我习惯在Prompt里明确要求仅根据上下文回答无相关信息就说不知道并且要求模型标注引用来源。这样既减少幻觉又方便追溯。温度保持低值RAG要的是准确不是创意。模型选择上统一API的好处这时候就体现出来了你可以用同一套检索代码快速对比不同模型的生成质量挑一个性价比最合适的。需要长期跑编码或Agent类任务的可以看看Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 想先在线验证模型效果的用模型对话 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Key管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。最后说个实用技巧把检索到的块和相似度分数一起记日志。上线后用户反馈答得不对时翻日志就能判断是检索没找到还是找到了但模型没用好。这个习惯能帮你省下大量排查时间。