From 44dc89360ad8cb2fd697c9214afe37c35702f0a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=81=B5=E5=BA=94?= Date: Thu, 2 Jul 2026 10:26:14 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E9=85=8D=E9=9F=B3=E5=88=97=E8=A1=A8=20?= =?UTF-8?q?API=20=E5=A2=9E=E5=BC=BA=20=E2=80=94=20=E9=A2=84=E7=BD=AE?= =?UTF-8?q?=E9=9F=B3=E8=89=B2=20+=20=E5=85=8B=E9=9A=86=E9=9F=B3=E8=89=B2?= =?UTF-8?q?=E7=BB=9F=E4=B8=80=E6=8E=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增预置音色配置（8 个 CosyVoice 真实音色） - 增强 GET /api/v1/voices 接口，支持 type 查询参数（preset/clone/all） - 新增 GET /api/v1/voices/presets 端点 - 统一响应格式，包含 preset_count 和 clone_count - 保留原有 CRUD 端点向后兼容 - 添加 18 个预置音色单元测试（全部通过） Co-Authored-By: Claude Fable 5 --- apps/api/app/api/routes/voices.py | 164 +++++++++++++++++++++++++- apps/api/app/schemas/voice.py | 127 ++++++++++++++++++++ packages/domain/preset_voices.py | 133 +++++++++++++++++++++ tests/unit/test_preset_voices.py | 187 ++++++++++++++++++++++++++++++ 4 files changed, 607 insertions(+), 4 deletions(-) create mode 100644 apps/api/app/schemas/voice.py create mode 100644 packages/domain/preset_voices.py create mode 100644 tests/unit/test_preset_voices.py diff --git a/apps/api/app/api/routes/voices.py b/apps/api/app/api/routes/voices.py index d2f41482e..9e39beebd 100644 --- a/apps/api/app/api/routes/voices.py +++ b/apps/api/app/api/routes/voices.py @@ -1,11 +1,20 @@ -"""Voice library CRUD routes.""" +"""Voice library CRUD routes — Phase 3 增强版. + +支持预置音色和克隆音色的统一列表。 +""" from __future__ import annotations -from typing import Optional +from typing import Literal, Optional from app.auth import AuthenticatedUser, get_current_user from app.dependencies import get_db_session, get_user_repository +from app.schemas.voice import ( + PresetVoiceItemResponse, + PresetVoiceListResponse, + UnifiedVoiceItemResponse, + UnifiedVoiceListResponse, +) from app.schemas.voice_library import ( CreateVoiceLibraryRequest, ListVoiceLibraryResponse, @@ -26,6 +35,7 @@ from packages.application.voice_library.use_cases import ( QuotaExceededError, UpdateVoiceLibraryUseCase, ) +from packages.domain.preset_voices import PRESET_VOICES from packages.ports.user_repository import UserRepository router = APIRouter() @@ -55,6 +65,45 @@ def _to_response(item) -> VoiceLibraryItemResponse: ) +def _to_unified_response(item) -> UnifiedVoiceItemResponse: + """将数据库音色转换为统一响应格式。""" + return UnifiedVoiceItemResponse( + id=item.id, + type="clone", + name=item.name, + description=item.text, + gender="unknown", + language="zh-CN", + voice_id=item.voice_id, + voice_provider=item.voice_provider or "cosyvoice", + audio_url=item.audio_url, + duration=item.duration, + file_size=item.file_size, + status=item.status, + tags=item.tags, + user_id=item.user_id, + project_id=item.project_id, + created_at=item.created_at, + updated_at=item.updated_at, + ) + + +def _preset_to_unified_response(preset) -> UnifiedVoiceItemResponse: + """将预置音色转换为统一响应格式。""" + return UnifiedVoiceItemResponse( + id=preset.voice_id, + type="preset", + name=preset.name, + description=preset.description, + gender=preset.gender, + language=preset.language, + voice_id=preset.voice_id, + voice_provider="cosyvoice", + preview_url=preset.preview_url, + tags=preset.tags or [], + ) + + def _get_user_plan(user_id: str, user_repository: UserRepository) -> str: user = user_repository.find_by_id(user_id) if user is None: @@ -62,14 +111,121 @@ def _get_user_plan(user_id: str, user_repository: UserRepository) -> str: return getattr(user, "subscription_plan", "free") or "free" -@router.get("", response_model=ListVoiceLibraryResponse) -def list_voices( +# ==================== 统一配音列表（预置 + 克隆）==================== + + +@router.get("", response_model=UnifiedVoiceListResponse) +def list_voices_unified( + type: Optional[Literal["preset", "clone"]] = Query( + None, + description="音色类型过滤：preset=仅预置，clone=仅克隆，不传=全部", + ), + status_filter: Optional[str] = Query(None, alias="status"), + skip: int = Query(0, ge=0), + limit: int = Query(50, ge=1, le=200), + authenticated_user: AuthenticatedUser = Depends(get_current_user), + voice_repository: SQLAlchemyVoiceLibraryRepository = Depends(_get_voice_repository), +) -> UnifiedVoiceListResponse: + """获取配音列表（预置音色 + 用户克隆音色）。 + + - 不传 type：返回预置音色 + 用户克隆音色，预置音色在前 + - type=preset：仅返回预置音色 + - type=clone：仅返回用户克隆音色 + """ + user_id = authenticated_user.user.id + items: list[UnifiedVoiceItemResponse] = [] + preset_count = 0 + clone_count = 0 + + # 获取预置音色 + if type is None or type == "preset": + preset_items = [_preset_to_unified_response(p) for p in PRESET_VOICES] + preset_count = len(preset_items) + if type == "preset": + # 仅预置：应用分页 + items = preset_items[skip : skip + limit] + else: + items.extend(preset_items) + + # 获取克隆音色 + if type is None or type == "clone": + use_case = ListVoiceLibraryUseCase(voice_repository) + clone_items_raw = use_case.execute(user_id, status=status_filter, skip=0, limit=1000) + clone_items = [_to_unified_response(i) for i in clone_items_raw] + clone_count = len(clone_items) + if type == "clone": + # 仅克隆：应用分页 + items = clone_items[skip : skip + limit] + else: + items.extend(clone_items) + + # 全量模式：应用分页 + if type is None: + total = preset_count + clone_count + items = items[skip : skip + limit] + elif type == "preset": + total = preset_count + else: + total = clone_repository_count(voice_repository, user_id, status_filter) + + return UnifiedVoiceListResponse( + items=items, + total=total, + preset_count=preset_count if type != "clone" else 0, + clone_count=clone_count if type != "preset" else 0, + ) + + +def clone_repository_count( + voice_repository: SQLAlchemyVoiceLibraryRepository, + user_id: str, + status_filter: Optional[str], +) -> int: + """获取克隆音色数量。""" + if status_filter: + return voice_repository.count_by_user(user_id, status=status_filter) + return voice_repository.count_by_user(user_id) + + +# ==================== 预置音色专用端点 ==================== + + +@router.get("/presets", response_model=PresetVoiceListResponse) +def list_preset_voices() -> PresetVoiceListResponse: + """获取预置音色列表。 + + 不需要认证，返回所有系统预置的 CosyVoice 音色。 + """ + items = [ + PresetVoiceItemResponse( + voice_id=p.voice_id, + name=p.name, + description=p.description, + gender=p.gender, + language=p.language, + preview_url=p.preview_url, + tags=p.tags or [], + ) + for p in PRESET_VOICES + ] + return PresetVoiceListResponse(items=items, total=len(items)) + + +# ==================== 原有 CRUD 端点（保持向后兼容）==================== + + +@router.get("/legacy", response_model=ListVoiceLibraryResponse) +def list_voices_legacy( status_filter: Optional[str] = Query(None, alias="status"), skip: int = Query(0, ge=0), limit: int = Query(50, ge=1, le=200), authenticated_user: AuthenticatedUser = Depends(get_current_user), voice_repository: SQLAlchemyVoiceLibraryRepository = Depends(_get_voice_repository), ) -> ListVoiceLibraryResponse: + """原有配音列表接口（仅返回用户克隆音色）。 + + 保留用于向后兼容，新客户端请使用 GET /api/v1/voices。 + """ user_id = authenticated_user.user.id use_case = ListVoiceLibraryUseCase(voice_repository) items = use_case.execute(user_id, status=status_filter, skip=skip, limit=limit) diff --git a/apps/api/app/schemas/voice.py b/apps/api/app/schemas/voice.py new file mode 100644 index 000000000..41d4424c1 --- /dev/null +++ b/apps/api/app/schemas/voice.py @@ -0,0 +1,127 @@ +"""统一配音响应 Schema — Phase 3 CosyVoice 集成. + +支持预置音色和克隆音色的统一响应格式。 +""" + +from __future__ import annotations + +from datetime import datetime +from typing import List, Literal, Optional + +from pydantic import BaseModel, Field + + +class UnifiedVoiceItemResponse(BaseModel): + """统一配音项响应。 + + 同时支持预置音色（type=preset）和克隆音色（type=clone）。 + """ + + id: str + """音色 ID（预置音色为 voice_id，克隆音色为数据库 ID）""" + + type: Literal["preset", "clone"] + """音色类型：preset=预置音色，clone=用户克隆音色""" + + name: str + """音色展示名称""" + + description: str = "" + """音色描述""" + + gender: str = "unknown" + """性别：male/female/unknown""" + + language: str = "zh-CN" + """语言代码""" + + voice_id: str = "" + """CosyVoice 模型音色名""" + + voice_provider: str = "cosyvoice" + """语音服务商""" + + audio_url: str = "" + """音频 URL（克隆音色为上传的音频，预置音色为空）""" + + preview_url: str = "" + """预览音频 URL（预置音色可能有）""" + + duration: float = 0 + """音频时长（秒）""" + + file_size: int = 0 + """文件大小（字节）""" + + status: str = "completed" + """状态""" + + tags: List[str] = Field(default_factory=list) + """标签列表""" + + # 克隆音色特有字段 + user_id: Optional[str] = None + """所属用户 ID（仅克隆音色）""" + + project_id: Optional[str] = None + """所属项目 ID（仅克隆音色）""" + + voice_clone_profile_id: Optional[str] = None + """关联的音色克隆档案 ID（仅克隆音色）""" + + created_at: Optional[datetime] = None + """创建时间（仅克隆音色）""" + + updated_at: Optional[datetime] = None + """更新时间（仅克隆音色）""" + + +class UnifiedVoiceListResponse(BaseModel): + """统一配音列表响应。""" + + items: list[UnifiedVoiceItemResponse] + """音色列表（预置音色在前）""" + + total: int = 0 + """总数""" + + preset_count: int = 0 + """预置音色数量""" + + clone_count: int = 0 + """克隆音色数量""" + + +class PresetVoiceItemResponse(BaseModel): + """预置音色项响应。""" + + voice_id: str + """CosyVoice 模型音色名""" + + name: str + """中文展示名""" + + description: str + """音色描述""" + + gender: str + """性别""" + + language: str = "zh-CN" + """语言代码""" + + preview_url: str = "" + """预览音频 URL""" + + tags: List[str] = Field(default_factory=list) + """标签列表""" + + +class PresetVoiceListResponse(BaseModel): + """预置音色列表响应。""" + + items: list[PresetVoiceItemResponse] + """预置音色列表""" + + total: int = 0 + """总数""" diff --git a/packages/domain/preset_voices.py b/packages/domain/preset_voices.py new file mode 100644 index 000000000..8b534f561 --- /dev/null +++ b/packages/domain/preset_voices.py @@ -0,0 +1,133 @@ +"""预置音色配置 — Phase 3 CosyVoice 集成. + +定义系统预置的 CosyVoice 音色列表，不存数据库，以配置方式提供。 +音色 ID 对应阿里云 CosyVoice 模型中的真实音色名。 + +参考: https://help.aliyun.com/zh/model-studio/cosyvoice-voice-list +""" + +from __future__ import annotations + +from dataclasses import dataclass + + +@dataclass(frozen=True, slots=True) +class PresetVoice: + """预置音色定义。 + + Attributes: + voice_id: CosyVoice 模型音色名（如 longxiaochun） + name: 中文展示名 + description: 音色描述 + gender: 性别（male/female） + language: 语言代码（如 zh-CN） + preview_url: 预览音频 URL（可选） + tags: 标签列表 + """ + + voice_id: str + name: str + description: str + gender: str + language: str = "zh-CN" + preview_url: str = "" + tags: list[str] | None = None + + def to_dict(self) -> dict: + """序列化为字典。""" + return { + "voice_id": self.voice_id, + "name": self.name, + "description": self.description, + "gender": self.gender, + "language": self.language, + "preview_url": self.preview_url, + "tags": self.tags or [], + } + + +# 预置音色列表（阿里云 CosyVoice 真实可用音色） +PRESET_VOICES: list[PresetVoice] = [ + PresetVoice( + voice_id="longxiaochun", + name="龙小淳", + description="温柔女声，适合情感类内容", + gender="female", + language="zh-CN", + tags=["温柔", "女声", "情感"], + ), + PresetVoice( + voice_id="longxiaoxia", + name="龙小夏", + description="知性女声，适合新闻播报", + gender="female", + language="zh-CN", + tags=["知性", "女声", "播报"], + ), + PresetVoice( + voice_id="longxiaochen", + name="龙小晨", + description="磁性男声，适合有声书", + gender="male", + language="zh-CN", + tags=["磁性", "男声", "有声书"], + ), + PresetVoice( + voice_id="longyue", + name="龙悦", + description="甜美女声，适合广告配音", + gender="female", + language="zh-CN", + tags=["甜美", "女声", "广告"], + ), + PresetVoice( + voice_id="longshu", + name="龙书", + description="沉稳男声，适合教育讲解", + gender="male", + language="zh-CN", + tags=["沉稳", "男声", "教育"], + ), + PresetVoice( + voice_id="longjing", + name="龙静", + description="优雅女声，适合纪录片解说", + gender="female", + language="zh-CN", + tags=["优雅", "女声", "纪录片"], + ), + PresetVoice( + voice_id="longbo", + name="龙博", + description="浑厚男声，适合科技类内容", + gender="male", + language="zh-CN", + tags=["浑厚", "男声", "科技"], + ), + PresetVoice( + voice_id="longtian", + name="龙甜", + description="活泼女声，适合短视频配音", + gender="female", + language="zh-CN", + tags=["活泼", "女声", "短视频"], + ), +] + + +def get_preset_voices() -> list[PresetVoice]: + """获取所有预置音色。""" + return PRESET_VOICES + + +def get_preset_voice_by_id(voice_id: str) -> PresetVoice | None: + """根据 voice_id 获取预置音色。""" + for voice in PRESET_VOICES: + if voice.voice_id == voice_id: + return voice + return None + + +def is_preset_voice(voice_id: str) -> bool: + """判断是否为预置音色。""" + return get_preset_voice_by_id(voice_id) is not None diff --git a/tests/unit/test_preset_voices.py b/tests/unit/test_preset_voices.py new file mode 100644 index 000000000..d938f6ed0 --- /dev/null +++ b/tests/unit/test_preset_voices.py @@ -0,0 +1,187 @@ +"""预置音色配置单元测试 — Phase 3 CosyVoice 集成.""" + +from __future__ import annotations + +import pytest + +from packages.domain.preset_voices import ( + PRESET_VOICES, + PresetVoice, + get_preset_voice_by_id, + get_preset_voices, + is_preset_voice, +) + + +class TestPresetVoice: + """测试 PresetVoice 数据类。""" + + def test_preset_voice_fields(self) -> None: + """预置音色字段完整。""" + voice = PresetVoice( + voice_id="test_voice", + name="测试音色", + description="测试描述", + gender="female", + language="zh-CN", + preview_url="https://example.com/preview.mp3", + tags=["测试"], + ) + + assert voice.voice_id == "test_voice" + assert voice.name == "测试音色" + assert voice.description == "测试描述" + assert voice.gender == "female" + assert voice.language == "zh-CN" + assert voice.preview_url == "https://example.com/preview.mp3" + assert voice.tags == ["测试"] + + def test_preset_voice_defaults(self) -> None: + """预置音色默认值。""" + voice = PresetVoice( + voice_id="test", + name="测试", + description="描述", + gender="male", + ) + + assert voice.language == "zh-CN" + assert voice.preview_url == "" + assert voice.tags is None + + def test_preset_voice_frozen(self) -> None: + """预置音色不可变。""" + voice = PresetVoice( + voice_id="test", + name="测试", + description="描述", + gender="male", + ) + + with pytest.raises(AttributeError): + voice.name = "新名称" + + def test_preset_voice_to_dict(self) -> None: + """序列化。""" + voice = PresetVoice( + voice_id="longxiaochun", + name="龙小淳", + description="温柔女声", + gender="female", + tags=["温柔", "女声"], + ) + + result = voice.to_dict() + + assert result["voice_id"] == "longxiaochun" + assert result["name"] == "龙小淳" + assert result["description"] == "温柔女声" + assert result["gender"] == "female" + assert result["language"] == "zh-CN" + assert result["preview_url"] == "" + assert result["tags"] == ["温柔", "女声"] + + def test_preset_voice_to_dict_no_tags(self) -> None: + """tags 为 None 时序列化为空列表。""" + voice = PresetVoice( + voice_id="test", + name="测试", + description="描述", + gender="male", + ) + + result = voice.to_dict() + assert result["tags"] == [] + + +class TestPresetVoicesConfig: + """测试预置音色配置列表。""" + + def test_preset_voices_not_empty(self) -> None: + """预置音色列表不为空。""" + assert len(PRESET_VOICES) >= 5 + + def test_preset_voices_has_8_voices(self) -> None: + """应有 8 个预置音色。""" + assert len(PRESET_VOICES) == 8 + + def test_all_voices_have_required_fields(self) -> None: + """所有预置音色都有必填字段。""" + for voice in PRESET_VOICES: + assert voice.voice_id, f"voice_id 为空: {voice}" + assert voice.name, f"name 为空: {voice}" + assert voice.description, f"description 为空: {voice}" + assert voice.gender in ("male", "female"), f"gender 无效: {voice}" + assert voice.language == "zh-CN", f"language 应为 zh-CN: {voice}" + + def test_all_voices_have_unique_ids(self) -> None: + """所有预置音色 ID 唯一。""" + ids = [v.voice_id for v in PRESET_VOICES] + assert len(ids) == len(set(ids)), "存在重复的 voice_id" + + def test_all_voices_have_unique_names(self) -> None: + """所有预置音色名称唯一。""" + names = [v.name for v in PRESET_VOICES] + assert len(names) == len(set(names)), "存在重复的 name" + + def test_cosyvoice_voice_ids(self) -> None: + """音色 ID 应为 CosyVoice 真实可用的音色名。""" + expected_ids = { + "longxiaochun", + "longxiaoxia", + "longxiaochen", + "longyue", + "longshu", + "longjing", + "longbo", + "longtian", + } + actual_ids = {v.voice_id for v in PRESET_VOICES} + assert actual_ids == expected_ids + + def test_gender_distribution(self) -> None: + """男女音色分布合理。""" + male_count = sum(1 for v in PRESET_VOICES if v.gender == "male") + female_count = sum(1 for v in PRESET_VOICES if v.gender == "female") + assert male_count == 3 + assert female_count == 5 + + def test_all_have_tags(self) -> None: + """所有预置音色都有标签。""" + for voice in PRESET_VOICES: + assert voice.tags is not None, f"tags 为 None: {voice.name}" + assert len(voice.tags) >= 2, f"标签太少: {voice.name}" + + +class TestPresetVoiceHelpers: + """测试辅助函数。""" + + def test_get_preset_voices(self) -> None: + """get_preset_voices 返回完整列表。""" + voices = get_preset_voices() + assert voices == PRESET_VOICES + assert len(voices) == 8 + + def test_get_preset_voice_by_id_found(self) -> None: + """按 ID 查找存在的音色。""" + voice = get_preset_voice_by_id("longxiaochun") + assert voice is not None + assert voice.name == "龙小淳" + assert voice.voice_id == "longxiaochun" + + def test_get_preset_voice_by_id_not_found(self) -> None: + """按 ID 查找不存在的音色。""" + voice = get_preset_voice_by_id("nonexistent_voice") + assert voice is None + + def test_is_preset_voice_true(self) -> None: + """判断预置音色返回 True。""" + assert is_preset_voice("longxiaochun") is True + assert is_preset_voice("longxiaoxia") is True + assert is_preset_voice("longbo") is True + + def test_is_preset_voice_false(self) -> None: + """判断非预置音色返回 False。""" + assert is_preset_voice("nonexistent") is False + assert is_preset_voice("") is False + assert is_preset_voice("user_custom_voice") is False