VoxCPM2

VoxCPM2 是 OpenBMB 开源的 TTS 模型，支持声音克隆。OpenMAIC 自带适配器，把 VoxCPM 跑在自己机器上即可对接。

什么时候用 VoxCPM2

如果只想要一个默认音色，用内置的豆包或 OpenAI 兼容 提供方更简单，参见配置 → TTS 提供方。

OpenMAIC 支持三种部署形态。三种走的是同一个 OpenMAIC 适配器，你只需要在设置里切换对应的后端类型即可。

后端	端点	适用场景
vLLM-Omni	`/v1/audio/speech`	OpenAI 兼容的语音端点，适合 GPU 服务器。
Python API	`/tts/upload`	VoxCPM 官方 Python runtime（基于 FastAPI）。
Nano-vLLM	`/generate`	轻量的 Nano-vLLM FastAPI 部署，适合小机器。

每种后端的具体启动方式见 VoxCPM 仓库。一个典型的本地快速启动：

# vLLM-Omni 示例
pip install vllm
python -m vllm_omni.server --model openbmb/VoxCPM2 --port 8000
# 端点为 http://localhost:8000/v1

两种方式选一种。

打开 设置 → 语音合成 → VoxCPM2，选择后端类型，粘贴 Base URL。下方的 Request URL 预览会显示 OpenMAIC 实际请求的地址。

这条路适合个人测试和按浏览器覆盖配置，不会影响其他用户。

在 .env.local 或 YAML 配置里加上下面一行，不需要 API key。

TTS_VOXCPM_BASE_URL=http://localhost:8000/v1

服务端配置会下发给用户；如果 provider 由服务端托管，客户端不能覆盖这些配置。

VoxCPM2 有三种声音模式，都在 设置 → 语音合成 → VoxCPM2 → VoxCPM 音色 里。

OpenMAIC 在合成时根据每个 Agent 的人设动态生成 voice prompt。无需任何配置，什么都不做就是这个效果。

用自然语言描述音色。生成后可以复用，分配给任意 Agent。

示例："温暖的女老师声音，平稳鼓励，中音域，吐字清晰。"

上传一段短的参考音频（≤ 60 秒，≤ 10 MB），或者直接在浏览器里录一段。音频存在 IndexedDB 中，每次合成时发给后端。

现象	可能原因
Request URL 预览返回 404	后端类型选错了，对照第 1 步的端点表。
第一次克隆请求要等 ~30s	后端冷启动，后续克隆会复用热运行时。
音频说到一半就断	后端输出 token 数受限，提高 `--max-tokens` 或对应 VoxCPM 配置。
401 / 403	给一个不需要 key 的后端配了 `TTS_VOXCPM_API_KEY`，留空即可。