跳至主要内容

语音 AI 快速入门

在不到 10 分钟的时间内构建并部署一个简单的语音助手。

概述

本指南将引导您设置您的第一个使用 LiveKit Agents for Python 的语音助手。在 10 分钟之内,您将拥有一个可以通过终端、浏览器、电话或原生应用程序与之交谈的语音助手。

LiveKit Agent Builder

LiveKit Agent Builder 是一种在浏览器中快速入门语音代理的方式,无需编写任何代码。它非常适合原型设计和探索想法,但功能不如完整的 LiveKit Agents SDK 那么多。请参阅 Agent Builder 指南了解更多详情。

入门项目

使用以下入门项目之一是启动您的第一个代理的最简单方法。单击“Use this template”(使用此模板)在右上角创建一个新的 GitHub 仓库,然后按照项目 README 中的说明进行操作。

这些项目采用最佳实践构建,包含一个完整的可用代理、测试以及一个优化的 AGENTS.md 文件,旨在将您的编码助手变成 LiveKit 专家。

要求

以下部分描述了开始使用 LiveKit Agents 的最低要求。

  • LiveKit Agents 需要 Python >= 3.10,< 3.14。
  • 本指南使用 uv 包管理器。
  • LiveKit Agents for Node.js 需要 Node.js >= 20。
  • 本指南使用 pnpmGitHub - LiveKit 文档 包管理器,并且需要 pnpm >= 10.15.0。

LiveKit Cloud

本指南假定您已注册免费的 LiveKit Cloud 帐户。LiveKit Cloud 包括代理部署、模型推理和实时媒体传输。创建一个免费项目,并在以下步骤中使用 API 密钥开始使用。

虽然本指南假定使用 LiveKit Cloud,但您可以将说明调整为 自托管 开源 LiveKit 服务器。对于生产环境中的自托管,请设置一个 自定义部署 环境,并进行以下更改:从代理代码中删除 增强型噪声消除 插件,并使用 插件 用于您自己的人工智能提供商。

LiveKit Docs MCP 服务器

如果您正在使用 AI 编码助手,您应该安装 LiveKit Docs MCP 服务器 以充分利用它。这可确保您的代理可以访问最新的文档和示例。《入门项目》还包含一个 AGENTS.md 文件,其中包含有关使用 MCP 服务器以及使用 LiveKit 构建代理的其他重要信息。

LiveKit CLI

使用 LiveKit CLI 管理 LiveKit API 密钥并将您的代理部署到 LiveKit Cloud。

  1. 安装 LiveKit CLI

    使用 Homebrew 安装 LiveKit CLI

    brew install livekit-cli
    curl -sSL https://get.livekit.io/cli | bash
    提示

    您还可以在此处 下载最新的预编译二进制文件。

    winget install LiveKit.LiveKitCLI
    提示

    您还可以在此处 下载最新的预编译二进制文件。

    此仓库使用 Git LFS 用于嵌入式视频资源。请确保您的机器上已安装 git-lfs,然后再继续。

    git clone github.com/livekit/livekit-cli
    make install
  2. 将您的 LiveKit Cloud 项目链接到 CLI

    lk cloud auth

    这将打开一个浏览器窗口以进行身份验证并将您的项目链接到 CLI。

AI 模型

语音代理需要一个或多个 AI 模型,以提供理解、智能和语音。LiveKit Agents 支持由多个专用模型构建的高性能 STT-LLM-TTS 语音管道,以及具有直接语音到语音功能的实时模型。

本指南的其余部分假定您使用以下两个入门包之一,它们提供了最佳的价值、功能和易用性。

您的代理将三个专用提供商串联在一起,构建了一个由 LiveKit Inference 提供支持的高性能语音管道。无需额外设置。

Diagram showing STT-LLM-TTS pipeline.
Component模型替代方案
STTAssemblyAI Universal-StreamingSTT 模型
LLMOpenAI GPT-4.1 miniLLM 模型
TTSCartesia Sonic-3TTS 模型

您的代理使用单个实时模型来提供富有表现力和逼真的语音体验。

Diagram showing realtime model.
模型所需密钥替代方案
OpenAI Realtime APIOPENAI_API_KEY实时模型

设置

使用以下部分中的说明设置您的新项目。

项目初始化

为语音代理创建一个新项目。

运行以下命令以使用 uv 创建一个准备好用于您的新语音代理的新项目。

uv init livekit-voice-agent --bare
cd livekit-voice-agent

运行以下命令以使用 pnpm 创建一个基于 TypeScript 的新项目,该项目准备好用于您的新语音代理。

mkdir livekit-voice-agent
cd livekit-voice-agent
pnpm init --init-type module
pnpm add -D typescript tsx
pnpm exec tsc --init

安装包

安装以下包以使用您的 STT-LLM-TTS 管道、噪声消除和 轮次检测 构建一个完整的语音 AI 代理。

uv add \
"livekit-agents[silero,turn-detector]~=1.3" \
"livekit-plugins-noise-cancellation~=0.2" \
"python-dotenv"

安装以下包以使用您的实时模型和噪声消除功能构建一个完整的语音 AI 代理。

uv add \
"livekit-agents[openai]~=1.3" \
"livekit-plugins-noise-cancellation~=0.2" \
"python-dotenv"

环境变量

运行以下命令将您的 LiveKit Cloud API 密钥加载到 .env.local 文件中

lk app env -w

文件应如下所示

LIVEKIT_API_KEY=<your API Key>
LIVEKIT_API_SECRET=<your API Secret>
LIVEKIT_URL=<your LiveKit server URL>

