huggingface/speech-to-speech

Kết luận: partial · Công nghệ: voice-agents · speech-to-text · text-to-speech · local-llm · huggingface

huggingface/speech-to-speech là một toolkit mẫu để dựng voice agent chạy cục bộ bằng mô hình mã nguồn mở, bao phủ chuỗi speech-to-text -> language model -> text-to-speech và cả dịch tiếng nói. Với ~8.3k stars, đây là nguồn tham khảo mạnh để thử nghiệm giao diện thoại thời gian thực, nhưng phù hợp nhất ở mức trial vì còn phụ thuộc năng lực phần cứng, độ trễ và mức hoàn thiện khi tích hợp vào sản phẩm thực tế.

📖 Giới thiệu chi tiết

🧩 Nó là gì?

huggingface/speech-to-speech là một toolkit mã nguồn mở giúp bạn dựng voice agent chạy cục bộ: bạn nói vào micro, AI nghe, hiểu, trả lời, rồi đọc câu trả lời thành tiếng. Nói đơn giản, đây là bộ khung để làm “trợ lý giọng nói” bằng các mô hình open-source.

🎯 Giải quyết vấn đề gì? Dành cho ai?

Dự án này giải quyết bài toán xây dựng một hệ thống hội thoại bằng giọng nói từ đầu đến cuối, gồm:

• Nghe giọng nói của người dùng
• Chuyển giọng nói thành chữ
• Đưa chữ đó cho mô hình ngôn ngữ xử lý
• Chuyển câu trả lời từ chữ thành giọng nói
• Trả âm thanh lại gần như theo thời gian thực

huggingface/speech-to-speech phù hợp với:

• Người mới muốn hiểu voice agent hoạt động như thế nào
• Developer muốn thử làm trợ lý giọng nói chạy local
• Nhóm nghiên cứu hoặc prototype sản phẩm AI thoại
• Người muốn dùng mô hình mã nguồn mở thay vì phụ thuộc hoàn toàn vào dịch vụ đóng
• Dự án robot, thiết bị nhúng, app desktop hoặc server có giao tiếp bằng giọng nói

Ví dụ thực tế: pipeline này đang được dùng làm backend hội thoại cho hàng nghìn robot Reachy Mini.

⚙️ Hoạt động ra sao?

Cơ chế chính của huggingface/speech-to-speech là một pipeline gồm nhiều bước nối tiếp nhau:

• VAD - Voice Activity Detection: phát hiện khi nào người dùng bắt đầu nói và khi nào dừng nói. Dự án dùng Silero VAD v5 mặc định.
• STT - Speech to Text: chuyển giọng nói thành văn bản. Mặc định dùng Parakeet TDT, ngoài ra có thể dùng Whisper, Faster Whisper, Paraformer, v.v.
• LLM - Language Model: mô hình ngôn ngữ nhận văn bản và tạo câu trả lời. Có thể dùng API tương thích OpenAI, HF Inference Providers, hoặc server local như vLLM và llama.cpp.
• TTS - Text to Speech: chuyển câu trả lời dạng chữ thành giọng nói. Mặc định dùng Qwen3-TTS, có thể đổi sang Kokoro-82M, Pocket TTS, ChatTTS, MMS TTS, v.v.
• WebSocket API: server expose API tương thích OpenAI Realtime tại ws://localhost:8765/v1/realtime, nên client hỗ trợ chuẩn này có thể kết nối khá dễ.
• Modular: mỗi phần có thể thay thế bằng backend khác qua CLI flags như --stt, --llm_backend, --tts.

Luồng tổng quát:

microphone audio
  -> VAD
  -> STT
  -> LLM
  -> TTS
  -> speaker audio

🆚 Khi nào nên dùng / không nên

Nên dùng huggingface/speech-to-speech khi:

• Bạn muốn thử hoặc học cách xây dựng voice agent end-to-end
• Bạn cần một pipeline có sẵn thay vì tự ghép từng phần
• Bạn muốn chạy nhiều thành phần local bằng mô hình open-source
• Bạn muốn dùng API tương thích OpenAI Realtime nhưng backend có thể tự host
• Bạn muốn linh hoạt đổi STT, LLM, TTS theo phần cứng và nhu cầu

