搭建属于你的语音助手并在本地运行：Whisper + Ollama + ChatterBox

原文链接：https://blog.duy-huynh.com/build-your-own-voice-assistant-and-run-it-locally/

更新于2025年5月：现已采用 Resemble AI 推出的最先进开源 TTS 模型——Chatterbox TTS，表现更胜一筹！

使用 Bark 的原始实现仍保留在 archive-2025-05-29 分支中，供参考。

继我上一篇关于如何搭建并本地运行 RAG 的文章之后，今天我们将更进一步：不仅实现大型语言模型的对话能力，还为其添加听和说的功能。我们的目标很简单——打造一款类似经典电影《钢铁侠》中贾维斯或弗莱迪那样的语音助手，它可以在你的电脑上离线运行。

ChatterBox 新特性：

• 🎯 语音克隆：只需一段简短音频样本即可克隆任意声音
• 🎭 情感控制：调节回复的情感表达强度
• 🚀 性能提升：0.5B 参数量模型，推理速度更快
• 💧 水印音频：内置神经网络水印技术，确保音频真实性

技术栈

首先，你需要设置一个 Python 虚拟环境。你可以选择 pyenv、virtualenv、poetry 等工具来完成这一任务。出于个人习惯，本教程将使用 Poetry。以下是几个关键库，你需要安装它们：

• rich：用于美化终端输出。
• openai-whisper：强大的语音转文本工具。
• chatterbox-tts：最先进的文本转语音合成模型，支持语音克隆与情感控制。
• langchain：用于对接大型语言模型（LLM）的简单易用库。
• langchain-openai：用于连接兼容 OpenAI 的云端 LLM 提供商，例如 MiniMax。
• sounddevice、pyaudio 和 speechrecognition：用于音频录制与播放的必备库。

详细的依赖列表请参阅此处链接。

其中最关键的部分是大型语言模型（LLM）后端。默认情况下，我们使用 Ollama 在本地运行 LLM。当然，你也可以选择 MiniMax 作为云端 LLM 提供商，这样无需本地 GPU 即可获得更高质量的响应。如果你对 Ollama 还不熟悉，建议先阅读我之前关于离线 RAG 的文章：“搭建属于你的 RAG 并在本地运行：Langchain + Ollama + Streamlit”。基本上，你只需要下载 Ollama 应用程序，拉取你喜欢的模型并启动即可。

架构设计

好了，如果一切准备就绪，接下来我们就可以开始下一步了。以下是整个应用的整体架构，主要由三个核心组件构成：

• 语音识别模块：利用 OpenAI 的 Whisper 将语音转换为文本。Whisper 经过多种数据集的训练，能够很好地处理不同语言和方言。
• 对话链模块：为了实现对话功能，我们将使用 Langchain 接口，并搭配可插拔的 LLM 后端——既可以是通过 Ollama 运行的本地模型（如 Gemma3、Llama-4），也可以是通过 MiniMax 提供的云端模型（MiniMax-M2.7）。这种组合能够提供流畅且富有吸引力的对话体验。
• 语音合成模块：文本到语音的转换则由 Resemble AI 的 Chatterbox TTS 完成，该模型以其逼真的语音生成能力和语音克隆功能而闻名。

工作流程非常简单：录制语音、将其转录为文本、利用 LLM 生成回复，最后再通过 ChatterBox 将文本转化为语音输出。

flowchart TD
    A[🎤 用户语音输入] --> B[语音识别<br/>OpenAI Whisper]
    B --> C[📝 文本转录]
    C --> D[对话链<br/>Langchain + Ollama / MiniMax<br/>Gemma3 / Llama-4 / MiniMax-M2.7]
    D --> E[🤖 生成回复]
    E --> F[语音合成<br/>Chatterbox TTS]
    F --> G[🔊 音频输出]
    G --> H[👤 用户听到回复]

    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style D fill:#fff3e0
    style E fill:#e8f5e8
    style F fill:#f3e5f5
    style G fill:#e1f5fe
    style H fill:#fce4ec

