Szybki start z Speech Engine
Dodaj głos do swojego agenta czatu za pomocą SDK ElevenLabs.
Ten przewodnik pokaże ci, jak stworzyć agenta głosowego z Speech Engine. Skonfigurujesz serwer, który połączy twój LLM z ElevenLabs, a potem klienta w przeglądarce, aby użytkownicy mogli rozmawiać głosowo z twoim agentem.
Użyj umiejętności ElevenLabs Speech Engine, aby dodać głos do swojego agenta czatu:
Jak działa Speech Engine
Speech Engine łączy twój LLM z ElevenLabs, aby użytkownicy mogli mówić do twojego agenta i słyszeć jego odpowiedzi. ElevenLabs obsługuje zamianę mowy na tekst i zamianę tekstu na mowę, a twój serwer zapewnia logikę LLM.
Każde połączenie WebSocket reprezentuje jedną rozmowę. Gdy użytkownik mówi, ElevenLabs transkrybuje dźwięk i wysyła transkrypcję na twój serwer. Twój serwer przekazuje ją do LLM, a następnie strumieniuje odpowiedź z powrotem. ElevenLabs zamienia tekst na mowę i odtwarza go w przeglądarce. SDK obsługuje zarządzanie połączeniem, zmianę tury i wykrywanie przerwań.
Wymagania wstępne
Ten samouczek używa API OpenAI dla LLM. Potrzebujesz klucza API OpenAI ustawionego w zmiennej środowiskowej OPENAI_API_KEY.
Konfiguracja serwera
Utwórz klucz API
Utwórz klucz API w panelu tutaj, którego użyjesz, aby bezpiecznie uzyskać dostęp do API.
Przechowuj klucz jako zarządzany sekret i przekaż go do SDK jako zmienną środowiskową w pliku .env lub bezpośrednio w konfiguracji aplikacji — zależnie od preferencji.
Udostępnij serwer
Speech Engine potrzebuje publicznie dostępnego adresu URL. Użyj ngrok, aby udostępnić lokalny serwer. Serwer nie jest jeszcze gotowy, ale ngrok musi działać wcześniej, aby w kolejnym kroku mieć adres URL.
Skopiuj adres URL przekierowania (np. https://abc123.ngrok.io).
Utwórz instancję Speech Engine
Użyj SDK, aby utworzyć instancję Speech Engine, przekazując adres URL ngrok z dodaną ścieżką /ws jako adres WebSocket.
Uruchom ten skrypt i skopiuj identyfikator Speech Engine (np. seng_8k3m9xr4hjnfg983brhmhkd98n6) do kolejnego kroku.
Utwórz serwer
Utwórz plik o nazwie server.py lub server.mts z poniższą zawartością. Konfiguruje on serwer, podłącza Speech Engine pod ścieżką /ws i używa OpenAI do generowania odpowiedzi.
Wywołanie zwrotne onTranscript / on_transcript otrzymuje pełną historię rozmowy i bieżącą sesję. SDK TypeScript udostępnia też AbortSignal, który uruchamia się, gdy użytkownik przerwie odpowiedź w trakcie. Przekazanie signal do wywołania OpenAI automatycznie anuluje żądanie LLM po przerwaniu.
sendResponse() / send_response() przyjmuje ciąg znaków, asynchroniczny iterowalny obiekt lub strumień z OpenAI, Anthropic albo Google Gemini. SDK automatycznie wyodrębnia treść tekstową.
W powyższym przykładzie pełna transkrypcja od użytkownika jest przekazywana do LLM. W środowisku produkcyjnym dodaj zabezpieczenia, aby zapobiec próbom wstrzykiwania promptów i manipulacji.
Konfiguracja klienta
Utwórz endpoint tokenu
Dodaj endpoint po stronie serwera, który generuje token rozmowy. Dzięki temu klucz API nie trafia do przeglądarki, a WebRTC zapewnia najlepszą jakość dźwięku.
Zbuduj interfejs rozmowy
Pobierz token rozmowy z serwera i użyj go do rozpoczęcia sesji.
React
JavaScript
Wypróbuj
Upewnij się, że działają trzy procesy:
- ngrok – przekierowuje do portu 3001
- Twój serwer Speech Engine –
python server.pylubnpx tsx server.mts - Serwer tokenów –
npx tsx token-server.mtslubpython token_server.py
Otwórz aplikację kliencką w przeglądarce i kliknij Rozpocznij rozmowę. Gdy pojawi się prośba, zezwól na dostęp do mikrofonu, a potem zacznij mówić. Powinieneś usłyszeć odpowiedź agenta w głośnikach.
Jeśli na serwerze masz włączone debug: true, w konsoli zobaczysz logi przychodzących transkrypcji i wysyłanych odpowiedzi.
Zdarzenia sesji
Konfiguracja pierwszej wiadomości agenta
Domyślnie agent czeka, aż użytkownik odezwie się pierwszy. Aby agent przywitał użytkownika na początku rozmowy, ustaw pierwszą wiadomość w opcji overrides klienta podczas uruchamiania sesji.
Pierwsza wiadomość jest wypowiadana przez agenta zaraz po nawiązaniu połączenia. Nie uruchamia wywołania zwrotnego onTranscript na twoim serwerze – jest obsługiwana w całości po stronie ElevenLabs.
Konfiguracja maksymalnego czasu rozmowy
Domyślnie rozmowa kończy się po 600 sekundach (10 minutach). Speech Engine obsługuje rozmowy trwające do 2400 sekund (40 minut). Aby zezwolić na dłuższe rozmowy, zaktualizuj zasób Speech Engine, ustawiając wyższą wartość max_duration_seconds:
Możesz też ustawić to w panelu: otwórz Speech Engine, przejdź do karty Zaawansowane i ustaw Maksymalny czas rozmowy w sekcji Zachowanie w rozmowie.
Rozmowy dłuższe niż 40 minut nie są obsługiwane i mogą zostać rozłączone, nawet jeśli
max_duration_seconds ma wyższą wartość. Jeśli potrzebujesz dłuższych rozmów, skontaktuj się z naszym
zespołem.