G10 进阶检索

系列定位：G4 讲「怎么切才对」，G5 讲基础检索三招（查询改写 / 近似检索 / 精排）。这三招解决的是「一段话里就有答案，只是没找出来」的问题。 G10 讲的是当基础检索从原理上就答不了时，官方给的两条进阶路： 知识图谱（knowledge_graph）与 CoRAG 链式检索（corag_module）。 版本基准：MindSDK 26.1.0（RAG SDK） ⚠️ 本课是最容易被"误用"的一课 —— 因为进阶方案的构建与维护成本远高于基础检索，本课的核心不是教你上，而是教你判断该不该上。

第一段章前定位

这课不教你什么：

不教基础检索三招（查询改写 / 近似检索 / reranker 精排）—— 那是 G5 的内容，本课把它们当作已经会了的前提。
不教怎么建库、怎么切分（upload_files 灌库链路、chunk_size 怎么定）—— 那是 G3 / G4 的内容。
不教 embedding 模型微调 —— 那是训练侧的事，归 H 层。
不给「上图谱一定比不上好」的结论 —— 恰恰相反，本课会告诉你多数场景不该上。

这课要教你什么：

基础检索有一个能力天花板，它发生在"答案不在任何一段里"的时候。 这时官方给了两条进阶路： 知识图谱 —— 把关系单独存下来，回答"A 和 B 是什么关系"； CoRAG —— 把一次检索变成多轮迭代检索，回答"先问 X，再拿 X 的答案去问 Y"。

但这两条路都要你付出真金白银的代价：建一次图要调无数次大模型做抽取；CoRAG 每答一次问题要迭代好几轮。 所以本课的一条主线是：先证明基础检索确实不够，再考虑进阶。

⚠️ 一条必须先说清的诚实提示：

官方对这两个模块只有《接口参考》（api/knowledge_graph.md、api/corag_module.md），没有像文生文、多轮对话那样的《开发流程》端到端章节。所以本课里凡属「什么时候该用」的判断，都是基于官方接口能力的归纳，正文会逐条标注；凡官方没给的一律写「官方未给出，需现场确认」。

第二段学习目标

学完这课，你应该能自己回答下面 5 个问题（都能自测）：

基础检索在什么类型的问题上会失效？为什么这不是"调参能救"的问题？
知识图谱模块（GraphRAGPipeline） 解决什么？官方的四个方法分别做什么？
CoRAG（CoRagAgent） 解决什么？它凭什么能回答"多跳"问题？
拿到一个真实的业务问题，你凭什么判断该补基础检索、还是该上进阶？不上进阶会损失什么？
两条进阶路各自的构建成本、运行成本、维护成本落在哪里？（能说出至少各两条官方给出的硬约束）

第三段全景：基础检索的天花板在哪，两条进阶路各补什么

3.1 基础检索做的是"一次相似度匹配"

G5 讲过的那三招，改的都是"这一次检索"：

招	改的位置	本质
查询改写检索（`MultiQueryRetriever`）	检索前	把一个问题拆成几个相似的问题，多查几遍
近似检索（`Retriever`）	检索时	按向量相似度取 topk
精排（`reranker`）	检索后	把取回来的 topk 重新排一遍

⭐ 三招有一个共同的前提：答案存在于某一段 chunk 里，只是没被挑出来。

这个前提一旦不成立，三招全都失效 —— 因为库里根本就没有那段"把两件事连起来的话"：

用户在问什么                        基础检索能不能答
─────────────────────────────────────────────────────────
"X 是什么"（答案在一段里）            能 —— topk 取对了就行
"X 和 Y 什么关系"（关系散在两段里）    不能 —— 没有哪一段同时提到 X 和 Y
"先查 X，再拿 X 的结果查 Y"（多步）    不能 —— 第二问依赖第一问的答案

3.2 两条进阶路，各补一种"串不起来"

用户问题
   │
   ├── 答案在一段里 ──────────────→ 基础检索够用（G3 / G4 / G5 就到这里）
   │
   └── 答案要靠"串"才能得到
             │
             ├── 要串的是【关系】—— 谁和谁、什么关系、中间隔了几跳
             │        └──→ 知识图谱  knowledge_graph
             │
             └── 要串的是【步骤】—— 先问 A，再按 A 的答案问 B
                      └──→ CoRAG 链式检索  corag_module

3.3 两条路的官方定位（原文）

模块	官方功能描述（节选）	官方点名的适用场景
知识图谱 `knowledge_graph`	结合大模型、图数据库（如 NetworkX 或 OpenGauss）、向量检索、重排序，实现文档的结构化知识抽取、图谱构建、概念聚类、向量化检索和多跳推理	「复杂知识问答、企业知识管理、智能检索等场景」
CoRAG `corag_module`	「一种基于链式检索增强生成的多轮问答框架，通过迭代生成子查询、获取相关文档并整合信息，实现复杂问题的深度推理和回答」	官方未单列场景清单

⭐ 关键区别一句话：

知识图谱把"关系"提前抽出来存好（建的时候贵，查的时候便宜）； CoRAG 不预建任何东西，每次问答现场多轮迭代（建的时候不贵，查的时候贵）。

这一句话就是本课的判断主轴。

3.4 两个模块在官方 16 个接口模块里的位置

官方《接口参考 · 使用说明》（api/README.md）列全了 RAG SDK 的 16 个接口模块， knowledge_graph 与 CoRAG 是最后两个，也是依赖最深、成本最高的两个。

⚠️ 官方在《使用说明》里给所有接口的两条通用硬规范，对这两个模块同样生效（G6 / G9 会展开）：

「RAG SDK 接口遵循异常处理机制，故用户必须在 try/except 语句块内进行调用以及异常处理，防止在使用的过程中出现异常抛出导致程序退出的情况。」

「如果使用 Cache 对问题-答案缓存，生成的数据库未做加密存储，如果涉及银行卡号、身份证号、护照号、口令等个人数据，请勿存放到数据库中。」

⭐ 为什么要在本课引这两条：进阶检索调用链更长、失败点更多， 一次没包异常的建图失败，可能把整个服务带走。

第四段【如果我来做】从"答不对"到决定要不要上进阶

4.0 我会按这个顺序做（顺序错了会白花钱）

① 先回基础，别急着上进阶（不写代码先诊断）
     把"答不对"的问题抄出来，先归因：是没切好？没调检索？还是原理上答不了

② 把问题分类（这一步决定后面所有事）
     多跳类 / 关系类 / 单跳但没查到 —— 三类要三种不同的处理

③ 判断该不该上进阶（用第 4.2 节那张表，别凭感觉）

④ 选路（知识图谱 还是 CoRAG）
     代价模型完全不同：一个贵在建，一个贵在查

⑤ 小样本试（先跑通一条链路，绝不全量建图）
     ⚠️ 这一步最容易花冤枉钱 —— 建图是要调大模型跑抽取的

⑥ 验证（用官方给的评估器，不看"有没有报错"）

