Chế độ giọng nói

Hermes Agent hỗ trợ tương tác bằng giọng nói đầy đủ trên nền tảng CLI và nhắn tin. Nói chuyện với đại lý bằng micrô của bạn, nghe câu trả lời bằng giọng nói và trò chuyện bằng giọng nói trực tiếp trong các kênh thoại Discord.

Nếu bạn muốn có hướng dẫn thiết lập thực tế với cấu hình được đề xuất và cách sử dụng thực tế, hãy xem Sử dụng Chế độ giọng nói với Hermes.

Điều kiện tiên quyết

Trước khi sử dụng các tính năng giọng nói, hãy đảm bảo bạn có:

Đã cài đặt Hermes Agent — pip install hermes-agent (xem Cài đặt)
Đã định cấu hình nhà cung cấp LLM — chạy hermes model hoặc đặt thông tin xác thực nhà cung cấp ưa thích của bạn trong ~/.hermes/.env
Thiết lập cơ sở hoạt động — chạy hermes để xác minh tổng đài viên phản hồi văn bản trước khi bật giọng nói

mẹo

Thư mục ~/.hermes/ và mặc định config.yaml được tạo tự động vào lần đầu tiên bạn chạy hermes . Bạn chỉ cần tạo ~/.hermes/.env theo cách thủ công cho khóa API.

Tổng quan

Tính năng	Nền tảng	Mô tả
Giọng nói tương tác	CLI	Nhấn Ctrl+B để ghi, nhân viên tự động phát hiện sự im lặng và phản hồi
Trả lời bằng giọng nói tự động	Điện tín, Bất hòa	Đại lý gửi âm thanh nói cùng với phản hồi văn bản
Kênh thoại	Bất hòa	Bot tham gia VC, lắng nghe người dùng nói, trả lời lại

Yêu cầu

Gói Python

# CLI voice mode (microphone + audio playback)
pip install "hermes-agent[voice]"

# Discord + Telegram messaging (includes discord.py[voice] for VC support)
pip install "hermes-agent[messaging]"

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

# Local TTS (NeuTTS, optional)
python -m pip install -U neutts[all]

# Everything at once
pip install "hermes-agent[all]"

Thêm	Gói	Bắt buộc đối với
`voice`	`sounddevice` , `numpy`	Chế độ giọng nói CLI
`messaging`	`discord.py[voice]` , `python-telegram-bot` , `aiohttp`	Bot Discord & Telegram
`tts-premium`	`elevenlabs`	Nhà cung cấp TTS ElevenLabs

Nhà cung cấp TTS cục bộ tùy chọn: cài đặt neutts riêng với python -m pip install -U neutts[all] . Trong lần sử dụng đầu tiên, nó sẽ tự động tải xuống mô hình.

thông tin

discord.py[voice] tự động cài đặt PyNaCl (để mã hóa giọng nói) và liên kết opus. Điều này là cần thiết để hỗ trợ kênh thoại Discord.

Phụ thuộc hệ thống

# macOS
brew install portaudio ffmpeg opus
brew install espeak-ng   

# for NeuTTS

# Ubuntu/Debian
sudo apt install portaudio19-dev ffmpeg libopus0
sudo apt install espeak-ng   

# for NeuTTS

| Phụ thuộc | Mục đích | Bắt buộc đối với | |----------||----------|-------------| | PortAudio | Đầu vào micrô và phát lại âm thanh | Chế độ giọng nói CLI | | ffmpeg | Chuyển đổi định dạng âm thanh (MP3 → Opus, PCM → WAV) | Tất cả nền tảng | | Thật tuyệt vời | Bộ giải mã giọng nói Discord | Kênh thoại Discord | | nói-ng | Phụ trợ phiên âm | Nhà cung cấp NeuTTS địa phương |

Khóa API

Thêm vào ~/.hermes/.env :

# Speech-to-Text — local provider needs NO key at all
# pip install faster-whisper          

# Free, runs locally, recommended
GROQ_API_KEY=your-key                 

# Groq Whisper — fast, free tier (cloud)
VOICE_TOOLS_OPENAI_KEY=your-key       

