GraphRAG 增强版验收报告

验收日期：2026 年 9 月 20 日。主案例为教学模拟甜品店，工作目录为 GraphRAG增强版_20260920 独立副本。

新增图检索全链路与原系统接入已经实际跑通。 最新甜品测试 43 项通过，保留的旧 IT 集成测试另行 9 项通过，共 52 项；第五章独立项目也完成了真实模型问答。18 道问题分别运行三种模式，共 54 次评估，其中 52 次真实模型生成、2 次因没有可用证据直接返回资料不足。

本报告区分工程运行、证据召回和答案质量。下文的召回百分比均指必要原文是否进入最终上下文，不能称为答案准确率。

一、验收范围与交付内容

本次实际执行范围包括：

Neo4j 与 Milvus 的同源资料导入，实体定位，包含／需要关系的一跳与多跳查询，原文回填，融合、重排、预算限制及带引用生成。
真实 Neo4j 重复导入、关系方向、引用出处、同名知识域隔离、歧义实体、版本替换和文档删除。
原系统的 FAQ、HTTP、WebSocket、会话历史接入；包括真正的流式模型回答、结束时的来源与路径、多轮追问改写、精确 FAQ 及缓存回答写入历史。
图通道发生连接异常时，保留真实 Milvus 结果，并返回异常信息的降级流程。
第五章独立项目直接执行命令行问答，不依赖整合版页面。

旧课程中的训练教程、模型微调教程及其代码保留。本次没有重新执行全部历史训练流程，也没有重新训练 BERT、BGE 或重排序模型。 “全链路通过”指本次新增检索问答链路及上述原系统接入范围，不能扩展为每份历史训练教程都已经重新运行。

课件构建统计为：47 个页面，其中新增 15 个页面，19 幅图解、29 处对应项目源码的知识点摘录。课件沿用已有版式和代码块形式，主案例先展示三份原始资料与图关系，再讲解术语和短代码。静态构建检查与实际浏览器检查已完成，0 断链、0 缺图、0 无效锚点、0 远程关键依赖。

二、主数据与原模型复用

甜品店主数据位于 代码/EnterpriseKB_qa_system/graph_qa/data/dessert-shop，包含：

内容	数量或范围
同源原文	31 份
实体	22 个
有出处的关系事实	27 条
标准问题	18 道
正式教学知识域	`dessert-shop`
同名隔离练习域	`lab-dessert`

套餐与单品使用 CONTAINS（包含），制作对象与材料使用 DEPENDS_ON（需要），负责人和销售位置分别使用 OWNED_BY、SOLD_AT。每条事实保存对应的原文文本块、版本和精确引用。Milvus 与 Neo4j 使用相同 corpus.jsonl 正文，标准问题和参考答案没有进入索引或检索规则。

旧 enterprise-it、lab-it 数据和旧 Milvus 集合继续保留。实际查询确认，新旧 Milvus 集合各有 31 条当前有效原文。有效条数使用查询结果核对，不把包含更新残留的物理存储统计误当成当前文档数量。

运行沿用已有 EnterpriseKB-RAG Conda 环境。编码器为本地已有 BGE-M3，输出稠密向量和学习型稀疏权重；重排序器为本地已有 bge-reranker-v2-m3。已有权重通过共享路径复用，评估记录 model_downloads=0，没有重复下载模型。生成沿用现有账户配置，本次记录中的模型为 gpt-5.5，输出上限为 8192 token。报告与课件不包含账户密钥。

三、真实测试结果

验收项	结果	证据文件
最新甜品完整测试	43 项通过，耗时 66.72 秒	`pytest-integration.log`、`pytest-integration.xml`
旧 IT 附录集成测试	9 项通过，耗时 16.72 秒	`pytest-legacy-it.log`、`pytest-legacy-it.xml`
第五章独立项目真实问答	成功，三份必要原文齐全	`chapter5-standalone.json`、`chapter5-standalone.log`

甜品测试日志中的 9 项 skipped 是旧 IT 附录测试：为避免将不同集合与数据域混测，先在甜品进程中跳过，再使用旧 IT 进程环境独立执行。这 9 项随后全部通过，不属于最终未执行项。