⑦ 定版与出证据（参数 + 问题集 + 结果，留一份给别人看）

⑧ 诚实（官方没给的部分明写"这里要自己查"）

⭐ 这个顺序里最容易被跳过、也最贵的是 ① 和 ⑤：

① 跳过 → 把"切分没切好"的问题当成"检索原理不够"，直接建图，建完发现还是答不对；
⑤ 跳过 → 一上来全量建图，参数错了要重跑一遍，而建图是大模型调用的大头。

4.1 第 ① 步：先回基础，把"答不对"归成三类

先确认环境是好的（排除"根本没装对"这种低级归因）：

命令　pip3 list | grep mxRag

含义：确认 RAG SDK 本体的 Python 包在不在（官方《安装部署》第 10 步给的就是这条）拆解：pip3 list（列出已安装的 Python 包）＋ |（管道）＋ grep mxRag（筛出含 mxRag 的行）用法：直接执行；想同时看版本用 pip3 show mxrag 期望：输出一行形如 mxrag 26.1.0（要看得到版本号） 不过会怎样：没有任何输出 → RAG SDK 没装或装到了别的 Python 环境（先回 G3《知识库搭建》的十步安装，别在这上面耽误事）

命令　python3 -c "from mx_rag.graphrag import GraphRAGPipeline; from mx_rag.corag.corag_agent import CoRagAgent; print('graph+corag ok')"

含义：确认两个进阶模块真的能导入 —— 这是"包在"和"模块能用"之间的差别拆解：python3 -c "..."（执行一段 Python）＋两个 from ... import ... 　　（包的路径分别来自官方示例 from mx_rag.graphrag import GraphRAGPipeline 与 from mx_rag.corag.corag_agent import CoRagAgent）用法：直接执行期望：打印 graph+corag ok 不过会怎样：报 ModuleNotFoundError 或 ImportError → 说明这个版本的 RAG SDK 没带这两个模块，先把版本对上再谈进阶（⚠️ 官方未给出这两个模块的最低版本要求，需现场确认）

然后做真正的归因（这一步没有命令能替代，要人工把问题抄出来看）：

你看到的现象	归到哪一类	该走哪条路
答案在文档里有，但检索没查到	基础检索没调好	回 G5，上查询改写 / 调 `k` / 加 reranker
查到了，但话说到一半	切分问题	回 G4，调 `chunk_size` / `chunk_overlap`
答案要跨两段才拼得起来，且拼的是关系	关系类	候选：知识图谱
答案要一步接一步问，第二步的问题取决于第一步的答案	多跳类	候选：CoRAG
问题本身模糊，用户自己也没说清	不是检索问题	别用技术方案盖业务问题

⭐ 最后一行最值钱：有相当一部分"检索不行"，其实是问题本身没定义清楚 —— 这类问题上任何进阶模块都是浪费。

4.2 第 ③ 步：判断该不该上进阶（本课最核心的一张表）

⚠️ 这张表是归纳，不是官方成文判据。 依据是官方两个模块的功能描述与参数约束（附录 A 逐条给了出处）， 官方没有给「什么场景该上」的决策文档。

判断项	倾向不必上	倾向可以考虑上
答案的形态	答案能在一段里说清	答案必须由多个实体/多个步骤拼出来
问答占比	这类问题占比很低（偶尔一个）	这类问题是主流量（业务就靠它）
数据更新频率	文档天天变	文档相对稳定（改了要重建，见下）
谁来维护	没人专门盯这个系统	有明确的负责人和迭代预算
算力余量	卡的余量已经很紧	有余量跑建图和多轮迭代
能不能接受"要重来"	不能接受	能接受（建图/换参数要重跑）
先试过基础方案没有	没试过 ← 这一条一票否决	基础方案已经试到头了

⭐ 最后一行是硬门槛：

没有把 G4（切分）+ G5（检索三招）试到头，就没资格判断"基础检索不够"。 因为进阶方案的前置条件恰恰是它 —— 图谱里的节点索引、CoRAG 调的那个检索接口， 用的还是同一套 chunk 和同一个向量库。底下没搭好，建了图也一样答不对。

4.3 第 ④ 步：选路 —— 两条路的代价模型完全不同

先看官方给出的硬约束（这些才是真正的成本）：

维度	知识图谱	CoRAG
成本发生在什么时候	建的时候（`build_graph` 要调大模型做三元组抽取）	查的时候（每答一问要迭代多轮）
官方给的容量约束	`work_dir` 剩余空间至少 5GB；`upload_files` 一次文档个数 [1, 100]；单个文档不超过 10G	无此约束（它不预建东西）
官方给的性能提示	「一次上传过多文档构建知识图谱时会比较慢」	官方评估示例输出里有 `avg_path_time` 与 `avg_time` 两个字段（见 5.9）
要不要额外组件	要选图数据库：`networkx`（默认）或 `opengauss`	要已经有一个能 POST 的检索接口（`retrieve_api_url`）
数据变了怎么办	内容变 → 图要重建（那是一次完整的抽取过程）	不用重建，因为它每次现查
哪一类问题它能答	关系/多跳（`subgraph_depth` 控制探索深度）	多步追问（`max_path_length` 控制轮数）

选路的一句话判据（归纳）：

要串的是"关系"，且文档稳定 → 知识图谱。 要串的是"步骤"，且文档常变 → CoRAG。 两个都要 → 官方未给出两者叠加的用法说明，需现场确认（见附录 A 第 12 条）。

4.4 第 ⑤ 步：小样本试 —— 这一步决定你会不会白花钱

⭐ 铁律：先拿一小批文档、一组问题，把一条链路跑通，再谈全量。

知识图谱方向，先确认工作目录够不够：

命令　df -h <work_dir>

含义：看知识图谱工作目录剩余空间够不够 —— 官方对 work_dir 的硬要求是剩余空间至少 5GB 拆解：df（disk free，看磁盘余量）＋ -h（human-readable，人类可读单位）用法：df -h /data/graph_work（把路径换成你给 work_dir 的那个目录）期望：Avail 一列 ≥ 5G（官方下限） 不过会怎样：报 No such file or directory → 目录还没建，先建目录； Avail 小于 5G —— 别开始建图，中途写不下是最难查的一类失败

CoRAG 方向，先确认那个检索接口真的能用（这是 CoRAG 的唯一外部依赖）：

命令　curl -s -X POST <retrieve_api_url> -H 'Content-Type: application/json' -d '{"query":"测试问题","top_k":5}'

