AI 内容创作 / 系统课时
数字人服务接口设计
数字人服务接口设计
本课把实时数字人的能力整理成一组稳定的会话接口,覆盖创建会话、提交文本、上传音频、查询状态、读取媒体流和结束会话。完成后,你将得到可运行的 FastAPI 示例,并能用统一状态与错误码约束客户端和服务端的协作。
学习目标
- 能够按会话资源划分数字人服务接口,并明确每个接口的输入、输出与幂等性要求。
- 能够使用状态机限制文本、音频、媒体流和结束会话等操作的合法时机。
- 能够运行并验证一个包含六类核心接口的最小服务。
会话资源与接口边界
数字人服务的中心资源应是会话,而不是一次文本请求。会话保存模型选择、角色配置、当前状态和流式输出上下文,客户端通过同一个 sessionId 连续提交文本或音频。这样可以让抢话、断线恢复、媒体订阅和资源释放都落在同一生命周期中。
| 方法与路径 | 作用 | 成功结果 | 幂等性建议 |
|---|---|---|---|
POST /sessions |
创建会话并分配资源 | 201 Created |
使用幂等键防止重复创建 |
POST /sessions/{id}/text |
提交一段待播报文本 | 202 Accepted |
使用业务请求 ID 去重 |
POST /sessions/{id}/audio |
上传用户音频 | 202 Accepted |
按音频片段 ID 去重 |
GET /sessions/{id} |
查询状态与配置 | 200 OK |
天然幂等 |
GET /sessions/{id}/stream |
读取事件快照 | 200 OK |
按已确认序号续读 |
DELETE /sessions/{id} |
结束会话并释放资源 | 204 No Content |
重复调用仍应安全 |
接口关系需要同时表达资源、状态与媒体流,使用结构图比逐条描述更容易建立整体认识。

