# langchain-study

**Repository Path**: haodong-liu/langchain-study

## Basic Information

- **Project Name**: langchain-study
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: LGPL-2.1
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-22
- **Last Updated**: 2026-07-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG 智能知识库问答系统

基于 **LangChain + FastAPI + React** 的全栈 RAG 应用学习项目，从零构建一个支持**文档入库、向量检索、流式问答、引用溯源、多轮对话**的智能知识库系统。

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Python](https://img.shields.io/badge/python-3.11-blue.svg)
![React](https://img.shields.io/badge/react-19-61dafb.svg)
![FastAPI](https://img.shields.io/badge/fastapi-0.115-009688.svg)

## ✨ 核心功能

### 📚 文档管理
- 拖拽上传 PDF / Markdown / TXT / Word
- **三种分片模式**：自动（500/50）/ 手动（自定义 chunk_size & overlap）/ 重新分片
- 异步入库，状态实时轮询
- 向量库 Chroma 持久化 + SQLite 元数据

### 💬 智能问答
- **流式输出**：SSE 打字机效果
- **Markdown 实时渲染**：代码块高亮 + 复制按钮、表格、列表
- **引用溯源**：AI 回答下方可展开查看检索到的文档片段
- **多轮对话**：自动指代消解（Query Rewrite）
- **三档应答**：知识库有 → 基于资料 / 知识库无 + 通用问题 → 通用回答 / 业务问题 → 引导上传

### 🗂 会话管理
- 左侧会话列表（新建/切换/删除）
- 消息持久化到 SQLite，刷新不丢失
- 首条消息自动生成会话标题

### 🎨 前端体验
- 气泡式聊天 UI（用户右蓝 / AI 左白 + 头像）
- 快捷问题建议
- 打字指示器三点动画
- 代码块悬浮复制按钮
- 自动滚动 + 滚动条美化

## 🏗 技术栈

### 后端
| 技术 | 用途 |
|------|------|
| **FastAPI** | Web 框架（异步、自动 Swagger 文档） |
| **LangChain** | 文档加载、文本切分、向量检索 |
| **Chroma** | 向量数据库（本地持久化） |
| **SQLAlchemy** | ORM（会话/文档元数据） |
| **OpenAI SDK** | 调用 OpenAI 兼容协议的 LLM / Embedding |
| **Pydantic Settings** | 环境变量管理 |

### 前端
| 技术 | 用途 |
|------|------|
| **Vite + React 19 + TS** | 构建 + 框架 |
| **Ant Design 6** | UI 组件库 |
| **React Router 7** | 路由 |
| **axios** | HTTP 客户端（拦截器 + 流式） |
| **react-markdown + remark-gfm** | Markdown 渲染 |
| **react-syntax-highlighter (Prism)** | 代码高亮 |

## 📁 项目结构

```
langchain-demo/
├── RAG学习路线.md             # 8 周学习规划
├── RAG实战执行方案.md         # 10 个 Step 详细手册
├── backend/
│   ├── app/
│   │   ├── api/
│   │   │   ├── chat.py            # 问答接口（/chat /chat/stream /chat/rag）
│   │   │   ├── document.py        # 文档管理（上传/列表/删除/重新分片）
│   │   │   └── conversation.py    # 会话 CRUD
│   │   ├── rag/
│   │   │   ├── loader.py          # PDF/MD/TXT/DOCX 加载
│   │   │   ├── splitter.py        # 文本切分（工厂函数）
│   │   │   ├── embedder.py        # Embedding 客户端
│   │   │   ├── store.py           # Chroma 向量库
│   │   │   └── retriever.py       # 检索 + Prompt 组装
│   │   ├── services/
│   │   │   ├── document_service.py
│   │   │   └── conversation_service.py
│   │   ├── models/
│   │   │   ├── document.py        # 文档表
│   │   │   └── conversation.py    # 会话 + 消息表
│   │   ├── db.py                  # 共享 SQLAlchemy engine
│   │   ├── config.py              # pydantic-settings
│   │   └── main.py                # FastAPI 入口
│   ├── data/                      # 运行时数据（向量库/SQLite/上传文件）
│   ├── .env.example               # 环境变量模板
│   └── requirements.txt
└── frontend/
    ├── src/
    │   ├── api/
    │   │   ├── client.ts          # axios 实例（拦截器）
    │   │   ├── chat.ts            # 流式问答（chatStream / chatRAGStream）
    │   │   ├── document.ts        # 文档管理 API
    │   │   └── conversation.ts    # 会话 API
    │   ├── components/
    │   │   └── Markdown.tsx       # MD 渲染 + 代码高亮 + 复制按钮
    │   ├── pages/
    │   │   ├── Chat/              # 聊天页（气泡 UI + 引用面板 + 会话侧栏）
    │   │   └── Documents/         # 文档管理页（拖拽上传 + 分片设置）
    │   ├── App.tsx                # 路由 + 侧边菜单
    │   └── main.tsx
    ├── package.json
    └── vite.config.ts             # 代理 /api → :8000
```

## 🚀 快速开始

### 1. 环境要求
- **Conda**（推荐 Miniconda）或 Python 3.11+
- **Node.js** 18+
- **pnpm**（`npm i -g pnpm`）

### 2. 后端启动

```bash
# 创建 conda 环境
conda create -n rag python=3.11 -y
conda activate rag

# 安装依赖
cd backend
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑 .env，填入你的 LLM 和 Embedding 配置

# 启动服务（默认 8000 端口）
uvicorn app.main:app --reload
```

访问 http://localhost:8000/docs 查看 Swagger API 文档。

### 3. 前端启动

```bash
cd frontend
pnpm install
pnpm dev
```

访问 http://localhost:5173 打开应用。

### 4. 环境变量说明（`.env`）

```bash
# LLM 配置（OpenAI 兼容协议）
LLM_BASE_URL=https://api.openai.com/v1        # 或自建 vLLM/Ollama
LLM_API_KEY=sk-xxx
LLM_MODEL=gpt-4o-mini

# Embedding 配置（同样兼容 OpenAI 协议）
EMBEDDING_BASE_URL=https://api.siliconflow.cn/v1
EMBEDDING_API_KEY=sk-xxx
EMBEDDING_MODEL=BAAI/bge-m3

# 向量库（默认 Chroma 本地持久化）
VECTOR_STORE_TYPE=chroma
VECTOR_STORE_PATH=./data/vectorstore
```

## 🎯 使用流程

```
1. 上传文档 → 文档管理页拖拽文件
2. 选择分片模式（自动/手动）
3. 等待状态变 "已就绪"
4. 切到智能问答页提问
5. AI 流式回答 + 底部展示引用来源
6. 开启新会话 / 切换历史会话
```

## 🔬 学习路径

本项目按 `RAG实战执行方案.md` 中的 **10 个 Step** 逐步构建，每个 Step 都有：
- 明确的验收标准
- 核心代码示例
- 关键学习点

| Step | 主题 | 产出 |
|------|------|------|
| 0 | 环境准备 | conda + LLM 连通 |
| 1 | 最小 LLM 对话 | FastAPI + React 聊天 |
| 2 | 流式输出 | SSE 打字机效果 |
| 2.5 | Markdown 动态渲染 | 代码高亮 + 表格 |
| 3 | 文档入库 | 上传 + 切分 + 向量库 |
| 3.5 | 分片策略 | 自动/手动/重新分片 |
| 4 | 基础 RAG 问答 | 检索 + 引用溯源 |
| 5 | 对话历史 | 多轮 + Query Rewrite + 持久化 |

后续可继续实现：
- **Step 6** 检索优化（Rerank / 混合检索 / HyDE）
- **Step 7** 向量库迁移 Milvus
- **Step 8** 评估体系（Ragas）
- **Step 9** 工程化（鉴权/缓存/异步任务）
- **Step 10** Docker 部署

## 📸 界面预览

- **智能问答**：气泡式聊天，AI 回答下方可展开引用
- **文档管理**：拖拽上传，列表显示分片参数和状态
- **会话管理**：左侧列表，支持新建/切换/删除

## 🛠 开发指南

### 后端开发
```bash
# 热重载启动
uvicorn app.main:app --reload --port 8000

# 运行测试脚本（验证 LLM / Embedding 连通性）
python test_llm.py
python test_embedding.py
python test_history.py
```

### 前端开发
```bash
pnpm dev          # 启动 dev server（5173 端口）
pnpm build        # 构建生产版本
pnpm lint         # 代码检查（oxlint）
```

### 数据库管理
- **SQLite**：`backend/data/docs.db`（文档元数据 + 会话 + 消息）
- **Chroma**：`backend/data/vectorstore/`（向量持久化目录）
- **清空数据**：删除 `backend/data/` 目录，重启服务

## 🧪 验证功能

### 测试 RAG 问答
```bash
curl -X POST http://localhost:8000/api/chat/rag \
  -H "Content-Type: application/json" \
  -d '{"message": "什么是 RAG？", "top_k": 3}'
```

### 测试文档上传
```bash
curl -X POST http://localhost:8000/api/documents/upload \
  -F "file=@test.pdf" \
  -F "split_mode=auto"
```

### 测试多轮对话（指代消解）
```python
import requests
# 第一轮
r1 = requests.post('http://localhost:8000/api/chat/rag', json={'message': '什么是 RAG？'})
conv_id = r1.json()['conversation_id']

# 第二轮（"它"指代 RAG）
r2 = requests.post('http://localhost:8000/api/chat/rag', json={
    'message': '它的核心流程是什么？',
    'conversation_id': conv_id
})
```

## 📖 相关文档

- **学习路线**：`RAG学习路线.md`（8 周 7 阶段规划）
- **执行方案**：`RAG实战执行方案.md`（10 Step 详细手册，含代码示例）
- **API 文档**：启动后访问 http://localhost:8000/docs

## 🤝 贡献

这是个人学习项目，欢迎参考代码。如果发现 bug 或有改进建议，欢迎提 Issue。

## 📄 License

MIT

## 🙏 致谢

- [LangChain](https://python.langchain.com) - LLM 应用开发框架
- [FastAPI](https://fastapi.tiangolo.com) - 现代 Python Web 框架
- [Chroma](https://www.trychroma.com) - 开源向量数据库
- [Ant Design](https://ant.design) - 企业级 UI 组件库