Compare commits
2 Commits
3626297211
...
3f22e2b875
| Author | SHA1 | Date | |
|---|---|---|---|
|
3f22e2b875 | ||
|
|
531688aa6b |
@@ -279,6 +279,36 @@ POST /api/v1/asr/{id}/transcribe
|
||||
|
||||
---
|
||||
|
||||
### 8. 预览 ASR (上传音频文件)
|
||||
|
||||
```http
|
||||
POST /api/v1/asr/{id}/preview
|
||||
```
|
||||
|
||||
上传音频文件进行识别预览。
|
||||
|
||||
**Request (multipart/form-data):**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| file | file | 是 | 音频文件 (audio/* | string | 否 | 指定语言，覆盖) |
|
||||
| language模型配置 |
|
||||
| api_key | string | 否 | 覆盖模型配置的 API Key |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"transcript": "您好，请问有什么可以帮助您？",
|
||||
"language": "zh",
|
||||
"confidence": 0.95,
|
||||
"latency_ms": 1500
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Schema 定义
|
||||
|
||||
```python
|
||||
|
||||
@@ -20,24 +20,31 @@ interface Assistant {
|
||||
id: string; // 助手唯一标识 (8位UUID)
|
||||
user_id: number; // 所属用户ID
|
||||
name: string; // 助手名称
|
||||
call_count: number; // 调用次数
|
||||
opener: string; // 开场白
|
||||
callCount: number; // 调用次数
|
||||
firstTurnMode: string; // 首轮模式: "bot_first" | "user_first"
|
||||
opener: string; // 开场白
|
||||
generatedOpenerEnabled: boolean; // 是否启用生成式开场白
|
||||
openerAudioEnabled: boolean; // 是否启用预生成开场音频
|
||||
openerAudioReady: boolean; // 开场音频是否已生成
|
||||
openerAudioDurationMs: number; // 开场音频时长(ms)
|
||||
prompt: string; // 系统提示词/人格设定
|
||||
knowledge_base_id?: string; // 关联知识库ID
|
||||
knowledgeBaseId?: string; // 关联知识库ID
|
||||
language: string; // 语言: "zh" | "en"
|
||||
voice?: string; // 声音ID
|
||||
voiceOutputEnabled: boolean; // 是否启用语音输出
|
||||
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
|
||||
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;
|
||||
}
|
||||
@@ -219,22 +226,109 @@ DELETE. 删除助手
|
||||
|
||||
---
|
||||
|
||||
### 6. 获取助手调用统计
|
||||
### 6. 获取助手引擎配置
|
||||
|
||||
```http
|
||||
GET /api/v1/assistants/{id}/stats
|
||||
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
|
||||
{
|
||||
"assistant_id": "abc12345",
|
||||
"total_calls": 128,
|
||||
"connected_calls": 120,
|
||||
"missed_calls": 8,
|
||||
"avg_duration_seconds": 180,
|
||||
"today_calls": 15
|
||||
"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..."
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -289,86 +289,7 @@ GET /api/v1/history/{call_id}/audio/{turn_index}
|
||||
|
||||
---
|
||||
|
||||
### 8. 搜索通话记录
|
||||
|
||||
```http
|
||||
GET /api/v1/history/search
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| q | string | 是 | 搜索关键词 |
|
||||
| page | int | 否 | 页码 |
|
||||
| limit | int | 否 | 每页数量 |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"total": 5,
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"list": [
|
||||
{
|
||||
"id": "call_001",
|
||||
"started_at": "2024-01-15T14:30:00Z",
|
||||
"matched_content": "用户咨询产品A的售后服务"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9. 获取统计信息
|
||||
|
||||
```http
|
||||
GET /api/v1/history/stats
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| start_date | string | 否 | 开始日期 |
|
||||
| end_date | string | 否 | 结束日期 |
|
||||
| assistant_id | string | 否 | 助手ID |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"total_calls": 150,
|
||||
"connected_calls": 135,
|
||||
"missed_calls": 15,
|
||||
"failed_calls": 0,
|
||||
"avg_duration_seconds": 180,
|
||||
"total_cost": 7.50,
|
||||
"by_status": {
|
||||
"connected": 135,
|
||||
"missed": 15,
|
||||
"failed": 0
|
||||
},
|
||||
"by_source": {
|
||||
"debug": 100,
|
||||
"external": 50
|
||||
},
|
||||
"daily_trend": [
|
||||
{
|
||||
"date": "2024-01-15",
|
||||
"calls": 20,
|
||||
"connected": 18,
|
||||
"avg_duration": 175
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 推荐的 Schema 定义
|
||||
## Schema 定义
|
||||
|
||||
```python
|
||||
# ============ Call Record ============
|
||||
@@ -440,17 +361,6 @@ class TranscriptOut(TranscriptCreate):
|
||||
|
||||
class Config:
|
||||
from_attributes = True
|
||||
|
||||
class HistoryStats(BaseModel):
|
||||
total_calls: int
|
||||
connected_calls: int
|
||||
missed_calls: int
|
||||
failed_calls: int
|
||||
avg_duration_seconds: float
|
||||
total_cost: float
|
||||
by_status: dict
|
||||
by_source: dict
|
||||
daily_trend: List[dict]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -9,7 +9,9 @@
|
||||
| 小助手 | [assistant.md](./assistant.md) | AI 助手管理 |
|
||||
| LLM 模型 | [llm.md](./llm.md) | LLM 模型配置与管理 |
|
||||
| ASR 模型 | [asr.md](./asr.md) | 语音识别模型配置 |
|
||||
| 声音资源 | [voice-resources.md](./voice-resources.md) | TTS 语音配置 |
|
||||
| 工具与测试 | [tools.md](./tools.md) | 工具列表与自动测试 |
|
||||
| 知识库 | [knowledge.md](./knowledge.md) | 知识库与文档管理 |
|
||||
| 历史记录 | [history-records.md](./history-records.md) | 通话记录和转写 |
|
||||
|
||||
---
|
||||
|
||||
420
api/docs/knowledge.md
Normal file
420
api/docs/knowledge.md
Normal file
@@ -0,0 +1,420 @@
|
||||
# 知识库 (Knowledge Base) API
|
||||
|
||||
知识库 API 用于管理知识库和文档的创建、索引和搜索。
|
||||
|
||||
## 基础信息
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| Base URL | `/api/v1/knowledge` |
|
||||
| 认证方式 | Bearer Token (预留) |
|
||||
|
||||
---
|
||||
|
||||
## 数据模型
|
||||
|
||||
### KnowledgeBase
|
||||
|
||||
```typescript
|
||||
interface KnowledgeBase {
|
||||
id: string; // 知识库唯一标识 (8位UUID)
|
||||
user_id: number; // 所属用户ID
|
||||
name: string; // 知识库名称
|
||||
description: string; // 知识库描述
|
||||
embeddingModel: string; // Embedding 模型名称
|
||||
chunkSize: number; // 文档分块大小
|
||||
chunkOverlap: number; // 分块重叠大小
|
||||
docCount: number; // 文档数量
|
||||
chunkCount: number; // 切分后的文本块数量
|
||||
status: string; // 状态: "active" | "inactive"
|
||||
createdAt: string; // 创建时间
|
||||
updatedAt: string; // 更新时间
|
||||
documents: KnowledgeDocument[]; // 关联的文档列表
|
||||
}
|
||||
```
|
||||
|
||||
### KnowledgeDocument
|
||||
|
||||
```typescript
|
||||
interface KnowledgeDocument {
|
||||
id: string; // 文档唯一标识
|
||||
kb_id: string; // 所属知识库ID
|
||||
name: string; // 文档名称
|
||||
size: string; // 文件大小
|
||||
fileType: string; // 文件类型
|
||||
storageUrl: string; // 存储地址
|
||||
status: string; // 状态: "pending" | "processing" | "completed" | "failed"
|
||||
chunkCount: number; // 切分后的文本块数量
|
||||
errorMessage: string; // 错误信息
|
||||
uploadDate: string; // 上传时间
|
||||
createdAt: string; // 创建时间
|
||||
processedAt: string; // 处理完成时间
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API 端点
|
||||
|
||||
### 1. 获取知识库列表
|
||||
|
||||
```http
|
||||
GET /api/v1/knowledge/bases
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| user_id | int | 否 | 1 | 用户ID |
|
||||
| page | int | 否 | 1 | 页码 |
|
||||
| limit | int | 否 | 50 | 每页数量 |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"total": 2,
|
||||
"page": 1,
|
||||
"limit": 50,
|
||||
"list": [
|
||||
{
|
||||
"id": "kb_001",
|
||||
"user_id": 1,
|
||||
"name": "产品知识库",
|
||||
"description": "产品文档和FAQ",
|
||||
"embeddingModel": "text-embedding-3-small",
|
||||
"chunkSize": 500,
|
||||
"chunkOverlap": 50,
|
||||
"docCount": 10,
|
||||
"chunkCount": 150,
|
||||
"status": "active",
|
||||
"createdAt": "2024-01-15T10:30:00",
|
||||
"updatedAt": "2024-01-15T10:30:00",
|
||||
"documents": [...]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 获取单个知识库详情
|
||||
|
||||
```http
|
||||
GET /api/v1/knowledge/bases/{kb_id}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "kb_001",
|
||||
"user_id": 1,
|
||||
"name": "产品知识库",
|
||||
"description": "产品文档和FAQ",
|
||||
"embeddingModel": "text-embedding-3-small",
|
||||
"chunkSize": 500,
|
||||
"chunkOverlap": 50,
|
||||
"docCount": 10,
|
||||
"chunkCount": 150,
|
||||
"status": "active",
|
||||
"createdAt": "2024-01-15T10:30:00",
|
||||
"updatedAt": "2024-01-15T10:30:00",
|
||||
"documents": [
|
||||
{
|
||||
"id": "doc_001",
|
||||
"kb_id": "kb_001",
|
||||
"name": "产品手册.pdf",
|
||||
"size": "1.2 MB",
|
||||
"fileType": "application/pdf",
|
||||
"storageUrl": "",
|
||||
"status": "completed",
|
||||
"chunkCount": 45,
|
||||
"errorMessage": null,
|
||||
"uploadDate": "2024-01-15T10:30:00",
|
||||
"createdAt": "2024-01-15T10:30:00",
|
||||
"processedAt": "2024-01-15T10:30:05"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 创建知识库
|
||||
|
||||
```http
|
||||
POST /api/v1/knowledge/bases
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "产品知识库",
|
||||
"description": "产品文档和FAQ",
|
||||
"embeddingModel": "text-embedding-3-small",
|
||||
"chunkSize": 500,
|
||||
"chunkOverlap": 50
|
||||
}
|
||||
```
|
||||
|
||||
**Fields 说明:**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| name | string | 是 | 知识库名称 |
|
||||
| description | string | 否 | 知识库描述 |
|
||||
| embeddingModel | string | 否 | Embedding 模型名称，默认 "text-embedding-3-small" |
|
||||
| chunkSize | int | 否 | 文档分块大小，默认 500 |
|
||||
| chunkOverlap | int | 否 | 分块重叠大小，默认 50 |
|
||||
|
||||
---
|
||||
|
||||
### 4. 更新知识库
|
||||
|
||||
```http
|
||||
PUT /api/v1/knowledge/bases/{kb_id}
|
||||
```
|
||||
|
||||
**Request Body:** (部分更新)
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "更新后的知识库名称",
|
||||
"description": "新的描述",
|
||||
"chunkSize": 800
|
||||
}
|
||||
```
|
||||
|
||||
**注意:** 如果知识库中已有索引的文档，则不能修改 embeddingModel。如需修改，请先删除所有文档。
|
||||
|
||||
---
|
||||
|
||||
### 5. 删除知识库
|
||||
|
||||
```http
|
||||
DELETE /api/v1/knowledge/bases/{kb_id}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Deleted successfully"
|
||||
}
|
||||
```
|
||||
|
||||
**注意:** 删除知识库会同时删除向量数据库中的相关数据。
|
||||
|
||||
---
|
||||
|
||||
### 6. 上传文档
|
||||
|
||||
```http
|
||||
POST /api/v1/knowledge/bases/{kb_id}/documents
|
||||
```
|
||||
|
||||
支持两种上传方式：
|
||||
|
||||
**方式一：文件上传 (multipart/form-data)**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| file | file | 是 | 要上传的文档文件 |
|
||||
|
||||
支持的文件类型：`.txt`, `.md`, `.csv`, `.json`, `.pdf`, `.docx`
|
||||
|
||||
**方式二：仅创建文档记录 (application/json)**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "document.pdf",
|
||||
"size": "1.2 MB",
|
||||
"fileType": "application/pdf",
|
||||
"storageUrl": "https://storage.example.com/doc.pdf"
|
||||
}
|
||||
```
|
||||
|
||||
**Response (文件上传):**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "doc_001",
|
||||
"name": "产品手册.pdf",
|
||||
"size": "1.2 MB",
|
||||
"fileType": "application/pdf",
|
||||
"storageUrl": "",
|
||||
"status": "completed",
|
||||
"chunkCount": 45,
|
||||
"message": "Document uploaded and indexed"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. 索引文档内容
|
||||
|
||||
```http
|
||||
POST /api/v1/knowledge/bases/{kb_id}/documents/{doc_id}/index
|
||||
```
|
||||
|
||||
直接向向量数据库索引文本内容，无需上传文件。
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"content": "要索引的文本内容..."
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Document indexed",
|
||||
"chunkCount": 10
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8. 删除文档
|
||||
|
||||
```http
|
||||
DELETE /api/v1/knowledge/bases/{kb_id}/documents/{doc_id}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Deleted successfully"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9. 搜索知识库
|
||||
|
||||
```http
|
||||
POST /api/v1/knowledge/search
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"kb_id": "kb_001",
|
||||
"query": "产品退货政策",
|
||||
"nResults": 5
|
||||
}
|
||||
```
|
||||
|
||||
**Fields 说明:**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| kb_id | string | 是 | 知识库ID |
|
||||
| query | string | 是 | 搜索查询文本 |
|
||||
| nResults | int | 否 | 返回结果数量，默认 5 |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"id": "doc_001",
|
||||
"text": "我们的退货政策是...",
|
||||
"score": 0.85,
|
||||
"metadata": {
|
||||
"document_name": "退货政策.pdf",
|
||||
"chunk_index": 3
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 10. 获取知识库统计
|
||||
|
||||
```http
|
||||
GET /api/v1/knowledge/bases/{kb_id}/stats
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"kb_id": "kb_001",
|
||||
"docCount": 10,
|
||||
"chunkCount": 150
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 支持的文件类型
|
||||
|
||||
| 文件类型 | 扩展名 | 说明 |
|
||||
|----------|--------|------|
|
||||
| 纯文本 | .txt | 纯文本文件 |
|
||||
| Markdown | .md | Markdown 格式文档 |
|
||||
| CSV | .csv | CSV 表格数据 |
|
||||
| JSON | .json | JSON 格式数据 |
|
||||
| PDF | .pdf | PDF 文档 (需要 pypdf) |
|
||||
| Word | .docx | Word 文档 (需要 python-docx) |
|
||||
|
||||
**注意:** 不支持旧的 .doc 格式，请转换为 .docx 或其他格式。
|
||||
|
||||
---
|
||||
|
||||
## Schema 定义
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
from typing import Optional, List
|
||||
|
||||
class KnowledgeBaseCreate(BaseModel):
|
||||
name: str
|
||||
description: Optional[str] = None
|
||||
embeddingModel: Optional[str] = "text-embedding-3-small"
|
||||
chunkSize: Optional[int] = 500
|
||||
chunkOverlap: Optional[int] = 50
|
||||
|
||||
class KnowledgeBaseUpdate(BaseModel):
|
||||
name: Optional[str] = None
|
||||
description: Optional[str] = None
|
||||
embeddingModel: Optional[str] = None
|
||||
chunkSize: Optional[int] = None
|
||||
chunkOverlap: Optional[int] = None
|
||||
|
||||
class KnowledgeSearchQuery(BaseModel):
|
||||
kb_id: str
|
||||
query: str
|
||||
nResults: Optional[int] = 5
|
||||
|
||||
class DocumentIndexRequest(BaseModel):
|
||||
content: str
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 单元测试
|
||||
|
||||
项目包含完整的单元测试，位于 `api/tests/test_knowledge.py`。
|
||||
|
||||
### 运行测试
|
||||
|
||||
```bash
|
||||
# 运行知识库相关测试
|
||||
pytest api/tests/test_knowledge.py -v
|
||||
|
||||
# 运行所有测试
|
||||
pytest api/tests/ -v
|
||||
```
|
||||
@@ -258,6 +258,68 @@ POST /api/v1/llm/{id}/chat
|
||||
|
||||
---
|
||||
|
||||
### 8. 预览模型输出
|
||||
|
||||
```http
|
||||
POST /api/v1/llm/{id}/preview
|
||||
```
|
||||
|
||||
预览模型输出，支持 text(chat) 与 embedding 两类模型。
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "请介绍一下你自己",
|
||||
"system_prompt": "你是一个专业的AI助手",
|
||||
"max_tokens": 512,
|
||||
"temperature": 0.7
|
||||
}
|
||||
```
|
||||
|
||||
**Response (text model):**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"reply": "您好！我是一个...",
|
||||
"usage": {
|
||||
"prompt_tokens": 20,
|
||||
"completion_tokens": 50,
|
||||
"total_tokens": 70
|
||||
},
|
||||
"latency_ms": 1500,
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
**Response (embedding model):**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"reply": "Embedding generated successfully. dims=1536. head=[0.012345, -0.023456, ...]",
|
||||
"usage": {
|
||||
"prompt_tokens": 10,
|
||||
"total_tokens": 10
|
||||
},
|
||||
"latency_ms": 800,
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
**Fields 说明:**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| message | string | 是 | 用户消息/嵌入文本 |
|
||||
| system_prompt | string | 否 | 系统提示词 (仅 text 模型) |
|
||||
| max_tokens | int | 否 | 最大生成 token 数 (默认 512) |
|
||||
| temperature | float | 否 | 温度参数 |
|
||||
| api_key | string | 否 | 覆盖模型配置的 API Key |
|
||||
|
||||
---
|
||||
|
||||
## Schema 定义
|
||||
|
||||
```python
|
||||
|
||||
@@ -15,14 +15,23 @@
|
||||
|
||||
系统内置以下工具：
|
||||
|
||||
| 工具ID | 名称 | 说明 |
|
||||
|--------|------|------|
|
||||
| search | 网络搜索 | 搜索互联网获取最新信息 |
|
||||
| calculator | 计算器 | 执行数学计算 |
|
||||
| weather | 天气查询 | 查询指定城市的天气 |
|
||||
| translate | 翻译 | 翻译文本到指定语言 |
|
||||
| knowledge | 知识库查询 | 从知识库中检索相关信息 |
|
||||
| code_interpreter | 代码执行 | 安全地执行Python代码 |
|
||||
| 工具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`: 系统类工具，直接在客户端执行
|
||||
|
||||
---
|
||||
|
||||
@@ -169,6 +178,132 @@ GET /api/v1/tools/health
|
||||
|
||||
---
|
||||
|
||||
### 4. 获取工具资源列表
|
||||
|
||||
```http
|
||||
GET /api/v1/tools/resources
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|------|------|------|--------|------|
|
||||
| category | string | 否 | - | 过滤类别: "query" \| "system" |
|
||||
| enabled | boolean | 否 | - | 过滤启用状态 |
|
||||
| include_system | boolean | 否 | true | 是否包含系统工具 |
|
||||
| page | int | 否 | 1 | 页码 |
|
||||
| limit | int | 否 | 100 | 每页数量 |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"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. 获取工具资源详情
|
||||
|
||||
```http
|
||||
GET /api/v1/tools/resources/{id}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. 创建工具资源
|
||||
|
||||
```http
|
||||
POST /api/v1/tools/resources
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"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. 更新工具资源
|
||||
|
||||
```http
|
||||
PUT /api/v1/tools/resources/{id}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8. 删除工具资源
|
||||
|
||||
```http
|
||||
DELETE /api/v1/tools/resources/{id}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 自动测试 (Autotest)
|
||||
|
||||
### 4. 运行完整自动测试
|
||||
|
||||
@@ -182,12 +182,14 @@ POST /api/v1/voices
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| name | string | 是 | 声音名称 |
|
||||
| vendor | string | 是 | 供应商 |
|
||||
| vendor | string | 是 | 供应商: "Ali" \| "Volcano" \| "Minimax" \| "OpenAI Compatible" \| "DashScope" |
|
||||
| gender | string | 是 | 性别: "Male" \| "Female" |
|
||||
| language | string | 是 | 语言: "zh" \| "en" |
|
||||
| description | string | 否 | 描述信息 |
|
||||
| model | string | 是 | 厂商语音模型标识 |
|
||||
| voice_key | string | 是 | 厂商voice_key |
|
||||
| model | string | 否 | 厂商语音模型标识 (可选，部分供应商有默认值) |
|
||||
| voice_key | string | 否 | 厂商 voice_key (可选，部分供应商有默认值) |
|
||||
| api_key | string | 否 | 供应商 API Key (可选，也可通过环境变量配置) |
|
||||
| base_url | string | 否 | API Base URL (可选，部分供应商有默认值) |
|
||||
| speed | number | 否 | 默认语速 (0.5-2.0)，默认 1.0 |
|
||||
| gain | number | 否 | 音量增益 (-10~10 dB)，默认 0 |
|
||||
| pitch | number | 否 | 音调调整，默认 0 |
|
||||
@@ -244,11 +246,14 @@ POST /api/v1/voices/{id}/preview
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"audio_url": "https://storage.example.com/preview/voice_001_preview.mp3",
|
||||
"duration_ms": 2500
|
||||
"audio_url": "data:audio/wav;base64,UklGRi...",
|
||||
"duration_ms": 2500,
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
**注意:** `audio_url` 返回 Base64 编码的音频数据 (data URI 格式)，可直接在浏览器中播放或解码保存为音频文件。
|
||||
|
||||
---
|
||||
|
||||
### 7. 获取供应商声音列表
|
||||
|
||||
@@ -16,7 +16,7 @@ AI Video Assistant 提供两种类型的 API：
|
||||
### 基础地址
|
||||
|
||||
```
|
||||
http://localhost:8080/api/v1
|
||||
http://localhost:8000/api/v1
|
||||
```
|
||||
|
||||
### 认证
|
||||
@@ -25,7 +25,7 @@ REST API 使用 Bearer Token 认证：
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||||
http://localhost:8080/api/v1/assistants
|
||||
http://localhost:8000/api/v1/assistants
|
||||
```
|
||||
|
||||
### 通用响应格式
|
||||
@@ -74,8 +74,11 @@ curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||||
| GET | /assistants | 获取助手列表 |
|
||||
| POST | /assistants | 创建助手 |
|
||||
| GET | /assistants/{id} | 获取助手详情 |
|
||||
| PATCH | /assistants/{id} | 更新助手 |
|
||||
| PUT | /assistants/{id} | 更新助手 |
|
||||
| DELETE | /assistants/{id} | 删除助手 |
|
||||
| GET | /assistants/{id}/config | 获取引擎配置 |
|
||||
| GET | /assistants/{id}/opener-audio | 获取开场音频状态 |
|
||||
| POST | /assistants/{id}/opener-audio/generate | 生成开场音频 |
|
||||
|
||||
#### 模型管理
|
||||
|
||||
@@ -83,19 +86,48 @@ curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||||
|------|------|------|
|
||||
| GET | /llm | 获取 LLM 模型列表 |
|
||||
| POST | /llm | 添加 LLM 模型 |
|
||||
| PUT | /llm/{id} | 更新 LLM 模型 |
|
||||
| DELETE | /llm/{id} | 删除 LLM 模型 |
|
||||
| POST | /llm/{id}/test | 测试 LLM 连接 |
|
||||
| POST | /llm/{id}/preview | 预览模型输出 |
|
||||
| GET | /asr | 获取 ASR 模型列表 |
|
||||
| POST | /asr | 添加 ASR 模型 |
|
||||
| PUT | /asr/{id} | 更新 ASR 模型 |
|
||||
| DELETE | /asr/{id} | 删除 ASR 模型 |
|
||||
| POST | /asr/{id}/test | 测试 ASR 连接 |
|
||||
| POST | /asr/{id}/preview | 上传音频预览识别 |
|
||||
| GET | /voices | 获取语音列表 |
|
||||
| POST | /voices | 添加语音配置 |
|
||||
| PUT | /voices/{id} | 更新语音配置 |
|
||||
| DELETE | /voices/{id} | 删除语音配置 |
|
||||
| POST | /voices/{id}/preview | 预览声音 |
|
||||
|
||||
#### 知识库管理
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | /knowledge-bases | 获取知识库列表 |
|
||||
| POST | /knowledge-bases | 创建知识库 |
|
||||
| POST | /knowledge-bases/{id}/documents | 上传文档 |
|
||||
| DELETE | /knowledge-bases/{id}/documents/{doc_id} | 删除文档 |
|
||||
| GET | /knowledge/bases | 获取知识库列表 |
|
||||
| POST | /knowledge/bases | 创建知识库 |
|
||||
| PUT | /knowledge/bases/{id} | 更新知识库 |
|
||||
| DELETE | /knowledge/bases/{id} | 删除知识库 |
|
||||
| POST | /knowledge/bases/{id}/documents | 上传文档 |
|
||||
| POST | /knowledge/bases/{id}/documents/{doc_id}/index | 索引文档内容 |
|
||||
| DELETE | /knowledge/bases/{id}/documents/{doc_id} | 删除文档 |
|
||||
| POST | /knowledge/search | 搜索知识库 |
|
||||
| GET | /knowledge/bases/{id}/stats | 获取统计信息 |
|
||||
|
||||
#### 工具管理
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | /tools/list | 获取内置工具列表 |
|
||||
| GET | /tools/resources | 获取工具资源列表 |
|
||||
| POST | /tools/resources | 创建工具资源 |
|
||||
| PUT | /tools/resources/{id} | 更新工具资源 |
|
||||
| DELETE | /tools/resources/{id} | 删除工具资源 |
|
||||
| GET | /tools/health | 健康检查 |
|
||||
| POST | /tools/autotest | 运行自动测试 |
|
||||
| POST | /tools/test-message | 发送测试消息 |
|
||||
|
||||
#### 历史记录
|
||||
|
||||
@@ -103,7 +135,11 @@ curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||||
|------|------|------|
|
||||
| GET | /history | 获取对话历史 |
|
||||
| GET | /history/{id} | 获取对话详情 |
|
||||
| GET | /history/stats | 获取统计数据 |
|
||||
| POST | /history | 创建通话记录 |
|
||||
| PUT | /history/{id} | 更新通话记录 |
|
||||
| DELETE | /history/{id} | 删除通话记录 |
|
||||
| POST | /history/{id}/transcripts | 添加转写片段 |
|
||||
| GET | /history/{id}/audio/{turn_index} | 获取音频文件 |
|
||||
|
||||
## WebSocket API
|
||||
|
||||
|
||||
Reference in New Issue
Block a user