NanoVLLM-VoxCPM¶

Nano-vLLM-VoxCPM 是基于 Nano-vLLM 的 VoxCPM 推理引擎。

仓库：a710128/nanovllm-voxcpm

提供 Python API（同步与异步流式）以及可选的 FastAPI 演示服务。

备注

该运行时以 GPU 为中心（CUDA + Triton + FlashAttention），不支持纯 CPU 运行。

支持的 VoxCPM 版本¶
VoxCPM 1.0（0.5B）	✅ 支持
VoxCPM 1.5	✅ 支持（默认）
VoxCPM 2	✅ 支持（从 `config.json` 自动检测 `voxcpm2` 架构）

主要特性¶

在 CUDA 设备上高吞吐（RTX 4090、H100、A100 等）
通过内部调度器并发处理请求
流式推理（按块产出波形）
可选的 HTTP 演示服务（FastAPI）
通过服务池实现多 GPU 请求级并行（每块 GPU 一个进程）

准备工作¶

Linux + NVIDIA GPU（CUDA）
Python >= 3.10，< 3.13
本地 VoxCPM checkpoint 目录

模型目录结构¶

Nano-vLLM-VoxCPM 从 *.safetensors 文件加载权重。模型目录至少应包含：

/path/to/model_dir/
├── config.json
├── audiovae.pth
└── *.safetensors

若 checkpoint 仅以 .pt / pytorch_model.bin 形式提供权重，请先转换为 safetensors。

安装¶

从 PyPI 安装：

pip install nano-vllm-voxcpm
# or
uv pip install nano-vllm-voxcpm

或从源码安装：

git clone https://github.com/a710128/nanovllm-voxcpm.git
cd nanovllm-voxcpm

# Recommended: use uv + lockfile
uv sync --frozen

基本用法（Python）¶

主入口为 nanovllm_voxcpm.VoxCPM.from_pretrained(...)。

生成音频（异步流式）¶

若在异步事件循环内调用，from_pretrained 返回异步服务池。

import asyncio
import numpy as np

from nanovllm_voxcpm import VoxCPM


async def main() -> None:
    server = VoxCPM.from_pretrained(
        model="/path/to/model_dir",
        devices=[0],
        max_num_batched_tokens=8192,
        max_num_seqs=16,
        gpu_memory_utilization=0.95,
    )
    await server.wait_for_ready()

    chunks: list[np.ndarray] = []
    async for chunk in server.generate(target_text="Hello world"):
        chunks.append(chunk)  # float32 numpy array

    wav = np.concatenate(chunks, axis=0)
    await server.stop()


if __name__ == "__main__":
    asyncio.run(main())

生成音频（同步）¶

若在事件循环外调用，from_pretrained 返回同步服务池。

import numpy as np

from nanovllm_voxcpm import VoxCPM


server = VoxCPM.from_pretrained(model="/path/to/model_dir", devices=[0])
chunks = [chunk for chunk in server.generate(target_text="Hello world")]
wav = np.concatenate(chunks, axis=0)
server.stop()

FastAPI 演示（HTTP）¶

仓库在 deployment/ 下提供 FastAPI 部署服务。

备注

FastAPI 演示服务未发布到 PyPI。请作为 uv workspace 成员从源码安装。

警告

FastAPI 演示并非生产就绪。在未采取额外安全措施前，请勿暴露到不可信网络。

安装部署所需扩展¶

uv sync --package nano-vllm-voxcpm-deployment --frozen

配置模型路径¶

设置环境变量 NANOVLLM_MODEL_PATH``（默认为 ``~/VoxCPM1.5）：

export NANOVLLM_MODEL_PATH=/path/to/model_dir

启动服务¶

uv run fastapi run deployment/app/main.py --host 0.0.0.0 --port 8000

然后打开：

http://localhost:8000/docs

/generate 端点以 MP3 流式返回音频：

Content-Type：audio/mpeg
载荷：MP3 字节流（流式）

问题排查¶

缺少参数 / 找不到权重¶

若出现类似错误：

ValueError: Missing parameters: ['base_lm.embed_tokens.weight', ...]

模型目录可能缺少 *.safetensors 权重（部分 VoxCPM 发行版仅含 .pt 文件）。请使用已转换为 safetensors 的 checkpoint，并确保 *.safetensors 与 config.json 位于同一目录。

启动缓慢¶

首次启动可能因模型加载与 GPU 显存分配而较慢，属正常现象。