ai-video-fullstack/backend/README.md

# 后端运行时

本目录提供 FastAPI 接入层、助手与模型资源管理，以及以 Pipecat 为核心的实时会话运行时。项目定位和完整能力状态见[仓库 README](../README.md)与[用户文档](../docs-user/status.mdx)。当前依赖版本以 [requirements.txt](requirements.txt) 为准。

## 请求如何进入运行时

```text
业务客户端 ── /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`。字段、事件和传输限制以[兼容矩阵](../docs-developer/openai-compatibility.mdx)为准。
- **既有通道**：`/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 自身的设置。 |

后两项是[建议收敛的占位内容](../docs-user/status.mdx)：在适配完成前，宜隐藏或标记不可用；移除已有资源定义前需考虑数据库记录。

## 主要目录

| 路径 | 用途 |
| --- | --- |
| `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 开发环境：

```bash
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 配置见[部署说明](../deploy/README.md)。

```bash
make test-backend
make contract-check
```

开发计划中的生产可观测性、并发保护和可靠性工作尚未全部完成，见[单租户生产化计划](../docs-developer/development-plan.mdx)。

提示词 Pipeline 的远程编程任务接入与迁移步骤见 [后台任务说明](../docs-developer/prompt-background-tasks.mdx)。使用 Pipecat 原生 Jobs，需先迁移数据库并配置已有的远程 OpenCode 服务。