495
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。

局限

延伸阅读