> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LiveKit Agents

> LiveKit Agents와 Venice로 실시간 음성 에이전트를 구축하고, OpenAI 호환 플러그인을 통해 Venice STT, LLM, TTS를 STT-LLM-TTS 파이프라인으로 연결하세요.

[LiveKit Agents](https://docs.livekit.io/agents/)는 실시간 음성 AI를 구축하기 위한 프레임워크입니다. Venice는 채팅, 트랜스크립션, 스피치 모두 OpenAI와 완전히 호환되므로, 음성 에이전트의 세 단계 — **음성-텍스트 변환(STT)**, **LLM**, **텍스트-음성 변환(TTS)** — 를 모두 `livekit-plugins-openai` 플러그인을 Venice base URL로 지정하여 구동할 수 있습니다.

<Note>
  Venice는 LiveKit Agents의 **STT-LLM-TTS 파이프라인** 아키텍처에 적합합니다. Venice는 OpenAI Realtime(스피치-투-스피치) WebSocket API를 제공하지 않으므로 `RealtimeModel` / 멀티모달 경로는 사용할 수 없습니다. 아래에 표시된 컴포넌트 기반 파이프라인을 사용하세요. 각 모델을 완전히 제어할 수 있으며 추론은 Venice의 프라이빗 인프라 안에서 유지됩니다.
</Note>

## Venice가 LiveKit Agents에 매핑되는 방식

| LiveKit 컴포넌트 | Venice 엔드포인트                 | 플러그인 클래스     |
| ------------ | ---------------------------- | ------------ |
| LLM          | `POST /chat/completions`     | `openai.LLM` |
| STT          | `POST /audio/transcriptions` | `openai.STT` |
| TTS          | `POST /audio/speech`         | `openai.TTS` |
| 턴 감지 (VAD)   | — (로컬에서 실행됨)                 | `silero.VAD` |

## 설정

프레임워크와 아래에서 사용할 플러그인을 설치하세요:

```bash theme={"system"}
pip install \
  "livekit-agents[openai,silero,turn-detector]" \
  livekit-plugins-openai \
  livekit-plugins-silero
```

Venice API 키와 LiveKit 연결 정보를 설정하세요:

```bash theme={"system"}
export VENICE_API_KEY="your-venice-api-key"

# LiveKit Cloud or self-hosted server
export LIVEKIT_URL="wss://your-project.livekit.cloud"
export LIVEKIT_API_KEY="your-livekit-api-key"
export LIVEKIT_API_SECRET="your-livekit-api-secret"
```

<Note>
  OpenAI 플러그인은 `api_key`가 생략되면 `OPENAI_API_KEY`로 대체됩니다. Venice를 지정하고 있으므로 항상 `api_key`를 명시적으로 전달하세요(그렇지 않으면 잘못된 환경 변수에서 키를 읽게 됩니다). 아래 예제는 `VENICE_API_KEY`를 읽습니다.
</Note>

## 전체 음성 에이전트

다음은 Venice STT로 트랜스크립션하고, Venice LLM으로 사고하며, Venice TTS로 말하는 완전한 음성 에이전트입니다. Silero가 로컬 음성 활동 감지를 제공하여 배치 STT가 언제 턴이 끝났는지 파악할 수 있게 합니다.

```python theme={"system"}
import os

from livekit import agents
from livekit.agents import Agent, AgentSession, RoomInputOptions
from livekit.plugins import openai, silero

VENICE_BASE_URL = "https://api.venice.ai/api/v1"
VENICE_API_KEY = os.environ["VENICE_API_KEY"]


class Assistant(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions="You are a helpful, concise voice assistant powered by Venice.",
        )


async def entrypoint(ctx: agents.JobContext):
    session = AgentSession(
        # Speech-to-text — Venice /audio/transcriptions
        stt=openai.STT(
            model="nvidia/parakeet-tdt-0.6b-v3",
            base_url=VENICE_BASE_URL,
            api_key=VENICE_API_KEY,
        ),
        # LLM — Venice /chat/completions (streaming + tool calling supported)
        # Venice's private, uncensored model feeding the STT-LLM-TTS pipeline
        llm=openai.LLM(
            model="venice-uncensored-1-2",
            base_url=VENICE_BASE_URL,
            api_key=VENICE_API_KEY,
        ),
        # Text-to-speech — Venice /audio/speech
        tts=openai.TTS(
            model="tts-kokoro",
            voice="af_sky",
            base_url=VENICE_BASE_URL,
            api_key=VENICE_API_KEY,
        ),
        # Local VAD handles endpointing for the batch STT
        vad=silero.VAD.load(),
    )

    await session.start(
        room=ctx.room,
        agent=Assistant(),
        room_input_options=RoomInputOptions(),
    )

    await session.generate_reply(
        instructions="Greet the user and offer your help."
    )


if __name__ == "__main__":
    agents.cli.run_app(agents.WorkerOptions(entrypoint_fnc=entrypoint))
```

개발 모드로 실행:

```bash theme={"system"}
python agent.py dev
```

## 각 컴포넌트 설정하기

### LLM

LLM은 가장 깔끔한 매핑입니다 — Venice `/chat/completions`는 SSE 스트리밍, 툴 호출, 비전을 모두 지원하며 LiveKit이 이 모든 것을 직접 사용합니다. `venice-uncensored-1-2`는 추론을 프라이빗하고 검열 없이 유지하면서 TTS 파이프라인에 공급합니다. 첫 토큰까지의 시간이 더 짧아야 하는 경우에만 `flash` 클래스 모델을 선택하세요.

```python theme={"system"}
llm = openai.LLM(
    model="venice-uncensored-1-2",
    base_url="https://api.venice.ai/api/v1",
    api_key=os.environ["VENICE_API_KEY"],
    temperature=0.7,
)
```

Venice 고유 옵션(웹 검색, 캐릭터 페르소나, 사고 제어)은 `extra_body`를 통해 전달하세요:

```python theme={"system"}
llm = openai.LLM(
    model="venice-uncensored-1-2",
    base_url="https://api.venice.ai/api/v1",
    api_key=os.environ["VENICE_API_KEY"],
    extra_body={"venice_parameters": {"enable_web_search": "auto"}},
)
```

### Speech-to-Text

LiveKit의 OpenAI STT는 음성 세그먼트마다 `/audio/transcriptions`를 호출하므로, 턴이 언제 끝나는지 감지하기 위해 VAD(위의 Silero)가 필요합니다. 기본 모델을 Venice STT 모델로 재정의하세요. `nvidia/parakeet-tdt-0.6b-v3`는 가장 작고 지연 시간이 낮은 옵션이며, 더 높은 정확도가 필요하다면 `stt-xai-v1`이나 `elevenlabs/scribe-v2`가 최신 대안입니다.

```python theme={"system"}
stt = openai.STT(
    model="nvidia/parakeet-tdt-0.6b-v3",
    base_url="https://api.venice.ai/api/v1",
    api_key=os.environ["VENICE_API_KEY"],
    language="en",          # or detect_language=True
    use_realtime=False,     # Venice has no realtime STT socket; keep batch mode
)
```

### Text-to-Speech

LiveKit의 OpenAI TTS는 `/audio/speech`를 호출합니다. Venice에서 음성은 모델별로 정해져 있으므로 — 동일한 모델의 `model`/`voice` 쌍을 전달하세요. `tts-kokoro`는 음성 단계를 프라이빗하고 검열 없이 유지하여 LLM의 출력을 그대로 말할 수 있습니다. MP3 디코드 단계를 피하고 지연 시간을 약간 줄이려면 `pcm`을 요청하세요. 프로바이더 기반의 더 빠른 음성(예: Gemini)은 콘텐츠 필터링을 적용할 수 있으므로, 검열 없는 음성이 필요하다면 피하세요.

```python theme={"system"}
tts = openai.TTS(
    model="tts-kokoro",
    voice="af_sky",
    base_url="https://api.venice.ai/api/v1",
    api_key=os.environ["VENICE_API_KEY"],
    response_format="pcm",  # mp3 | opus | aac | flac | wav | pcm
    speed=1.0,
)
```

## 권장 모델

모델 ID는 시간이 지남에 따라 변경됩니다 — 하드코딩하는 대신 **런타임에 `GET /models?type=...` 및 `GET /models/traits`로 현재 옵션을 확인하세요**. 음성 에이전트의 경우 체감 응답성은 첫 토큰까지의 시간과 TTS 속도에 의존하므로 저지연 티어(이름에 `flash`, `turbo`, `mini`가 있거나 파라미터 수가 적은 모델)를 우선시하세요. 현재 카탈로그에서 시작하기 좋은 지점들:

| 컴포넌트                       | 모델                                                                    | 이유                                      |
| -------------------------- | --------------------------------------------------------------------- | --------------------------------------- |
| LLM (프라이빗 + 검열 없음, 음성 기본값) | `venice-uncensored-1-2`                                               | TTS 파이프라인에 공급되는 Venice의 프라이빗하고 검열 없는 모델 |
| LLM (빠른 대안)                | `gemini-3-5-flash`, `zai-org-glm-4.7-flash`, `deepseek-v4-flash`      | 첫 토큰까지 시간이 더 짧아야 할 경우의 Flash 클래스        |
| LLM (추론 / 툴)               | `zai-org-glm-5-2`, `grok-4-5`                                         | 복잡한 툴 사용을 위한 최신 플래그십                    |
| STT (최저 지연)                | `nvidia/parakeet-tdt-0.6b-v3`                                         | 작고 빠르며 다국어 지원                           |
| STT (최신 / 정확도)             | `stt-xai-v1`, `elevenlabs/scribe-v2`                                  | 최신 트랜스크립션 모델                            |
| TTS (프라이빗 + 검열 없음, 음성 기본값) | `tts-kokoro`                                                          | 폭넓은 음성 카탈로그, 저지연, 출력을 그대로 발화            |
| TTS (빠른 대안)                | `tts-gemini-3-1-flash`, `tts-elevenlabs-turbo-v2-5`, `tts-qwen3-0-6b` | 더 빠른 티어이지만 프로바이더 기반 음성은 콘텐츠를 필터링할 수 있음  |

<Card title="모든 모델 둘러보기" icon="database" href="/models/overview">
  텍스트, 음성-텍스트, 텍스트-음성으로 필터링하고 실시간 가격 및 기능을 확인하세요.
</Card>

## 지연 시간 및 프로덕션 팁

음성 에이전트의 품질은 턴 전환 지연 시간 — 사용자가 문장을 끝낸 시점과 에이전트가 말하기 시작하는 시점 사이의 시간 — 에 좌우됩니다. 전체 Venice 파이프라인에서는 대략 다음을 예상하세요:

| 단계             | 기여           | 참고                                                               |
| -------------- | ------------ | ---------------------------------------------------------------- |
| VAD 엔드포인팅      | 약 300–700 ms | 턴이 완료된 것으로 간주되기 전의 후행 무음. Silero의 `min_silence_duration`을 조정하세요. |
| STT            | 수백 ms        | 단일 요청/응답, 중간 결과 없음.                                              |
| LLM 첫 토큰까지의 시간 | 작음 (중첩됨)     | 스트리밍되므로 TTS에 파이프라인됩니다.                                           |
| TTS 첫 오디오      | 수백 ms        | LiveKit이 문장 단위로 합성하므로 재생은 전체 응답이 아닌 첫 문장 이후에 시작됩니다.              |

**첫 오디오까지 약 0.8–1.5초**를 예상하세요 — 어시스턴트 스타일의 차분한 턴 전환에는 훌륭합니다. 매우 자주 끊기고 겹치는 대화의 경우에는 네이티브 스피치-투-스피치 모델 대비 간격이 느껴질 것입니다.

### 지연 시간 줄이기

* TTS에서 `response_format="pcm"`을 사용해 MP3 디코드 단계를 건너뛰세요.
* Silero VAD를 조정(`silero.VAD.load(min_silence_duration=0.4)`)하여 음성을 잘라내지 않고 엔드포인팅을 단축하세요.
* STT/TTS에는 저지연 티어를 선호하세요(예: `tts-kokoro` TTS, `nvidia/parakeet-tdt-0.6b-v3` STT). 프라이빗하고 검열 없이 유지하려면 LLM은 `venice-uncensored-1-2`를 유지하세요. 첫 토큰까지의 시간이 더 빨라야 할 때만 `flash` 클래스 LLM으로 전환하세요.
* 답변을 간결하게 유지하세요 — 체감 응답성을 좌우하는 것은 첫 문장입니다.

### 프로바이더 혼합

LiveKit은 각 컴포넌트를 독립적으로 선택할 수 있게 해주므로, 프라이버시와 검열 없는 모델이 가장 중요한 곳에서는 Venice를 유지하고 지연 시간이 중요한 곳에서는 스트리밍 프로바이더로 교체할 수 있습니다. 상호작용이 많은 일반적인 구성은 Venice LLM(및 선택적으로 STT)을 유지하면서 전용 스트리밍 TTS와 페어링하는 방식입니다:

```python theme={"system"}
from livekit.plugins import openai, silero
# from livekit.plugins import cartesia  # example streaming TTS

session = AgentSession(
    stt=openai.STT(
        model="nvidia/parakeet-tdt-0.6b-v3",
        base_url="https://api.venice.ai/api/v1",
        api_key=os.environ["VENICE_API_KEY"],
    ),
    llm=openai.LLM(
        model="venice-uncensored-1-2",
        base_url="https://api.venice.ai/api/v1",
        api_key=os.environ["VENICE_API_KEY"],
    ),
    # Swap in a streaming TTS for the snappiest voice output
    tts=cartesia.TTS(voice="..."),
    vad=silero.VAD.load(),
)
```

<Tip>
  가장 단순하고 가장 프라이빗한 설정을 위해 전체 Venice로 시작하세요. 빠르고 대화형이 강한 소비자 경험을 구축한다면 Venice LLM을 유지하고 음성 출력 단계에는 스트리밍 TTS를 평가해보세요.
</Tip>

## 제약 사항 및 참고

* **스피치-투-스피치 / Realtime API 없음.** Venice에는 OpenAI Realtime WebSocket이 없으므로 `openai.realtime.RealtimeModel` 및 멀티모달 에이전트 경로는 사용할 수 없습니다. 위에 나온 STT-LLM-TTS 파이프라인을 사용하세요.
* **STT는 배치이며 스트리밍이 아닙니다.** Venice 트랜스크립션은 요청/응답 방식이므로 엔드포인팅을 위해 VAD(Silero)가 필요합니다. 이는 스트리밍 STT 소켓 대비 약간의 지연 시간을 추가합니다.
* **TTS는 플러그인에 의해 버퍼링됩니다.** LiveKit의 OpenAI TTS 래퍼는 `streaming=False`를 보고하므로 Venice의 문장 단위 `streaming` 플래그를 사용하지 않습니다. 그래도 대부분의 에이전트에서 지연 시간은 충분히 양호합니다. 디코드 오버헤드를 최소화하려면 `response_format="pcm"`을 사용하세요.
* **음성을 모델과 일치시키세요.** TTS `voice` ID는 매칭되는 `model`에서만 유효합니다. [Text-to-Speech Models](/models/text-to-speech)를 참조하세요.
* **모델 목록을 하드코딩하지 마세요.** Venice 모델 ID는 정기적으로 폐기 및 교체됩니다 — 런타임에 `GET /models` / `GET /models/traits`를 쿼리하세요. [Deprecations](/overview/deprecations)를 참조하세요.

## 관련 리소스

* [LiveKit Agents 문서](https://docs.livekit.io/agents/)
* [Speech-to-Text 가이드](/guides/media/speech-to-text) · [모델](/models/speech-to-text)
* [Text-to-Speech 가이드](/guides/media/text-to-speech) · [모델](/models/text-to-speech)
* [함수 호출](/guides/features/function-calling)
* [AI 에이전트](/guides/integrations/ai-agents)