声音模型

hermes agent 声音模型

Hermes 智能体支持跨 CLI 和即时通讯平台的完整语音交互。你可以通过麦克风与智能体对话，听取语音回复，并在 Discord 语音频道中进行实时语音通话。

如果你想了解包含推荐配置和实际使用模式的实用设置指南，请参阅《在 Hermes 中使用语音模式》（Use Voice Mode with Hermes）。

前提条件

在使用语音功能之前，请确保已完成以下准备：

安装 Hermes 智能体 —— pip install hermes-agent（参见安装指南）。
配置 LLM 提供商 —— 运行 hermes model 或在 ~/.hermes/.env 中设置你首选的提供商凭据。
验证基础环境 —— 在启用语音之前，运行 hermes 以确认智能体能正常响应文本。

功能概览

功能	平台	描述
交互式语音 (Interactive Voice)	CLI	按下 `Ctrl+B` 开始录音，智能体将自动检测停顿并进行回复。
语音自动回复 (Auto Voice Reply)	Telegram, Discord	智能体在发送文本回复的同时，会发送一段语音音频。
语音频道 (Voice Channel)	Discord	机器人加入语音频道（VC），监听用户发言并以语音形式回传答复。

核心需求

Python 软件包

# CLI 语音模式（麦克风 + 音频播放）
pip install "hermes-agent[voice]"

# Discord + Telegram 消息推送（包含支持语音频道的 discord.py[voice]）
pip install "hermes-agent[messaging]"

# 高级 TTS (ElevenLabs)
pip install "hermes-agent[tts-premium]"

# 本地 TTS (NeuTTS, 可选)
python -m pip install -U neutts[all]

# 一次性安装所有功能
pip install "hermes-agent[all]"

额外包 (Extra)	包含的库	适用场景
voice	sounddevice, numpy	CLI 语音模式
messaging	discord.py[voice], python-telegram-bot, aiohttp	Discord & Telegram 机器人
tts-premium	elevenlabs	ElevenLabs TTS 提供商

可选的本地 TTS 提供商：通过 python -m pip install -U neutts[all] 单独安装。首次使用时会自动下载模型。

系统依赖

# macOS
brew install portaudio ffmpeg opus
brew install espeak-ng   # 仅 NeuTTS 需要

# Ubuntu/Debian
sudo apt install portaudio19-dev ffmpeg libopus0
sudo apt install espeak-ng   # 仅 NeuTTS 需要

依赖项	用途	适用场景
PortAudio	麦克风输入和音频播放	CLI 语音模式
ffmpeg	音频格式转换 (MP3 → Opus, PCM → WAV)	所有平台
Opus	Discord 语音编解码器	Discord 语音频道
espeak-ng	音标化后端 (Phonemizer)	本地 NeuTTS 提供商

API 密钥

将以下内容添加到 ~/.hermes/.env：

# 语音转文本 (STT) —— 本地提供商完全不需要密钥
# pip install faster-whisper          # 免费，本地运行，推荐使用
GROQ_API_KEY=your-key                 # Groq Whisper —— 速度极快，有免费额度（云端）
VOICE_TOOLS_OPENAI_KEY=your-key       # OpenAI Whisper —— 付费（云端）

# 文本转语音 (TTS)（可选 —— Edge TTS 和 NeuTTS 无需任何密钥即可工作）
ELEVENLABS_API_KEY=***           # ElevenLabs —— 顶级音质
# 上方的 VOICE_TOOLS_OPENAI_KEY 同样可以启用 OpenAI TTS

CLI 语音模式

语音模式在 经典 CLI (hermes chat) 和 TUI (hermes --tui) 中均可用。两者的行为完全一致 —— 拥有相同的斜杠命令、相同的 VAD 静音检测、相同的流式 TTS 以及相同的幻觉过滤器。此外，TUI 会将崩溃取证日志转发至 ~/.hermes/logs/，因此在特殊音频后端上发生的“一键通话”故障可以携带完整的堆栈跟踪进行报告，而不会静默消失。

快速开始

启动 CLI 并启用语音模式：

hermes                # 启动交互式 CLI

然后在 CLI 内部使用以下命令：

/voice          Toggle voice mode on/off
/voice on       Enable voice mode
/voice off      Disable voice mode
/voice tts      Toggle TTS output
/voice status   Show current state

工作原理

通过 hermes 启动 CLI 并使用 /voice on 启用语音模式。
**按下 Ctrl+B** —— 播放一声蜂鸣音 (880Hz)，开始录音。
说话 —— 实时音频电平条会显示你的输入：● [▁▂▃▅▇▇▅▂] ❯。
停止说话 —— 在检测到 3 秒静音后，录音自动停止。
播放两声蜂鸣音 (660Hz)，确认录音结束。
音频通过 Whisper 进行转录并发送给智能体。
如果启用了 TTS，智能体的回答将被大声朗读。
录音自动重新开始 —— 无需按下任何键即可再次说话。