测试真实连接 Neo4j、Milvus、MySQL 和 Redis，真实调用现有生成服务。更新与删除检查在独立 test-* 知识域中执行并清理。故障降级测试仅对图通道注入连接异常，保留实际 Milvus 查询，不以模拟成功结果代替服务验收。

另外验证了两个异步流式任务交错时各自保留引用，避免把一个问题的答案与另一个问题的来源混用。

第五章独立问答的问题是：

草莓缺货，为什么双人下午茶也会受影响？

实际回答给出了“双人下午茶 → 包含 → 招牌蛋糕 → 需要 → 草莓酱 → 需要 → 新鲜草莓”，并分别引用三张资料卡。它同时说明缺料影响的传播方向相反，且已有草莓酱、成品蛋糕仍需盘点，不能直接认定套餐已经停售。该输出记录为真实模型生成，警告、未知引用和跨知识域证据均为 0。

四、三种模式的公平对照

完整评估于北京时间 16:07 至 16:18 执行，graphrag-evaluation.json 中 completed=true，共保存 54 条逐题结果。

三种模式分别为：

模式	实际执行的检索
`milvus`	稠密＋稀疏召回，融合并重排
`graph`	实体定位、包含／需要等图关系查询、回填原文并重排
`hybrid`	稠密＋稀疏＋图召回，统一处理候选与证据

三种模式使用同一批原文、相同编码及重排模型、相同生成服务和提示词。每个向量通道候选上限 20，最终最多 12 个唯一原文块，上下文字符上限 14,000，最大图路径长度 3，路径数量上限 32，RRF 平滑常数 60。

图证据包可能包含多份原文，因此预算按唯一原文块数量核对，不把“12 个图包”与“12 个文本块”视为同等信息量。字符预算是统一上限，实际 token 数并不因此完全相同；每次模型实际 usage 保留在报告中。

模型预热后，每个请求前清除本进程的编码与重排结果缓存，并逐题轮换三种模式顺序。数据库、操作系统缓存和外部服务延迟仍会影响耗时，因此不根据单次速度差异宣称某种检索技术普遍更快。

关系事实由人工逐条核对，并有对应原文；这是一项额外结构化工作。可选 LLM 抽取经过格式、实体与引用校验后仍需人工核查语义，不能把本次结果描述成未经审核的全自动建图效果。

必要原文的总体覆盖

18 道题中，17 道具有明确的必要原文；未知商品题 q13 没有必要来源，其召回率记为 null，不作为 100% 计入均值。

模式	必要原文平均召回率（17 题）	必要证据全部齐全
Milvus 稠密＋稀疏	77.52%	10 / 17
仅图检索	82.35%	14 / 17
融合检索	100%	17 / 17

这是当前小规模教学数据和固定问题集上的结果，不代表任意企业资料的效果。事实来源覆盖同样由入选原文映射得到，向量结果不需要带图路径字段才能计分。原文进入上下文，也不自动保证模型理解或使用正确。

具体补到了哪些缺口

题目	Milvus 必要来源	仅图检索	融合检索	可以观察到的差异
q03：草莓缺货为何影响双人下午茶	1 / 3	3 / 3	3 / 3	补齐招牌蛋糕制作卡、草莓酱制作卡两个中间环节
q01：哪些甜品与套餐的后续制作可能受影响	2 / 5	5 / 5	5 / 5	补齐两种套餐搭配卡与草莓酱制作卡
q04：全部相关商品、店员与通知位置	4 / 9	9 / 9	9 / 9	将岗位记录与配方、套餐组成证据连接起来
q10：蛋糕外带需要哪些包装用品	1 / 1	0 / 1	1 / 1	包装清单是纯文字，融合保留普通文本检索能力

q03 的三份必要来源是：

menu-tea:v1:c01：“双人下午茶包含一份招牌蛋糕。”
recipe-cake:v1:c01：“制作招牌蛋糕需要草莓酱。”
recipe-sauce:v1:c01：“制作草莓酱需要新鲜草莓。”

三份资料没有提前写入完整标准答案。实际 Milvus 结果保留了套餐搭配卡，缺少另外两张制作卡；图检索沿既有关系找到这两个环节。这个具体证据缺口，是本例展示图检索价值的依据。