安装步骤

⚠️ 重要提示：我们强烈推荐使用 uv 来管理依赖，而不是用 pip 和 requirements.txt 文件。requirements.txt 是通过 uv pip freeze 生成的，其中包含固定版本号，可能会在不同系统上无法正确安装。

方法一：使用 uv（推荐）

# 如果尚未安装 uv，请先安装
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者在 macOS 上：brew install uv
# 或者在 Windows 上：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 克隆仓库
git clone https://github.com/vndee/local-talking-llm.git
cd local-talking-llm

# 使用 uv 安装依赖（推荐）
uv sync

# 激活虚拟环境
source .venv/bin/activate  # Windows 上：.venv\Scripts\activate

# 下载 NLTK 数据（用于句子分词）
python -c "import nltk; nltk.download('punkt_tab')"

方法二：使用 pip（替代方案）

如果你更倾向于使用 pip，可以直接从 pyproject.toml 文件安装：

# 克隆仓库
git clone https://github.com/vndee/local-talking-llm.git
cd local-talking-llm

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows 上：venv\Scripts\activate

# 从 pyproject.toml 安装（而非 requirements.txt）
pip install -e .

# 下载 NLTK 数据
python -c "import nltk; nltk.download('punkt')"

安装并配置 Ollama

# 安装并启动 Ollama
# 按照 https://ollama.ai 上的说明操作
ollama pull gemma3  # 或其他你喜欢的模型

配置 MiniMax（云端 LLM 替代方案）

如果你没有本地 GPU，或者希望使用更高品质的云端模型，可以选用 MiniMax 作为 LLM 后端：

1. 在 MiniMax 平台 注册并获取 API 密钥。
2. 设置环境变量：

   export MINIMAX_API_KEY="your-api-key-here"
   

使用 MiniMax 时无需安装 Ollama——LLM 将在云端运行，而 TTS 和 STT 仍然会在本地执行。

使用方法

基本用法

python app.py

语音克隆功能

录制一段 10–30 秒的音频样本，作为你要克隆的声音，然后运行：

python app.py --voice path/to/voice_sample.wav

自定义设置

# 调整情感表达和语速
python app.py --exaggeration 0.7 --cfg-weight 0.3

# 使用不同的 LLM 模型
python app.py --model codellama

# 保存生成的语音样本
python app.py --save-voice

使用 MiniMax 云端 LLM

python app.py --use-minimax --minimax-api-key=your-api-key-here

# 使用 MiniMax 作为 LLM 提供者（需要设置 MINIMAX_API_KEY 环境变量）
python app.py --provider minimax

# 使用特定的 MiniMax 模型并自定义温度
python app.py --provider minimax --model MiniMax-M2.7 --temperature 0.8

# 直接传递 API 密钥
python app.py --provider minimax --api-key your-api-key-here

# 结合语音克隆和情感控制
python app.py --provider minimax --voice path/to/voice.wav --exaggeration 0.7

配置选项

• --provider: LLM 提供者（ollama 或 minimax，默认：ollama）
• --api-key: 云 LLM 提供者的 API 密钥（或使用 MINIMAX_API_KEY 环境变量）
• --temperature: LLM 温度（0.0-1.0，默认：0.7）
• --voice: 用于语音克隆的音频文件路径
• --exaggeration: 情感强度（0.0-1.0，默认：0.5）
  • 较低值（0.3-0.4）：语气更平静、中性
  • 较高值（0.7-0.9）：更具表现力和情感
• --cfg-weight: 控制语速和表达风格（0.0-1.0，默认：0.5）
  • 较低值：语速较快、更生动
  • 较高值：语速较慢、更沉稳
• --model: 要使用的 Ollama 模型（默认：llama2）
• --save-voice: 将生成的音频回复保存到 voices/ 目录

