搭建一个语音智能体

序章：为什么要做这个实验？

        想象一下，你刚上大一，加入了一个创客社团。社长说：“我们能不能做一个能语音聊天、还能自己托管服务器的 AI 助手？不花钱买云服务那种。”

        你一愣：这听起来像毕业设计啊？！

        别慌。今天，我会带你用 Docker Compose​ 把整个系统“拼”出来。就像搭乐高：每个零件都有说明书，你只需要按顺序拼。最后你会得到一个能在浏览器里说话、智能体 会回答你的完整系统。

第一章：认识你的“乐高零件”

        我们这套系统有四个角色，我把它们拟人化：

关键理解：

• 浏览器（Playground）不直接连 Agent，而是连 LiveKit Server。

• Agent 是“被派活”的：你进房间，LiveKit 就通知 Agent 进来服务。

• 所有零件都跑在你电脑上（或你实验室的服务器上），数据不出内网。

第二章：准备工作

2.1 你需要安装的软件

        打开你的终端（Mac 用 Terminal，Windows 用 PowerShell 或 WSL），确认以下命令能跑：

docker –version
docker compose version
git –version

如果没装，去官网下载：

• Docker Desktop：Docker Desktop: The #1 Containerization Tool for Developers | Docker
• Git：Git

2.2 创建你的实验文件夹

mkdir -p ~/livekit-lab/agent/src
mkdir -p ~/livekit-lab/agent/playground
cd ~/livekit-lab

现在你的目录长这样：

livekit-lab/
├── agent/
│ └── src/
└── playground/

第三章：生成“钥匙”和“密码本”

        LiveKit 需要一对 API Key 和 Secret，就像宿舍楼的门禁卡。

        运行这个命令（如果你装了 livekit-server 的二进制；没装也没关系，我们直接用 Docker 生成）：

docker run –rm docker.1ms.run/livekit/livekit-server:latest generate-keys

        你会看到类似输出：

API Key: APIxxxxxx
API Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

        把它们记在记事本里，后面要用。

        为了方便，我们先用默认的 devkey 和 secretsecretsecretsecretsecretsecret@2026（仅限内网测试，别外网暴露）。

第四章：写配置文件（像填表格）

4.1 宿舍楼配置：livekit.yaml

        在livekit-lab/下新建livekit.yaml：

port: 7880
bind_addresses:
– "0.0.0.0"

rtc:
tcp_port: 7881
port_range_start: 50000
port_range_end: 60000
use_external_ip: false # 本机测试用 false；云服务器改 true

keys:
devkey: secretsecretsecretsecretsecretsecret@2026

logging:
level: info

4.2 环境变量：.env

        在livekit-lab下新建 .env（这个文件不要提交到 GitHub）：

LIVEKIT_API_KEY=devkey
LIVEKIT_API_SECRET=secretsecretsecretsecretsecretsecret@2026

# 浏览器访问的地址（本机用 ws://，公网用 wss://）
NEXT_PUBLIC_LIVEKIT_URL=ws://localhost:7880

# 下面三个填你自己的，没有就先放空，后面会报错提示
DEEPGRAM_API_KEY=xxx
OPENAI_API_KEY=xxx
CARTESIA_API_KEY=xxx

提醒：

• DEEPGRAM 是语音转文字，OPENAI 是大脑，CARTESIA 是文字转语音。
• 你可以先用免费额度注册

第五章：编写智能体代码

5.1 agent/requirements.txt

        告诉Python需要哪些库：

python-dotenv
livekit-agents
livekit
livekit-api
livekit-plugins-deepgram
livekit-plugins-openai
livekit-plugins-cartesia
livekit-plugins-silero
livekit-plugins-turn-detector

5.2 agent/src/agent.py

        这是智能体的大脑。我们一步一步写，每行我都加了注释：

import os
from dotenv import load_dotenv
from livekit import agents
from livekit.agents import Agent, AgentSession, RoomInputOptions
from livekit.plugins import deepgram, openai, cartesia, silero
from livekit.plugins.turn_detection.multilingual import MultilingualModel

# 加载 .env 文件里的秘密
load_dotenv()

# 定义你的智能体的性格
class VoiceAgent(Agent):
def __init__(self):
super().__init__(
instructions="你是一个中文语音助手，用自然口语回答，不要念标点符号。"
)

# 这是 agent 被派到房间时的入口函数
async def entrypoint(ctx: agents.JobContext):
# 连接到 LiveKit 房间
await ctx.connect()

# 创建会话，组装各个部件
session = AgentSession(
stt=deepgram.STT(model="nova-3", language="zh-CN"), # 耳朵：中文语音识别
llm=openai.LLM(model="gpt-4o-mini"), # 大脑：大模型
tts=cartesia.TTS(model="sonic-3"), # 嘴巴：语音合成
vad=silero.VAD.load(), # 噪声检测：判断你什么时候说完
turn_detection=MultilingualModel(), # 轮次检测：防止抢话
)