含义：手工打一次 CoRAG 要调的那个检索接口 —— 确认它存在、能收 POST、返回的是能解析的 JSON 拆解：curl（发 HTTP 请求）＋ -s（安静模式，少打进度）＋ -X POST（用 POST 方法）　　＋ -H 'Content-Type: application/json'（告诉对方我发的是 JSON）　　＋ -d '{...}'（请求体）　　请求体的字段来自官方《CoRAG》文档的请求体示例：{"query": "...", "top_k": 5} 用法：把 <retrieve_api_url> 换成实际地址；官方只规定接口必须支持 POST、请求体为 JSON 且包含查询文本 query 期望：返回一段 JSON，且能对上官方的响应格式之一（document_ids+documents / chunks / data / results / docs / passages 六种之一） 不过会怎样：Connection refused → 接口地址不对或没起；返回 200 但字段对不上那六种格式 → CoRAG 取不到文档内容（它认的是 content/contents/text 与 id/doc_id 这些字段名）； ⚠️ 官方未给出这个检索接口该怎么部署（用 RAG SDK 自己的、还是自建），需现场确认

4.5 第 ⑥ 步：验证 —— 用官方给的评估器，不看"有没有报错"

⭐ 两条路官方都给了评估器，这是本课最有判断价值的一条：

路	官方评估器	它回答什么问题
知识图谱	`GraphEvaluator.evaluate(relations)`	图建得好不好（抽取的精度/召回/F1）
CoRAG	`CoRagEvaluator.evaluate(...)`	CoRAG 比朴素检索好多少（它内置了朴素检索对比）

⭐ CoRAG 评估器里有一个非常实用的开关： enable_naive_retrieval（默认 True）—— 它会同时跑一遍"不用 CoRAG、直接检索"的结果，输出里给你 corag_accuracy 和 naive_accuracy 两个数。

这就是你判断"值不值得上 CoRAG"的官方依据 —— 不是你觉得好，是两个数放在一起。

4.6 第 ⑦ 步：定版与出证据

进阶方案要留下的一份记录（官方未规定格式，这是实践归纳）：

项	内容
走的是哪条路	知识图谱 / CoRAG
触发它的问题类别	关系类 / 多跳类，共几个问题
基础方案的对照结果	同一组问题，G5 的三招跑出来是多少 ← 这一栏是"该不该上"的证据
关键参数定版值	`subgraph_depth` / `max_path_length` / `retrieval_top_k`
评估结果	`GraphEvaluator` 的三组 P/R/F1，或 `corag_accuracy` vs `naive_accuracy`
没做成的部分	官方没给答案、只能标"现场确认"的那些

⭐ 「基础方案的对照结果」这一栏最值钱： 它证明的不是"进阶方案能用"，而是"进阶方案值得用"。——这两件事不一样。

第五段逐件拆开：知识图谱、CoRAG

5.1 知识图谱：一个类，四个方法

官方给的是「一个统一入口 + 四个方法」：

from mx_rag.graphrag import GraphRAGPipeline
GraphRAGPipeline(work_dir, llm, embedding_model, dim, rerank_model,
                 graph_type, graph_name, encrypt_fn, decrypt_fn, kwargs)

官方功能描述：「提供知识图谱创建、检索的统一入口。」

关键参数（官方原文摘录）：

参数	必选	官方说明
`work_dir`	必选	知识图谱工作目录，剩余空间至少 5GB；保存生成的图 json 中间文件。不能为相对路径，路径长度 ≤1024，不能为软链接且不允许存在 `..`；不在禁止路径列表：`["/etc", "/usr/bin", "/usr/lib", "/usr/lib64", "/sys/", "/dev/", "/sbin/", "/tmp"]`
`llm`	必选	大模型接口实例对象（`Text2TextLLM`）
`embedding_model`	必选	`langchain_core.embeddings.Embeddings` 的子类，取值包含 `mx_rag.embedding.local.TextEmbedding`、`mx_rag.embedding.service.TEIEmbedding`
`dim`	必选	向量维度，范围 [1, 1024×1024]
`rerank_model`	可选	默认 `None`；可取 `mx_rag.reranker.local.LocalReranker` / `mx_rag.reranker.service.TEIReranker`
`graph_type`	可选	默认 `"networkx"`，取值仅支持 `["networkx", "opengauss"]`
`graph_name`	可选	默认 `"graph"`，范围 [1, 255]，只能由标识符组成
`encrypt_fn` / `decrypt_fn`	可选	对 `build_graph` 产生的 json 加/解密的回调。官方明确：上传文档涉及银行卡号、身份证号、护照号、口令等个人数据时，请配置该参数
`kwargs`	可选	扩展参数，含 `age_graph`（`openGauss` 图时必传）、`devs`（指定 NPU 设备，只含一个元素的 list）、`node_vector_store`、`conceptualize`（默认 False）、`concept_vector_store`

⭐ 三个从参数表里能直接读出来的成本信号：

work_dir 要 ≥5GB → 图是落盘的，不是纯内存结构；
devs 是本地的 NPU 设备号 → 建图和检索都要占卡；
conceptualize 默认 False → 概念聚类是要额外开的（开了就多一份 concept_vector_store 的开销）。

5.2 四个方法：上传 → 建图 → 检索 → 取检索器

方法	官方函数原型	干什么	返回值
上传文档	`def upload_files(file_list, loader_mng)`	上传创建知识图谱所需要的文档列表	无
建图	`def build_graph(lang, **kwargs)`	创建文本节点索引并生成知识图谱	无（但落盘产出 6 个文件，见 5.3）
检索	`def retrieve_graph(question, **kwargs)`	检索返回相关文档片段	`List[str]` —— 检索到的上下文片段
取检索器	`def as_retriever(**kwargs)`	返回检索器	`GraphRetriever`（继承自 `langchain_core.retrievers.BaseRetriever`）

upload_files 的官方两条硬约束（这两条决定了建的节奏）：

file_list：文件列表，注意同一批次文档列表只支持同一种语言类型， 一次上传过多文档构建知识图谱时会比较慢，文档个数限制 [1, 100]。单个文档路径长度 [1, 1024]，不能为软链接且不允许存在 ..，且每个文档大小不超过 10G。

⭐ 翻译：一次最多 100 个文档，而且多了会慢 —— 官方的建议方向是分批，不是一次全塞。

build_graph(lang, **kwargs) 的三个关键扩展参数（官方）：

参数	官方默认值	官方说明
`lang`	`Lang.EN`（英文语料）	⚠️ 中文语料要显式改成中文
`max_workers`	5	构建知识图谱的线程数
`batch_size`	32	节点向量化、检索等操作的批大小
`top_k`	5（范围 [1,100]）	图节点概念聚类时向量检索返回的最相似概念数
`threshold`	0.3（范围 [0.0,1.0]）	向量相似性阈值，低于此值被过滤

⭐ lang 默认为 Lang.EN 这一条最容易踩 —— 中文语料不显式改，抽取质量会明显不对。 （Lang 枚举在 G4 已讲过：只支持 EN / CH 两种。）

5.3 建图完事之后，怎么知道"真的建成了"——六个文件

官方明确列出 build_graph 执行后会在 work_dir 下生成的 6 个过程文件：

文件名	官方说明
`"{graph_name}.json"`	用于保存图；`graph_type` 为 `"networkx"` 时，检索会通过该文件加载图
`"{graph_name}_relations.json"`	保存实体关系信息
`"{graph_name}_concepts.json"`	保存概念信息
`"{graph_name}_synset.json"`	保存概念聚类之后的类别信息
`"{graph_name}_node_vectors.index"`	实体的向量索引文件
`"{graph_name}_concept_vectors.index"`	概念的向量索引文件

