53 lines
2.2 KiB
Markdown
53 lines
2.2 KiB
Markdown
# VoxCPM 常见问题与修复记录
|
||
|
||
本文档记录了在 Windows 环境下部署 VoxCPM 时遇到的常见问题及其修复方案。
|
||
|
||
## 1. 依赖安装失败 (`editdistance` 构建错误)
|
||
|
||
### 问题描述
|
||
在执行 `pip install` 安装依赖时，`funasr` 的依赖项 `editdistance` 在 Windows + Python 3.13 环境下编译失败，报错涉及 C++ 语法错误。
|
||
|
||
### 原因
|
||
`editdistance` 缺少适配 Python 3.13 的预编译 Wheel 包，且本地编译环境（MSVC）存在兼容性问题。
|
||
|
||
### 解决方案
|
||
1. **修改 `pyproject.toml`**：从依赖列表中暂时移除 `funasr`。
|
||
2. **代码适配**：在 `app.py` 中将 `funasr` 改为可选依赖（Optional Import）。如果未安装，ASR（自动语音识别）功能将自动禁用，但不影响核心 TTS 功能。
|
||
|
||
```python
|
||
try:
|
||
from funasr import AutoModel
|
||
HAS_FUNASR = True
|
||
except ImportError:
|
||
HAS_FUNASR = False
|
||
print("Warning: funasr not installed. ASR features will be disabled.")
|
||
# Dummy class for type hinting
|
||
class AutoModel: pass
|
||
```
|
||
|
||
## 2. 模型文件加载失败 (`FileNotFoundError: audiovae.pth`)
|
||
|
||
### 问题描述
|
||
运行 `app.py` 时报错 `FileNotFoundError: [Errno 2] No such file or directory: '.../audiovae.pth'`。
|
||
|
||
### 原因
|
||
模型下载过程可能中断或不完整。原有的检查逻辑仅验证了目录和 `config.json` 是否存在，未验证核心权重文件（如 `audiovae.pth`）。
|
||
|
||
### 解决方案
|
||
优化了 `app.py` 中的 `_resolve_model_dir` 函数：
|
||
1. **增加完整性检查**：验证 `config.json`、`audiovae.pth` 以及权重文件（`.safetensors` 或 `.bin`）是否齐全。
|
||
2. **自动修复**：检测到文件缺失时，自动删除损坏的目录并重新触发 HuggingFace 下载。
|
||
|
||
## 3. Gradio 界面报错与类型提示问题
|
||
|
||
### 问题描述
|
||
1. **Linter 报错**：`AutoModel` 可能未绑定。
|
||
2. **API 参数错误**：`show_progress=True` 导致类型错误。
|
||
|
||
### 解决方案
|
||
1. **类型修复**：在 `ImportError` 分支中添加 `class AutoModel: pass` 空类定义，解决静态类型检查报错。
|
||
2. **参数修正**：将 `run_btn.click` 中的 `show_progress=True` 修改为 `show_progress="full"`，适配新版 Gradio API。
|
||
|
||
---
|
||
*文档生成时间：2025-12-12*
|