# langchain-study

**Repository Path**: mkee/langchain-study

## Basic Information

- **Project Name**: langchain-study
- **Description**: LangChain + LangGraph 开发本地知识库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-03
- **Last Updated**: 2026-03-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LangChain RAG 系统

基于 LangGraph + LangChain 集成阿里云通义千问（Qwen）的检索增强生成（RAG）系统，向量数据库采用 Chroma。

## 功能特性

- 创建或加载本地知识库
- 用户从页面录入文档内容（支持文本和分类）
- 文档分块处理
- 添加新文档到向量数据库
- 相似度检索
- 基于检索结果生成回答（RAG 链）
- 纯检索链（无需 LLM）
- 验证本地知识库（查看文档列表和详情）
- 删除知识库中的文档
- 本地调试追踪器（查看工作流执行过程）
- 多轮检索（反思机制优化查询）

## 技术栈

- **LLM**: 阿里云通义千问 (Qwen)
- **工作流引擎**: LangGraph
- **向量数据库**: Chroma
- **框架**: LangChain, FastAPI
- **前端**: HTML + Jinja2 模板

## 环境配置

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置 API 密钥

**推荐方式：使用 .env 文件**（更安全，不会提交到 Git）

1. 复制环境变量模板
   ```bash
   copy env_template.txt .env
   ```

2. 编辑 `.env` 文件，填入真实的 API 密钥：
   ```
   DASHSCOPE_API_KEY=your-api-key-here
   ```

获取 API 密钥：https://dashscope.console.aliyun.com/

### 3. 启动服务

```bash
python main.py
```

或使用 uvicorn：

```bash
uvicorn app:app --host 0.0.0.0 --port 8000 --reload
```

服务启动后访问：http://localhost:8000

## 项目结构

```
.
├── app.py                      # FastAPI 应用入口
├── config.py                   # 配置文件
├── main.py                     # 服务启动入口
├── core/                       # 核心模块
│   ├── __init__.py
│   ├── clients.py              # LLM 和向量库客户端
│   └── prompt_manager.py      # 提示词管理器
├── services/                   # 业务服务
│   ├── __init__.py
│   ├── rag_service.py          # RAG 工作流服务
│   ├── document_service.py    # 文档管理服务
│   ├── debug_tracer.py        # 本地调试追踪器
│   └── debug_run.py           # 调试运行脚本
├── api/                        # API 路由
│   ├── __init__.py
│   └── routes.py
├── templates/                  # HTML 模板
│   ├── index.html
│   ├── document_detail.html
│   └── prompts/
│       └── prompts.yaml       # 提示词模板配置
├── .env                       # 环境变量（API 密钥）
├── env_template.txt           # 环境变量模板
├── requirements.txt           # 依赖列表
└── .gitignore                 # Git 忽略配置
```

## 配置说明

在 `.env` 文件中可以配置以下选项：

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `DASHSCOPE_API_KEY` | 阿里云通义千问 API 密钥 | - |
| `CHUNK_SIZE` | 文档分块大小 | 1000 |
| `CHUNK_OVERLAP` | 文档分块重叠大小 | 200 |
| `DEFAULT_RETRIEVAL_K` | 默认检索数量 | 4 |
| `VECTORSTORE_PATH` | 向量数据库存储路径 | chroma_db |
| `HOST` | 服务器地址 | 0.0.0.0 |
| `PORT` | 服务器端口 | 8000 |
| `DEBUG` | 开发模式（禁用字节码缓存） | true |

## 使用指南

### 1. 添加文档

在页面 "添加文档到知识库" 部分：
- 输入文档内容
- 输入分类标签
- 点击 "添加文档"

### 2. 查询知识库

在页面 "知识库查询" 部分：
- 输入查询问题
- 选择查询方式：
  - **RAG 链**: 基于检索结果生成回答（使用 LangGraph 工作流）
  - **纯检索链**: 仅返回检索结果
- 点击 "查询"

### 3. 验证知识库

在页面 "验证知识库" 部分：
- 点击 "验证知识库状态"，查看知识库中的文档数量
- 查看文档列表，包含每个文档的预览、分类和 ID
- 点击 "查看详情" 按钮，查看文档的完整内容
- 点击 "删除" 按钮，删除指定文档

### 4. 本地调试（可选）

项目提供了本地调试追踪器，用于查看 LangGraph 工作流的执行过程：

```python
from services.rag_service import get_rag_graph
from services.debug_tracer import LocalDebugTracer

# 创建调试追踪器
tracer = LocalDebugTracer(
    verbose=True,           # 显示详细输入输出
    log_file="debug.log",  # 保存日志到文件
    show_llm_inputs=True,  # 显示 LLM 输入
    show_llm_outputs=True  # 显示 LLM 输出
)

# 获取带调试追踪器的工作流
graph = get_rag_graph(tracer)

# 执行工作流
result = graph.invoke({
    "question": "你的问题",
    "documents": [],
    "context": "",
    "answer": "",
    "retrieval_count": 0,
    "max_retrievals": 2
})

# 打印执行摘要
tracer.print_summary()
```

或使用快捷脚本：

```bash
python -m services.debug_run
```

调试输出示例：
```
15:32:10.123 [INFO] [START] 开始执行节点: 检索文档
15:32:10.456 [INFO] [DONE] 节点完成: 检索文档 (耗时: 0.335s)
...
==================================================
📊 执行摘要
==================================================
执行节点数: 4
总耗时: 2.456s

各节点耗时:
  - 检索文档: 0.335s
  - 格式化文档: 0.012s
  - 反思: 1.234s
  - 生成答案: 0.875s
==================================================
```

## RAG 工作流说明

项目使用 LangGraph 构建 RAG 工作流，流程如下：

```
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  检索文档   │───▶│ 格式化文档  │───▶│    反思     │
└─────────────┘    └─────────────┘    └─────────────┘
       ▲                                     │
       │           ┌─────────────┐           │
       └───────────┤ should_continue ├◀──────┘
                   └─────────────┘
                        │
                   ┌────┴────┐
                   ▼         ▼
              "生成答案"   "反思"
                   │         │
                   ▼         ▼
              ┌─────────────┐
              │   生成答案   │
              └─────────────┘
```

- **检索文档**: 从向量数据库检索相关文档
- **格式化文档**: 将检索到的文档格式化为上下文
- **反思**: 反思检索结果，决定是否需要继续检索
- **should_continue**: 条件判断，控制工作流走向
- **生成答案**: 基于最终上下文生成回答

### 多轮检索机制

1. 第一轮：检索 → 格式化 → 反思 → 判断
2. 反思后如果认为需要更多文档 → 回到检索
3. 否则 → 生成答案

通过 LLM 分析检索结果，如果认为检索不够充分，会自动改进搜索关键词进行新一轮检索。

## 提示词模板

提示词模板保存在 `templates/prompts/prompts.yaml` 文件中：

- `rag`: RAG 回答生成提示词
- `reflect`: 反思检索结果提示词

可以在不修改代码的情况下调整提示词内容。

## 注意事项

- `.env` 文件包含敏感 API 密钥，已加入 `.gitignore`，请勿提交到 Git
- 向量数据库存储在 `chroma_db` 目录（可通过配置修改）
- 确保 API 密钥有足够的调用额度
- 文档会被自动分块存储，每个分块大小为 1000 字符（可通过配置修改）
- 开发模式下禁用 Python 字节码缓存（`__pycache__`），方便调试