audio.cpp 详细部署教程

1. 项目简介

audio.cpp 是一个基于 ggml 构建的全功能纯 C++ 音频模型推理引擎，支持文本转语音（TTS）、语音识别（ASR）、语音活动检测（VAD）、声音转换、音乐生成等多种音频任务 。该项目最大的特点是完全无需 Python 依赖，通过 CUDA、HIP/ROCm、Vulkan、Metal 和 CPU 等多种后端实现跨平台部署 。

核心特性：

  • 多模型支持：截至 Release 0.7，已覆盖 62 个模型系列和 85+ 模型变体，包括 Higgs Audio、Fish Audio、Chatterbox、Supertonic 3、ACE-Step 等
  • 多任务覆盖：支持 TTS、语音克隆、语音转换、ASR、说话人日志、VAD、音源分离、音乐生成等
  • 性能优化：CUDA 优化显著，部分 TTS 路径比 Python 参考实现快 1.8x 至 10x
  • GGUF 支持：所有已发布模型系列均支持 GGUF 加载，Q8 量化可减少约 37% 的显存占用
  • WebUI 界面：提供 Gradio 网页界面，支持模型加载、语音上传、参数调节等功能

系统要求：

组件 要求
操作系统 Windows、Linux、macOS
GPU（可选） NVIDIA（CUDA）、AMD（HIP/ROCm）、Apple Silicon（Metal）、支持 Vulkan 的设备
构建工具 CMake、Ninja、C++ 编译器（MSVC/GCC/Clang）

2. 安装方式概览

audio.cpp 提供多种安装方式，根据使用场景选择：

安装方式 适用场景 优势
Windows 预编译包 Windows 用户快速上手 无需编译，开箱即用
Homebrew 安装 macOS 用户 一行命令完成安装
源码编译 开发者定制 完全可控，支持所有后端
Nix 构建 NixOS 用户 声明式配置，可复现构建

3. 方式一：Windows 预编译包（推荐）

这是 Windows 用户最简单的部署方式，无需编译。

3.1 下载预编译包

根据你的硬件配置选择合适的包 ：

CPU 版本（自包含）：

  • audiocpp-windows-cpu-fast.zip — 针对本机 CPU 优化，速度最快
  • audiocpp-windows-cpu-balance.zip — 平衡兼容性与性能（推荐大多数用户）
  • audiocpp-windows-cpu-portable.zip — 最大兼容性，适合老旧 CPU

CUDA 版本（需先下载运行时包）：

  • audiocpp-windows-cuda-runtime.zip — CUDA 运行时 DLL（必需）
  • audiocpp-windows-cuda-fast.zip / balance.zip / portable.zip — 选择其一

推荐组合：

  • NVIDIA GPU 用户：audiocpp-windows-cuda-runtime.zip + audiocpp-windows-cuda-balance.zip
  • 仅 CPU 用户：audiocpp-windows-cpu-balance.zip

3.2 解压与运行

将下载的 zip 文件解压到任意目录，然后通过命令行运行：

1
2
3
4
5
6
7
8
# 查看帮助信息
.\audiocpp_cli.exe --help

# 启动服务器
.\audiocpp_server.exe

# 指定后端运行（CUDA 版本）
.\audiocpp_cli.exe --backend cuda

3.3 使用 WebUI

预编译包中可能包含 webui/run_webui.bat 脚本，双击运行即可启动 Gradio 网页界面，浏览器访问 http://127.0.0.1:7860 。

4. 方式二：macOS Homebrew 安装

macOS 用户可以通过 Homebrew 快速安装 ：

1
2
3
4
5
6
7
8
# 添加 tap
brew tap 0xShug0/audio-cpp

# 信任该 tap
brew trust 0xShug0/audio-cpp

# 安装 audio.cpp
brew install audio-cpp

安装完成后，验证：

1
audiocpp_cli --help

5. 方式三：源码编译（推荐开发者）

5.1 通用前置依赖

无论哪个平台，都需要以下工具：

1
2
3
# CMake 3.20+
# Ninja 构建系统
# C++17 兼容编译器

5.2 Windows 编译

前置要求 ：

  • Visual Studio Build Tools 2022 或更新版本（含 C++ 桌面工作负载）
  • MSVC x64 编译器、Windows SDK、CMake、Ninja、MSVC OpenMP 组件
  • NVIDIA CUDA Toolkit（CUDA 构建）
  • LunarG Vulkan SDK（Vulkan 构建）

使用 PowerShell 构建：

1
2
3
4
5
6
7
8
# CPU 版本
.\scripts\build_windows.ps1 -Preset windows-cpu-release -Target audiocpp_cli -Jobs 16

# CUDA 版本
.\scripts\build_windows.ps1 -Preset windows-cuda-release -Target audiocpp_cli -Jobs 16

# Vulkan 版本
.\scripts\build_windows.ps1 -Preset windows-vulkan-release -Target audiocpp_cli -Jobs 16

构建产物输出到 build\windows-cpu-release\bin\audiocpp_cli.exe 。

CPU 架构配置 ：

配置 构建标志 适用场景
Fast -CpuArch native 本机使用，速度最快
Balance -CpuArch avx2 大多数现代 PC（推荐）
Portable -CpuArch baseline 最大兼容性

5.3 Linux / macOS 编译

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 克隆仓库
git clone https://github.com/0xShug0/audio.cpp.git
cd audio.cpp

# 创建构建目录
mkdir build && cd build

# CPU 构建
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ..
ninja audiocpp_cli audiocpp_server

