495
English 繁體中文 简体中文

如何用 LiveKit + Synthesia 数字人(版本 2)?

林邦源博士 · AI 笔记 · 2026 年 11 月 6 日 · 约 7 分钟阅读

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

准备工作

设定 LiveKit Cloud

在 cloud.livekit.io 注册登录。进入控制台,点 Projects → Create Project, 打开项目后点 Keys,复制这三个值:

设定 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 的限制

延伸阅读