README.md

# AI Video Assistant

基于 [Pipecat](https://github.com/pipecat-ai/pipecat) 的实时交互服务层。通过配置助手，将 **ASR → LLM → TTS 管线**或**端到端 Realtime 语音模型**与轮次检测、打断、工具、工作流和可选视觉能力组合起来，向业务应用提供实时会话服务。管理界面负责配置、预览和排查；对外接入使用 OpenAI Realtime 兼容子集，提供 WebSocket 和 WebRTC 两种通道。

这里的 `assistant:<id>` 代表服务端配置好的完整助手，不是底层模型 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)：生产化待办。