--- title: 单租户生产化开发计划 description: 以标准接口、实时可观测性、运行可靠性和全链路质量门禁为主线的建设计划。 icon: list-checks --- # 单租户生产化开发计划 ## 目标 本计划把当前平台从“功能完整的单租户 MVP”推进到“可以稳定对外提供服务的单租户生产平台”。建设顺序固定为： 1. 标准接口契约； 2. 实时可观测性与 SLO； 3. 生产运行可靠性； 4. 全链路质量门禁。 顺序不能颠倒：先确定平台对调用方承诺的行为，再测量真实质量，然后根据数据加固运行时，最后用自动化门禁持续证明质量。 ## 范围 本计划包含： - OpenAI-compatible Responses 和 Realtime 公开接口； - HTTP、SSE、WebSocket 和 WebRTC 的协议契约； - Pipecat Pipeline、Provider、工具、知识库和后台任务的指标与追踪； - 单实例优先的生产部署、优雅停机、任务恢复和资源保护； - 协议、浏览器媒体链路、弱网、故障和负载测试。 本计划暂不包含： - 多用户、组织、工作空间和 RBAC； - `/v1/chat/completions` 兼容层； - 完整实现 OpenAI Responses 的所有可选能力； - SIP、跨区域部署和 Realtime 断线续传； - 助手草稿、发布版本和环境晋级体系。 即使暂不建设完整权限体系，公网部署前仍必须移除默认凭证、分离签名密钥、启用 TLS，并设置基本的请求与并发限制。 ## 当前基线 - `POST /v1/responses` 和 `GET /v1/responses/{response_id}` 已支持持久化状态、`previous_response_id`、SSE 和 Client Tool 续传。 - `/v1/realtime/client_secrets`、`/v1/realtime/calls` 和 `/v1/realtime` WebSocket 已支持标准事件与项目扩展事件。 - Realtime 已支持 WebRTC、WebSocket、Server VAD、PTT、打断、函数调用和条件视觉输入。 - 后端现有 342 个自动化测试，并通过统一入口处理本地 NLTK 运行环境。 - 前端可以通过构建和 lint，已增加官方 SDK 契约测试，但尚无系统性的组件测试和浏览器端到端测试。 - Responses 已启用 Provider token usage 采集；延迟等 Pipecat metrics 尚未启用，健康检查仍只有进程存活语义。 - 知识库处理、通话后分析、Webhook 和批量测试仍有进程内任务或 Worker。 ## 里程碑一：标准接口契约 ### 目标 让第三方调用方只依赖公开文档、OpenAPI 和标准 SDK 即可完成接入，并清楚知道哪些 OpenAI 能力受支持、哪些能力被平台锁定或尚未实现。 ### 1.1 建立兼容性规范 - [x] 将公开协议命名为 `OpenAI-compatible subset v1`。 - [x] 为 Responses 请求字段、返回对象、SSE 事件和错误码维护兼容矩阵。 - [x] 为 Realtime 客户端事件、服务端事件、传输限制和扩展事件维护兼容矩阵。 - [x] 区分三种字段状态：支持、平台锁定、不支持。 - [x] 为 `x.interactive_media.*` 扩展增加独立版本号和能力协商说明。 - [x] 规定新增字段向后兼容、废弃字段通知和破坏性变更升级规则。 ### 1.2 补全公开 API Schema - [x] 为 Responses create、retrieve 和错误对象建立 Pydantic 模型。 - [x] 使用判别联合描述 `message`、`function_call` 和 `function_call_output`。 - [x] 在 OpenAPI 中声明 JSON、multipart/form-data、application/sdp 和 text/event-stream。 - [x] 为 Realtime JSON 事件维护可校验的 JSON Schema。 - [x] 为所有公开响应声明状态码、错误结构和示例。 - [x] 生成并提交稳定的 OpenAPI snapshot，CI 检查未审查的契约变化。 ### 1.3 完善 Responses 资源接口 - [x] 增加 `GET /v1/responses/{response_id}/input_items`，支持稳定排序和分页。 - [x] 增加 `DELETE /v1/responses/{response_id}`。 - [x] 删除 Response 时使用逻辑删除或内部 tombstone，不能破坏已有子 Response 的祖先链。 - [x] 增加 `Idempotency-Key`：同 Key、同请求返回原结果；同 Key、不同请求返回冲突。 - [x] Provider 可以提供 Token 统计时返回真实 `usage`；无法提供时保持 `null` 并写入兼容说明。 - [x] 暂不实现 background 时，明确拒绝 `/cancel`，而不是静默接受。 ### 1.4 增加模型发现与统一错误 - [x] 增加 `GET /v1/models`，列出当前可以通过公开接口调用的助手。 - [x] 第一版继续返回 `assistant:asst_xxx`；响应结构为未来稳定助手别名保留字段。 - [x] 所有公开 HTTP 错误统一为 OpenAI 风格的 `error` 对象。 - [x] 所有 HTTP 响应返回或透传 `X-Request-ID`。 - [x] Realtime `error.event_id` 必须关联原客户端事件。 - [x] 401、404、409、422、429、503 的使用规则写入协议文档。 ### 1.5 SDK 契约测试 - [x] 使用官方 OpenAI Python SDK 测试 Responses 非流式、多轮和 SSE。 - [x] 使用官方 OpenAI JavaScript SDK 测试相同场景。 - [x] 测试 Client Tool 调用及 `function_call_output` 续传。 - [x] 测试跨 API Key 隐藏、重复幂等键和不支持字段。 - [x] 对 Realtime WebSocket 事件运行 JSON Schema 与事件顺序测试。 ### 验收标准 - OpenAPI 中所有公开 HTTP 接口都有请求体、响应体和错误 schema。 - 官方 Python 和 JavaScript SDK 可以通过自定义 `base_url` 完成三轮 Responses 对话。 - 非流式结果、SSE 最终结果和 GET 查询结果语义一致。 - 公开兼容矩阵与代码自动化测试一一对应。 - 调用方不阅读项目源码也能完成首次接入。 ## 里程碑二：实时可观测性与 SLO ### 目标 能够回答“慢在哪里、错在哪里、影响了多少会话”，并用可量化指标定义实时对话质量。 ### 2.1 建立统一关联标识 每次执行使用以下层级： ```text request_id └─ session_id / response_id └─ conversation_id └─ turn_id ├─ asr span ├─ llm span ├─ tts span ├─ knowledge span └─ tool span ``` - [ ] 使用 `contextvars` 在异步任务中传播关联标识。 - [ ] HTTP、SSE、WebSocket、WebRTC、后台任务和 Webhook 使用同一套标识命名。 - [ ] 日志中输出关联标识，但不把提示词、转写、密钥或动态变量作为默认日志字段。 - [ ] 指标标签禁止使用 response ID、session ID 等高基数字段。 ### 2.2 接入 Metrics 和 Tracing - [ ] 启用 Pipecat Pipeline metrics。 - [ ] 接入 Prometheus 指标端点。 - [ ] 接入 OpenTelemetry SDK，并允许通过 OTLP 环境变量配置 exporter。 - [ ] 为 FastAPI、HTTP Provider 调用和 PostgreSQL 增加基础自动插桩。 - [ ] 为 Pipeline 阶段、工具、知识库、SSE 和后台任务增加业务 span。 - [ ] exporter 不可用时不得阻塞或终止实时对话。 ### 2.3 第一批指标 | 指标 | 类型 | 推荐标签 | | --- | --- | --- | | 活跃 Realtime 会话 | Gauge | channel、runtime_mode | | 会话建立和结束 | Counter | channel、status、reason | | 用户停说到首音频 | Histogram | runtime_mode、provider | | ASR final 延迟 | Histogram | interface_type、status | | LLM 首 Token 延迟 | Histogram | interface_type、status | | TTS 首音频延迟 | Histogram | interface_type、status | | 打断处理延迟 | Histogram | channel、status | | 工具调用延迟 | Histogram | tool_type、status | | 知识库检索延迟 | Histogram | mode、status | | Responses 请求 | Counter/Histogram | stream、status | | 后台任务 | Counter/Histogram | kind、status | - [ ] 统一定义成功、取消、客户端断开、超时和内部失败状态。 - [ ] Provider 错误按鉴权、限流、超时、网络和服务端错误分类。 - [ ] WebRTC 首版从服务端可见统计开始；浏览器 `getStats()` 上报作为后续增强。 ### 2.4 仪表盘与初始 SLO - [ ] 建立 Realtime 总览、Provider、Responses、工具与后台任务仪表盘。 - [ ] 至少展示 p50、p95、p99 和最近错误样本。 - [ ] 先采集基线，再确认正式阈值。 - [ ] 为会话建立失败率、首音频延迟、Provider 错误率和任务积压设置告警。 初始候选目标： | 项目 | 候选目标 | | --- | --- | | Realtime 会话建立成功率 | ≥ 99.5% | | 用户停说到首音频 | p95 ≤ 2 秒 | | 服务端打断处理 | p95 ≤ 250 ms | | 平台自身导致的 turn 失败率 | ≤ 0.5% | | Responses 非流式成功率 | ≥ 99.5% | 正式 SLO 必须在目标部署环境和真实 Provider 上取得基线后确认。 ### 验收标准 - 可以从一次失败的会话追踪到具体 Provider、工具或存储阶段。 - 仪表盘能展示首音频延迟、错误率、活跃会话和任务积压。 - 关闭监控后端不会影响对话主链路。 - 日志和指标不泄漏用户内容或密钥。 ## 里程碑三：生产运行可靠性 ### 目标 在单租户、单区域、单个 Realtime API 进程优先的约束下，实现可恢复、可排空、有限流和可备份的生产运行方式。 ### 3.1 Realtime 进程生命周期 - [ ] 增加服务状态：starting、ready、draining、stopped。 - [ ] draining 后停止签发 Client Secret，并拒绝新 Calls 和 WebSocket 会话。 - [ ] 已建立会话在可配置的宽限期内继续运行。 - [ ] 宽限期结束后取消剩余 Pipeline，并持久化明确终态。 - [ ] 统一 WebRTC、WebSocket、RTVI 和 Responses 的关闭及取消路径。 - [ ] 为 Pipeline 启动、关闭和资源释放增加超时保护。 Realtime Pipeline 与媒体连接绑定，继续保留在 API 进程内，不迁移到普通任务队列。 ### 3.2 健康检查和资源保护 - [ ] 增加 `/health/live`，只判断事件循环和进程是否存活。 - [ ] 增加 `/health/ready`，检查数据库、迁移版本、必要配置和对象存储。 - [ ] readiness 失败时不接收新会话，但 liveness 不应因此触发无限重启。 - [ ] 设置全局活跃会话上限和每 API Key 并发上限。 - [ ] 为请求体、音频缓冲、SSE 队列和工具结果设置大小上限。 - [ ] 数据库连接池、HTTP 连接池和线程池使用显式上限。 - [ ] 达到容量上限时返回可识别的 429 或 503。 ### 3.3 Provider 可靠性策略 - [ ] 统一 Provider 错误分类和超时配置。 - [ ] 只有在尚未向客户端输出内容时才允许自动重试。 - [ ] 流式输出开始后禁止透明重试，避免重复文字、音频或工具调用。 - [ ] 对新会话实现轻量熔断和恢复探测。 - [ ] 模型资源测试与生产请求共享同一套连接和错误分类逻辑。 - [ ] 备用 Provider 或模型作为后续可选能力，不在第一批强制实现。 ### 3.4 迁移后台任务 第一批迁移以下任务： - 知识库文档解析与向量化； - 通话后分析； - Webhook 投递； - 批量测试和 Prompt 改进。 实现约束： - [ ] 使用 Redis + ARQ 作为单租户 MVP 队列。 - [ ] PostgreSQL 保存任务业务状态，Redis 只负责投递、租约和重试。 - [ ] 每类任务都有幂等键、最大重试次数和明确终态。 - [ ] Worker 崩溃后任务可以重新领取。 - [ ] 重复执行不能重复发送 Webhook 或写入重复结果。 - [ ] API 能查询任务状态，服务启动不再直接恢复和执行全部后台工作。 ### 3.5 生产部署和恢复 - [ ] 增加生产 API 镜像，移除 `--reload`。 - [ ] 前端使用 `next build` 与 `next start` 或静态生产部署。 - [ ] 数据库迁移作为独立部署步骤，不能由多个 API 实例同时执行。 - [ ] 为 PostgreSQL 和对象存储编写备份、恢复和校验步骤。 - [ ] 设置日志轮转、磁盘水位和录音/Response 保留策略。 - [ ] 完成一次从备份恢复到新环境的演练。 ### 验收标准 - 服务进入 draining 后不接收新会话，已有会话可以正常结束或在超时后被正确取消。 - Worker 被强制终止后，未完成任务可以恢复且不会重复产生副作用。 - Provider 超时不会无限占用 Pipeline 或连接。 - 数据库或对象存储不可用时 readiness 会失败并给出可诊断原因。 - 生产部署不运行开发热更新服务。 ## 里程碑四：全链路质量门禁 ### 目标 把协议正确性、实时体验和故障恢复变成每次变更都能重复验证的发布条件。 ### 4.1 测试分层 | 层级 | 运行时机 | 内容 | | --- | --- | --- | | 单元和组件测试 | 每次提交 | 协议解析、状态机、工具、工作流、指标 | | 契约测试 | 每次提交 | OpenAPI、JSON Schema、Python/JS SDK | | 服务集成测试 | 每次提交 | PostgreSQL、Redis、对象存储、Fake Provider | | 浏览器媒体测试 | 主分支或发布前 | WebRTC、假麦克风、DataChannel、打断 | | 基础设施测试 | 每日或发布前 | TURN、弱网、故障注入 | | 真实 Provider smoke | 每日或发布前 | 限量 ASR、LLM、TTS、Realtime 调用 | | 负载和长稳测试 | 发布前 | 并发、容量、内存、连接和任务泄漏 | ### 4.2 每次提交门禁 - [ ] 提供一个无需隐藏环境变量的后端测试命令。 - [ ] 运行后端全部测试、前端 lint 和 production build。 - [ ] 从空数据库执行所有 Alembic migrations。 - [ ] 校验 OpenAPI snapshot 和 Realtime JSON Schema。 - [ ] 使用 Fake Provider 完成 Responses 三轮对话、分支和 Client Tool 续传。 - [ ] 测试 SSE 断开、Pipeline 失败、超时和取消后的数据库终态。 - [ ] 测试 Worker 幂等、重试和任务恢复。 ### 4.3 浏览器和媒体链路 - [ ] 使用 Playwright Chromium 假麦克风输入固定音频文件。 - [ ] 验证 WebRTC SDP、远端音频轨道和 `oai-events` DataChannel。 - [ ] 验证 Server VAD、PTT、打断和 Client Tool。 - [ ] 使用固定 PCM fixture 测试 Realtime WebSocket。 - [ ] 在独立环境中强制只走 TURN，避免测试误用直连路径。 - [ ] 保存失败时的浏览器日志、协议事件和服务端 trace。 ### 4.4 弱网、故障和负载 - [ ] 使用 Linux `tc netem` 注入延迟、抖动、丢包和短时断网。 - [ ] 注入 ASR、LLM、TTS、工具、数据库、Redis 和对象存储超时。 - [ ] 验证客户端断开后 Pipeline 与资源及时释放。 - [ ] 对 Responses HTTP/SSE 和 Realtime WebSocket 运行并发测试。 - [ ] 使用 aiortc 测试客户端运行 WebRTC 并发场景。 - [ ] 运行 30 至 60 分钟长连接 soak test，观察内存、Task 和连接数量。 ### 4.5 发布判定 一次生产发布至少满足： - [ ] 单元、契约、集成和浏览器关键路径全部通过。 - [ ] 没有未审查的公开协议变化。 - [ ] p95 首音频延迟未超过允许回归范围。 - [ ] 错误率、超时率和异常断开率未超过阈值。 - [ ] 没有持续增长的 Pipeline、asyncio Task、数据库连接或 WebRTC peer。 - [ ] 备份恢复和 Worker 恢复机制在当前版本仍然有效。 ## 推荐交付批次 ### 批次 A：契约与工程入口 - 修复统一测试命令； - 建立后端、前端和 migration CI； - 为 Responses 增加 Pydantic/OpenAPI schema； - 增加统一错误对象、Request ID 和 OpenAPI snapshot； - 增加 Python SDK Responses 契约测试。 ### 批次 B：Realtime 契约与观测基础 - 建立 Realtime 事件 JSON Schema； - 增加 JavaScript SDK 和 WebSocket 契约测试； - 建立关联 ID 和结构化日志； - 接入 Prometheus 与 OpenTelemetry； - 输出第一版运行基线仪表盘。 ### 批次 C：生命周期与 Worker - 增加 live、ready 和 draining； - 增加会话、缓冲和连接池上限； - 统一 Provider 超时和重试边界； - 引入 ARQ Worker 并逐类迁移后台任务； - 增加生产镜像与备份恢复说明。 ### 批次 D：全链路发布门禁 - 建立 PostgreSQL、Redis、对象存储和 Fake Provider 集成环境； - 增加 Playwright WebRTC 与 PCM WebSocket 测试； - 增加 TURN、弱网、故障注入和真实 Provider smoke； - 建立负载、长稳测试和发布阈值。 ## 总体验收 完成本计划后，平台应满足以下定义： 1. 对外接口有明确、可生成、可测试的稳定契约； 2. 每个请求、会话和对话轮次都可以被测量和追踪； 3. 服务、Provider 或 Worker 故障不会留下无法恢复的模糊状态； 4. 发布前可以自动证明标准接口、实时媒体链路和核心 SLO 没有回归； 5. 无需引入多用户体系，也能作为单租户生产服务安全、稳定地运行。