Tangledup-ai/lang-agent
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update readme

Browse Source
This commit is contained in:
goulustis
2025-11-28 18:33:05 +08:00
parent ccfb66944d
commit 0fa49ffb28
1 changed files with 35 additions and 253 deletions
Download Patch File Download Diff File Expand all files Collapse all files

288
README.md
View File

@@ -1,278 +1,60 @@
# langchain-agent
# Lang Agent Chat API
## 项目概述
这是一个基于FastAPI的聊天API服务，使用OpenAI格式的请求来调用pipeline.invoke方法进行聊天。
这是一个基于LangChain和LangGraph构建的智能代理系统，集成了RAG(检索增强生成)、工具调用和WebSocket通信功能。项目主要用于茶饮场景的智能对话和订单处理，支持多种工具调用和远程MCP(Model Context Protocol)服务器集成。
## 项目结构
```
langchain-agent/
├── lang_agent/ # 核心模块目录
│ ├── base.py # 基础抽象类定义
│ ├── config.py # 配置管理系统
│ ├── pipeline.py # 主流程控制模块
│ ├── mcp_server.py # MCP服务器实现
│ ├── tool_manager.py # 工具管理器
│ ├── client_tool_manager.py # 客户端工具管理器
│ ├── graphs/ # 图工作流模块
│ │ ├── routing.py # 路由图实现
│ │ └── react.py # ReAct图实现
│ ├── rag/ # RAG模块
│ │ ├── simple.py # 简单RAG实现
│ │ └── emb.py # 文本嵌入模型
│ ├── dummy/ # 示例工具
│ │ └── calculator.py # 计算器工具
│ └── eval/ # 评估模块
│ ├── evaluator.py # 评估器
│ └── validator.py # 验证器
├── scripts/ # 可执行脚本目录
│ ├── run_agent_server.py # 启动代理服务器
│ ├── start_mcp_server.py # 启动MCP服务器
│ ├── ws_start_register_tools.py # WebSocket工具注册
│ ├── ws_start_all_mcps.py # 启动所有MCP服务
│ ├── demo_chat.py # 聊天演示
│ ├── make_rag_database.py # 创建RAG数据库
│ ├── make_eval_dataset.py # 创建评估数据集
│ └── eval.py # 评估脚本
├── configs/ # 配置文件目录
│ ├── mcp_config.json # MCP配置
│ ├── ws_mcp_config.json # WebSocket MCP配置
│ └── route_sys_prompts/ # 路由系统提示
│ ├── chat_prompt.txt # 聊天提示
│ ├── route_prompt.txt # 路由提示
│ └── tool_prompt.txt # 工具提示
└── fastapi_server/ # FastAPI服务器模块
├── server.py # 服务器实现
├── server_dashscope.py # DashScope服务器
└── test_*.py # 测试客户端
```
## 核心模块功能
### 1. 基础模块 (lang_agent/base.py)
定义了两个抽象基类：
- `LangToolBase`: 所有工具的基类，要求实现`get_tool_fnc`方法返回工具函数列表
- `GraphBase`: 所有图工作流的基类，要求实现`invoke`方法执行工作流
### 2. 配置管理 (lang_agent/config.py)
实现了灵活的配置系统：
- `PrintableConfig`: 提供配置打印和敏感信息脱敏功能
- `InstantiateConfig`: 支持通过`_target`属性动态实例化类
- `KeyConfig`: 管理API密钥，从环境变量加载
- `ToolConfig`: 控制工具使用开关
- 提供配置加载、合并和MCP配置转换等工具函数
### 3. 图工作流模块 (lang_agent/graphs/)
#### 路由图 (routing.py)
实现了基于决策的智能路由系统：
- `RoutingConfig`: 配置LLM参数和路由选项
- `RoutingGraph`: 构建状态图工作流，包含路由节点、聊天模型节点和工具模型节点
- 工作流程：通过LLM决策将请求路由到"chat"或"order"路径，分别调用不同的工具集
#### ReAct图 (react.py)
实现了ReAct(Reason-Act)模式的智能体：
- `ReactGraphConfig`: 配置ReAct图的参数
- `ReactGraph`: 使用LangChain的create_agent创建智能体，支持流式输出
- 集成ToolManager管理工具调用
### 4. 工具管理系统
#### 工具管理器 (lang_agent/tool_manager.py)
核心工具管理模块：
- `ToolManagerConfig`: 配置各种工具(RAG、计算器等)
- `ToolManager`: 统一管理工具实例化与调用
- 支持本地工具和MCP客户端工具的整合
- 将工具转换为LangChain的StructuredTool格式
#### 客户端工具管理器 (lang_agent/client_tool_manager.py)
管理MCP客户端工具：
- `ClientToolManagerConfig`: 管理MCP配置文件路径
- `ClientToolManager`: 通过MultiServerMCPClient从MCP服务器获取工具
### 5. RAG模块 (lang_agent/rag/)
#### 简单RAG (simple.py)
基础检索实现：
- `SimpleRagConfig`: 配置嵌入模型和数据库路径
- `SimpleRag`: 使用QwenEmbeddings和FAISS向量存储实现检索功能
- 支持相似度搜索和结果序列化
#### 嵌入模型 (emb.py)
文本嵌入实现：
- `QwenEmbeddings`: 继承LangChain的Embeddings基类
- 使用DashScope API实现文本嵌入
- 支持批量和单文本嵌入、同步和异步处理
- 包含速率限制、并发控制和错误处理机制
### 6. MCP服务器 (lang_agent/mcp_server.py)
实现MCP服务器功能：
- `MCPServerConfig`: 配置服务器名称、主机、端口和传输方式
- `MCPServer`: 使用FastMCP创建服务器，注册工具管理器中的工具
- 支持CORS配置和多种传输方式(stdio, sse, streamable-http)
### 7. 主流程控制 (lang_agent/pipeline.py)
项目的核心流程控制：
- `PipelineConfig`: 配置LLM参数、服务器设置和图配置
- `Pipeline`: 实现模块初始化、图工作流调用、WebSocket服务器和聊天接口
- 集成RoutingGraph或ReactGraph作为工作流引擎
- 提供带角色设定的对话逻辑
## 系统工作流程
1. **初始化阶段**:
- 加载配置和环境变量
- 初始化LLM、嵌入模型和工具管理器
- 构建图工作流(RoutingGraph或ReactGraph)
2. **请求处理阶段**:
- 接收用户输入
- 通过图工作流进行路由决策或ReAct推理
- 调用相应工具(RAG检索、计算器、远程MCP工具等)
- 生成响应并返回
3. **扩展功能**:
- WebSocket服务器支持实时通信
- MCP协议支持远程工具调用
- 评估系统支持模型性能测试
## 安装与配置
### 1. 安装依赖
## 安装依赖
```bash
# 安装xiaoliang-catering以支持购物车工具；否则，请在lang_agent/tool_manager.py中注释掉
pip install xiaoliang-catering
# 开发模式安装
# recommended to install as dev to easily modify the configs in ./config
python -m pip install -e .
```
### 2. 环境变量配置
## 环境变量
需要设置以下环境变量：
make a `.env` with:
```bash
export ALI_API_KEY=你的阿里云API密钥
export ALI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
export MCP_ENDPOINT=你的MCP端点
export LANGSMITH_API_KEY=你的LangSmith API密钥
ALI_API_KEY=<ALI API KEY>
ALI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
MCP_ENDPOINT=<OBSOLETE>
LANGSMITH_API_KEY=<LANG SMITH API KEY> # for testing only; location of where dataset is stored
```
## 运行指南
### 1. 启动MCP服务器
## 运行服务
```bash
# 1. 确保所有环境变量已设置
# 2. 启动MCP服务器
python scripts/start_mcp_server.py
# for easy debug; streams full message internally for visibility
python fastapi_server/fake_stream_server_dashscopy.py
# 3. 使用上述命令中的链接更新configs/ws_mcp_config.json
# 4. 启动WebSocket工具注册
python scripts/ws_start_register_tools.py
```
# for live production
python fastapi_server/server_dashscope.py
# for production
python -m pip install .
```
# Runables
all runnables are under scripts
### 2. 运行代理服务器
```bash
python scripts/run_agent_server.py
```
### 3. 演示聊天
```bash
python scripts/demo_chat.py
```
### 4. 创建RAG数据库
```bash
python scripts/make_rag_database.py
```
### 5. 运行评估
```bash
# 创建评估数据集
python scripts/make_eval_dataset.py
# 运行评估
python scripts/eval.py
```
## 评估数据集格式
评估数据集格式如下，详见`scripts/make_eval_dataset.py`：
```json
[
{
"inputs": {"text": "用retrieve查询光予尘然后介绍"}, // 模型输入；使用列表进行对话
"outputs": {"answer": "光予尘茉莉绿茶为底", // 参考答案
"tool_use": ["retrieve"]} // 工具使用；如果提供了多个工具，假设模型需要使用所有工具
}
]
# this supports openai-api; unmaintained; NOT RECOMMENDED
python fastapi_server/server.py
```
# Configure for Xiaozhi
0. Start the `fastapi_server/server_dashscope.py` file
1. Make a new model entry in `xiaozhi` with AliBL as provider.
2. Fill in the `base_url` entry. The other entries (`API_KEY`, `APP_ID`) can be garbage
- for local computer `base_url=http://127.0.0.1:8588/api/`
- if inside docker, it needs to be `base_url=http://{computer_ip}:8588/api/`
## Runnables
everything in scripts:
- For sample usage see `scripts/demo_chat.py`.
- To evaluate the current default config `scripts/eval.py`
- To make a dataset for eval `scripts/make_eval_dataset.py`
```
# Configure for Xiaozhi
0. Start the `fastapi_server/server_dashscope.py` file
1. Make a new model entry in `xiaozhi` with AliBL as provider.
2. Fill in the `base_url` entry. The other entries (`API_KEY`, `APP_ID`) can be garbage
- for local computer `base_url=http://127.0.0.1:8588/api/`
- if inside docker, it needs to be `base_url=http://{computer_ip}:8588/api/
```
## 技术栈
## Registering MCP service
put the links in `configs/mcp_config.json`
- **核心框架**: LangChain, LangGraph
- **嵌入模型**: QwenEmbeddings (DashScope API)
- **向量存储**: FAISS
- **Web框架**: FastAPI, WebSocket
- **协议支持**: MCP (Model Context Protocol)
- **配置管理**: Tyro, YAML
- **日志系统**: Loguru
## 扩展指南
## Graph structure
Graph structure:
### 添加新工具
![Graph overview](./graph.png)
We choose this structure to overcome a limitation in xiaozhi. Specifically, both normal chatting and tool use prompts are deligated to one model. That leads to degregation in quality of generated conversation and tool use. By splitting into two model, we effectively increase the prompt limit size while preserving model quality.
1. 在`lang_agent/dummy/`或其他适当目录创建新工具类，继承`LangToolBase`
2. 实现`get_tool_fnc`方法返回工具函数列表
3. 在`lang_agent/tool_manager.py`中注册新工具
4. 更新相关配置文件
### 添加新图工作流
1. 在`lang_agent/graphs/`目录创建新图类，继承`GraphBase`
2. 实现`invoke`方法执行工作流
3. 在`lang_agent/pipeline.py`中添加新图类型支持
4. 更新配置文件以支持新图类型
### 添加新评估指标
1. 在`lang_agent/eval/`目录扩展评估器或验证器
2. 在`scripts/eval.py`中集成新指标
3. 更新评估数据集格式以支持新指标
## Modifying LLM prompts
Refer to model above when modifying the prompts.
they are in `configs/route_sys_prompts`
- `chat_prompt.txt`: controls `chat_model_call`
- `route_prompt.txt`: controls `router_call`
- `tool_prompt.txt`: controls `tool_model_call`
- `chatty_prompt.txt`: controls how the model say random things when tool use is in progress. Ignore this for now as model architecture is not yet configurable