diff --git a/api/docs/asr.md b/api/docs/asr.md index 5b9098f..17e6b49 100644 --- a/api/docs/asr.md +++ b/api/docs/asr.md @@ -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 diff --git a/api/docs/assistant.md b/api/docs/assistant.md index cad5ba0..e357e05 100644 --- a/api/docs/assistant.md +++ b/api/docs/assistant.md @@ -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..." } ``` diff --git a/api/docs/history-records.md b/api/docs/history-records.md index 0a55843..0101226 100644 --- a/api/docs/history-records.md +++ b/api/docs/history-records.md @@ -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] ``` --- diff --git a/api/docs/index.md b/api/docs/index.md index fb685f3..892dec0 100644 --- a/api/docs/index.md +++ b/api/docs/index.md @@ -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) | 通话记录和转写 | --- diff --git a/api/docs/knowledge.md b/api/docs/knowledge.md new file mode 100644 index 0000000..2733c35 --- /dev/null +++ b/api/docs/knowledge.md @@ -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 +``` diff --git a/api/docs/llm.md b/api/docs/llm.md index 86d3c24..ad9a210 100644 --- a/api/docs/llm.md +++ b/api/docs/llm.md @@ -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 diff --git a/api/docs/tools.md b/api/docs/tools.md index 7361ffe..892b8a2 100644 --- a/api/docs/tools.md +++ b/api/docs/tools.md @@ -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. 运行完整自动测试 diff --git a/api/docs/voice-resources.md b/api/docs/voice-resources.md index 23c68ac..135005c 100644 --- a/api/docs/voice-resources.md +++ b/api/docs/voice-resources.md @@ -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. 获取供应商声音列表 diff --git a/docs/content/api-reference/index.md b/docs/content/api-reference/index.md index 7600383..516d837 100644 --- a/docs/content/api-reference/index.md +++ b/docs/content/api-reference/index.md @@ -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