AI 研究助理 (LangGraph + RAG)

这是一个基于 LangChain 生态（特别是 LangGraph）构建的复杂 AI 工作流项目。它扮演一个智能研究助理的角色，能够根据用户提出的研究主题，智能地决策信息源，结合本地私有知识库 (RAG) 和实时网络搜索，最终自动生成一份结构化的研究报告。

这个项目旨在演示如何使用 LangGraph 构建一个包含条件路由、多数据源检索和状态管理的先进 Agent。

• 动态路由 (Dynamic Routing): 工作流内置一个“路由器”节点，能利用 LLM 分析研究主题，智能决定下一步是查询本地知识库，还是进行网络搜索。
• RAG 集成 (RAG Integration): 能够索引本地文档（位于 documents/ 目录），并基于这些私有知识回答特定问题。
• 实时 Web 搜索: 当问题需要最新或广泛的信息时，可以调用 DuckDuckGo 进行实时网络搜索。
• 状态化工作流 (Stateful Workflow): 全程使用 LangGraph 构建，通过一个中心化的 State 对象来管理和传递数据，使复杂流程清晰可控。
• 自动化报告生成: 在聚合所有信息后，自动生成一份格式良好、内容连贯的研究报告。

该助理的工作流程被建模为一个有向图，其执行逻辑如下：

1. 规划 (Plan): 接收用户输入的研究主题，利用 LLM 制定一个初步的研究计划和一组核心搜索查询。
2. 路由 (Route): （关键步骤） 分析主题和计划，决定最佳的信息检索策略：
   • 如果主题与本地知识库高度相关，则选择 rag_retrieval 路径。
   • 如果主题需要广泛或最新的信息，则选择 web_search 路径。
3. 检索 (Retrieve): 根据路由决策，执行相应的检索任务（从本地 Chroma 向量数据库或从网络）。
4. 聚合 (Aggregate): 将从不同来源检索到的信息整合成一份统一、干净的上下文。
5. 生成 (Generate): 基于聚合后的上下文，驱动 LLM 生成最终的详细研究报告。

/ai_research_assistant/
├── .env                  # 存储API密钥的环境变量文件
├── README.md             # 项目说明
├── requirements.txt      # Python依赖包列表
├── config.py             # 加载配置和环境变量
├── ingest.py             # [重要] 用于构建本地向量数据库的脚本
├── retrievers.py         # 统一管理RAG和Web检索器
├── graph.py              # LangGraph的核心：定义State、节点和图逻辑
├── main.py               # 项目的执行入口
└── documents/            # 存放你的本地知识库源文件 (.txt)
    └── medical_ai_report_2024.txt
└── vector_store/         # ingest.py脚本处理后生成的本地向量数据库

请遵循以下步骤来设置和运行项目。

git clone https://github.com/zhang-song-bo/a-simple-langgraph-demo
cd ai_research_assistant

为了避免包版本冲突，强烈建议使用虚拟环境。

• macOS / Linux:

  python3 -m venv venv
  source venv/bin/activate

• Windows:

  python -m venv venv
  venv\Scripts\activate

pip install -r requirements.txt

创建一个名为 .env 的文件，复制以下内容，并将 sk-... 替换为你的真实 OpenAI API 密钥。

OPENAI_API_KEY="sk-..."

将你希望助理能够查询的私有文档（目前支持 .txt 文件）放入 documents/ 文件夹中。项目中已包含一个示例文件 medical_ai_report_2024.txt。

在第一次运行主程序之前，你必须先运行 ingest.py 脚本。它会读取 documents/ 文件夹下的所有文档，将其处理并索引到一个本地的 Chroma 向量数据库中（存储在 vector_store/ 目录）。

python ingest.py

注意: 此步骤只需执行一次。如果你更新了 documents/ 文件夹中的内容，需要重新运行此脚本来更新知识库。

所有设置完成后，直接运行 main.py 即可启动工作流。

python main.py

脚本将依次执行两个预设的研究主题，一个旨在触发 RAG 路径，另一个旨在触发 Web 搜索路径，你将能清晰地看到控制台输出的每一步执行过程和路由决策。

你可以自由修改 main.py 文件中的 topic_rag 和 topic_web 变量来测试你自己的研究问题。

本项目已内置 API 服务（基于 FastAPI）与容器化配置，支持本地或服务器自托管。

1. 准备环境变量（在项目根目录创建 .env 文件）：

   SILICONFLOW_API_KEY="你的密钥"

2. 安装依赖并构建向量库：

   pip install -r requirements.txt
   python ingest.py

3. 启动 API：

   uvicorn server:app --host 0.0.0.0 --port 8000

4. 健康检查与调用：

   • 健康检查: GET http://localhost:8000/health
   • 运行工作流: POST http://localhost:8000/run，请求体：

   { "topic": "CureGPT模型是什么？" }

1. 准备 .env（与上面相同，至少包含 SILICONFLOW_API_KEY）。

2. 首次构建镜像并生成向量库（将宿主机 documents/ 挂载到容器内，只读；vector_store/ 持久化）：

   docker compose build
   docker compose run --rm langgraph python ingest.py

3. 启动服务：

   docker compose up -d

4. 访问 API：

   • 健康检查: GET http://localhost:8000/health
   • 执行请求: POST http://localhost:8000/run，请求体同上。

5. 更新文档后需要重新构建向量库：

   docker compose run --rm langgraph python ingest.py

• documents/: 本地知识库源文件（容器内只读挂载）。
• vector_store/: Chroma 向量数据库（容器卷持久化）。

• GET /health: 健康检查；若 SILICONFLOW_API_KEY 未配置，会返回 500。
• POST /run: 传入 { "topic": "..." }；返回字段包含：
  • topic: 请求主题
  • events: 节点事件流水，便于调试观察执行过程
  • report: 生成的最终报告

• 将 SILICONFLOW_API_KEY 作为环境变量注入，不要硬编码在镜像内。
• 使用反向代理（如 Nginx/Caddy）暴露 8000 端口并启用 HTTPS。
• 监控容器健康检查，必要时配置重启策略（restart: unless-stopped）。

• main.py: 项目的启动器，定义研究主题并调用工作流。
• ingest.py: 一次性脚本，用于将你的私有文档处理成一个可供检索的 RAG 知识库。
• graph.py: 项目的核心。在这里，我们定义了 ResearchState、所有的工作节点（Planner, Router, Retriever等）以及它们之间的条件连接关系（Conditional Edges）。
• retrievers.py: 封装和管理数据源。它提供了访问 Web 搜索和本地 RAG 知识库的统一接口。
• config.py: 负责从 .env 文件加载 API 密钥等配置，实现配置与代码分离。
• documents/: 你的私有知识源。
• vector_store/: 持久化存储的向量数据库，由 ingest.py 生成。