feat(#1195): 新增克隆音色试听接口 /voice-clones/{id}/preview #1201

Merged

xiaoxia merged 3 commits from feat/voice-clone-preview-1195 into develop 2026-07-30 16:47:50 +08:00

Conversation 3 Commits 3 Files Changed 4

+388 -2

xiaoxia commented 2026-07-30 14:02:53 +08:00

Owner

Copy Link

Copy Source

功能

• 新增 GET /api/v1/voice-clones/{clone_id}/preview 端点
• 克隆音色 ready 状态下可实时 TTS 合成试听音频
• 支持默认试听文本（缓存7天）和自定义文本
• 对应前端 #1195 克隆音色不能播放

变更

• apps/api/app/schemas/voice_clone.py: 新增 VoiceClonePreviewResponse
• apps/api/app/api/routes/voice_clones.py: 新增 preview 路由
• tests/unit/test_voice_clone_preview.py: 10个单元测试

测试

本地10个单测全绿，覆盖：

• ✅ 正常试听（ready状态）
• ✅ 自定义试听文本
• ✅ 404（克隆不存在）
• ✅ 400（pending/processing/failed 状态）
• ✅ 502（TTS合成失败）
• ✅ 缓存机制（默认文本）
• ✅ 自定义文本不缓存
• ✅ 非所有者无权限

## 功能 - 新增 `GET /api/v1/voice-clones/{clone_id}/preview` 端点 - 克隆音色 ready 状态下可实时 TTS 合成试听音频 - 支持默认试听文本（缓存7天）和自定义文本 - 对应前端 #1195 克隆音色不能播放 ## 变更 - apps/api/app/schemas/voice_clone.py: 新增 VoiceClonePreviewResponse - apps/api/app/api/routes/voice_clones.py: 新增 preview 路由 - tests/unit/test_voice_clone_preview.py: 10个单元测试 ## 测试 本地10个单测全绿，覆盖： - ✅ 正常试听（ready状态） - ✅ 自定义试听文本 - ✅ 404（克隆不存在） - ✅ 400（pending/processing/failed 状态） - ✅ 502（TTS合成失败） - ✅ 缓存机制（默认文本） - ✅ 自定义文本不缓存 - ✅ 非所有者无权限

xiaoxia added 1 commit 2026-07-30 14:02:53 +08:00

feat(#1195): 新增克隆音色试听接口 /voice-clones/{id}/preview ... 1437120634

- 新增 GET /voice-clones/{clone_id}/preview 端点
- 支持默认试听文本（缓存7天）和自定义文本
- 状态校验：仅 ready 状态可试听
- 10 个单元测试覆盖成功/失败/缓存/权限等场景

gitea-actions bot commented 2026-07-30 14:04:40 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#1201
预览链接	https://pr-1201.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #1201 | | 预览链接 | [https://pr-1201.preview.xiaoxiajianji.com](https://pr-1201.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

xiaoxia added 1 commit 2026-07-30 14:31:25 +08:00

fix(test): 修复voice_clone_preview测试污染GetVoiceCloneUseCase类的问题 ... d6dfb48687

测试中用delattr删除了类原生execute方法，导致后续测试文件
test_voice_clone_use_cases.py中GetVoiceCloneUseCase.execute丢失。
改为保存原始方法并在finally中恢复。

xiaoxia force-pushed feat/voice-clone-preview-1195 from 52ead68415 to d6dfb48687 2026-07-30 14:31:25 +08:00 Compare

auto-approve-bot added 1 commit 2026-07-30 14:33:56 +08:00

style: auto-format with black + isort + prettier [skip ci-format-check] b23bd2a942

auto-approve-bot commented 2026-07-30 14:38:13 +08:00

Collaborator

Copy Link

Copy Source

代码审查结果 - PR #1201

⚠️ 问题（2个需要修改）

1. apps/api/app/api/routes/voice_clones.py 第251-263行：缓存逻辑存在并发安全问题（竞态条件/惊群效应）。
   • 代码在检查缓存（if clone_id in _clone_preview_cache）和写入缓存（_clone_preview_cache[clone_id] = ...）之间存在时间窗口。由于 synthesize_speech 是耗时操作，在多线程/并发环境下，多个请求可能同时通过缓存检查，导致对同一个 clone_id 重复调用昂贵的 TTS 接口，造成资源浪费和计费异常。
2. apps/api/app/api/routes/voice_clones.py 第40行：全局缓存字典存在内存泄漏风险。
   • _clone_preview_cache 为全局字典，仅在读操作时检查 TTL，从未有过期清理机制。随着时间推移，如果 clone_id 不断增长或产生大量废弃 ID，该字典将无限膨胀，导致服务内存溢出（OOM）。

💡 建议（2个可选）

1. apps/api/app/api/routes/voice_clones.py 第236行：建议增加 text 参数的长度校验。
   • 目前直接将用户传入的 text 传递给下游 TTS 服务。如果用户传入超长文本，可能导致请求耗时过长或费用异常。建议限制最大长度（如 500 字符）。
2. apps/api/app/schemas/voice_clone.py：Python 源码文件不应具有可执行权限。
   • Diff 显示该文件权限从 100644 变更为 100755。Python 脚本通常不需要可执行权限，这不符合安全最佳实践和 Git 规范。

---

✅ 格式检查通过 | ❌ 逻辑审查审查需修改 | ⚠️ 建议关注性能

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-07-30 06:38:12 | 模型:}

## 代码审查结果 - PR #1201 ### ⚠️ 问题（2个需要修改） 1. **apps/api/app/api/routes/voice_clones.py 第251-263行**：缓存逻辑存在并发安全问题（竞态条件/惊群效应）。 - 代码在检查缓存（`if clone_id in _clone_preview_cache`）和写入缓存（`_clone_preview_cache[clone_id] = ...`）之间存在时间窗口。由于 `synthesize_speech` 是耗时操作，在多线程/并发环境下，多个请求可能同时通过缓存检查，导致对同一个 `clone_id` 重复调用昂贵的 TTS 接口，造成资源浪费和计费异常。 2. **apps/api/app/api/routes/voice_clones.py 第40行**：全局缓存字典存在内存泄漏风险。 - `_clone_preview_cache` 为全局字典，仅在读操作时检查 TTL，从未有过期清理机制。随着时间推移，如果 `clone_id` 不断增长或产生大量废弃 ID，该字典将无限膨胀，导致服务内存溢出（OOM）。 ### 💡 建议（2个可选） 1. **apps/api/app/api/routes/voice_clones.py 第236行**：建议增加 `text` 参数的长度校验。 - 目前直接将用户传入的 `text` 传递给下游 TTS 服务。如果用户传入超长文本，可能导致请求耗时过长或费用异常。建议限制最大长度（如 500 字符）。 2. **apps/api/app/schemas/voice_clone.py**：Python 源码文件不应具有可执行权限。 - Diff 显示该文件权限从 `100644` 变更为 `100755`。Python 脚本通常不需要可执行权限，这不符合安全最佳实践和 Git 规范。 --- ✅ 格式检查通过 | ❌ 逻辑审查审查需修改 | ⚠️ 建议关注性能 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-07-30 06:38:12 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

xiaoxia merged commit c861e90289 into develop 2026-07-30 16:47:50 +08:00

gitea-actions bot commented 2026-07-30 16:48:37 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #1201 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #1201 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1201