Speech Engine 빠른 시작
ElevenLabs SDK를 사용해 채팅 에이전트에 음성을 추가하세요.
이 가이드에서는 Speech Engine으로 음성 기반 에이전트를 구축하는 방법을 안내합니다. LLM을 ElevenLabs에 연결하는 서버를 설정한 다음, 사용자가 에이전트와 음성으로 대화할 수 있도록 브라우저 클라이언트를 연결합니다.
ElevenLabs Speech Engine 스킬을 사용해 채팅 에이전트에 음성을 추가하세요.
Speech Engine 작동 방식
Speech Engine은 사용자가 에이전트에게 말하고 응답을 들을 수 있도록 LLM을 ElevenLabs에 연결합니다. ElevenLabs가 음성-텍스트 변환과 텍스트 음성 변환을 처리하며, 서버에서 LLM 로직을 제공합니다.
각 WebSocket 연결은 하나의 대화를 나타냅니다. 사용자가 말하면 ElevenLabs가 오디오를 전사하고 전사문을 서버로 보냅니다. 서버는 이를 LLM에 전달한 다음 응답을 스트리밍하여 다시 보냅니다. ElevenLabs는 텍스트를 음성으로 변환해 브라우저에서 재생합니다. SDK가 연결 관리, 턴 관리, 인터럽트 감지를 처리합니다.
사전 요구 사항
이 튜토리얼에서는 LLM에 OpenAI API를 사용합니다. OPENAI_API_KEY 환경 변수에 설정된 OpenAI API 키가 필요합니다.
서버 설정
API 키 만들기
여기 대시보드에서 API 키를 생성하세요. 이 키는 API에 안전하게 액세스하는 데 사용됩니다.
키를 관리형 시크릿으로 저장하고, 선호에 따라 .env 파일을 통한 환경 변수 또는 앱 구성에서 직접 SDK에 전달하세요.
서버 공개
Speech Engine에는 공개적으로 액세스할 수 있는 URL이 필요합니다. ngrok을 사용해 로컬 서버를 공개하세요. 서버는 아직 구축하지 않았지만, 다음 단계에서 사용할 URL을 확보하려면 먼저 ngrok을 실행해야 합니다.
포워딩 URL(예: https://abc123.ngrok.io)을 복사하세요.
Speech Engine 인스턴스 만들기
SDK를 사용해 Speech Engine 인스턴스를 만들고, /ws 경로를 추가한 ngrok URL을 WebSocket URL로 전달하세요.
이 스크립트를 실행하고 다음 단계에서 사용할 Speech Engine ID(예: seng_8k3m9xr4hjnfg983brhmhkd98n6)를 복사하세요.
서버 만들기
다음 내용으로 server.py 또는 server.mts 파일을 만드세요. 서버를 설정하고, /ws 경로에 Speech Engine을 연결하며, OpenAI를 사용해 응답을 생성합니다.
onTranscript / on_transcript 콜백은 전체 대화 기록과 현재 세션을 받습니다. TypeScript SDK는 사용자가 응답 도중 인터럽트하면 실행되는 AbortSignal도 제공합니다. signal을 OpenAI 호출에 전달하면 인터럽트 시 LLM 요청이 자동으로 취소됩니다.
sendResponse() / send_response()는 문자열, 비동기 이터러블 또는 OpenAI, Anthropic, Google Gemini의 스트림을 받습니다. SDK가 텍스트 콘텐츠를 자동으로 추출합니다.
위 예시에서는 사용자의 전체 전사문이 LLM에 전달됩니다. 프로덕션 환경에서는 프롬프트 인젝션이나 조작 시도를 방지하기 위한 가드레일을 추가해야 합니다.
클라이언트 설정
토큰 엔드포인트 만들기
대화 토큰을 생성하는 서버 측 엔드포인트를 추가하세요. 이렇게 하면 API 키를 브라우저에 노출하지 않으면서 최상의 오디오 품질을 위해 WebRTC를 사용할 수 있습니다.
테스트하기
다음 3개의 프로세스가 실행 중인지 확인하세요.
- ngrok - 포트 3001로 포워딩
- Speech Engine 서버 -
python server.py또는npx tsx server.mts - 토큰 서버 -
npx tsx token-server.mts또는python token_server.py
브라우저에서 클라이언트 애플리케이션을 열고 대화 시작을 클릭하세요. 메시지가 표시되면 마이크 액세스를 허용한 후 말해 보세요. 스피커를 통해 에이전트의 응답을 들을 수 있습니다.
서버에서 debug: true를 활성화했다면 콘솔에서 들어오는 전사문과 나가는 응답이 기록되는 것을 볼 수 있습니다.
세션 이벤트
첫 번째 에이전트 메시지 구성
기본적으로 에이전트는 사용자가 먼저 말할 때까지 기다립니다. 대화가 시작될 때 에이전트가 사용자에게 인사하도록 하려면 세션 시작 시 클라이언트의 overrides 옵션에 첫 번째 메시지를 설정하세요.
첫 번째 메시지는 연결이 설정되는 즉시 에이전트가 말합니다. 서버의 onTranscript 콜백을 트리거하지 않으며, ElevenLabs 측에서 전적으로 처리됩니다.
최대 대화 시간 구성
기본적으로 대화는 600초(10분) 후에 종료됩니다. Speech Engine은 최대 7,200초(2시간)의 대화를 지원합니다. 더 긴 대화를 허용하려면 max_duration_seconds를 더 높은 값으로 설정하여 Speech Engine 리소스를 업데이트하세요.
대시보드에서도 설정할 수 있습니다. Speech Engine을 열고 고급 탭으로 이동한 다음 대화 동작 아래에서 최대 대화 시간을 설정하세요.