ArchRAG调试总结

在 AI 系统，例如此次的ArchRAG系统的开发过程中，调试是贯穿始终的核心环节。从环境搭建到模型交互，从数据处理到架构设计，各类问题呈现出明显的层级特征。

以下结合实战经验，对 AI 系统调试的核心问题、根源及解决思路进行系统梳理。

一、环境与依赖配置类 Bug

1. LangChain 模块导入错误

• 现象：ModuleNotFoundError: No module named 'langchain_ollama'等系列错误。
• 原因：LangChain 0.2.x 版本后模块化重构，第三方集成从langchain_community拆分至独立包。
• 解决方案：通过pip install -U langchain-neo4j langchain-ollama等命令安装独立包；将导入语句从from langchain_community.xxx改为from langchain_xxx。
• 经验：框架模块化是趋势，langchain-community常为过渡载体，需紧跟版本变更。

二、服务通信类 Bug

2. Ollama 服务 502 错误

• 现象：向 Ollama 发送请求时返回502 Bad Gateway。
• 原因：网络代理劫持本地流量；模型过大、驱动不兼容、Ollama 内部 Bug 或与无核显 CPU 指令集冲突。
• 解决方案：关闭 V** 和代理并重启 Ollama；重装 Ollama 与 NVIDIA 驱动；设置OLLAMA_CPU_TARGET=v2兼容 CPU；更换轻量模型（如qwen2:1.5b）；小批次处理数据并添加延迟。
• 经验：502是服务崩溃信号，需从网络、硬件、模型多维度排查。这个bug消耗了大量时间，尝试了各种方法都不奏效，最后发现是V**占据了端口，关闭V**后就好了。

三、代码逻辑类 Bug

3. 变量未定义错误

• 现象：NameError: name 'CONFIG' is not defined等。
• 原因：跨模块环境变量访问失败；变量名拼写错误或循环变量与列表名混淆。
• 解决方案：采用单文件架构消除模块导入问题；模块化时通过字典显式传递配置；修正变量名与语法。
• 经验：Streamlit 单脚本模式下，单文件架构是解决变量作用域问题的高效方案。

4. 空嵌入错误

• 现象：ChromaDB 报错Expected Embeddings to be non-empty list。
• 原因：文档解析生成空内容Document对象，或嵌入模型无法生成向量。
• 解决方案：过滤page_content.strip()为空的文档；检查嵌入模型返回值，为空则跳过并警告。
• 经验：数据清洗是 AI 系统基础，输入数据质量直接影响后续流程。

四、LLM 交互与约束类 Bug

5. LLM JSON 输出格式错误

• 现象：Invalid json output，模型输出含对话文本而非纯 JSON。
• 原因：轻量模型指令遵循能力不足；Prompt 缺少格式指令。
• 解决方案：调用 Ollama 时用.bind(format="json")强制 JSON 输出；完善 Prompt 变量注入；升级至yi:34b等强指令模型。
• 经验：小模型格式输出能力有限，需结合强制约束与模型选型。

6. Cypher 语法错误

• 现象：LLM 生成的 Cypher 查询因语法错误失败（如[:提出|:关于]或错误使用ENDS WITH）。
• 原因：模型知识过时；存在语法 “幻觉”，编造不存在的语法。
• 解决方案：Prompt 中注入正确语法示例与正反案例；添加 “属性过滤必须用 WHERE 子句” 等硬性规则。
• 经验：用明确示例与强硬指令约束模型行为，消除语法歧义。

7. RAG 模型幻觉

• 现象：答案脱离检索上下文。
• 原因：Prompt 约束不足，LLM 突破限制调用外部知识；上下文边界模糊。
• 解决方案：Prompt 中加入 “仅用提供上下文，否则明确拒绝” 等硬约束；用<Context>标签划定上下文边界。
• 经验：抑制幻觉需极致 Prompt 工程，明确 AI 角色为受限知识问答机。

五、数据库交互类 Bug

8. 知识图谱数据类型错误

• 现象：Type mismatch: expected a map but was String。
• 原因：LLM 输出 JSON 格式不规范（如节点列表混入纯字符串）。
• 解决方案：入库前验证数据格式，过滤不合格节点与关系。
• 经验：对 LLM 输出需不信任，通过防御性编程确保数据安全。

9. Cypher 版本兼容错误

• 现象：WITH is required between MERGE and CALL。
• 原因：新版 Neo4j 要求MERGE后用WITH传递变量。
• 解决方案：Cypher 模板中添加WITH子句。
• 经验：数据库版本迭代会改变语法规则，需关注兼容性变更。

六、框架与架构类 Bug

10. LangChain 模板解析冲突

• 现象：Input to ChatPromptTemplate is missing variables ['nodes']。
• 原因：from_template()误将含{}的 JSON Schema 解析为模板变量。
• 解决方案：改用from_messages与partial()构建 Prompt。
• 经验：复杂字符串场景需选择合适 API，避免模板解析冲突。

11. LangChain 链式组合错误

• 现象：Expected a Runnable... got <class 'generator'>。
• 原因：过度使用.transform()破坏 LCEL 执行流程，导致数据类型错误。
• 解决方案：拆分链条为多个.assign()步骤，规范数据流。
• 经验：遵循 LCEL 最佳实践，确保组件间数据传递合规。

12. 多轮对话延迟

• 现象：第二个问题返回第一个问题的答案。
• 原因：对话历史 Prompt 指令模糊，LLM 误解任务。
• 解决方案：重写 Prompt，明确任务为 “将后续问题改为独立问题”。
• 经验：指令需唯一且明确，消除歧义是多轮对话关键。

13. 知识图谱失声

• 现象：cypher_query始终为 “无”，图谱路径未激活。
• 原因：Text-to-Cypher 链有 “无法生成则放弃” 的退路，AI 对开放问题过度谨慎。
• 解决方案：重构为向量检索→线索喂给图谱链的串行架构，强制围绕实体构建查询。
• 经验：架构设计需通过流程约束消除 AI “逃避” 倾向，提升功能激活率。

七、调试总结

• 分层排查：从环境到架构，按层级定位问题，避免头痛医头。
• 最小复现：用最简代码隔离问题，排除无关因素干扰。
• 质疑默认：不迷信库的默认行为，验证版本、路径、权限等基础要素。
• 社区借力：开源社区的错误报告与解决方案是重要参考。

AI 系统的调试过程，本质是人与机器、规则与智能的持续磨合。每解决一个 Bug，都是对系统认知的深化，最终实现从能运行到稳定可靠 的跨越。

由于知识图谱的难度远超过预期，目前对其理解不够深入，使用效果不理想，所以在此次的ArchRAG V1.0版本中暂时删除了这项功能。

计划在学习如何用实体-关系-属性的思维，解构和重组信息，设计高质量的Schema（本体）以后，在V2.0版本中再加入。