实现细节

基于 ChatterBox 的 TextToSpeechService

新的 TextToSpeechService 利用 ChatterBox 的高级功能：

from chatterbox.tts import ChatterboxTTS

class TextToSpeechService:
    def __init__(self, device: str = "cuda" if torch.cuda.is_available() else "cpu"):
        self.device = device
        self.model = ChatterboxTTS.from_pretrained(device=device)
        self.sample_rate = self.model.sr

    def synthesize(self, text: str, audio_prompt_path: str = None,
                  exaggeration: float = 0.5, cfg_weight: float = 0.5):
        wav = self.model.generate(
            text,
            audio_prompt_path=audio_prompt_path,
            exaggeration=exaggeration,
            cfg_weight=cfg_weight
        )
        return self.sample_rate, wav.squeeze().cpu().numpy()

相比之前的 Bark 实现，主要改进包括：

• 语音克隆：传入音频文件即可克隆任意声音
• 情感控制：通过 exaggeration 参数调整表达力度
• 音质提升：ChatterBox 生成的语音更加自然
• 推理速度更快：模型规模更小（0.5B 对比 Bark 的大型模型）

动态情感分析

应用现在包含自动情感检测功能，使回应更具表现力：

def analyze_emotion(text: str) -> float:
    emotional_keywords = ['amazing', 'terrible', 'love', 'hate', 'excited',
                         'sad', 'happy', 'angry', '!', '?!']
    emotion_score = 0.5
    for keyword in emotional_keywords:
        if keyword in text.lower():
            emotion_score += 0.1
    return min(0.9, max(0.3, emotion_score))

最佳实践建议

1. 语音克隆：

   • 使用清晰的 10-30 秒音频样本
   • 确保样本背景噪声尽可能少
   • 样本中的语音应自然流畅

2. 情感控制：

   • 一般对话场景：exaggeration=0.5, cfg_weight=0.5
   • 戏剧化/富有表现力的场景：exaggeration=0.7+，cfg_weight=0.3
   • 冷静专业的语气：exaggeration=0.3，cfg_weight=0.7

3. 性能优化：

   • 如果有 CUDA 可用，尽量使用以加速推理
   • 第一次生成可能会较慢，因为需要加载模型
   • 可考虑使用较小的 Whisper 模型（如 "tiny.en" 或 "base.en"）以加快转录速度。

生产级部署

对于希望将此应用提升至生产级别的用户，可考虑以下方案：

• 性能优化：

  • 使用优化的推理引擎（ONNX、TensorRT）
  • 实施模型量化以提高推理速度
  • 添加常用短语的缓存机制

• 增强功能：

  • 支持多说话人及语音档案管理
  • 实现实时语音转换
  • 集成更多 LLM 提供者
  • 构建带有实时流媒体功能的 Web 界面

• 语音数据库：

  • 创建语音样本库
  • 实现语音选择界面
  • 增加语音混合功能

• API 服务：

  • 提供 TTS 请求的 RESTful API
  • 支持 WebSocket 实时通信
  • 实施速率限制与身份验证

故障排除

依赖安装问题

问题：运行 requirements.txt 安装时出现错误，例如：

• ERROR: Could not find a version that satisfies the requirement cPython==0.0.6
• ModuleNotFoundError: No module named 'distutils'
• 各种版本冲突

解决方案：requirements.txt 文件由 uv pip freeze 生成，其中包含的精确版本可能在不同系统上无法正常工作。请尝试以下替代方法：

1. 推荐使用 uv：

   uv sync
   

2. 使用 pip 和 pyproject.toml：

   pip install -e .
   

3. 手动安装核心包：

   pip install chatterbox-tts langchain-ollama openai-whisper sounddevice rich nltk
   

运行时问题

