docs: clarify realtime interaction positioning and capability status
This commit is contained in:
Xin Wang
@@ -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:<id>` 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` 为字段及事件依据。
|
||||
+2
-2
@@ -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"]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
+37
-19
@@ -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)及公开协议的兼容范围。
|
||||
|
||||
+27
-11
@@ -1,22 +1,38 @@
|
||||
---
|
||||
title: 产品概览
|
||||
description: 面向实时语音交互的助手管理与集成平台。
|
||||
icon: video
|
||||
description: 了解实时交互服务层的定位、组成和当前边界。
|
||||
icon: radio
|
||||
---
|
||||
|
||||
# 产品概览
|
||||
|
||||
在一个界面中配置模型、知识库、工具和助手，并通过 WebRTC 或 WebSocket 接入实时语音对话。
|
||||
AI Video Assistant 是基于 Pipecat 的实时交互服务层。你可以将语音识别、大模型、语音合成，或端到端 Realtime 语音模型绑定到助手，再配置轮次、打断、提示词、工具和工作流，通过 WebSocket 或 WebRTC 接入业务应用。
|
||||
|
||||
## 平台组成
|
||||
管理界面用于配置和预览。业务客户端调用的是服务端已配置的助手：公开接口中的 `assistant:<id>` 指完整助手，并非底层模型 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/`。能力状态以当前仓库实现为准；具体第三方模型仍需用自己的凭证实测。
|
||||
|
||||
@@ -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` 是否有运行适配、助手绑定是否完整，再查看管理界面的会话历史和后端日志。
|
||||
@@ -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 模型适配尚未实现。 |
|
||||
|
||||
以上是文档和产品目录的收敛建议，不是删除正在使用的管理界面接口。接口、数据或资源定义的实际移除需要单独处理兼容性和已有数据。
|
||||
Reference in New Issue
Block a user