# x-langchain

**Repository Path**: chain-engine/x-langchain

## Basic Information

- **Project Name**: x-langchain
- **Description**: 一个完整的 LangChain（LLM应用开发框架） 学习与实践项目
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-05
- **Last Updated**: 2026-03-22

## Categories & Tags

**Categories**: ai

**Tags**: None

## README

# x-langchain

> LangChain 学习与实践项目

`x-langchain` 是一个完整的 LangChain（LLM应用开发框架） 学习与实践项目，旨在帮助开发者系统学习和掌握 LangChain 框架的核心概念与应用方法。本项目通过实际案例展示如何使用 LangChain 构建大语言模型应用，包括模型集成、工具调用、上下文管理等关键功能，为 LangChain 初学者和进阶开发者提供实践参考。

---

### 什么是 LangChain？

- **官方定义**："LangChain is a framework for developing applications powered by large language models"
- **Gartner 描述**："LLM application development frameworks like LangChain"

简单来说，`LangChain` 是一个帮助开发者快速构建基于大语言模型（LLM）应用的开发框架。

---

## 🔄 工作流程

以下是 Agent 调用工具的完整时序图：

```mermaid
sequenceDiagram
    participant U as 用户
    participant A as Agent
    participant M as 模型(Qwen)
    participant T as 工具(get_weather)

    U->>A: "上海的天气"
    A->>M: 发送用户消息 + 工具列表
    M->>M: 判断需调用工具
    M->>A: 返回 ToolCall: {name: "get_weather", args: {city: "上海"}}
    A->>T: 执行 get_weather("上海")
    T->>A: 返回 "上海多云 25°C"
    A->>M: 发送 ToolResponse
    M->>M: 生成自然语言回答
    M->>A: 返回最终回答
    A->>U: "上海今天多云，气温25°C"
```

---

## 📌 目录

