Add docs for api backend
This commit is contained in:
Xin Wang
364
api/docs/speech-recognition.md
Normal file
364
api/docs/speech-recognition.md
Normal file
@@ -0,0 +1,364 @@
|
||||
# 语音识别 (Speech Recognition / ASR) API
|
||||
|
||||
语音识别 API 用于管理语音识别模型的配置和调用。
|
||||
|
||||
## 基础信息
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| Base URL | `/api/v1/asr` |
|
||||
| 认证方式 | Bearer Token (预留) |
|
||||
|
||||
---
|
||||
|
||||
## 数据模型
|
||||
|
||||
### ASRConfig
|
||||
|
||||
```typescript
|
||||
interface ASRConfig {
|
||||
id: string; // 配置ID
|
||||
user_id: number; // 所属用户ID
|
||||
name: string; // 配置名称
|
||||
vendor: string; // 供应商
|
||||
language: string; // 识别语言
|
||||
base_url: string; // API地址
|
||||
api_key: string; // API密钥
|
||||
model_name?: string; // 模型名称
|
||||
hotwords?: string[]; // 热词增强
|
||||
enable_punctuation: boolean; // 是否启用标点
|
||||
enable_normalization: boolean; // 是否启用文本规范化
|
||||
enabled: boolean;
|
||||
created_at: string;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API 端点
|
||||
|
||||
### 1. 获取 ASR 配置列表
|
||||
|
||||
```http
|
||||
GET /api/v1/asr
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| language | string | 否 | 过滤语言 |
|
||||
| vendor | string | 否 | 过滤供应商 |
|
||||
| enabled | boolean | 否 | 过滤启用状态 |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"total": 3,
|
||||
"list": [
|
||||
{
|
||||
"id": "asr_001",
|
||||
"user_id": 1,
|
||||
"name": "Whisper 多语种识别",
|
||||
"vendor": "OpenAI Compatible",
|
||||
"language": "Multi-lingual",
|
||||
"base_url": "https://api.openai.com/v1",
|
||||
"api_key": "sk-***",
|
||||
"model_name": "whisper-1",
|
||||
"enable_punctuation": true,
|
||||
"enable_normalization": true,
|
||||
"enabled": true,
|
||||
"created_at": "2024-01-15T10:30:00Z"
|
||||
},
|
||||
{
|
||||
"id": "asr_002",
|
||||
"user_id": 1,
|
||||
"name": "SenseVoice 中文识别",
|
||||
"vendor": "OpenAI Compatible",
|
||||
"language": "zh",
|
||||
"base_url": "https://api.speech.ai/v1",
|
||||
"api_key": "sk-***",
|
||||
"model_name": "sensevoice-small",
|
||||
"hotwords": ["小助手", "帮我"],
|
||||
"enabled": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 获取单个 ASR 配置详情
|
||||
|
||||
```http
|
||||
GET /api/v1/asr/{id}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "asr_001",
|
||||
"user_id": 1,
|
||||
"name": "Whisper 多语种识别",
|
||||
"vendor": "OpenAI Compatible",
|
||||
"language": "Multi-lingual",
|
||||
"base_url": "https://api.openai.com/v1",
|
||||
"api_key": "sk-xxx",
|
||||
"model_name": "whisper-1",
|
||||
"hotwords": [],
|
||||
"enable_punctuation": true,
|
||||
"enable_normalization": true,
|
||||
"enabled": true,
|
||||
"created_at": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 创建 ASR 配置
|
||||
|
||||
```http
|
||||
POST /api/v1/asr
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "SenseVoice 中文识别",
|
||||
"vendor": "OpenAI Compatible",
|
||||
"language": "zh",
|
||||
"base_url": "https://api.speech.ai/v1",
|
||||
"api_key": "sk-your-api-key",
|
||||
"model_name": "sensevoice-small",
|
||||
"hotwords": ["小助手", "帮我"],
|
||||
"enable_punctuation": true,
|
||||
"enable_normalization": true,
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
**Fields 说明:**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| name | string | 是 | 配置名称 |
|
||||
| vendor | string | 是 | 供应商: "OpenAI Compatible" / "Azure" / "阿里云" / "讯飞" |
|
||||
| language | string | 是 | 语言: "zh" / "en" / "Multi-lingual" |
|
||||
| base_url | string | 是 | API Base URL |
|
||||
| api_key | string | 是 | API Key |
|
||||
| model_name | string | 否 | 模型名称 |
|
||||
| hotwords | string[] | 否 | 热词列表，提升识别准确率 |
|
||||
| enable_punctuation | boolean | 否 | 是否输出标点，默认 true |
|
||||
| enable_normalization | boolean | 否 | 是否文本规范化，默认 true |
|
||||
| enabled | boolean | 否 | 是否启用，默认 true |
|
||||
|
||||
---
|
||||
|
||||
### 4. 更新 ASR 配置
|
||||
|
||||
```http
|
||||
PUT /api/v1/asr/{id}
|
||||
```
|
||||
|
||||
**Request Body:** (部分更新)
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Whisper-1 优化版",
|
||||
"language": "zh",
|
||||
"enable_punctuation": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. 删除 ASR 配置
|
||||
|
||||
```http
|
||||
DELETE /api/v1/asr/{id}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. 测试 ASR 识别
|
||||
|
||||
```http
|
||||
POST /api/v1/asr/{id}/test
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"audio_url": "https://example.com/test-audio.wav",
|
||||
"audio_data": "base64_encoded_audio" // 二选一
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"transcript": "您好，请问有什么可以帮助您？",
|
||||
"language": "zh",
|
||||
"confidence": 0.95,
|
||||
"duration_ms": 3000,
|
||||
"latency_ms": 450
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. 实时语音识别 (流式)
|
||||
|
||||
```http
|
||||
WS /api/v1/asr/{id}/stream
|
||||
```
|
||||
|
||||
**连接参数:**
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| audio_format | string | 音频格式: "pcm" / "mp3" / "wav" |
|
||||
| sample_rate | int | 采样率: 16000 / 44100 |
|
||||
| channels | int | 声道数: 1 (单声道) / 2 (立体声) |
|
||||
|
||||
**消息格式:**
|
||||
|
||||
客户端发送 (音频数据):
|
||||
```json
|
||||
{
|
||||
"type": "audio",
|
||||
"data": "base64_encoded_audio_chunk"
|
||||
}
|
||||
```
|
||||
|
||||
服务端返回 (识别结果):
|
||||
```json
|
||||
{
|
||||
"type": "transcript",
|
||||
"text": "您好",
|
||||
"is_final": false
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "transcript",
|
||||
"text": "您好，请问有什么可以帮助您？",
|
||||
"is_final": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 推荐的 Schema 定义
|
||||
|
||||
```python
|
||||
# ============ ASR Model ============
|
||||
class ASRLanguage(str, Enum):
|
||||
ZH = "zh"
|
||||
EN = "en"
|
||||
MULTILINGUAL = "Multi-lingual"
|
||||
|
||||
class ASRVendor(str, Enum):
|
||||
OPENAI_COMPATIBLE = "OpenAI Compatible"
|
||||
AZURE = "Azure"
|
||||
ALI = "阿里云"
|
||||
IFLYTEK = "讯飞"
|
||||
|
||||
class ASRModelBase(BaseModel):
|
||||
name: str
|
||||
vendor: str
|
||||
language: str # "zh" | "en" | "Multi-lingual"
|
||||
base_url: str
|
||||
api_key: str
|
||||
model_name: Optional[str] = None
|
||||
hotwords: List[str] = []
|
||||
enable_punctuation: bool = True
|
||||
enable_normalization: bool = True
|
||||
enabled: bool = True
|
||||
|
||||
class ASRModelCreate(ASRModelBase):
|
||||
pass
|
||||
|
||||
class ASRModelUpdate(BaseModel):
|
||||
name: Optional[str] = None
|
||||
language: Optional[str] = None
|
||||
base_url: Optional[str] = None
|
||||
api_key: Optional[str] = None
|
||||
model_name: Optional[str] = None
|
||||
hotwords: Optional[List[str]] = None
|
||||
enable_punctuation: Optional[bool] = None
|
||||
enable_normalization: Optional[bool] = None
|
||||
enabled: Optional[bool] = None
|
||||
|
||||
class ASRModelOut(ASRModelBase):
|
||||
id: str
|
||||
user_id: int
|
||||
created_at: datetime
|
||||
|
||||
class Config:
|
||||
from_attributes = True
|
||||
|
||||
class ASRTestRequest(BaseModel):
|
||||
audio_url: Optional[str] = None
|
||||
audio_data: Optional[str] = None # base64 encoded
|
||||
|
||||
class ASRTestResponse(BaseModel):
|
||||
success: bool
|
||||
transcript: Optional[str] = None
|
||||
language: Optional[str] = None
|
||||
confidence: Optional[float] = None
|
||||
duration_ms: Optional[int] = None
|
||||
latency_ms: Optional[int] = None
|
||||
error: Optional[str] = None
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 供应商配置示例
|
||||
|
||||
### OpenAI Whisper
|
||||
|
||||
```json
|
||||
{
|
||||
"vendor": "OpenAI Compatible",
|
||||
"base_url": "https://api.openai.com/v1",
|
||||
"api_key": "sk-xxx",
|
||||
"model_name": "whisper-1",
|
||||
"language": "Multi-lingual",
|
||||
"enable_punctuation": true,
|
||||
"enable_normalization": true
|
||||
}
|
||||
```
|
||||
|
||||
### 阿里云智能语音
|
||||
|
||||
```json
|
||||
{
|
||||
"vendor": "阿里云",
|
||||
"base_url": "https://filetrans.cn-shanghai.aliyuncs.com/v1",
|
||||
"api_key": "your-access-key-id:your-access-key-secret",
|
||||
"model_name": "nls.cn-shanghai",
|
||||
"language": "zh",
|
||||
"hotwords": ["产品名称", "公司名"]
|
||||
}
|
||||
```
|
||||
|
||||
### 讯飞语音
|
||||
|
||||
```json
|
||||
{
|
||||
"vendor": "讯飞",
|
||||
"base_url": "https://iat-api.xfyun.cn/v2/iat",
|
||||
"api_key": "your-appid:your-api-key",
|
||||
"model_name": "iat",
|
||||
"language": "zh",
|
||||
"enable_punctuation": true
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user