Update backend api
This commit is contained in:
Xin Wang
445
api/docs/tools.md
Normal file
445
api/docs/tools.md
Normal file
@@ -0,0 +1,445 @@
|
||||
# 工具与自动测试 (Tools & Autotest) API
|
||||
|
||||
工具与自动测试 API 用于管理可用工具列表和自动测试功能。
|
||||
|
||||
## 基础信息
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| Base URL | `/api/v1/tools` |
|
||||
| 认证方式 | Bearer Token (预留) |
|
||||
|
||||
---
|
||||
|
||||
## 可用工具 (Tool Registry)
|
||||
|
||||
系统内置以下工具：
|
||||
|
||||
| 工具ID | 名称 | 说明 |
|
||||
|--------|------|------|
|
||||
| search | 网络搜索 | 搜索互联网获取最新信息 |
|
||||
| calculator | 计算器 | 执行数学计算 |
|
||||
| weather | 天气查询 | 查询指定城市的天气 |
|
||||
| translate | 翻译 | 翻译文本到指定语言 |
|
||||
| knowledge | 知识库查询 | 从知识库中检索相关信息 |
|
||||
| code_interpreter | 代码执行 | 安全地执行Python代码 |
|
||||
|
||||
---
|
||||
|
||||
## API 端点
|
||||
|
||||
### 1. 获取可用工具列表
|
||||
|
||||
```http
|
||||
GET /api/v1/tools/list
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"search": {
|
||||
"name": "网络搜索",
|
||||
"description": "搜索互联网获取最新信息",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"query": {"type": "string", "description": "搜索关键词"}
|
||||
},
|
||||
"required": ["query"]
|
||||
}
|
||||
},
|
||||
"calculator": {
|
||||
"name": "计算器",
|
||||
"description": "执行数学计算",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"expression": {"type": "string", "description": "数学表达式，如: 2 + 3 * 4"}
|
||||
},
|
||||
"required": ["expression"]
|
||||
}
|
||||
},
|
||||
"weather": {
|
||||
"name": "天气查询",
|
||||
"description": "查询指定城市的天气",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"city": {"type": "string", "description": "城市名称"}
|
||||
},
|
||||
"required": ["city"]
|
||||
}
|
||||
},
|
||||
"translate": {
|
||||
"name": "翻译",
|
||||
"description": "翻译文本到指定语言",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"text": {"type": "string", "description": "要翻译的文本"},
|
||||
"target_lang": {"type": "string", "description": "目标语言，如: en, ja, ko"}
|
||||
},
|
||||
"required": ["text", "target_lang"]
|
||||
}
|
||||
},
|
||||
"knowledge": {
|
||||
"name": "知识库查询",
|
||||
"description": "从知识库中检索相关信息",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"query": {"type": "string", "description": "查询内容"},
|
||||
"kb_id": {"type": "string", "description": "知识库ID"}
|
||||
},
|
||||
"required": ["query"]
|
||||
}
|
||||
},
|
||||
"code_interpreter": {
|
||||
"name": "代码执行",
|
||||
"description": "安全地执行Python代码",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"code": {"type": "string", "description": "要执行的Python代码"}
|
||||
},
|
||||
"required": ["code"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 获取工具详情
|
||||
|
||||
```http
|
||||
GET /api/v1/tools/list/{tool_id}
|
||||
```
|
||||
|
||||
**Path Parameters:**
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| tool_id | string | 工具ID |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "计算器",
|
||||
"description": "执行数学计算",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"expression": {"type": "string", "description": "数学表达式，如: 2 + 3 * 4"}
|
||||
},
|
||||
"required": ["expression"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应 (工具不存在):**
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "Tool not found"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 健康检查
|
||||
|
||||
```http
|
||||
GET /api/v1/tools/health
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"timestamp": 1705315200.123,
|
||||
"tools": ["search", "calculator", "weather", "translate", "knowledge", "code_interpreter"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 自动测试 (Autotest)
|
||||
|
||||
### 4. 运行完整自动测试
|
||||
|
||||
```http
|
||||
POST /api/v1/tools/autotest
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| llm_model_id | string | 否 | - | LLM 模型ID |
|
||||
| asr_model_id | string | 否 | - | ASR 模型ID |
|
||||
| test_llm | boolean | 否 | true | 是否测试LLM |
|
||||
| test_asr | boolean | 否 | true | 是否测试ASR |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "abc12345",
|
||||
"started_at": 1705315200.0,
|
||||
"duration_ms": 2500,
|
||||
"tests": [
|
||||
{
|
||||
"name": "Model Existence",
|
||||
"passed": true,
|
||||
"message": "Found model: GPT-4o",
|
||||
"duration_ms": 15
|
||||
},
|
||||
{
|
||||
"name": "API Connection",
|
||||
"passed": true,
|
||||
"message": "Latency: 150ms",
|
||||
"duration_ms": 150
|
||||
},
|
||||
{
|
||||
"name": "Temperature Setting",
|
||||
"passed": true,
|
||||
"message": "temperature=0.7"
|
||||
},
|
||||
{
|
||||
"name": "Streaming Support",
|
||||
"passed": true,
|
||||
"message": "Received 15 chunks",
|
||||
"duration_ms": 800
|
||||
}
|
||||
],
|
||||
"summary": {
|
||||
"passed": 4,
|
||||
"failed": 0,
|
||||
"total": 4
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. 测试单个 LLM 模型
|
||||
|
||||
```http
|
||||
POST /api/v1/tools/autotest/llm/{model_id}
|
||||
```
|
||||
|
||||
**Path Parameters:**
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| model_id | string | LLM 模型ID |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "llm_test_001",
|
||||
"started_at": 1705315200.0,
|
||||
"duration_ms": 1200,
|
||||
"tests": [
|
||||
{
|
||||
"name": "Model Existence",
|
||||
"passed": true,
|
||||
"message": "Found model: GPT-4o",
|
||||
"duration_ms": 10
|
||||
},
|
||||
{
|
||||
"name": "API Connection",
|
||||
"passed": true,
|
||||
"message": "Latency: 180ms",
|
||||
"duration_ms": 180
|
||||
},
|
||||
{
|
||||
"name": "Temperature Setting",
|
||||
"passed": true,
|
||||
"message": "temperature=0.7"
|
||||
},
|
||||
{
|
||||
"name": "Streaming Support",
|
||||
"passed": true,
|
||||
"message": "Received 12 chunks",
|
||||
"duration_ms": 650
|
||||
}
|
||||
],
|
||||
"summary": {
|
||||
"passed": 4,
|
||||
"failed": 0,
|
||||
"total": 4
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. 测试单个 ASR 模型
|
||||
|
||||
```http
|
||||
POST /api/v1/tools/autotest/asr/{model_id}
|
||||
```
|
||||
|
||||
**Path Parameters:**
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| model_id | string | ASR 模型ID |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "asr_test_001",
|
||||
"started_at": 1705315200.0,
|
||||
"duration_ms": 800,
|
||||
"tests": [
|
||||
{
|
||||
"name": "Model Existence",
|
||||
"passed": true,
|
||||
"message": "Found model: Whisper-1",
|
||||
"duration_ms": 8
|
||||
},
|
||||
{
|
||||
"name": "Hotwords Config",
|
||||
"passed": true,
|
||||
"message": "Hotwords: 3 words"
|
||||
},
|
||||
{
|
||||
"name": "API Availability",
|
||||
"passed": true,
|
||||
"message": "Status: 200",
|
||||
"duration_ms": 250
|
||||
},
|
||||
{
|
||||
"name": "Language Config",
|
||||
"passed": true,
|
||||
"message": "Language: zh"
|
||||
}
|
||||
],
|
||||
"summary": {
|
||||
"passed": 4,
|
||||
"failed": 0,
|
||||
"total": 4
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. 发送测试消息
|
||||
|
||||
```http
|
||||
POST /api/v1/tools/test-message
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| llm_model_id | string | 是 | - | LLM 模型ID |
|
||||
| message | string | 否 | "Hello, this is a test message." | 测试消息 |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"reply": "Hello! This is a test reply from GPT-4o.",
|
||||
"usage": {
|
||||
"prompt_tokens": 15,
|
||||
"completion_tokens": 12,
|
||||
"total_tokens": 27
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应 (模型不存在):**
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "LLM Model not found"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试结果结构
|
||||
|
||||
### AutotestResult
|
||||
|
||||
```typescript
|
||||
interface AutotestResult {
|
||||
id: string; // 测试ID
|
||||
started_at: number; // 开始时间戳
|
||||
duration_ms: number; // 总耗时(毫秒)
|
||||
tests: TestCase[]; // 测试用例列表
|
||||
summary: TestSummary; // 测试摘要
|
||||
}
|
||||
|
||||
interface TestCase {
|
||||
name: string; // 测试名称
|
||||
passed: boolean; // 是否通过
|
||||
message: string; // 测试消息
|
||||
duration_ms: number; // 耗时(毫秒)
|
||||
}
|
||||
|
||||
interface TestSummary {
|
||||
passed: number; // 通过数量
|
||||
failed: number; // 失败数量
|
||||
total: number; // 总数量
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试项目说明
|
||||
|
||||
### LLM 模型测试项目
|
||||
|
||||
| 测试名称 | 说明 |
|
||||
|----------|------|
|
||||
| Model Existence | 检查模型是否存在于数据库 |
|
||||
| API Connection | 测试 API 连接并测量延迟 |
|
||||
| Temperature Setting | 检查温度配置 |
|
||||
| Streaming Support | 测试流式响应支持 |
|
||||
|
||||
### ASR 模型测试项目
|
||||
|
||||
| 测试名称 | 说明 |
|
||||
|----------|------|
|
||||
| Model Existence | 检查模型是否存在于数据库 |
|
||||
| Hotwords Config | 检查热词配置 |
|
||||
| API Availability | 测试 API 可用性 |
|
||||
| Language Config | 检查语言配置 |
|
||||
|
||||
---
|
||||
|
||||
## 单元测试
|
||||
|
||||
项目包含完整的单元测试，位于 `api/tests/test_tools.py`。
|
||||
|
||||
### 测试用例概览
|
||||
|
||||
| 测试类 | 说明 |
|
||||
|--------|------|
|
||||
| TestToolsAPI | 工具列表、健康检查等基础功能测试 |
|
||||
| TestAutotestAPI | 自动测试功能完整测试 |
|
||||
|
||||
### 运行测试
|
||||
|
||||
```bash
|
||||
# 运行工具相关测试
|
||||
pytest api/tests/test_tools.py -v
|
||||
|
||||
# 运行所有测试
|
||||
pytest api/tests/ -v
|
||||
```
|
||||
Reference in New Issue
Block a user