1. 为什么你的 RAG 一遇到多跳问题就断链先对齐一个概念RAG 是检索增强生成SAG 是 Structured Augmented Generation一种把文档重新组织成「事项 实体」轻结构的检索方案。它要解决的问题很具体——你问一个需要绕两步才能回答的问题普通向量检索就开始失灵。我拿一个真实场景举例。你有一个本地知识库里面存着几百份技术文档。用户问「写《XX》的作者出生在哪个国家」。普通向量 RAG 会怎么做它把这个问题做 embedding然后去向量库里找字面最相似的 chunk。结果第一跳的线索「作者是谁」和第二跳的答案「出生在哪个国家」大概率不在同一个 chunk 里。于是你调大 topK把更多 chunk 塞进上下文指望模型自己拼出来。塞得越多噪声越多token 越贵首 token 越慢模型反而更容易被无关内容带偏。这就是「硬塞 chunk」的典型症状。问题的根不在 embedding 模型不够好而在于 chunk 这个检索单元本身是「一跳」的——它靠相似度一次性捞回来跨文档、跨段落的关系它不认。多跳问题里证据天然散在好几个 chunk 里相似度最高的那个 chunk 不一定是答案所在。SAG 走的是另一条路。它不急着堆 chunk也不先搭一张完整知识图谱而是把文档重新组织成「事项 实体」的轻结构让检索能从命中的一条事项出发沿着实体关系多跳走下去。结构可以写成三行chunk - event # 每个切片抽出一个完整事项 chunk - entities # 每个切片抽出多个实体 event - entities # 事项和实体互相挂钩event事项负责保住完整语义它是一句保留了主语、动作、对象的完整陈述不是关键词。entities实体负责建索引和搭桥同一个实体会出现在不同的事项里顺着它就能从一条事项跳到另一条相关事项。event ↔ entities 这条双向关系就是多跳发生的地方。这篇要交付的东西很明确一套可复制的 config.toml / settings.json 骨架加上 TaoToken 统一 Key 的接入步骤最后给出证据链命中率的验证动作。你照着配完能直接跑通一次带 trace 的多跳检索。2. TaoToken 前置一个 Key 打通 Embedding、LLM、RerankSAG 的检索链路里至少要调三类模型Embedding 做向量化LLM 做事项和实体抽取Rerank 做精排。如果你分别去接三家 provider就要维护三套 base_url、三套 key、三套限流策略调试的时候光对账就够烦。TaoToken 在这里的价值是统一入口。它提供 OpenAI-compatible 接口Embedding、LLM、Rerank 都可以走同一个 base_url 和同一个 Key。对 SAG 这种要同时配三类模型的场景能省掉大量配置对齐的工作。你需要先拿到 Key。进控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建完在 API Keys 页面复制出来https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接口地址统一用https://taotoken.net/api注意这个地址后面不加 UTM 参数它是给程序调用的不是给浏览器点的。配置的时候 base_url 填https://taotoken.net/api/v1OpenAI SDK 会自动拼/chat/completions或/embeddings。提示Key 只显示一次复制后先存到密码管理器。后面 config.toml 和 settings.json 都要引用它建议用环境变量注入别硬编码进仓库。模型选择上SAG 的默认示例用的是 qwen3.6-flash 做 LLM、qwen3-rerank 做精排、text-embedding-3-large 做向量。你在 TaoToken 的模型列表里确认这几个模型可用再往下配。如果某个模型暂时不可用换同系列的等价模型即可SAG 不绑定具体模型名。3. 可复制配置config.toml 与 settings.json 骨架SAG 的配置分两层后端读.env或config.toml前端和 MCP 读settings.json。下面给的是能直接跑的骨架你只需要替换 Key 和项目 ID。先看后端config.toml# config.toml - SAG 后端配置骨架 [database] host localhost port 5432 name sag user sag password sag_local_dev [embedding] base_url https://taotoken.net/api/v1 api_key ${TAOTOKEN_API_KEY} model text-embedding-3-large dimensions 1024 batch_size 32 [llm] base_url https://taotoken.net/api/v1 api_key ${TAOTOKEN_API_KEY} model qwen3.6-flash temperature 0.1 max_tokens 2048 [rerank] base_url https://taotoken.net/api/v1 api_key ${TAOTOKEN_API_KEY} model qwen3-rerank top_k 5 [search] default_mode fast enable_trace true max_hops 3几个参数值得单独说。max_hops 3控制多跳的最大跳数设太大容易在实体图上绕远设太小又接不上证据链从 3 开始调比较稳。enable_trace true一定要开后面验证命中率全靠它。batch_size 32是 embedding 的批大小如果你的文档量大可以调到 64 或 128但要注意 provider 的并发限制。再看前端和 MCP 用的settings.json{ apiBase: http://localhost:4173, searchMode: fast, topK: 5, returnTrace: true, mcpServers: { sag: { command: npm, args: [run, mcp], env: { SAG_MCP_SOURCE_ID: 你的项目ID, TAOTOKEN_API_KEY: 你的Key } } } }SAG_MCP_SOURCE_ID绑定当前项目外部 Agent 调用时不用再传 projectId。returnTrace设为 true检索结果里会带上内部链路调证据链的时候这个比答案本身更有用。环境变量注入这样写export TAOTOKEN_API_KEYsk-你的Key export SAG_MCP_SOURCE_ID项目ID配完先别急着灌数据跑一次连通性检查curl -X POST https://taotoken.net/api/v1/embeddings \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:text-embedding-3-large,input:连通性测试}返回里有data[0].embedding数组就说明 Key 和 base_url 都对。这一步不过后面全是白搭。4. 验证请求从灌数据到带 trace 的多跳检索配置通了之后走一遍完整链路。先起 PostgreSQL 和服务docker compose up -d npm install npm run db:setup npm run devWebUI 在http://localhost:5173API 在http://localhost:4173。新建项目进「文档」页上传.md或.txt等处理队列跑完。处理过程会依次做切片、向量化、事项抽取、实体抽取、关系整理每一步的中间产物都能在日志里看到。灌完数据用 API 发一次检索请求curl -X POST http://localhost:4173/api/search \ -H Content-Type: application/json \ -d { query: SAG 为什么适合多跳检索, sourceIds: [你的项目ID], strategy: multi, searchMode: fast, topK: 5, returnTrace: true }返回结构里重点看三块。events是命中的事项列表每条都带完整语义。trace是检索链路记录了从 query 命中哪个实体入口、经过几次跳转、每次跳转命中了哪些事项。rerank_scores是精排后的分数用来判断哪条证据最相关。验证证据链是否接上看 trace 里的跳转路径。一个健康的多跳链路应该长这样query - entity: SAG hop1 - event: SAG 把文档组织成事项和实体 hop2 - entity: 事项 hop3 - event: 事项保留完整语义实体做跳板如果 trace 里只有 hop1 就停了说明实体桥没搭起来检查实体抽取是否正常。如果 hop 数超过 max_hops 还在绕说明实体粒度太细需要调整抽取 prompt 或合并同义实体。标准模式standard多两次 LLM 调用精度更高但更慢适合离线跑评测curl -X POST http://localhost:4173/api/search \ -H Content-Type: application/json \ -d { query: 写《XX》的作者出生在哪个国家, sourceIds: [你的项目ID], strategy: multi, searchMode: standard, topK: 5, returnTrace: true }对比 fast 和 standard 两次的 trace你能直观看到 LLM 抽 query 实体带来的召回差异。日常在线检索用 fast离线评测和难问题用 standard。5. 本篇常见错排查配 SAG 的过程中报错集中在几个地方。下面按出现频率排。第一个坑pgvector 扩展没装。报错长这样ERROR: type vector does not exist。原因是 PostgreSQL 镜像没带 pgvector。解决方法是换用官方带 pgvector 的镜像或者手动装docker exec -it sag-postgres psql -U sag -d sag -c CREATE EXTENSION IF NOT EXISTS vector;第二个坑embedding 维度对不上。报错expected 1024 dimensions, not 1536。这是 config.toml 里的dimensions和实际模型输出维度不一致。text-embedding-3-large 默认 3072 维但 SAG 示例里设了 1024你需要确认模型支持维度裁剪或者把dimensions改成模型实际输出维度。改完要重建向量索引旧数据得重新灌。第三个坑MCP 连不上报SAG_MCP_SOURCE_ID not found。检查 settings.json 里的项目 ID 是否和 WebUI 里显示的一致。项目 ID 在项目设置页能看到复制的时候别带空格。另外 MCP 进程要能读到TAOTOKEN_API_KEY环境变量如果你在 settings.json 里写了 Key确认 JSON 格式没写错。第四个坑检索返回空结果。先确认文档处理队列跑完了没跑完的话事项和实体都还没入库。再看sourceIds是否传对传错项目 ID 会查不到任何东西。最后检查searchModefast 模式依赖实体库的全文索引如果实体抽取失败入口就命中不了。第五个坑trace 里 hop 数异常。如果每次检索都只跳一跳检查实体抽取的 prompt 是否把实体抽成了长句。实体应该是轻量的、可精确匹配的节点太长就失去了桥接作用。如果 hop 数爆炸检查是否有循环引用同一个实体在多个事项间反复跳这时候要加去重逻辑或降低 max_hops。第六个坑TaoToken 返回 401。检查 Key 是否过期以及 base_url 是否写成了https://taotoken.net/api而不是https://taotoken.net/api/v1。OpenAI SDK 需要/v1后缀才能正确拼接路径。如果用的是 curl 直接调路径要写全。排障的时候有个通用技巧打开 WebUI 右侧的「原始日志」面板它把 LLM、Embedding、Rerank 的原始请求和响应都摊开了。比对着日志看比猜快得多。6. 接入文档与后续动作配置跑通之后下一步是把 SAG 接到你的 Agent 或应用里。MCP 是最省事的方式每个项目自带一份配置复制到 Agent 的 mcpServers 里就能用。暴露的四个工具覆盖了灌数据、检索、看链路、查详情sag_ingest_document # 导入文档并完成切片、抽事项、抽实体、向量化 sag_search # 对当前项目做 SAG 多路检索返回内部 trace sag_explain_search # 返回检索链路说明和 trace方便调试 sag_get_event # 按事件 ID 查事件详情不想走 MCP 就用 HTTP API创建项目、写入文档、检索、流式拿检索过程都有现成 endpoint。接入细节看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你要长期跑编码类 Agent反复检索文档是高频动作可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite想先验证模型对话效果不搭本地环境直接进模型对话页试https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite最后给三个判断试 SAG 的时候直接照着看。你的问题是否真的需要多跳证据如果一跳就能答普通向量检索够用。前两条召回结果是否已经命中关键证据Recall2 高意味着 Agent 不用把上下文撑大去赌。trace 里每一次实体跳转是否能被人读懂读不懂说明实体粒度或抽取逻辑有问题。三条都过再谈替换现有 RAG三条不过先调语料切分、模型配置和问题集。别把 README 里的 benchmark 直接当成自己语料上的结论。那组数字是在英文多跳问答数据集、特定 embedding 和 LLM 配置下跑出来的。中文语料、你自己的文档结构、换一套模型结果都会变。正确姿势是拿 SAG 跑通流程后用你真实的文档和真实的问题自己测一遍 Recall 和延迟再决定要不要用它替换现有检索。