该循环将一直持续，直到你在录音期间按下 Ctrl+B（退出连续模式），或者连续 3 次录音未检测到任何语音。

静音检测 (Silence Detection)

采用两阶段算法检测你是否已完成发言：

语音确认 —— 等待高于 RMS 阈值 (200) 的音频持续至少 0.3 秒，能够容忍音节间的短暂下降。
结束检测 —— 一旦确认了语音，在连续静音 3.0 秒后触发停止。

如果 15 秒内完全未检测到语音，录音将自动停止。

silence_threshold（静音阈值）和 silence_duration（静音时长）均可在 config.yaml 中配置。你还可以通过 voice.beep_enabled: false 禁用录音开始/停止的蜂鸣音。

流式 TTS (Streaming TTS)

当启用 TTS 时，智能体会随着文本的生成逐句朗读其回答 —— 你无需等待完整响应：

将文本增量缓冲为完整的句子（最少 20 个字符）。
剥离 Markdown 格式和 <think> 思考块。
实时生成并播放每一句的音频。

幻觉过滤器 (Hallucination Filter)

Whisper 有时会从静音或背景噪音中生成幻影文本（如 “Thank you for watching”, “Subscribe” 等）。智能体会使用一套包含多种语言、共 26 个已知幻觉短语的集合，配合一个捕获重复变体的正则表达式来过滤掉这些内容。

网关语音回复 (Telegram & Discord)

如果你尚未设置消息机器人，请参阅针对特定平台的指南：

Telegram 设置指南
Discord 设置指南

启动网关以连接到你的消息平台：

hermes gateway        # 启动网关（连接到已配置的平台）
hermes gateway setup  # 针对首次配置的交互式设置向导

Discord：频道 vs 私信 (DMs)

该机器人在 Discord 上支持两种交互模式：

模式	如何对话	是否需要艾特 (@)	设置
私信 (DM)	打开机器人资料 → “发送消息”	否	立即生效
服务器频道	在机器人所在的文本频道中输入	是 (@机器人名称)	必须将机器人邀请至服务器

私信（个人使用推荐）： 只需打开与机器人的私信窗口并输入即可 —— 无需 @艾特。语音回复和所有命令在私信中的运作方式与频道一致。
服务器频道： 机器人仅在你 @艾特它（例如 @hermesbyt4 hello）时才会响应。请确保从艾特弹出框中选择的是机器人用户，而不是同名的角色。

若要在服务器频道中禁用艾特限制，请在 ~/.hermes/.env 中添加：

DISCORD_REQUIRE_MENTION=false

或者设置特定频道为自由响应模式（无需艾特）：

DISCORD_FREE_RESPONSE_CHANNELS=123456789,987654321

命令

这些命令在 Telegram 和 Discord（包括私信和文本频道）中均可使用：

/voice          Toggle voice mode on/off
/voice on       Voice replies only when you send a voice message
/voice tts      Voice replies for ALL messages
/voice off      Disable voice replies
/voice status   Show current setting

模式

模式	命令	行为
off	`/voice off`	仅限文本（默认）
voice_only	`/voice on`	仅当你发送语音消息时朗读回复
all	`/voice tts`	对每一条消息都朗读回复

语音模式设置在网关重启后依然保持（持久化）。

平台交付方式

平台	格式	备注
Telegram	语音气泡 (Opus/OGG)	在聊天界面内直接播放。如果需要，ffmpeg 会将 MP3 转换为 Opus。
Discord	原生语音气泡 (Opus/OGG)	像用户语音消息一样在界面内播放。如果语音气泡 API 失败，则降级为文件附件。

Discord 语音频道

这是最具沉浸感的语音功能：机器人加入 Discord 语音频道，监听用户的发言，转录语音内容，通过智能体处理后，再将回复在语音频道中播报出来。

设置

1. Discord 机器人权限

如果你已经为文本功能设置了 Discord 机器人（参见 Discord 设置指南），则需要添加语音权限。前往 Discord Developer Portal → 你的应用 → Installation → Default Install Settings → Guild Install：在现有的文本权限基础上增加以下权限：

权限	用途	是否必选
Connect	加入语音频道	是
Speak	在语音频道中播放 TTS 音频	是
Use Voice Activity	检测用户何时正在说话	推荐

更新后的权限整数 (Permissions Integer)：

仅文本： 274878286912（查看频道、发送消息、阅读历史、嵌入链接、附件、帖子、反应）
文本 + 语音： 274881432640（上述所有权限 + 连接、说话）

