# langchain_study

**Repository Path**: gunhe/langchain_study

## Basic Information

- **Project Name**: langchain_study
- **Description**: langchain_study
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-04
- **Last Updated**: 2026-03-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LangChain 学习项目

这是一个 LangChain 和 LangGraph 的学习实践项目，包含了 RAG（检索增强生成）、Agent、多 LLM 提供商集成等示例代码。

## 项目简介

本项目通过实际代码示例学习和实践：
- 多种 LLM 提供商集成（DeepSeek、通义千问、OneAPI 等）
- RAG（检索增强生成）完整流程
- LangChain Agent 开发
- LangGraph 工作流编排
- 多种文档加载器使用
- 向量数据库集成
- FastAPI RESTful API 服务（兼容 OpenAI 格式）

## 快速开始

### 1. 安装依赖

```bash
pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
pip install -r requirement.txt
```

### 2. 配置环境变量

编辑 `myenv.py`，填入你的 API 密钥：

```python
DASHSCOPE_API_KEY = "your_key_here"   # 阿里云百炼
DEEPSEEK_API_KEY  = "your_key_here"   # DeepSeek
ONEAPI_API_KEY    = "your_key_here"   # OneAPI 网关
ONEAPI_BASE_URL   = "your_url_here"
```

### 3. 运行示例

```bash
# 运行 Agent 快速开始示例
python examples/demo01_quick_start.py

# 运行 RAG 示例
python examples/demo03_rag.py
```

### 4. 启动 API 服务

```bash
# 方式 1: 使用启动脚本
bash scripts/start_api.sh

# 方式 2: 直接运行
python main.py

# 访问 API 文档
# http://localhost:8000/docs
```

### 5. Docker 部署

**构建镜像：**
```bash
docker build -t langchain-study .
```

**运行容器（通过 -e 注入密钥）：**
```bash
docker run -p 8000:8000 \
  -e DEEPSEEK_API_KEY=your_key \
  -e DASHSCOPE_API_KEY=your_key \
  -e ONEAPI_API_KEY=your_key \
  -e ONEAPI_BASE_URL=your_url \
  langchain-study
```

**或使用 .env 文件：**
```bash
# 创建 .env 文件
cat > .env <<EOF
DEEPSEEK_API_KEY=your_key
DASHSCOPE_API_KEY=your_key
ONEAPI_API_KEY=your_key
ONEAPI_BASE_URL=your_url
EOF

docker run -p 8000:8000 --env-file .env langchain-study
```

启动后访问 `http://localhost:8000/docs`

## 项目结构

```
langchain_study/
├── main.py                # FastAPI 主应用入口
├── routes.py              # API 路由（OpenAI 兼容接口）
├── routes_admin.py        # 管理路由
├── models.py              # 请求/响应数据模型
├── services.py            # 业务逻辑层（RAG 服务）
├── stream_handler.py      # 流式响应处理器
├── response_handler.py    # 非流式响应处理器
├── config.py              # 统一配置管理
├── utils.py               # 工具函数
├── myenv.py               # 环境变量管理
├── requirement.txt        # 项目依赖
├── pyproject.toml         # 项目配置
├── common/                # 公共模块
│   ├── __init__.py
│   └── llm_factory.py     # 统一 LLM 工厂（含实例缓存）
├── examples/              # 核心示例代码
│   ├── demo01_quick_start.py      # Agent 快速开始
│   ├── demo01_output_parsers.py   # 输出解析器示例
│   ├── demo02_model.py            # 模型使用示例
│   ├── demo02_model_movie.py      # 模型电影示例
│   ├── demo03_rag.py              # RAG 完整示例
│   ├── demo04_agent.py            # Agent 示例
│   ├── demo11.py                  # 流式输出测试
│   ├── demo11_response_format.py  # 响应格式示例
│   ├── api_client_example.py      # API 客户端示例
│   └── README.md
├── langchain/             # LangChain 专项示例
│   ├── demo_agent.py      # Agent 示例
│   ├── demo_agent.ipynb   # Agent Notebook
│   ├── demo_tools.py      # 工具示例
│   ├── data/              # 示例数据
│   │   └── nke-10k-2023.pdf
│   ├── document_loaders/  # 文档加载器
│   │   ├── demo_pypdf_loader.py
│   │   ├── demo_csv_loader.py
│   │   ├── demo_json_loader.py
│   │   ├── demo_web_base_loader.py
│   │   └── index.md
│   ├── prompts/           # Prompt 工程
│   │   ├── demo02_prompts_ChatPromptTemplate.py
│   │   ├── demo03_prompts.py
│   │   ├── demo07_prompts_fanyi.py
│   │   └── demo08_prompts_runnable.py
│   ├── vectorstores/      # 向量数据库示例
│   │   ├── demo01.py
│   │   ├── demo03_4.py
│   │   ├── demo03_memory.py
│   │   ├── demo03_me.py
│   │   └── demo04_sql_agent.py
│   ├── openal/            # OpenAI 相关
│   │   ├── demo01_http_proxy.py
│   │   ├── demo02_embedding.py
│   │   ├── demo03.py
│   │   └── README.md
│   └── sql/               # SQL Agent 数据
│       └── data.sql
├── scripts/               # 脚本工具
│   ├── start_api.sh               # API 启动脚本
│   ├── start_chatgpt_web.sh       # ChatGPT Web 启动脚本
│   └── create_langgraph_project.sh # LangGraph 项目创建脚本
├── tests/                 # 测试用例
│   ├── test_openai_api.py
│   ├── test_stream_integration.py
│   ├── test_stream_modes.py
│   ├── test_response_integration.py
│   └── README.md
└── docs/                  # 文档
    ├── API_GUIDE.md
    ├── CHERRY_STUDIO_SETUP.md
    ├── FASTAPI_INTEGRATION.md
    ├── STREAM_HANDLER_INTEGRATION.md
    ├── RESPONSE_HANDLER_INTEGRATION.md
    ├── LLM_IMPORT_UNIFICATION.md
    ├── MODELS_CONFIG.md
    ├── MODELS_ENDPOINT.md
    └── ...
```

