Revamp documentation structure in mkdocs.yml by reorganizing navigation for improved accessibility. Remove outdated content from previous sections and introduce new topics including detailed guides on assistant management, configuration options, and tool integrations. Enhance API reference documentation with comprehensive error codes and WebSocket protocol details. Add new sections for automated testing, data analysis, and knowledge base management, ensuring a cohesive and user-friendly documentation experience.
This commit is contained in:
Xin Wang
229
docs/content/customization/tools.md
Normal file
229
docs/content/customization/tools.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# 工具集成
|
||||
|
||||
工具（Tools）让助手能够执行外部操作，如查询天气、搜索信息、调用 API 等。
|
||||
|
||||
## 概述
|
||||
|
||||
工具是助手能力的扩展。当用户的请求需要外部数据或操作时，助手会调用相应的工具。
|
||||
|
||||
## 内置工具
|
||||
|
||||
| 工具 | 说明 | 参数 |
|
||||
|------|------|------|
|
||||
| `search` | 网络搜索 | query: 搜索关键词 |
|
||||
| `weather` | 天气查询 | city: 城市名称 |
|
||||
| `calculator` | 数学计算 | expression: 计算表达式 |
|
||||
| `knowledge` | 知识库检索 | query: 查询内容 |
|
||||
|
||||
### 启用内置工具
|
||||
|
||||
在助手配置的 **工具** 标签页：
|
||||
|
||||
1. 勾选需要启用的工具
|
||||
2. 配置工具参数（如有）
|
||||
3. 保存配置
|
||||
|
||||
## 自定义工具
|
||||
|
||||
支持通过 HTTP 回调实现自定义工具。
|
||||
|
||||
### 定义工具
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "query_order",
|
||||
"description": "查询用户订单信息",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"order_id": {
|
||||
"type": "string",
|
||||
"description": "订单编号"
|
||||
}
|
||||
},
|
||||
"required": ["order_id"]
|
||||
},
|
||||
"endpoint": {
|
||||
"url": "https://api.example.com/orders",
|
||||
"method": "GET",
|
||||
"headers": {
|
||||
"Authorization": "Bearer {{api_key}}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 工具字段说明
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| name | 工具名称（英文标识符） |
|
||||
| description | 工具描述（LLM 用于理解工具用途） |
|
||||
| parameters | 参数定义（JSON Schema 格式） |
|
||||
| endpoint | HTTP 调用配置 |
|
||||
|
||||
### 参数映射
|
||||
|
||||
工具参数自动映射到 HTTP 请求：
|
||||
|
||||
- **GET 请求**：参数作为 query string
|
||||
- **POST 请求**：参数作为 JSON body
|
||||
|
||||
## 客户端工具
|
||||
|
||||
某些工具需要在客户端执行（如获取地理位置）。
|
||||
|
||||
### 工作流程
|
||||
|
||||
1. 助手返回 `assistant.tool_call` 事件
|
||||
2. 客户端执行工具并获取结果
|
||||
3. 客户端发送 `tool_call.results` 消息
|
||||
4. 助手继续生成回复
|
||||
|
||||
### 服务端事件
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "assistant.tool_call",
|
||||
"data": {
|
||||
"tool_call_id": "call_abc123",
|
||||
"tool_name": "get_location",
|
||||
"arguments": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 客户端响应
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "tool_call.results",
|
||||
"results": [
|
||||
{
|
||||
"tool_call_id": "call_abc123",
|
||||
"name": "get_location",
|
||||
"output": {
|
||||
"latitude": 39.9042,
|
||||
"longitude": 116.4074,
|
||||
"city": "北京"
|
||||
},
|
||||
"status": {
|
||||
"code": 200,
|
||||
"message": "ok"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 工具调用示例
|
||||
|
||||
### 天气查询
|
||||
|
||||
用户："北京今天天气怎么样？"
|
||||
|
||||
助手调用工具：
|
||||
```json
|
||||
{
|
||||
"tool_name": "weather",
|
||||
"arguments": {
|
||||
"city": "北京"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
工具返回：
|
||||
```json
|
||||
{
|
||||
"temperature": 25,
|
||||
"condition": "晴",
|
||||
"humidity": 40
|
||||
}
|
||||
```
|
||||
|
||||
助手回复："北京今天天气晴朗，气温 25 度，湿度 40%。"
|
||||
|
||||
### 订单查询
|
||||
|
||||
用户："帮我查一下订单 12345"
|
||||
|
||||
助手调用工具：
|
||||
```json
|
||||
{
|
||||
"tool_name": "query_order",
|
||||
"arguments": {
|
||||
"order_id": "12345"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
工具返回：
|
||||
```json
|
||||
{
|
||||
"order_id": "12345",
|
||||
"status": "已发货",
|
||||
"tracking": "SF1234567890"
|
||||
}
|
||||
```
|
||||
|
||||
助手回复："您的订单 12345 已发货，快递单号是 SF1234567890。"
|
||||
|
||||
## 工具配置最佳实践
|
||||
|
||||
### 1. 清晰的描述
|
||||
|
||||
工具描述应该让 LLM 准确理解何时使用：
|
||||
|
||||
```
|
||||
好的描述：
|
||||
"查询指定城市的实时天气信息，包括温度、天气状况和湿度"
|
||||
|
||||
不好的描述：
|
||||
"天气工具"
|
||||
```
|
||||
|
||||
### 2. 完整的参数定义
|
||||
|
||||
```json
|
||||
{
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"city": {
|
||||
"type": "string",
|
||||
"description": "城市名称，如 '北京'、'上海'"
|
||||
},
|
||||
"date": {
|
||||
"type": "string",
|
||||
"description": "日期，格式 YYYY-MM-DD，可选，默认今天"
|
||||
}
|
||||
},
|
||||
"required": ["city"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 错误处理
|
||||
|
||||
工具应返回清晰的错误信息：
|
||||
|
||||
```json
|
||||
{
|
||||
"status": {
|
||||
"code": 404,
|
||||
"message": "未找到该城市的天气数据"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
1. **验证输入** - 不要直接信任用户输入
|
||||
2. **限制权限** - 工具只应有必要的权限
|
||||
3. **审计日志** - 记录所有工具调用
|
||||
4. **速率限制** - 防止滥用
|
||||
|
||||
## 下一步
|
||||
|
||||
- [知识库配置](knowledge-base.md) - 让助手具备专业知识
|
||||
- [工作流编排](workflows.md) - 复杂对话流程
|
||||
Reference in New Issue
Block a user