Add docs for api backend
This commit is contained in:
Xin Wang
254
api/docs/assistant.md
Normal file
254
api/docs/assistant.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# 助手 (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; // 助手名称
|
||||
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. 获取助手列表
|
||||
|
||||
```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}/stats
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"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` 中补充以下字段：
|
||||
|
||||
```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
|
||||
```
|
||||
Reference in New Issue
Block a user