⭐ 这 6 个文件就是"建成了没有"的第一手判据 —— 比"命令没报错"可靠得多：

命令　ls -lh <work_dir>

含义：看 build_graph 有没有真的产出那 6 个文件（空格大不大，也能看出抽了多少东西）拆解：ls（列目录）＋ -l（长格式：权限、大小、时间）＋ -h（大小用人类可读单位）用法：ls -lh /data/graph_work（work_dir 实际路径）期望：看到 graph.json、graph_relations.json、graph_concepts.json、　　graph_synset.json、graph_node_vectors.index、graph_concept_vectors.index 　　（文件名里的 graph 是你传给 graph_name 的那个值） 不过会怎样：只有前几个、少了 .index 文件 → 向量化那一步没走完； 一个都没有 → build_graph 根本没跑成功，回第四段排查（别急着调检索参数）

5.4 检索端：`retrieve_graph` 的六个可调参数

def retrieve_graph(question, **kwargs)

扩展参数	官方默认值	官方说明	调大的后果（归纳）
`use_text`	`True`	检索子图时仅使用文本类型节点包含的文本构建上下文	改这个要清楚你的节点类型
`batch_size`	4（范围 [1,1024]）	节点向量化时的批大小	显存与速度的取舍
`similarity_tail_threshold`	0.0（范围 [0.0,1.0]）	向量相似阈值，低于该值被过滤	默认不过滤，调大才开始筛
`retrieval_top_k`	40（范围 [1,1000]）	按实体从节点向量库检索相似节点的 topk	候选更多，噪声也更多
`reranker_top_k`	20（范围 [1,1000]）	reranker 需要的 topk	精排阶段的计算量
`subgraph_depth`	2（范围 [1, 5]）	图检索最大探索的深度	这就是"多跳"的跳数上限

⭐ subgraph_depth 是本课最该记住的一个参数：

它直接定义了这套图"能跨几跳"。默认 2，官方上限 5。 跳数越大，探索的子图越大、耗时越长 —— 这就是"关系类问题"的运行成本旋钮。 ⚠️ 官方只给了范围，没给"什么场景该设几"的经验值，需现场确认。

5.5 建完的图好不好，官方有个专门的评估器

from mx_rag.graphrag import GraphEvaluator
GraphEvaluator(llm, llm_config)          # llm 必选（Text2TextLLM）；llm_config 必选（LLMParameterConfig）

def evaluate(relations)

官方说明：

relations：list[dict]，知识图谱关系列表，每个元素为一个字典， 必须包括键 raw_text，键 entity_relations、event_entity_relations、event_relations 可选。 列表长度范围 [1, 50000]，嵌套深度最高为 5，文本长度限制 4096。

返回值：官方写「无」—— 但它会打印输出三组精度、召回以及 F1 得分，分别对应实体、事件中的实体、事件的抽取情况。

「输出的得分越高，抽取的质量越好。」

⭐ 为什么这条很关键：知识图谱的质量取决于"大模型抽三元组抽得准不准"。 这个评估器就是让你在不看个案的情况下，知道抽取质量到底是什么水平。 （官方调用示例里读的正是 build_graph 产出的 ..._relations.json。）

5.6 CoRAG：三个类，一条"多轮"的链

官方定位（原文）：

CoRAG（Chain of Retrieval-Augmented Generation）是一种基于链式检索增强生成的 多轮问答框架，通过迭代生成子查询、获取相关文档并整合信息，实现复杂问题的深度推理和回答。

三个核心类：

类	官方定位	导入路径（官方示例）
`CoRagBaseConfig`	基础配置类，包含共享的核心参数	`from mx_rag.corag.config import CoRagBaseConfig`
`CoRagAgent`	负责生成推理路径和最终答案，是框架的核心组件	`from mx_rag.corag.corag_agent import CoRagAgent`
`ReasoningPath`	推理路径的数据类，含原始查询、子查询、子答案、文档 ID、思考过程、文档	`from mx_rag.corag.corag_agent import ReasoningPath`

5.7 `CoRagBaseConfig`：把成本参数一眼看清

CoRagBaseConfig(base_llm, retrieve_api_url, num_threads, max_path_length,
                final_llm, sub_answer_llm, judge_llm)

参数	必选	官方默认值	官方说明
`base_llm`	必选	—	基础 LLM 实例，用于生成子查询和答案
`retrieve_api_url`	必选	—	检索 API 的 URL，必须支持 POST 请求，请求体为 JSON 格式，包含查询文本 `query`
`num_threads`	可选	8	并行处理的线程数
`max_path_length`	可选	3	最大路径长度，表示生成子查询的最大轮数
`final_llm` / `sub_answer_llm` / `judge_llm`	可选	`None`	不提供则使用 `base_llm`
`retrieve_top_k`	可选	5	检索 API 返回的文档数量
`client_param`	可选	`ClientParam()`	HTTP 客户端参数

⭐ 从这张表里能读出的成本公式（这是"贵在查"的原因）：

答一个问题，最少要调 max_path_length 轮 LLM 生成子查询 + 同样轮数的检索接口。 而 base_llm / sub_answer_llm / judge_llm 不提供就都退化到同一个 base_llm —— 默认配置下，同一个模型要在一问里被反复调用多次。

⭐ 官方还给了一整套"检索接口返回体"的兼容说明（这是接入时的坑）：

请求体（官方示例）：{"query": "Which company acquired by Google was founded first?", "top_k": 5}
响应体支持 6 种格式：含 document_ids+documents / chunks / data / results / docs / passages
内容从哪里取：字段 content、contents、text
文档 ID 从哪里取：字段 id、doc_id
也支持直接返回字符串列表

翻译：它对你的检索接口很宽容，但字段名必须是那几个之一 —— 否则接口通着，CoRAG 也拿不到内容。

5.8 `CoRagAgent`：两个方法，一问两段

CoRagAgent(base_llm, retrieve_api_url, final_llm, sub_answer_llm)

方法	官方函数原型	返回值
生成推理路径	`def sample_path(self, query, task_desc, max_path_length)`	`ReasoningPath` —— 包含完整推理路径的对象
生成最终答案	`def generate_final_answer(self, rag_path, task_description)`	`str` —— 生成的最终答案文本

⭐ 官方把这两步分开了，这个设计本身就说明问题：

sample_path 是"探索"，generate_final_answer 是"收口"。 分开意味着你可以先看探索出来的路径对不对，再决定要不要生成答案 —— 调试 CoRAG 时，先看 ReasoningPath 里的 subqueries / subanswers，比直接看最终答案有用得多。

ReasoningPath 的六个字段（官方）：original_query、subqueries、subanswers、 document_ids、reasoning_steps、documents。