# OpenAI Whisper — paid (cloud)

# Text-to-Speech (optional — Edge TTS and NeuTTS work without any key)
ELEVENLABS_API_KEY=***           

# ElevenLabs — premium quality
# VOICE_TOOLS_OPENAI_KEY above also enables OpenAI TTS

mẹo

Nếu faster-whisper được cài đặt, chế độ giọng nói sẽ hoạt động với không có khóa API cho STT. Mô hình (~150 MB cho base ) tự động tải xuống trong lần sử dụng đầu tiên.

Chế độ giọng nói CLI

Bắt đầu nhanh

Khởi động CLI và bật chế độ giọng nói:

hermes                

# Start the interactive CLI

Sau đó sử dụng các lệnh này trong 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

Cách thức hoạt động1. Khởi động CLI bằng `hermes` và bật chế độ giọng nói với `/voice on`

Nhấn Ctrl+B — một tiếng bíp phát ra (880Hz), quá trình ghi bắt đầu
Nói — thanh mức âm thanh trực tiếp hiển thị thông tin đầu vào của bạn: ● [▁▂▃▅▇▇▅▂] ❯
Dừng nói — sau 3 giây im lặng, ghi âm tự động dừng
Hai tiếng bíp phát (660Hz) xác nhận quá trình ghi đã kết thúc
Âm thanh được chép lại qua Whisper và gửi đến đại lý
Nếu TTS được bật, câu trả lời của nhân viên sẽ được nói to
Ghi âm tự động khởi động lại — nói lại mà không cần nhấn phím bất kỳ

Vòng lặp này tiếp tục cho đến khi bạn nhấn Ctrl+B trong khi ghi (thoát khỏi chế độ liên tục) hoặc 3 bản ghi liên tiếp không phát hiện được giọng nói.

mẹo

Khóa bản ghi có thể định cấu hình thông qua voice.record_key trong ~/.hermes/config.yaml (mặc định: ctrl+b ).

Phát hiện im lặng

Thuật toán hai giai đoạn phát hiện khi bạn nói xong:

Xác nhận giọng nói — đợi âm thanh trên ngưỡng RMS (200) trong ít nhất 0,3 giây, chấp nhận những khoảng lặng ngắn giữa các âm tiết
Phát hiện kết thúc — sau khi lời nói được xác nhận, sẽ kích hoạt sau 3,0 giây im lặng liên tục

Nếu không phát hiện thấy giọng nói nào trong 15 giây, quá trình ghi sẽ tự động dừng.

Cả silence_threshold và silence_duration đều có thể định cấu hình trong config.yaml .

Đang phát TTS

Khi TTS được bật, tổng đài viên sẽ nói câu trả lời từng câu khi nó tạo văn bản — bạn không cần đợi phản hồi đầy đủ:

Đệm văn bản delta thành câu hoàn chỉnh (tối thiểu 20 ký tự)
Loại bỏ định dạng đánh dấu và khối <think>
Tạo và phát âm thanh mỗi câu trong thời gian thực

Bộ lọc ảo giác

Lời thì thầm đôi khi tạo ra văn bản ảo từ sự im lặng hoặc tiếng ồn xung quanh ("Cảm ơn bạn đã xem", "Đăng ký", v.v.). Tác nhân lọc chúng ra bằng cách sử dụng một bộ 26 cụm từ ảo giác đã biết trên nhiều ngôn ngữ, cộng với mẫu biểu thức chính quy để nắm bắt các biến thể lặp đi lặp lại.

Trả lời bằng giọng nói qua cổng (Telegram & Discord)

Nếu bạn chưa thiết lập bot nhắn tin của mình, hãy xem hướng dẫn dành riêng cho nền tảng:

Bắt đầu cổng kết nối với nền tảng nhắn tin của bạn:

hermes gateway        

# Start the gateway (connects to configured platforms)
hermes gateway setup  

# Interactive setup wizard for first-time configuration

Bất hòa: Kênh và DM

Bot hỗ trợ hai chế độ tương tác trên Discord:

