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

配置说明

本页面介绍 Realtime Agent Studio 各组件的配置方法。

---

配置概览

RAS 采用分层配置，各组件独立配置：

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 文件：

# API 服务地址（必填）
VITE_API_URL=http://localhost:8080

# Engine WebSocket 地址（可选，默认同 API 服务器）
VITE_WS_URL=ws://localhost:8000

# Google Gemini API Key（可选，用于前端直连）
VITE_GEMINI_API_KEY=your_api_key

变量说明

变量	必填	说明	默认值
VITE_API_URL	✅	后端 API 服务地址	-
VITE_WS_URL	❌	WebSocket 服务地址	从 API URL 推断
VITE_GEMINI_API_KEY	❌	Gemini API 密钥	-

多环境配置

=== "开发环境"

```env
# .env.development
VITE_API_URL=http://localhost:8080
VITE_WS_URL=ws://localhost:8000
```

=== "生产环境"

```env
# .env.production
VITE_API_URL=https://api.example.com
VITE_WS_URL=wss://ws.example.com
```

---

API 服务配置

环境变量

# 数据库配置
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：

# 服务配置
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 服务配置

环境变量

# 后端 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：

# 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 环境变量

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：

# Docker Compose 会自动加载
SECRET_KEY=your-production-secret-key
POSTGRES_PASSWORD=secure-db-password

---

配置优先级

配置按以下优先级加载（高优先级覆盖低优先级）：

1. 命令行参数（最高）
2. 环境变量
3. .env 文件
4. 配置文件 (yaml)
5. 代码默认值（最低）

---

敏感配置管理

!!! danger "安全提醒" 不要将敏感信息提交到代码仓库！

推荐做法

1. 使用 .env 文件，并将其加入 .gitignore
2. 使用环境变量，通过 CI/CD 注入
3. 使用密钥管理服务，如 AWS Secrets Manager、HashiCorp Vault

.gitignore 配置

# 环境配置文件
.env
.env.local
.env.*.local

# 敏感数据目录
/secrets/
*.pem
*.key

---

配置验证

启动服务前验证配置是否正确：

# 验证 API 服务配置
cd api
python -c "from app.config import settings; print(settings)"

# 验证 Engine 配置
cd engine
python -c "from config import settings; print(settings)"

---

下一步

• 安装部署 - 开始安装服务
• Docker 部署 - 容器化部署
• 生产环境 - 生产配置指南