您还必须设置 OPENAI_API_KEY 环境变量,使用您自己的 OpenAI 平台帐户

LIVEKIT_API_KEY=<your API Key>
LIVEKIT_API_SECRET=<your API Secret>
LIVEKIT_URL=<your LiveKit server URL>
OPENAI_API_KEY=<Your OpenAI API Key>

代理代码

创建一个包含您的代理代码的文件。

from dotenv import load_dotenv
from livekit import agents, rtc
from livekit.agents import AgentServer,AgentSession, Agent, room_io
from livekit.plugins import noise_cancellation, silero
from livekit.plugins.turn_detector.multilingual import MultilingualModel
load_dotenv(".env.local")
class Assistant(Agent):
def __init__(self) -> None:
super().__init__(
instructions="""You are a helpful voice AI assistant.
You eagerly assist users with their questions by providing information from your extensive knowledge.
Your responses are concise, to the point, and without any complex formatting or punctuation including emojis, asterisks, or other symbols.
You are curious, friendly, and have a sense of humor.""",
)
server = AgentServer()
@server.rtc_session()
async def my_agent(ctx: agents.JobContext):
session = AgentSession(
stt="assemblyai/universal-streaming:en",
llm="openai/gpt-4.1-mini",
tts="cartesia/sonic-3:9626c31c-bec5-4cca-baa8-f8ba9e84c8bc",
vad=silero.VAD.load(),
turn_detection=MultilingualModel(),
)
await session.start(
room=ctx.room,
agent=Assistant(),
room_options=room_io.RoomOptions(
audio_input=room_io.AudioInputOptions(
noise_cancellation=lambda params: noise_cancellation.BVCTelephony() if params.participant.kind == rtc.ParticipantKind.PARTICIPANT_KIND_SIP else noise_cancellation.BVC(),
),
),
)
await session.generate_reply(
instructions="Greet the user and offer your assistance."
)
if __name__ == "__main__":
agents.cli.run_app(server)
from dotenv import load_dotenv
from livekit import agents, rtc
from livekit.agents import AgentServer, AgentSession, Agent, room_io
from livekit.plugins import (
openai,
noise_cancellation,
)
load_dotenv(".env.local")
class Assistant(Agent):
def __init__(self) -> None:
super().__init__(instructions="You are a helpful voice AI assistant.")
server = AgentServer()
@server.rtc_session()
async def my_agent(ctx: agents.JobContext):
session = AgentSession(
llm=openai.realtime.RealtimeModel(
voice="coral"
)
)
await session.start(
room=ctx.room,
agent=Assistant(),
room_options=room_io.RoomOptions(
audio_input=room_io.AudioInputOptions(
noise_cancellation=lambda params: noise_cancellation.BVCTelephony() if params.participant.kind == rtc.ParticipantKind.PARTICIPANT_KIND_SIP else noise_cancellation.BVC(),
),
),
)
await session.generate_reply(
instructions="Greet the user and offer your assistance. You should start by speaking in English."
)
if __name__ == "__main__":
agents.cli.run_app(server)

下载模型文件

要使用 turn-detectorsileronoise-cancellation 插件,您首先需要下载模型文件

uv run agent.py download-files
  1. download-files 脚本添加到您的 package.json 文件中

    pnpm pkg set "scripts.download-files=tsc && node agent.js download-files"
  2. 添加 download-files 脚本后,运行以下命令

    pnpm download-files

与播放场连接

仅限 Python

如果您使用的是 Node.js,您可以跳过此设置并继续连接到播放场

console 模式下启动您的代理,以便在您的终端内运行

uv run agent.py console

您的代理通过终端与您交谈,您也可以与它交谈。

Screenshot of the CLI console mode.

连接到播放场

dev 模式下启动您的代理,以将其连接到 LiveKit 并使其可从互联网上的任何地方访问

uv run agent.py dev
  1. dev 脚本添加到您的 package.json 文件中

    pnpm pkg set "scripts.dev=tsx agent.ts dev"
  2. 在添加开发脚本后,每当你想要在开发模式下运行你的代理时,运行以下命令

    pnpm dev

使用代理游乐场与你的代理对话并探索其全部的多模态功能。

代理 CLI 模式

devstart 模式下,你的代理连接到 LiveKit Cloud 并加入房间

  • dev 模式:在开发模式下运行你的代理,用于测试和调试。

  • start 模式:在生产模式下运行你的代理。

对于 Python 代理,运行以下命令以在生产模式下启动你的代理

uv run agent.py start

对于 Node.js 代理,你需要将 buildstart 脚本添加到你的 package.json 文件中使用生产模式。

pnpm pkg set "scripts.build=tsc"
pnpm pkg set "scripts.start=node agent.js start"

现在运行以下命令来构建和启动你的生产代理

pnpm build
pnpm start

Python 代理也可以使用 console 模式,该模式在本地运行,并且仅在你的终端内可用。

部署到 LiveKit Cloud

从你的项目的根目录运行以下命令,并使用 LiveKit CLI。确保你已经 关联了你的 LiveKit Cloud 项目并添加了 构建和启动脚本

lk agent create

CLI 会在你的当前目录中创建 Dockerfile.dockerignorelivekit.toml 文件,然后使用你的 LiveKit Cloud 项目注册你的代理并部署它。

部署完成后,你可以在游乐场中访问你的代理,或者继续使用 console 模式,在你本地构建和测试你的代理时。

下一步

遵循这些指南,让你的语音 AI 应用在现实世界中发挥作用。