THINGJS RAG 知识库 · 核心交付
交付概览
对外是四项交付：在线文档助手、MCP 知识服务、RAG 质量评测平台、运维监控大屏。文档索引、问句规划、双路检索、融合排序、生成模型和请求库是四项交付共用的基础设施。
- 索引、问句规划与双路检索：供在线文档助手和 MCP 知识服务使用，评测平台用这条链路做回归。
- 网页检索问答、日 token 池和点踩：属于在线文档助手。
- MCP 工具、API Key 和调用追踪：属于 MCP 知识服务。
- 检索规则计分、生成规则检查、生成裁判和发版门禁：属于 RAG 质量评测平台。
- 请求回放、实时运行状态、当前健康和日报：属于运维监控大屏。
共用检索与索引
- 简介：把 ThingJS API 文档变成可检索片段，并完成问句规划、双路召回和片段采用。两个问答产品走同一条链路。
- 技术栈：TypeScript、LangChain、LanceDB、BM25、RRF、
Qwen3-Embedding-4B、qwen3.8-flash。 - 功能描述：按
###切到成员；超出 800 字的同一成员再切分，相邻段目标重叠 200 字，代码块尽量保持完整。同一批片段建立向量与关键词索引，新版本校验后切换 active 指针，默认保留最近 5 版。文档问题做别名扩写和近邻类名纠错；纠正后的整句做一次向量检索，同一进程内相同问句复用已计算的查询向量，BM25 最多 6 路。单类采用 5 条，多类每类最多 3 条并轮流采用。生成前排除用户明确禁用的片段；没有可用证据时不调用生成模型。生成模型连续失败后熔断，熔断期间不再调用它；已经检索到片段时，返回这些片段并说明模型暂不可用。
在线文档助手
- 简介：给 ThingJS 开发者在浏览器里核对 API 用法和出处。
- 技术栈：TypeScript、网页、
POST /api/search、POST /api/chat。 - 功能描述：
/api/search返回文档片段，/api/chat基于可用证据生成回答并检查引用。非文档话术返回固定回复，目录外类名直接空结果。排除后没有可用证据时，以低置信说明资料不足，不调用生成模型。网页不验编辑器 API Key，问答消耗独立日 token 池。使用者可以对回答点踩。入口鉴权不等于文档级权限隔离。
MCP 知识服务
- 简介：给 IDE 和编码 Agent 调用当前托管索引，不必在每台编辑器上复制文档库。
- 技术栈：TypeScript、MCP、
search_thingjs_docs、ask_thingjs_docs、API Key。 - 功能描述：两个工具与网页共用检索和生成。正式接入时用 API Key 校验调用方，检索和问答的用量记在该 Key 上，并留下可追踪的请求。本机可以不带 Token 调试。它控制谁能调用，不按客户拆文档。
RAG 质量评测平台
- 简介：给研发、测试和算法人员检查检索与生成有没有退步。
- 技术栈：TypeScript、检索与生成黄金集、HTML 报告、评测中心页、
qwen3.8-flash裁判。 - 功能描述：检索和生成各有黄金集，报告保留逐题证据和错题归因。检索按规则计分；生成先做规则检查，再由裁判模型打分。裁判默认使用
qwen3.8-flash，温度为 0。下面两节是默认发版门槛，用来决定能否切换索引，不是已经测得的线上命中率或幻觉率。未通过时沿用上一版索引。评测中心页挂在运维站点中，能力仍属于本交付。
检索发版指标
检索看期望类和成员有没有进入可以采用的位置。类没命中，后面的生成上下文里没有这个类。成员只看前 3 条，与每类最多采用 3 条对齐。误空把「文档里有答案却返回空」和「本来就该空」分开。口语、点名成员、拼写错误再各算一层，避免某一类问法退步被总命中率盖住。
| 指标 | 口径 | 默认发版门槛 |
|---|---|---|
| 类命中 | 可答题中，期望类进入计分窗口的比例。单类看前 5 条；多个期望类时，窗口取 5 和「类数 × 3」里较大的值 | ≥ 90% |
| 成员命中 | 要求成员的题中，期望类和成员同时出现在前 3 条的比例 | ≥ 75% |
| 误空 | 可答题中，返回空结果且类未进窗口的比例 | ≤ 2% |
| 口语类命中 | 口语问法这一层的类命中。该层少于 5 题时不检查 | ≥ 70% |
| 成员层成员命中 | 点名成员这一层的成员命中。该层少于 5 题时不检查 | ≥ 70% |
| 拼写类命中 | 拼写错误这一层的类命中。该层少于 3 题时不检查 | ≥ 50% |
报告还会给出前 1 条和前 3 条的类命中、成员第 1 条命中、成员 MRR，以及按结构化类名计算的严格命中。发版比例用上表。
生成发版指标
生成侧的规则检查回答能不能解析、置信是否符合该答还是该空、引用是否落在本次证据里、类名和成员有没有出现、示例路径有没有带出、不该答的题有没有拒答、期望类有没有只出现在被丢弃的片段里。裁判阅读问题、回答、引用和本次证据，按 1 到 5 分判断依据是否在证据里、是否答到问题、引用内容是否对得上证据。5 分是完全符合，3 分是部分符合，1 分是明显不符合。三项都至少 4 分且没有幻觉，这题裁判通过。API 用法至少 4 分、答到问题至少 4 分、没有幻觉、也没有不符合参考事实的内容，这题回答算正确。发版看的是裁判通过率和幻觉条数。
| 指标 | 口径 | 默认发版门槛 |
|---|---|---|
| 回答结构 | 返回结果能按回答格式解析 | 100% |
| 置信符合预期 | 该答的题为可用置信，该空的题为空置信 | 100% |
| 引用合法 | 该答且置信符合预期的题里，引用落在本次证据内，并且至少有一条引用 | 100% |
| 类名覆盖 | 该答且置信符合预期的题里出现期望类 | ≥ 95% |
| 成员覆盖 | 要求成员的可答题里出现期望成员 | ≥ 85% |
| 路径脱敏 | 回答不带示例场景路径和文件路径 | 100% |
| 负例拒答 | 不该答的题返回空结果，并且没有调用生成模型 | 100% |
| 期望类被滤掉 | 可答题里期望类只出现在被丢弃片段的比例 | 0 |
| 裁判通过 | 已打分的题里，依据、答问、引用对齐都至少 4 分，且没有幻觉 | ≥ 80% |
| 幻觉 | 裁判标出含证据外事实、API 或参数的题数 | 0 |
报告还会记录内部文档路径、意外降级、低置信仍调用生成模型，以及引用是否支撑事实。单题错题原因还包括必须提到的词、禁止说法和代码块。
运维监控大屏
- 简介：给运维和值班查看在线文档助手、MCP 知识服务和评测流量。
- 技术栈：TypeScript、SQLite、只读页面。
- 功能描述：独立只读站点提供质量总览、单次请求回放、实时运行状态和日报。实时页查看 MCP 当前连接、正在执行的请求、搜索与嵌入队列、生成模型熔断，以及近几分钟的失败和慢请求。请求按在线文档助手、MCP 知识服务和评测流量分开；评测流量单独查看，在线助手和 MCP 的用户质量只统计各自渠道。页面上可看到失败、空答、低置信、降级和点踩。