wx44wx/AI-VideoAssistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3f22e2b875685e6f00f53f8486d4e1d71d1a3fea
AI-VideoAssistant/api/docs/tools.md

12 KiB
Raw Blame History

工具与自动测试 (Tools & Autotest) API

工具与自动测试 API 用于管理可用工具列表和自动测试功能。

基础信息

项目 值
Base URL /api/v1/tools
认证方式 Bearer Token (预留)

可用工具 (Tool Registry)

系统内置以下工具：

工具ID 名称 类别 说明
calculator 计算器 query 执行数学计算
code_interpreter 代码执行 query 安全地执行Python代码
current_time 当前时间 query 获取当前本地时间
turn_on_camera 打开摄像头 system 执行打开摄像头命令
turn_off_camera 关闭摄像头 system 执行关闭摄像头命令
increase_volume 调高音量 system 提升设备音量
decrease_volume 调低音量 system 降低设备音量
voice_message_prompt 语音消息提示 system 播报一条语音提示消息
text_msg_prompt 文本消息提示 system 显示一条文本弹窗提示
voice_choice_prompt 语音选项提示 system 播报问题并展示可选项，等待用户选择
text_choice_prompt 文本选项提示 system 显示文本选项弹窗并等待用户选择

类别说明：

  • query: 查询类工具，需要配置 HTTP URL
  • system: 系统类工具，直接在客户端执行

API 端点

1. 获取可用工具列表

GET /api/v1/tools/list

Response:

{
  "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. 获取工具详情

GET /api/v1/tools/list/{tool_id}

Path Parameters:

参数 类型 说明
tool_id string 工具ID

Response:

{
  "name": "计算器",
  "description": "执行数学计算",
  "parameters": {
    "type": "object",
    "properties": {
      "expression": {"type": "string", "description": "数学表达式，如: 2 + 3 * 4"}
    },
    "required": ["expression"]
  }
}

错误响应 (工具不存在):

{
  "detail": "Tool not found"
}

3. 健康检查

GET /api/v1/tools/health

Response:

{
  "status": "healthy",
  "timestamp": 1705315200.123,
  "tools": ["search", "calculator", "weather", "translate", "knowledge", "code_interpreter"]
}

4. 获取工具资源列表

GET /api/v1/tools/resources

Query Parameters:

参数 类型 必填 默认值 说明
category string 否 - 过滤类别: "query" | "system"
enabled boolean 否 - 过滤启用状态
include_system boolean 否 true 是否包含系统工具
page int 否 1 页码
limit int 否 100 每页数量

Response:

{
  "total": 15,
  "page": 1,
  "limit": 100,
  "list": [
    {
      "id": "calculator",
      "user_id": 1,
      "name": "计算器",
      "description": "执行数学计算",
      "category": "query",
      "icon": "Terminal",
      "http_method": "GET",
      "http_url": null,
      "http_timeout_ms": 10000,
      "parameter_schema": {
        "type": "object",
        "properties": {
          "expression": {"type": "string", "description": "数学表达式"}
        },
        "required": ["expression"]
      },
      "parameter_defaults": {},
      "wait_for_response": false,
      "enabled": true,
      "is_system": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

5. 获取工具资源详情

GET /api/v1/tools/resources/{id}

6. 创建工具资源

POST /api/v1/tools/resources

Request Body:

{
  "name": "订单查询",
  "description": "查询用户订单信息",
  "category": "query",
  "icon": "Search",
  "http_method": "POST",
  "http_url": "https://api.example.com/orders",
  "http_headers": {"Authorization": "Bearer {api_key}"},
  "http_timeout_ms": 10000,
  "parameter_schema": {
    "type": "object",
    "properties": {
      "order_id": {"type": "string", "description": "订单ID"}
    },
    "required": ["order_id"]
  },
  "enabled": true
}

Fields 说明:

字段 类型 必填 说明
id string 否 工具ID，默认自动生成
name string 是 工具名称
description string 否 工具描述
category string 是 类别: "query" | "system"
icon string 否 图标名称
http_method string 否 HTTP 方法，默认 GET
http_url string 否* HTTP 请求地址 (query 类必填)
http_headers object 否 HTTP 请求头
http_timeout_ms int 否 超时时间(毫秒)，默认 10000
parameter_schema object 否 参数 JSON Schema
parameter_defaults object 否 默认参数值
wait_for_response boolean 否 是否等待响应 (仅 system 类)
enabled boolean 否 是否启用，默认 true

7. 更新工具资源

PUT /api/v1/tools/resources/{id}

8. 删除工具资源

DELETE /api/v1/tools/resources/{id}

自动测试 (Autotest)

4. 运行完整自动测试

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:

{
  "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 模型

POST /api/v1/tools/autotest/llm/{model_id}

Path Parameters:

参数 类型 说明
model_id string LLM 模型ID

Response:

{
  "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 模型

POST /api/v1/tools/autotest/asr/{model_id}

Path Parameters:

参数 类型 说明
model_id string ASR 模型ID

Response:

{
  "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. 发送测试消息

POST /api/v1/tools/test-message

Query Parameters:

参数 类型 必填 默认值 说明
llm_model_id string 是 - LLM 模型ID
message string 否 "Hello, this is a test message." 测试消息

Response:

{
  "success": true,
  "reply": "Hello! This is a test reply from GPT-4o.",
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 12,
    "total_tokens": 27
  }
}

错误响应 (模型不存在):

{
  "detail": "LLM Model not found"
}

测试结果结构

AutotestResult

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 自动测试功能完整测试

运行测试

# 运行工具相关测试
pytest api/tests/test_tools.py -v

# 运行所有测试
pytest api/tests/ -v
Reference in New Issue View Git Blame Copy Permalink