Chế độ	Cách Nói chuyện	Yêu cầu đề cập	Thiết lập
Tin nhắn trực tiếp (DM)	Mở hồ sơ của bot → "Tin nhắn"	Không	Hoạt động ngay lập tức
Kênh máy chủ	Nhập vào kênh văn bản có bot	Có ( `@botname` )	Bot phải được mời vào máy chủ

DM (được khuyến nghị cho mục đích sử dụng cá nhân): Chỉ cần mở DM bằng bot và nhập — không cần @mention. Trả lời bằng giọng nói và tất cả các lệnh hoạt động giống như trong các kênh.

Kênh máy chủ: Bot chỉ phản hồi khi bạn @đề cập đến nó (ví dụ: @hermesbyt4 hello ). Đảm bảo bạn chọn người dùng bot từ cửa sổ bật lên đề cập chứ không phải vai trò có cùng tên.

mẹo

Để tắt yêu cầu đề cập trong các kênh máy chủ, hãy thêm vào ~/.hermes/.env :

DISCORD_REQUIRE_MENTION=false

Hoặc đặt các kênh cụ thể làm phản hồi miễn phí (không cần đề cập):

DISCORD_FREE_RESPONSE_CHANNELS=123456789,987654321

Lệnh

Chúng hoạt động trong cả Telegram và Discord (kênh DM và văn bản):

/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

Chế độ

Chế độ	Lệnh	Hành vi
`off`	`/voice off`	Chỉ văn bản (mặc định)
`voice_only`	`/voice on`	Chỉ trả lời khi bạn gửi tin nhắn thoại
`all`	`/voice tts`	Nói trả lời mọi tin nhắn

Cài đặt chế độ giọng nói được duy trì trong suốt quá trình khởi động lại cổng.

Phân phối nền tảng

Nền tảng	Định dạng	Ghi chú
Điện tín	Bong bóng thoại (Opus/OGG)	Phát nội tuyến trong trò chuyện. ffmpeg chuyển đổi MP3 → Opus nếu cần
Bất hòa	Bong bóng giọng nói bản địa (Opus/OGG)	Phát nội tuyến giống như tin nhắn thoại của người dùng. Quay lại tệp đính kèm nếu API bong bóng thoại không thành công

Kênh thoại Discord

Tính năng giọng nói hấp dẫn nhất: bot tham gia kênh giọng nói Discord, lắng nghe người dùng nói, chép lại lời nói của họ, xử lý thông qua tổng đài viên và nói lại câu trả lời trong kênh giọng nói.

Thiết lập

1. Quyền của Discord Bot

Nếu bạn đã thiết lập bot Discord cho văn bản (xem Hướng dẫn thiết lập Discord), bạn cần thêm quyền bằng giọng nói.

Đi tới Cổng thông tin dành cho nhà phát triển Discord → ứng dụng của bạn → Cài đặt → Cài đặt cài đặt mặc định → Cài đặt bang hội:

Thêm các quyền này vào các quyền văn bản hiện có:

Giấy phép	Mục đích	Bắt buộc
Kết nối	Tham gia các kênh thoại	Có
Nói	Phát âm thanh TTS trong các kênh thoại	Có
Sử dụng Hoạt động bằng giọng nói	Phát hiện khi người dùng đang nói	Được đề xuất

Số nguyên quyền được cập nhật:

Cấp độ	Số nguyên	Bao gồm những gì
Chỉ văn bản	`274878286912`	Xem kênh, Gửi tin nhắn, Đọc lịch sử, Nhúng, Tệp đính kèm, Chủ đề, Phản ứng
Văn bản + Giọng nói	`274881432640`	Tất cả ở trên + Kết nối, Nói chuyện

Mời lại bot bằng URL quyền được cập nhật:

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

Thay thế YOUR_APP_ID bằng ID ứng dụng của bạn từ Cổng thông tin dành cho nhà phát triển.

cảnh báo

Việc mời lại bot đến máy chủ mà bot đã cài đặt sẽ cập nhật các quyền của bot mà không cần xóa bot. Bạn sẽ không mất bất kỳ dữ liệu hoặc cấu hình nào.

