如何用 LiveKit + Synthesia 数字人(版本 2)?
Synthesia 能生成逼真的 AI 数字人,实时说话、实时对口型。 LiveKit 则把数字人和语音代理绑在一起:麦克风 → 语音识别 → LLM → 文字转语音 → 数字人。
版本 1 里数字人知道的所有东西都硬写在 Python prompt 里。这样代码好读,但每次想让 Lin 多知道一件事, 都得改 Python、再重启。
版本 2 把知识搬到一个纯文字档,叫做 FAQs.txt for frequently asked questions。
改完文件、打开一通新的通话,数字人就会学到新内容——不用改代码。Lin 现在能回答四个问题
(营业时间、主打菜、地址、回复其他问题的备案答案),不再只限一个。
整条流水线
浏览器麦克风 → VAD → STT → turn detection → LLM → TTS → Synthesia 数字人 → 浏览器视频
五块元件透过 LiveKit 的实时传输连在一起。 VAD(语音活动检测)负责监听你什么时候开口、什么时候停下, STT 把语音转文字,LLM 负责回答, TTS 把回答念出来,Synthesia 渲染出跟语音同步的脸。 全部跑在 LiveKit Cloud 上。
准备工作
- 一台 Mac(Windows 和 Linux 也能用,步骤一样)。
- 装好 Homebrew 和
uv包管理器——如果还没装uv,跑brew install uv。 - 一个 LiveKit Cloud 账号(免费的 Build 套餐就够)。
- 一个 Synthesia 账号。至少要在上面创建一个数字人(免费账号也能体验)。
- 把 LiveKit 和 Synthesia 的凭证复制到一个叫
.env的文件里——见下文。
设定 LiveKit Cloud
在 cloud.livekit.io 注册登录。进入控制台,点 Projects → Create Project, 打开项目后点 Keys,复制这三个值:
LIVEKIT_URL—— 格式像wss://your-project.livekit.cloud。LIVEKIT_API_KEY—— 短字符串,像APIxxxxxxxxxxxxx。LIVEKIT_API_SECRET—— 长字符串,只显示一次。
设定 Synthesia
登录 app.synthesia.io。
进入 Avatars,选一个或新建一个数字人——每个数字人都有一个 UUID,
打开它时 URL 里就能看到(像 3190429b-1eda-4151-bf24-96162e405840),
这就是 SYNTHESIA_AVATAR_ID。
然后到 API Keys
创建一把密钥——这就是 SYNTHESIA_API_KEY。
创建 .env
在你的项目文件夹里新建一个文件,命名为 .env,填入以下五行:
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=APIxxxxxxxxxxxxx
LIVEKIT_API_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SYNTHESIA_API_KEY=syn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SYNTHESIA_AVATAR_ID=3190429b-1eda-4151-bf24-96162e405840
注意:绝对不要把 .env 传到 GitHub 或任何公开网站——里面是你的真实凭证。
在自己电脑上执行
下载 zip 文件,
解压到一个文件夹里。zip 里包含 agent.py、server.py、
index.html、FAQs.txt、pyproject.toml 和 README.md。
把你的 .env 凭证文件放到同一文件夹(如上面所示)。然后在 Visual Studio Code 里打开这个文件夹,
在两个不同的终端窗口里分别执行:
终端 1 —— 语音代理 + 数字人引擎:
uv sync
uv run agent.py dev
终端 2 —— 浏览器页面的 Web 服务器:
uv run server.py
uv sync 只需要第一次跑——它会自动装 Python 3.13 和所有依赖包。之后每次只要开两个终端分别执行 agent.py 和 server.py 就行。
在浏览器里打开页面
两个终端都跑起来之后,在 Chrome、Safari 或 Edge 里打开 http://127.0.0.1:8080, 点 Start,允许麦克风权限,然后等个几秒让代理和数字人加入房间。 你应该能看到 Lin 跟你打招呼——点一下麦克风图标试试问它一个问题,比如「你们在哪里?」或「你们有什么主打菜?」。
不动 Python,直接编辑知识库
Lin 知道的所有东西都在 FAQs.txt,就在 agent.py 旁边:
Q: When is YouFantasy open?
A: YouFantasy is open every day from 9am to 10pm.
Q: What are the main courses?
A: Salmon, Beef, Chicken, Pork, Tofu.
Q: Where is YouFantasy?
A: YouFantasy is on Tat Chee Avenue, Kowloon Tong, Hong Kong.
Q: Any other question?
A: Sorry, I do not have answer for that question.
每当一通新的通话开始,agent.py 都会重新读取这个文件,把 prompt 里的
{faqs} 占位符换成最新内容,才启动 session。要给 Lin 加新知识,
只要加一组 Q&A、存档、再打开一通新的通话就行——不用改 Python。
zip 里的文件
pyproject.toml
[project]
name = "folder-ai-avatar-v2"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
"aiohttp>=3.14.4",
"livekit-agents[openai,silero]~=1.8",
"livekit-plugins-synthesia~=1.8",
"python-dotenv>=1.2.4",
]
[build-system]
requires = ["setuptools>=70"]
build-backend = "setuptools.build_meta"
[tool.setuptools.packages.find]
include = []
agent.py
import asyncio
import os
from pathlib import Path
from dotenv import load_dotenv
from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli, inference
from livekit.plugins import silero, synthesia
load_dotenv(dotenv_path=Path(__file__).parent / ".env")
AGENT_NAME = "avatar-demo"
AVATAR_ID = os.getenv("SYNTHESIA_AVATAR_ID") or "3190429b-1eda-4151-bf24-96162e405840"
VOICE_ID = "db6b0ed5-d5d3-463d-ae85-518a07d3c2b4"
FAQS_FILE = Path(__file__).parent / "FAQs.txt" # the avatar's knowledge
# {faqs} is replaced with the contents of FAQs.txt at the start of every call.
INSTRUCTIONS = """\
You are Lin, the host at YouFantasy, a made-up restaurant. You are a real-time
avatar in a spoken conversation, so answer in one to three short sentences and never use
markdown, lists, or URLs.
Answer only from these FAQs:
{faqs}
Those are the only things you know. If the guest asks anything the FAQs do not
cover, use the answer to "Any other question?" word for word."""
def prewarm(proc) -> None:
proc.userdata["vad"] = silero.VAD.load()
async def entrypoint(ctx: JobContext) -> None:
await ctx.connect()
session = AgentSession(
vad=ctx.proc.userdata["vad"],
stt=inference.STT(model="cartesia/ink-2"),
llm=inference.LLM(model="openai/gpt-4.1-mini"),
tts=inference.TTS(model="cartesia/sonic-3.6", voice=VOICE_ID),
turn_handling={"turn_detection": "stt"},
)
avatar = synthesia.AvatarSession(
synthesia.AvatarConfig(avatar_ids=[AVATAR_ID]),
join_timeout=60.0,
)
for attempt in range(3):
try:
await avatar.start(session, room=ctx.room)
break
except synthesia.SynthesiaError as e:
if not e.retryable or attempt == 2:
raise
await asyncio.sleep(2)
# Read FAQs fresh each call so edits to FAQs.txt show up on the next call.
faqs = FAQS_FILE.read_text(encoding="utf-8").strip()
await session.start(
agent=Agent(instructions=INSTRUCTIONS.replace("{faqs}", faqs)),
room=ctx.room,
)
session.generate_reply(
instructions="Welcome the guest to YouFantasy and invite them to ask a question, in one short sentence."
)
if __name__ == "__main__":
cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint, prewarm_fnc=prewarm, agent_name=AGENT_NAME, port=8081))
server.py
import os
import uuid
from datetime import timedelta
from pathlib import Path
from aiohttp import web
from dotenv import load_dotenv
from livekit import api
load_dotenv(dotenv_path=Path(__file__).parent / ".env")
AGENT_NAME = "avatar-demo"
async def token(request: web.Request) -> web.Response:
room = f"avatar-demo-{uuid.uuid4().hex[:8]}"
jwt = (
api.AccessToken()
.with_identity(f"user-{uuid.uuid4().hex[:8]}")
.with_ttl(timedelta(minutes=15))
.with_grants(api.VideoGrants(room_join=True, room=room))
.with_room_config(
api.RoomConfiguration(
sync_streams=True,
agents=[api.RoomAgentDispatch(agent_name=AGENT_NAME)],
)
)
.to_jwt()
)
return web.json_response({"url": os.environ["LIVEKIT_URL"], "token": jwt})
async def index(request: web.Request) -> web.FileResponse:
return web.FileResponse(
Path(__file__).parent / "index.html", headers={"Cache-Control": "no-store"}
)
app = web.Application()
app.router.add_get("/", index)
app.router.add_get("/token", token)
if __name__ == "__main__":
web.run_app(app, host="127.0.0.1", port=8080)
index.html
<!doctype html>
<html lang="en">
... (same as in English version above)
工作原理,大白话解释
两个程序,两个终端,一个文字档。
agent.py 是语音 + 数字人引擎。
server.py 是一个小小的 aiohttp Web 服务器,负责提供页面,并在每次造访时签发一个短期有效的 LiveKit 存取令牌。
FAQs.txt 是知识库——agent 每次都会重新读取它,把内容塞进 prompt 里的 {faqs}。
为什么用文字档? 不会写代码的人也能维护它。餐厅经理、写专题的学生、做教学 demo 的老师——都不用打开 Python 就能加一件事。规则只有一条:每组问答以 Q: 和 A: 各起一行,两组之间空一行。
浏览器完全不知道数字人这回事。
index.html 只是加入一个 LiveKit 房间、播放所有收到的视频轨——
它不关心轨来自真实摄像机还是 Synthesia 数字人。数字人从 agent 内部把自己的视频流传出来,
房间设定里 sync_streams=True 保证嘴型和音讯同步。
冷启动自动重试。 Synthesia 服务偶尔会花几秒钟才能拉起一个数字人会话,所以 agent 会最多重试三次再放弃。 这就是为什么第一次点 Start 会感觉慢——不是坏了,是在热身。
版本 1 vs. 版本 2 一眼看懂
| 版本 1 | 版本 2 | |
|---|---|---|
| 知识库在哪里 | Python prompt(INSTRUCTIONS) |
文字档(FAQs.txt) |
| 更新知识需要 | 改 Python + 重启 | 存档 + 打新的一通 |
| 问题数量 | 1(营业时间) | 4(时间、菜、地址、备案答案) |
| 执行指令 | 两个终端,一样 | 两个终端,一样 |
版本 2 的限制
- Lin 还是只会
FAQs.txt里的东西。 纯文字档很方便快速更新,但它不能算数、也不能查即时资讯。若要让它会查天气、股价或预约,下一步要加工具或 RAG。 - 需要两个账号(LiveKit 和 Synthesia)。 LiveKit Cloud 的 Inference 服务已经包含 STT、LLM、TTS(包括 Cartesia 和 Deepgram 的语音模型), 不用另外申请这些提供者的账号。Synthesia 目前有免费 Basic 套餐(本文编写时是 2026 年 11 月), 内含 Interactive Avatar 1 个并发 session;付费套餐提高数量并增加 credits。
- 两个终端才能跑。 演示方便,但要上线的话应该用一个 supervisor 把两者绑起来,或者直接在 LiveKit Cloud Agents 上执行。
- Web 服务器没有鉴权。
server.py给每个访客直接生成一个房间令牌,没做登录。本地测试没问题,绝对不要原样部署到公网。
延伸阅读
- livekit.io —— LiveKit 官网,含定价和文档。
- livekit/agents —— LiveKit Agents Python 仓库,有更多范例(包括 Synthesia)。
- LiveKit Synthesia Avatar 文档 —— 官方指南。
- synthesia.io —— 创建和管理你的数字人。
- 如何用 LiveKit + Synthesia 数字人(版本 1)? —— 同一个数字人的精简版,知识库硬编码在 Python 里。
- 如何用 LiveKit 语音代理聊天? —— 没有数字人脸的语音代理版本。
- 如何用带天气工具的 LiveKit 语音代理? —— 示范怎么给代理加一个能调用真实 API 的工具。