From 56b574d98769312cddb399d2067293e6a9f3f55b Mon Sep 17 00:00:00 2001 From: Xin Wang Date: Thu, 24 Sep 2026 02:49:46 +0800 Subject: [PATCH] docs: clarify realtime interaction positioning and capability status --- README.md | 57 +++++++ backend/README.md | 214 ++++++--------------------- docs-developer/index.mdx | 3 +- docs-developer/integrations.mdx | 2 + docs-developer/realtime-protocol.mdx | 2 +- docs-user/access.mdx | 27 ++++ docs-user/docs.json | 4 +- docs-user/features.mdx | 56 ++++--- docs-user/index.mdx | 38 +++-- docs-user/quickstart.mdx | 30 ++++ docs-user/status.mdx | 45 ++++++ frontend/README.md | 41 ++--- 12 files changed, 288 insertions(+), 231 deletions(-) create mode 100644 README.md create mode 100644 docs-user/access.mdx create mode 100644 docs-user/quickstart.mdx create mode 100644 docs-user/status.mdx diff --git a/README.md b/README.md new file mode 100644 index 0000000..a63eac3 --- /dev/null +++ b/README.md @@ -0,0 +1,57 @@ +# AI Video Assistant + +基于 [Pipecat](https://github.com/pipecat-ai/pipecat) 的实时交互服务层。通过配置助手，将 **ASR → LLM → TTS 管线**或**端到端 Realtime 语音模型**与轮次检测、打断、工具、工作流和可选视觉能力组合起来，向业务应用提供实时会话服务。管理界面负责配置、预览和排查；对外接入使用 OpenAI Realtime 兼容子集，提供 WebSocket 和 WebRTC 两种通道。 + +这里的 `assistant:` 代表服务端配置好的完整助手，不是底层模型 ID。OpenAI Realtime **协议兼容**也不意味着已接入 OpenAI Realtime **模型**。公开协议是有明确边界的 [OpenAI-compatible subset v1](docs-developer/openai-compatibility.mdx)，并非完整 OpenAI API。 + +> 当前仓库尚未提供 LICENSE 文件。开源发布前需要确定并添加许可证。 + +## 项目组成 + +| 层次 | 职责 | +| --- | --- | +| 接入层 | `/v1/realtime` WebSocket、`/v1/realtime/calls` WebRTC；另有 `/v1/responses` 文本接口。 | +| 运行层 | Pipecat 管理媒体传输、Pipeline 或 Realtime 模型、轮次与打断；助手配置决定提示词、工作流、工具和模型资源。 | +| 配置层 | Web 界面维护助手、模型资源、知识库和工具，并提供调试、测试与历史记录。 | + +旧的 `/ws/voice`、`/ws/stream` 和 `/api/webrtc/offer` 仍供平台界面及特定集成使用，采用管理员鉴权与不同的消息格式；第三方新接入应先阅读[接入方式](docs-user/access.mdx)。 + +## 当前能力 + +以下状态以仓库实现为准；具体模型服务是否可用仍取决于所填凭证、协议兼容性和实际联调。 + +| 状态 | 能力 | +| --- | --- | +| 已实现 | Pipeline 模式接入受支持的 ASR、LLM、TTS；Pipecat 轮次检测、打断；Prompt、Workflow 和部分外部 Agent；WebRTC/WebSocket 实时会话。 | +| 已实现 | 对外 OpenAI Realtime 兼容子集，以及 Pipeline 助手的 `/v1/responses` 文本接口；具体事件和字段见[兼容矩阵](docs-developer/openai-compatibility.mdx)。 | +| 已实现但有条件 | 端到端 Realtime 模型目前有 StepFun StepAudio 与 Qwen Audio 运行适配；工具、视觉和轮次控制依助手模式及 Provider 能力而异。 | +| 未实现 | OpenAI Realtime 和 Gemini Live 的**底层模型运行适配**；任意 VAD/EOU 模型即插即用；WebSocket 连续视频、SIP、Realtime 断线续传、完整 OpenAI API 兼容。 | + +模型资源目录中的 `openai-realtime`、`gemini-realtime` 及对应示例资源目前是**未接通的占位项**：可以看到或配置资源，不代表语音会话能运行。完整状态和建议收敛项见[能力状态](docs-user/status.mdx)。 + +## 本地启动 + +需要 Docker Compose。以下命令启动本地开发环境；API 容器启动时会执行数据库迁移并同步接口定义： + +```bash +docker compose up -d +``` + +打开管理界面 `http://localhost:3030`；后端健康检查为 `http://localhost:8000/health`，接口文档为 `http://localhost:8000/docs`。首次语音测试前需在「组件库 / 模型资源」中填写真实服务连接，并创建助手绑定。可选的 `make db-seed` 需要本机安装 `make` 和 `uv`，用于初始化示例数据；其中的 `replace-me` 是占位密钥。该命令也会更新示例助手绑定，已有数据的环境不要把它当作常规升级命令。 + +从管理界面创建 Prompt 助手时，可以选择： + +1. **Pipeline**：绑定受支持的 ASR、LLM、TTS，并配置 VAD、轮次结束与打断。 +2. **Realtime**：绑定已接通的 StepFun 或 Qwen Audio 资源；轮次控制主要使用 Provider 的设置。 +3. 保存后通过助手语音预览验证整条链路，再按[公开接入方式](docs-user/access.mdx)连接业务客户端。 + +浏览器麦克风在 localhost 或 HTTPS 环境下使用；公网 WebRTC 通常还需要 TURN。部署说明见 [deploy/README.md](deploy/README.md)。 + +## 文档 + +- [用户文档概览](docs-user/index.mdx)：产品定位与使用路径。 +- [配置第一个助手](docs-user/quickstart.mdx)：模型资源、助手与语音预览。 +- [功能与配置](docs-user/features.mdx)：助手模式、模型、轮次、视觉和工具的适用范围。 +- [能力状态与收敛建议](docs-user/status.mdx)：已实现、未实现及建议移除的占位内容。 +- [开发者快速开始](docs-developer/index.mdx)、[Realtime 协议](docs-developer/realtime-protocol.mdx)、[Responses 接口](docs-developer/responses-api.mdx)：接口细节与契约。 +- [后端说明](backend/README.md)：实现和本地开发；[开发计划](docs-developer/development-plan.mdx)：生产化待办。 diff --git a/backend/README.md b/backend/README.md index 20c43b3..cf0daf8 100644 --- a/backend/README.md +++ b/backend/README.md @@ -1,189 +1,63 @@ -# AI Video Assistant — 后端引擎 +# 后端运行时 -参考 [dograh](../dograh),用 **pipecat** 作语音引擎的自建后端。目标是逐步长成 -类 dograh 平台,但**同时支持 WebRTC 和 WS 两种音频输出**。 +本目录提供 FastAPI 接入层、助手与模型资源管理，以及以 Pipecat 为核心的实时会话运行时。项目定位和完整能力状态见[仓库 README](../README.md)与[用户文档](../docs-user/status.mdx)。当前依赖版本以 [requirements.txt](requirements.txt) 为准。 -## 双输出架构(核心) - -pipecat 把"管线"和"输出方式"解耦:同一条 `STT→LLM→TTS` 管线可挂不同 transport。 - -``` - ┌─────────────────────────────────┐ - 浏览器 ──WebRTC──► /ws/voice ──┤ │ - │ run_pipeline(transport, cfg): │ - 自定义/话务 ─WS──► /ws/stream ─┤ input→STT→LLM→TTS→output │ - └─────────────────────────────────┘ -``` - -- **WebRTC**(`/ws/voice`):浏览器,低延迟,带 NAT 穿透。`SmallWebRTCTransport` -- **WS**(`/ws/stream`):裸音频流,服务端/话务/自定义客户端,无 ICE/TURN。`FastAPIWebsocketTransport` - -加第三种输出(如 Twilio 电话)= 在 `services/pipecat/transports.py` 再加一个 `build_xxx_transport` + serializer,管线一行不用改。 - -## 目录结构(对齐 dograh 的 `api/`,便于生长) - -``` -ai-video-backend/ -├── app.py # FastAPI 入口,挂路由 + CORS -├── settings.py # 读 .env,仅存数据库/CORS/TURN 等运行设置 -├── models.py # AssistantConfig(对齐前端 AssistantForm) -├── routes/ # 一个文件一组端点(对齐 dograh routes/) -│ ├── health.py -│ ├── voice_webrtc.py # WebRTC 信令 -│ └── voice_ws.py # WS 裸音频流 -├── services/ -│ └── pipecat/ # 引擎(对齐 dograh services/pipecat/) -│ ├── service_factory.py # 建 STT/LLM/TTS(按 interface_type 分发) -│ ├── transports.py # transport 工厂(加输出方式在此) -│ └── pipeline.py # 管线拼装与运行(transport 无关) -├── Dockerfile -├── requirements.txt -└── .env.example - -# 平台长大后会再加(对齐 dograh): -# db/ SQLAlchemy 模型 + 会话(助手/对话/向量) -# schemas/ pydantic 请求响应 -# tasks/ 后台任务(转写、报表)—— 配 redis -# services/storage.py 录音存储 —— 配 minio -``` - -## 国产栈(全走 OpenAI 兼容,换栈只改 .env) - -| 类型 | 默认 | 接入 | -|------|------|------| -| LLM | DeepSeek | 云端直连,只需 key | -| STT | SenseVoice / FunASR | 本地 OpenAI 兼容转写服务 | -| TTS | CosyVoice | 本地 OpenAI 兼容 TTS 服务 | - -### 讯飞 ASR / TTS / SuperTTS - -讯飞鉴权直接存入对应 `ModelResource.secrets`，接口参数存入 `ModelResource.values`： - -- 普通语音识别：`interface_type=xfyun-asr` -- 普通语音合成：`interface_type=xfyun-tts` -- 超拟人语音合成：`interface_type=xfyun-super-tts` -- `values.apiUrl` 保存讯飞 WebSocket URL，音色、语速等可选参数也放在 `values` -- `secrets` 分别保存 `appId`、`apiKey`、`apiSecret` - -## 接口定义驱动的模型注册表 - -LLM、ASR、TTS、Embedding、Realtime 使用同一套两层结构： +## 请求如何进入运行时 ```text -assistant_model_bindings -> model_resources -> interface_definitions +业务客户端 ── /v1/realtime WebSocket 或 /v1/realtime/calls WebRTC ──┐ +管理界面 ── /api/webrtc/offer、/ws/voice 或 /ws/stream ──────────┤ + ▼ + 协议适配 / Pipecat transport + ▼ + 助手配置 + Pipeline 或 Realtime 模型 ``` -- `interface_definitions`: 定义具体接入协议、能力和动态表单字段。 -- `model_resources`: 每条资源自带 `values/secrets`，不复用供应商账号。 -- `assistant_model_bindings`: 助手按能力选择模型资源。 +- **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_type` 是具体协议，例如 `xfyun-asr`、`xfyun-tts`、 -`xfyun-super-tts`，后端严格按它选择服务实现，不根据模型 ID 或 URL 猜测。 +## 模型资源与能力边界 -API： +`interface_definitions` 定义协议类型和表单字段，`model_resources` 保存每个资源的连接参数与凭证，`assistant_model_bindings` 决定助手使用哪些资源。运行时按 `interface_type` 创建服务，不根据 URL 或模型名自动推断协议。 -- `/api/interface-definitions`: 前端读取字段定义并动态生成 Dialog。 -- `/api/model-resources`: 统一模型资源 CRUD，敏感字段逐项打码。 +| 类型 | 当前运行状态 | +| --- | --- | +| `openai-llm`、`openai-asr`、`openai-tts` 及已接通的讯飞接口 | Pipeline 可用；具体 Provider 仍需联调。 | +| `stepfun-realtime`、`qwen-audio-realtime` | Realtime 可用；具体功能按 Provider 能力限制。 | +| `openai-realtime`、`gemini-realtime` | **未接通运行时**。接口定义和种子资源仍在目录中，不能据此宣称模型可用。 | +| 任意独立 VAD／EOU 模型 | **未实现**。目前是内置 Pipeline 策略或 Realtime Provider 自身的设置。 | -## 本地运行(用 uv,Python 3.12) +后两项是[建议收敛的占位内容](../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 -cd ai-video/backend -uv venv # 按 .python-version 用 3.12 - -# 阶段 A:只验证存储/CRUD(不装 pipecat,秒级) -uv pip install fastapi "uvicorn[standard]" sqlalchemy asyncpg greenlet python-dotenv pydantic loguru -# 阶段 B:做语音时再装全量(含 pipecat,需 3.10+) -# uv pip install -r requirements.txt - -cp .env.example .env # 只放数据库/CORS/TURN;模型 key 在模型资源里维护 -# 起 Postgres:在 ai-video/ 下 docker compose up -d postgres -cd .. -make db-migrate # 首次或表结构变更后执行 Alembic 迁移 -cd backend -uv run --with-requirements requirements.txt uvicorn app:app --reload --port 8000 +docker compose up -d ``` -> pipecat 相关代码用**惰性导入**,所以阶段 A 不装 pipecat 也能启动并跑 `/api/*` 与 `/health`; -> 只有真正连 `/ws/voice`、`/ws/stream` 时才需要全量依赖。 -> -> 交互式 API 文档:启动后访问 http://localhost:8000/docs(手动戳 CRUD、定 schema 用)。 +API 容器启动时会执行 Alembic 迁移并同步接口定义。本机单独运行后端时，可用 `make db-init` 完成这两步；它需要本机安装 `uv`。需要演示助手和模型资源时，另运行 `make db-seed`；种子密钥是占位值，不能直接用于真实模型调用。`make db-seed` 还会更新示例助手的模型绑定，不要在已有生产配置上当作常规升级命令运行。 -## 数据库迁移 - -表结构由 Alembic 管理，SQLAlchemy 模型在 `db/models.py`，迁移文件在 -`migrations/versions/`。 +后端地址是 `http://localhost:8000`，交互式 HTTP API 文档是 `/docs`。本地开发也可在 `backend/` 目录使用 `uv run --with-requirements requirements.txt uvicorn app:app --reload --port 8000`，需先准备数据库和环境变量。完整部署与 TURN 配置见[部署说明](../deploy/README.md)。 ```bash -cd ai-video -make db-migrate # 升级到最新版 -make db-revision msg="add xxx" # 根据模型差异生成迁移 -make db-current # 查看当前库版本 +make test-backend +make contract-check ``` -`interface_definitions` 的默认数据由 `services/interface_catalog.py` 维护，并通过 -启动时同步或 `make db-sync-interface-definitions` 写入数据库；模型资源、知识库和助手示例数据继续走 `db/seed_*.sql`。 - -## Docker(ai-video/docker-compose.yaml)—— 调试主路径 - -api 服务挂了源码 + `--reload`,前端用 npm dev + HMR,改代码都即时生效。 - -```bash -cd ai-video -docker compose up # 前台起 pg + api(:8000)+ ui(:3030),日志直出 -docker compose up -d # 后台起;看日志 docker compose logs -f api -docker compose down # 停止全部 - -# 知识库依赖 RustFS；默认 compose 会一起启动。Redis 仍是可选服务。 -docker compose up -d postgres rustfs api ui -docker compose --profile data up -d redis -# 可选:公网部署(WebRTC 需 TURN) -docker compose --profile remote up -d -``` - -> 首次 `up` 会构建 api 镜像(装全量 `requirements.txt`,含 pipecat,较慢)。 -> 之后改 Python 代码靠 `--reload` 热更新,不用重建;只有改 `requirements.txt` 才 `docker compose build api`。 - -## 极简知识库 MVP - -知识库入口为前端「组件 / 知识库」。使用前先在「组件 / 模型」配置并启用 -一个 Embedding 资源，然后： - -1. 创建知识库并选择 Embedding 模型。 -2. 上传 PDF、DOCX、TXT、Markdown、CSV、JSON 或 HTML，或者直接添加文字。 -3. 文档状态会从 `pending` 变为 `processing`，最终进入 `ready` 或 `failed`。 -4. 失败记录会保留，可在页面重试；完成后可预览分块并使用「检索测试」验证召回。 -5. 在提示词助手的 pipeline 模式下选择知识库。每轮 LLM 推理前会自动检索并注入相关片段。 - -当前后台处理使用 FastAPI 进程内任务，适合 MVP。服务重启时未完成任务会转为失败， -可在页面重试；需要多实例或高吞吐时再迁移到 Redis/ARQ worker。 - -## Prompt 动态变量 - -提示词助手的 Pipeline 与 Realtime 模式都支持在开场白和系统提示词中使用 -`{{ variable_name }}`。Pipeline 模式还支持在 HTTP 工具的 URL、Header 和 Body -中引用变量。助手页维护变量类型、默认值和必填规则；调试面板在每次通话开始前 -传入会话值。Realtime 会把渲染后的提示词作为模型 instructions。 - -内置系统变量包括 `system__conversation_id`、`system__time`、 -`system__agent_turns` 和 `system__conversation_history`。客户端不能提交 -`system__*` 或 `secret__*`。HTTP 工具的密钥变量必须在工具的服务端密钥配置中 -以 `secret__` 开头声明，而且只能用于 Header。 - -HTTP 工具可通过“响应变量赋值”把 JSON 路径写回普通会话变量，例如： - -```json -{"order_status": "response.order.status"} -``` - -后续轮次会使用新值重新渲染系统提示词。上线前执行 `make db-migrate`，应用 -`20260712_0007` 迁移。 - -## 待联调 / TODO - -- [ ] 联调 Pipecat 1.3.0 语音链路与各 OpenAI 兼容服务 -- [ ] 起本地 SenseVoice / CosyVoice 的 OpenAI 兼容服务 -- [x] `realtime` 模式(StepFun StepAudio Realtime) -- [x] `realtime` 模式(Alibaba Cloud Qwen-Audio 3.0 Realtime MVP) -- [x] 前端 `DebugVoicePanel` 接 `/ws/voice`(参考 dograh `useWebSocketRTC.tsx`) -- [ ] 加 DB 后:助手配置入库(目前随请求内联) +开发计划中的生产可观测性、并发保护和可靠性工作尚未全部完成，见[单租户生产化计划](../docs-developer/development-plan.mdx)。 diff --git a/docs-developer/index.mdx b/docs-developer/index.mdx index fe720ae..a90d69b 100644 --- a/docs-developer/index.mdx +++ b/docs-developer/index.mdx @@ -12,10 +12,9 @@ icon: rocket ```bash docker compose up -d -make db-seed ``` -首次启动会构建后端镜像。启动后访问： +首次启动会构建后端镜像；API 容器会执行数据库迁移并同步接口定义。需要演示助手和模型资源时，可额外运行 `make db-seed`（本机需有 `make` 和 `uv`）。种子密钥是占位值，该命令也会更新示例助手绑定，不要在已有配置的环境中当作常规升级命令。启动后访问： - 前端：`http://localhost:3030` - 后端健康检查：`http://localhost:8000/health` diff --git a/docs-developer/integrations.mdx b/docs-developer/integrations.mdx index 6552c36..1a87642 100644 --- a/docs-developer/integrations.mdx +++ b/docs-developer/integrations.mdx @@ -41,6 +41,8 @@ icon: plug ## 实时语音通道 +以下是管理界面语音预览和既有自定义客户端使用的平台通道，需要管理员鉴权；它们不是对外的 OpenAI Realtime 兼容协议。新业务客户端优先参照[Realtime 兼容协议设计](/realtime-protocol)，使用 `/v1/realtime` WebSocket 或 `/v1/realtime/calls` WebRTC。 + | 通道 | 地址 | 适用场景 | | --- | --- | --- | | WebRTC 信令 | `ws(s):///ws/voice` | 浏览器低延迟语音与视频输入。 | diff --git a/docs-developer/realtime-protocol.mdx b/docs-developer/realtime-protocol.mdx index b94eb48..566b7ac 100644 --- a/docs-developer/realtime-protocol.mdx +++ b/docs-developer/realtime-protocol.mdx @@ -38,7 +38,7 @@ Realtime 协议适配层 | OpenAI Realtime Core | 保持标准事件名称、字段含义和生命周期，不改变标准事件语义 | 任意 OpenAI Realtime 兼容客户端 | | `x.interactive_media.*` Extensions | 所有项目扩展均有命名空间和能力协商 | 了解 Interactive Media 扩展的客户端 | -普通兼容客户端不声明扩展能力时，服务端不会发送 `x.interactive_media.*` 事件。它仍可使用音频、文本、图片、转写、回复流、打断和函数调用，但不会获得工作流节点、动态变量、连续视频等项目专属状态。 +普通兼容客户端不声明扩展能力时，服务端不会发送 `x.interactive_media.*` 事件。它仍可使用音频、文本、转写、回复流、打断和函数调用；图片输入仅在已授权视觉的 Pipeline 助手中可用。工作流节点、动态变量和连续视频等项目专属状态需要相应扩展能力。 客户端和服务端事件的机器可校验版本分别保存在 `backend/contracts/openai-realtime-client-events.schema.json` 与 `backend/contracts/openai-realtime-server-events.schema.json`。所有服务端事件含唯一 `event_id`；错误事件中的 `error.event_id` 指向触发错误的客户端事件。 diff --git a/docs-user/access.mdx b/docs-user/access.mdx new file mode 100644 index 0000000..155e36b --- /dev/null +++ b/docs-user/access.mdx @@ -0,0 +1,27 @@ +--- +title: 接入方式 +description: 区分公开 Realtime 接口、Responses 文本接口和平台调试通道。 +icon: plug +--- + +# 接入方式 + +新业务客户端使用 `/v1/` 下的公开接口。请求中的 `model` 是 `assistant:<助手 ID>`；底层模型、凭证、提示词和工具由服务端助手配置决定。 + +| 用途 | 接口 | 鉴权与数据 | +| --- | --- | --- | +| 浏览器或移动端实时音频 | `POST /v1/realtime/client_secrets`、`POST /v1/realtime/calls` | 业务后端用长期 Key 签发短期令牌；客户端用 WebRTC 媒体轨道传音频、DataChannel 传事件。 | +| 服务端或自定义客户端实时会话 | `/v1/realtime?model=assistant:` WebSocket | 使用 Bearer Key；JSON 文本帧承载事件，音频为 Base64 PCM16。 | +| Pipeline 助手的文本调用 | `POST /v1/responses` | 长期 Bearer Key；支持 JSON 或 SSE、多轮 `previous_response_id`。 | +| 查询可调用助手 | `GET /v1/models` | 长期 Bearer Key；返回助手 ID 和其 `responses`／`realtime` 能力。 | + +公开 Realtime 接口是 **OpenAI-compatible subset v1**，并附有可协商的 `x.interactive_media.*` 扩展。客户端可更新的会话字段有限；助手身份、模型、提示词、音色和工具等以服务端配置为准。WebSocket 暂只支持指定格式的音频与图片项，不支持连续视频；连续摄像头输入使用协商后的 WebRTC 视频轨道。 + +## 管理界面和旧通道 + +| 通道 | 当前用途 | 与公开接口的区别 | +| --- | --- | --- | +| `/api/webrtc/offer`、`/ws/voice` | 管理界面 WebRTC 预览和现有集成 | 使用管理员鉴权及平台信令／RTVI 消息。 | +| `/ws/stream` | 裸音频 WebSocket、内部调试和既有自定义客户端 | 使用管理员鉴权；先发启动 JSON，之后传二进制音频帧，不是 OpenAI Realtime JSON 事件协议。 | + +这些通道目前仍在使用。文档建议移除的是**把它们写成第三方首选公开接口的旧表述**，不是立即删除端点。接入前请以开发者文档中的 `openai-compatibility.mdx`、`realtime-protocol.mdx` 和 `responses-api.mdx` 为字段及事件依据。 diff --git a/docs-user/docs.json b/docs-user/docs.json index 4f1082f..04c2933 100644 --- a/docs-user/docs.json +++ b/docs-user/docs.json @@ -1,6 +1,6 @@ { "$schema": "https://mintlify.com/docs.json", - "name": "AI 视频助手 · 用户文档", + "name": "AI Video Assistant · 实时交互层", "theme": "mint", "colors": { "primary": "#1b2741", @@ -46,7 +46,7 @@ "groups": [ { "group": "产品", - "pages": ["index", "features"] + "pages": ["index", "quickstart", "features", "access", "status"] } ] } diff --git a/docs-user/features.mdx b/docs-user/features.mdx index f73b360..97725be 100644 --- a/docs-user/features.mdx +++ b/docs-user/features.mdx @@ -1,32 +1,50 @@ --- title: 核心功能 -description: 项目的主要能力与配置关系。 -icon: bot +description: 助手模式、模型、轮次、视觉、工具和知识库的适用范围。 +icon: sliders-horizontal --- -# 核心功能 +# 功能与配置 -## 助手配置 +以下“已实现”指仓库有对应运行路径；实际服务还需要有效凭证，并受模型提供方能力约束。[能力状态](/status)列出尚未接通和建议移除的占位内容。 -助手是运行时入口，支持提示词、工作流和外部托管三类大脑： +## 选择助手和运行模式 -| 类型 | 用途 | -| --- | --- | -| `prompt` | 用提示词驱动的基础对话，可绑定工具。 | -| `workflow` | 用节点图编排对话流程。 | -| `dify` / `fastgpt` / `opencode` | 将对话处理交给外部 Agent 服务。 | +| 助手类型 | Pipeline | Realtime | 说明 | +| --- | --- | --- | --- | +| Prompt | 已实现 | 已实现，有 Provider 限制 | 提示词驱动，可绑定模型及受支持的工具。 | +| Workflow | 已实现 | 已实现，有 Provider 限制 | 用节点编排对话、状态和动作。 | +| Dify / FastGPT / OpenCode | 已实现 | 未实现 | 对话处理交给外部 Agent，语音输入输出仍由平台管线处理。 | -其中 `prompt` 和 `workflow` 支持 `pipeline` 与 `realtime`；外部托管 Agent 仅支持 `pipeline`。 +创建助手时，**Pipeline** 需要分别绑定 ASR、LLM、TTS；外部 Agent 助手将 LLM 环节交给外部服务。**Realtime** 绑定一个端到端语音模型资源。模型资源按 `interface_type` 选择适配，填写一个看似兼容的 URL 不会自动生成新的运行适配。 -## 模型与知识库 +## 模型和交互效果 -模型资源按具体协议注册，而不是按厂商名称猜测。当前支持 OpenAI 兼容的 LLM、ASR、TTS、Embedding、Realtime，也支持讯飞 ASR/TTS/SuperTTS、StepFun Realtime，以及 Dify、FastGPT、OpenCode Agent。 +| 配置 | 当前状态 | 适用范围 | +| --- | --- | --- | +| OpenAI 兼容 LLM、ASR、TTS | 已实现 | Pipeline；具体兼容性仍需连接测试和语音预览。 | +| 讯飞 ASR、TTS、SuperTTS | 已实现 | Pipeline。 | +| StepFun StepAudio、Qwen Audio Realtime | 已实现 | Realtime；不同 Provider 的工具与轮次能力不相同。 | +| OpenAI Realtime、Gemini Live 底层模型 | 未实现 | 资源定义和示例存在，但语音运行适配尚未接通。 | +| 独立 VAD / EOU 模型替换 | 未实现 | Pipeline 当前使用内置 Silero VAD 与 Local Smart Turn；可以调参数、选策略，不能任意选择模型。 | -知识库可绑定一个 Embedding 模型资源。助手引用知识库后，需先解绑才能删除该知识库。 +Pipeline 的“高级交互配置”可以调整 VAD 阈值、开始／停止确认时间、打断检测方式，以及静音等待或 Smart Turn 轮次结束策略。Realtime 模式的 VAD、Smart Turn 等由所选 Provider 的资源设置和会话能力决定；同名参数不保证跨 Provider 行为相同。 -## 工具与历史 +## 视觉、知识库和工具 -- 可复用工具分为 System、HTTP、Client 和 MCP；结束对话属于 System 类别。 -- HTTP 工具的 URL、请求头、参数和密钥独立管理。 -- Prompt 助手和 Workflow Agent 节点可开启内置系统工具：结束对话、更新状态、跳过本轮、请求人工接管；Workflow 还提供确定性的 Update State 节点。 -- 历史记录保留会话、通道、运行模式及消息序列，便于排查对话。 +| 能力 | 当前状态 | 使用条件 | +| --- | --- | --- | +| WebRTC 摄像头输入 | 已实现，有条件 | 助手开启视觉、客户端协商视频轨道，运行时按需获取画面；不是任意 Live 模型的连续视频理解。 | +| Realtime 协议图片项 | 已实现，有条件 | 目前仅 Pipeline 模式及已授权视觉的助手支持；Realtime 模式明确拒绝。 | +| 知识库检索 | 已实现，有条件 | 需要 Embedding 模型和已处理的文档，主要用于 Pipeline 的 Prompt／Workflow。 | +| System、HTTP、Client、MCP 工具 | 已实现，有条件 | Pipeline 和 Workflow 按配置执行；Prompt Realtime 的工具能力取决于 Provider 声明。 | +| 会话与消息历史 | 已实现 | 可在管理界面查看通道、运行模式和消息，辅助排查。 | + +Prompt Realtime 中，Qwen Audio 已声明部分 HTTP、MCP、Client 和内置工具能力；StepFun Prompt Realtime 尚未声明工具能力。保存助手前，界面和服务端会校验不兼容项。外部 Agent 的上下文、知识库和工具通常由对应服务管理。 + +## 配置建议 + +- 需要明确控制 ASR、LLM、TTS、VAD 和轮次结束策略时，先选 Pipeline。 +- 需要端到端语音模型时，先选已接通的 StepFun 或 Qwen Audio，再验证该 Provider 的打断与工具行为。 +- 需要摄像头时，使用 WebRTC，并在助手中启用视觉；WebSocket 不传连续视频。 +- 需要业务客户端集成时，先查看[接入方式](/access)及公开协议的兼容范围。 diff --git a/docs-user/index.mdx b/docs-user/index.mdx index 3e6ab0b..a61bbb9 100644 --- a/docs-user/index.mdx +++ b/docs-user/index.mdx @@ -1,22 +1,38 @@ --- title: 产品概览 -description: 面向实时语音交互的助手管理与集成平台。 -icon: video +description: 了解实时交互服务层的定位、组成和当前边界。 +icon: radio --- # 产品概览 -在一个界面中配置模型、知识库、工具和助手，并通过 WebRTC 或 WebSocket 接入实时语音对话。 +AI Video Assistant 是基于 Pipecat 的实时交互服务层。你可以将语音识别、大模型、语音合成，或端到端 Realtime 语音模型绑定到助手，再配置轮次、打断、提示词、工具和工作流，通过 WebSocket 或 WebRTC 接入业务应用。 -## 平台组成 +管理界面用于配置和预览。业务客户端调用的是服务端已配置的助手：公开接口中的 `assistant:` 指完整助手，并非底层模型 ID。对外接口遵循 **OpenAI-compatible subset v1**，只覆盖文档列出的字段和事件。 -- **助手**：定义提示词、运行模式、模型绑定及可选工作流。 -- **组件库**：统一维护模型资源、知识库和可复用工具。 -- **语音引擎**：Pipecat 管线支持浏览器 WebRTC 与裸 WebSocket 音频流。 +## 从配置到接入 -> 凭证只保存在模型资源或助手的服务端配置中；接口返回会自动打码。 +1. 在「组件库 / 模型资源」填写模型服务地址和凭证。 +2. 创建 Prompt、Workflow 或外部 Agent 助手，选择 Pipeline 或可用的 Realtime 运行模式。 +3. 通过语音预览检查延迟、打断、轮次和回复效果。 +4. 使用公开 Realtime WebRTC/WebSocket 接口接入业务客户端；Pipeline 助手还可使用 Responses 文本接口。 -## 下一步 +详见[功能与配置](/features)及[接入方式](/access)。 -- [核心功能](/features)：了解助手类型、模型、知识库与工具。 -- 本地启动与对接见仓库中的 `docs-developer/`（独立开发者文档站点）。 +## 两种运行模式 + +| 模式 | 组合方式 | 当前轮次控制 | +| --- | --- | --- | +| Pipeline | ASR → LLM／外部 Agent → TTS | 使用 Pipecat 的 VAD、静音或 Smart Turn 策略，可配置打断。 | +| Realtime | 端到端语音模型负责识别、生成和合成 | 主要由所选 Provider 的轮次检测能力决定；不等同于 Pipeline 的独立 VAD/EOU 配置。 | + +两种模式可通过同一套公开 Realtime 接口调用，但功能受助手类型、模型适配和客户端通道限制。当前运行适配的端到端模型类型是 **StepFun StepAudio** 与 **Qwen Audio Realtime**。模型资源目录中出现 OpenAI Realtime 或 Gemini Live，不表示其底层模型适配已经实现。 + +## 阅读指引 + +- [配置第一个助手](/quickstart)：从模型资源到语音预览。 +- [功能与配置](/features)：选择助手、模型、轮次、视觉和工具。 +- [接入方式](/access)：区分公开协议与管理界面使用的通道。 +- [能力状态](/status)：逐项查看已实现、未实现和建议收敛的内容。 + +本地启动、请求字段和事件协议见仓库根目录 `README.md` 与 `docs-developer/`。能力状态以当前仓库实现为准；具体第三方模型仍需用自己的凭证实测。 diff --git a/docs-user/quickstart.mdx b/docs-user/quickstart.mdx new file mode 100644 index 0000000..91fba50 --- /dev/null +++ b/docs-user/quickstart.mdx @@ -0,0 +1,30 @@ +--- +title: 配置第一个助手 +description: 从模型资源到语音预览，验证第一条实时会话链路。 +icon: rocket +--- + +# 配置第一个助手 + +本页从已启动的管理界面开始。首次本地部署可在仓库根目录运行 `docker compose up -d`；API 容器启动时会迁移数据库并同步模型接口定义。界面地址为 `http://localhost:3030`。可选的 `make db-seed` 需要本机安装 `make` 和 `uv`，用于加入演示数据；种子资源中的 `replace-me` 密钥不能用于真实调用，也不要在已有助手数据的环境中当作常规升级命令使用。 + +## 1. 配置模型资源 + +进入「组件库 / 模型资源」，选择接口类型并填写服务地址、模型 ID 和凭证。语音 Pipeline 至少需要 ASR、LLM、TTS；端到端 Realtime 模式目前选择 StepFun StepAudio 或 Qwen Audio。保存前使用“测试连接”，然后再通过语音预览验证整条链路。单项连接成功不代表音频格式、轮次和工具行为均已可用。 + +如果目录中看到 OpenAI Realtime 或 Gemini Live，请先查看[能力状态](/status)：这两种底层模型当前尚未接通运行时。 + +## 2. 创建助手 + +进入「创建助手」，先选择 Prompt 类型，并按需求选运行模式： + +- **Pipeline**：分别绑定 ASR、LLM、TTS；填写系统提示词，按需要设置开场白、打断和高级轮次策略。 +- **Realtime**：绑定一个已接通的 Realtime 资源；音色、VAD 或 Smart Turn 设置以该 Provider 的资源字段和实际能力为准。 + +保存后从助手详情页打开语音预览。第一次验证建议只检查听取用户语音、生成回复、播放语音和打断；确认基本链路后再添加知识库、视觉、工具或 Workflow。 + +## 3. 接入业务客户端 + +语音预览通过后，按[接入方式](/access)选择公开 WebRTC 或 WebSocket。浏览器麦克风需要 localhost 或 HTTPS；公网 WebRTC 通常还要配置 TURN。公开接口以 `assistant:<助手 ID>` 选择助手，第三方客户端不直接提交底层模型密钥。 + +如果会话启动失败，先检查模型资源的真实凭证、所选 `interface_type` 是否有运行适配、助手绑定是否完整，再查看管理界面的会话历史和后端日志。 diff --git a/docs-user/status.mdx b/docs-user/status.mdx new file mode 100644 index 0000000..102ca20 --- /dev/null +++ b/docs-user/status.mdx @@ -0,0 +1,45 @@ +--- +title: 能力状态 +description: 已实现、未实现与建议收敛的项目内容。 +icon: list-checks +--- + +# 能力状态 + +本页的“已实现”表示当前仓库存在对应代码路径，并不替代真实 Provider、弱网或并发环境下的验收。“未实现”表示不能因配置界面、种子数据或开发计划中出现名称就视为可用。“建议移除”是待评估的收敛项，尚未删除。 + +## 已实现或有条件可用 + +| 能力 | 状态 | 边界 | +| --- | --- | --- | +| Pipecat Pipeline：ASR → LLM／外部 Agent → TTS | 已实现 | 需要匹配的模型接口、有效凭证和实际联调。 | +| Pipecat Pipeline 的 Silero VAD、静音结束、Local Smart Turn、打断 | 已实现 | 可调整参数与策略；模型实现目前固定。 | +| StepFun StepAudio、Qwen Audio Realtime | 已实现 | Provider 的轮次、工具与视觉能力各不相同。 | +| Prompt、Workflow、Dify／FastGPT／OpenCode 助手 | 已实现 | 外部 Agent 只支持 Pipeline；公开 `/v1/models` 当前不列出 OpenCode。 | +| OpenAI Realtime 兼容子集的 WebSocket／WebRTC | 已实现 | 是对外协议适配，不代表所有 OpenAI 字段或底层 OpenAI 模型可用。 | +| Responses 文本接口 | 已实现 | 面向可通过该接口调用的 Pipeline 助手。 | +| WebRTC 可选摄像头与视觉处理 | 有条件可用 | 需要助手授权视觉、客户端协商视频轨道，并受运行模式限制。 | +| 工具和知识库 | 有条件可用 | 受助手模式、模型 Provider 与资源配置限制。 | +| 会话与消息历史 | 已实现 | 可在管理界面查看，辅助排查。 | + +## 未实现或尚未承诺 + +| 能力 | 当前情况 | +| --- | --- | +| OpenAI Realtime、Gemini Live 底层模型适配 | 资源目录和种子数据存在，但 Realtime 运行时只创建 StepFun、Qwen Audio 服务。 | +| 任意 VAD、EOU 模型作为独立资源接入 | 目前只有内置 Pipeline 策略及部分 Provider 自身的轮次配置。 | +| 任意原生音视频 Live 模型接入 | 当前摄像头能力以 WebRTC 视频轨道和按需画面处理为主，不能据此宣称通用 Live 模型支持。 | +| 完整 OpenAI API、`/v1/chat/completions` | 公开协议只承诺兼容矩阵中列出的子集。 | +| WebSocket 连续视频、SIP、Realtime 断线续传 | 当前公开协议不支持；可参考开发计划评估。 | +| 多租户、RBAC、完整生产可观测性与可靠性 | 开发计划中仍有待办，当前定位为单租户 MVP。 | + +## 建议移除或收敛，尚未执行 + +| 对象 | 建议 | 原因 | +| --- | --- | --- | +| `openai-realtime`、`gemini-realtime` 可选资源定义与示例资源 | 在运行适配完成前，从可用列表和默认种子中移除，或明确置为“未接通”。已有数据库记录需先评估迁移。 | 当前可配置，但启动语音会话时会遇到不支持的接口类型。 | +| 把 `/ws/voice`、`/ws/stream` 写作第三方首选入口的旧说明 | 从对外接入主线移到“平台调试／既有通道”说明。 | 它们与 `/v1/realtime` 的鉴权、消息格式和兼容承诺不同。 | +| 将“Realtime 协议兼容”写作“OpenAI Realtime 模型已接入”的措辞 | 从功能列表中删除混用表述，分别列对外协议和底层 Provider。 | 两种能力由不同代码实现，当前完成度不同。 | +| 将“视频输入”写作“通用 Live 模型能力”的措辞 | 改为“WebRTC 可选视频轨道和有条件的视觉处理”。 | WebSocket 连续视频与通用 Live 模型适配尚未实现。 | + +以上是文档和产品目录的收敛建议，不是删除正在使用的管理界面接口。接口、数据或资源定义的实际移除需要单独处理兼容性和已有数据。 diff --git a/frontend/README.md b/frontend/README.md index e215bc4..94cc90e 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,36 +1,25 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). +# 管理界面 -## Getting Started +这是实时交互服务层的配置与调试界面，用于管理助手、模型资源、知识库、工具，以及语音预览、测试和历史记录。项目定位、公开接口与能力状态见[仓库 README](../README.md)和[用户文档](../docs-user/index.mdx)。 -First, run the development server: +## 本地开发 + +推荐在仓库根目录运行 `docker compose up -d`，界面地址为 `http://localhost:3030`，后端为 `http://localhost:8000`。如需单独运行前端： ```bash +cd frontend +npm ci npm run dev -# or -yarn dev -# or -pnpm dev -# or -bun dev ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +单独运行时 Next.js 默认监听 `http://localhost:3000`。浏览器默认连接 `http://localhost:8000`；需要其他后端地址时设置 `NEXT_PUBLIC_API_BASE_URL`。后端及数据库仍需单独启动。 -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. +## 检查 -This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. +```bash +npm run lint +npm run test:contracts +npm run build +``` -## Learn More - -To learn more about Next.js, take a look at the following resources: - -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. - -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! - -## Deploy on Vercel - -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. - -Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details. +界面中的“Realtime 模型资源”列表包含尚未接通运行时的占位类型；实际可运行的类型与功能限制见[能力状态](../docs-user/status.mdx)。