ydy0615
7985fe9641
Introduce a comprehensive TTS/ASR module that: - Adds /v1/tts-asr/config, /status, /warmup, /tts, /asr endpoints with detailed JSON responses - Implements Apple‑Silicon detection, device selection (MPS/CUDA/CPU), and memory limiting logic - Supports selectable model size, quantization, and offline mode via environment variables - Adds robust audio validation and multi‑path resampling fallback - Provides new README sections for API usage, device detection, and performance benchmarking - Includes a full testing suite: unit tests, integration tests, macOS simulation and performance reports - Updates backend dependencies and CI scripts - Adds new front‑end views and components for Univer editor integration All changes are backward compatible; new features are exposed through environment variables and new API routes.
454 lines
11 KiB
Markdown
454 lines
11 KiB
Markdown
# TTS/ASR 测试指南
|
||
|
||
本文档提供完整的测试脚本使用说明，包括单元测试、集成测试和macOS环境模拟测试。
|
||
|
||
## 测试脚本概览
|
||
|
||
| 脚本 | 位置 | 用途 | 需要后端服务 |
|
||
|------|------|------|--------------|
|
||
| `test_tts_asr_unit.py` | `backend/tests/` | 单元测试（设备检测、模型选择、音频处理） | 否 |
|
||
| `test_tts_asr_integration.py` | `backend/tests/` | 集成测试（API端点、完整流程） | 是 |
|
||
| `simulate_macos.py` | `backend/tests/` | macOS环境模拟（在非Mac环境测试） | 否 |
|
||
|
||
## 快速开始
|
||
|
||
### 1. 单元测试（推荐首先运行）
|
||
|
||
单元测试不需要实际运行模型或后端服务，测试代码逻辑：
|
||
|
||
```bash
|
||
# 使用pytest运行（推荐）
|
||
pytest backend/tests/test_tts_asr_unit.py -v
|
||
|
||
# 直接运行
|
||
python backend/tests/test_tts_asr_unit.py
|
||
|
||
# 运行特定测试类
|
||
pytest backend/tests/test_tts_asr_unit.py::TestAppleSiliconDetection -v
|
||
|
||
# 运行特定测试方法
|
||
pytest backend/tests/test_tts_asr_unit.py::TestAppleSiliconDetection::test_is_apple_silicon_on_darwin_arm64 -v
|
||
```
|
||
|
||
### 2. macOS环境模拟测试
|
||
|
||
在非macOS环境下模拟Apple Silicon环境：
|
||
|
||
```bash
|
||
# 运行完整模拟测试套件
|
||
python backend/tests/simulate_macos.py --full-simulation
|
||
|
||
# 仅模拟Apple Silicon环境并进入交互模式
|
||
python backend/tests/simulate_macos.py --apple-silicon
|
||
|
||
# 模拟特定设备
|
||
python backend/tests/simulate_macos.py --device mps
|
||
python backend/tests/simulate_macos.py --device cuda
|
||
|
||
# 运行特定测试
|
||
python backend/tests/simulate_macos.py --test device # 设备检测
|
||
python backend/tests/simulate_macos.py --test memory # 内存管理
|
||
python backend/tests/simulate_macos.py --test model # 模型选择
|
||
python backend/tests/simulate_macos.py --test audio # 音频处理
|
||
python backend/tests/simulate_macos.py --test env # 环境变量
|
||
```
|
||
|
||
### 3. 集成测试
|
||
|
||
集成测试需要运行后端服务：
|
||
|
||
```bash
|
||
# 1. 启动后端服务（终端1）
|
||
python backend/main.py
|
||
|
||
# 2. 运行集成测试（终端2）
|
||
# 运行所有测试
|
||
python backend/tests/test_tts_asr_integration.py
|
||
|
||
# 运行特定测试
|
||
python backend/tests/test_tts_asr_integration.py --test config # 配置端点
|
||
python backend/tests/test_tts_asr_integration.py --test status # 状态端点
|
||
python backend/tests/test_tts_asr_integration.py --test warmup # 预热测试
|
||
python backend/tests/test_tts_asr_integration.py --test tts # TTS测试
|
||
python backend/tests/test_tts_asr_integration.py --test asr # ASR测试
|
||
python backend/tests/test_tts_asr_integration.py --test perf # 性能测试
|
||
|
||
# 自定义API地址
|
||
python backend/tests/test_tts_asr_integration.py --url http://localhost:8001 --key your-api-key
|
||
```
|
||
|
||
## 详细测试说明
|
||
|
||
### 单元测试详解
|
||
|
||
#### TestAppleSiliconDetection
|
||
|
||
测试Apple Silicon检测功能：
|
||
|
||
- `test_is_apple_silicon_on_darwin_arm64`: 在Darwin/arm64环境检测
|
||
- `test_is_apple_silicon_on_windows`: 在Windows环境不应检测到
|
||
- `test_is_apple_silicon_on_linux`: 在Linux环境不应检测到
|
||
|
||
#### TestEnvironmentVariables
|
||
|
||
测试环境变量解析：
|
||
|
||
- `test_default_environment_values`: 验证默认值
|
||
- `test_custom_environment_values`: 验证自定义值
|
||
|
||
#### TestModelSizeSelection
|
||
|
||
测试模型大小选择：
|
||
|
||
- `test_whisper_model_sizes_mapping`: 模型大小映射验证
|
||
- `test_recommended_model_size_explicit`: 显式指定大小
|
||
- `test_invalid_model_size_falls_back`: 无效大小回退
|
||
|
||
#### TestAudioValidation
|
||
|
||
测试音频验证：
|
||
|
||
- `test_validate_empty_audio`: 空音频验证
|
||
- `test_validate_valid_wav_header`: 有效WAV头验证
|
||
- `test_validate_invalid_audio`: 无效音频验证
|
||
|
||
#### TestAudioResampling
|
||
|
||
测试音频重采样：
|
||
|
||
- `test_resample_same_rate`: 相同采样率
|
||
- `test_resample_different_rate`: 不同采样率重采样
|
||
- `test_resample_downsample`: 下采样
|
||
|
||
#### TestDeviceCapabilities
|
||
|
||
测试设备能力检测：
|
||
|
||
- `test_device_capabilities_dataclass`: 数据类验证
|
||
- `test_device_capabilities_with_mps`: MPS设备能力
|
||
|
||
#### TestModelCacheCheck
|
||
|
||
测试模型缓存检查：
|
||
|
||
- `test_cache_check_non_offline_mode`: 非离线模式
|
||
- `test_cache_check_offline_mode_missing`: 离线模式缺失模型
|
||
|
||
#### TestRequestResponseModels
|
||
|
||
测试API模型：
|
||
|
||
- `test_tts_request_model`: TTS请求模型
|
||
- `test_asr_request_model`: ASR请求模型
|
||
- `test_model_status_model`: 状态模型
|
||
|
||
### 集成测试详解
|
||
|
||
#### TTSASRIntegrationTest
|
||
|
||
主要集成测试：
|
||
|
||
- `test_01_config_endpoint`: 配置端点测试
|
||
- `test_02_status_endpoint`: 状态端点测试
|
||
- `test_03_warmup_endpoint`: 预热端点测试
|
||
- `test_04_tts_endpoint_basic`: TTS基本功能测试
|
||
- `test_05_asr_endpoint_basic`: ASR基本功能测试
|
||
- `test_06_api_key_validation`: API密钥验证测试
|
||
- `test_07_tts_long_text`: TTS长文本测试
|
||
|
||
#### PerformanceTest
|
||
|
||
性能测试：
|
||
|
||
- `test_tts_latency`: TTS延迟测试
|
||
|
||
### macOS模拟测试详解
|
||
|
||
#### MacOSSimulator类
|
||
|
||
提供以下模拟功能：
|
||
|
||
- `simulate_apple_silicon()`: 模拟Darwin/arm64环境
|
||
- `simulate_mps_device()`: 模拟MPS设备可用
|
||
- `simulate_cuda_device()`: 模拟CUDA设备可用
|
||
- `cleanup()`: 清理模拟环境
|
||
|
||
#### 独立测试函数
|
||
|
||
- `test_device_detection_on_apple_silicon()`: Apple Silicon设备检测
|
||
- `test_memory_management()`: 内存管理测试
|
||
- `test_model_size_selection()`: 模型大小选择测试
|
||
- `test_audio_processing()`: 音频处理测试
|
||
- `test_environment_variables()`: 环境变量测试
|
||
|
||
## 测试覆盖率
|
||
|
||
### 单元测试覆盖的功能
|
||
|
||
- [x] Apple Silicon检测逻辑
|
||
- [x] 环境变量解析和默认值
|
||
- [x] 模型大小选择和推荐
|
||
- [x] 音频数据验证
|
||
- [x] 音频重采样（多回退方案）
|
||
- [x] 设备能力检测数据结构
|
||
- [x] 模型缓存检查
|
||
- [x] API请求/响应模型
|
||
|
||
### 集成测试覆盖的功能
|
||
|
||
- [x] 配置端点（`/v1/tts-asr/config`）
|
||
- [x] 状态端点（`/v1/tts-asr/status`）
|
||
- [x] 预热端点（`/v1/tts-asr/warmup`）
|
||
- [x] TTS端点（`/v1/tts-asr/tts`）
|
||
- [x] ASR端点（`/v1/tts-asr/asr`）
|
||
- [x] API密钥验证
|
||
- [x] 长文本处理
|
||
- [x] 性能基准测试
|
||
|
||
### macOS模拟测试覆盖的场景
|
||
|
||
- [x] Apple Silicon环境模拟
|
||
- [x] MPS设备模拟
|
||
- [x] CUDA设备模拟
|
||
- [x] 系统内存模拟
|
||
- [x] 完整环境变量测试
|
||
|
||
## 常见测试场景
|
||
|
||
### 场景1: 开发时快速验证
|
||
|
||
```bash
|
||
# 快速单元测试
|
||
pytest backend/tests/test_tts_asr_unit.py -v --tb=short
|
||
|
||
# macOS模拟（完整）
|
||
python backend/tests/simulate_macos.py --full-simulation
|
||
```
|
||
|
||
### 场景2: 验证特定配置
|
||
|
||
```bash
|
||
# 设置环境变量后测试
|
||
export TTS_ASR_MODEL_SIZE=small
|
||
export TTS_ASR_QUANTIZE=true
|
||
|
||
# 运行测试
|
||
python backend/tests/simulate_macos.py --test model
|
||
```
|
||
|
||
### 场景3: API功能验证
|
||
|
||
```bash
|
||
# 启动服务
|
||
python backend/main.py
|
||
|
||
# 测试配置端点
|
||
python backend/tests/test_tts_asr_integration.py --test config
|
||
|
||
# 测试TTS功能
|
||
python backend/tests/test_tts_asr_integration.py --test tts
|
||
|
||
# 测试ASR功能
|
||
python backend/tests/test_tts_asr_integration.py --test asr
|
||
```
|
||
|
||
### 场景4: 性能基准测试
|
||
|
||
```bash
|
||
# 启动服务
|
||
python backend/main.py
|
||
|
||
# 运行性能测试
|
||
python backend/tests/test_tts_asr_integration.py --test perf
|
||
```
|
||
|
||
## 测试输出解读
|
||
|
||
### 成功示例
|
||
|
||
```
|
||
test_is_apple_silicon_on_darwin_arm64 ... ok
|
||
test_is_apple_silicon_on_windows ... ok
|
||
test_is_apple_silicon_on_linux ... ok
|
||
|
||
----------------------------------------------------------------------
|
||
Ran 3 tests in 0.005s
|
||
|
||
OK
|
||
```
|
||
|
||
### 失败示例
|
||
|
||
```
|
||
test_device_detection_on_apple_silicon ... FAIL
|
||
|
||
======================================================================
|
||
FAIL: test_device_detection_on_apple_silicon
|
||
----------------------------------------------------------------------
|
||
Traceback (most recent call last):
|
||
File "test_tts_asr_unit.py", line 45, in test_is_apple_silicon_on_darwin_arm64
|
||
self.assertTrue(_is_apple_silicon())
|
||
AssertionError: False is not true
|
||
|
||
----------------------------------------------------------------------
|
||
Ran 1 tests in 0.002s
|
||
|
||
FAILED (failures=1)
|
||
```
|
||
|
||
## 持续集成配置
|
||
|
||
### GitHub Actions示例
|
||
|
||
```yaml
|
||
name: TTS/ASR Tests
|
||
|
||
on: [push, pull_request]
|
||
|
||
jobs:
|
||
unit-tests:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v3
|
||
- uses: actions/setup-python@v4
|
||
with:
|
||
python-version: '3.10'
|
||
- name: Install dependencies
|
||
run: |
|
||
pip install -r backend/requirements.txt
|
||
pip install pytest
|
||
- name: Run unit tests
|
||
run: pytest backend/tests/test_tts_asr_unit.py -v
|
||
- name: Run macOS simulation
|
||
run: python backend/tests/simulate_macos.py --full-simulation
|
||
```
|
||
|
||
### pytest配置
|
||
|
||
创建 `pytest.ini`:
|
||
|
||
```ini
|
||
[pytest]
|
||
testpaths = backend/tests
|
||
python_files = test_*.py
|
||
python_classes = Test*
|
||
python_functions = test_*
|
||
addopts = -v --tb=short
|
||
```
|
||
|
||
## 故障排查
|
||
|
||
### 问题1: 导入错误
|
||
|
||
```
|
||
ModuleNotFoundError: No module named 'backend'
|
||
```
|
||
|
||
**解决方案**:
|
||
|
||
```bash
|
||
# 确保在项目根目录运行
|
||
cd /path/to/llm-in-text
|
||
|
||
# 或设置PYTHONPATH
|
||
export PYTHONPATH="${PYTHONPATH}:$(pwd)"
|
||
```
|
||
|
||
### 问题2: 后端服务连接失败
|
||
|
||
```
|
||
✗ 无法连接到服务: [Errno 111] Connection refused
|
||
```
|
||
|
||
**解决方案**:
|
||
|
||
```bash
|
||
# 确保后端服务正在运行
|
||
python backend/main.py
|
||
|
||
# 检查端口
|
||
lsof -i :8001
|
||
|
||
# 或使用自定义URL
|
||
python backend/tests/test_tts_asr_integration.py --url http://localhost:8001
|
||
```
|
||
|
||
### 问题3: 模型未加载
|
||
|
||
```
|
||
⚠ TTS失败（可能是模型未加载）
|
||
```
|
||
|
||
**解决方案**:
|
||
|
||
这是预期行为，表示模型需要时间下载。可以：
|
||
|
||
1. 等待模型下载完成
|
||
2. 使用预热端点: `POST /v1/tts-asr/warmup`
|
||
3. 启用离线模式（如果模型已下载）
|
||
|
||
### 问题4: 测试超时
|
||
|
||
```
|
||
httpx.ReadTimeout: timed out
|
||
```
|
||
|
||
**解决方案**:
|
||
|
||
```bash
|
||
# 增加超时时间
|
||
export TEST_TIMEOUT=300.0
|
||
|
||
# 或在测试脚本中修改
|
||
TEST_TIMEOUT = 300.0 # 5分钟
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
1. **开发时**: 频繁运行单元测试
|
||
```bash
|
||
pytest backend/tests/test_tts_asr_unit.py -v --tb=short
|
||
```
|
||
|
||
2. **提交前**: 运行完整测试套件
|
||
```bash
|
||
pytest backend/tests/test_tts_asr_unit.py -v
|
||
python backend/tests/simulate_macos.py --full-simulation
|
||
```
|
||
|
||
3. **部署前**: 运行集成测试
|
||
```bash
|
||
python backend/tests/test_tts_asr_integration.py
|
||
```
|
||
|
||
4. **调试时**: 使用详细输出
|
||
```bash
|
||
pytest backend/tests/test_tts_asr_unit.py -v -s --tb=long
|
||
```
|
||
|
||
## 测试报告
|
||
|
||
生成测试覆盖率报告：
|
||
|
||
```bash
|
||
# 安装coverage
|
||
pip install pytest-cov
|
||
|
||
# 运行并生成报告
|
||
pytest backend/tests/test_tts_asr_unit.py --cov=backend.tts_asr --cov-report=html
|
||
|
||
# 查看报告
|
||
open htmlcov/index.html
|
||
```
|
||
|
||
## 相关文档
|
||
|
||
- [TTS/ASR修复说明](./TTS_ASR_MACOS_FIX.md)
|
||
- [环境变量配置](../README.md#ttsasr环境变量配置)
|
||
- [API文档](../README.md#api接口)
|
||
|
||
---
|
||
|
||
**更新日期**: 2026-04-06
|
||
**维护者**: 项目开发团队
|