From d5378b1ec9bc06d22bbbc2afbec76b82241c9298 Mon Sep 17 00:00:00 2001 From: Xin Wang Date: Fri, 10 Jul 2026 22:54:30 +0800 Subject: [PATCH] =?UTF-8?q?Add=20documentation=20for=20AI=20=E8=A7=86?= =?UTF-8?q?=E9=A2=91=E5=8A=A9=E6=89=8B=20including=20configuration,=20feat?= =?UTF-8?q?ures,=20integrations,=20and=20quickstart=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create a new JSON schema file for documentation settings. - Add core features documentation detailing assistant configuration and model integration. - Include an index page introducing the AI 视频助手 and its platform components. - Document integration methods for model services and external agents. - Provide a quickstart guide for setting up the local development environment using Docker. - Add light and dark logo SVG files for branding purposes. --- docs/docs.json | 57 +++++++++++++++++++++++++++++++++++++++++++ docs/features.mdx | 31 +++++++++++++++++++++++ docs/index.mdx | 26 ++++++++++++++++++++ docs/integrations.mdx | 48 ++++++++++++++++++++++++++++++++++++ docs/logo-dark.svg | 18 ++++++++++++++ docs/logo-light.svg | 18 ++++++++++++++ docs/quickstart.mdx | 45 ++++++++++++++++++++++++++++++++++ 7 files changed, 243 insertions(+) create mode 100644 docs/docs.json create mode 100644 docs/features.mdx create mode 100644 docs/index.mdx create mode 100644 docs/integrations.mdx create mode 100644 docs/logo-dark.svg create mode 100644 docs/logo-light.svg create mode 100644 docs/quickstart.mdx diff --git a/docs/docs.json b/docs/docs.json new file mode 100644 index 0000000..296a095 --- /dev/null +++ b/docs/docs.json @@ -0,0 +1,57 @@ +{ + "$schema": "https://mintlify.com/docs.json", + "name": "AI 视频助手", + "theme": "mint", + "colors": { + "primary": "#1b2741", + "light": "#3a4a6b", + "dark": "#0c1426" + }, + "logo": { + "light": "/logo-light.svg", + "dark": "/logo-dark.svg", + "href": "/" + }, + "appearance": { + "default": "dark" + }, + "fonts": { + "family": "Inter", + "weight": 400, + "heading": { + "family": "Cormorant Garamond", + "weight": 300 + } + }, + "icons": { + "library": "lucide" + }, + "background": { + "decoration": "gradient", + "color": { + "light": "#f3f5fb", + "dark": "#070b16" + } + }, + "styling": { + "eyebrows": "breadcrumbs", + "codeblocks": { + "theme": { + "light": "github-light", + "dark": "github-dark" + } + } + }, + "navigation": { + "groups": [ + { + "group": "开始使用", + "pages": ["index", "quickstart"] + }, + { + "group": "产品与对接", + "pages": ["features", "integrations"] + } + ] + } +} diff --git a/docs/features.mdx b/docs/features.mdx new file mode 100644 index 0000000..f975c27 --- /dev/null +++ b/docs/features.mdx @@ -0,0 +1,31 @@ +--- +title: 核心功能 +description: 项目的主要能力与配置关系。 +icon: bot +--- + +# 核心功能 + +## 助手配置 + +助手是运行时入口，支持提示词、工作流和外部托管三类大脑： + +| 类型 | 用途 | +| --- | --- | +| `prompt` | 用提示词驱动的基础对话，可绑定工具。 | +| `workflow` | 用节点图编排对话流程。 | +| `dify` / `fastgpt` / `opencode` | 将对话处理交给外部 Agent 服务。 | + +其中 `prompt` 和 `workflow` 支持 `pipeline` 与 `realtime`；外部托管 Agent 仅支持 `pipeline`。 + +## 模型与知识库 + +模型资源按具体协议注册，而不是按厂商名称猜测。当前支持 OpenAI 兼容的 LLM、ASR、TTS、Embedding、Realtime，也支持讯飞 ASR/TTS/SuperTTS、StepFun Realtime，以及 Dify、FastGPT、OpenCode Agent。 + +知识库可绑定一个 Embedding 模型资源。助手引用知识库后，需先解绑才能删除该知识库。 + +## 工具与历史 + +- 可复用工具支持结束通话和 HTTP 请求两种类型。 +- HTTP 工具的 URL、请求头、参数和密钥独立管理。 +- 历史记录保留会话、通道、运行模式及消息序列，便于排查对话。 diff --git a/docs/index.mdx b/docs/index.mdx new file mode 100644 index 0000000..849dc52 --- /dev/null +++ b/docs/index.mdx @@ -0,0 +1,26 @@ +--- +title: AI 视频助手 +description: 面向实时语音交互的助手管理与集成平台。 +icon: video +--- + +# AI 视频助手 + +在一个界面中配置模型、知识库、工具和助手，并通过 WebRTC 或 WebSocket 接入实时语音对话。 + + + + 本地启动服务并完成首次助手配置。 + + + 了解模型、外部 Agent 与语音通道的接入方式。 + + + +## 平台组成 + +- **助手**：定义提示词、运行模式、模型绑定及可选工作流。 +- **组件库**：统一维护模型资源、知识库和可复用工具。 +- **语音引擎**：Pipecat 管线支持浏览器 WebRTC 与裸 WebSocket 音频流。 + +> 凭证只保存在模型资源或助手的服务端配置中；接口返回会自动打码。 diff --git a/docs/integrations.mdx b/docs/integrations.mdx new file mode 100644 index 0000000..9ca9987 --- /dev/null +++ b/docs/integrations.mdx @@ -0,0 +1,48 @@ +--- +title: 对接说明 +description: 模型服务、外部 Agent 与实时语音通道的接入方式。 +icon: plug +--- + +# 对接说明 + +## 模型服务 + +优先通过「组件库 / 模型资源」接入。接口定义会动态给出表单字段，凭证写入 `secrets`，普通参数写入 `values`。 + +| 场景 | 推荐接口类型 | +| --- | --- | +| 通用大模型、转写、合成、向量 | `openai-llm`、`openai-asr`、`openai-tts`、`openai-embedding` | +| 端到端实时语音 | `stepfun-realtime` 或 `openai-realtime` | +| 讯飞语音 | `xfyun-asr`、`xfyun-tts`、`xfyun-super-tts` | + +讯飞接入需要将 `appId`、`apiKey`、`apiSecret` 写入 `secrets`，WebSocket 地址及音色等参数写入 `values`。 + +## 外部 Agent + +创建助手时选择 Dify、FastGPT 或 OpenCode： + +- Dify：填写服务地址和 API Key。 +- FastGPT：额外填写应用 ID。 +- OpenCode：填写服务地址、API Key 和可选提示词。 + +外部 Agent 的上下文、知识库和工具由对方服务处理。 + +## 实时语音通道 + +| 通道 | 地址 | 适用场景 | +| --- | --- | --- | +| WebRTC 信令 | `ws(s):///ws/voice` | 浏览器低延迟语音与视频输入。 | +| 裸音频 WebSocket | `ws(s):///ws/stream` | 服务端、话务网关或自定义客户端。 | + +两个通道均使用管理员登录 Cookie 鉴权。推荐仅传 `assistant_id`，让服务端解析模型密钥；`inline_config` 仅用于调试。 + +### WebSocket 音频流启动 + +连接 `/ws/stream` 后，先发送一条文本 JSON，再发送二进制音频帧： + +```json +{"assistant_id":"asst_xxx"} +``` + +WebRTC 在公网环境通常需要 TURN。设置 `TURN_URLS` 和 `TURN_SECRET` 后，可通过 `GET /api/webrtc/ice-servers` 获取浏览器 ICE 配置。 diff --git a/docs/logo-dark.svg b/docs/logo-dark.svg new file mode 100644 index 0000000..e7ec66d --- /dev/null +++ b/docs/logo-dark.svg @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + + + AI视频助手 + diff --git a/docs/logo-light.svg b/docs/logo-light.svg new file mode 100644 index 0000000..a75e7d0 --- /dev/null +++ b/docs/logo-light.svg @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + + + AI视频助手 + diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx new file mode 100644 index 0000000..71dc492 --- /dev/null +++ b/docs/quickstart.mdx @@ -0,0 +1,45 @@ +--- +title: 快速开始 +description: 用 Docker 启动本地开发环境，并创建第一个可语音预览的助手。 +icon: rocket +--- + +# 快速开始 + +## 1. 启动服务 + +在项目根目录执行： + +```bash +docker compose up -d +make db-seed +``` + +首次启动会构建后端镜像。启动后访问： + +- 前端：`http://localhost:3030` +- 后端健康检查：`http://localhost:8000/health` +- 后端接口文档：`http://localhost:8000/docs` + +## 2. 配置模型资源 + +进入「组件库 / 模型资源」，选择协议类型并填写连接信息。OpenAI 兼容服务通常需要： + +- `values.modelId`：模型标识 +- `values.apiUrl`：服务地址 +- `secrets.apiKey`：访问密钥 + +保存前可使用“测试连接”确认可用性。 + +## 3. 创建助手 + +进入「创建助手」，绑定需要的模型资源： + +- **pipeline**：绑定 LLM、ASR、TTS，适合常规语音对话。 +- **realtime**：绑定 Realtime 模型，适合端到端语音交互。 + +保存后，从助手详情页打开语音预览即可测试。 + + +浏览器麦克风仅在 localhost 或 HTTPS 下可用。局域网、远程环境请按仓库中的 `deploy/README.md` 配置 HTTPS 与 TURN。 +