AI-VideoAssistant/docs/content/getting-started/index.md

安装部署

本章节介绍如何安装和配置 Realtime Agent Studio (RAS) 开发环境。

---

系统组件

RAS 由三个核心服务组成：

flowchart LR
    subgraph Services["服务组件"]
        Web[Web 前端<br/>React + TypeScript]
        API[API 服务<br/>FastAPI]
        Engine[Engine 服务<br/>WebSocket]
    end

    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（推荐）

最快捷的启动方式，适合快速体验和生产部署。

# 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. 克隆项目

git clone https://github.com/your-org/AI-VideoAssistant.git
cd AI-VideoAssistant

2. 启动 API 服务

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 服务

cd engine
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python main.py

4. 启动 Web 前端

cd web
npm install
npm run dev

访问 http://localhost:3000

---

验证安装

检查服务状态

服务	URL	预期结果
Web	http://localhost:3000	看到登录/控制台页面
API	http://localhost:8080/docs	看到 Swagger 文档
Engine	http://localhost:8000/health	返回 {"status": "ok"}

测试 WebSocket 连接

const ws = new WebSocket('ws://localhost:8000/ws?assistant_id=test');
ws.onopen = () => console.log('Connected!');
ws.onerror = (e) => console.error('Error:', e);

---

目录结构

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/                   # 文档

---

常见问题

端口被占用

# 查看端口占用
# Linux/Mac
lsof -i :3000

# Windows
netstat -ano | findstr :3000

修改对应服务的端口配置后重启。

Docker 构建失败

# 清理 Docker 缓存
docker system prune -a

# 重新构建
docker-compose build --no-cache

Python 依赖安装失败

确保使用 Python 3.10+：

python --version  # 需要 3.10+

---

下一步

• 环境要求 - 详细的软件版本要求
• 配置说明 - 环境变量配置指南
• 快速开始 - 创建第一个助手
• Docker 部署 - 生产环境部署