THINGJS RAG 知识库 · 架构设计
整体架构
四项交付共用文档索引。在线文档助手和 MCP 知识服务进入同一条问句处理链路；评测平台回归这条链路，并用裁判模型判断生成题的当次回答；运维大屏读取请求留痕。
可左右滚动查看完整图；点击图可全屏缩放。
在线文档助手与 MCP 知识服务的问句处理如下。系统先判断是否在问文档；文档问题经过问句规划、双路检索与片段采用，再返回片段或生成回答。
可左右滚动查看完整图；点击图可全屏缩放。
部署架构
| 组成 | 使用方式 | 作用 |
|---|---|---|
| 在线文档助手 | 网页 POST /api/search、POST /api/chat | 开发者检索与问答；独立日 token 池，可点踩 |
| MCP 知识服务 | search_thingjs_docs、ask_thingjs_docs | 与网页共用检索；正式接入用 API Key 记录用量 |
| RAG 质量评测平台 | 黄金集脚本、报告、评测中心页、生成裁判模型 | 检索黄金集按规则计分；裁判判断生成题回答是否正确；未通过门禁时沿用上一版索引 |
| 运维监控大屏 | 独立只读站点 | 回放请求，查看实时运行状态、健康和日报 |
| 共用检索与索引 | TypeScript、LangChain、LanceDB、BM25、Qwen3-Embedding-4B、qwen3.8-flash | 问句规划、双路检索、融合采用和有证据时的生成 |
请求链路
下面是在线文档助手和 MCP 知识服务共用的一次请求。评测平台按同一链路回归。检索黄金集按规则计分类命中、成员命中和误空。生成黄金集在得到回答后，由裁判模型对照本次检索证据判断这次回答是否正确。运维大屏读取这些请求的留痕。
- 意图分流：用类名、别名、标识符和领域词判断文档信号。问候、天气等非文档话术直接返回固定话术；问句里的类样子标识都不在类目录、也没有别名命中时直接空结果。这两种情况都不调用嵌入或生成模型。混合句中有明确文档信号时继续检索。
- 问句规划：别名补充相关类和成员；近邻拼写错误按类目录纠正，并替换到检索问句里。已确认的类和成员作为精确目标。不使用大模型改写问句。
- 双路检索：纠正后的整句最多生成一次查询向量，同一进程内相同问句复用已计算的查询向量。LanceDB 取前 28 条；BM25 最多运行 6 条查询，每路取前 28 条，再按切片 ID 去重。
- 融合与采用：RRF 按两路名次融合。问句对上类目录中的文件时，先从这些文件取片段，再补其他类。同一类里，问句点名的成员优先，其余优先概述和构造函数；精确目标排在混合检索结果之前。单类问题采用 5 条；涉及两个及以上类时，每类最多 3 条，按类轮流采用。
- 输出：网页
POST /api/search与 MCPsearch_thingjs_docs返回片段。问答入口在生成前排除用户明确禁用的片段，再把留下的证据交给qwen3.8-flash；引用须对应该次证据。没有检索结果，或排除后没有可用证据时，不调用生成模型；排除后没有可用证据的回答标为低置信，并说明资料不足。生成模型连续失败后熔断，熔断期间不再调用它；已经检索到片段时，返回这些片段并说明模型暂不可用。
关键设计
文档如何切片并发布？
Markdown 文档先按 ### 标题切到成员级。单个成员超过 800 字时再分段，相邻段目标重叠 200 字；代码块尽量保持完整，图片附在对应片段末尾。切片记录类名、成员名、层级与来源，供检索、回填和引用使用。
可左右滚动查看完整图；点击图可全屏缩放。
文档或别名变化后建立新版本，校验通过才切换 active 指针；默认保留最近 5 版供回滚。服务监听文档目录时，保存 Markdown 后默认约 5 秒增量嵌入并热加载，不必停服务。嵌入模型变化时建立新的索引配置，避免不同向量维度混用。
为什么检索后还要按类采用？
RRF 只解决两路检索结果如何排序。一次问多个类时，若直接截取融合结果前 5 条，前几个类可能占满位置。采用阶段按问句中的类轮流取片段，让每个类有机会进入上下文。同一类内部先留问句点名的成员，再留概述和构造函数。
如何区分检索问题与生成问题？
在线请求先检查目标类或成员是否进入采用列表。未进入时排查切片、别名、规划和融合；进入后若回答遗漏、引用不符或编造内容，再排查生成提示和引用校验。检索和生成分别留痕，便于定位问题。
评测时两边分开。检索黄金集按规则计分类命中、成员命中和误空。生成黄金集先检查引用是否落在本次证据上，再由裁判模型判断这次回答是否正确。在线文档助手和 MCP 的单次提问使用采用列表和引用校验。
系统边界
- 身份与文档权限：正式 MCP 接入用 API Key 校验调用方，用量记在该 Key 上；网页不验这把 Key，问答消耗独立的日 token 池。这控制谁能调用，不等于按文档做访问隔离。当前是一套索引和语料来源标记，没有租户级文档 ACL。
- 回答依据：生成回答只使用本次交给模型的证据；用户明确禁用的片段会先排除。来源标记用于说明文档出处，不能代替权限隔离。
- 扩容现状：BM25 索引驻内存。按产品线拆索引、检索前定域和跨实例共享查询缓存属于后续规模化方案，不是当前已交付能力。