AI-VideoAssistant/api/docs/assistant.md

助手 (Assistant) API

助手 API 用于管理 AI 小助手的创建、配置和操作。

基础信息

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

---

数据模型

Assistant

interface Assistant {
  id: string;           // 助手唯一标识 (8位UUID)
  user_id: number;      // 所属用户ID
  name: string;         // 助手名称
  call_count: number;   // 调用次数
  opener: string;      // 开场白
  prompt: string;       // 系统提示词/人格设定
  knowledge_base_id?: string;  // 关联知识库ID
  language: string;     // 语言: "zh" | "en"
  voice?: string;      // 声音ID
  speed: number;        // 语速 (0.5-2.0)
  hotwords: string[];  // 热词列表
  tools: string[];      // 启用的工具ID列表
  interruption_sensitivity: number;  // 打断灵敏度 (ms)
  config_mode: string;  // 配置模式: "platform" | "dify" | "fastgpt" | "none"
  api_url?: string;    // 外部API URL
  api_key?: string;     // 外部API Key
  // 模型关联 (新增)
  llm_model_id?: string;       // LLM模型ID
  asr_model_id?: string;       // ASR模型ID
  embedding_model_id?: string; // Embedding模型ID
  rerank_model_id?: string;    // Rerank模型ID
  created_at: string;
  updated_at: string;
}

---

API 端点

1. 获取助手列表

GET /api/v1/assistants

Query Parameters:

参数	类型	必填	默认值	说明
page	int	否	1	页码
limit	int	否	50	每页数量

Response:

{
  "total": 100,
  "page": 1,
  "limit": 50,
  "list": [
    {
      "id": "abc12345",
      "user_id": 1,
      "name": "客服助手",
      "call_count": 128,
      "opener": "您好，请问有什么可以帮助您？",
      "prompt": "你是一个专业的客服人员...",
      "language": "zh",
      "voice": "voice_001",
      "speed": 1.0,
      "hotwords": ["帮助", "退款"],
      "tools": ["query_order", "refund"],
      "interruption_sensitivity": 500,
      "config_mode": "platform",
      "llm_model_id": "llm_001",
      "asr_model_id": "asr_001",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

---

2. 获取单个助手详情

GET /api/v1/assistants/{id}

Path Parameters:

参数	类型	说明
id	string	助手ID

Response:

{
  "id": "abc12345",
  "user_id": 1,
  "name": "客服助手",
  "call_count": 128,
  "opener": "您好，请问有什么可以帮助您？",
  "prompt": "你是一个专业的客服人员...",
  "knowledge_base_id": "kb_001",
  "language": "zh",
  "voice": "voice_001",
  "speed": 1.0,
  "hotwords": ["帮助", "退款"],
  "tools": ["query_order", "refund"],
  "interruption_sensitivity": 500,
  "config_mode": "platform",
  "api_url": "https://api.example.com",
  "llm_model_id": "llm_001",
  "asr_model_id": "asr_001",
  "embedding_model_id": "emb_001",
  "rerank_model_id": "rerank_001",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

---

3. 创建助手

POST /api/v1/assistants

Request Body:

{
  "name": "客服助手",
  "opener": "您好，请问有什么可以帮助您？",
  "prompt": "你是一个专业的客服人员，擅长解答产品问题和处理投诉。",
  "knowledgeBaseId": "kb_001",
  "language": "zh",
  "voice": "voice_001",
  "speed": 1.0,
  "hotwords": ["帮助", "退款", "物流"],
  "tools": ["query_order", "refund", "track_order"],
  "interruptionSensitivity": 500,
  "configMode": "platform",
  "llmModelId": "llm_001",
  "asrModelId": "asr_001",
  "embeddingModelId": "emb_001",
  "rerankModelId": "rerank_001"
}

Fields 说明:

字段	类型	必填	说明
name	string	是	助手名称
opener	string	否	开场白，默认空字符串
prompt	string	否	系统提示词，默认空字符串
knowledgeBaseId	string	否	关联知识库ID
language	string	否	语言，默认 "zh"
voice	string	否	声音资源ID
speed	number	否	语速，默认 1.0
hotwords	string[]	否	热词列表
tools	string[]	否	启用的工具ID列表
interruptionSensitivity	number	否	打断灵敏度(ms)，默认 500
configMode	string	否	配置模式，默认 "platform"
llmModelId	string	否	LLM模型ID
asrModelId	string	否	ASR模型ID
embeddingModelId	string	否	Embedding模型ID
rerankModelId	string	否	Rerank模型ID

---

4. 更新助手

PUT /api/v1/assistants/{id}

Request Body: (部分更新)

{
  "name": "高级客服助手",
  "prompt": "你是一个高级客服人员...",
  "speed": 1.2
}

---

5```http

DELETE. 删除助手

/api/v1/assistants/{id}

**Response:**

```json
{
  "message": "Deleted successfully"
}

---

6. 获取助手调用统计

GET /api/v1/assistants/{id}/stats

Response:

{
  "assistant_id": "abc12345",
  "total_calls": 128,
  "connected_calls": 120,
  "missed_calls": 8,
  "avg_duration_seconds": 180,
  "today_calls": 15
}

---

建议的 Schema 改进

基于 web/types.ts 的分析，建议在 schemas.py 中补充以下字段：

class AssistantBase(BaseModel):
    # ... 现有字段 ...
    llm_model_id: Optional[str] = None
    asr_model_id: Optional[str] = None
    embedding_model_id: Optional[str] = None
    rerank_model_id: Optional[str] = None