六月

本地语音聊天机器人：Ollama + HF Transformers + Coqui TTS 工具包

• 概述
• 安装
• 使用
• 定制化
• 常见问题

概述

june 是一款本地语音聊天机器人，它结合了 Ollama（用于语言模型功能）、Hugging Face Transformers（用于语音识别）以及 Coqui TTS 工具包（用于文本转语音合成）的强大能力。该工具提供了一个灵活且注重隐私的解决方案，可在您的本地机器上实现语音辅助交互，确保所有数据都不会被发送到外部服务器。

交互模式

• 文本输入/输出： 向助手提供文本输入，并接收文本回复。
• 语音输入/文本输出： 使用麦克风进行语音输入，并从助手那里获得文本回复。
• 文本输入/音频输出： 提供文本输入，并同时接收文本和合成音频回复。
• 语音输入/音频输出（默认）： 使用麦克风进行语音输入，并以文本和合成音频的形式接收回复。

安装

先决条件

• Ollama
• Python 3.10 或更高版本（需包含 pip)
• Python 开发包（例如 Debian 系统中的 apt install python3-dev）——仅适用于 GNU/Linux
• PortAudio 开发包（例如 Debian 系统中的 apt install portaudio19-dev）——仅适用于 GNU/Linux
• PortAudio（例如使用 Homebrew 的 brew install portaudio）——仅适用于 macOS
• Microsoft Visual C++ 14.0 或更高版本——仅适用于 Windows

从源码安装

方法 1：直接安装

要直接从 GitHub 仓库安装 june：

pip install git+https://github.com/mezbaul-h/june.git@master

方法 2：克隆并安装

或者，您也可以克隆仓库并在本地安装：

git clone https://github.com/mezbaul-h/june.git
cd june
pip install .

使用

如果您尚未拉取语言模型（默认为 llama3.1:8b-instruct-q4_0），请先使用 Ollama 进行拉取：

ollama pull llama3.1:8b-instruct-q4_0

接下来，运行程序（使用默认配置）：

june-va

这将使用 llama3.1:8b-instruct-q4_0 提供 LLM 功能，openai/whisper-small.en 进行语音识别，以及 tts_models/en/ljspeech/glow-tts 进行音频合成。

您还可以通过 JSON 配置文件自定义程序的行为：

june-va --config path/to/config.json

[!NOTE] 配置文件是可选的。有关配置文件结构的更多信息，请参阅定制化部分。

定制化

应用程序可以通过配置文件进行定制。配置文件必须是 JSON 文件。默认配置如下：

{
    "llm": {
        "disable_chat_history": false,
        "model": "llama3.1:8b-instruct-q4_0"
    },
    "stt": {
        "device": "torch 设备标识符（如果可用则为 `cuda`；否则为 `cpu`）",
        "generation_args": {
            "batch_size": 8
        },
        "model": "openai/whisper-small.en"
    },
    "tts": {
        "device": "torch 设备标识符（如果可用则为 `cuda`；否则为 `cpu`）",
        "model": "tts_models/en/ljspeech/glow-tts"
    }
}

当您使用配置文件时，它会覆盖默认配置，但不会完全替换。因此，您可以根据需要部分修改配置。例如，如果您不想使用语音识别功能，而只想通过文本方式提供提示，可以通过以下配置文件来禁用该功能：

{
  "stt": null
}

同样地，您也可以禁用音频合成器，或同时禁用两者，从而仅以文本模式使用虚拟助手。

如果您只想修改加载特定类型模型的设备，而不改变该模型的其他默认属性，则可以使用：

{
  "tts": {
    "device": "cpu"
  }
}

配置属性

llm - 语言模型配置

• llm.device: 将管道分配到的 Torch 设备标识符（例如 cpu、cuda、mps）。
• llm.disable_chat_history: 布尔值，指示是否禁用或启用聊天历史记录。启用聊天历史记录会使交互更加动态，因为模型可以访问之前的上下文，但这会消耗更多的计算资源。禁用后，对话互动性会降低，但所需的计算资源也会减少。
• llm.model: Ollama 上文本生成模型的标签名称。请确保这是您机器上存在的有效模型标签。
• llm.system_prompt: 向模型提供系统提示。如果底层模型不支持系统提示，则会引发错误。

stt - 语音转文本模型配置

