482 lines
17 KiB
Python
482 lines
17 KiB
Python
# -*- coding: utf-8 -*-
|
||
"""
|
||
ASR API路由
|
||
"""
|
||
|
||
from fastapi import (
|
||
APIRouter,
|
||
Request,
|
||
HTTPException,
|
||
Depends
|
||
)
|
||
from fastapi.responses import JSONResponse
|
||
from typing import Annotated, Optional
|
||
import time
|
||
import logging
|
||
|
||
from ...core.config import settings
|
||
from ...core.exceptions import (
|
||
AuthenticationException,
|
||
InvalidParameterException,
|
||
InvalidMessageException,
|
||
UnsupportedSampleRateException,
|
||
DefaultServerErrorException,
|
||
get_http_status_code,
|
||
)
|
||
from ...core.security import validate_token
|
||
from ...models.common import SampleRate
|
||
from ...models.asr import (
|
||
ASRResponse,
|
||
ASRHealthCheckResponse,
|
||
ASRModelsResponse,
|
||
ASRSuccessResponse,
|
||
ASRErrorResponse,
|
||
ASRQueryParams,
|
||
)
|
||
from ...utils.common import generate_task_id
|
||
from ...services.asr.manager import get_model_manager
|
||
from ...services.asr.model_selection import validate_offline_model_id
|
||
from ...services.asr.runtime import get_runtime_router
|
||
from ...services.asr.audio_validation import validate_sample_rate
|
||
from ...services.asr.offline_transcription_service import (
|
||
OfflineTranscriptionOptions,
|
||
PreparedAudio,
|
||
get_offline_transcription_service,
|
||
)
|
||
|
||
# 配置日志
|
||
logger = logging.getLogger(__name__)
|
||
|
||
# 创建路由器
|
||
router = APIRouter(prefix="/stream/v1", tags=["ASR"])
|
||
|
||
|
||
def _build_asr_openapi_parameters() -> list[dict]:
|
||
parameters: list[dict] = [
|
||
{
|
||
"name": "model",
|
||
"in": "query",
|
||
"required": False,
|
||
"schema": {
|
||
"type": "string",
|
||
"maxLength": 128,
|
||
"example": "qwen3-asr-0.6b",
|
||
},
|
||
"description": "可选。离线 ASR 模型 ID；不传则使用服务当前默认模型",
|
||
},
|
||
{
|
||
"name": "audio_address",
|
||
"in": "query",
|
||
"required": False,
|
||
"schema": {
|
||
"type": "string",
|
||
"maxLength": 512,
|
||
"example": "https://media.cdn.vect.one/podcast_demo.mp4",
|
||
},
|
||
"description": "音频/视频文件地址，支持 HTTP/HTTPS URL、file:// 或服务端本地路径。仅当请求体为空时使用；若同时上传请求体，服务会忽略此参数",
|
||
},
|
||
{
|
||
"name": "sample_rate",
|
||
"in": "query",
|
||
"required": False,
|
||
"schema": {
|
||
"type": "integer",
|
||
"enum": [8000, 16000, 22050, 24000, 32000, 44100, 48000],
|
||
"default": 16000,
|
||
"example": 16000,
|
||
},
|
||
"description": "音频采样率（Hz）。音频会在服务端自动转换，通常保持默认值即可",
|
||
},
|
||
{
|
||
"name": "enable_speaker_diarization",
|
||
"in": "query",
|
||
"required": False,
|
||
"schema": {
|
||
"type": "boolean",
|
||
"default": True,
|
||
"example": True,
|
||
},
|
||
"description": "是否启用说话人分离。启用后响应会包含 speaker_id 字段",
|
||
},
|
||
{
|
||
"name": "enable_speaker_identification",
|
||
"in": "query",
|
||
"required": False,
|
||
"schema": {
|
||
"type": "boolean",
|
||
"default": True,
|
||
"example": True,
|
||
},
|
||
"description": "是否匹配已注册声纹库。仅在 enable_speaker_diarization=true 时生效，命中后响应会包含 speaker_name/user_id",
|
||
},
|
||
{
|
||
"name": "enable_text_cleanup",
|
||
"in": "query",
|
||
"required": False,
|
||
"schema": {
|
||
"type": "boolean",
|
||
"default": True,
|
||
"example": True,
|
||
},
|
||
"description": "是否启用文本去重、跨段重叠裁剪和口头语清理",
|
||
},
|
||
{
|
||
"name": "vocabulary_id",
|
||
"in": "query",
|
||
"required": False,
|
||
"schema": {
|
||
"type": "string",
|
||
"maxLength": 512,
|
||
"example": "阿里巴巴 20 腾讯 15",
|
||
},
|
||
"description": "热词字符串，格式：`热词1 权重1 热词2 权重2`。权重范围 1-100，建议 10-30。可提升特定词汇的识别准确率",
|
||
},
|
||
{
|
||
"name": "X-NLS-Token",
|
||
"in": "header",
|
||
"required": False,
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 256,
|
||
"example": "",
|
||
},
|
||
"description": "访问令牌，用于身份认证。未配置 API_KEY 环境变量时可忽略",
|
||
},
|
||
]
|
||
if settings.ASR_ENABLE_WORD_TIMESTAMPS:
|
||
parameters.insert(
|
||
5,
|
||
{
|
||
"name": "word_timestamps",
|
||
"in": "query",
|
||
"required": False,
|
||
"schema": {
|
||
"type": "boolean",
|
||
"default": False,
|
||
"example": False,
|
||
},
|
||
"description": "是否返回字词级时间戳（默认关闭；启用时会自动调用 forced aligner）",
|
||
},
|
||
)
|
||
return parameters
|
||
|
||
|
||
async def get_asr_params(request: Request) -> ASRQueryParams:
|
||
"""从请求中提取并验证ASR参数"""
|
||
# 从URL查询参数中获取
|
||
query_params = dict(request.query_params)
|
||
|
||
# 使用统一的验证器验证参数
|
||
try:
|
||
# 验证采样率（转换为整数）
|
||
if "sample_rate" in query_params and query_params["sample_rate"]:
|
||
try:
|
||
sample_rate = int(query_params["sample_rate"]) # type: ignore
|
||
validated_rate = validate_sample_rate(sample_rate)
|
||
query_params["sample_rate"] = str(validated_rate) # type: ignore
|
||
except ValueError:
|
||
raise InvalidParameterException(
|
||
f"采样率必须是整数，收到: {query_params['sample_rate']}"
|
||
)
|
||
|
||
# 创建ASRQueryParams实例，Pydantic会自动验证和设置默认值
|
||
return ASRQueryParams.model_validate(query_params)
|
||
except InvalidParameterException:
|
||
raise
|
||
except Exception as e:
|
||
raise InvalidParameterException(f"请求参数错误: {str(e)}")
|
||
|
||
|
||
@router.post(
|
||
"/asr",
|
||
response_model=ASRResponse,
|
||
responses={
|
||
200: {
|
||
"description": "识别成功",
|
||
"model": ASRSuccessResponse,
|
||
},
|
||
400: {
|
||
"description": "请求参数错误",
|
||
"model": ASRErrorResponse,
|
||
},
|
||
401: {"description": "认证失败", "model": ASRErrorResponse},
|
||
500: {"description": "服务器内部错误", "model": ASRErrorResponse},
|
||
},
|
||
summary="语音识别（支持长音频）",
|
||
description="""
|
||
将音频文件转写为文本，兼容阿里云语音识别 RESTful API。
|
||
|
||
## 功能特性
|
||
- 支持多种音频格式与常见含音轨视频容器：WAV, MP3, M4A, FLAC, OGG, AAC, AMR, PCM, WEBM, MP4, MOV, MKV, AVI 等
|
||
- 自动音频格式检测和转换
|
||
- 支持长音频自动分段识别（返回带时间戳的分段结果）
|
||
- 最大文件大小：{settings.MAX_AUDIO_SIZE // (1024 * 1024)}MB（可通过环境变量 MAX_AUDIO_SIZE 配置）
|
||
|
||
## 音频输入方式
|
||
1. **请求体上传**：将音频/视频二进制数据作为请求体发送
|
||
2. **URL/本地路径读取**：通过 `audio_address` 参数指定音频/视频文件 URL（HTTP/HTTPS）或服务端本地路径
|
||
|
||
如果请求体和 `audio_address` 同时存在，服务会优先使用请求体，并忽略 `audio_address`。
|
||
|
||
## 注意事项
|
||
- 默认使用服务当前启用的 Qwen3-ASR 模型；也可通过可选 `model` 参数指定当前可用离线模型
|
||
- `vocabulary_id` 参数用于传递热词，格式：`热词1 权重1 热词2 权重2`（如：`阿里巴巴 20 腾讯 15`）
|
||
- `enable_speaker_identification` 仅在 `enable_speaker_diarization=true` 时生效，用于匹配已注册声纹库
|
||
- `enable_text_cleanup` 控制识别后的文本去重、跨段重叠裁剪和口头语清理
|
||
- 音频会自动转换为 16kHz 采样率进行识别
|
||
""",
|
||
openapi_extra={
|
||
"parameters": _build_asr_openapi_parameters(),
|
||
"requestBody": {
|
||
"description": "音频/视频文件二进制数据。支持格式：WAV, MP3, M4A, FLAC, OGG, AAC, AMR, PCM, WEBM, MP4, MOV, MKV, AVI 等。若同时提供 audio_address，服务会优先使用这里上传的内容",
|
||
"content": {
|
||
"application/octet-stream": {
|
||
"schema": {"type": "string", "format": "binary"}
|
||
}
|
||
},
|
||
"required": False,
|
||
},
|
||
},
|
||
)
|
||
async def asr_transcribe(
|
||
request: Request, params: Annotated[ASRQueryParams, Depends(get_asr_params)]
|
||
) -> JSONResponse:
|
||
"""语音识别API端点"""
|
||
task_id = generate_task_id()
|
||
prepared_audio: Optional[PreparedAudio] = None
|
||
|
||
# 性能计时
|
||
request_start_time = time.time()
|
||
|
||
# 记录请求开始（此时文件已上传完成）
|
||
content_length = request.headers.get("content-length", "unknown")
|
||
logger.info(f"[{task_id}] 收到ASR请求, content_length={content_length}")
|
||
|
||
transcription_service = get_offline_transcription_service()
|
||
|
||
try:
|
||
# 验证请求头部（鉴权）
|
||
result, content = validate_token(request, task_id)
|
||
if not result:
|
||
raise AuthenticationException(content, task_id)
|
||
|
||
model_id = validate_offline_model_id(params.model)
|
||
|
||
# 使用音频服务处理音频
|
||
target_sample_rate = int(params.sample_rate) if params.sample_rate else 16000
|
||
prepared_audio = await transcription_service.prepare_from_request(
|
||
request=request,
|
||
audio_address=params.audio_address,
|
||
task_id=task_id,
|
||
sample_rate=target_sample_rate,
|
||
)
|
||
|
||
logger.info(f"[{task_id}] 开始调用 transcribe_long_audio (enable_speaker_diarization={params.enable_speaker_diarization})...")
|
||
asr_result = await transcription_service.transcribe(
|
||
prepared_audio,
|
||
OfflineTranscriptionOptions(
|
||
model_id=model_id,
|
||
sample_rate=int(params.sample_rate or SampleRate.RATE_16000),
|
||
hotwords=params.vocabulary_id or "",
|
||
enable_speaker_diarization=params.enable_speaker_diarization is not False,
|
||
enable_speaker_identification=(
|
||
params.enable_speaker_diarization is not False
|
||
and params.enable_speaker_identification is not False
|
||
),
|
||
enable_text_cleanup=params.enable_text_cleanup is not False,
|
||
word_timestamps=(
|
||
settings.ASR_ENABLE_WORD_TIMESTAMPS
|
||
and params.word_timestamps is True
|
||
),
|
||
task_id=task_id,
|
||
),
|
||
)
|
||
|
||
logger.info(f"[{task_id}] 识别完成，共 {len(asr_result.segments)} 个分段，总字符: {len(asr_result.text)}")
|
||
|
||
# 构建分段结果（始终返回 segments，短音频也是 1 个 segment）
|
||
segments_data = []
|
||
for seg in asr_result.segments:
|
||
seg_dict = {
|
||
"text": seg.text,
|
||
"start_time": round(seg.start_time, 2),
|
||
"end_time": round(seg.end_time, 2),
|
||
}
|
||
if seg.speaker_id:
|
||
seg_dict["speaker_id"] = seg.speaker_id
|
||
if seg.speaker_name:
|
||
seg_dict["speaker_name"] = seg.speaker_name
|
||
if seg.user_id:
|
||
seg_dict["user_id"] = seg.user_id
|
||
# 添加字词级时间戳（如果存在）
|
||
if seg.word_tokens:
|
||
seg_dict["word_tokens"] = [
|
||
{
|
||
"text": wt.text,
|
||
"start_time": round(wt.start_time, 3),
|
||
"end_time": round(wt.end_time, 3),
|
||
}
|
||
for wt in seg.word_tokens
|
||
]
|
||
segments_data.append(seg_dict)
|
||
|
||
# 计算请求处理时间
|
||
request_duration = time.time() - request_start_time
|
||
|
||
# 返回成功响应（统一数据结构）
|
||
response_data = {
|
||
"task_id": task_id,
|
||
"result": asr_result.text,
|
||
"status": 200,
|
||
"message": "SUCCESS",
|
||
"segments": segments_data,
|
||
"duration": round(asr_result.duration, 2),
|
||
"processing_time": round(request_duration, 3),
|
||
}
|
||
|
||
return JSONResponse(content=response_data, headers={"task_id": task_id})
|
||
|
||
except (
|
||
AuthenticationException,
|
||
InvalidParameterException,
|
||
InvalidMessageException,
|
||
UnsupportedSampleRateException,
|
||
DefaultServerErrorException,
|
||
) as e:
|
||
e.task_id = task_id
|
||
logger.error(f"[{task_id}] ASR异常: {e.message}")
|
||
|
||
# 使用标准错误格式
|
||
response_data = e.to_dict()
|
||
return JSONResponse(
|
||
content=response_data,
|
||
headers={"task_id": task_id},
|
||
status_code=get_http_status_code(e.status_code),
|
||
)
|
||
|
||
except Exception as e:
|
||
logger.error(f"[{task_id}] 未知异常: {str(e)}")
|
||
|
||
# 使用标准错误格式
|
||
from ...core.exceptions import create_error_response
|
||
response_data = create_error_response(
|
||
error_code="DEFAULT_SERVER_ERROR",
|
||
message=f"内部服务错误: {str(e)}",
|
||
task_id=task_id,
|
||
)
|
||
return JSONResponse(content=response_data, headers={"task_id": task_id})
|
||
|
||
finally:
|
||
transcription_service.cleanup(prepared_audio)
|
||
|
||
|
||
@router.get(
|
||
"/asr/health",
|
||
response_model=ASRHealthCheckResponse,
|
||
summary="ASR 服务健康检查",
|
||
description="""
|
||
检查语音识别服务的运行状态和资源使用情况。
|
||
|
||
## 返回信息
|
||
- **status**: 服务状态（healthy/unhealthy/error）
|
||
- **model_loaded**: 默认模型是否已加载
|
||
- **device**: 当前推理设备（cuda:0/cpu）
|
||
- **loaded_models**: 已加载的模型列表
|
||
- **memory_usage**: GPU 显存使用情况（仅 GPU 模式）
|
||
""",
|
||
)
|
||
async def health_check(request: Request):
|
||
"""ASR服务健康检查端点"""
|
||
# 鉴权
|
||
result, content = validate_token(request)
|
||
if not result:
|
||
raise AuthenticationException(content, "health_check")
|
||
|
||
try:
|
||
# 尝试获取默认模型的引擎
|
||
try:
|
||
runtime_router = get_runtime_router()
|
||
default_model = runtime_router.resolve_model_id(None)
|
||
async with await runtime_router.acquire_engine(default_model) as engine:
|
||
model_loaded = True
|
||
device = engine.device
|
||
except Exception:
|
||
model_loaded = False
|
||
device = "unknown"
|
||
|
||
runtime_router = get_runtime_router()
|
||
memory_info = runtime_router.get_memory_usage()
|
||
loaded_models = runtime_router.get_loaded_model_ids()
|
||
accelerator_info = memory_info.get("accelerator")
|
||
|
||
return {
|
||
"status": "healthy" if model_loaded else "unhealthy",
|
||
"model_loaded": model_loaded,
|
||
"device": device,
|
||
"version": settings.APP_VERSION,
|
||
"message": (
|
||
"ASR service is running normally"
|
||
if model_loaded
|
||
else "ASR model not loaded"
|
||
),
|
||
"loaded_models": loaded_models,
|
||
"memory_usage": memory_info.get("gpu_memory"),
|
||
"accelerator": accelerator_info,
|
||
}
|
||
except Exception as e:
|
||
return {
|
||
"status": "error",
|
||
"model_loaded": False,
|
||
"device": "unknown",
|
||
"version": settings.APP_VERSION,
|
||
"message": str(e),
|
||
"accelerator": None,
|
||
}
|
||
|
||
@router.get(
|
||
"/asr/models",
|
||
response_model=ASRModelsResponse,
|
||
summary="获取声明条目列表",
|
||
description="""
|
||
返回系统声明的离线模型与 realtime capability 信息。
|
||
|
||
## 条目说明
|
||
|
||
| ID | 类型 | 说明 |
|
||
|----|------|------|
|
||
| qwen3-asr-1.7b | model | 离线/实时共用的 Qwen3-ASR 模型条目 |
|
||
| qwen3-asr-0.6b | model | 轻量版 Qwen3-ASR 模型条目 |
|
||
## 返回信息
|
||
- **declared_entries**: 声明的模型与 capability 列表
|
||
- **declared_count**: 声明项总数
|
||
- **runtime**: 运行时加载状态
|
||
""",
|
||
)
|
||
async def list_models(request: Request):
|
||
"""获取声明条目列表端点"""
|
||
# 鉴权
|
||
result, content = validate_token(request)
|
||
if not result:
|
||
raise AuthenticationException(content, "list_models")
|
||
|
||
try:
|
||
|
||
model_manager = get_model_manager()
|
||
runtime_router = get_runtime_router()
|
||
loaded_model_ids = runtime_router.get_loaded_model_ids()
|
||
entries = model_manager.list_declared_entries()
|
||
|
||
return {
|
||
"declared_entries": entries,
|
||
"declared_count": len(entries),
|
||
"runtime": {
|
||
"loaded_model_ids": loaded_model_ids,
|
||
"loaded_count": len(loaded_model_ids),
|
||
"default_offline_model_id": runtime_router.resolve_model_id(None),
|
||
},
|
||
}
|
||
except Exception as e:
|
||
logger.error(f"获取模型列表时发生错误: {str(e)}")
|
||
raise HTTPException(status_code=500, detail=f"获取模型列表失败: {str(e)}")
|