2. Ý định cổng đặc quyền

Trong Cổng thông tin dành cho nhà phát triển → ứng dụng của bạn → Bot → Ý định cổng đặc quyền, bật cả ba:

Ý định	Mục đích
Ý định hiện diện	Phát hiện trạng thái trực tuyến/ngoại tuyến của người dùng
Ý định của thành viên máy chủ	Ánh xạ số nhận dạng SSRC giọng nói tới ID người dùng Discord
Ý định nội dung tin nhắn	Đọc nội dung tin nhắn trong các kênh

Cả ba đều cần thiết cho chức năng kênh thoại đầy đủ. Ý định của thành viên máy chủ đặc biệt quan trọng — nếu không có nó, bot không thể xác định được ai đang nói trong kênh thoại.

3. Bộ mã hóa OpusThư viện codec Opus phải được cài đặt trên máy chạy cổng:

# macOS (Homebrew)
brew install opus

# Ubuntu/Debian
sudo apt install libopus0

Bot tự động tải codec từ:

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

4. Biến môi trường

# ~/.hermes/.env

# Discord bot (already configured for text)
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=your-user-id

# STT — local provider needs no key (pip install faster-whisper)
# GROQ_API_KEY=your-key            

# Alternative: cloud-based, fast, free tier

# TTS — optional. Edge TTS and NeuTTS need no key.
# ELEVENLABS_API_KEY=***      

# Premium quality
# VOICE_TOOLS_OPENAI_KEY=***  

# OpenAI TTS / Whisper

Khởi động cổng

hermes gateway        

# Start with existing configuration

Bot sẽ trực tuyến trong Discord trong vòng vài giây.

Lệnh

Sử dụng những thứ này trong kênh văn bản Discord nơi bot hiện diện:

/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

thông tin

Bạn phải ở trong kênh thoại trước khi chạy /voice join . Bot tham gia vào cùng một VC mà bạn đang tham gia.

Cách thức hoạt động

Khi bot tham gia một kênh thoại, nó:

Nghe luồng âm thanh của từng người dùng một cách độc lập
Phát hiện sự im lặng — 1,5 giây im lặng sau ít nhất 0,5 giây xử lý kích hoạt giọng nói
Phiên âm âm thanh qua Whisper STT (cục bộ, Groq hoặc OpenAI)
Quy trình thông qua quy trình tác nhân đầy đủ (phiên, công cụ, bộ nhớ)
Nói trả lời lại bằng kênh thoại qua TTS

Tích hợp kênh văn bản

Khi bot ở trong kênh thoại:

Bản ghi xuất hiện trong kênh văn bản: [Voice] @user: what you said
Phản hồi của tác nhân được gửi dưới dạng văn bản trong kênh VÀ được nói trong VC
Kênh văn bản là kênh đã phát hành /voice join

Ngăn chặn tiếng vang

Bot tự động tạm dừng trình nghe âm thanh trong khi phát các câu trả lời TTS, ngăn không cho nó nghe và xử lý lại đầu ra của chính nó.

Kiểm soát truy cập

Chỉ những người dùng được liệt kê trong DISCORD_ALLOWED_USERS mới có thể tương tác qua giọng nói. Âm thanh của người dùng khác bị âm thầm bỏ qua.

# ~/.hermes/.env
DISCORD_ALLOWED_USERS=284102345871466496

Tham khảo cấu hình

config.yaml

# Voice recording (CLI)
voice:
  record_key: "ctrl+b"            

# Key to start/stop recording
  max_recording_seconds: 120       

# Maximum recording length
  auto_tts: false                  

# Auto-enable TTS when voice mode starts
  silence_threshold: 200           

# RMS level (0-32767) below which counts as silence
  silence_duration: 3.0            

# Seconds of silence before auto-stop

# Speech-to-Text
stt:
  provider: "local"                  

# "local" (free) 

| "groq" | "openai"
  local:
    model: "base"                    

# tiny, base, small, medium, large-v3
  

