如何用 LiveKit + Synthesia 數位人(版本 1)?
只能輸出文字或一個沒有臉的聲音的語音代理已經很有用——但如果代理有 一張臉,感覺就會像在跟真人說話。 Synthesia 能生成逼真的 AI 數位人,即時說話、即時對口型。 LiveKit 則把數位人和語音代理流水線綁在一起:麥克風 → 語音辨識 → LLM → 文字轉語音 → 數位人。
這篇筆記帶你跑通最小可執行演示:瀏覽器裡一個視訊框、一個按鈕,數位人 Lin 扮演一家 虛構餐廳的迎賓員,回答你什麼時候開門。這是版本 1——故意做得很精簡, 讓每一行程式碼都容易看懂。
整條流水線
瀏覽器麥克風 → VAD → STT → 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 和 pyproject.toml。
把你的 .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 跟你打招呼——點一下麥克風圖示試試問它一個問題,比如「你們幾點開門?」。
zip 裡的檔案
pyproject.toml
[project]
name = "folder-ai-avatar"
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 = ["uv_build>=0.12.11,<0.13.0"]
build-backend = "uv_build"
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"
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 short sentence and never use
markdown, lists, or URLs.
YouFantasy is open every day from 9am to 10pm.
That is the only thing you know. If the guest asks about anything else, say
kindly that for now you can only help with our opening hours."""
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)
await session.start(agent=Agent(instructions=INSTRUCTIONS), room=ctx.room)
session.generate_reply(
instructions="Welcome the guest to YouFantasy and invite them to ask about our opening hours, 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 是語音 + 數位人引擎——它加入 LiveKit 房間、監聽麥克風、負責回答、驅動數位人。
server.py 是一個小小的 aiohttp Web 伺服器,負責提供頁面,並在每次造訪時簽發一個短期有效的 LiveKit 存取權杖(這樣憑證就不會寫死在 HTML 裡)。
兩個要分開啟動,因為各自佔用不同連接埠。
瀏覽器完全不知道數位人這回事。
index.html 只是加入一個 LiveKit 房間、播放所有收到的視訊軌——
它不關心軌來自真實攝影機還是 Synthesia 數位人。數位人從 agent 內部把自己的視訊流傳出來,
房間設定裡 sync_streams=True 保證嘴型和音訊同步。
冷啟動自動重試。 Synthesia 服務偶爾會花幾秒鐘才能拉起一個數位人會話,所以 agent 會最多重試三次再放棄。 這就是為什麼第一次點 Start 會感覺慢——不是壞了,是在熱身。
版本 1 的限制
- Lin 只知道營業時間。
整個知識庫就是
INSTRUCTIONS裡的一段話。故意這樣設計——版本 1 先把管線搭起來, 後續版本再加工具、資料庫或 RAG。 - 需要三個帳號(LiveKit、Synthesia、Cartesia)。 LiveKit Cloud 覆蓋了 STT、LLM、TTS,但 Synthesia 是單獨付費的訂閱。本文編寫時 Synthesia 按數位人分鐘收費。
- 兩個終端機才能跑。 演示方便,但要上線的話應該用一個 supervisor 把兩者綁起來,或者直接在 LiveKit Cloud Agents 上執行。
- Web 伺服器沒有鑑權。
server.py給每個訪客直接生成一個房間權杖,沒做登入。本地測試沒問題,絕對不要原樣部署到公網。
延伸閱讀
- livekit.io —— LiveKit 官網,含定價和文件。
- livekit/agents —— LiveKit Agents Python 倉庫,有更多範例(包括 Synthesia)。
- LiveKit Synthesia Avatar 文件 —— 官方指南。
- synthesia.io —— 建立和管理你的數位人。
- 如何用 LiveKit 語音代理聊天? —— 同一個代理,沒有數位人版本。
- 如何用帶天氣工具的 LiveKit 語音代理? —— 示範怎麼給代理加一個能呼叫真實 API 的工具。