From 531688aa6bee41ea428b9ff52b8423c601a0e4d9 Mon Sep 17 00:00:00 2001 From: Xin Wang Date: Mon, 2 Mar 2026 01:56:38 +0800 Subject: [PATCH] Enhance API documentation by adding new endpoints for ASR preview, assistant configuration retrieval, and knowledge base management. Update existing assistant and tool definitions for improved clarity and functionality. Remove outdated sections from history records documentation, ensuring a streamlined reference for users. --- api/docs/asr.md | 30 ++ api/docs/assistant.md | 140 ++++++++-- api/docs/history-records.md | 92 +----- api/docs/index.md | 2 + api/docs/knowledge.md | 420 ++++++++++++++++++++++++++++ api/docs/llm.md | 62 ++++ api/docs/tools.md | 151 +++++++++- api/docs/voice-resources.md | 15 +- docs/content/api-reference/index.md | 52 +++- 9 files changed, 829 insertions(+), 135 deletions(-) create mode 100644 api/docs/knowledge.md 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