# model: "whisper-1"              

# Legacy: used when provider is not set

# Text-to-Speech
tts:
  provider: "edge"                 

# "edge" (free) 

| "elevenlabs" | "openai" 

| "neutts" | "minimax"
  edge:
    voice: "en-US-AriaNeural"      

# 322 voices, 74 languages
  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"  

# optional: override for self-hosted or OpenAI-compatible endpoints
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

Biến môi trường

# Speech-to-Text providers (local needs no key)
# pip install faster-whisper        

# Free local STT — no API key needed
GROQ_API_KEY=...                    

# Groq Whisper (fast, free tier)
VOICE_TOOLS_OPENAI_KEY=...         

# OpenAI Whisper (paid)

# STT advanced overrides (optional)
STT_GROQ_MODEL=whisper-large-v3-turbo    

# Override default Groq STT model
STT_OPENAI_MODEL=whisper-1               

# Override default OpenAI STT model
GROQ_BASE_URL=https://api.groq.com/openai/v1     

# Custom Groq endpoint
STT_OPENAI_BASE_URL=https://api.openai.com/v1    

# Custom OpenAI STT endpoint

# Text-to-Speech providers (Edge TTS and NeuTTS need no key)
ELEVENLABS_API_KEY=***             

# ElevenLabs (premium quality)
# VOICE_TOOLS_OPENAI_KEY above also enables OpenAI TTS

# Discord voice channel
DISCORD_BOT_TOKEN=...
DISCORD_ALLOWED_USERS=...

So sánh nhà cung cấp STT

Nhà cung cấp	Người mẫu	Tốc độ	Chất lượng	Chi phí	Khóa API
Địa phương	`base`	Nhanh (phụ thuộc vào CPU/GPU)	Tốt	Miễn phí	Không
Địa phương	`small`	Trung bình	Tốt hơn	Miễn phí	Không
Địa phương	`large-v3`	Chậm	Tốt nhất	Miễn phí	Không
Ngớ ngẩn	`whisper-large-v3-turbo`	Rất nhanh (~0,5 giây)	Tốt	Cấp miễn phí	Có
Ngớ ngẩn	`whisper-large-v3`	Nhanh (~1 giây)	Tốt hơn	Cấp miễn phí	Có
OpenAI	`whisper-1`	Nhanh (~1 giây)	Tốt	Đã trả tiền	Có
OpenAI	`gpt-4o-transcribe`	Trung bình (~2 giây)	Tốt nhất	Đã trả tiền	Có

Ưu tiên của nhà cung cấp (dự phòng tự động): local > groq > openai

So sánh nhà cung cấp TTS

Nhà cung cấp	Chất lượng	Chi phí	Độ trễ	Yêu cầu khóa
TTS cạnh	Tốt	Miễn phí	~1 giây	Không
ElevenLabs	Xuất sắc	Đã trả tiền	~2 giây	Có
OpenAI TTS	Tốt	Đã trả tiền	~1,5 giây	Có
NeuTTS	Tốt	Miễn phí	Phụ thuộc vào CPU/GPU	Không

NeuTTS sử dụng khối cấu hình tts.neutts ở trên.

Khắc phục sự cố

"Không tìm thấy thiết bị âm thanh" (CLI)

PortAudio chưa được cài đặt:

brew install portaudio    

# macOS
sudo apt install portaudio19-dev  

# Ubuntu

Bot không phản hồi trên các kênh máy chủ Discord

