ByteNoteByteNote
字

字节笔记本

2026年2月22日

voice-assistant：基于 Whisper + Yi 模型的本地语音助手

#开源工具

本文介绍 voice-assistant，一个基于 Python 开发的本地语音助手项目。该项目结合了 OpenAI Whisper 语音识别和零一万物 Yi 大语言模型，实现了完全离线的智能语音对话功能，保护用户隐私的同时提供流畅的交互体验。

项目简介

voice-assistant 是由 linyiLYi 开发的开源项目，在 GitHub 上已获得 1.3k+ stars 和 213 个 fork。这是一个单脚本项目，所有核心逻辑都集中在 main.py 中，代码简洁易懂，非常适合作为学习本地 AI 语音助手的入门项目。

该项目的主要特点：

  • 完全本地运行：语音识别的 Whisper 模型和对话的 Yi 模型都在本地执行，无需联网，保护隐私
  • 实时语音交互：支持语音输入和语音输出，实现自然的人机对话
  • 跨平台支持：基于 Python 开发，支持 macOS、Windows 和 Linux
  • 可定制性强：支持更换不同的语言模型和语音合成方式

核心特性

  • 语音输入识别：基于 OpenAI Whisper 模型，支持多语言语音识别
  • 智能对话生成：使用零一万物 Yi-34B-Chat 或 Yi-6B-Chat 大语言模型生成回复
  • 语音合成输出：使用系统 TTS（macOS say 命令）将文字回复转换为语音
  • 流式响应：支持大模型流式输出，边生成边语音播报，提升交互体验
  • 静音检测：自动检测用户语音结束，无需手动按键

技术栈

  • Python 3.11.5：项目开发语言
  • OpenAI Whisper：语音识别模型，基于 Apple MLX 框架优化
  • Yi 大语言模型：零一万物开发的对话模型，支持 6B 和 34B 参数版本
  • LangChain：大语言模型应用开发框架
  • llama.cpp：本地运行大语言模型的高性能推理引擎
  • PyAudio：音频录制和播放处理

安装指南

环境配置

推荐使用 Anaconda 配置 Python 环境：

bash
# 创建虚拟环境
conda create -n VoiceAI python=3.11
conda activate VoiceAI

# 安装依赖
pip install -r requirements.txt

# 安装支持 Metal 加速的 llama-cpp-python（macOS）
CMAKE_ARGS="-DLLAMA_METAL=on" pip install llama-cpp-python

# 安装音频处理工具（macOS）
brew install portaudio
pip install pyaudio

依赖列表

text
torch
torchvision
torchaudio
mlx
langchain
langchain-community
numba
numpy
tqdm
more-itertools
tiktoken==0.3.3

模型文件准备

  1. 语音识别模型：下载 Whisper Large V3 MLX 版本

  2. 对话模型（二选一）：

快速开始

1. 配置麦克风

运行工具脚本查看可用麦克风：

bash
python tools/list_microphones.py

在 main.py 中设置麦克风 ID：

python
MIC_IDX = 0  # 根据 list_microphones.py 输出修改

2. 配置模型路径

python
WHISP_PATH = "models/whisper-large-v3"
MODEL_PATH = "models/yi-34b-chat.Q8_0.gguf"  # 或 yi-chat-6b.Q8_0.gguf

3. 选择语言

python
LANG = "EN"  # CN 表示中文，EN 表示英文

4. 运行程序

bash
python main.py

程序启动后会进入监听状态，直接说话即可开始对话。

使用示例

对话流程

text
Listening...          # 程序开始监听
Transcribing...       # 识别语音内容
Guest: 你好，今天天气怎么样？ (Time 1250 ms)
Generating...         # 大模型生成回复
Server: 你好！我是本地语音助手，无法获取实时天气信息，但我可以帮你查询天气网站或告诉你如何查看天气预报。 (Time 3250 ms)

核心代码解析

语音录制函数：

python
def record_audio():
    audio = pyaudio.PyAudio()
    stream = audio.open(format=FORMAT, channels=CHANNELS, rate=RATE,
                       input=True, input_device_index=MIC_IDX,
                       frames_per_buffer=CHUNK)
    silent_chunks = 0
    audio_started = False
    frames = []

    while True:
        data = stream.read(CHUNK)
        frames.append(data)
        rms = compute_rms(data)

        if audio_started:
            if rms < SILENCE_THRESHOLD:
                silent_chunks += 1
                if silent_chunks > SILENT_CHUNKS:
                    break
            else:
                silent_chunks = 0
        elif rms >= SILENCE_THRESHOLD:
            audio_started = True
    # ... 保存音频文件

语音输出回调处理：

python
class VoiceOutputCallbackHandler(BaseCallbackHandler):
    def on_llm_new_token(self, token, **kwargs):
        with self.lock:
            self.generated_text += token
        # 检测句子结束，触发语音合成
        if token in ['.', '。', '!', '！', '?', '？']:
            with self.lock:
                self.speech_queue.put(self.generated_text)
                self.generated_text = ""

项目结构

text
voice-assistant/
├── main.py                 # 主程序入口
├── requirements.txt        # Python 依赖
├── models/                 # 模型文件目录
│   ├── whisper-large-v3/   # 语音识别模型
│   └── yi-34b-chat.Q8_0.gguf  # 对话模型
├── prompts/                # 提示词模板
│   ├── example-cn.txt      # 中文提示词
│   └── example-en.txt      # 英文提示词
├── recordings/             # 临时录音文件
├── tools/
│   └── list_microphones.py # 麦克风列表工具
└── whisper/                # Whisper 语音识别模块

注意事项

  1. 硬件要求：

    • 使用 Yi-34B 模型需要至少 39GB 内存
    • 使用 Yi-6B 模型可以在普通笔记本电脑上运行
    • macOS 用户建议开启 Metal 加速提升推理速度

  2. 平台差异：

    • macOS：使用内置 say 命令进行语音合成
    • Windows/Linux：需要替换为 speech_recognition 和 pyttsx3

  3. 静音阈值：根据环境噪音调整 SILENCE_THRESHOLD 参数

致谢

该项目基于以下开源项目构建：

项目链接

开源工具
上一篇

Claude Telegram Bot：将 Claude Code 变成你的个人 Telegram 助手

下一篇

voice-assistant：基于 Whisper + Yi 模型的本地语音助手

分享: