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版本中再加入。

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。原始发表：2025-07-30，如有侵权请联系[email protected] 删除