包装题保留为反例：仅图检索没有取得 policy-packing:v1:c01，无法据图回答蛋糕纸盒、保冷袋和一次性餐具的清单；Milvus 和融合模式都找到了这份原文。不能只展示图通道有收益的问题。

生成与边界检查

54 次评估中，52 次执行真实模型生成。仅图模式的 q11（营业时间）与 q13（未知商品）没有可用证据，程序直接返回资料不足，没有为了凑调用次数强行生成。

完整结果中的通道警告、未知引用编号和跨知识域引用均为 0。人工抽查还确认：巧克力饼干题引用明确“不使用草莓”的配方；未知榴莲千层题没有编造制作人；缺货原因题没有认定采购员漏订；两家店同名套餐分别返回小陈、小方。

这些检查各自只覆盖明确的边界。引用编号合法不等于每句话语义正确，关键词覆盖也不等于答案准确率；完整原始回答保留，供进一步人工审阅。

五、证据文件与复现

本目录主要结果文件：

graphrag-evaluation.json：54 次完整记录，包含原文、路径、实际答案、引用、耗时及模型 usage。
graphrag-evaluation.md：汇总表与逐题缺少的原文。
graphrag-evaluation-showcase.json：主案例及负对照的可视化输入。
pytest-integration.*、pytest-legacy-it.*：当前与保留场景的真实测试记录。
chapter5-standalone.json：第五章独立项目的真实回答。

在 代码/EnterpriseKB_qa_system 目录、已有 Conda 环境中运行：

GRAPH_RUN_INTEGRATION=1 GRAPH_RUN_LLM_TESTS=1 \
  python -m pytest tests_graph -q

python -m evaluation_graph.run_evaluation \
  --output ../../验证结果/graphrag-evaluation.json

旧 IT 附录应使用独立进程变量选择旧集合与数据，不能改动甜品店默认配置后混跑：

GRAPH_SCOPE=enterprise-it \
GRAPH_MILVUS_COLLECTION=enterprise_graph_lesson_v1 \
GRAPH_DATA_DIR="$PWD/graph_qa/data" \
GRAPH_RUN_INTEGRATION=1 GRAPH_RUN_LEGACY_IT=1 \
  python -m pytest tests_graph/test_legacy_it_integration.py -q

六、原文件、页面与接口最终核对

本任务的全部课程和代码修改均位于增强版副本。对原课件与代码的 296 个基线文件进行最终哈希检查，294 个与基线一致；另外 2 个（原 5.1 RAG系统评估工具.html 与 search/search_index.json）在执行期间由用户的另一项任务修改，用于细化忠实度、答案相关性流程图及搜索索引。已核对该任务的文件修改记录；本任务保留这些授权修改，没有还原或覆盖原件。详细记录见 original-integrity.json，原始基线未改写。

课件实际浏览器检查确认：延续原 Material 版式、短代码可复制、中文搜索“草莓”返回 13 个结果；桌面无缺图及页面横向溢出。390px 窄屏下页面宽度仍为 390px，图解在 358px 容器中保留 680px 内容宽度，可横向查看；测试后已恢复浏览器视口。详见 browser-checks.json。

问答页面真实提交主问题后，显示完整三跳解释、12 份原文依据和 5 条候选关系路径；展开可核对配方与套餐原句，刷新后会话、答案及引用仍存在。页面不把缺原料直接等同于所有现货售罄。独立 HTTP 请求返回 200，会话历史记录 1 轮，见 api-query.json 与 api-history.json。课件与演示页均未发现浏览器脚本错误。

副本内 181 个 Python 文件通过语法编译检查（compile-check.json）。旧教程保留了部分字符串转义写法的语法警告，未产生编译错误；此项不代替前述真实服务与问答测试。当前服务数据状态见 health.json。

课件制作习惯已写入课程制作技能与本副本的 research/courseware-preferences.md：先用熟悉的事物直接呈现技术机制，图解和实际数据一致，学生沿图回答具体问题后再学习术语与短代码，避免只有表面相似的类比。

验收报告.md 12 KB History Raw