使用更新后的权限 URL 重新邀请机器人：

https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274881432640

将 YOUR_APP_ID 替换为来自 Developer Portal 的 Application ID。

2. 特权网关意图 (Privileged Gateway Intents)

在 Developer Portal → 你的应用 → Bot → Privileged Gateway Intents 中，启用全部三项：

意图	用途
Presence Intent	检测用户在线/离线状态
Server Members Intent	将 `DISCORD_ALLOWED_USERS` 中的用户名解析为数字 ID（有条件开启）
Message Content Intent	读取频道中的文本消息内容

Message Content Intent 是必需的。Server Members Intent 仅在你使用用户名配置 DISCORD_ALLOWED_USERS 列表时才需要 —— 如果你使用的是数字用户 ID，则可以保持关闭。语音频道的 SSRC 到用户 ID 的映射通过语音 WebSocket 的 SPEAKING 操作码实现，不需要 Server Members Intent。

3. Opus 编解码器

运行网关的机器上必须安装 Opus 编解码器库：

# macOS (Homebrew)
brew install opus

# Ubuntu/Debian
sudo apt install libopus0

机器人会自动从以下路径加载编解码器：

macOS: /opt/homebrew/lib/libopus.dylib
Linux: libopus.so.0

4. 环境变量

# Discord 机器人（已配置文本功能）
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=your-user-id

# STT —— 本地提供商无需密钥 (pip install faster-whisper)
# GROQ_API_KEY=your-key            # 备选：云端、快速、有免费额度

# TTS —— 可选。Edge TTS 和 NeuTTS 无需密钥。
# ELEVENLABS_API_KEY=***      # 高级音质
# VOICE_TOOLS_OPENAI_KEY=***  # OpenAI TTS / Whisper

启动网关

hermes gateway        # 使用现有配置启动

机器人应在几秒钟内于 Discord 上线。

命令

在机器人所在的 Discord 文本频道中使用以下命令：

/voice join      Bot joins your current voice channel
/voice channel   Alias for /voice join
/voice leave     Bot disconnects from voice channel
/voice status    Show voice mode and connected channel

工作原理

当机器人加入语音频道后，它会：

监听：独立监听每个用户的音频流。
静音检测：在至少 0.5 秒的发言后，若出现 1.5 秒的静音，则触发处理流程。
转录：通过 Whisper STT（本地、Groq 或 OpenAI）转录音频。
处理：通过完整的智能体流水线（会话、工具、记忆）进行处理。
播报：通过 TTS 将回复在语音频道中大声朗读。

文本频道集成

当机器人在语音频道中时：

转录文本会出现在文本频道中：[Voice] @user: 你说的话
智能体的响应既会作为文本发送到频道中，也会在语音频道中播报。
关联的文本频道即为你发出 /voice join 命令的频道。

回声消除 (Echo Prevention)

机器人在播放 TTS 回复时会自动暂停其音频监听器，防止其听到并重新处理自己的输出内容。

访问控制

只有 DISCORD_ALLOWED_USERS 列表中列出的用户可以通过语音进行交互。其他用户的音频将被静默忽略。

DISCORD_ALLOWED_USERS=284102345871466496

配置参考

config.yaml

# 语音录制 (CLI)
voice:
  record_key: "ctrl+b"            # 开始/停止录音的热键
  max_recording_seconds: 120       # 最大录音时长
  auto_tts: false                  # 语音模式启动时自动启用 TTS
  beep_enabled: true               # 播放录音开始/停止的蜂鸣音
  silence_threshold: 200           # RMS 电平 (0-32767)，低于此值视为静音
  silence_duration: 3.0            # 自动停止前的静音时长（秒）

# 语音转文本 (STT)
stt:
  provider: "local"                  # "local" (免费) | "groq" | "openai"
  local:
    model: "base"                    # tiny, base, small, medium, large-v3
  # model: "whisper-1"              # 旧版：未设置 provider 时使用

# 文本转语音 (TTS)
tts:
  provider: "edge"                 # "edge" (免费) | "elevenlabs" | "openai" | "neutts" | "minimax"
  edge:
    voice: "en-US-AriaNeural"      # 包含 322 种语音，74 种语言
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"    # Adam
    model_id: "eleven_multilingual_v2"
  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"                 # alloy, echo, fable, onyx, nova, shimmer
    base_url: "https://api.openai.com/v1"  # 可选：覆盖自托管或兼容 OpenAI 的端点
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

环境变量

# 语音转文本提供商 (local 不需要密钥)
# pip install faster-whisper        # 免费本地 STT — 无需 API 密钥
GROQ_API_KEY=...                    # Groq Whisper (快，有免费额度)
VOICE_TOOLS_OPENAI_KEY=...         # OpenAI Whisper (付费)