状态、错误与流式约定
最小状态可以设为 READY、GENERATING 和 CLOSED。文本或音频只允许在 READY 时提交;服务接受任务后进入 GENERATING;本轮媒体生成完成后回到 READY;结束会话后进入 CLOSED,后续写操作应返回 409 Conflict。不存在的会话返回 404 Not Found,请求格式错误返回 422 Unprocessable Entity,资源暂不可用返回 503 Service Unavailable。
流式接口还需要携带递增的 sequence、事件类型和会话标识。客户端可提交最后确认的序号,服务端回放保留窗口内的事件。若序号已落在保留窗口之外,应告知客户端需要重建状态。生产环境若使用 WebSocket,还应在控制消息中保留 traceId、requestId 和心跳时间,以便定位一次请求跨越识别、合成与渲染链路时的延迟。
FastAPI 完整示例
将代码保存为 app/main.py。Python 3.11 环境安装 python -m pip install fastapi==0.162.0 uvicorn==0.54.0。它实现进程内状态和有限事件记录,只做协议演练。文本及音频都通过可信身份和同一个状态门禁;课堂另设一个完成按钮对应的模拟端点。生产完成消息只接受已授权的内部工作器。
import hashlib
import hmac
import io
import json
import os
import threading
import uuid
import wave
from dataclasses import dataclass, field
from fastapi import FastAPI, Header, HTTPException, Query, Request, Response
from fastapi.responses import JSONResponse, StreamingResponse
from pydantic import BaseModel, ConfigDict, Field
@dataclass
class Session:
id: str
owner: str
state: str = "READY"
active: str | None = None
events: list = field(default_factory=list)
accepted: dict = field(default_factory=dict)
class TextInput(BaseModel):
model_config = ConfigDict(extra="forbid")
text: str = Field(min_length=1, max_length=2000)
class Completion(BaseModel):
generation: str
def build_app(tokens):
app = FastAPI()
sessions, creations = {}, {}
lock = threading.RLock()
def owner(request):
kind, _, token = request.headers.get("authorization", "").partition(" ")
if kind.lower() == "bearer":
for actor, expected in tokens.items():
if len(expected) >= 16 and hmac.compare_digest(token.encode(), expected.encode()):
return actor
raise HTTPException(401, "authentication_required", headers={"WWW-Authenticate": "Bearer"})
def owned(sid, actor):
session = sessions.get(sid)
if session is None or session.owner != actor:
raise HTTPException(404, "session_unavailable")
return session
def add_event(session, name):
session.events.append({
"sessionId": session.id, "sequence": len(session.events) + 1,
"type": name, "generation": session.active,
})
def accept(sid, actor, key, kind, content):
fingerprint = (kind, hashlib.sha256(content).digest())
with lock:
session = owned(sid, actor)
if session.state == "CLOSED":
raise HTTPException(409, "session_closed")
old = session.accepted.get(key)
if old:
if old[0] != fingerprint:
raise HTTPException(409, "idempotency_conflict")
return old[1]
if session.state != "READY":
raise HTTPException(409, "session_busy")
if len(session.accepted) >= 64:
raise HTTPException(503, "demo_capacity")
session.active = uuid.uuid4().hex
session.state = "GENERATING"
add_event(session, "generation.accepted")
reply = {"generation": session.active, "accepted": True}
session.accepted[key] = (fingerprint, reply)
return reply
@app.get("/healthz")
def health():
return {"status": "alive"}
@app.post("/sessions", status_code=201)
def create(request: Request, idempotency_key: str = Header(min_length=1, max_length=80)):
actor = owner(request)
with lock:
key = (actor, idempotency_key)
if key not in creations:
if len(sessions) >= 32:
raise HTTPException(503, "demo_capacity")
sid = uuid.uuid4().hex
sessions[sid] = Session(sid, actor)
creations[key] = sid
sid = creations[key]
return JSONResponse({"id": sid}, status_code=201, headers={"Location": "/sessions/" + sid})
@app.post("/sessions/{sid}/text", status_code=202)
def submit_text(sid: str, data: TextInput, request: Request,
idempotency_key: str = Header(min_length=1, max_length=80)):
actor = owner(request)
if not data.text.strip():
raise HTTPException(422, "empty_text")
return accept(sid, actor, idempotency_key, "text", data.text.encode())
@app.post("/sessions/{sid}/audio", status_code=202)
async def submit_audio(sid: str, request: Request,
idempotency_key: str = Header(min_length=1, max_length=80)):
actor = owner(request)
with lock:
owned(sid, actor)
media = request.headers.get("content-type", "").split(";", 1)[0].strip().lower()
if media != "audio/wav":
raise HTTPException(415, "expected_audio_wav")
data = bytearray()
async for chunk in request.stream():
if len(data) + len(chunk) > 65536:
raise HTTPException(413, "audio_too_large")
data.extend(chunk)
try:
with wave.open(io.BytesIO(data), "rb") as file:
config = (file.getnchannels(), file.getsampwidth(), file.getframerate())
frames = file.getnframes()
if config != (1, 2, 16000) or not 0 < frames <= 32000:
raise ValueError
if len(file.readframes(frames)) != 2 * frames:
raise ValueError
except (wave.Error, EOFError, ValueError):
raise HTTPException(422, "invalid_pcm_wav") from None
return accept(sid, actor, idempotency_key, "audio", data)
@app.get("/sessions/{sid}")
def status(sid: str, request: Request):
with lock:
session = owned(sid, owner(request))
return {"id": sid, "state": session.state, "generation": session.active}
@app.get("/sessions/{sid}/stream")
def stream(sid: str, request: Request, after: int = Query(ge=0, default=0)):
with lock:
session = owned(sid, owner(request))
lines = tuple(json.dumps(event) + "\n" for event in session.events if event["sequence"] > after)
return StreamingResponse(iter(lines), media_type="application/x-ndjson")
@app.post("/sessions/{sid}/demo-complete", status_code=204)
def complete(sid: str, data: Completion, request: Request):
with lock:
session = owned(sid, owner(request))
if session.state != "GENERATING" or session.active != data.generation:
raise HTTPException(409, "stale_completion")
add_event(session, "generation.completed")
session.state, session.active = "READY", None
return Response(status_code=204)
@app.delete("/sessions/{sid}", status_code=204)
def close(sid: str, request: Request):
with lock:
session = owned(sid, owner(request))
if session.state != "CLOSED":
add_event(session, "session.closed")
session.state, session.active = "CLOSED", None
return Response(status_code=204)
return app
app = build_app({"local-demo": os.environ.get("DEMO_TOKEN", "")})在本机生成仅供演练的令牌并启动。以下是 Bash 命令。
export DEMO_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(24))')"
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 &
DEMO_PID=$!保持在同一终端,验证创建、提交、状态、事件和关闭。音频路径使用第 02 章生成的实际 16 kHz PCM WAV。
auth="Authorization: Bearer $DEMO_TOKEN"
base="http://127.0.0.1:8000"
sid=$(curl -fsS -X POST "$base/sessions" -H "$auth" -H 'Idempotency-Key: create-1' |
python -c 'import json,sys; print(json.load(sys.stdin)["id"])')
generation=$(curl -fsS -X POST "$base/sessions/$sid/text" -H "$auth" \
-H 'Idempotency-Key: text-1' -H 'Content-Type: application/json' \
-d '{"text":"欢迎使用数字人服务"}' | python -c 'import json,sys; print(json.load(sys.stdin)["generation"])')
curl -fsS "$base/sessions/$sid" -H "$auth"
curl -fsS -X POST "$base/sessions/$sid/demo-complete" -H "$auth" \
-H 'Content-Type: application/json' -d "{\"generation\":\"$generation\"}"
curl -fsS -X POST "$base/sessions/$sid/audio" -H "$auth" \
-H 'Idempotency-Key: audio-1' -H 'Content-Type: audio/wav' --data-binary @voice_input.wav
curl -fsS "$base/sessions/$sid/stream?after=1" -H "$auth"
curl -fsS -o /dev/null -w '%{http_code}\n' -X DELETE "$base/sessions/$sid" -H "$auth"
kill "$DEMO_PID"预期状态先为 GENERATING,文本完成后音频才可受理。续读只返回序号大于 1 的事件,关闭返回 204。相同幂等键和同一内容返回原受理回执;换内容返回 409。模拟端点只生成状态事件,不能据此判定真实音频或视频已生成。多实例部署须替换内存锁、身份映射和有限历史,并为结束状态设定保留与清理规则。
设计校验与常见错误
首先检查接口是否以会话为边界。若文本、音频和媒体流分别创建独立资源,客户端将很难判断它们是否属于同一轮交互。其次检查状态写入是否具有原子性,避免两个并发提交同时看到 READY 并重复占用模型。最后检查结束会话是否同时撤销订阅、取消任务并释放模型引用,而不只是删除一条数据库记录。
常见错误是把长任务做成同步 HTTP 请求,导致网关超时。正确做法是快速返回 202 Accepted,再通过状态查询或流式通道发送进度。另一个错误是直接把底层异常文本返回给客户端;服务应映射成稳定的业务错误码,并把完整堆栈写入带 traceId 的内部日志。
本课总结
- 数字人服务应围绕会话资源统一组织输入、状态、媒体流和资源释放。
- 状态机、幂等键、事件序号和稳定错误码共同决定接口能否在并发与重连场景下可靠工作。
- 最小可运行接口可以先用内存状态和模拟流验证契约,再替换为队列、模型服务与媒体网关。
下一课预告
下一课将学习“模型加载与资源管理”,把本课创建和结束会话的接口进一步连接到模型预加载、引用计数、显存回收与多模型切换机制。