- [核心特性](#-核心特性)
- [快速开始](#-快速开始)
- [项目结构](#-项目结构)
- [插件化工具系统](#-插件化工具系统)
- [配置说明](#-配置说明)
- [使用方法](#-使用方法)
- [测试与质量保障](#-测试与质量保障)
- [许可证](#-许可证)
- [支持与贡献](#-支持与贡献)

---

## ✨ 核心特性

- **多模型兼容**：支持 DeepSeek、豆包、阿里云通义千问等主流 LLM 后端
- **工具调用（Function Calling）**：通过声明式接口集成外部 API 与业务系统
- **TextToSQL 功能**：支持自然语言到 SQL 的转换，包括问题重写、Schema 解析、SQL 生成、验证和执行
- **上下文管理**：内置对话历史管理，支持连续对话
- **安全合规**：
  - API 密钥管理（从环境变量加载，避免硬编码）
  - 输入/输出内容过滤
- **可观测性**：集成结构化日志系统，便于监控和调试
- **现代化架构**：基于 LangChain 构建，支持类型安全与模块化设计

---

## 🚀 快速开始

### 环境要求

- Python 3.11 或更高版本
- 推荐使用 [`uv`](https://github.com/astral-sh/uv) 作为包管理器（亦兼容 `pip`）

### 安装与运行

```bash
# 克隆项目
git clone https://gitee.com/chain-engine/x-langchain.git
cd x-langchain

# 安装依赖（推荐使用 uv）
uv sync

# 配置环境变量
cp .env.example .env
# 编辑 .env，填入必要的 API 密钥和数据库配置

# 运行智能助手（进入交互式对话模式）
# 使用默认模型（DeepSeek）
uv run main.py

# 或通过环境变量指定模型
MODEL_NAME=deepseek uv run main.py
MODEL_NAME=doubao uv run main.py
MODEL_NAME=tongyi uv run main.py
```

---

## 📁 项目结构

```
x-langchain/
├── config/             # 配置管理模块
│   ├── __init__.py
│   └── settings.py     # 配置类，从环境变量加载配置
├── models/             # 模型管理模块
│   ├── __init__.py
│   └── model_factory.py  # 模型工厂，用于创建不同的模型实例
├── tools/              # 工具模块（插件化系统）
│   ├── __init__.py     # 工具模块入口
│   ├── registry.py      # 工具注册表和装饰器
│   ├── weather_tool.py  # 天气查询工具
│   ├── calendar_tool.py  # 日历查询工具
│   ├── web_search_tool.py  # 网络搜索工具
│   └── text_to_sql/     # TextToSQL 相关工具
│       ├── __init__.py
│       ├── question_rewrite_tool.py  # 问题重写工具
│       ├── get_schema_tool.py  # 获取数据库结构工具
│       ├── generate_sql_tool.py  # 生成 SQL 工具
│       ├── validate_sql_tool.py  # 验证 SQL 工具
│       ├── execute_sql_tool.py  # 执行 SQL 工具
│       └── convert_to_natural_language_tool.py  # 结果转换工具
├── clients/            # 客户端模块
│   ├── __init__.py
│   └── db/             # 数据库客户端
│       ├── __init__.py
│       └── client.py    # 数据库操作客户端
├── core/               # 核心模块
│   ├── __init__.py
│   └── logger.py       # 日志系统
├── agents/             # Agent 模块
│   ├── __init__.py
│   └── agent_factory.py  # Agent 工厂，用于创建 Agent 实例
├── tests/              # 测试模块
│   ├── __init__.py
│   ├── test_settings.py      # 配置管理测试
│   ├── test_weather_tool.py  # 天气工具测试
│   └── test_model_factory.py  # 模型工厂测试
├── .env                # 环境变量配置文件
├── .env.example        # 环境变量配置示例
├── main.py             # 项目主入口，实现命令行接口
├── pyproject.toml      # 项目元数据和依赖管理
├── setup.py            # 项目构建配置
├── requirements.txt    # 依赖列表
└── README.md           # 项目文档
```

---

## 🔌 插件化工具系统

x-langchain 提供了插件化的工具管理系统，开发者可以轻松添加新工具，无需修改核心代码。

### 核心特性

- **自动注册**: 使用 `@register_tool` 装饰器自动注册工具
- **工具发现**: 自动扫描 `tools/` 目录，发现新工具
- **类别管理**: 按类别组织工具，便于管理和过滤
- **向后兼容**: 完全兼容现有工具代码

### 快速开始

创建新工具只需三步：

```python
# 1. 在 tools/ 目录下创建新文件
# tools/my_tool.py

# 2. 使用装饰器注册工具
from tools.registry import register_tool

@register_tool(name="my_tool", category="custom", description="我的工具")
class MyTool:
    def __init__(self):
        self.name = "my_tool"
        self.description = "我的自定义工具"

    def run(self, param: str) -> str:
        return f"处理参数: {param}"

# 3. 完成！工具会在模块导入时自动注册
```

### 工具查询

```python
from tools import ToolRegistry

# 检查工具是否存在
if ToolRegistry.contains("my_tool"):
    tool = ToolRegistry.get("my_tool")

# 获取所有工具
all_tools = ToolRegistry.get_all()

# 按类别获取工具
custom_tools = ToolRegistry.get_all(category="custom")

# 获取统计信息
stats = ToolRegistry.get_stats()
print(f"总工具数: {stats['total_tools']}")
```

### 文档

详细的插件开发指南请参考：[插件开发指南](docs/插件开发指南.md)

---

## ⚙️ 配置说明

### 环境变量配置

项目使用 `.env` 文件存储配置信息，主要包括以下配置项：

#### DeepSeek 配置

```env
# DeepSeek API
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DEEPSEEK_API_BASE=https://api.deepseek.com/v1
DEEPSEEK_MODEL_NAME=deepseek-chat
```

#### 豆包配置

```env
# 豆包 API
DOUBAO_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
DOUBAO_API_BASE=https://ark.cn-beijing.volces.com/api/v3
DOUBAO_MODEL_NAME=ep-xxxxxxxxxxxxxx
```

#### 阿里云百炼配置

```env
# 阿里云百炼 API
ALIYUN_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ALIYUN_MODEL_NAME=qwen-plus
```

#### 数据库配置（用于 TextToSQL）

```env
# 数据库配置
DB_HOST=192.168.111.234
DB_PORT=3306
DB_USER=root
DB_PASSWORD=123456
DB_NAME=yeyushilai
DB_URL=mysql+pymysql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}
```

#### 通用配置

```env
# 通用配置
TEMPERATURE=0.0
DEBUG=True
STRUCTURED=False
```

---

## 📖 使用方法

### 交互式对话模式

启动程序后，会进入交互式对话模式：

```bash
$ uv run main.py

==================================================
欢迎使用智能助手！输入 'exit'、'quit' 或 '退出' 结束对话
==================================================

你: 上海天气怎么样？

2026-03-05 10:00:00,123 - INFO - 查询结果:
上海今天多云，气温 18°C，东风 3级，湿度 65%，空气质量良好。

你: 帮我查询数据库中的用户数量

2026-03-05 10:01:00,456 - INFO - 查询结果:
根据数据库查询，当前系统中有 150 个用户。

你: exit

感谢使用，再见！
```

### 模型选择

通过环境变量 `MODEL_NAME` 指定使用的模型：

- `deepseek`: 使用 DeepSeek 模型（默认）
- `doubao`: 使用豆包模型
- `tongyi`: 使用阿里云通义千问模型

例如：
```bash
# 使用 DeepSeek（默认）
uv run main.py

# 使用豆包
MODEL_NAME=doubao uv run main.py

# 使用通义千问
MODEL_NAME=tongyi uv run main.py
```

---

## 🧪 测试与质量保障

### 运行测试

项目提供了完整的测试套件，用于确保代码质量：

```bash
# 运行所有测试
uv run python -m pytest

# 运行特定测试模块
uv run python -m pytest tests/test_settings.py -v
uv run python -m pytest tests/test_weather_tool.py -v
uv run python -m pytest tests/test_model_factory.py -v
```

### 代码质量

- **类型检查**：使用 Python 的类型注解确保类型安全
- **错误处理**：添加了详细的错误处理和容错机制
- **日志系统**：集成了统一的日志系统，便于监控和调试
- **模块化设计**：采用模块化设计，提高代码的可维护性和可扩展性

---

## 📄 许可证

本项目采用 MIT 许可证，详见 [LICENSE](LICENSE) 文件。

---

## 🤝 支持与贡献

### 支持

如果您在使用过程中遇到问题，请通过以下方式获取支持：

- 查看 [LangChain 官方文档](https://python.langchain.com/docs/get_started/introduction)
- 查看 [项目文档](README.md)
- 提交 [GitHub Issue](https://gitee.com/chain-engine/x-langchain/issues)

### 贡献

我们欢迎社区贡献，包括但不限于：

- 修复 bug
- 添加新功能
- 改进文档
- 优化性能

请通过 GitHub Pull Request 提交您的贡献。

---

## 参考文档

- [LangChain 中文文档](https://langchain-doc.cn/v1/python/langchain/overview.html)
- [DeepSeek 官方文档](https://platform.deepseek.com/docs/api)
- [豆包官方文档](https://www.doubao.com/)
- [阿里云通义千问官方文档](https://help.aliyun.com/product/1081203.html)