# STT 高级覆盖选项 (可选)
STT_GROQ_MODEL=whisper-large-v3-turbo    # 覆盖默认 Groq STT 模型
STT_OPENAI_MODEL=whisper-1               # 覆盖默认 OpenAI STT 模型
GROQ_BASE_URL=https://api.groq.com/openai/v1     # 自定义 Groq 端点
STT_OPENAI_BASE_URL=https://api.openai.com/v1    # 自定义 OpenAI STT 端点

# 文本转语音提供商 (Edge TTS 和 NeuTTS 不需要密钥)
ELEVENLABS_API_KEY=***             # ElevenLabs (顶级音质)
# 上方的 VOICE_TOOLS_OPENAI_KEY 同样可以启用 OpenAI TTS

# Discord 语音频道
DISCORD_BOT_TOKEN=...
DISCORD_ALLOWED_USERS=...

STT 提供商对比

提供商	模型	速度	质量	费用	需要密钥
Local	base	快 (取决于 CPU/GPU)	好	免费	否
Local	small	中等	更好	免费	否
Local	large-v3	慢	最好	免费	否
Groq	whisper-large-v3-turbo	极快 (~0.5s)	好	免费层级	是
Groq	whisper-large-v3	快 (~1s)	更好	免费层级	是
OpenAI	whisper-1	快 (~1s)	好	付费	是
OpenAI	gpt-4o-transcribe	中等 (~2s)	最好	付费	是

提供商优先级（自动降级）： local > groq > openai

TTS 提供商对比

提供商	质量	费用	延迟	需要密钥
Edge TTS	好	免费	~1s	否
ElevenLabs	极佳	付费	~2s	是
OpenAI TTS	好	付费	~1.5s	是
NeuTTS	好	免费	取决于 CPU/GPU	否

NeuTTS 使用上方 tts.neutts 配置块。

故障排除

“未找到音频设备” (CLI)

未安装 PortAudio：

brew install portaudio    # macOS
sudo apt install portaudio19-dev  # Ubuntu

机器人不在 Discord 服务器频道中回复

在服务器频道中，机器人默认需要被 @提及。请确保：

输入 @ 并选择 机器人用户（带 #数字判别符），而不是选择同名的 身份组 (Role)
或者改用 私信 (DM) — 无需提及
或者在 ~/.hermes/.env 中设置 DISCORD_REQUIRE_MENTION=false

机器人进入了语音频道但听不到我说话

检查你的 Discord 用户 ID 是否已加入 DISCORD_ALLOWED_USERS
确保你在 Discord 中没有被静音
机器人需要从 Discord 接收到一个 SPEAKING (正在说话) 事件才能映射你的音频 — 请在加入频道后的几秒钟内开始说话

机器人能听到我说话但不回复

验证 STT（语音转文本）是否可用：安装 faster-whisper（无需密钥）或设置 GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY
检查 LLM 模型是否已配置且可访问
查看网关日志：tail -f ~/.hermes/logs/gateway.log

机器人在文本中回复但在语音频道中不说话

TTS（文本转语音）提供商可能发生故障 — 检查 API 密钥和配额
Edge TTS（免费，无需密钥）是默认的备选方案
检查日志中的 TTS 错误信息

Whisper 返回乱码/垃圾文本

幻觉过滤器会自动处理大部分情况。如果你仍然遇到虚假的转录文本：

使用更安静的环境
调整配置中的 silence_threshold（值越高 = 越不敏感）
尝试使用不同的 STT 模型

声音模型

前提条件

功能概览

核心需求

Python 软件包

系统依赖

API 密钥

CLI 语音模式

快速开始

工作原理

静音检测 (Silence Detection)

流式 TTS (Streaming TTS)

幻觉过滤器 (Hallucination Filter)

网关语音回复 (Telegram & Discord)

Discord：频道 vs 私信 (DMs)

命令

模式

平台交付方式

Discord 语音频道

设置

1. Discord 机器人权限

2. 特权网关意图 (Privileged Gateway Intents)

3. Opus 编解码器

4. 环境变量

启动网关

命令

工作原理

文本频道集成

回声消除 (Echo Prevention)

访问控制

配置参考

config.yaml

环境变量

STT 提供商对比

TTS 提供商对比

故障排除

“未找到音频设备” (CLI)

机器人不在 Discord 服务器频道中回复

机器人进入了语音频道但听不到我说话

机器人能听到我说话但不回复

机器人在文本中回复但在语音频道中不说话

Whisper 返回乱码/垃圾文本

快速上手

使用 Hermes

功能

消息平台

集成

指南与教程

开发者指南