4c05131536
- Revised mkdocs.yml to reflect the new site name and description, enhancing clarity for users. - Added a changelog.md to document important changes and updates for the project. - Introduced a roadmap.md to outline development plans and progress for future releases. - Expanded index.md with a comprehensive overview of the platform, including core features and installation instructions. - Enhanced concepts documentation with detailed explanations of assistants, engines, and their configurations. - Updated configuration documentation to provide clear guidance on environment setup and service configurations. - Added extra JavaScript for improved user experience in the documentation site.
290 lines
4.8 KiB
Markdown
290 lines
4.8 KiB
Markdown
# 配置说明
|
||
|
||
本页面介绍 Realtime Agent Studio 各组件的配置方法。
|
||
|
||
---
|
||
|
||
## 配置概览
|
||
|
||
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 服务地址（必填）
|
||
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 服务配置
|
||
|
||
### 环境变量
|
||
|
||
```env
|
||
# 数据库配置
|
||
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-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 配置
|
||
|
||
```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) - 容器化部署
|
||
- [生产环境](../deployment/production.md) - 生产配置指南
|