• tts.device: 将管道分配到的 Torch 设备标识符（例如 cpu、cuda、mps）。
• stt.generation_args: 包含 Hugging Face 语音识别管道所接受的生成参数的对象。
• stt.model: Hugging Face 上语音识别模型的名称。请确保这是 Hugging Face 上存在的有效模型 ID。

tts - 文本转语音模型配置

• tts.device: 将管道分配到的 Torch 设备标识符（例如 cpu、cuda、mps）。
• tts.generation_args: 包含 Coqui TTS API 所接受的生成参数的对象。
• tts.model: Coqui TTS 工具包支持的文本转语音模型名称。请确保这是有效的模型 ID。

常见问题

问：语音输入是如何工作的？

在看到 [system]> 正在监听声音... 的消息后，您可以直接对着麦克风说话。与典型的语音助手不同，这里不需要唤醒词。只需开始说话，工具就会自动检测并处理您的语音输入。说完后，请保持 3 秒钟的静默，以便助手完成对您的语音输入的处理。

问：我可以克隆声音吗？

Coqui TTS 工具包支持的许多模型（例如 tts_models/multilingual/multi-dataset/xtts_v2）都支持声音克隆功能。您可以使用自己的语音档案，配合一段较短的音频片段（大多数模型约为 1 分钟）。准备好音频片段后，您可以通过自定义配置让助手使用该声音，例如：

{
  "tts": {
    "model": "tts_models/multilingual/multi-dataset/xtts_v2",
    "generation_args": {
      "language": "en",
      "speaker_wav": "/path/to/your/target/voice.wav"
    }
  }
}

问：我可以在 june 中使用远程的 Ollama 实例吗？

是的，你可以轻松地将远程托管的 Ollama 实例与 june 集成，而不必使用本地实例。操作方法如下：

1. 将 OLLAMA_HOST 环境变量设置为你远程 Ollama 实例的相应 URL。
2. 按照常规方式运行程序。

示例：

要使用远程 Ollama 实例，可以使用类似如下的命令：

OLLAMA_HOST=http://localhost:11434 june-va

June 快速上手指南

June 是一个完全本地运行的语音聊天机器人，结合了 Ollama（大语言模型）、Hugging Face Transformers（语音识别）和 Coqui TTS（语音合成）。所有数据均在本地处理，无需上传至外部服务器，确保隐私安全。

环境准备

在开始之前，请确保您的系统满足以下要求并安装好前置依赖：

核心依赖

• Ollama: 用于运行本地大语言模型。
• Python: 版本需为 3.10 或更高（包含 pip）。

系统特定依赖

根据您的操作系统，还需安装以下开发包：

• GNU/Linux (Debian/Ubuntu 等):

  sudo apt install python3-dev portaudio19-dev
  

• macOS:

  brew install portaudio
  

• Windows: 安装 Microsoft Visual C++ Build Tools (版本 14.0 或更高)。

提示：国内用户若遇到 Python 包下载缓慢，建议在安装时指定国内镜像源（如清华源）： pip install ... -i https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

您可以选择以下任意一种方式进行安装：

方法一：直接安装（推荐）

直接从 GitHub 仓库安装最新正式版：

pip install git+https://github.com/mezbaul-h/june.git@master

方法二：克隆源码安装

如果您需要修改源码或进行开发：

git clone https://github.com/mezbaul-h/june.git
cd june
pip install .

基本使用

1. 拉取大语言模型

首次使用前，需要通过 Ollama 下载默认的对话模型（此处以 llama3.1 为例）：

ollama pull llama3.1:8b-instruct-q4_0

注：国内用户若拉取缓慢，可配置 OLLAMA_HOST 或使用相关加速代理。

2. 启动语音助手

安装完成并下载模型后，直接在终端运行以下命令即可启动默认模式的语音助手（支持语音输入 + 语音/文字输出）：

june-va

默认配置说明：

• LLM: llama3.1:8b-instruct-q4_0
• 语音识别 (STT): openai/whisper-small.en
• 语音合成 (TTS): tts_models/en/ljspeech/glow-tts

3. 交互方式

启动后看到 [system]> Listening for sound... 提示即可开始使用：

• 语音交互：直接对着麦克风说话，说完后保持安静约 3 秒，系统将自动处理并回复（支持文字和语音播报）。
• 纯文本模式：如需禁用语音功能，可创建配置文件将 stt 或 tts 设为 null，并通过 --config 参数加载（详见高级定制文档）。