Không nên dùng, hoặc cần cân nhắc, khi:

• Bạn cần một sản phẩm ổn định tuyệt đối cho production ngay lập tức
• Máy của bạn yếu, không có GPU, hoặc không đủ RAM/VRAM cho mô hình giọng nói
• Bạn cần độ trễ cực thấp và chất lượng âm thanh đồng đều trên mọi thiết bị
• Bạn không muốn xử lý vấn đề cài đặt CUDA, driver, model backend
• Bạn chỉ cần gọi API giọng nói đơn giản, không cần tự host hay tùy biến sâu

So với việc dùng thẳng dịch vụ cloud như OpenAI Realtime API, huggingface/speech-to-speech cho bạn nhiều quyền kiểm soát hơn và có thể chạy local, nhưng đổi lại việc cài đặt, tối ưu độ trễ và chọn mô hình sẽ phức tạp hơn.

🚀 Bắt đầu nhanh

Yêu cầu cơ bản:

• Python 3.10+
• Máy có micro và loa nếu muốn nói chuyện trực tiếp
• GPU sẽ tốt hơn, nhưng một số backend có thể chạy CPU
• Nếu dùng LLM qua OpenAI-compatible API, cần cấu hình API key phù hợp

Cài đặt nhanh từ PyPI:

pip install speech-to-speech

Chạy server mặc định:

export OPENAI_API_KEY=...
speech-to-speech

Lệnh này khởi động server tương thích OpenAI Realtime tại:

ws://localhost:8765/v1/realtime

Mặc định, pipeline sẽ dùng:

VAD: Silero VAD v5
STT: Parakeet TDT
LLM: OpenAI-compatible API
TTS: Qwen3-TTS

Nếu bạn checkout source code và muốn thử nói chuyện từ terminal thứ hai:

git clone https://github.com/huggingface/speech-to-speech.git
cd speech-to-speech
uv sync

Terminal 1:

export OPENAI_API_KEY=...
speech-to-speech

Terminal 2:

python scripts/listen_and_play_realtime.py --host 127.0.0.1 --port 8765

Nếu muốn chạy LLM local bằng llama.cpp, ví dụ với Gemma 4:

llama-server -hf ggml-org/gemma-4-E4B-it-GGUF -np 2 -c 65536 -fa on --swa-full

Sau đó trỏ speech-to-speech sang server local đó:

speech-to-speech \
    --model_name "ggml-org/gemma-4-E4B-it-GGUF" \
    --responses_api_base_url "http://127.0.0.1:8080/v1" \
    --responses_api_api_key ""

Trên macOS Apple Silicon, có thể thử cấu hình tối ưu local:

speech-to-speech --local_mac_optimal_settings

✅ Điểm mạnh & ⚠️ Hạn chế

Điểm mạnh:

• Pipeline đầy đủ từ nghe, hiểu, trả lời đến đọc thành tiếng
• Có thể chạy local với nhiều mô hình mã nguồn mở
• Tương thích OpenAI Realtime, dễ kết nối với client quen thuộc
• Mỗi thành phần có thể thay thế: STT, LLM, TTS đều có nhiều backend
• Hữu ích để học, prototype và thử nghiệm voice agent thực tế
• Đã được dùng trong backend hội thoại cho Reachy Mini

Hạn chế:

• Phụ thuộc nhiều vào phần cứng, đặc biệt là GPU/RAM/VRAM
• Cài đặt có thể phức tạp nếu gặp vấn đề CUDA, backend TTS hoặc dependency
• Độ trễ và chất lượng giọng nói thay đổi tùy mô hình và máy chạy
• Phù hợp nhất ở mức thử nghiệm/prototype trước khi đưa vào sản phẩm nghiêm túc
• Muốn production ổn định cần thêm kiểm thử, giám sát, tối ưu và xử lý lỗi
• Người mới có thể cần thời gian để hiểu các lựa chọn như VAD, STT, LLM, TTS