349 lines
7.9 KiB
Markdown
349 lines
7.9 KiB
Markdown
# 助手 (Assistant) API
|
|
|
|
助手 API 用于管理 AI 小助手的创建、配置和操作。
|
|
|
|
## 基础信息
|
|
|
|
| 项目 | 值 |
|
|
|------|-----|
|
|
| Base URL | `/api/v1/assistants` |
|
|
| 认证方式 | Bearer Token (预留) |
|
|
|
|
---
|
|
|
|
## 数据模型
|
|
|
|
### Assistant
|
|
|
|
```typescript
|
|
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. 获取助手列表
|
|
|
|
```http
|
|
GET /api/v1/assistants
|
|
```
|
|
|
|
**Query Parameters:**
|
|
|
|
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
|
|------|------|------|--------|------|
|
|
| page | int | 否 | 1 | 页码 |
|
|
| limit | int | 否 | 50 | 每页数量 |
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"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. 获取单个助手详情
|
|
|
|
```http
|
|
GET /api/v1/assistants/{id}
|
|
```
|
|
|
|
**Path Parameters:**
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| id | string | 助手ID |
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"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. 创建助手
|
|
|
|
```http
|
|
POST /api/v1/assistants
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"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. 更新助手
|
|
|
|
```http
|
|
PUT /api/v1/assistants/{id}
|
|
```
|
|
|
|
**Request Body:** (部分更新)
|
|
|
|
```json
|
|
{
|
|
"name": "高级客服助手",
|
|
"prompt": "你是一个高级客服人员...",
|
|
"speed": 1.2
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 5```http
|
|
DELETE. 删除助手
|
|
|
|
/api/v1/assistants/{id}
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"message": "Deleted successfully"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 6. 获取助手引擎配置
|
|
|
|
```http
|
|
GET /api/v1/assistants/{id}/config
|
|
```
|
|
|
|
获取助手的运行时引擎配置，包含 LLM、ASR、TTS、知识库等服务的完整配置信息。
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"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. 获取助手开场音频状态
|
|
|
|
```http
|
|
GET /api/v1/assistants/{id}/opener-audio
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"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 文件
|
|
|
|
```http
|
|
GET /api/v1/assistants/{id}/opener-audio/pcm
|
|
```
|
|
|
|
返回 PCM 音频文件 (application/octet-stream)。
|
|
|
|
---
|
|
|
|
### 9. 生成开场音频
|
|
|
|
```http
|
|
POST /api/v1/assistants/{id}/opener-audio/generate
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"text": "您好，请问有什么可以帮助您？"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"enabled": true,
|
|
"ready": true,
|
|
"encoding": "pcm_s16le",
|
|
"sampleRateHz": 16000,
|
|
"channels": 1,
|
|
"durationMs": 2500,
|
|
"textHash": "abc123...",
|
|
"ttsFingerprint": "def456..."
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 建议的 Schema 改进
|
|
|
|
基于 web/types.ts 的分析，建议在 `schemas.py` 中补充以下字段：
|
|
|
|
```python
|
|
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
|
|
```
|