• CUDA 显存不足：切换到 CPU 模式或降低模型精度
• 麦克风无法工作：检查系统权限和设备设置
• 推理缓慢：确保在可用时使用 GPU，必要时可选用小型号模型
• 语音克隆质量不佳：使用高质量、语音清晰的音频样本
• 导入错误：运行应用前务必激活虚拟环境

总结

通过集成 ChatterBox，我们的本地语音助手得到了显著提升。新增的语音克隆和情感控制功能为打造个性化且富有表现力的 AI 助手开辟了全新可能性。无论您是想构建个人版的 Jarvis、创作内容，还是开发语音驱动的应用程序，这套升级后的技术栈都提供了强大的基础支持。

Whisper 强大的语音识别能力、Ollama 灵活的 LLM 服务以及 ChatterBox 先进的 TTS 技术相结合，共同打造出一款完全离线运行的多功能语音助手。无需任何云端服务，也无需 API 密钥，纯粹依靠本地 AI 功能！

资源链接

• ChatterBox GitHub
• Ollama
• MiniMax 平台
• Whisper
• 原文博客

---

local-talking-llm 快速上手指南

构建属于你自己的本地语音助手（类似钢铁侠的 Jarvis），支持离线运行。该工具集成了 Whisper（语音识别）、Ollama/MiniMax（大语言模型）和 ChatterBox（语音合成与克隆）。

环境准备

系统要求

• 操作系统: Windows, macOS, 或 Linux
• Python: 3.10 或更高版本
• 硬件:
  • 推荐配备 NVIDIA GPU (用于加速 Whisper 和 ChatterBox 推理)
  • 若无 GPU，可在 CPU 上运行但速度较慢
• 依赖工具:
  • Ollama (若使用本地模型)
  • uv (推荐的包管理工具，替代 pip)

前置依赖

确保已安装以下基础工具：

• Git
• FFmpeg (用于音频处理，大多数包管理器可直接安装)

安装步骤

推荐使用 uv 进行依赖管理，以避免版本冲突。

1. 安装 uv (如未安装)

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. 克隆项目并安装依赖

git clone https://github.com/vndee/local-talking-llm.git
cd local-talking-llm

# 同步依赖并创建虚拟环境
uv sync

# 激活虚拟环境
# Linux/macOS:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

# 下载必要的 NLTK 数据
python -c "import nltk; nltk.download('punkt_tab')"

3. 配置大语言模型后端

方案 A：使用 Ollama (本地运行，推荐)

# 安装 Ollama 后，拉取模型 (例如 gemma3 或 llama3)
ollama pull gemma3

方案 B：使用 MiniMax (云端运行，无需本地显卡)

1. 注册 MiniMax 平台 获取 API Key。
2. 设置环境变量：

export MINIMAX_API_KEY="your-api-key-here"
# Windows PowerShell: $env:MINIMAX_API_KEY="your-api-key-here"

基本使用

1. 启动语音助手

默认使用本地 Ollama 模型：

python app.py

若使用 MiniMax 云端模型：

python app.py --provider minimax

2. 体验声音克隆 (可选)

准备一段 10-30 秒的目标人声录音（格式为 .wav，背景噪音小），然后运行：

python app.py --voice path/to/voice_sample.wav

3. 调整情感与语速 (可选)

通过参数控制回复的情感强度和语速风格：

# 高情感表达 (更夸张), 较快语速
python app.py --exaggeration 0.8 --cfg-weight 0.3

# 平静专业语调，较慢语速
python app.py --exaggeration 0.3 --cfg-weight 0.7

常用参数说明

• --provider: 选择模型提供商 (ollama 或 minimax)
• --model: 指定模型名称 (如 gemma3, MiniMax-M2.7)
• --voice: 声音克隆样本路径
• --exaggeration: 情感强度 (0.0-1.0，默认 0.5)
• --cfg-weight: 语速控制 (0.0-1.0，越低越快)
• --save-voice: 将生成的语音保存到 voices/ 目录