⭐ reasoning_steps：「思考过程列表，每个子查询对应一个思考过程」 —— 这是 CoRAG 相对基础检索最不一样的一点：它把"为什么这么问"留下来了。 但也要清楚：这份留痕本身也是要花算力生成的。

5.9 官方给的评估输出：CoRAG 到底比朴素检索强在哪

CoRagEvaluator：

from mx_rag.corag.evaluator import CoRagEvaluator
CoRagEvaluator(config)

def evaluate(self, eval_file, save_file, calc_recall, enable_naive_retrieval, num_contexts)

参数	官方默认值	官方说明
`eval_file`	—	支持 HotpotQA 和 MuSiQue 两种格式
`save_file`	—	结果保存文件路径
`calc_recall`	`True`	是否计算召回率
`enable_naive_retrieval`	`True`	是否启用朴素检索对比。「朴素检索是指通过原始问题直接调用检索 API 检索相关文档，不依赖 CoRAG 流程」
`num_contexts`	10	检索上下文数量

官方给出的评估输出（示例片段，type 为 Summary 的那一条）：

字段	官方示例值
`total_samples`	11
`corag_accuracy`	0.36
`naive_accuracy`	0.090
`corag_correct_count`	4
`naive_correct_count`	1
`avg_path_time`	142.308
`avg_time`	56.682
`corag_micro_recall`	0.863
`naive_micro_recall`	0.68

⭐ 这张表要怎么看（本课最重要的一段读法）：

质量确实上去了：corag_accuracy 0.36 对 naive_accuracy 0.090；
代价也确实在那里：avg_path_time 142.308 对 avg_time 56.682 —— avg_path_time 明显更高；
⚠️ 但这两组数字是官方文档里的"示例评估输出"，不是你场景里的性能承诺。 你自己的场景是涨了还是没涨，只能自己跑 CoRagEvaluator 出来看。

这一条就是本课"该不该上"的量化入口： 如果 corag_accuracy 没比 naive_accuracy 高出多少，那多花的时间就不值。

5.10 CoRAG 还有一条"建的时候也贵"的路：样本生成与微调

官方给了 CoRAG 的样本生成与子查询微调（这是很多人不知道的一块）：

类	官方定位	关键方法
`SampleGenerator`	生成 CoRAG 训练样本，多线程并行，为每个查询生成有效推理路径	`def generate(self, input_file, output_file, n_samples)`，`n_samples` 默认 5（每个查询采样的路径数量）
`SubqueryFineTuner`	微调模型以优化子查询生成，支持 NPU 加速	`def train(self)`；官方明确：使用前需要调用 `torch.npu.set_device` 设置 NPU 设备

⭐ 这里有一条和本体系直接接上的官方说明：

「支持 NPU 加速，使用前需要调用 torch.npu.set_device 设置 NPU 设备。」

这就是 C 层（TorchNPU）的知识在 G 层的落点 —— 微调那一侧要走昇腾，前提还是那个"框架认得卡"。

⚠️ 但要诚实说清：微调属于训练侧。本课只把它标出来（它是"进阶中的进阶"）， 具体怎么训，官方在 CoRAG 章节只给了接口示例，训练侧的完整流程不在本课范围。

第六段判据 / 验收

本段的硬要求：看内容，不看报错。 ⚠️ 本段所有判据都是实践归纳 —— 官方没有给这两个模块的验收清单。

6.1 知识图谱的四条判据

#	判据	怎么验	不过说明
①	图落盘了	`ls -lh <work_dir>` 看到官方列的那 6 个文件	建图没跑完 / `work_dir` 不可写
②	抽取质量过得去	`GraphEvaluator.evaluate(relations)` 打印出三组 P/R/F1	抽取指令/语言没配对（`lang` 默认是 `EN`）
③	关系类问题能跨跳	拿一组必须跨文档的问题问 `retrieve_graph`，看 `List[str]` 里有没有把两段都带回来	`subgraph_depth` 太小（默认 2）
④	和基础检索有对照	同一组问题，基础检索跑一遍，图检索跑一遍	没有对照 = 证明不了该上

6.2 CoRAG 的四条判据

#	判据	怎么验	不过说明
⑤	检索接口通	第四段那条 `curl -X POST` 能收到 6 种格式之一	`retrieve_api_url` 不对，或字段名不在官方那几个里
⑥	路径真的生成了	`sample_path(...)` 返回的 `ReasoningPath` 里 `subqueries` 和 `subanswers` 非空	模型没按 `task_desc` 生成子查询
⑦	比朴素检索强	`CoRagEvaluator.evaluate(..., enable_naive_retrieval=True)` 的 `corag_accuracy` 明显高于 `naive_accuracy`	不强就别上（直接看 5.9 那组字段）
⑧	多花的钱有数	对比输出里的 `avg_path_time` 与 `avg_time`	只有质量数据没有时间数据，等于没做决策

⭐ 判据 ⑧ 单独拎出来说： "效果好"从来不是决策依据，"效果/代价"才是。 官方评估输出里同时给了质量和时间两组数，这就是设计者希望你两个一起看。

第七段出问题怎么查

排查顺序：先确认"基础方案真的不够" → 再确认"进阶链路跑通了" → 最后才怀疑效果。

7.1 知识图谱方向

你看到的现象	先归到哪一步	具体动作
建图报错、`work_dir` 相关	环境	查路径是不是相对路径、有没有 `..`、是不是软链接、在不在禁止列表（`/etc`、`/tmp` 等）、剩余空间够不够 5GB
建图很慢、跑很久	规模	官方明说「一次上传过多文档构建知识图谱时会比较慢」→ 拆批（单批上限 100 个文档）
中文语料抽出来的东西很怪	语言	`build_graph` 的 `lang` 默认是 `Lang.EN` → 显式改成中文
六个文件只出了前几个	向量化	缺 `.index` 文件 → 向量化那步没走完；查 `devs` 设的设备对不对
概念相关的文件是空的	配置	`conceptualize` 默认 `False` → 不聚类就不会有概念数据，这属正常
关系类问题还是答不对	跳数	查 `subgraph_depth`（默认 2，上限 5）
抽出来的东西质量差	质量	跑 `GraphEvaluator.evaluate` 看三组 P/R/F1 —— 先量，再改
想改抽取规则	提示词	官方给了默认提示，可通过 `triple_instructions`（`entity_relation` / `event_entity` / `event_relation`）与 `conceptualizer_prompts`（`entity` / `event` / `relation`）覆盖
要换图数据库	选型	`graph_type` 只支持 `networkx` / `opengauss`；选 `opengauss` 必须传 `age_graph`（官方明说「请使用安全的连接方式」）
涉及个人数据	安全	官方明确：配置 `encrypt_fn` / `decrypt_fn` 保证个人数据安全

7.2 CoRAG 方向

