后端运行时
本目录提供 FastAPI 接入层、助手与模型资源管理，以及以 Pipecat 为核心的实时会话运行时。项目定位和完整能力状态见仓库 README与用户文档。当前依赖版本以 requirements.txt 为准。
请求如何进入运行时
业务客户端 ── /v1/realtime WebSocket 或 /v1/realtime/calls WebRTC ──┐
管理界面 ── /api/webrtc/offer、/ws/voice 或 /ws/stream ──────────┤
▼
协议适配 / Pipecat transport
▼
助手配置 + Pipeline 或 Realtime 模型
- Pipeline：ASR → LLM／外部 Agent → TTS；Pipecat 负责媒体帧、用户轮次、打断和服务编排。Pipeline 的 VAD 使用 Silero，轮次结束可选静音等待或 Local Smart Turn。
- Realtime：端到端语音模型负责识别、生成和合成。当前
create_realtime_service()只接通stepfun-realtime与qwen-audio-realtime。轮次控制主要来自 Provider 配置。 - 公开接口：
/v1/realtime、/v1/realtime/calls、/v1/realtime/client_secrets、/v1/responses和/v1/models。字段、事件和传输限制以兼容矩阵为准。 - 既有通道：
/api/webrtc/offer、/ws/voice、/ws/stream仍供管理界面和已有集成使用；它们使用管理员鉴权，不采用公开 Realtime JSON 事件协议。
模型资源与能力边界
interface_definitions 定义协议类型和表单字段，model_resources 保存每个资源的连接参数与凭证，assistant_model_bindings 决定助手使用哪些资源。运行时按 interface_type 创建服务，不根据 URL 或模型名自动推断协议。
| 类型 | 当前运行状态 |
|---|---|
openai-llm、openai-asr、openai-tts 及已接通的讯飞接口 |
Pipeline 可用；具体 Provider 仍需联调。 |
stepfun-realtime、qwen-audio-realtime |
Realtime 可用；具体功能按 Provider 能力限制。 |
openai-realtime、gemini-realtime |
未接通运行时。接口定义和种子资源仍在目录中，不能据此宣称模型可用。 |
| 任意独立 VAD／EOU 模型 | 未实现。目前是内置 Pipeline 策略或 Realtime Provider 自身的设置。 |
后两项是建议收敛的占位内容：在适配完成前，宜隐藏或标记不可用；移除已有资源定义前需考虑数据库记录。
主要目录
| 路径 | 用途 |
|---|---|
routes/openai_realtime.py、routes/openai_responses.py |
公开 Realtime 与 Responses 入口。 |
routes/voice_webrtc.py、routes/voice_ws.py |
管理界面和旧通道入口。 |
services/pipecat/pipeline.py |
Pipecat 会话编排。 |
services/pipecat/service_factory.py、services/pipecat/turn_config.py |
模型服务与 Pipeline 轮次策略。 |
services/interface_catalog.py |
接口定义目录。 |
db/models.py、migrations/ |
SQLAlchemy 数据模型与 Alembic 迁移。 |
contracts/ |
OpenAPI 与 Realtime 事件契约快照。 |
本地运行与验证
在仓库根目录启动 Docker 开发环境：
docker compose up -d
API 容器启动时会执行 Alembic 迁移并同步接口定义。本机单独运行后端时，可用 make db-init 完成这两步；它需要本机安装 uv。需要演示助手和模型资源时，另运行 make db-seed；种子密钥是占位值，不能直接用于真实模型调用。make db-seed 还会更新示例助手的模型绑定，不要在已有生产配置上当作常规升级命令运行。
后端地址是 http://localhost:8000，交互式 HTTP API 文档是 /docs。本地开发也可在 backend/ 目录使用 uv run --with-requirements requirements.txt uvicorn app:app --reload --port 8000，需先准备数据库和环境变量。完整部署与 TURN 配置见部署说明。
make test-backend
make contract-check
开发计划中的生产可观测性、并发保护和可靠性工作尚未全部完成，见单租户生产化计划。
提示词 Pipeline 的远程编程任务接入与迁移步骤见 后台任务说明。使用 Pipecat 原生 Jobs，需先迁移数据库并配置已有的远程 OpenCode 服务。