7.9 KiB
7.9 KiB
助手 (Assistant) API
助手 API 用于管理 AI 小助手的创建、配置和操作。
基础信息
| 项目 | 值 |
|---|---|
| Base URL | /api/v1/assistants |
| 认证方式 | Bearer Token (预留) |
数据模型
Assistant
interface Assistant {
id: string; // 助手唯一标识 (8位UUID)
user_id: number; // 所属用户ID
name: string; // 助手名称
callCount: number; // 调用次数
firstTurnMode: string; // 首轮模式: "bot_first" | "user_first"
opener: string; // 开场白
generatedOpenerEnabled: boolean; // 是否启用生成式开场白
openerAudioEnabled: boolean; // 是否启用预生成开场音频
openerAudioReady: boolean; // 开场音频是否已生成
openerAudioDurationMs: number; // 开场音频时长(ms)
prompt: string; // 系统提示词/人格设定
knowledgeBaseId?: string; // 关联知识库ID
language: string; // 语言: "zh" | "en"
voiceOutputEnabled: boolean; // 是否启用语音输出
voice?: string; // 声音ID
speed: number; // 语速 (0.5-2.0)
hotwords: string[]; // 热词列表
tools: string[]; // 启用的工具ID列表
botCannotBeInterrupted: boolean; // 是否禁止打断
interruptionSensitivity: number; // 打断灵敏度 (ms)
configMode: string; // 配置模式: "platform" | "dify" | "fastgpt" | "none"
apiUrl?: string; // 外部API URL
apiKey?: string; // 外部API Key
// 模型关联
llmModelId?: string; // LLM模型ID
asrModelId?: string; // ASR模型ID
embeddingModelId?: string; // Embedding模型ID
rerankModelId?: 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}/config
获取助手的运行时引擎配置，包含 LLM、ASR、TTS、知识库等服务的完整配置信息。
Response:
{
"assistantId": "abc12345",
"configVersionId": "asst_abc12345_20240115103000",
"assistant": {
"systemPrompt": "你是一个专业的客服人员...",
"firstTurnMode": "bot_first",
"greeting": "您好，请问有什么可以帮助您？",
"generatedOpenerEnabled": false,
"output": {"mode": "audio"},
"bargeIn": {"enabled": true, "minDurationMs": 500},
"services": {
"llm": {"provider": "openai", "model": "gpt-4o", "apiKey": "...", "baseUrl": "..."},
"asr": {"provider": "openai_compatible", "model": "paraformer-realtime-v2", "apiKey": "..."},
"tts": {"enabled": true, "provider": "dashscope", "model": "qwen3-tts-flash-realtime", "voice": "Cherry", "speed": 1.0}
},
"tools": [...],
"knowledgeBaseId": "kb_001",
"openerAudio": {"enabled": true, "ready": true, "pcmUrl": "/api/assistants/abc12345/opener-audio/pcm"}
},
"sessionStartMetadata": {...},
"sources": {
"llmModelId": "llm_001",
"asrModelId": "asr_001",
"voiceId": "voice_001",
"knowledgeBaseId": "kb_001"
},
"warnings": []
}
7. 获取助手开场音频状态
GET /api/v1/assistants/{id}/opener-audio
Response:
{
"enabled": true,
"ready": true,
"encoding": "pcm_s16le",
"sampleRateHz": 16000,
"channels": 1,
"durationMs": 2500,
"textHash": "abc123...",
"ttsFingerprint": "def456...",
"updatedAt": "2024-01-15T10:30:00Z"
}
8. 下载开场音频 PCM 文件
GET /api/v1/assistants/{id}/opener-audio/pcm
返回 PCM 音频文件 (application/octet-stream)。
9. 生成开场音频
POST /api/v1/assistants/{id}/opener-audio/generate
Request Body:
{
"text": "您好，请问有什么可以帮助您？"
}
Response:
{
"enabled": true,
"ready": true,
"encoding": "pcm_s16le",
"sampleRateHz": 16000,
"channels": 1,
"durationMs": 2500,
"textHash": "abc123...",
"ttsFingerprint": "def456..."
}
建议的 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