你看到的现象	先归到哪一步	具体动作
一启动就报检索接口错	外部依赖	`retrieve_api_url` 必须支持 POST、请求体 JSON 且含 `query` —— 用第四段那条 `curl` 先手工打通
接口通了但一条文档都拿不到	字段名	响应内容必须能在 `content`/`contents`/`text` 里取到，ID 在 `id`/`doc_id` 里取到；对不上就是取不到
答一问特别慢	轮数	`max_path_length` 默认 3 → 每加一轮就多一轮 LLM + 检索
子查询跑偏	任务描述	`task_desc` / `task_description` 是指导 LLM 行为的，写清了它才不跑偏
同一个模型被反复调用	配置	`final_llm` / `sub_answer_llm` / `judge_llm` 不提供就都退化成 `base_llm`
想要更多训练样本	样本生成	`SampleGenerator.generate` 的 `n_samples` 默认 5（每个查询的采样路径数）
微调时卡在设备上	NPU	官方明确：使用前需要调用 `torch.npu.set_device`
评估报文件格式错	输入格式	`eval_file` 只支持 HotpotQA 与 MuSiQue 两种格式
评估结果里没有对照	开关	`enable_naive_retrieval` 默认 `True`，别关掉 —— 关了就没有对照

7.3 一个通用的、比技术排查更靠前的动作

现象	先做什么
上进阶之后效果并没有变好	回第四段 4.1 的第一张表：把问题重新归一次类。很多"检索不行"其实是切分或问题定义的问题
不想再花钱了，想退回去	可以退：两个模块都是独立调用的，`knowledge_graph` 只多占了 `work_dir`；CoRAG 只是多了一个外部接口。基础链路（G3–G5）一直没被动过

⭐ 最后一行是本课要给你的底气： 进阶方案不是替换关系，是叠加关系。不上、或者上了再退，基础链路都不受影响。

第八段常见报错清单

⚠️ 先说清一件事：官方 RAG SDK 文档没有单独的"报错码表"，且故障案例库里没有知识图谱 / CoRAG 相关案例（按关键词检索返回 0 条）。本表上半部分是官方 FAQ 的原文条目（可直接照用）， 下半部分按现象组织，属实践归纳。查其他报错用官方案例库按稳定特征词检索： https://www.hiascend.com/document/caselibrary

8.1 官方 FAQ 里的真实条目（这两个模块同样会碰到）

现象	官方原因	官方解决方案
Python 导包时 `std::bad_alloc`	不同组件引用 libgomp 时冲突	在运行的 Demo 或示例代码第一行加入 `from paddle.base import libpaddle`（官方示例里就有这一行）
运行完成最后报 `corrupted size vs. prev_size` 或 `Segmentation fault`	业务进程中有别的组件用了 acl 资源并调用了 `aclFinalize` 释放，导致 acl 资源重复释放	方案一：设环境变量 `MX_INDEX_FINALIZE=0`（表示 Index SDK 不调用 `aclFinalize`）。方案二：删掉 `from paddle.base import libpaddle`，并调整导包顺序 —— 若同时导入 `mx_rag.retrievers`/`mx_rag.storage` 与 `mx_rag.document`/`mx_rag.knowledge`，需先导入后者
抛出异常时堆栈只打印一行	默认堆栈限制为 0：`sys.tracebacklimit = 0`	在 `import mx_rag` 或子模块之后增加 `sys.tracebacklimit = 1000`。⚠️ 官方 NOTE：打印堆栈可能带出调用点参数，注意识别敏感信息

⭐ 第三条对这两个模块尤其重要： 进阶链路的调用层次比基础链路深 —— 堆栈只有一行时，你根本不知道错在"建图"还是"检索"，所以 sys.tracebacklimit 这条要提前设。

8.2 按现象查（本节为归纳）

现象	先查什么
`ModuleNotFoundError: mx_rag.graphrag` / `mx_rag.corag`	这个版本的 SDK 带没带这两个模块（⚠️ 官方未给出最低版本要求，需现场确认）
`work_dir` 相关报错	相对路径 / `..` / 软链接 / 在禁止路径列表里 / 剩余空间 <5GB
建图慢到不可接受	单批文档数（官方上限 [1,100]），拆批重跑
中文抽取质量差	`build_graph(lang=...)` 默认 `Lang.EN`
`.index` 文件不存在	向量化未完成；`devs` 指定的 NPU 设备是否正确
`opengauss` 图相关报错	`graph_type="opengauss"` 时 `age_graph` 必须传；官方要求「使用安全的连接方式」
涉及个人数据被质疑	官方明确要求配置 `encrypt_fn` / `decrypt_fn`
CoRAG 取不到文档	响应体字段名是否落在官方的 `content`/`contents`/`text` 与 `id`/`doc_id` 里
CoRAG 超时	`client_param` 的 `timeout` 默认 60 秒（取值 (0,600]）
评估器报格式不认	`eval_file` 只支持 HotpotQA / MuSiQue
微调时报设备错误	官方明确：用前先 `torch.npu.set_device`
服务整个退出	所有 RAG SDK 接口必须在 `try/except` 内调用（官方《使用说明》硬规范）

第九段小结 + 钩子 + 自测

三句话记住本课

基础检索的天花板是"答案得在一段里" —— 一旦答案要靠关系或步骤串起来，改检索参数救不回来，那才是进阶的信号。
两条进阶路的成本发生在不同时候 —— 知识图谱贵在建（建图要调大模型抽取、要 ≥5GB 工作目录、文档变了要重建）； CoRAG 贵在查（max_path_length 默认 3，答一问要好几轮）。
官方给了"值不值得"的量化入口，请用它 —— GraphEvaluator 给你抽取质量，CoRagEvaluator 直接给你 corag_accuracy vs naive_accuracy 和 avg_path_time vs avg_time。没有对照，就没有决策。

⭐ 本课最想留下的一句话

不上进阶方案，不是落后；在没有对照证据的情况下上进阶，才是浪费。

进阶方案解决的是一小类问题（关系类、多跳类）。如果这类问题在你的业务里占比很低，把同样的力气花在 G4 的切分和 G5 的检索上，回报更大。

判断顺序永远是：先证明基础方案试到头了，再谈进阶。

自测（不看上文）

哪一类问题，基础检索从原理上答不了？为什么调 k 或加 reranker 都不管用？
GraphRAGPipeline 的 work_dir 有哪几条官方硬约束？哪一条最容易在建图跑到一半才暴露？
build_graph 跑完之后，哪几个文件说明它真的建成了？
build_graph 的 lang 默认是什么？中文语料不改会怎样？
subgraph_depth 和 max_path_length 分别控制什么？它们各属于哪条路的成本旋钮？
CoRAG 的评估输出里，你要看哪两组数字才能做出"该不该上"的决定？
如果上了进阶方案效果没变好，你的第一步该做什么？

钩子：G 层到这里收口

G10 是 G 层的最后一课。回头看这一层走过的路：