# 启动会话，把房间和 agent 绑定
await session.start(
room=ctx.room,
agent=VoiceAgent(),
)

# 让智能体先打招呼
await session.generate_reply(
instructions="用一句话打招呼，告诉用户你已启动。"
)

if __name__ == "__main__":
# 启动 worker，连接到 LiveKit Server
agents.cli.run_app(
agents.WorkerOptions(
entrypoint_fnc=entrypoint,
ws_url=os.getenv("LIVEKIT_URL", "ws://localhost:7880"),
api_key=os.getenv("LIVEKIT_API_KEY"),
api_secret=os.getenv("LIVEKIT_API_SECRET"),
)
)

知识点：

• stt (Speech-to-Text)：把你的声音变成文字。
• llm (Large Language Model)：理解文字并生成回答。
• tts (Text-to-Speech)：把回答念出来。
• vad (Voice Activity Detection)：判断你什么时候开始说话、什么时候停。
• urn_detection：防止 AI 在你还没说完就抢答。

5.3 agent/Dockerfile

        把Python代码打包成容器：

FROM python:3.11-slim
WORKDIR /app

COPY requirements.txt .
RUN pip install –no-cache-dir -r requirements.txt

COPY src ./src
RUN python src/agent.py download-files || true

CMD ["python", "src/agent.py", "start"]

六章：搭建浏览器对讲机

6.1 playground/Dockerfile

        官方Playground是 Next.js写的，我们直接用它的源码：

FROM node:20-alpine
WORKDIR /app

RUN apk add –no-cache git
RUN git clone –depth 1 https://github.com/livekit/agents-playground.git .

RUN npm install

EXPOSE 3000

CMD ["npm", "run", "dev", "–", "–hostname", "0.0.0.0", "–port", "3000"]

注意：这个Dockerfile会在每次构建时从GitHub拉代码。如果你网络不好，可以提前clone到本地再COPY：

FROM node:20-alpine
WORKDIR /app

# 将本地已 clone 的 agents-playground 代码复制到镜像中
COPY . .

RUN npm install

EXPOSE 3000

CMD ["npm", "run", "dev", "–", "–hostname", "0.0.0.0", "–port", "3000"]

第七章：总装

        在livekit-lab/下新建docker-compose.yml，这是整个实验的“总接线图”：

services:
redis:
image: redis:7-alpine
restart: unless-stopped
volumes:
– redis_data:/data

livekit:
image: livekit/livekit-server:latest
restart: unless-stopped
command: ["–config", "/etc/livekit.yaml"]
env_file:
– .env
volumes:
– ./livekit.yaml:/etc/livekit.yaml:ro
ports:
– "7880:7880"
– "7881:7881"
– "50000-60000:50000-60000/udp"
depends_on:
– redis

agent:
build: ./agent
restart: unless-stopped
env_file:
– .env
environment:
LIVEKIT_URL: ws://livekit:7880
depends_on:
– livekit

playground:
build: ./playground
restart: unless-stopped
env_file:
– .env
environment:
LIVEKIT_API_KEY: ${LIVEKIT_API_KEY}
LIVEKIT_API_SECRET: ${LIVEKIT_API_SECRET}
NEXT_PUBLIC_LIVEKIT_URL: ${NEXT_PUBLIC_LIVEKIT_URL}
ports:
– "3000:3000"
depends_on:
– livekit

volumes:
redis_data:

讲解：

• depends_on 表示依赖关系：Agent 必须等 LiveKit 起来才能连。
• env_file 让所有容器共享同一份密码本。
• ports 把容器里的端口映射到你的电脑上，这样浏览器才能访问。

第八章：启动实验（激动人心的时刻）

        在livekit-lab/目录下运行：

docker compose up -d –build

        当你看到类似 registering worker … 的字样，说明 语音智能体已经上线了！

第九章：对话吧！

    如果没声音，检查：

• 麦克风权限是否允许
• 终端里 agent 日志有没有报错
• .env 里的API Key是否填对

第十章：常见故障与调试

10.1 浏览器连不上

• 确认NEXT_PUBLIC_LIVEKIT_URL是ws://localhost:7880（不是 wss）
• 确认LiveKit容器在运行：docker ps

10.2 有文字没声音

• 检查CARTESIA_API_KEY是否有效
• 查看agent日志：docker compose logs agent

10.3 端口冲突

• 如果7880被占用，改livekit.yaml里的port和 docker-compose.yml里的映射

10.4 想重置一切

docker compose down -v
docker compose up -d –build

附：完整文件树

livekit-lab/
├── .env
├── docker-compose.yml
├── livekit.yaml
├── agent/
│ ├── Dockerfile
│ ├── requirements.txt
│ └── src/
│ └── agent.py
└── playground/
└── Dockerfile