xAI 보이스 에이전트

xAI 보이스 에이전트 (Realtime API)

xAI의 Grok Voice Agent를 LiteLLM에서 사용하는 방법을 알아봐요. WebSocket 연결로 실시간 음성 대화를 지원해요.

출처: 문서

본문

xAI의 Grok Voice Agent는 WebSocket 연결을 통해 실시간 음성 대화 기능을 제공해서, 자연스러운 양방향 오디오 상호작용을 가능하게 해요.

빠른 시작

지원 모델

이들은 실시간 speech-to-speech 대화를 위해 만들어진 전용 풀-듀플렉스 모델이에요. 함수 호출, 웹 검색, X 검색, 컬렉션 검색, 원격 MCP 도구, 자동 언어 감지와 함께 20개 이상의 언어를 지원해요. 아래 예시는 항상 최신 릴리스를 추적하는 grok-voice-latest를 사용하며, 릴리스 간 안정적인 동작이 필요하면 grok-voice-think-fast-1.0 같은 버전명으로 고정해요.

LiteLLM이 연결하는 방식

LiteLLM은 xAI의 Voice Agent를 AI 게이트웨이를 통해 제공하므로, 실시간 트래픽은 직접 Python SDK 호출 대신 proxy의 OpenAI 호환 /v1/realtime WebSocket 엔드포인트를 거쳐요. 표준 WebSocket 클라이언트(Python websockets, Node ws, OpenAI SDK)를 게이트웨이에 연결하면, proxy가 올바른 모델과 인증 헤더로 세션을 wss://api.x.ai/v1/realtime에 전달해요.

LiteLLM Proxy (AI Gateway) 사용법

여러 xAI 배포에 로드 밸런싱하거나 다른 제공사와 결합할 수 있어요.

1. config에 모델 추가

model_list:
  - model_name: grok-voice-agent
    litellm_params:
      model: xai/grok-voice-latest
      api_key: os.environ/XAI_API_KEY
    model_info:
      mode: realtime

  # Optional: Add fallback to OpenAI
  - model_name: grok-voice-agent
    litellm_params:
      model: openai/gpt-4o-realtime-preview-2024-10-01
      api_key: os.environ/OPENAI_API_KEY
    model_info:
      mode: realtime

2. Proxy 시작

litellm --config /path/to/config.yaml

# RUNNING on http://0.0.0.0:4000

3. 연결 테스트

Python 클라이언트:

import asyncio
import websockets
import json

async def test_proxy():
    url = "ws://0.0.0.0:4000/v1/realtime?model=grok-voice-agent"

    async with websockets.connect(
        url,
        extra_headers={
            "Authorization": "Bearer sk-",  # Your LiteLLM proxy key
            "OpenAI-Beta": "realtime=v1"
        }
    ) as ws:
        # First event from the server is session.created
        message = await ws.recv()
        print(f"Connected: {message}")

        # Send a message
        await ws.send(json.dumps({
            "type": "conversation.item.create",
            "item": {
                "type": "message",
                "role": "user",
                "content": [{
                    "type": "input_text",
                    "text": "Hello from LiteLLM proxy!"
                }]
            }
        }))

        # Request response
        await ws.send(json.dumps({
            "type": "response.create"
        }))

        # Listen for response
        async for message in ws:
            data = json.loads(message)
            print(f"Event: {data['type']}")

            if data['type'] == 'response.done':
                break

asyncio.run(test_proxy())

Node.js 클라이언트:

// test.js - Run with: node test.js
const WebSocket = require("ws");

const url = "ws://0.0.0.0:4000/v1/realtime?model=grok-voice-agent";

const ws = new WebSocket(url, {
    headers: {
        "Authorization": "Bearer sk-",
        "OpenAI-Beta": "realtime=v1",
    },
});

ws.on("open", function open() {
    console.log("Connected to xAI via LiteLLM proxy");

    // Send a message
    ws.send(JSON.stringify({
        type: "conversation.item.create",
        item: {
            type: "message",
            role: "user",
            content: [{
                type: "input_text",
                text: "What's the weather like?"
            }]
        }
    }));

    // Request response
    ws.send(JSON.stringify({
        type: "response.create",
        response: {
            modalities: ["text"],
            instructions: "Please assist the user."
        }
    }));
});

ws.on("message", function incoming(message) {
    const data = JSON.parse(message.toString());
    console.log(`Event: ${data.type}`);

    if (data.type === 'response.done') {
        ws.close();
    }
});

ws.on("error", function handleError(error) {
    console.error("Error: ", error);
});

OpenAI와의 주요 차이점

xAI의 Grok Voice Agent는 OpenAI의 Realtime API와 몇 가지 차이가 있어요:

LiteLLM은 xAI 엔드포인트를 자동 구성하고, 인증 헤더를 설정하며(xAI에는 OpenAI-Beta 헤더를 보내지 않음), WebSocket 연결을 관리해요. 그 외에는 xAI 특유의 처리가 필요 없어요. Voice Agent API는 OpenAI 호환이며 OpenAI처럼 연결 시 session.created를 내보내요. 오디오 응답은 response.output_audio.delta로 스트리밍되고, 일치하는 전사본은 response.output_audio_transcript.delta에 있어요.

관련 문서

• xAI 채팅/텍스트 모델
• LiteLLM Realtime API 개요
• xAI 공식 문서

지원

문제나 질문이 있다면:

• LiteLLM GitHub Issues
• xAI 문서

더 알아보기 (Learn more)

• xAI 보이스 에이전트
• LiteLLM Realtime API