Theo mặc định, bot yêu cầu @mention trong các kênh máy chủ. Hãy chắc chắn rằng bạn:1. Nhập @ và chọn người dùng bot (với #discriminator), không phải vai trò có cùng tên 2. Hoặc sử dụng DM thay thế - không cần đề cập 3. Hoặc đặt DISCORD_REQUIRE_MENTION=false trong ~/.hermes/.env

Bot tham gia VC nhưng không nghe thấy tôi

Kiểm tra ID người dùng Discord của bạn có trong DISCORD_ALLOWED_USERS
Đảm bảo bạn không bị tắt tiếng trong Discord
Bot cần sự kiện NÓI từ Discord trước khi có thể ánh xạ âm thanh của bạn — bắt đầu nói trong vòng vài giây sau khi tham gia

Bot nghe thấy tôi nhưng không phản hồi

Kiểm tra STT có sẵn: cài đặt faster-whisper (không cần key) hoặc đặt GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY
Kiểm tra mô hình LLM đã được cấu hình và có thể truy cập được chưa
Xem lại nhật ký cổng: tail -f ~/.hermes/logs/gateway.log

Bot phản hồi bằng văn bản nhưng không trả lời bằng kênh thoại

Nhà cung cấp TTS có thể không thành công - hãy kiểm tra khóa và hạn ngạch API
Edge TTS (miễn phí, không key) là dự phòng mặc định
Kiểm tra nhật ký lỗi TTS

Whisper trả về văn bản rác

Bộ lọc ảo giác sẽ tự động bắt hầu hết các trường hợp. Nếu bạn vẫn nhận được bản ghi ảo:

Sử dụng môi trường yên tĩnh hơn
Điều chỉnh silence_threshold trong config (cao hơn = kém nhạy hơn)
Thử mẫu STT khác

Điều kiện tiên quyết

Tổng quan

Yêu cầu

Gói Python​

Phụ thuộc hệ thống​

Khóa API​

Chế độ giọng nói CLI

Bắt đầu nhanh​

Cách thức hoạt động1. Khởi động CLI bằng hermes và bật chế độ giọng nói với /voice on​

Phát hiện im lặng​

Đang phát TTS​

Bộ lọc ảo giác​

Trả lời bằng giọng nói qua cổng (Telegram & Discord)

Bất hòa: Kênh và DM​

Lệnh​

Chế độ​

Phân phối nền tảng​

Kênh thoại Discord

Thiết lập​

1. Quyền của Discord Bot​

2. Ý định cổng đặc quyền​

3. Bộ mã hóa OpusThư viện codec Opus phải được cài đặt trên máy chạy cổng:​

4. Biến môi trường​

Khởi động cổng​

Lệnh​

Cách thức hoạt động​

Tích hợp kênh văn bản​

Ngăn chặn tiếng vang​

Kiểm soát truy cập​

Tham khảo cấu hình

config.yaml​

Biến môi trường​

So sánh nhà cung cấp STT​

So sánh nhà cung cấp TTS​

Khắc phục sự cố

"Không tìm thấy thiết bị âm thanh" (CLI)​

Bot không phản hồi trên các kênh máy chủ Discord​

Bot tham gia VC nhưng không nghe thấy tôi​

Bot nghe thấy tôi nhưng không phản hồi​

Bot phản hồi bằng văn bản nhưng không trả lời bằng kênh thoại​

Whisper trả về văn bản rác​

Gói Python

Phụ thuộc hệ thống

Khóa API

Bắt đầu nhanh

Cách thức hoạt động1. Khởi động CLI bằng `hermes` và bật chế độ giọng nói với `/voice on`

Phát hiện im lặng

Đang phát TTS

Bộ lọc ảo giác

Bất hòa: Kênh và DM

Lệnh

Chế độ

Phân phối nền tảng

Thiết lập

1. Quyền của Discord Bot

2. Ý định cổng đặc quyền

3. Bộ mã hóa OpusThư viện codec Opus phải được cài đặt trên máy chạy cổng:

4. Biến môi trường

Khởi động cổng

Lệnh

Cách thức hoạt động

Tích hợp kênh văn bản

Ngăn chặn tiếng vang

Kiểm soát truy cập

config.yaml

Biến môi trường

So sánh nhà cung cấp STT

So sánh nhà cung cấp TTS

"Không tìm thấy thiết bị âm thanh" (CLI)

Bot không phản hồi trên các kênh máy chủ Discord

Bot tham gia VC nhưng không nghe thấy tôi

Bot nghe thấy tôi nhưng không phản hồi

Bot phản hồi bằng văn bản nhưng không trả lời bằng kênh thoại

Whisper trả về văn bản rác