知识图谱 P0 级缺陷修复总结

Bug A：JSON 解析崩溃

1. 现象：

Pipeline 运行中频繁抛出 json.decoder.JSONDecodeError，导致进程中断。日志显示无法解析 LaTeX 符号（如 \mu, \sim）或 Markdown 代码块。

2. 根本原因 ：

语法的阻抗失配：LLM 输出的是自然语言流（包含转义符、注释、格式修饰），而 Python JSON 库要求的是严格的语法树。两者之间缺乏缓冲层。

3. 修复策略与方法：

策略：三层防御机制。

方法：在 core/utils.py 中重构 extract_json：

• Layer 1 (提取)：利用正则精准提取 ```json ... ``` 或最外层 { ... }，过滤掉无用闲聊。
• Layer 2 (预处理)：引入 LaTeX 专用正则，将 \ 转义为 \\，防止反斜杠破坏 JSON 结构。
• Layer 3 (兜底)：引入 json_repair 库，自动修复缺少的引号、逗号或未闭合的括号。

4. 意义：建立了系统的输入稳定性。无论 LLM 吐出什么“脏”文本，系统都能将其转化为合法的程序对象，确保流水线永不卡死。

Bug B：大法官输出截断

1. 现象：在使用 DeepSeek-R1（推理模型）时，JSON 输出往往在末尾被切断（缺失 }]），API 返回 finish_reason: length。

2. 根本原因：

思维链挤占：推理模型会生成长篇大论的思维链（CoT），占用了有限的 Context Window，导致留给核心 JSON 数据的 Token 预算不足。

3. 修复策略与方法：

策略：物理隔离与动态扩容。

方法：

• Prompt 隔离：强制要求模型将推理过程包裹在 <thought> 标签中，仅将 JSON 放在最后。
• 代码剥离：utils.py 增加逻辑，物理删除 <thought>...</thought> 内容。
• 动态扩容：llm_client.py 识别模型类型，对 Chat 模型分配 8192 Tokens，确保空间充足。

4. 意义：解决了“深度推理与输出完整性”的矛盾。让系统既能拥有专家的思考深度，又能保持数据的完整结构。

Bug C：全1.0置信度

1. 现象：所有提取出的实体和关系，其 confidence 字段均为 1.0。模型表现出毫无根据的盲目自信。

2. 根本原因：

• 指令僵化：Prompt 中曾禁止输出非 1.0 内容，导致模型被迫“撒谎”。
• 缺乏校验：代码层完全信任模型输出，没有“验资”环节。

3. 修复策略与方法：

策略：双重约束。

方法：

• Prompt 分级：在 Prompt 中植入查表法（强制=1.0，推荐=0.9，推断=0.8，其余丢弃）。
• 参数锁定：agents.py 中将 temperature 强制设为 0.0，消除随机性。
• 代码立法：新增 _validate_confidence 函数，如果 confidence=1.0 但缺乏 source_reference（证据），代码强制将其降级为 0.9。

4. 意义：赋予了系统严谨性。通过代码逻辑强迫AI学会谦卑，为下游应用提供了可信的风险评估依据。

Bug D：数值节点图爆炸

1. 现象：neo4j_nodes.csv 中充斥着 20℃, 50Pa, ≥5次/h 等数以万计的孤立节点。图谱臃肿，语义混乱。

2. 根本原因：

建模错误：照搬自然语言的主谓宾结构，将“属性值（Value）”错误地建模为“实体节点（Node）”。

3. 修复策略与方法：

策略：图谱坍缩/ 属性上浮。

方法：

• 模型层 (models.py)：识别指向数值的关系，解析出 {value, unit, operator}，并标记该关系为“待销毁”。
• 导出层 (database.py)：拦截上述关系，将数值属性注入到源节点（如 Parameter）中，并物理剔除所有 Value 类型的节点。
• 类型注入：强制将字段重命名为 value:float，确保数据库可计算。

4. 意义：实现了“从 NLP 到 Database”的思维跃迁。将图谱规模压缩 40%，查询速度提升数倍，并使 AI 具备了数值计算能力。

Bug E：实体命名混乱

1. 现象：

洁净室、洁净区、洁净室（区） 被识别为三个独立节点；AHU 和 ahu 无法对齐。图谱断裂。

2. 根本原因：

熵增原理：自然语言的多样性（高熵）与数据库的唯一性（低熵）冲突。缺乏标准化的清洗机制。

3. 修复策略与方法：

策略：全图联动清洗。

方法：

• 工具层 (utils.py)：构建 EntityNormalizer，集成“正则去括号（含方括号）”和“同义词映射表”。
• 联动更新：在清洗实体名的同时，同步更新所有关系中的 source 和 target，防止断链。
• 集成层 (agents.py)：在 Agent 输出结果前显式调用清洗，确保“对抗派”看到的是对齐后的数据。

4. 意义：解决了数据孤岛问题。实现了多源异构数据的自动对齐，是构建行业标准本体论的基础。

Bug A & B：构建了词法分析器 —— 确保输入流可读、完整。

Bug E：构建了符号表 —— 确保变量名（实体）全局唯一且对齐。

Bug D：构建了类型系统 —— 区分了对象（Node）和原语（Property）。

Bug C：构建了语义校验器 —— 确保逻辑成立、可信。

整个调试过程的本质，是在解决计算机科学中经典的阻抗失配(Impedance Mismatch) 问题。

两个世界的对立

1. 左侧世界 (LLM)：概率的、连续的、发散的。

它倾向于生成流畅的文本，不关心结构的严谨性。

它认为 "20℃" 和 "温度为20度" 是相似的语义流。

2. 右侧世界 (知识图谱/数据库)：确定的、离散的、收敛的。

它要求严格的 Schema。

它认为 (Node) 和 {Property} 是截然不同的数据结构。

3. 我们的角色：波函数坍缩器

我们在 utils.py, models.py, database.py 中编写的所有代码，本质上构建了一个中间件编译器。

它的输入是 LLM 的思维波函数（包含了各种可能性的概率分布）。

它的输出是坍缩后的晶体（唯一的、确定的图谱结构）。

4. Bug 的本质：波函数在坍缩过程中，溢出了容器（JSON报错）、选错了基底（命名未对齐）或维度保留过多（数值节点爆炸）。

通过这一过程，我们总结出了构建 LLM-based 复杂系统的三条铁律：

📜 第一定律：防御性编程是基石

永远不要信任 LLM 的输出结构，即使你已经在 Prompt 里强调了一万遍。

体现：Bug A 和 Bug B 的修复证明，Prompt 只能提高遵循指令的概率，而 Python 代码（正则、解析器、截断保护）才是保障系统 100% 不崩溃的最后一道防线。

Code > Prompt

📜 第二定律：图谱建模决定系统上限

不要把自然语言的语法树直接映射为知识图谱。

体现：Bug D 的修复证明，盲目提取（把数值当实体）会导致图谱不可用。必须用数据库设计的思维（实体 vs 属性）去审视 LLM 的提取结果，主动进行降维（坍缩）处理。

📜 第三定律：数据闭环需多维校验

单点校验是脆弱的，必须建立全链路的校验网。

体现：Bug C 和 Bug E 的修复证明，单纯靠 Prompt 约束（如严禁括号）是无效的。必须结合 Prompt 引导（源头）、Code 清洗（中间件）和 Schema 约束（数据库层）三位一体，才能保证数据的一致性。