# LiveKit Voice AI 部署计划 ## 📋 项目概况 | 项目 | 内容 | |------|------| | **项目名** | LiveKit Voice AI | | **目标** | 基于 LiveKit Agents 的实时语音AI框架 | | **硬件** | Intel Mac, 8GB RAM, CPU-only | | **部署模式** | Docker Compose 本地部署 | | **版本** | v1.11 | --- ## 🗓️ 部署阶段计划 ### Phase 1: 环境准备（Day 1） #### Step 1.1: 安装基础工具 ```bash # 确认安装状态 docker --version # 29.3.1 ✅ python3 --version # 3.14.6 ✅ pip install --upgrade pip # 升级pip ``` #### Step 1.2: 创建项目目录 ```bash mkdir -p ~/Projects/livekit-agents cd ~/Projects/livekit-agents ``` #### Step 1.3: 克隆代码 ```bash # 从工作空间复制或直接使用 cp -r /Users/leo/.hermes/workspace/livekit-agents/* ~/Projects/livekit-agents/ cd ~/Projects/livekit-agents ``` --- ### Phase 2: 模型下载（Day 1，预计 30-60分钟） #### Step 2.1: 配置 HF 镜像 ```bash # 设置环境变量 export HF_ENDPOINT=https://hf-mirror.com ``` #### Step 2.2: 下载 STT 模型（SenseVoiceSmall） ```bash mkdir -p models/funasr cd models/funasr # 下载 SenseVoiceSmall 模型（约 500MB） git clone https://www.modelscope.cn/iic/SenseVoiceSmall.git ``` #### Step 2.3: 下载 VAD 模型 ```bash mkdir -p models/vad # TEN VAD（轻量级，306KB） # 通过 pip 安装即可，无需额外下载 pip install ten-vad ``` #### Step 2.4: 可选：下载 pyannote 模型（说话人分离） ```bash mkdir -p models/pyannote # pyannote 模型较大（~1GB），内存允许时再下载 # huggingface-cli download pyannote/segmentation --local-dir models/pyannote/segmentation # huggingface-cli download pyannote/embedding --local-dir models/pyannote/embedding ``` --- ### Phase 3: 配置服务（Day 1） #### Step 3.1: 配置环境变量 ```bash # 复制并编辑配置 cp .env.example .env vim .env ``` **关键配置项：** ```bash # LiveKit 认证（开发环境使用默认值即可） LIVEKIT_API_KEY=devkey LIVEKIT_API_SECRET=secret LIVEKIT_URL=http://localhost:7880 # Hermes LLM API Key HERMES_API_KEY=[REDACTED] # 模型服务地址 FUNASR_ENDPOINT=http://localhost:8080 HERMES_ENDPOINT=http://localhost:8642/v1 # 可选服务 DIARIZATION_ENABLED=false INDEX_TTS_ENABLED=false # 已禁用，内存不足 ``` #### Step 3.2: 验证配置文件 ```bash # 检查 docker-compose.yml docker compose config # 检查配置加载 cat .env | grep -v SECRET ``` --- ### Phase 4: 启动服务（Day 1） #### Step 4.1: 一键启动 ```bash chmod +x scripts/start.sh ./scripts/start.sh ``` #### Step 4.2: 手动分步启动（调试用） ```bash # 1. 启动 LiveKit Server docker compose up -d livekit-server # 2. 等待健康检查通过 sleep 10 docker compose ps # 3. 启动 FunASR docker compose up -d funasr # 4. 启动 Hermes LLM docker compose up -d hermes # 5. 启动 Agent Worker docker compose up -d agent-worker ``` #### Step 4.3: 验证服务状态 ```bash # 查看所有服务 docker compose ps # 检查健康状态 curl http://localhost:7880/health # LiveKit curl http://localhost:8080/health # FunASR curl http://localhost:8642/health # Hermes curl http://localhost:8640/health # Agent Worker ``` --- ### Phase 5: 测试验证（Day 2） #### Step 5.1: Web UI 测试 ``` 打开浏览器访问：http://localhost:7880 - 创建房间测试 - 音频连接测试 ``` #### Step 5.2: Agent 对话测试 ```bash # 测试 STT 接口 curl -X POST http://localhost:8080/stream \ -H "Content-Type: audio/wav" \ --data-binary @test_audio.wav # 测试 Hermes API curl http://localhost:8642/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"messages":[{"role":"user","content":"你好"}]}' ``` #### Step 5.3: 端到端延迟测试 ```bash # 运行延迟测试脚本 python scripts/test_latency.py ``` --- ### Phase 6: 生产部署（Day 3+） #### Step 6.1: 服务器配置 | 配置 | 规格 | 说明 | |------|------|------| | CPU | 8核+ | 推荐 AMD EPYC 或 Intel Xeon | | 内存 | 16GB+ | 当前 8GB 可运行基础功能 | | 磁盘 | 50GB+ | 存储模型和日志 | | 网络 | 100Mbps+ | 支持多人会议 | #### Step 6.2: 域名与 HTTPS ```bash # 配置 Nginx 反向代理 # 或使用 Traefik 自动 HTTPS ``` #### Step 6.3: 监控与告警 ```bash # 启动监控服务 docker compose up -d prometheus grafana # 访问 Grafana open http://localhost:3000 # 默认账号: admin / admin ``` --- ## 📊 资源占用估算 ### CPU-only 部署内存预算 | 服务 | 镜像/状态 | 内存限制 | 实际占用 | |------|-----------|----------|----------| | LiveKit Server | `livekit/livekit-server:latest` | 512MB | ~200MB | | FunASR | `funasr-runtime-sdk-cpu-0.4.7` | 1GB | ~500MB | | Hermes | 自建镜像 | 512MB | ~300MB | | Agent Worker | 自建镜像 | 512MB | ~300MB | | Prometheus | `prom/prometheus:latest` | 256MB | ~200MB | | Grafana | `grafana/grafana:latest` | 256MB | ~150MB | | **总计** | | **~3GB** | **~1.7GB** | > 当前 8GB 内存足够运行，预留约 6GB 给系统和其他应用 --- ## 🔧 故障排查 ### 常见问题 | 问题 | 原因 | 解决方案 | |------|------|----------| | `docker compose up` 失败 | 端口冲突 | `docker compose down` 后重启 | | FunASR 启动慢 | 模型加载 | 首次启动等待 2-3 分钟 | | Agent 无响应 | Hermes 未就绪 | 检查 `docker compose logs hermes` | | 音频不清晰 | VAD 阈值 | 调整 TEN VAD threshold=0.5 | | OOM 错误 | 内存不足 | 关闭 pyannote 或增加 swap | ### 日志查看 ```bash # 查看所有服务日志 docker compose logs -f # 查看特定服务 docker compose logs -f funasr docker compose logs -f hermes docker compose logs -f agent-worker ``` --- ## 📁 项目文件清单 ``` livekit-agents/ ├── agent.py # Agent Worker 主入口 ├── requirements.txt # Python 依赖 ├── Dockerfile.agent # Agent Docker 镜像 ├── docker-compose.yml # 服务编排 ├── .env.example # 环境变量模板 ├── .env.dev # 开发环境配置 ├── README.md # 项目说明 │ ├── config/ │ ├── livekit.yaml # LiveKit 配置 │ ├── hermes.yaml # Hermes 配置 │ └── prometheus.yml # 监控配置 │ ├── scripts/ │ ├── download_models.sh # 模型下载脚本 │ ├── start.sh # 一键启动脚本 │ └── test_latency.py # 延迟测试脚本 │ ├── services/ │ └── index-tts/ # IndexTTS 服务（已禁用） │ ├── hermes/ │ └── Dockerfile # Hermes 镜像构建 │ └── monitoring/ ├── prometheus.yml └── grafana/ ├── dashboards/provider.yml └── datasources/prometheus.yml ``` --- ## 🚀 快速启动命令 ```bash # 一键部署 cd ~/Projects/livekit-agents ./scripts/start.sh # 访问地址 echo "LiveKit Dashboard: http://localhost:7880" echo "Grafana: http://localhost:3000" echo "Prometheus: http://localhost:9090" ``` --- ## 📞 技术支持 - PRD 文档: `/Users/leo/.hermes/workspace/livekit_agents_PRD.md` - 代码仓库: `/Users/leo/.hermes/workspace/livekit-agents/` - 监控系统: `http://localhost:3000` (admin/admin)