langchain_neo4j_rag_app

想象一下这个场景：你是医院信息科的技术人员，领导扔给你一个需求——「能不能做个聊天机器人，让护士和行政人员用自然语言查询医院的就诊数据、科室等待时间和患者反馈？」

传统做法是让工程师写一堆 SQL 接口，前端再做几个查询页面，不仅开发周期长，每次需求变化都要改代码。而现在，有了这个开源项目，你可以直接丢给大语言模型一个数据库连接，让它自己学会写 Cypher 查询语句，自己去图数据库里找答案。这就是 LangChain + Neo4j RAG Chatbot 做的事情。## 项目背景

本项目源自美国知名 Python 教程网站 Real Python 的一篇实战文章「Build an LLM RAG Chatbot With LangChain」，由得克萨斯大学达拉斯分校学生 hfhoffman1144 开发维护，2023 年 12 月首次提交，至今已获得 248 颗 Stars 和 72 个 Fork。

项目的核心目标不是做一个面向患者或医生的最终产品，而是一个可扩展的 RAG 开发模板——它展示了如何将 LangChain 的最新特性（Agent 工具调用、动态 Prompt 优化）与图数据库（Neo4j）的结构化查询能力结合起来，构建一个真正能理解自然语言并访问真实数据库的智能助手。

作者在 README 中明确写道：「希望这个仓库能为开发者提供一个模板，用于为自己的数据和场景构建聊天机器人。」## 技术原理：用 Cypher 查询让大模型「读懂」图数据库

这个项目最值得研究的技术亮点，是它实现了 Text-to-Cypher 能力——让大语言模型根据用户的自然语言问题，自动生成并执行 Cypher（图查询语言）语句，从而访问 Neo4j 中的结构化医疗数据。

Agent 工具调用架构

整个系统的核心是一个 LangChain Agent，它挂载了 4 个工具（Tools）：

1. explore_patient_experiences：用向量检索（RAG）回答患者体验相关问题。患者的评论文本通过 OpenAI Embedding 模型向量化后存入 Neo4j 的向量索引，查询时用语义相似度检索相关评论。

2. explore_hospital_database：将自然语言问题翻译成 Cypher 查询语句，直接访问医院数据库的结构化数据（就诊记录、医生信息、医院信息、保险支付方等）。

3. get_hospital_wait_time：查询特定医院的实时等待时间。

4. find_most_available_hospital：找出当前等待时间最短的医院。

这 4 个工具覆盖了两类完全不同的数据访问模式——非结构化 RAG（患者评论）和结构化 Text-to-Cypher（医院数据）——这正是现代 RAG 系统最值得探索的方向。

动态 Few-Shot Prompting

生成准确的 Cypher 语句是 Text-to-Cypher 的核心难题之一——大模型往往容易生成语法错误或方向错误的查询。项目采用了一个巧妙的动态 Few-Shot 策略：

在向量索引中预先存入一批「问题 → 正确 Cypher」示例对，当 Agent 需要生成 Cypher 时，先用当前问题检索语义最相似的若干示例，将其作为上下文注入 Prompt 中。这种方式比固定 Few-Shot 更精准——每次只注入与当前问题最相关的示例，保持 Prompt 精简的同时大幅提升查询准确率。

自助式 Cypher 示例门户

项目还提供了一个 Streamlit 自助门户（cypher_example_portal），用户可以在界面上传「问题 + 正确 Cypher」对，丰富 Few-Shot 示例库。这意味着产品团队可以在不修改代码的情况下，持续优化 Agent 的查询准确率——这是一个非常实用的运营思路。## 部署体验：docker-compose 一键启动

从工程化角度看，这个项目最让人惊喜的是它的部署设计。项目提供了完整的 docker-compose.yml，定义了 4 个 Docker 服务：

部署只需两步：填写 .env（Neo4J 连接信息 + OpenAI API Key），然后 docker-compose up --build。服务间通过 host.docker.internal 互通，依赖关系清晰（ETL 先启动，后端等待 ETL 完成后启动）。

需要注意的是：项目使用 Neo4j AuraDB（云托管版），需要自行在 neo4j.com 注册免费实例；LLM 调用依赖 OpenAI API，不支持本地模型，因此存在 API 调用费用。## 代码架构：清晰的模块化设计

项目的代码结构体现了良好的工程实践：

langchain_neo4j_rag_app/
├── chatbot_api/src/
│   ├── agents/          # Agent 定义 + 4个工具
│   ├── chains/          # LangChain Chain（cypher_chain, review_chain）
│   ├── langchain_custom/# 自定义 Graph QA Chain
│   ├── models/          # Pydantic 请求/响应模型
│   └── main.py          # FastAPI 入口
├── chatbot_frontend/    # Streamlit 前端（一个 main.py）
├── cypher_example_portal/  # 自助门户（Streamlit）
├── hospital_neo4j_etl/  # CSV → Neo4j ETL 管道
└── data/                # 6个 CSV 医疗数据文件

• chatbot_api 是整个系统的核心，用 Pydantic 定义了请求/响应 Schema（HospitalQueryInput / HospitalQueryOutput），并对外部 API 调用实现了 10 次重试（@async_retry）以应对偶发连接问题。
• hospital_neo4j_etl 使用 Neo4j 的 LOAD CSV WITH HEADERS 语句批量导入数据，并预先设置各节点类型的唯一性约束（CREATE CONSTRAINT IF NOT EXISTS），体现了生产级数据管道的规范意识。
• poetry 管理 Python 依赖，pyproject.toml 中明确定义了 LangChain、LangChain Community、LangChain OpenAI、Streamlit、Neo4j Driver 等核心依赖。## 局限与改进空间

作为一个教学性质的项目，它也有明显的局限性：

LLM 供应商锁定：代码硬编码使用 OpenAI（GPT-4o-mini），不支持本地模型（如 Ollama）或开源模型。如果要换成 Claude 或本地 LLaMA，需要修改多个文件中的 ChatOpenAI 和 OpenAIEmbeddings 调用，扩展性不足。

Cypher 准确性瓶颈：当动态 Few-Shot 检索不到足够相似的示例时，大模型生成的 Cypher 语句仍可能出错。作者在 README 中也承认这是当前的薄弱环节，计划未来加入 Chatbot 性能评估。

Neo4j 依赖：图数据库的运维复杂度（备份、扩缩容、Neo4j AuraDB 的连接数限制）对个人开发者或小团队来说有一定门槛。

多语言支持：目前仅有英文文档和英文数据集，中文场景下需要额外做本地化工作。## 总结与价值

langchain_neo4j_rag_app 是一个质量超出预期的 RAG 教学项目，它用一套完整的医疗数据场景，串联起了 Agent 架构、Text-to-Cypher、向量 RAG、动态 Few-Shot、FastAPI + Streamlit 部署等多项核心技术。

如果你想深入理解 RAG 系统的工程落地，这个项目值得 Clone 下来跑一遍——它比大多数论文配套代码更完整，比大多数开源 RAG 示例更系统。从中你可以学到：

• 如何用 LangChain 定义 Agent 和工具
• 如何用 Neo4j 实现图数据库 + 向量库的混合检索
• 如何通过 docker-compose 将多个微服务整合为一个完整的 AI 应用
• 如何用 Few-Shot Prompting 优化 Text-to-Cypher 准确率

适合人群：LangChain 进阶学习者、知识图谱工程师、正在构建 RAG 系统的 AI 应用开发者。

图1：项目运行演示，展示了 Agent 在回答医院就诊相关问题时的完整对话流程