290 lines
6.7 KiB
Markdown
290 lines
6.7 KiB
Markdown
# LangChain Learning Kit
|
||
|
||
> 企业级 LangChain 学习平台 - 提供完整的后端 API 系统，展示 LangChain 核心功能
|
||
|
||
## 项目简介
|
||
|
||
LangChain Learning Kit 是一个教学性质但架构接近生产环境的学习平台，帮助开发者理解和掌握 LangChain 的关键功能：
|
||
|
||
- 🤖 **模型管理**: 支持多种 LLM 和 Embedding 模型配置与切换
|
||
- 📚 **知识库管理**: 基于 FAISS 的向量存储和文档检索
|
||
- 💬 **多轮对话**: 支持会话状态和历史管理
|
||
- 🔧 **智能体编排**: Agent 与工具集成 (Retriever, Calculator)
|
||
- ⚡ **异步处理**: 文档分块、嵌入计算等异步任务
|
||
|
||
## 技术栈
|
||
|
||
- **后端框架**: FastAPI
|
||
- **数据库**: MySQL 8.0 + SQLAlchemy 2.0
|
||
- **LangChain**: langchain + langchain-openai
|
||
- **向量存储**: FAISS (本地)
|
||
- **容器化**: Docker + Docker Compose
|
||
- **测试**: pytest
|
||
|
||
## 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- Python 3.11+
|
||
- MySQL 8.0+
|
||
- OpenAI API Key
|
||
|
||
### 1. 克隆项目
|
||
|
||
```bash
|
||
git clone http://124.221.136.193:3000/python-test/langchain-learning-kit.git
|
||
cd langchain-learning-kit
|
||
```
|
||
|
||
### 2. 安装依赖
|
||
|
||
#### 方式 A: 使用 Conda (推荐 - 适合 Anaconda 用户)
|
||
|
||
```bash
|
||
# 自动化安装（Windows）
|
||
setup_conda_env.bat
|
||
|
||
# 或手动创建环境
|
||
conda env create -f environment.yml
|
||
conda activate langchain-learning-kit
|
||
```
|
||
|
||
详细说明请查看 [CONDA_SETUP.md](CONDA_SETUP.md)
|
||
|
||
#### 方式 B: 使用 venv (传统方式)
|
||
|
||
```bash
|
||
# 创建虚拟环境
|
||
python -m venv venv
|
||
|
||
# 激活虚拟环境
|
||
# Windows
|
||
venv\Scripts\activate
|
||
# Linux/Mac
|
||
source venv/bin/activate
|
||
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 3. 配置环境变量
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# 编辑 .env 文件，填入你的配置
|
||
```
|
||
|
||
必需的环境变量：
|
||
- `DATABASE_URL`: MySQL 连接字符串
|
||
- `OPENAI_API_KEY`: OpenAI API Key
|
||
|
||
### 4. 初始化数据库
|
||
|
||
```bash
|
||
# 方式 A: 使用初始化脚本
|
||
python scripts/init_db.py
|
||
|
||
# 方式 B: 使用 Alembic 迁移
|
||
cd app/db
|
||
alembic upgrade head
|
||
```
|
||
|
||
### 5. 启动服务
|
||
|
||
```bash
|
||
# 从项目根目录启动
|
||
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
服务启动后访问:
|
||
- API 文档: http://localhost:8000/docs
|
||
- 健康检查: http://localhost:8000/health
|
||
|
||
## 使用 Docker
|
||
|
||
```bash
|
||
# 启动所有服务 (MySQL + API)
|
||
docker-compose up -d
|
||
|
||
# 查看日志
|
||
docker-compose logs -f api
|
||
|
||
# 停止服务
|
||
docker-compose down
|
||
|
||
# 开发模式 (代码热重载)
|
||
docker-compose --profile dev up api-dev
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
langchain-learning-kit/
|
||
├── app/
|
||
│ ├── main.py # FastAPI 入口
|
||
│ ├── config.py # 配置管理
|
||
│ ├── api/ # API 路由
|
||
│ │ ├── models.py # 模型管理 API
|
||
│ │ ├── kb.py # 知识库 API
|
||
│ │ ├── conv.py # 对话 API
|
||
│ │ └── agent.py # Agent API
|
||
│ ├── services/ # 业务逻辑层
|
||
│ │ ├── model_manager.py
|
||
│ │ ├── kb_manager.py
|
||
│ │ ├── conv_manager.py
|
||
│ │ ├── agent_orchestrator.py
|
||
│ │ └── job_manager.py
|
||
│ ├── db/ # 数据库层
|
||
│ │ ├── models.py # SQLAlchemy 模型
|
||
│ │ ├── session.py # 数据库连接
|
||
│ │ └── alembic/ # 迁移脚本
|
||
│ ├── tools/ # LangChain 工具
|
||
│ │ ├── retriever.py
|
||
│ │ └── calculator.py
|
||
│ └── utils/ # 工具函数
|
||
│ ├── text_splitter.py
|
||
│ ├── faiss_helper.py
|
||
│ ├── logger.py
|
||
│ └── exceptions.py
|
||
├── tests/ # 测试
|
||
│ ├── conftest.py # pytest 配置
|
||
│ └── test_api_health.py
|
||
├── docs/ # 文档
|
||
│ ├── architecture.md # 架构设计
|
||
│ └── api.md # API 文档
|
||
├── scripts/ # 脚本
|
||
│ └── init_db.py # 数据库初始化
|
||
├── Dockerfile # Docker 镜像
|
||
├── docker-compose.yml # 容器编排
|
||
├── pytest.ini # 测试配置
|
||
├── requirements.txt # Python 依赖
|
||
├── environment.yml # Conda 环境
|
||
└── .env.example # 环境变量模板
|
||
```
|
||
|
||
## API 使用示例
|
||
|
||
### 创建模型配置
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/v1/models" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"name": "gpt-4",
|
||
"type": "llm",
|
||
"config": {
|
||
"model_name": "gpt-4",
|
||
"temperature": 0.7
|
||
},
|
||
"is_default": true
|
||
}'
|
||
```
|
||
|
||
### 创建知识库
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/v1/kb" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"name": "my_kb",
|
||
"description": "My first knowledge base"
|
||
}'
|
||
```
|
||
|
||
### 摄取文档
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/v1/kb/1/ingest" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"documents": [
|
||
{
|
||
"title": "LangChain Introduction",
|
||
"content": "LangChain is a framework for developing applications powered by language models...",
|
||
"source": "manual"
|
||
}
|
||
]
|
||
}'
|
||
```
|
||
|
||
### 查询知识库
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/v1/kb/1/query" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"query": "What is LangChain?",
|
||
"k": 5
|
||
}'
|
||
```
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
pytest
|
||
|
||
# 运行特定测试
|
||
pytest tests/unit/test_model_manager.py
|
||
|
||
# 生成覆盖率报告
|
||
pytest --cov=app --cov-report=html
|
||
```
|
||
|
||
## 文档
|
||
|
||
- [架构设计](docs/architecture.md) - 系统架构、数据流、设计决策
|
||
- [API 文档](docs/api.md) - REST API 详细文档
|
||
- [交互式 API 文档](http://localhost:8000/docs) - Swagger UI (启动服务后访问)
|
||
|
||
## 核心功能
|
||
|
||
### 1. 模型管理
|
||
|
||
支持多种 LLM 和 Embedding 模型的配置、切换和版本管理。
|
||
|
||
### 2. 知识库 (RAG)
|
||
|
||
- 文档上传和分块
|
||
- 向量嵌入计算
|
||
- FAISS 向量检索
|
||
- 元数据管理
|
||
|
||
### 3. 多轮对话
|
||
|
||
- 会话状态管理
|
||
- 对话历史存储
|
||
- RAG 上下文注入
|
||
|
||
### 4. 智能体 (Agent)
|
||
|
||
- Retriever Tool: 知识库检索
|
||
- Calculator Tool: 数学计算
|
||
- 可扩展工具系统
|
||
|
||
## 开发指南
|
||
|
||
### 添加新的 LLM 提供商
|
||
|
||
1. 在 `app/services/model_manager.py` 中添加提供商类
|
||
2. 实现 `get_llm()` 方法
|
||
3. 更新配置验证逻辑
|
||
|
||
### 添加新的 Agent 工具
|
||
|
||
1. 在 `app/tools/` 创建工具文件
|
||
2. 继承 LangChain Tool 基类
|
||
3. 在 `AgentOrchestrator` 中注册工具
|
||
|
||
## 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
## 联系方式
|
||
|
||
如有问题，请提交 Issue。
|