G1 私有化     →  数据不出内网（三件事：部署位置 / 数据流向 / 资产保护）
G2 RAG 基础   →  为什么要 RAG，两条主线八步
G3 知识库     →  怎么把文件灌进去（十步安装 + 两个库）
G4 解析与切分  →  切得对不对（决定检索的上限）
G5 检索与精排  →  三招调好（查询改写 / 近似检索 / 精排）
G6 问答编排   →  怎么组装给模型（Chain / 缓存 / Prompt 压缩 / try·except）
G7 效果评估   →  怎么证明答得对
G8 容量与成本  →  几张卡服务多少人
G9 企业安全   →  权限 / 审计 / 多租户（含官方缓存未加密警告）
G10 进阶检索  →  不够用时，两条进阶路，以及什么时候**不必**上

⭐ G 层的位置一句话说清：

A–F 解决「怎么把模型跑起来」，G 解决「怎么让它在企业里真的能用」。 而 G 层里最容易被误用的一课就是本课 —— 因为它是最"高级"的一课，也最容易被当成"写了才完整"的一课。

⚠️ 还没覆盖的（诚实标注）： 训练侧整块空白 —— 官方四大开发场景里的「训练开发」， A–G 全在推理侧。本课 5.10 提到的 SubqueryFineTuner 只是擦了个边， 完整的微调链路不在这里（计划归 H 层「模型定制」，待立项）。

另外 G 层还有几课没有写完：G6 / G7 / G8 / G9。 本课是 G 层唯一一节可选的课 —— 它排在最后，也最适合"用不到就先跳过去"。

附录 A 官方出处

#	内容	官方出处
1	知识图谱模块定位：「实现基于知识图谱的 RAG 流程。它结合了大模型（LLM）、图数据库（如 NetworkX 或 OpenGauss）、向量检索、重排序等多种技术，实现了文档的结构化知识抽取、图谱构建、概念聚类、向量化检索和多跳推理等能力。该模块适用于复杂知识问答、企业知识管理、智能检索等场景。」	MindSDK 26.1.0《RAG SDK · 接口参考 · 知识图谱》→ `zh/mindsdk/2610/rag/ragug/docs/zh/api/knowledge_graph.md`
2	`GraphRAGPipeline` 函数原型与参数：`GraphRAGPipeline(work_dir, llm, embedding_model, dim, rerank_model, graph_type, graph_name, encrypt_fn, decrypt_fn, kwargs)`；`work_dir` 剩余空间至少 5GB、不能为相对路径、长度 ≤1024、不能软链接、不许 `..`、禁止路径列表 `["/etc","/usr/bin","/usr/lib","/usr/lib64","/sys/","/dev/","/sbin/","/tmp"]`	同上（同文件内 `GraphRAGPipeline` 类功能）
3	`graph_type` 取值：默认 `"networkx"`，取值仅支持 `["networkx", "opengauss"]`；`kwargs` 含 `age_graph`（openGauss 时需指定）、`devs`（只含一个元素的 `list[int]`）、`node_vector_store`、`conceptualize`（默认 `False`）、`concept_vector_store`	同上
4	`encrypt_fn` / `decrypt_fn` 与个人数据提醒：「如果上传的文档涉及银行卡号、身份证号、护照号、口令等个人数据，请配置该参数保证个人数据安全」	同上
5	`upload_files(file_list, loader_mng)`：同一批次只支持同一种语言类型；一次上传过多文档构建知识图谱时会比较慢；文档个数限制 [1, 100]；单文档路径长度 [1,1024]、不能软链接、不许 `..`、单文档不超过 10G	同上
6	`build_graph(lang, kwargs)`：创建文本节点索引并生成知识图谱；`lang` 默认 `Lang.EN`；`max_workers` 默认 5；`batch_size` 默认 32；`top_k` 默认 5（范围 [1,100]）；`threshold` 默认 0.3**（范围 [0.0,1.0]）；`triple_instructions`（`entity_relation`/`event_entity`/`event_relation`）与 `conceptualizer_prompts`（`entity`/`event`/`relation`）可覆盖默认提示	同上
7	`build_graph` 产出的 6 个文件：`"{graph_name}.json"`、`"{graph_name}_relations.json"`、`"{graph_name}_concepts.json"`、`"{graph_name}_synset.json"`、`"{graph_name}_node_vectors.index"`、`"{graph_name}_concept_vectors.index"`；`graph_type` 为 `"networkx"` 时检索通过 `{graph_name}.json` 加载图	同上
8	`retrieve_graph(question, kwargs)`：返回 `List[str]`（检索到的上下文片段）；`use_text` 默认 `True`；`batch_size` 默认 4（范围 [1,1024]）；`similarity_tail_threshold` 默认 0.0（范围 [0.0,1.0]）；`retrieval_top_k` 默认 40（范围 [1,1000]）；`reranker_top_k` 默认 20（范围 [1,1000]）；`subgraph_depth` 默认 2，范围 [1,5]**，「图检索最大探索的深度」	同上
9	`as_retriever(kwargs)`：返回 `GraphRetriever`，继承自 `langchain_core.retrievers.BaseRetriever`**	同上
10	`GraphEvaluator(llm, llm_config)` / `evaluate(relations)`：对知识图谱质量进行评估、评估大语言模型抽取的三元组关系；`relations` 为 `list[dict]`，必须包括键 `raw_text`，`entity_relations`/`event_entity_relations`/`event_relations` 可选，列表长度 [1, 50000]，嵌套深度最高 5，文本长度限制 4096；函数会打印输出三组精度、召回以及 F1 得分（实体 / 事件中的实体 / 事件）	同上
11	官方提示词：文档给出中文与英文两版默认提示（`TRIPLE_INSTRUCTIONS_CN/EN`、`ENTITY_PROMPT_CN/EN`、`EVENT_PROMPT_CN/EN`、`RELATION_PROMPT_CN/EN`），便于在默认提示基础上自定义修改	同上
12	CoRAG 模块定位：「CoRAG（Chain of Retrieval-Augmented Generation）是一种基于链式检索增强生成的多轮问答框架，通过迭代生成子查询、获取相关文档并整合信息，实现复杂问题的深度推理和回答。」	MindSDK 26.1.0《RAG SDK · 接口参考 · CoRAG》→ `zh/mindsdk/2610/rag/ragug/docs/zh/api/corag_module.md`
13	`CoRagBaseConfig(base_llm, retrieve_api_url, num_threads, max_path_length, final_llm, sub_answer_llm, judge_llm)`：`retrieve_api_url` 必须支持 POST，请求体 JSON 含 `query`；`num_threads` 默认 8；`max_path_length` 默认 3（生成子查询的最大轮数）；`final_llm`/`sub_answer_llm`/`judge_llm` 不提供则使用 `base_llm`；`retrieve_top_k` 默认 5；`client_param` 默认 `ClientParam()`	同上（`CoRagBaseConfig` 参数说明）
14	请求体与响应体格式：请求体示例 `{"query": "...", "top_k": 5}`；响应体支持 6 种格式（`document_ids`+`documents` / `chunks` / `data` / `results` / `docs` / `passages`）；文档内容从 `content`、`contents`、`text` 提取；文档 ID 从 `id`、`doc_id` 提取；支持直接返回字符串列表	同上
15	`CoRagAgent(base_llm, retrieve_api_url, final_llm, sub_answer_llm)`：负责生成推理路径和最终答案；`sample_path(self, query, task_desc, max_path_length)` → `ReasoningPath`；`generate_final_answer(self, rag_path, task_description)` → `str`	同上
16	`ReasoningPath` 字段：`original_query`、`subqueries`、`subanswers`、`document_ids`、`reasoning_steps`（「思考过程列表，每个子查询对应一个思考过程」）、`documents`	同上
17	`SampleGenerator(config)` / `generate(self, input_file, output_file, n_samples)`：生成 CoRAG 训练样本，多线程并行；`n_samples` 默认 5（每个查询采样的路径数量）	同上
18	`SubqueryFineTuner(finetune_args, train_args)` / `train(self)`：微调模型以优化子查询生成，支持 NPU 加速，使用前需要调用 `torch.npu.set_device` 设置 NPU 设备；`FineTuneArguments` 的 `model_name_or_path` 仅支持本地模型，默认 `"Qwen/Qwen2.5-7B-Instruct"`，`max_len` 默认 2048	同上
19	`CoRagEvaluator(config)` / `evaluate(self, eval_file, save_file, calc_recall, enable_naive_retrieval, num_contexts)`：`calc_recall` 默认 `True`；`enable_naive_retrieval` 默认 `True`（「朴素检索是指通过原始问题直接调用检索 API 检索相关文档，不依赖 CoRAG 流程」）；`num_contexts` 默认 10；`eval_file` 支持 HotpotQA 与 MuSiQue 两种格式	同上
20	评估输出示例数字：`total_samples` 11、`corag_accuracy` 0.36、`naive_accuracy` 0.090、`corag_correct_count` 4、`naive_correct_count` 1、`avg_path_time` 142.308、`avg_time` 56.682、`corag_micro_recall` 0.863、`naive_micro_recall` 0.68	同上（评估输出示例，为文档示例值，非性能承诺）
21	两条通用硬规范：① 「RAG SDK 接口遵循异常处理机制，故用户必须在 try/except 语句块内进行调用以及异常处理，防止在使用的过程中出现异常抛出导致程序退出的情况」；② NOTE「RAG SDK 如果使用 Cache 对问题-答案缓存，生成的数据库未做加密存储，如果涉及银行卡号、身份证号、护照号、口令等个人数据，请勿存放到数据库中」	MindSDK 26.1.0《RAG SDK · 接口参考 · 使用说明》→ `…/docs/zh/api/README.md`
22	官方 16 个接口模块清单：`knowledge_graph` 与 `CoRAG` 是其中第 15、16 个模块	同上
23	官方 FAQ 三条：`std::bad_alloc`（libgomp 冲突 → 首行加 `from paddle.base import libpaddle`）；`corrupted size vs. prev_size` / `Segmentation fault`（acl 资源重复释放 → `MX_INDEX_FINALIZE=0`，或删 `libpaddle` 并调整导包顺序）；堆栈只打印一行（`sys.tracebacklimit = 0` → 改为 1000）	MindSDK 26.1.0《RAG SDK · FAQ》→ `…/docs/zh/faq.md`
24	安装部署章节只列两类依赖：NPU 驱动固件 + CANN；以及 Index SDK 检索软件包与 Python 3.11 —— 未列出 `networkx` / `OpenGauss` 的安装步骤	MindSDK 26.1.0《RAG SDK · 安装部署》→ `…/docs/zh/installation_guide.md`
25	RAG SDK 支持硬件（整体）：Atlas 300I Duo 推理卡 / Atlas 800I A2 推理服务器 / Atlas 800I A3 超节点服务器 —— 官方未给知识图谱与 CoRAG 单独的支持型号清单	MindSDK 26.1.0《RAG SDK · 简介》→ `…/docs/zh/introduction.md`
26	基础检索三个类的官方原型（本课对照用）：`Retriever(vector_store, document_store, embed_func, k, score_threshold)`、`MultiQueryRetriever(llm, prompt, parser, llm_config)`、`BMRetriever(docs, llm, k, llm_config, prompt, preprocess_func)`	MindSDK 26.1.0《RAG SDK · 接口参考 · 检索》→ `…/docs/zh/api/retrieval.md`
27	官方《开发流程》覆盖场景：文生文场景 / 文本检索图片 / 多轮对话 / 调用 Agentic RAG 样例 / chat with ragsdk —— 没有知识图谱与 CoRAG 的端到端章节	MindSDK 26.1.0《RAG SDK · 开发流程》→ `…/docs/zh/user_guide.md`