# CUDA 构建
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DENGINE_ENABLE_CUDA=ON ..
ninja audiocpp_cli audiocpp_server

# Vulkan 构建
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DENGINE_ENABLE_VULKAN=ON ..
ninja audiocpp_cli audiocpp_server

5.4 Nix 构建

NixOS 用户可以使用项目提供的 flake.nix ：

1
2
3
4
5
# 启用 flake
nix develop

# 构建（支持 CUDA/Vulkan/Metal 选项）
nix build

6. 模型管理

audio.cpp 提供模型管理器用于下载和管理模型。

6.1 下载模型

模型托管在 HuggingFace 上 ：

1
2
3
4
5
# 列出可用模型
audiocpp_model_manager list

# 下载指定模型
audiocpp_model_manager download <model_id>

6.2 使用 GGUF 模型

所有模型系列均支持 GGUF 格式加载，推荐使用 Q8_0 量化以平衡性能和精度 ：

1
2
# 使用 GGUF 模型运行
audiocpp_cli --model path/to/model.gguf --task tts --input "你好，世界"

7. 配置与使用

7.1 命令行使用

1
2
3
4
5
6
7
8
# TTS 文本转语音
audiocpp_cli --model <model_path> --task tts --input "Hello, world" --output output.wav

# ASR 语音识别
audiocpp_cli --model <model_path> --task asr --input audio.wav --output transcript.txt

# 指定后端
audiocpp_cli --backend cuda --model <model_path> --task tts --input "Hello"

7.2 服务器模式

启动 API 服务器，提供 OpenAI 兼容接口 ：

1
2
3
4
5
# 启动服务器
audiocpp_server --host 0.0.0.0 --port 8080

# 查看可用设备
audiocpp_server --list-devices

7.3 WebUI 使用

WebUI 提供图形化操作界面 ：

1
2
3
4
# 启动 WebUI
python webui.py
# 或使用批处理脚本
webui\run_webui.bat

浏览器访问 http://127.0.0.1:7860。

WebUI 功能：

  • 按需加载模型（选择模型后点击“加载”）
  • 上传参考语音进行语音克隆
  • 下载未安装的模型
  • 动态生成模型专属参数控件

7.4 高级参数配置

WebUI 的高级参数由 configs/model_params.json 驱动，选择模型后会自动生成匹配的滑块、数字框、开关等控件 。也可以在“其他参数（JSON）”折叠框中手动传入未列出的参数。

8. 创建 Systemd 服务（Linux）

对于生产环境部署，建议创建 systemd 服务 ：

1
2
# 创建服务文件
sudo nano /etc/systemd/system/audiocpp.service

内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[Unit]
Description=audio.cpp Server
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/opt/audiocpp
ExecStart=/opt/audiocpp/audiocpp_server --host 0.0.0.0 --port 8080
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

启用并启动服务：

1
2
3
4
sudo systemctl daemon-reload
sudo systemctl enable audiocpp
sudo systemctl start audiocpp
sudo systemctl status audiocpp

9. 性能优化建议

9.1 CUDA 优化

  • 使用 CUDA 后端可显著提升推理速度，部分 TTS 路径比 Python 快 1.8x 至 10x
  • CUDA 构建同时包含 CPU 后端，可通过 --backend cpu 切换

9.2 GGUF 量化

  • Q8_0 量化可减少约 37% 的显存占用，同时保持较好精度
  • 对于显存受限的设备，推荐使用 GGUF Q8 模型

9.3 CPU 线程配置

CPU 模式下，线程数会自动根据物理核心数设置（不计算超线程），超过 4 核时保留一个核心空闲 。如需手动设置：

1
export AUDIOCPP_THREADS=N

10. 常见问题与解决方案

10.1 构建失败

问题：CMake 配置或编译报错。

解决方案：

  • 确保 CMake 版本 ≥ 3.20
  • Windows 用户确保使用 MSVC 编译器
  • CUDA 构建需安装 CUDA Toolkit 并确保 nvcc 在 PATH 中

10.2 WebUI 无法连接

问题：WebUI 启动后无法连接后端。

解决方案：

  • WebUI 会自动检测后端（优先 GPU，否则 CPU）
  • 可通过 AUDIOCPP_BACKEND=gpu|cpu 强制指定后端
  • 检查端口 8080 是否被占用

10.3 模型加载失败

问题：模型文件无法加载。

解决方案：

  • 确认模型格式受支持（safetensors 或 GGUF）
  • 检查模型路径是否正确
  • 对于 GGUF 模型，确认量化版本与运行时匹配

10.4 CUDA 显存不足

问题：运行时报显存不足错误。

解决方案：

  • 使用 GGUF Q8 量化模型减少显存占用
  • 尝试 --backend cpu 切换到 CPU 推理
  • 减少批处理大小或使用更小的模型变体

11. 部署架构总结

部署方式 适用场景 安装命令 特点
Windows 预编译包 Windows 用户 下载解压即用 无需编译，开箱即用
Homebrew macOS 用户 brew install audio-cpp 一行命令完成
源码编译 开发者 cmake + ninja 支持所有后端，完全可控
Nix 构建 NixOS 用户 nix build 声明式配置，可复现

audio.cpp 作为一个纯 C++ 的音频推理引擎，通过预编译包或源码编译可以快速完成部署。Windows 用户建议使用预编译包，macOS 用户可通过 Homebrew 安装，开发者和 Linux 用户则推荐源码编译以获得最佳性能和硬件支持。部署完成后，可通过 CLI、服务器 API 或 WebUI 三种方式使用，支持 TTS、ASR、语音克隆、音乐生成等多种音频任务。