125 lines
5.3 KiB
Markdown
125 lines
5.3 KiB
Markdown
# LLM Tool Proxy
|
||
|
||
## 1. 概述 (Overview)
|
||
|
||
本项目是一个基于 FastAPI 实现的智能LLM（大语言模型）代理服务。其核心功能是拦截发往LLM的API请求，动态地将客户端定义的`tools`（工具）信息注入到提示词（Prompt）中，然后将LLM返回的结果进行解析，将其中可能包含的工具调用（Tool Call）指令提取出来，最后以结构化的格式返回给调用者。
|
||
|
||
这使得即使底层LLM原生不支持工具调用参数，我们也能通过提示工程的方式赋予其使用工具的能力。
|
||
|
||
## 2. 设计原则 (Design Principles)
|
||
|
||
本程序在设计上严格遵循了以下原则：
|
||
|
||
- **高内聚 (High Cohesion)**: 业务逻辑被集中在服务层 (`app/services.py`) 中，与API路由和数据模型分离。
|
||
- **低耦合 (Low Coupling)**:
|
||
- API层 (`app/main.py`) 只负责路由和请求校验，不关心业务实现细节。
|
||
- 通过依赖注入 (`Depends`) 获取配置，避免了全局状态。
|
||
- LLM调用被抽象为独立的函数，方便未来切换不同的LLM后端或在测试中使用模拟（Mock）实现。
|
||
- **可测试性 (Testability)**: 项目包含了完整的单元测试和集成测试 (`tests/`)，使用 `pytest` 和 `TestClient` 来确保每个模块的正确性和整体流程的稳定性。
|
||
|
||
## 3. 项目结构 (Project Structure)
|
||
|
||
```
|
||
.
|
||
├── app/ # 核心应用代码
|
||
│ ├── core/ # 配置管理
|
||
│ │ └── config.py
|
||
│ ├── main.py # FastAPI 应用实例和 API 路由
|
||
│ ├── models.py # Pydantic 数据模型
|
||
│ └── services.py # 核心业务逻辑
|
||
├── tests/ # 测试代码
|
||
│ └── test_main.py
|
||
├── .env # 环境变量文件 (需手动创建)
|
||
├── .gitignore # Git 忽略文件
|
||
├── README.md # 本文档
|
||
└── .venv/ # Python 虚拟环境 (由 uv 创建)
|
||
```
|
||
|
||
## 4. 核心逻辑详解 (Core Logic)
|
||
|
||
### 4.1. 提示词注入 (Prompt Injection)
|
||
|
||
- **实现函数**: `app.services.inject_tools_into_prompt`
|
||
- **策略**:
|
||
1. 将客户端请求中 `tools` 列表（JSON数组）序列化为格式化的JSON字符串。
|
||
2. 创建一个新的、`role` 为 `system` 的独立消息。
|
||
3. 此消息包含明确的指令，告诉LLM它拥有哪些工具以及如何通过特定的格式来调用它们。
|
||
4. **调用格式约定**: 指示LLM在需要调用工具时，必须输出一个 `<tool_call>{...}</tool_call>` 的XML标签，其中包含一个带有 `name` 和 `arguments` 字段的JSON对象。
|
||
5. 这个系统消息被插入到原始消息列表的第二个位置（索引1），然后整个修改后的消息列表被发送到真实的LLM后端。
|
||
- **目的**: 对调用者透明，将工具使用的“契约”通过上下文传递给LLM。
|
||
|
||
### 4.2. 响应解析 (Response Parsing)
|
||
|
||
- **实现函数**: `app.services.parse_llm_response`
|
||
- **策略**:
|
||
1. 使用正则表达式 (`re.search`) 在LLM返回的纯文本响应中查找 `<tool_call>...</tool_call>` 标签。
|
||
2. 如果找到，它会提取标签内的JSON字符串，并将其解析为一个结构化的 `ToolCall` 对象。此时，返回给客户端的 `ResponseMessage` 中 `tool_calls` 字段将被填充，而 `content` 字段可能为 `None`。
|
||
3. 如果未找到标签，则将LLM的全部响应视为常规的文本内容，填充 `content` 字段。
|
||
- **目的**: 将LLM的非结构化（或半结构化）输出，转换为客户端可以轻松处理的、定义良好的结构化数据。
|
||
|
||
## 5. 配置管理 (Configuration)
|
||
|
||
- 配置文件为根目录下的 `.env`。
|
||
- `app/core/config.py` 中的 `get_settings` 函数通过依赖注入的方式在每次请求时加载环境变量，确保配置的实时性和在测试中的灵活性。
|
||
- **必需变量**:
|
||
- `REAL_LLM_API_URL`: 真实LLM后端的地址。
|
||
- `REAL_LLM_API_KEY`: 用于访问真实LLM的API密钥。
|
||
|
||
## 6. 如何运行与测试 (Usage)
|
||
|
||
### 6.1. 环境设置
|
||
|
||
```bash
|
||
# 创建虚拟环境
|
||
uv venv
|
||
|
||
# 安装依赖
|
||
uv pip install fastapi uvicorn httpx pytest
|
||
```
|
||
|
||
### 6.2. 运行开发服务器
|
||
|
||
```bash
|
||
uvicorn app.main:app --reload
|
||
```
|
||
服务将运行在 `http://127.0.0.1:8000`。
|
||
|
||
### 6.3. 运行测试
|
||
|
||
```bash
|
||
# 使用 .venv 中的 python 解释器执行 pytest
|
||
.venv/bin/python -m pytest
|
||
```
|
||
|
||
## 7. API 端点示例 (API Example)
|
||
|
||
**端点**: `POST /v1/chat/completions`
|
||
|
||
**请求示例 (带工具)**:
|
||
```bash
|
||
curl -X POST "http://127.0.0.1:8000/v1/chat/completions" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"messages": [
|
||
{"role": "user", "content": "What is the weather in San Francisco?"}
|
||
],
|
||
"tools": [
|
||
{
|
||
"type": "function",
|
||
"function": {
|
||
"name": "get_weather",
|
||
"description": "Get weather for a city",
|
||
"parameters": {}
|
||
}
|
||
}
|
||
]
|
||
}'
|
||
```
|
||
|
||
## 8. 未来升级方向 (Future Improvements)
|
||
|
||
- **支持多种LLM后端**: 修改 `call_llm_api_real` 函数，使其能根据请求参数或配置选择不同的LLM提供商。
|
||
- **更灵活的工具调用格式**: 支持除XML标签外的其他格式，例如纯JSON输出模式。
|
||
- **流式响应 (Streaming)**: 支持LLM的流式输出，并实时解析和返回给客户端。
|
||
- **错误处理增强**: 针对不同的LLM API错误码和网络问题，提供更精细的错误反馈。
|