⚠️ 本文中「官方未给出」的地方（逐条列出）

以下内容在官方文档中没有给 —— 本课没有编造，正文均按「需现场确认」处理：

knowledge_graph 与 corag_module 的最低版本要求（本课用到的导入路径均取自 26.1.0 官方示例，是否更早版本就有这两个模块，官方未给出）。
「什么业务该上知识图谱 / 什么业务不必」的成文判据 —— 官方只给了模块功能描述与「适用于复杂知识问答、企业知识管理、智能检索等场景」这一句，没有决策文档。第二、四段的判断表与选路判据均为本课归纳。
知识图谱模块的额外依赖安装步骤 —— 官方《安装部署》只列 Index SDK 与 Python 3.11，networkx / OpenGauss 怎么装、版本怎么配套，官方未给出。
建图一次的大模型调用量与耗时估算 —— 官方只说「一次上传过多文档构建知识图谱时会比较慢」，没给量化数据。
subgraph_depth 什么场景该设几 —— 官方只给默认 2、范围 [1,5]，没有经验值。
retrieve_api_url 该怎么部署（用 RAG SDK 自己的检索服务、还是自建一个 HTTP 接口）—— 官方只规定协议与请求体，部署方式未给出。
知识图谱与 CoRAG 能否叠加使用（先建图、再用 CoRAG 迭代图检索）—— 两个模块在文档里是并列的，叠加用法官方未给出。
评估结果的合格线 —— 官方只给了示例输出的数字（5.9 那张表），没有说多少算好。
这两个模块的支持硬件型号 —— 官方只有 RAG SDK 整体的硬件表（附录 A 第 25 条），没给模块级的支持清单。
官方故障案例库里没有知识图谱 / CoRAG 相关案例（按关键词检索返回 0 条）—— 所以第八段的报错清单只有 FAQ 那三条是官方的，其余为按现象归纳。
第六段的验收判据（8 条） —— 全部为实践归纳，官方未给这两个模块的验收清单。
第七段的排查表 —— 全部为实践归纳，官方未给排查路径。

附录 B 命令详解

前几课已解释过的命令（source、chmod、pip3 install -r、python3 -c、ls 等）此处不重复展开。 ⚠️ 本课的命令分两类：通用系统命令（df、curl）与 按官方接口写的自检片段（python3 -c / curl 请求体）—— 后者不是官方给出的命令，是按官方示例构造的，正文已逐条标注。