langchain-learning-kit/README.md

# 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。