## API 端点

启动服务后访问 `http://localhost:8000/docs` 查看完整文档。

| 方法 | 路径 | 说明 |
|------|------|------|
| GET  | `/api/v1/health` | 健康检查 |
| GET  | `/api/v1/models` | 获取可用模型列表（OpenAI 格式） |
| POST | `/api/v1/chat` | 聊天对话 |
| POST | `/api/v1/responses` | OpenAI 兼容聊天接口（Cherry Studio 等客户端） |

### Cherry Studio / OpenAI 兼容客户端

`/api/v1/responses` 兼容 OpenAI API 格式，支持流式输出：

```python
import requests

response = requests.post("http://localhost:8000/api/v1/responses", json={
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": False
})
print(response.json())
```

模型名称会自动映射到对应 provider：
- 包含 `deepseek` → DeepSeek
- 包含 `qwen` → 通义千问
- 其他 → 默认 DeepSeek

## LLM 工厂

`common/llm_factory.py` 统一管理 LLM 实例，内置缓存避免重复创建：

```python
from common.llm_factory import get_llm

llm = get_llm("deepseek", model="deepseek-chat", temperature=0.7)
llm = get_llm("qwen", model="qwen-plus")
llm = get_llm("oneapi", model="gpt-4o")
```

## 测试

```bash
# 运行所有测试
pytest tests/

# 运行单个测试
python tests/test_openai_api.py
```

## 文档索引

- [API 使用指南](docs/API_GUIDE.md)
- [Cherry Studio 接入指南](docs/CHERRY_STUDIO_SETUP.md)
- [FastAPI 集成文档](docs/FASTAPI_INTEGRATION.md)
- [流式处理集成](docs/STREAM_HANDLER_INTEGRATION.md)
- [响应处理中间层](docs/RESPONSE_HANDLER_INTEGRATION.md)
- [LLM 导入统一化](docs/LLM_IMPORT_UNIFICATION.md)

## 配置说明

配置参数集中在 `config.py` 中管理：

```python
from config import rag_config, llm_config

print(llm_config.temperature)  # 0.7
print(llm_config.max_tokens)   # 2000
print(rag_config.top_k)        # 5
```

## 学习资源

- [LangChain 官方文档](https://docs.langchain.com/)
- [LangGraph 文档](https://langchain-ai.github.io/langgraph/)
- [阿里云百炼平台](https://bailian.console.aliyun.com/)

## 注意事项

- 不要将 `myenv.py` 中的真实密钥提交到 Git 仓库
- 定期轮换 API 密钥
- 不要在代码中硬编码密钥

## 许可证

MIT License