diff --git a/api/Dockerfile b/api/Dockerfile index 020bad5..a531225 100644 --- a/api/Dockerfile +++ b/api/Dockerfile @@ -1,15 +1,17 @@ FROM python:3.12-slim +# Install build tools for C++11 (needed for native extensions, e.g. chromadb) +RUN apt-get update && apt-get install -y --no-install-recommends \ + build-essential \ + && rm -rf /var/lib/apt/lists/* + WORKDIR /app -# 安装依赖 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt -# 复制代码 COPY . . -# 创建数据目录 RUN mkdir -p /app/data EXPOSE 8100 diff --git a/api/requirements.txt b/api/requirements.txt index 173875c..c8e2136 100644 --- a/api/requirements.txt +++ b/api/requirements.txt @@ -1,12 +1,12 @@ -aiosqlite==0.19.0 -fastapi==0.109.0 -uvicorn==0.27.0 -python-multipart==0.0.6 -python-dotenv==1.0.0 -pydantic==2.5.3 -sqlalchemy==2.0.25 -minio==7.2.0 -httpx==0.26.0 -chromadb==0.4.22 -openai==1.12.0 -dashscope==1.25.11 +aiosqlite==0.22.1 +fastapi==0.135.1 +uvicorn==0.41.0 +python-multipart==0.0.22 +python-dotenv==1.2.2 +pydantic==2.11.7 +sqlalchemy==2.0.48 +minio==7.2.20 +httpx==0.28.1 +chromadb==1.5.2 +openai==2.24.0 +dashscope==1.25.13 diff --git a/docker/README.md b/docker/README.md index d7a08b9..90e0a58 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1 +1,78 @@ -# Docker Deployment \ No newline at end of file +# Docker Deployment + +This folder contains Docker Compose configuration to run the entire AI VideoAssistant stack. + +## Services + +| Service | Port | Description | +|---------|------|-------------| +| minio | 9000, 9001 | S3-compatible object storage | +| backend | 8100 | FastAPI backend API | +| engine | 8001 | Conversation engine (WebSocket) | +| frontend | 6000 | React web application | + +## Prerequisites + +1. Docker and Docker Compose installed +2. The `engine/data/vad/silero_vad.onnx` VAD model file must exist +3. Agent configuration in `engine/config/agents/default.yaml` + +## Quick Start + +```bash +cd docker +docker compose up -d +``` + +## Access Points + +- **Frontend**: http://localhost:6000 +- **Backend API**: http://localhost:8100 +- **Engine WebSocket**: ws://localhost:8001/ws +- **MinIO Console**: http://localhost:9001 (admin / password123) + +## Configuration + +### Engine Environment Variables + +The engine service uses environment variables for configuration. Key variables: + +- `BACKEND_URL`: Backend API URL (default: `http://backend:8100`) +- `LOG_LEVEL`: Logging level (default: `INFO`) +- `CORS_ORIGINS`: Allowed CORS origins + +Agent-specific settings (LLM, TTS, ASR) are configured via YAML files in `engine/config/agents/`. + +### Volumes + +- `minio_data`: MinIO storage data +- `backend_data`: Backend SQLite database +- `engine_logs`: Engine log files + +## Development Mode + +To mount source code for hot-reload during development: + +```bash +docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d +``` + +## Logs + +```bash +# View all logs +docker compose logs -f + +# View specific service logs +docker compose logs -f engine +docker compose logs -f backend +``` + +## Stopping + +```bash +docker compose down + +# Remove volumes as well +docker compose down -v +``` diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index 70b0923..5546801 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -1,11 +1,35 @@ -version: '3.8' +# Project name used as prefix for containers, volumes, and networks +name: ras + +# Docker registry mirror for China users (change to empty or "docker.io" if you have direct access) +x-registry-mirror: ®istry-mirror docker.1ms.run services: - # 后端 API + # MinIO (S3 compatible storage) + minio: + image: ${REGISTRY_MIRROR:-docker.1ms.run}/minio/minio + ports: + - "9000:9000" + - "9001:9001" + volumes: + - minio_data:/data + environment: + MINIO_ROOT_USER: admin + MINIO_ROOT_PASSWORD: password123 + command: server /data --console-address ":9001" + healthcheck: + test: ["CMD", "mc", "ready", "local"] + interval: 5s + timeout: 5s + retries: 5 + + # Backend API backend: build: context: ../api dockerfile: Dockerfile + args: + REGISTRY_MIRROR: ${REGISTRY_MIRROR:-docker.1ms.run} ports: - "8100:8100" environment: @@ -15,12 +39,18 @@ services: - MINIO_SECRET_KEY=password123 - MINIO_BUCKET=ai-audio volumes: - - ../api:/app - - ../api/data:/app/data + - backend_data:/app/data depends_on: - - minio + minio: + condition: service_started + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8100/health"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 10s - # 对话引擎 (py-active-call) + # Conversation Engine engine: build: context: ../engine @@ -28,31 +58,64 @@ services: ports: - "8001:8001" environment: + - HOST=0.0.0.0 + - PORT=8001 + - BACKEND_MODE=http - BACKEND_URL=http://backend:8100 + - LOG_LEVEL=INFO + - CORS_ORIGINS=["http://localhost:6000","http://localhost:3000"] + volumes: + - ../engine/config:/app/config:ro + - ../engine/data:/app/data:ro + - engine_logs:/app/logs depends_on: - - backend + backend: + condition: service_started + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8001/health"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 15s - # 前端 (Vite + React) + # Frontend (Vite + React) – production: built static files served on 6000 frontend: build: context: ../web dockerfile: Dockerfile args: - - VITE_API_BASE_URL=http://localhost:8100/api + REGISTRY_MIRROR: ${REGISTRY_MIRROR:-docker.1ms.run} + VITE_API_BASE_URL: ${VITE_API_BASE_URL:-http://localhost:8100/api} + VITE_ENGINE_WS_URL: ${VITE_ENGINE_WS_URL:-ws://localhost:8001/ws} ports: - "6000:6000" depends_on: - backend + - engine - # MinIO (S3 兼容存储) - minio: - image: minio/minio + # Frontend dev – hot reload on port 3000 (run with: docker compose --profile dev up) + frontend-dev: + profiles: + - dev + build: + context: ../web + dockerfile: Dockerfile.dev + args: + REGISTRY_MIRROR: ${REGISTRY_MIRROR:-docker.1ms.run} ports: - - "9000:9000" - - "9001:9001" - volumes: - - ./storage/minio/data:/data + - "3000:3000" environment: - MINIO_ROOT_USER: admin - MINIO_ROOT_PASSWORD: password123 - command: server /data --console-address ":9001" + - VITE_API_BASE_URL=${VITE_API_BASE_URL:-http://localhost:8100/api} + - VITE_ENGINE_WS_URL=${VITE_ENGINE_WS_URL:-ws://localhost:8001/ws} + volumes: + - ../web:/app + - frontend_dev_node_modules:/app/node_modules + depends_on: + - backend + - engine + +volumes: + minio_data: + backend_data: + engine_logs: + frontend_dev_node_modules: diff --git a/docs/README.md b/docs/README.md index 037132f..d3c5455 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,18 @@ # Documentation -部署 MkDocs： -pip install mkdocs -mkdocs serve +**安装依赖（推荐使用 1.x，避免与 Material 主题不兼容）：** -访问 http://localhost:8000 查看文档网站。 \ No newline at end of file +```bash +cd docs +pip install -r requirements.txt +``` + +或手动安装：`pip install "mkdocs>=1.6,<2" mkdocs-material` + +**本地预览：** + +```bash +mkdocs serve +``` + +访问终端中显示的地址（如 http://127.0.0.1:8000）查看文档。 \ No newline at end of file diff --git a/docs/content/changelog.md b/docs/content/changelog.md new file mode 100644 index 0000000..b99bb81 --- /dev/null +++ b/docs/content/changelog.md @@ -0,0 +1,81 @@ +# 更新日志 + +本文档记录 Realtime Agent Studio 的所有重要变更。 + +格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)， +版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 + +--- + +## [未发布] + +### 开发中 + +- 工作流可视化编辑器 +- 知识库 RAG 集成 +- JavaScript/Python SDK +- Step Audio 多模态模型支持 + +--- + +## [0.1.0] - 2025-01-15 + +### 新增 + +#### 实时交互引擎 + +- **管线式全双工引擎** - ASR → LLM → TTS 流水线架构 +- **智能打断** - 支持 VAD 和 EOU 检测 +- **OpenAI 兼容接口** - 支持 OpenAI Compatible 的 ASR/TTS 服务 +- **DashScope TTS** - 阿里云语音合成服务适配 + +#### 智能体配置 + +- **系统提示词** - 支持角色定义和动态变量 `{{variable}}` +- **模型管理** - LLM/ASR/TTS 模型统一管理界面 +- **工具调用** - Webhook 工具和客户端工具配置 + +#### 交互测试 + +- **实时调试控制台** - 内置 WebSocket 调试工具 + +#### 开放接口 + +- **WebSocket 协议** - `/ws` 端点，支持二进制音频流 +- **RESTful API** - 完整的助手/模型/会话 CRUD 接口 + +#### 历史监控 + +- **会话回放** - 音频 + 转写 + LLM 响应完整记录 +- **会话筛选** - 按时间、助手、状态多维度检索 + +#### 部署 + +- **Docker 支持** - 提供 docker-compose 一键部署 + +### 技术栈 + +- 前端：React 18, TypeScript, Tailwind CSS, Zustand +- 后端：FastAPI (Python 3.10+) +- 数据库：SQLite（开发）/ PostgreSQL（生产） + +--- + +## 版本规划 + +| 版本 | 计划发布 | 主要特性 | +|------|---------|---------| +| 0.2.0 | 2025 Q1 | 工作流编辑器、知识库集成 | +| 0.3.0 | 2025 Q2 | SDK 发布、多模态模型 | +| 1.0.0 | 2025 H2 | 生产就绪、企业特性 | + +--- + +## 贡献者 + +感谢所有为 RAS 做出贡献的开发者！ + +--- + +[未发布]: https://github.com/your-org/AI-VideoAssistant/compare/v0.1.0...HEAD +[0.1.0]: https://github.com/your-org/AI-VideoAssistant/releases/tag/v0.1.0 diff --git a/docs/content/concepts/assistants.md b/docs/content/concepts/assistants.md new file mode 100644 index 0000000..f22c4c8 --- /dev/null +++ b/docs/content/concepts/assistants.md @@ -0,0 +1,253 @@ +# 助手概念详解 + +深入了解助手（Assistant）的设计理念和配置细节。 + +--- + +## 什么是助手？ + +**助手**是 RAS 中的核心实体，代表一个具有特定角色、能力和行为的 AI 对话智能体。每个助手都是独立配置的，可以服务于不同的业务场景。 + +### 助手的组成 + +```mermaid +flowchart TB + subgraph Assistant["助手"] + Identity[身份定义] + Models[模型配置] + Capabilities[能力扩展] + Behavior[行为控制] + end + + subgraph Identity + Name[名称] + Prompt[系统提示词] + Language[语言] + end + + subgraph Models + LLM[LLM 模型] + ASR[ASR 模型] + TTS[TTS 声音] + end + + subgraph Capabilities + Tools[工具调用] + KB[知识库] + end + + subgraph Behavior + Greeting[开场白] + Interruption[打断设置] + Output[输出模式] + end +``` + +--- + +## 身份定义 + +### 系统提示词 + +系统提示词是助手最重要的配置，它定义了： + +| 要素 | 说明 | 示例 | +|------|------|------| +| **角色** | 助手扮演什么身份 | "你是一名专业的医疗咨询顾问" | +| **能力** | 助手能做什么 | "你可以回答健康问题，但不能开具处方" | +| **限制** | 助手不能做什么 | "不要讨论政治话题" | +| **风格** | 回复的语气和格式 | "保持友好专业，回答简洁" | + +### 提示词模板 + +```markdown +## 角色 +你是{{company}}的智能客服助手"小智"。 + +## 任务 +- 回答用户关于产品和服务的问题 +- 协助处理订单查询和售后问题 +- 收集用户反馈 + +## 限制 +- 不讨论竞争对手产品 +- 不承诺超出权限的优惠 +- 遇到复杂问题引导用户联系人工客服 + +## 风格 +- 语气友好亲切 +- 回答简洁明了，每次 2-3 句话 +- 适当使用语气词使对话更自然 +``` + +--- + +## 模型配置 + +### LLM 模型 + +大语言模型是助手的"大脑"，负责理解用户意图和生成回复。 + +| 参数 | 说明 | 建议值 | +|------|------|--------| +| **温度** | 回复随机性，越高越发散 | 0.7 (对话) / 0.3 (问答) | +| **最大 Token** | 单次回复长度上限 | 256-512 | +| **上下文长度** | 记忆的对话轮数 | 10-20 轮 | + +### ASR 模型 + +语音识别模型将用户语音转为文字。 + +| 配置 | 说明 | +|------|------| +| **语言** | 识别语言，如中文、英文 | +| **热词** | 提高特定词汇识别率 | +| **标点** | 是否自动添加标点 | + +### TTS 声音 + +语音合成将助手回复转为语音输出。 + +| 配置 | 说明 | +|------|------| +| **音色** | 选择声音角色 | +| **语速** | 说话速度，0.5-2.0 | +| **音调** | 声音高低 | + +--- + +## 能力扩展 + +### 工具调用 + +通过工具让助手能够执行外部操作： + +```mermaid +flowchart LR + User[用户] -->|"查询订单"| Assistant[助手] + Assistant -->|调用工具| API[订单 API] + API -->|返回数据| Assistant + Assistant -->|回复| User +``` + +**工具定义示例：** + +```json +{ + "name": "get_order_status", + "description": "查询用户订单状态", + "parameters": { + "type": "object", + "properties": { + "order_id": { + "type": "string", + "description": "订单编号" + } + }, + "required": ["order_id"] + } +} +``` + +### 知识库关联 + +让助手基于私有文档回答问题： + +```mermaid +flowchart LR + Question[用户问题] --> Search[知识检索] + Search --> KB[(知识库)] + KB --> Context[相关内容] + Context --> LLM[LLM] + LLM --> Answer[回答] +``` + +--- + +## 行为控制 + +### 开场白设置 + +| 模式 | 说明 | +|------|------| +| **助手先说** | 连接后助手主动问候 | +| **用户先说** | 等待用户开口 | +| **静默** | 不自动开场 | + +### 打断设置 + +| 选项 | 说明 | +|------|------| +| **允许打断** | 用户可随时插话 | +| **禁止打断** | 助手说完才能输入 | +| **灵敏度** | 打断触发的敏感程度 | + +### 输出模式 + +| 模式 | 说明 | +|------|------| +| **语音** | TTS 语音输出 | +| **文本** | 纯文本输出 | +| **混合** | 同时输出语音和文本 | + +--- + +## 助手版本管理 + +### 草稿与发布 + +```mermaid +gitGraph + commit id: "创建助手" + commit id: "配置提示词" + commit id: "添加工具" + branch published + checkout published + commit id: "发布 v1" + checkout main + commit id: "修改提示词" + commit id: "调整参数" + checkout published + merge main id: "发布 v2" +``` + +- **草稿**: 可随时修改，仅供测试 +- **发布**: 正式上线，用于生产环境 + +### 配置导入导出 + +支持以 JSON 格式导入导出助手配置，便于： + +- 备份和恢复 +- 跨环境迁移 +- 团队共享模板 + +--- + +## 最佳实践 + +### 1. 提示词工程 + +- **明确角色**: 清晰定义助手身份 +- **设定边界**: 明确能做什么、不能做什么 +- **控制长度**: 语音场景下回复要简短 + +### 2. 模型选择 + +- **平衡成本与效果**: 不一定需要最强模型 +- **测试不同供应商**: 找到最适合场景的组合 +- **考虑延迟**: 语音交互对延迟敏感 + +### 3. 工具设计 + +- **单一职责**: 每个工具做一件事 +- **清晰描述**: 让 LLM 正确理解何时调用 +- **错误处理**: 工具失败时优雅降级 + +--- + +## 相关文档 + +- [助手配置](../assistants/configuration.md) - 配置界面详解 +- [提示词指南](../assistants/prompts.md) - 编写高质量提示词 +- [工具集成](../customization/tools.md) - 工具配置详情 diff --git a/docs/content/concepts/engines.md b/docs/content/concepts/engines.md new file mode 100644 index 0000000..925a721 --- /dev/null +++ b/docs/content/concepts/engines.md @@ -0,0 +1,323 @@ +# 引擎架构详解 + +深入了解 RAS 的两种引擎架构：管线式引擎和多模态引擎。 + +--- + +## 引擎概述 + +引擎是 RAS 的核心，负责处理实时语音交互。根据不同需求，可以选择两种架构： + +| 架构 | 特点 | 适用场景 | +|------|------|---------| +| **管线式** | 灵活、可定制、成本可控 | 大多数场景 | +| **多模态** | 低延迟、自然、简单 | 高端体验场景 | + +--- + +## 管线式引擎 (Pipeline) + +### 架构设计 + +管线式引擎将语音交互拆分为三个独立阶段： + +```mermaid +flowchart LR + subgraph Input["输入处理"] + Audio[用户音频] --> VAD[VAD 检测] + VAD --> ASR[语音识别] + ASR --> Text[转写文本] + end + + subgraph Process["语义处理"] + Text --> LLM[大语言模型] + LLM --> Response[回复文本] + end + + subgraph Output["输出生成"] + Response --> TTS[语音合成] + TTS --> OutputAudio[助手音频] + end +``` + +### 数据流详解 + +```mermaid +sequenceDiagram + participant U as 用户 + participant E as 引擎 + participant ASR as ASR 服务 + participant LLM as LLM 服务 + participant TTS as TTS 服务 + + U->>E: 音频帧 (PCM 16kHz) + + Note over E: VAD 检测语音活动 + E->>E: 累积音频缓冲 + + Note over E: 检测到语音结束 (EOU) + E->>ASR: 发送音频 + ASR-->>E: 转写文本 (流式) + E-->>U: transcript.delta + E-->>U: transcript.final + + E->>LLM: 发送对话历史 + 用户输入 + LLM-->>E: 回复文本 (流式) + E-->>U: assistant.response.delta + + loop 流式合成 + E->>TTS: 文本片段 + TTS-->>E: 音频片段 + E-->>U: 音频帧 + end + + E-->>U: assistant.response.final +``` + +### 延迟分析 + +管线式引擎的延迟由各环节累加： + +| 环节 | 典型延迟 | 优化方向 | +|------|---------|---------| +| VAD/EOU | 200-500ms | 调整灵敏度 | +| ASR | 100-300ms | 选择快速模型 | +| LLM TTFT | 200-500ms | 选择低延迟模型 | +| TTS | 100-200ms | 流式合成 | +| **总计** | **600-1500ms** | - | + +### 流式优化 + +为降低感知延迟，采用流式处理： + +```mermaid +gantt + title 非流式 vs 流式处理 + dateFormat X + axisFormat %s + + section 非流式 + ASR完成 :a1, 0, 300ms + LLM完成 :a2, after a1, 800ms + TTS完成 :a3, after a2, 500ms + 播放 :a4, after a3, 500ms + + section 流式 + ASR :b1, 0, 300ms + LLM开始 :b2, after b1, 200ms + TTS开始 :b3, after b2, 100ms + 边生成边播放 :b4, after b3, 600ms +``` + +--- + +## 多模态引擎 (Multimodal) + +### 架构设计 + +多模态引擎使用端到端模型，直接处理音频输入输出： + +```mermaid +flowchart LR + subgraph Client["客户端"] + Mic[麦克风] --> AudioIn[音频输入] + AudioOut[音频输出] --> Speaker[扬声器] + end + + subgraph Engine["引擎"] + AudioIn --> RT[Realtime Model] + RT --> AudioOut + end + + subgraph Model["多模态模型"] + RT --> GPT4o[GPT-4o Realtime] + RT --> Gemini[Gemini Live] + RT --> Step[Step Audio] + end +``` + +### 数据流详解 + +```mermaid +sequenceDiagram + participant U as 用户 + participant E as 引擎 + participant RT as Realtime Model + + U->>E: 音频帧 + E->>RT: 转发音频 + + Note over RT: 端到端处理 + + RT-->>E: 音频响应 (流式) + E-->>U: 播放音频 + + Note over U,RT: 支持全双工
用户可随时打断 +``` + +### 支持的模型 + +| 模型 | 供应商 | 特点 | +|------|--------|------| +| **GPT-4o Realtime** | OpenAI | 最自然的语音，延迟极低 | +| **Gemini Live** | Google | 多模态能力强 | +| **Step Audio** | 阶跃星辰 | 国内可用，中文优化 | + +### 延迟对比 + +```mermaid +xychart-beta + title "端到端延迟对比" + x-axis ["管线式 (普通)", "管线式 (优化)", "多模态"] + y-axis "延迟 (ms)" 0 --> 1500 + bar [1200, 700, 300] +``` + +--- + +## 智能打断机制 + +两种引擎都支持智能打断，但实现方式不同。 + +### 管线式引擎打断 + +```mermaid +sequenceDiagram + participant U as 用户 + participant E as 引擎 + participant TTS as TTS + + Note over E,TTS: TTS 正在合成播放 + E->>U: 音频帧... + + U->>E: 用户说话 (检测到 VAD) + E->>E: 判断是否有效打断 + + alt 有效打断 + E->>TTS: 停止合成 + E->>E: 清空音频缓冲 + E-->>U: output.audio.interrupted + Note over E: 处理新输入 + else 噪音/误触发 + Note over E: 继续播放 + end +``` + +### 多模态引擎打断 + +多模态模型原生支持全双工，打断由模型内部处理： + +```mermaid +sequenceDiagram + participant U as 用户 + participant E as 引擎 + participant RT as Realtime Model + + Note over RT: 模型正在输出 + RT-->>E: 音频流... + E-->>U: 播放 + + U->>E: 用户说话 + E->>RT: 转发用户音频 + + Note over RT: 模型检测到打断
自动停止输出 + + RT-->>E: 新的响应 + E-->>U: 播放新响应 +``` + +--- + +## 引擎选择指南 + +### 决策流程 + +```mermaid +flowchart TD + Start[选择引擎] --> Q1{延迟要求?} + + Q1 -->|< 500ms| Q2{预算充足?} + Q1 -->|> 500ms 可接受| Pipeline[管线式引擎] + + Q2 -->|是| Q3{模型可用?} + Q2 -->|否| Pipeline + + Q3 -->|GPT-4o/Gemini 可用| Multimodal[多模态引擎] + Q3 -->|国内环境受限| Q4{Step Audio?} + + Q4 -->|可用| Multimodal + Q4 -->|不可用| Pipeline +``` + +### 场景推荐 + +| 场景 | 推荐引擎 | 理由 | +|------|---------|------| +| **企业客服** | 管线式 | 成本可控，可定制 ASR | +| **高端虚拟人** | 多模态 | 最自然的交互体验 | +| **电话机器人** | 管线式 | 可对接电信 ASR | +| **语音助手** | 多模态 | 低延迟，自然对话 | +| **口语练习** | 管线式 | 需要精确的 ASR 评分 | + +### 混合方案 + +也可以根据用户等级使用不同引擎： + +```mermaid +flowchart LR + User[用户请求] --> Router{路由判断} + + Router -->|VIP 用户| Multimodal[多模态引擎] + Router -->|普通用户| Pipeline[管线式引擎] + + Multimodal --> Response[响应] + Pipeline --> Response +``` + +--- + +## 配置示例 + +### 管线式引擎配置 + +```json +{ + "engine": "pipeline", + "asr": { + "provider": "openai-compatible", + "model": "FunAudioLLM/SenseVoiceSmall", + "language": "zh" + }, + "llm": { + "provider": "openai", + "model": "gpt-4o-mini", + "temperature": 0.7 + }, + "tts": { + "provider": "openai-compatible", + "model": "FunAudioLLM/CosyVoice2-0.5B", + "voice": "anna" + } +} +``` + +### 多模态引擎配置 + +```json +{ + "engine": "multimodal", + "model": { + "provider": "openai", + "model": "gpt-4o-realtime-preview", + "voice": "alloy" + } +} +``` + +--- + +## 相关文档 + +- [系统架构](../overview/architecture.md) - 整体架构设计 +- [WebSocket 协议](../api-reference/websocket.md) - 协议详情 +- [部署指南](../deployment/index.md) - 引擎部署配置 diff --git a/docs/content/concepts/index.md b/docs/content/concepts/index.md new file mode 100644 index 0000000..63d257d --- /dev/null +++ b/docs/content/concepts/index.md @@ -0,0 +1,284 @@ +# 核心概念 + +本章节介绍 Realtime Agent Studio 中的核心概念，帮助你更好地理解和使用平台。 + +--- + +## 概念总览 + +```mermaid +flowchart TB + subgraph Platform["RAS 平台"] + Assistant[助手 Assistant] + + subgraph Resources["资源库"] + LLM[LLM 模型] + ASR[ASR 模型] + TTS[TTS 声音] + KB[知识库] + end + + subgraph Engine["交互引擎"] + Pipeline[管线式引擎] + Multimodal[多模态引擎] + end + + Session[会话 Session] + end + + Assistant --> LLM + Assistant --> ASR + Assistant --> TTS + Assistant --> KB + Assistant --> Engine + Engine --> Session +``` + +--- + +## 助手 (Assistant) + +**助手**是 RAS 的核心实体，代表一个可对话的 AI 智能体。 + +### 助手配置 + +每个助手包含以下配置： + +| 配置项 | 说明 | +|-------|------| +| **名称** | 助手的显示名称 | +| **系统提示词** | 定义助手角色、行为、限制 | +| **LLM 模型** | 选择用于生成回复的大语言模型 | +| **ASR 模型** | 选择用于语音识别的模型 | +| **TTS 声音** | 选择用于语音合成的音色 | +| **工具** | 配置助手可调用的外部工具 | +| **知识库** | 关联的知识库（用于 RAG） | + +### 助手生命周期 + +```mermaid +stateDiagram-v2 + [*] --> Draft: 创建 + Draft --> Draft: 编辑配置 + Draft --> Published: 发布 + Published --> Draft: 取消发布 + Published --> Published: 更新配置 + Published --> [*]: 删除 +``` + +--- + +## 会话 (Session) + +**会话**代表一次完整的对话交互，从用户连接到断开。 + +### 会话状态 + +```mermaid +stateDiagram-v2 + [*] --> Connecting: WebSocket 连接 + Connecting --> Started: session.started + Started --> Active: 对话中 + Active --> Active: 多轮对话 + Active --> Stopped: session.stop + Stopped --> [*]: 连接关闭 +``` + +### 会话数据 + +每个会话记录包含： + +- **基本信息** - ID、时长、时间戳 +- **音频数据** - 用户和助手的音频记录 +- **转写文本** - ASR 识别结果 +- **LLM 交互** - 输入输出和工具调用 +- **元数据** - 渠道、来源、自定义变量 + +--- + +## 管线式引擎 vs 多模态引擎 + +RAS 支持两种引擎架构，适用于不同场景。 + +### 管线式引擎 (Pipeline) + +将语音交互拆分为三个独立环节： + +``` +用户语音 → [ASR] → 文本 → [LLM] → 回复 → [TTS] → 助手语音 +``` + +**优点：** + +- 灵活选择各环节供应商 +- 可独立优化每个环节 +- 成本可控 + +**缺点：** + +- 延迟较高（累加延迟） +- 需要协调多个服务 + +### 多模态引擎 (Multimodal) + +使用端到端模型直接处理： + +``` +用户语音 → [Realtime Model] → 助手语音 +``` + +**优点：** + +- 更低延迟 +- 更自然的语音 +- 架构简单 + +**缺点：** + +- 依赖特定供应商 +- 成本较高 +- 可定制性有限 + +### 选择建议 + +| 场景 | 推荐引擎 | +|------|---------| +| 成本敏感 | 管线式 | +| 延迟敏感 | 多模态 | +| 需要特定 ASR/TTS | 管线式 | +| 追求最自然体验 | 多模态 | + +--- + +## 智能打断 (Barge-in) + +**智能打断**是指用户在助手说话时可以随时插话，系统能够： + +1. 检测用户开始说话 +2. 立即停止 TTS 播放 +3. 处理用户新的输入 + +### 打断检测方式 + +| 方式 | 说明 | +|------|------| +| **VAD** | Voice Activity Detection，检测到声音活动即打断 | +| **语义** | 基于语音内容判断是否有意义的打断 | +| **混合** | VAD + 语义结合，减少误触发 | + +### 打断流程 + +```mermaid +sequenceDiagram + participant User as 用户 + participant Engine as 引擎 + participant TTS as TTS + + Note over Engine,TTS: 助手正在播放回复 + Engine->>User: 音频流... + User->>Engine: 开始说话 (VAD 触发) + Engine->>Engine: 打断判断 + Engine->>TTS: 停止合成 + Engine->>User: output.audio.interrupted + Note over Engine: 处理新输入 +``` + +--- + +## 工具调用 (Tool Calling) + +助手可以通过**工具**扩展能力，访问外部系统或执行特定操作。 + +### 工具类型 + +| 类型 | 说明 | 示例 | +|------|------|------| +| **Webhook** | 调用外部 HTTP API | 查询订单、预约日程 | +| **客户端** | 由客户端执行的操作 | 打开页面、显示表单 | +| **内置** | 平台提供的工具 | 代码执行、计算器 | + +### 工具调用流程 + +```mermaid +sequenceDiagram + participant User as 用户 + participant LLM as LLM + participant Tool as 工具 + + User->>LLM: "帮我查一下订单状态" + LLM->>LLM: 决定调用工具 + LLM->>Tool: get_order_status(order_id) + Tool-->>LLM: {status: "已发货"} + LLM->>User: "您的订单已发货" +``` + +--- + +## 知识库 (Knowledge Base) + +**知识库**让助手能够基于私有文档回答问题，实现 RAG（检索增强生成）。 + +### 工作原理 + +```mermaid +flowchart LR + subgraph Indexing["索引阶段"] + Doc[文档] --> Chunk[分块] + Chunk --> Embed[向量化] + Embed --> Store[(向量数据库)] + end + + subgraph Query["查询阶段"] + Q[用户问题] --> QEmbed[问题向量化] + QEmbed --> Search[相似度搜索] + Store --> Search + Search --> Context[相关上下文] + Context --> LLM[LLM 生成回答] + end +``` + +### 支持的文档格式 + +- PDF +- Word (.docx) +- Markdown +- 纯文本 +- HTML + +--- + +## 动态变量 + +**动态变量**允许在运行时向助手注入上下文信息。 + +### 使用方式 + +在系统提示词中使用 `{{variable}}` 占位符： + +``` +你是{{company_name}}的客服助手。 +当前用户是{{customer_name}}，会员等级为{{tier}}。 +``` + +连接时通过 `dynamicVariables` 传入： + +```json +{ + "type": "session.start", + "metadata": { + "dynamicVariables": { + "company_name": "ABC 公司", + "customer_name": "张三", + "tier": "VIP" + } + } +} +``` + +--- + +## 下一步 + +- [快速开始](../quickstart/index.md) - 创建第一个助手 +- [助手配置](../assistants/configuration.md) - 详细配置说明 +- [WebSocket 协议](../api-reference/websocket.md) - API 接口详情 diff --git a/docs/content/deployment/index.md b/docs/content/deployment/index.md index 9342b33..681ed16 100644 --- a/docs/content/deployment/index.md +++ b/docs/content/deployment/index.md @@ -1,13 +1,12 @@ -# 部署指南 +# 部署概览 -本章节介绍如何将 Realtime Agent Studio (RAS) 部署到生产环境。 +本章节介绍如何使用 Docker 部署 Realtime Agent Studio (RAS)。 ## 部署方式 | 方式 | 适用场景 | 复杂度 | |------|---------|--------| -| [Docker 部署](docker.md) | 快速部署、容器化环境 | 简单 | -| [生产环境](production.md) | Nginx 反向代理、高可用 | 中等 | +| [Docker 部署](docker.md) | 快速启动、容器化运行 | 简单 | ## 快速开始 @@ -20,7 +19,7 @@ docker run -d -p 3000:80 --name ai-assistant-web ai-video-assistant-web ### 验证部署 -1. 访问 http://your-domain.com +1. 访问 http://localhost:3000 2. 检查页面是否正常加载 3. 验证各功能模块是否可用 diff --git a/docs/content/deployment/production.md b/docs/content/deployment/production.md deleted file mode 100644 index a105d9d..0000000 --- a/docs/content/deployment/production.md +++ /dev/null @@ -1,191 +0,0 @@ -# 生产环境部署 - -本文档介绍如何将 Realtime Agent Studio (RAS) 部署到生产环境，包括 Nginx 配置、SSL 证书、性能优化等。 - -## Nginx 部署 - -### 1. 构建前端 - -```bash -cd web -npm run build -``` - -### 2. 部署静态文件 - -```bash -sudo mkdir -p /var/www/ai-assistant -sudo cp -r dist/* /var/www/ai-assistant/ -``` - -### 3. 配置 Nginx - -创建 `/etc/nginx/sites-available/ai-assistant`： - -```nginx -server { - listen 80; - server_name your-domain.com; - root /var/www/ai-assistant; - index index.html; - - # Gzip 压缩 - gzip on; - gzip_types text/plain text/css application/json application/javascript; - - # 静态文件缓存 - location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { - expires 30d; - add_header Cache-Control "public, immutable"; - } - - # SPA 路由支持 - location / { - try_files $uri $uri/ /index.html; - } - - # API 反向代理 - location /api { - proxy_pass http://localhost:8080; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - } - - # WebSocket 代理 - location /ws { - proxy_pass http://localhost:8000; - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_set_header Host $host; - proxy_read_timeout 86400; - } -} -``` - -### 4. 启用站点 - -```bash -sudo ln -s /etc/nginx/sites-available/ai-assistant /etc/nginx/sites-enabled/ -sudo nginx -t -sudo systemctl reload nginx -``` - -## SSL 证书配置 - -### 使用 Let's Encrypt - -```bash -# 安装 certbot -sudo apt install certbot python3-certbot-nginx - -# 申请证书 -sudo certbot --nginx -d your-domain.com - -# 自动续期 -sudo certbot renew --dry-run -``` - -### HTTPS 配置 - -```nginx -server { - listen 443 ssl http2; - server_name your-domain.com; - - ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; - ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; - - # SSL 安全配置 - ssl_protocols TLSv1.2 TLSv1.3; - ssl_prefer_server_ciphers on; - ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256; - - # HSTS - add_header Strict-Transport-Security "max-age=31536000" always; - - # ... 其他配置同上 -} - -# HTTP 重定向到 HTTPS -server { - listen 80; - server_name your-domain.com; - return 301 https://$server_name$request_uri; -} -``` - -## 性能优化 - -### Nginx 优化 - -```nginx -# 在 http 块中添加 -worker_processes auto; -worker_connections 1024; - -# 开启 sendfile -sendfile on; -tcp_nopush on; -tcp_nodelay on; - -# 缓冲区设置 -client_body_buffer_size 10K; -client_header_buffer_size 1k; -client_max_body_size 8m; -``` - -### 静态资源 CDN - -如果使用 CDN，修改构建配置： - -```env -# .env.production -VITE_CDN_URL=https://cdn.your-domain.com -``` - -## 监控与日志 - -### 访问日志 - -```nginx -access_log /var/log/nginx/ai-assistant.access.log; -error_log /var/log/nginx/ai-assistant.error.log; -``` - -### 日志轮转 - -```bash -# /etc/logrotate.d/nginx -/var/log/nginx/*.log { - daily - rotate 14 - compress - delaycompress - missingok - notifempty -} -``` - -## 备份策略 - -### 数据库备份 - -```bash -# PostgreSQL 备份 -pg_dump -U postgres ai_assistant > backup_$(date +%Y%m%d).sql - -# 定时备份（crontab） -0 2 * * * pg_dump -U postgres ai_assistant > /backups/backup_$(date +\%Y\%m\%d).sql -``` - -## 高可用部署 - -对于高可用需求，建议： - -1. **负载均衡** - 使用 Nginx upstream 或云负载均衡 -2. **数据库主从** - PostgreSQL 主从复制 -3. **Redis 集群** - 会话和缓存高可用 -4. **健康检查** - 定期检测服务状态 diff --git a/docs/content/getting-started/configuration.md b/docs/content/getting-started/configuration.md index 2dd1763..14c2e84 100644 --- a/docs/content/getting-started/configuration.md +++ b/docs/content/getting-started/configuration.md @@ -1,83 +1,278 @@ # 配置说明 -## 环境变量 +本页面介绍 Realtime Agent Studio 各组件的配置方法。 -在项目根目录或 `web` 目录下创建 `.env` 文件： +--- + +## 配置概览 + +RAS 采用分层配置，各组件独立配置： + +```mermaid +flowchart TB + subgraph Config["配置层级"] + ENV[环境变量] + File[配置文件] + DB[数据库配置] + end + + subgraph Services["服务组件"] + Web[Web 前端] + API[API 服务] + Engine[Engine 服务] + end + + ENV --> Web + ENV --> API + ENV --> Engine + File --> API + File --> Engine + DB --> API +``` + +--- + +## Web 前端配置 + +### 环境变量 + +在 `web/` 目录创建 `.env` 文件： ```env -# API 服务地址 +# API 服务地址（必填） VITE_API_URL=http://localhost:8080 -# Gemini API Key（可选） -VITE_GEMINI_API_KEY=your_api_key_here +# Engine WebSocket 地址（可选，默认同 API 服务器） +VITE_WS_URL=ws://localhost:8000 + +# Google Gemini API Key（可选，用于前端直连） +VITE_GEMINI_API_KEY=your_api_key ``` -## 变量说明 +### 变量说明 | 变量 | 必填 | 说明 | 默认值 | -|------|------|------|--------| -| `VITE_API_URL` | 是 | 后端 API 服务地址 | http://localhost:8080 | -| `VITE_GEMINI_API_KEY` | 否 | Google Gemini API 密钥 | - | +|------|:----:|------|--------| +| `VITE_API_URL` | ✅ | 后端 API 服务地址 | - | +| `VITE_WS_URL` | ❌ | WebSocket 服务地址 | 从 API URL 推断 | +| `VITE_GEMINI_API_KEY` | ❌ | Gemini API 密钥 | - | -## 后端服务配置 - -后端服务使用独立的配置文件，位于 `api/config/` 目录： - -### 数据库配置 - -```yaml -database: - host: localhost - port: 5432 - name: ai_assistant - user: postgres - password: your_password -``` - -### Redis 配置 - -```yaml -redis: - host: localhost - port: 6379 - db: 0 -``` - -## Engine 服务配置 - -Engine 服务配置位于 `engine/config/` 目录： - -### 助手默认配置 - -参考 `engine/config/agents/default.yaml`： - -```yaml -agent: - name: "默认助手" - language: "zh-CN" - temperature: 0.7 - max_tokens: 2048 -``` - -## 多环境配置 - -### 开发环境 +### 开发环境配置 ```env # .env.development VITE_API_URL=http://localhost:8080 +VITE_WS_URL=ws://localhost:8000 ``` -### 生产环境 +--- + +## API 服务配置 + +### 环境变量 ```env -# .env.production -VITE_API_URL=https://api.your-domain.com +# 数据库配置 +DATABASE_URL=sqlite:///./data/app.db +# 或 PostgreSQL +# DATABASE_URL=postgresql://user:pass@localhost:5432/ras + +# Redis 配置（可选） +REDIS_URL=redis://localhost:6379/0 + +# 安全配置 +SECRET_KEY=your-secret-key-at-least-32-chars +CORS_ORIGINS=http://localhost:3000,https://your-domain.com + +# 日志级别 +LOG_LEVEL=INFO + +# 文件存储路径 +UPLOAD_DIR=./uploads ``` +### 配置文件 + +API 服务支持 YAML 配置文件 `api/config/settings.yaml`： + +```yaml +# 服务配置 +server: + host: "0.0.0.0" + port: 8080 + workers: 4 + +# 数据库配置 +database: + url: "sqlite:///./data/app.db" + pool_size: 5 + max_overflow: 10 + +# Redis 配置 +redis: + url: "redis://localhost:6379/0" + +# 安全配置 +security: + secret_key: "your-secret-key" + token_expire_minutes: 1440 + +# 日志配置 +logging: + level: "INFO" + format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s" +``` + +--- + +## Engine 服务配置 + +### 环境变量 + +```env +# 后端 API 地址 +BACKEND_URL=http://localhost:8080 + +# WebSocket 服务配置 +WS_HOST=0.0.0.0 +WS_PORT=8000 + +# 音频配置 +AUDIO_SAMPLE_RATE=16000 +AUDIO_CHANNELS=1 + +# 日志级别 +LOG_LEVEL=INFO +``` + +### 引擎配置 + +Engine 配置文件 `engine/config/engine.yaml`： + +```yaml +# WebSocket 服务 +websocket: + host: "0.0.0.0" + port: 8000 + ping_interval: 30 + ping_timeout: 10 + +# 音频处理 +audio: + sample_rate: 16000 + channels: 1 + chunk_size: 640 # 20ms at 16kHz + +# VAD 配置 +vad: + enabled: true + threshold: 0.5 + min_speech_duration: 0.25 + min_silence_duration: 0.5 + +# 引擎默认配置 +defaults: + engine_type: "pipeline" # pipeline 或 multimodal + max_response_tokens: 512 + temperature: 0.7 +``` + +--- + +## Docker 配置 + +### docker-compose.yml 环境变量 + +```yaml +version: '3.8' + +services: + web: + environment: + - VITE_API_URL=http://api:8080 + + api: + environment: + - DATABASE_URL=postgresql://postgres:password@db:5432/ras + - REDIS_URL=redis://redis:6379/0 + - SECRET_KEY=${SECRET_KEY} + + engine: + environment: + - BACKEND_URL=http://api:8080 + - LOG_LEVEL=INFO +``` + +### 使用 .env 文件 + +在项目根目录创建 `.env`： + +```env +# Docker Compose 会自动加载 +SECRET_KEY=your-secret-key-at-least-32-chars +POSTGRES_PASSWORD=secure-db-password +``` + +--- + ## 配置优先级 -1. 命令行参数 +配置按以下优先级加载（高优先级覆盖低优先级）： + +``` +1. 命令行参数（最高） 2. 环境变量 -3. `.env` 文件 -4. 默认值 +3. .env 文件 +4. 配置文件 (yaml) +5. 代码默认值（最低） +``` + +--- + +## 敏感配置管理 + +!!! danger "安全提醒" + 不要将敏感信息提交到代码仓库！ + +### 推荐做法 + +1. **使用 .env 文件**，并将其加入 `.gitignore` +2. **使用环境变量**，通过 CI/CD 注入 +3. **使用密钥管理服务**，如 AWS Secrets Manager、HashiCorp Vault + +### .gitignore 配置 + +```gitignore +# 环境配置文件 +.env +.env.local +.env.*.local + +# 敏感数据目录 +/secrets/ +*.pem +*.key +``` + +--- + +## 配置验证 + +启动服务前验证配置是否正确： + +```bash +# 验证 API 服务配置 +cd api +python -c "from app.config import settings; print(settings)" + +# 验证 Engine 配置 +cd engine +python -c "from config import settings; print(settings)" +``` + +--- + +## 下一步 + +- [安装部署](index.md) - 开始安装服务 +- [Docker 部署](../deployment/docker.md) - 容器化部署 diff --git a/docs/content/getting-started/index.md b/docs/content/getting-started/index.md index ffc496c..6363418 100644 --- a/docs/content/getting-started/index.md +++ b/docs/content/getting-started/index.md @@ -2,54 +2,189 @@ 本章节介绍如何安装和配置 Realtime Agent Studio (RAS) 开发环境。 -## 概述 +--- -Realtime Agent Studio (RAS) 由以下组件构成： +## 系统组件 -| 组件 | 说明 | -|------|------| -| **Web 前端** | React + TypeScript 构建的管理界面 | -| **API 服务** | Python FastAPI 后端服务 | -| **Engine 服务** | 实时对话引擎（WebSocket） | +RAS 由三个核心服务组成： -## 安装步骤 +```mermaid +flowchart LR + subgraph Services["服务组件"] + Web[Web 前端
React + TypeScript] + API[API 服务
FastAPI] + Engine[Engine 服务
WebSocket] + end -### 1. 克隆项目 + subgraph Storage["数据存储"] + DB[(SQLite/PostgreSQL)] + end + + Web -->|REST| API + Web -->|WebSocket| Engine + API <--> DB + Engine <--> API +``` + +| 组件 | 端口 | 说明 | +|------|------|------| +| **Web 前端** | 3000 | React + TypeScript 管理控制台 | +| **API 服务** | 8080 | Python FastAPI 后端 | +| **Engine 服务** | 8000 | 实时对话引擎（WebSocket） | + +--- + +## 快速安装 + +### 方式一：Docker Compose（推荐） + +最快捷的启动方式，适合快速体验和生产部署。 ```bash -git clone https://github.com/your-repo/AI-VideoAssistant.git +# 1. 克隆项目 +git clone https://github.com/your-org/AI-VideoAssistant.git +cd AI-VideoAssistant + +# 2. 启动服务 +docker-compose up -d + +# 3. 访问控制台 +open http://localhost:3000 +``` + +!!! tip "首次启动" + 首次启动需要构建镜像，可能需要几分钟时间。 + +### 方式二：本地开发 + +适合需要修改代码的开发者。 + +#### 1. 克隆项目 + +```bash +git clone https://github.com/your-org/AI-VideoAssistant.git cd AI-VideoAssistant ``` -### 2. 安装依赖 +#### 2. 启动 API 服务 + +```bash +cd api +python -m venv venv +source venv/bin/activate # Windows: venv\Scripts\activate +pip install -r requirements.txt +uvicorn main:app --host 0.0.0.0 --port 8080 --reload +``` + +#### 3. 启动 Engine 服务 + +```bash +cd engine +python -m venv venv +source venv/bin/activate +pip install -r requirements.txt +python main.py +``` + +#### 4. 启动 Web 前端 ```bash cd web npm install -``` - -### 3. 配置环境变量 - -创建 `.env` 文件，详见 [配置说明](configuration.md)。 - -### 4. 启动开发服务器 - -```bash npm run dev ``` -访问 http://localhost:3000 +访问 `http://localhost:3000` -## 构建生产版本 +--- -```bash -npm run build +## 验证安装 + +### 检查服务状态 + +| 服务 | URL | 预期结果 | +|------|-----|---------| +| Web | http://localhost:3000 | 看到登录/控制台页面 | +| API | http://localhost:8080/docs | 看到 Swagger 文档 | +| Engine | http://localhost:8000/health | 返回 `{"status": "ok"}` | + +### 测试 WebSocket 连接 + +```javascript +const ws = new WebSocket('ws://localhost:8000/ws?assistant_id=test'); +ws.onopen = () => console.log('Connected!'); +ws.onerror = (e) => console.error('Error:', e); ``` -构建产物在 `dist` 目录。 +--- + +## 目录结构 + +``` +AI-VideoAssistant/ +├── web/ # React 前端 +│ ├── src/ +│ │ ├── components/ # UI 组件 +│ │ ├── pages/ # 页面 +│ │ ├── stores/ # Zustand 状态 +│ │ └── api/ # API 客户端 +│ └── package.json +├── api/ # FastAPI 后端 +│ ├── app/ +│ │ ├── routers/ # API 路由 +│ │ ├── models/ # 数据模型 +│ │ └── services/ # 业务逻辑 +│ └── requirements.txt +├── engine/ # 实时交互引擎 +│ ├── app/ +│ │ ├── pipeline/ # 管线引擎 +│ │ └── multimodal/ # 多模态引擎 +│ └── requirements.txt +├── docker/ # Docker 配置 +│ └── docker-compose.yml +└── docs/ # 文档 +``` + +--- + +## 常见问题 + +### 端口被占用 + +```bash +# 查看端口占用 +# Linux/Mac +lsof -i :3000 + +# Windows +netstat -ano | findstr :3000 +``` + +修改对应服务的端口配置后重启。 + +### Docker 构建失败 + +```bash +# 清理 Docker 缓存 +docker system prune -a + +# 重新构建 +docker-compose build --no-cache +``` + +### Python 依赖安装失败 + +确保使用 Python 3.10+： + +```bash +python --version # 需要 3.10+ +``` + +--- ## 下一步 - [环境要求](requirements.md) - 详细的软件版本要求 - [配置说明](configuration.md) - 环境变量配置指南 -- [部署指南](../deployment/index.md) - 生产环境部署 +- [快速开始](../quickstart/index.md) - 创建第一个助手 +- [Docker 部署](../deployment/docker.md) - 镜像构建与编排 diff --git a/docs/content/getting-started/requirements.md b/docs/content/getting-started/requirements.md index c689380..e925de6 100644 --- a/docs/content/getting-started/requirements.md +++ b/docs/content/getting-started/requirements.md @@ -1,65 +1,149 @@ # 环境要求 +本页面列出运行 Realtime Agent Studio 所需的软件和硬件要求。 + +--- + ## 软件依赖 ### 必需软件 -| 软件 | 版本要求 | 说明 | +| 软件 | 版本要求 | 说明 | 安装命令 | +|------|---------|------|---------| +| **Node.js** | 18.0+ | 前端构建运行 | `nvm install 18` | +| **Python** | 3.10+ | 后端服务 | `pyenv install 3.10` | +| **Docker** | 20.10+ | 容器化部署（可选） | [安装指南](https://docs.docker.com/get-docker/) | + +### 可选软件 + +| 软件 | 版本要求 | 用途 | |------|---------|------| -| Node.js | 18.0 或更高 | JavaScript 运行时 | -| npm/yarn/pnpm | 最新版本 | 包管理器 | -| Python | 3.10+ | 后端服务运行环境 | +| **Docker Compose** | 2.0+ | 多服务编排 | +| **PostgreSQL** | 14+ | 生产数据库 | +| **Redis** | 6.0+ | 缓存与会话 | +| **Nginx** | 1.20+ | 反向代理 | -### 推荐浏览器 +--- -| 浏览器 | 版本要求 | -|--------|---------| -| Chrome | 90+ | -| Firefox | 90+ | -| Edge | 90+ | -| Safari | 14+ | +## 版本检查 -## 检查环境 +运行以下命令验证环境： -运行以下命令检查已安装的软件版本： +=== "Node.js" -```bash -# 检查 Node.js 版本 -node --version + ```bash + node --version + # v18.0.0 或更高 + + npm --version + # 8.0.0 或更高 + ``` -# 检查 npm 版本 -npm --version +=== "Python" -# 检查 Python 版本 -python --version -``` + ```bash + python --version + # Python 3.10.0 或更高 + + pip --version + # pip 22.0 或更高 + ``` -## 硬件建议 +=== "Docker" + + ```bash + docker --version + # Docker version 20.10.0 或更高 + + docker compose version + # Docker Compose version v2.0.0 或更高 + ``` + +--- + +## 浏览器支持 + +控制台需要现代浏览器支持 WebSocket 和 Web Audio API： + +| 浏览器 | 最低版本 | 推荐版本 | +|--------|---------|---------| +| Chrome | 90+ | 最新版 | +| Firefox | 90+ | 最新版 | +| Edge | 90+ | 最新版 | +| Safari | 14+ | 最新版 | + +!!! warning "IE 不支持" + Internet Explorer 不受支持，请使用现代浏览器。 + +--- + +## 硬件要求 ### 开发环境 -| 资源 | 建议配置 | -|------|---------| -| CPU | 4 核心以上 | -| 内存 | 8GB 以上 | -| 磁盘 | 20GB 可用空间 | +| 资源 | 最低配置 | 推荐配置 | +|------|---------|---------| +| **CPU** | 2 核心 | 4 核心+ | +| **内存** | 4GB | 8GB+ | +| **磁盘** | 10GB | 20GB+ SSD | +| **网络** | 10Mbps | 100Mbps | -### 生产环境 - -| 资源 | 建议配置 | -|------|---------| -| CPU | 8 核心以上 | -| 内存 | 16GB 以上 | -| 磁盘 | 100GB SSD | -| 网络 | 100Mbps 以上 | +--- ## 网络要求 -以下域名需要可访问（用于 API 调用）： +### 出站访问 -| 服务 | 域名 | -|------|------| -| OpenAI | api.openai.com | -| DeepSeek | api.deepseek.com | -| 阿里云 TTS | nls-gateway.cn-shanghai.aliyuncs.com | -| 火山引擎 | openspeech.bytedance.com | +以下外部服务需要网络可达（根据使用的模型供应商）： + +| 服务 | 域名 | 端口 | 用途 | +|------|------|------|------| +| **OpenAI** | api.openai.com | 443 | LLM / TTS | +| **Azure OpenAI** | *.openai.azure.com | 443 | LLM / ASR / TTS | +| **阿里云** | *.aliyuncs.com | 443 | DashScope TTS | +| **SiliconFlow** | api.siliconflow.cn | 443 | ASR / TTS | +| **DeepSeek** | api.deepseek.com | 443 | LLM | + +### 端口规划 + +| 服务 | 默认端口 | 可配置 | +|------|---------|--------| +| Web 前端 | 3000 | ✅ | +| API 服务 | 8080 | ✅ | +| Engine 服务 | 8000 | ✅ | +| PostgreSQL | 5432 | ✅ | +| Redis | 6379 | ✅ | + +--- + +## 操作系统 + +### 支持的系统 + +| 操作系统 | 版本 | 支持状态 | +|---------|------|---------| +| **Ubuntu** | 20.04 LTS, 22.04 LTS | ✅ 完全支持 | +| **Debian** | 11, 12 | ✅ 完全支持 | +| **CentOS** | 8+ | ✅ 完全支持 | +| **macOS** | 12+ (Monterey) | ✅ 开发支持 | +| **Windows** | 10/11 + WSL2 | ✅ 开发支持 | + +### Windows 注意事项 + +推荐使用 WSL2 进行开发： + +```powershell +# 安装 WSL2 +wsl --install + +# 安装 Ubuntu +wsl --install -d Ubuntu +``` + +--- + +## 下一步 + +- [配置说明](configuration.md) - 环境变量配置 +- [安装部署](index.md) - 开始安装 +- [Docker 部署](../deployment/docker.md) - 容器化部署 diff --git a/docs/content/images/logo.png b/docs/content/images/logo.png new file mode 100644 index 0000000..8e32fa9 Binary files /dev/null and b/docs/content/images/logo.png differ diff --git a/docs/content/index.md b/docs/content/index.md index d052c00..6c82d06 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -1,128 +1,114 @@ -# 实时交互智能体工作平台（RAS） +

+ Realtime Agent Studio +

-实时交互智能体工作平台（Realtime Agent Studio，简称 RAS）是一款以大语言模型为核心，构建实时交互音视频智能体的工作平台。支持管线式的全双工交互引擎和原生多模态模型两种核心，覆盖实时交互智能体构建过程中的配置、测试、发布、监控流程环节，平台包含大模型集成、语音识别、语音合成、自动化测试等功能，帮助用户快速构建实时交互智能体。 +

+ 构建实时交互音视频智能体的开源工作平台 +

-可以将该平台看作Vapi，Retell，ElevenAgents的开源替代。 +

+ Version + License + Python + Node +

-![仪表盘](images/dashboard.png) - -## 功能特色 - -### 实时交互引擎 - -平台的核心是一个低延迟、高并发的实时交互引擎，支持两种架构模式： - -- **管线式全双工引擎**：将语音识别（ASR）、大语言模型（LLM）、语音合成（TTS）串联成流水线，支持语音打断，实现自然的对话体验 -- **原生多模态模型支持**：直接接入 GPT-4o Realtime、Gemini Live 等端到端多模态模型，获得更低延迟和更自然的语音交互 -- **智能打断处理**：支持基于声音活动和语义的turn-detection模型，引擎自动处理音频截断和状态同步 - -### 智能体配置管理 - -提供可视化的智能体配置界面，无需编码即可创建和调整智能体： - -- **系统提示词编辑**：支持角色设定，会话动态变量 -- **模型选择与参数调优**：灵活切换 LLM/ASR/TTS 供应商，调整温度、采样等参数 -- **工具/函数调用配置**：webhook工具通过网络请求访问外部资源，客户端工具通过与用户交互获取信息，以及内建工具比如代码执行器，计算工具。 -- **知识库关联**：接入 RAG 系统，让智能体基于私有文档回答问题 -- **工作流编辑**：使用可视化流程编辑器构建包含多个环节的交互助手及其上下文切换 - -### 交互测试工具 - -内置完整的测试工具链，保障智能体上线质量： - -- **实时调试控制台**：在线测试体验智能体交互 ASR/LLM/TTS 各环节的输入输出 -- **自动化测试工具**：支持固定测试（预设问答对批量测试）和智能测试（AI自动生成测试用例），自动执行并生成测试报告 - -### 开放接口 - -提供标准化的 API 接口，便于集成到现有系统： - -- **WebSocket 实时协议**：支持音视频流式传输、双向通信 -- **RESTful 管理接口**：助手 CRUD、会话管理、配置导入导出 -- **Webhook 回调**：会话开始/结束、工具调用、异常告警等事件通知 -- **SDK 支持**：提供 JavaScript、Python、移动端 SDK，简化客户端集成 - -### 交互历史监控 - -全面的会话记录和数据分析能力： - -- **完整会话回放**：保存音频、转写文本、LLM 响应、工具调用的完整链路 -- **实时仪表盘**：并发会话数、平均响应时间、错误率等关键指标可视化 -- **会话检索与筛选**：按时间、助手、用户、关键词等维度快速定位会话 - -### 自主部署 - -支持私有化部署，数据安全可控： - -- **Docker 一键部署**：提供 docker-compose 配置，一行命令启动完整平台 -- **模型本地化**：支持云端模型和本地私有化模型两种方案 - -## 核心功能 - -| 功能模块 | 描述 | -|---------|------| -| **助手管理** | 创建、配置、测试 AI 助手 | -| **工作流** | 可视化流程编排 | -| **模型库** | LLM/ASR/语音模型配置 | -| **知识库** | RAG 文档知识管理 | -| **历史记录** | 对话日志查询与分析 | -| **自动化测试** | 批量测试与质量评估 | -| **仪表盘** | 实时数据统计与可视化分析 | - -## 开发计划（Roadmap） - -### 已完成 (Completed) - -#### 实时交互引擎 -- [x] 管线式全双工引擎 - ASR/LLM/TTS 流水线 - - [x] 智能打断处理 - VAD + EOU 检测 - - [x] OpenAI兼容的 ASR TTS 接口适配 - - [x] DashScope TTS 接口适配 - -#### 智能体配置管理 -- [x] 系统提示词编辑 - prompt 配置，动态变量注入 -- [x] 模型选择 - LLM/ASR/TTS 模型管理 -- [x] 工具调用配置 - webhook 工具 + 客户端工具 - -#### 交互测试工具 -- [x] 实时调试控制台 - WebSocket 调试连接示例 - -#### 开放接口 -- [x] WebSocket 协议 - /ws 端点 -- [x] RESTful 接口 - 完整的 CRUD API - -#### 交互历史监控 -- [x] 完整会话回放 - 音频 + 转写 + LLM 响应 -- [x] 会话检索筛选 - 按时间/助手/状态筛选 +

+ 快速开始 · + API 文档 · + 安装部署 · + 路线图 +

--- -### 开发中 (In Progress) +## 什么是 Realtime Agent Studio？ -#### 智能体配置管理 -- [ ] 私有化部署的 ASR TTS 适配 -- [ ] 工作流编辑 - 可视化流程编排 -- [ ] 知识库关联 - RAG 文档管理 +Realtime Agent Studio (RAS) 是一款以大语言模型为核心，构建实时交互音视频智能体的工作平台。支持管线式的全双工交互引擎和原生多模态模型两种架构，覆盖实时交互智能体的配置、测试、发布、监控全流程。 -#### 实时交互引擎 -- [ ] 原生多模态模型支持 - 由于GPT-4o Realtime, Gemini Live国内环境问题，计划加入Step Audio - -#### 开放接口 -- [ ] SDK 支持 - JavaScript/Python SDK -- [ ] WebRTC 协议 - /webrtc 端点 - -#### 效果评估 -- [ ] 自动化测试工具 - 固定测试 + 智能测试 +可以将 RAS 看作 [Vapi](https://vapi.ai)、[Retell](https://retellai.com)、[ElevenLabs Agents](https://elevenlabs.io) 的**开源替代方案**。 --- -### 待实现 (To Do) +## 核心特性 -#### 开放接口 -- [ ] Webhook 回调 - 会话事件通知 +
-#### 效果评估 -- [ ] 实时仪表盘 - 基础统计看板，需完善 +- :zap: **低延迟实时引擎** + + --- + + 管线式全双工架构，ASR/LLM/TTS 流水线处理，支持智能打断，端到端延迟 < 500ms + +- :brain: **多模态模型支持** + + --- + + 支持 GPT-4o Realtime、Gemini Live、Step Audio 等原生多模态模型直连 + +- :wrench: **可视化配置** + + --- + + 无代码配置助手、提示词、工具调用、知识库关联，所见即所得 + +- :electric_plug: **开放 API** + + --- + + 标准 WebSocket 协议，RESTful 管理接口，支持 Webhook 回调 + +- :shield: **私有化部署** + + --- + + Docker 一键部署，数据完全自主可控，支持本地模型 + +- :chart_with_upwards_trend: **全链路监控** + + --- + + 完整会话回放，实时仪表盘，自动化测试与效果评估 + +
+ +--- + +## 系统架构 + +```mermaid +flowchart LR + subgraph Client["客户端"] + Web[Web 浏览器] + App[移动应用] + SDK[SDK] + end + + subgraph RAS["Realtime Agent Studio"] + Engine[实时交互引擎] + API[API 服务] + DB[(数据库)] + end + + subgraph Pipeline["管线式引擎"] + ASR[语音识别] + LLM[大语言模型] + TTS[语音合成] + end + + subgraph External["外部服务"] + OpenAI[OpenAI] + Azure[Azure] + Local[本地模型] + end + + Client -->|WebSocket| Engine + Client -->|REST| API + Engine --> Pipeline + Engine <--> API + API <--> DB + Pipeline --> External +``` --- @@ -130,11 +116,12 @@ | 层级 | 技术 | |------|------| -| Frontend | React, TypeScript, Tailwind CSS | -| State | Zustand, React Query | -| Backend | FastAPI (Python) | -| Engine | Python | -| Database | SQLite | +| **前端** | React 18, TypeScript, Tailwind CSS, Zustand | +| **后端** | FastAPI (Python 3.10+) | +| **引擎** | Python, WebSocket, asyncio | +| **数据库** | SQLite / PostgreSQL | +| **知识库** | | +| **部署** | Docker, Nginx | --- @@ -142,36 +129,91 @@
-- :rocket: **[快速开始](quickstart/index.md)** +- :rocket: **[快速开始](quickstart/index.md)** + + --- 5 分钟创建你的第一个 AI 助手 -- :wrench: **[安装部署](getting-started/index.md)** +- :book: **[核心概念](concepts/index.md)** - 环境准备与安装配置 + --- -- :robot: **[助手管理](assistants/index.md)** + 了解助手、管线、多模态等核心概念 + +- :wrench: **[安装部署](getting-started/index.md)** + + --- + + 环境准备、本地开发与 Docker/生产部署 + +- :robot: **[助手管理](assistants/index.md)** + + --- 创建和配置智能对话助手 -- :gear: **[功能定制](customization/knowledge-base.md)** +- :gear: **[功能定制](customization/knowledge-base.md)** + + --- 知识库、工具、语音、工作流 -- :bar_chart: **[数据分析](analysis/dashboard.md)** +- :bar_chart: **[数据分析](analysis/dashboard.md)** + + --- 仪表盘、历史记录、测试评估 -- :book: **[API 参考](api-reference/index.md)** +- :electric_plug: **[API 参考](api-reference/index.md)** - WebSocket 协议与接口文档 + --- -- :cloud: **[部署指南](deployment/index.md)** + WebSocket 协议与 REST 接口文档 - Docker、Nginx 生产部署 +
-- :question: **[常见问题](resources/faq.md)** +--- - 使用问题与故障排查 +## 快速体验 - \ No newline at end of file +### 使用 Docker 启动 + +```bash +git clone https://github.com/your-org/AI-VideoAssistant.git +cd docker +docker-compose up -d +# for development +# docker compose --profile dev up -d +``` + +访问 `http://localhost:3000` 即可使用控制台。 + +### WebSocket 连接示例 + +```javascript +const ws = new WebSocket('ws://localhost:8000/ws?assistant_id=YOUR_ID'); + +ws.onopen = () => { + ws.send(JSON.stringify({ + type: 'session.start', + audio: { encoding: 'pcm_s16le', sample_rate_hz: 16000, channels: 1 } + })); +}; +``` + +--- + +## 参与贡献 + +我们欢迎社区贡献！查看 [贡献指南](https://github.com/your-org/AI-VideoAssistant/blob/main/CONTRIBUTING.md) 了解如何参与。 + +- :star: Star 项目支持我们 +- :bug: 提交 Issue 报告问题 +- :hammer: 提交 PR 贡献代码 + +--- + +## 许可证 + +本项目基于 [MIT 许可证](https://github.com/your-org/AI-VideoAssistant/blob/main/LICENSE) 开源。 diff --git a/docs/content/javascripts/extra.js b/docs/content/javascripts/extra.js new file mode 100644 index 0000000..b3fe8f7 --- /dev/null +++ b/docs/content/javascripts/extra.js @@ -0,0 +1,26 @@ +// Realtime Agent Studio - Custom JavaScript + +document.addEventListener("DOMContentLoaded", function () { + // Add external link icons + document.querySelectorAll('a[href^="http"]').forEach(function (link) { + if (!link.hostname.includes(window.location.hostname)) { + link.setAttribute("target", "_blank"); + link.setAttribute("rel", "noopener noreferrer"); + } + }); + + // Smooth scroll for anchor links + document.querySelectorAll('a[href^="#"]').forEach(function (anchor) { + anchor.addEventListener("click", function (e) { + const targetId = this.getAttribute("href").slice(1); + const targetElement = document.getElementById(targetId); + if (targetElement) { + e.preventDefault(); + targetElement.scrollIntoView({ + behavior: "smooth", + block: "start", + }); + } + }); + }); +}); diff --git a/docs/content/overview/architecture.md b/docs/content/overview/architecture.md new file mode 100644 index 0000000..df86af5 --- /dev/null +++ b/docs/content/overview/architecture.md @@ -0,0 +1,314 @@ +# 系统架构 + +本文档详细介绍 Realtime Agent Studio (RAS) 的系统架构设计。 + +--- + +## 整体架构 + +RAS 采用前后端分离的微服务架构，主要由三个核心服务组成： + +```mermaid +flowchart TB + subgraph Client["客户端"] + Browser[Web 浏览器] + Mobile[移动应用] + ThirdParty[第三方系统] + end + + subgraph Frontend["前端服务"] + WebApp[React 管理控制台] + end + + subgraph Backend["后端服务"] + API[API 服务
FastAPI] + Engine[实时交互引擎
WebSocket] + end + + subgraph Storage["数据存储"] + DB[(SQLite/PostgreSQL)] + FileStore[文件存储] + end + + subgraph External["外部服务"] + LLM[LLM 服务] + ASR[ASR 服务] + TTS[TTS 服务] + end + + Browser --> WebApp + Mobile -->|WebSocket| Engine + ThirdParty -->|REST API| API + WebApp -->|REST API| API + WebApp -->|WebSocket| Engine + API <--> DB + API <--> FileStore + Engine <--> API + Engine --> LLM + Engine --> ASR + Engine --> TTS +``` + +--- + +## 核心组件 + +### 1. Web 前端 (React) + +管理控制台，提供可视化的配置和监控界面。 + +| 功能模块 | 说明 | +|---------|------| +| 助手管理 | 创建、配置、测试智能助手 | +| 资源库 | LLM/ASR/TTS 模型管理 | +| 知识库 | RAG 文档上传与管理 | +| 历史记录 | 会话日志查询与回放 | +| 仪表盘 | 实时数据统计 | +| 调试控制台 | WebSocket 实时测试 | + +### 2. API 服务 (FastAPI) + +RESTful API 后端，处理所有管理操作。 + +```mermaid +flowchart LR + subgraph API["API 服务"] + Router[路由层] + Service[业务逻辑层] + Model[数据模型层] + end + + Client[客户端] --> Router + Router --> Service + Service --> Model + Model --> DB[(数据库)] +``` + +**主要职责：** + +- 助手 CRUD 操作 +- 模型资源管理 +- 知识库管理 +- 会话记录存储 +- 认证与授权 + +### 3. 实时交互引擎 (Engine) + +核心组件，处理实时音视频对话。 + +```mermaid +flowchart TB + subgraph Engine["实时交互引擎"] + WS[WebSocket Handler] + SM[会话管理器] + + subgraph Pipeline["管线式引擎"] + VAD[VAD 检测] + ASR[语音识别] + LLM[大语言模型] + TTS[语音合成] + end + + subgraph Multimodal["多模态引擎"] + RT[Realtime Model
GPT-4o / Gemini] + end + end + + Client[客户端] -->|音频流| WS + WS --> SM + SM --> Pipeline + SM --> Multimodal + Pipeline -->|文本/音频| WS + Multimodal -->|文本/音频| WS +``` + +--- + +## 引擎架构 + +### 管线式全双工引擎 + +传统方案，将语音交互拆分为三个独立阶段： + +```mermaid +sequenceDiagram + participant C as 客户端 + participant E as 引擎 + participant ASR as 语音识别 + participant LLM as 大语言模型 + participant TTS as 语音合成 + + C->>E: 音频流 (PCM) + E->>ASR: 语音转文字 + ASR-->>E: 转写文本 + E->>LLM: 生成回复 + LLM-->>E: 回复文本 (流式) + E->>TTS: 文字转语音 + TTS-->>E: 音频流 + E->>C: 播放音频 +``` + +**特点：** + +- 灵活选择各环节供应商 +- 可独立优化每个环节 +- 延迟约 500-1500ms + +### 原生多模态引擎 + +使用端到端多模态模型（如 GPT-4o Realtime）： + +```mermaid +sequenceDiagram + participant C as 客户端 + participant E as 引擎 + participant RT as Realtime Model + + C->>E: 音频流 + E->>RT: 音频输入 + RT-->>E: 音频输出 (流式) + E->>C: 播放音频 +``` + +**特点：** + +- 更低延迟 (< 300ms) +- 更自然的语音交互 +- 依赖特定模型供应商 + +--- + +## 数据流 + +### WebSocket 会话流程 + +```mermaid +sequenceDiagram + participant C as 客户端 + participant E as 引擎 + participant API as API 服务 + participant DB as 数据库 + + C->>E: 连接 ws://.../ws?assistant_id=xxx + E->>API: 获取助手配置 + API->>DB: 查询助手 + DB-->>API: 助手数据 + API-->>E: 配置信息 + + C->>E: session.start + E-->>C: session.started + E-->>C: config.resolved + + loop 对话循环 + C->>E: 音频帧 (binary) + E-->>C: input.speech_started + E-->>C: transcript.delta + E-->>C: transcript.final + E-->>C: assistant.response.delta + E-->>C: output.audio.start + E-->>C: 音频帧 (binary) + E-->>C: output.audio.end + end + + C->>E: session.stop + E->>API: 保存会话记录 + API->>DB: 存储 + E-->>C: session.stopped +``` + +### 智能打断流程 + +```mermaid +sequenceDiagram + participant C as 客户端 + participant E as 引擎 + participant TTS as TTS 服务 + + Note over E: 正在播放 TTS 音频 + E->>C: 音频帧... + + C->>E: 用户说话 (VAD 检测) + E->>E: 触发打断 + E->>TTS: 停止合成 + E-->>C: output.audio.interrupted + + Note over E: 处理新的用户输入 + E-->>C: input.speech_started +``` + +--- + +## 部署架构 + +### 开发环境 + +```mermaid +flowchart LR + subgraph Local["本地开发"] + Web[npm run dev
:3000] + API[uvicorn
:8080] + Engine[python main.py
:8000] + DB[(SQLite)] + end + + Web --> API + Web --> Engine + API --> DB + Engine --> API +``` + +## 技术选型 + +| 组件 | 技术 | 选型理由 | +|------|------|---------| +| **前端框架** | React 18 | 成熟生态，组件化开发 | +| **状态管理** | Zustand | 轻量级，TypeScript 友好 | +| **UI 组件** | Tailwind CSS | 原子化 CSS，快速开发 | +| **后端框架** | FastAPI | 高性能，自动 API 文档 | +| **WebSocket** | websockets | Python 异步 WebSocket | +| **ORM** | SQLAlchemy | 功能完善，支持多数据库 | +| **数据库** | SQLite/PostgreSQL | 开发简单/生产可靠 | + +--- + +## 扩展性设计 + +### 模型适配器模式 + +```mermaid +classDiagram + class ModelAdapter { + <> + +generate(prompt) string + +stream(prompt) AsyncIterator + } + + class OpenAIAdapter { + +generate(prompt) string + +stream(prompt) AsyncIterator + } + + class AzureAdapter { + +generate(prompt) string + +stream(prompt) AsyncIterator + } + + class LocalAdapter { + +generate(prompt) string + +stream(prompt) AsyncIterator + } + + ModelAdapter <|-- OpenAIAdapter + ModelAdapter <|-- AzureAdapter + ModelAdapter <|-- LocalAdapter +``` + +通过适配器模式，可以轻松接入新的模型供应商。 + +--- + +## 相关文档 + +- [WebSocket 协议](../api-reference/websocket.md) - 详细的协议规范 +- [部署概览](../deployment/index.md) - Docker 部署 +- [核心概念](../concepts/index.md) - 助手、管线等概念说明 diff --git a/docs/content/overview/index.md b/docs/content/overview/index.md new file mode 100644 index 0000000..b9d0398 --- /dev/null +++ b/docs/content/overview/index.md @@ -0,0 +1,148 @@ +# 产品概览 + +了解 Realtime Agent Studio 的核心功能和设计理念。 + +--- + +## 什么是 RAS？ + +Realtime Agent Studio (RAS) 是一个**开源的实时交互智能体工作平台**，让开发者能够快速构建和部署具备语音对话能力的 AI 助手。 + +### 核心价值 + +| 价值主张 | 说明 | +|---------|------| +| **低代码配置** | 可视化界面配置助手，无需编写复杂代码 | +| **实时交互** | 毫秒级响应，支持语音打断，自然对话体验 | +| **开放灵活** | 支持多种模型供应商，自由选择最适合的方案 | +| **私有部署** | 完全自主可控，数据不出域 | + +--- + +## 功能模块 + +```mermaid +mindmap + root((RAS)) + 助手管理 + 创建配置 + 提示词编辑 + 模型选择 + 工具调用 + 资源库 + LLM 模型 + ASR 模型 + TTS 声音 + 知识库 + 文档上传 + 向量检索 + RAG 问答 + 监控分析 + 会话回放 + 数据统计 + 自动测试 + 部署集成 + WebSocket API + REST API + SDK +``` + +### 助手管理 + +创建和配置智能对话助手： + +- **系统提示词** - 定义助手角色和行为 +- **模型配置** - 选择 LLM、ASR、TTS 模型 +- **工具调用** - 配置 Webhook 和客户端工具 +- **开场白** - 设置首轮对话模式 + +### 资源库 + +集中管理各类模型资源： + +- **语音识别 (ASR)** - 多供应商 ASR 模型管理 +- **大语言模型 (LLM)** - OpenAI、Azure、本地模型 +- **语音合成 (TTS)** - 多音色声音资源 + +### 知识库 + +为助手提供专业知识： + +- **文档上传** - 支持 PDF、Word、Markdown 等格式 +- **向量化索引** - 自动分块和向量化 +- **RAG 检索** - 基于语义的知识检索 + +### 监控分析 + +全面的数据分析能力： + +- **会话回放** - 完整链路日志和音频回放 +- **实时仪表盘** - 并发数、延迟、错误率统计 +- **自动化测试** - 批量测试和效果评估 + +--- + +## 对比其他方案 + +| 特性 | RAS | Vapi | Retell | ElevenLabs | +|------|-----|------|--------|------------| +| **开源** | :white_check_mark: | :x: | :x: | :x: | +| **私有部署** | :white_check_mark: | :x: | :x: | :x: | +| **管线式引擎** | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | +| **多模态模型** | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: | +| **自定义 ASR/TTS** | :white_check_mark: | 有限 | 有限 | :x: | +| **知识库** | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | +| **工作流编辑** | 开发中 | :white_check_mark: | :x: | :x: | +| **定价** | 免费 | 按量付费 | 按量付费 | 按量付费 | + +--- + +## 适用场景 + +
+ +- :telephone_receiver: **智能客服** + + --- + + 7x24 小时自动接听，处理常见咨询，复杂问题转人工 + +- :hospital: **医疗问诊** + + --- + + 预问诊信息收集，健康咨询，用药提醒 + +- :school: **教育培训** + + --- + + 口语练习，知识问答，个性化辅导 + +- :handshake: **销售助手** + + --- + + 产品介绍，需求挖掘，预约安排 + +- :headphones: **语音助手** + + --- + + 智能家居控制，日程管理，信息查询 + +- :robot: **虚拟人** + + --- + + 数字人直播，虚拟主播，交互式展示 + +
+ +--- + +## 下一步 + +- [快速开始](../quickstart/index.md) - 5 分钟创建第一个助手 +- [系统架构](architecture.md) - 深入了解技术实现 +- [核心概念](../concepts/index.md) - 学习关键概念 diff --git a/docs/content/quickstart/index.md b/docs/content/quickstart/index.md index c339f92..3e15783 100644 --- a/docs/content/quickstart/index.md +++ b/docs/content/quickstart/index.md @@ -273,4 +273,4 @@ ws.onmessage = (event) => { - [配置知识库](../customization/knowledge-base.md) - 让助手回答专业问题 - [添加工具](../customization/tools.md) - 扩展助手能力 - [查看 API 文档](../api-reference/websocket.md) - 深入了解协议细节 -- [部署到生产环境](../deployment/index.md) - 正式上线 +- [Docker 部署](../deployment/index.md) - 使用容器运行 diff --git a/docs/content/roadmap.md b/docs/content/roadmap.md new file mode 100644 index 0000000..2680a29 --- /dev/null +++ b/docs/content/roadmap.md @@ -0,0 +1,102 @@ +# 开发路线图 + +本页面展示 Realtime Agent Studio 的开发计划和进度。 + +--- + +## 已完成 :white_check_mark: + +### 实时交互引擎 + +- [x] **管线式全双工引擎** - ASR/LLM/TTS 流水线架构 +- [x] **智能打断处理** - VAD + EOU 检测 +- [x] **OpenAI 兼容接口** - ASR/TTS 标准接口适配 +- [x] **DashScope TTS** - 阿里云语音合成适配 + +### 智能体配置管理 + +- [x] **系统提示词编辑** - Prompt 配置，动态变量注入 +- [x] **模型选择** - LLM/ASR/TTS 模型管理界面 +- [x] **工具调用配置** - Webhook 工具 + 客户端工具 + +### 交互测试工具 + +- [x] **实时调试控制台** - WebSocket 调试连接示例 + +### 开放接口 + +- [x] **WebSocket 协议** - `/ws` 端点完整实现 +- [x] **RESTful 接口** - 完整的 CRUD API + +### 交互历史监控 + +- [x] **完整会话回放** - 音频 + 转写 + LLM 响应 +- [x] **会话检索筛选** - 按时间/助手/状态筛选 + +--- + +## 开发中 :construction: + +### 智能体配置管理 + +- [ ] **私有化 ASR/TTS 适配** - 本地模型接入 +- [ ] **工作流编辑** - 可视化流程编排 +- [ ] **知识库关联** - RAG 文档管理 + +### 实时交互引擎 + +- [ ] **原生多模态模型** - Step Audio 接入（GPT-4o Realtime/Gemini Live 国内环境受限） + +### 开放接口 + +- [ ] **SDK 支持** - JavaScript/Python SDK +- [ ] **WebRTC 协议** - `/webrtc` 端点 + +### 效果评估 + +- [ ] **自动化测试工具** - 固定测试 + 智能测试 + +--- + +## 计划中 :spiral_notepad: + +### 开放接口 + +- [ ] **Webhook 回调** - 会话事件通知机制 + +### 效果评估 + +- [ ] **实时仪表盘增强** - 完善统计看板功能 + +### 企业特性 + +- [ ] **多租户支持** - 团队/组织管理 +- [ ] **权限管理** - RBAC 角色权限控制 +- [ ] **审计日志** - 操作记录追踪 + +### 生态集成 + +- [ ] **更多模型供应商** - 讯飞、百度、腾讯等 +- [ ] **CRM 集成** - Salesforce、HubSpot 等 +- [ ] **呼叫中心集成** - SIP/PSTN 网关 + +--- + +## 版本规划 + +| 版本 | 目标 | 状态 | +|------|------|------| +| **v0.1.0** | 核心功能 MVP，管线式引擎 | :white_check_mark: 已发布 | +| **v0.2.0** | 工作流编辑器，知识库集成 | :construction: 开发中 | +| **v0.3.0** | SDK 发布，多模态模型支持 | :spiral_notepad: 计划中 | +| **v1.0.0** | 生产就绪，企业特性 | :spiral_notepad: 计划中 | + +--- + +## 参与贡献 + +对路线图有建议？欢迎通过以下方式参与： + +- 在 [GitHub Issues](https://github.com/your-org/AI-VideoAssistant/issues) 提交功能请求 +- 在 [Discussions](https://github.com/your-org/AI-VideoAssistant/discussions) 参与讨论 +- 直接提交 PR 贡献代码 diff --git a/docs/content/stylesheets/extra.css b/docs/content/stylesheets/extra.css new file mode 100644 index 0000000..b0fd038 --- /dev/null +++ b/docs/content/stylesheets/extra.css @@ -0,0 +1,156 @@ +/* Realtime Agent Studio - Custom Styles */ + +:root { + --md-primary-fg-color: #4f46e5; + --md-primary-fg-color--light: #6366f1; + --md-primary-fg-color--dark: #4338ca; + --md-accent-fg-color: #6366f1; +} + +/* Hero Section - Center aligned content */ +.md-typeset p[align="center"] { + text-align: center; +} + +.md-typeset p[align="center"] img { + display: inline-block; + margin: 0 4px; + vertical-align: middle; +} + +.md-typeset p[align="center"] a { + margin: 0 8px; +} + +[data-md-color-scheme="slate"] { + --md-primary-fg-color: #818cf8; + --md-primary-fg-color--light: #a5b4fc; + --md-primary-fg-color--dark: #6366f1; + --md-accent-fg-color: #818cf8; +} + +/* Hero Section Styling */ +.md-content h1 { + font-weight: 700; + letter-spacing: -0.02em; +} + +/* Badge Styling */ +.md-content img[src*="badge"] { + margin: 0 4px; + vertical-align: middle; +} + +/* Grid Cards Enhancement */ +.md-typeset .grid.cards > ul > li { + border: 1px solid var(--md-default-fg-color--lightest); + border-radius: 8px; + transition: all 0.2s ease; +} + +.md-typeset .grid.cards > ul > li:hover { + border-color: var(--md-primary-fg-color); + box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); + transform: translateY(-2px); +} + +/* Code Block Enhancement */ +.md-typeset pre > code { + border-radius: 8px; +} + +.md-typeset .highlight { + border-radius: 8px; + overflow: hidden; +} + +/* Table Enhancement */ +.md-typeset table:not([class]) { + border-radius: 8px; + overflow: hidden; + border: 1px solid var(--md-default-fg-color--lightest); +} + +.md-typeset table:not([class]) th { + background-color: var(--md-default-fg-color--lightest); + font-weight: 600; +} + +/* Admonition Enhancement */ +.md-typeset .admonition, +.md-typeset details { + border-radius: 8px; + border: none; +} + +/* Mermaid Diagram Styling */ +.mermaid { + margin: 1.5rem 0; +} + +/* Navigation Enhancement */ +.md-nav__link { + font-weight: 500; +} + +.md-nav__item--active > .md-nav__link { + font-weight: 600; +} + +/* Footer Styling */ +.md-footer { + margin-top: 3rem; +} + +/* Center align for hero badges */ +.md-content > .md-typeset > div[align="center"] img { + margin: 0.25rem; +} + +/* Task list styling */ +.md-typeset .task-list-item input[type="checkbox"] { + margin-right: 0.5rem; +} + +/* Improve readability */ +.md-typeset { + font-size: 0.85rem; + line-height: 1.75; +} + +.md-typeset h2 { + margin-top: 2.5rem; + padding-bottom: 0.5rem; + border-bottom: 1px solid var(--md-default-fg-color--lightest); +} + +.md-typeset h3 { + margin-top: 1.5rem; +} + +/* Responsive improvements */ +@media screen and (max-width: 76.1875em) { + .md-typeset .grid.cards > ul > li { + padding: 1rem; + } +} + +/* Animation for interactive elements */ +.md-typeset a:not(.md-button) { + transition: color 0.15s ease; +} + +.md-typeset a:not(.md-button):hover { + color: var(--md-accent-fg-color); +} + +/* Version selector styling */ +.md-version { + font-size: 0.75rem; +} + +/* Search highlight */ +.md-search-result mark { + background-color: var(--md-accent-fg-color--transparent); + color: inherit; +} diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index c37b38b..3912233 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -1,6 +1,7 @@ -site_name: "实时交互智能体工作平台 (RAS)" -site_description: "实时交互智能体工作平台 (Realtime Agent Studio) - 智能对话与工作流管理平台" -copyright: "2025" +site_name: "Realtime Agent Studio" +site_description: "构建实时交互音视频智能体的开源工作平台" +site_url: "https://your-org.github.io/AI-VideoAssistant" +copyright: "Copyright © 2025 RAS Team" site_author: "RAS Team" docs_dir: "content" @@ -8,15 +9,24 @@ site_dir: "site" nav: - 首页: index.md + - 产品概览: + - 概述: overview/index.md + - 系统架构: overview/architecture.md - 快速开始: - - 概览: quickstart/index.md + - 5 分钟入门: quickstart/index.md - 资源库配置: quickstart/dashboard.md + - 核心概念: + - 概述: concepts/index.md + - 助手详解: concepts/assistants.md + - 引擎架构: concepts/engines.md - 安装部署: - - 概览: getting-started/index.md + - 概述: getting-started/index.md - 环境要求: getting-started/requirements.md - 配置说明: getting-started/configuration.md + - 部署概览: deployment/index.md + - Docker 部署: deployment/docker.md - 助手管理: - - 概览: assistants/index.md + - 概述: assistants/index.md - 配置选项: assistants/configuration.md - 提示词指南: assistants/prompts.md - 测试调试: assistants/testing.md @@ -32,28 +42,34 @@ nav: - 效果评估: analysis/evaluation.md - 自动化测试: analysis/autotest.md - API 参考: - - 概览: api-reference/index.md + - 概述: api-reference/index.md - WebSocket 协议: api-reference/websocket.md - 错误码: api-reference/errors.md - - 部署指南: - - 概览: deployment/index.md - - Docker 部署: deployment/docker.md - - 生产环境: deployment/production.md - 资源: - 常见问题: resources/faq.md - 故障排查: resources/troubleshooting.md + - 更新日志: changelog.md + - 路线图: roadmap.md theme: name: material language: zh + custom_dir: overrides + icon: + logo: material/robot-outline + font: + text: Inter + code: JetBrains Mono palette: - - scheme: default + - media: "(prefers-color-scheme: light)" + scheme: default primary: indigo accent: indigo toggle: icon: material/brightness-7 name: 切换到深色模式 - - scheme: slate + - media: "(prefers-color-scheme: dark)" + scheme: slate primary: indigo accent: indigo toggle: @@ -61,34 +77,86 @@ theme: name: 切换到浅色模式 features: - navigation.instant + - navigation.instant.prefetch - navigation.tracking - navigation.tabs + - navigation.tabs.sticky - navigation.sections - navigation.expand + - navigation.path + - navigation.top + - navigation.footer - toc.follow - search.suggest - search.highlight + - search.share - content.code.copy - + - content.code.annotate + - content.tabs.link markdown_extensions: + - abbr - admonition + - attr_list + - def_list + - footnotes + - md_in_html + - tables + - toc: + permalink: true + toc_depth: 3 + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret - pymdownx.details - - pymdownx.superfences + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg - pymdownx.highlight: anchor_linenums: true + line_spans: __span + pygments_lang_class: true - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.magiclink: + repo_url_shorthand: true + user: your-org + repo: AI-VideoAssistant + - pymdownx.mark + - pymdownx.smartsymbols - pymdownx.snippets + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.tabbed: alternate_style: true - pymdownx.tasklist: custom_checkbox: true - - pymdownx.emoji: - emoji_index: !!python/name:material.extensions.emoji.twemoji - emoji_generator: !!python/name:material.extensions.emoji.to_svg - - tables - - attr_list - - md_in_html + - pymdownx.tilde plugins: - search: lang: zh + separator: '[\s\-\.]+' + - minify: + minify_html: true + +extra: + # version.provider: mike — only enable when deploying with mike (versions.json is generated on deploy) + social: + - icon: fontawesome/brands/github + link: https://github.com/your-org/AI-VideoAssistant + name: GitHub + generator: false + analytics: + provider: google + property: G-XXXXXXXXXX + +extra_css: + - stylesheets/extra.css + +extra_javascript: + - javascripts/extra.js diff --git a/docs/overrides/main.html b/docs/overrides/main.html new file mode 100644 index 0000000..fd9a318 --- /dev/null +++ b/docs/overrides/main.html @@ -0,0 +1,9 @@ +{% extends "base.html" %} + +{% block extrahead %} + + + + + +{% endblock %} diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..babe3ca --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +# Pin MkDocs to 1.x; Material for MkDocs is not yet compatible with MkDocs 2.0 +# https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/ +mkdocs>=1.6,<2 +mkdocs-material diff --git a/engine/.dockerignore b/engine/.dockerignore new file mode 100644 index 0000000..fa21249 --- /dev/null +++ b/engine/.dockerignore @@ -0,0 +1,51 @@ +# Python +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +.venv/ +venv/ +ENV/ +.eggs/ +*.egg-info/ +*.egg + +# IDE +.idea/ +.vscode/ +*.swp +*.swo + +# Logs +logs/ +*.log + +# Testing +.pytest_cache/ +.coverage +htmlcov/ +.tox/ + +# Environment +.env +.env.local +*.env + +# Git +.git/ +.gitignore + +# Docker +Dockerfile +.dockerignore + +# Development files +*.md +tests/ +examples/ +scripts/ +docs/ + +# Running artifacts +running/ diff --git a/engine/Dockerfile b/engine/Dockerfile new file mode 100644 index 0000000..e6e5806 --- /dev/null +++ b/engine/Dockerfile @@ -0,0 +1,26 @@ +FROM python:3.12-slim + +WORKDIR /app + +# Install system dependencies for audio processing +RUN apt-get update && apt-get install -y --no-install-recommends \ + build-essential \ + libportaudio2 \ + libportaudiocpp0 \ + portaudio19-dev \ + ffmpeg \ + && rm -rf /var/lib/apt/lists/* + +# Install Python dependencies +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt + +# Copy application code +COPY . . + +# Create necessary directories +RUN mkdir -p /app/logs /app/data/vad + +EXPOSE 8001 + +CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8001"] diff --git a/web/Dockerfile b/web/Dockerfile index ed27eea..79c7d53 100644 --- a/web/Dockerfile +++ b/web/Dockerfile @@ -1,5 +1,6 @@ # Build stage -FROM node:20-alpine AS builder +ARG REGISTRY_MIRROR=docker.1ms.run +FROM ${REGISTRY_MIRROR}/node:20-alpine AS builder WORKDIR /app @@ -8,11 +9,14 @@ RUN npm ci COPY . . ARG VITE_API_BASE_URL=http://localhost:8100/api +ARG VITE_ENGINE_WS_URL=ws://localhost:8001/ws ENV VITE_API_BASE_URL=$VITE_API_BASE_URL +ENV VITE_ENGINE_WS_URL=$VITE_ENGINE_WS_URL RUN npm run build # Serve stage (no nginx – Node + serve on port 6000) -FROM node:20-alpine +ARG REGISTRY_MIRROR=docker.1ms.run +FROM ${REGISTRY_MIRROR}/node:20-alpine RUN npm install -g serve diff --git a/web/Dockerfile.dev b/web/Dockerfile.dev new file mode 100644 index 0000000..b03a1a7 --- /dev/null +++ b/web/Dockerfile.dev @@ -0,0 +1,13 @@ +# Development: run Vite dev server with hot reload (source mounted as volume) +ARG REGISTRY_MIRROR=docker.1ms.run +FROM ${REGISTRY_MIRROR}/node:20-alpine + +WORKDIR /app + +COPY package.json package-lock.json ./ +RUN npm ci + +# App code is mounted at runtime; no COPY of source +EXPOSE 3000 + +CMD ["npm", "run", "dev"]