English 繁體中文 简体中文

如何用 LiveKit 語音代理聊天?

林邦源 · AI 筆記 · 2026年11月4日 · 閱讀時間約 5 分鐘

語音代理(Voice Agent)是一種你可以即時對話的 AI 程式:你說話,它先辨識你的語音轉成文字(STT,speech-to-text),再把文字交給大型語言模型(LLM),最後把答案轉回語音播放給你聽(TTS,text-to-speech)。LiveKit 是一個開源框架,把這三個部件透過網際網路串在一起,所以你的代理可以跑在伺服器上,接受來自瀏覽器或電話的通話。

本筆記带你跑起一個精簡但完整的語音代理 Python 程式。代理會先問候你、用 LLM 的知識回答任何問題,不需要自訂工具。

觀看示範

在 Google Drive 觀看 (無需帳戶)。

你需要準備什麼

設定 LiveKit Cloud

到 cloud.livekit.io 註冊帳號。在控制台點 Projects → Create Project,打開專案後到 Keys 頁面,複製三個值:

在你的專案資料夾裡建立一個名為 .env 的檔案,內容如下:

LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=APIxxxxxxxxxxxxx
LIVEKIT_API_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

注意:千萬不要把 .env 放上 GitHub 或任何公開網站——裡面有真實憑證。

在自己電腦上執行

下載 zip 檔案,解壓縮到一個資料夾裡。zip 裡包含程式和 pyproject.toml 專案設定檔。把你的 .env 憑證檔案放到同一資料夾(如上面「設定 LiveKit Cloud」步驟所示)。然後在 Visual Studio Code 裡打開這個資料夾,在終端機逐條輸入以下兩行:

uv sync
uv run main.py console

uv sync 讀取 pyproject.toml,如果你的電腦還沒有 Python 3.13,它會自動下載安裝,然後裝好所有相依套件。uv run main.py console 會在終端機啟動代理,讓你直接說話、並聽到代理的回答。你只需要跑一次 uv sync——只有在修改了 main.py 或相依套件之後才需要重新跑。

程式檔案

zip 裡包含兩個檔案:pyproject.toml 和 main.py。下面是它們的完整內容供參考。

pyproject.toml

[project]
name = "folder-ai-livekit-agent"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
    "livekit-agents>=1.8.4,<2",
    "python-dotenv",
]

[build-system]
requires = ["uv_build>=0.13.6,<0.14.0"]
build-backend = "uv_build"

main.py

from dotenv import load_dotenv
from livekit.agents import (
    Agent,
    AgentServer,
    AgentSession,
    JobContext,
    cli,
    inference,
)

load_dotenv()


server = AgentServer()


@server.rtc_session()
async def entrypoint(ctx: JobContext):
    session = AgentSession(
        vad=inference.VAD(),
        stt=inference.STT("deepgram/nova-3", language="multi"),
        llm=inference.LLM("google/gemma-4-31b-it"),
        tts=inference.TTS("cartesia/sonic-3", voice="9626c31c-bec5-4cca-baa8-f8ba9e84c8bc"),
    )

    agent = Agent(
        instructions=(
            "You are a helpful and friendly voice assistant built by LiveKit. "
            "Use your knowledge to answer any question the user asks, clearly "
            "and concisely. Engage naturally in conversation."
        ),
    )

    await session.start(agent=agent, room=ctx.room)
    await session.generate_reply(instructions="greet the user and ask what they'd like to talk about")


if __name__ == "__main__":
    cli.run_app(server)

main.py 的運作原理(白話版本)

STT、LLM、TTS。AgentSession 那行把四個部件串起來:vad=inference.VAD() 是語音活動偵測——監聽麥克風,只在你說話時把語音交給 LLM,避免把背景雜訊也送去處理。Deepgram(deepgram/nova-3)把語音轉文字,Google Gemma 4(google/gemma-4-31b-it)回答問題,Cartesia(cartesia/sonic-3)把答案唸出來。四者都跑在 LiveKit Cloud 上,所以你不用分別向三家模型商申請 key——一個 LiveKit 帳號就搞定。

不需要工具。本代理直接用 LLM 內建的知識回答問題,不像帶天氣工具的版本那樣需要呼叫外部 API。這意味著零安裝依賴、零額外憑證;但也意味著代理無法存取即時資料或私人資料。

主動問候。會話開始後,generate_reply(instructions="greet the user and ask what they'd like to talk about") 會讓代理先說一句話,所以打電話進來的人聽到的是問候,而不是靜默。

跟你的代理對話

讓 uv run main.py console 在終端機執行中,程式會請求 Mac 的麥克風權限——按 Allow。然後對著麥克風說話:你應該會聽到代理回你問候,接著就可以自由對話。想停止時按 Ctrl+C。

如果終端機一直沒反應,或顯示缺少憑證的錯誤訊息,按 Ctrl+C 停止,檢查 .env 是否在專案資料夾,再執行一次 uv run main.py console。

局限

延伸閱讀