Step2 生产知识图谱构建

输入与入口

以下为独立构图入口说明。历史默认主键文件 data/graph_keys.json 已移除，运行下列独立命令时需追加 --keys <配置路径>。日常请使用 scripts/update_data.py --mode templates：该流程从 LLM 数据评估获取主键，不依赖此文件。

默认读取 Step1 已导出的 data/production/<模板名>.xlsx（“数据”页），以 data/templates/metadata/*.xlsx 的“字段来源”页校验表头。不会重新拉取 DMS。节点标签使用完整模板名，例如“人员信息”“项目信息”，属性保留模板字段原名。

# 只做本地预检和关系计算；评分规则会加载本地模型，不调用 Neo4j/LLM
uv run python scripts/build_graph.py --check-only

# 完整流程：预检 → 关系计算 → LLM 元图谱 → Neo4j → 发布元图谱
uv run python scripts/build_graph.py
# 专用入口等效
uv run python scripts/build_production_graph.py

可使用 --template-dir、--production-dir、--relations、--keys、 --output-dir 指定输入输出。QA 与前端默认消费项目 output/ 下的发布文件。显式传入历史 JSON 时，build_graph.py 配置.json [--clear] 仍运行旧固定模板流程；它不属于生产构图。历史 build_meta.py 也不属于新流程，含全图清理，不用于生产数据。

主键与合并

独立构图通过 --keys <配置路径> 读取显式主键配置，例如 {"人员信息": ["工号"], "项目信息": ["项目编号"]}。该入口增加模板时必须在传入配置中明确主键，也支持复合主键；统一更新入口的主键来源不同，见 README。

同主键记录始终合为一个节点，保留所有来源行号。字段按以下规则合并：

空值不覆盖非空值；重复值去重；仅一个非空值时保留标量。
存在不同非空值时，保留为确定排序的列表，不选取第一条或最后一条覆盖。
主键值缺失（含纯空白）的记录输出警告并跳过，不阻断其他有效记录；复合主键提示实际缺失字段。表头或主键配置错误仍阻止入库。属性比较不自动去空格或做业务归一化。
异构类型多值因 Neo4j 数组类型限制，在主属性中存 JSON 编码字符串列表；原始有类型值保留在 _kg_mixed_values_json。关系计算始终使用原始类型值。

关系匹配逐一比较多值列表中的值：任意值对满足规则即连边，同规则同节点对只建一条边；评分关系取命中值对的最高分。多值不意味着同时任职，也不推断先后时间。构图报告包含合并行数、合并主键组数、多值字段统计，以及 warnings（文件、工作表、Excel 行号、缺失字段）和 skipped_rows，不输出原始字段值。跳过行不计入合并行数；全部记录缺主键的模板保留为零节点。原始生产工作簿保持不变。

relation.xlsx 规则

读取每个非空工作表的五列：起点、终点、连接字段、判断方法、边名。空工作表忽略，重复规则、未知模板、错误字段和未知判断方法报错。连接字段通过已知字段组合解析，允许字段名自身含连字符，但歧义时报错。

方法	计算
相等	非空属性值完全一致，保留类型和空格差异
包含	两者必须为文本，执行 `a in b or b in a`
评分	本地 `models/Qwen3-Embedding-0.6B` 编码，余弦相似度严格大于阈值

空值、空字符串和纯空白值均不参与关系匹配，防止空字符串产生全图误连。每条规则检查所有候选节点，保留所有匹配，允许一对多、多对多以及规则命中的自环。边方向严格遵循起点→终点；例如“上级项目编号-项目编号 / 父项目为”是子项目→父项目。评分使用唯一文本缓存和分块矩阵计算；不会按 top-k 截断，也不会退化成词法匹配。 .env 与 .env.example 配置 STEP2_RELATION_SIMILARITY_THRESHOLD=0.8；修改阈值后重新执行构图生效，仅支持 [-1, 1] 内的有限数。

Neo4j 与失败行为

全部本地校验与 LLM 结构校验通过后才创建节点，然后创建关系并回读节点/边数量。节点保留 _kg_id、_kg_file、_kg_sheet、_kg_rows、_kg_build，边保留规则 id、判断方法，以及评分边的得分与阈值。

新图以独立 build id 暂存；数量校验通过后，单次查询删除之前由本流程拥有的 _Step2Record 节点，再发布 JSON。历史固定模板图和其他标签的数据不清理。必须串行运行构图命令；本版本不支持两个构图进程同时发布到同一数据库。

暂存写入失败会尝试删除本次暂存节点；若清理失败，报告会明确标记。激活请求响应不明时保留新图供核对，不冒险删除可能已经成为当前版本的数据。 Neo4j 与本地文件系统不能形成跨系统事务：若数据库已写入而 JSON 发布失败，报告中 database_written=true、schema_published=false，候选 Schema 保留在 output/step2_schema_candidate.json；核对数据库 build id 后重跑可恢复发布。

元知识图谱

LLM 使用现有 .env 的 DEEPSEEK_* 配置。输入只含节点名、字段名、主键字段名、关系规则及聚合数量，不发送原始生产单元格值、文件路径、DMS 物理字段或凭据。真实结构由模板和计算结果确定，LLM 生成语义说明，输出 id 必须完整且唯一，不得新增节点、关系、属性或改写统计。调用/校验失败不发布伪造的成功结果。

输出延续前端 nodes/relations/meta JSON 契约：

meta_graph_schema.json：全部模板和规则，含零记录、零匹配项及实际数量。
meta_graph_schema_display.json：仅有节点/关系实例的展示项。
step2_build_report.json：本次阶段、成败、主键校验、合并统计、关系数量和未匹配节点数。

QA 的 meta/schema.py 摘要优先读取生产文件；旧导出脚本不会再用固定 Schema 覆盖已发布生产 Schema。生产图不套用旧测试数据的 2026-01～04 时间范围。 本轮仅接入元图谱上下文：Step3 的固定检索工具仍用“人员/项目”等历史标签，后续必须按新标签与属性重构检索并做业务回归，不能据此宣称生产问答已可用。

验证

uv run python scripts/test_step2_production.py 使用合成工作簿、可控向量、Fake LLM 和 Fake Neo4j 检查规则、冲突、阈值、元图谱和失败清理，不代表外部服务联调通过。 2026-09-04 用户改为按唯一键合并不同属性；13项离线回归通过。真实预检通过：人员2806行→2804节点（2组重复），项目213节点，父项目为94边、服务于4344边。随后用户对具体目标与聚合载荷回复“继续”，真实构图已成功：3017节点、4438边，完整和展示元图谱 JSON 均已发布。独立数据库回读验证数量与两组多值合并，发布文件 build id 与数据库一致。本机8000接口未响应，浏览器视觉验证尚未完成。

step2-graph-building.md 7.1 KB Permalink Riwayat Mentahan