# LiveKit Voice AI 框架

基于 LiveKit Agents 的实时语音 AI 框架，支持 STT/TTS/LLM 全链路本地部署。

## 架构

```
客户端 → LiveKit Server (WebRTC) → Agent Worker → FunASR (STT) → Hermes (LLM) → IndexTTS (TTS)
                                                          ↓
                                                    pyannote (说话人分离)
```

## 特性

- ✅ **低延迟**: 端到端 <300ms
- ✅ **本地部署**: 无云端 API 依赖
- ✅ **流式处理**: 边说边识别边回复
- ✅ **打断逻辑**: VAD+STT 语义判断
- ✅ **多Agent**: 可扩展的角色切换
- ✅ **监控**: Prometheus + Grafana

## 快速开始

### 1. 环境准备

```bash
# 安装 Docker Desktop
https://www.docker.com/products/docker-desktop/

# 克隆项目
git clone <your-repo>
cd livekit-agents
```

### 2. 配置

```bash
# 复制环境变量模板
cp .env.example .env

# 编辑配置
vim .env
```

### 3. 下载模型

```bash
# 赋予执行权限
chmod +x scripts/download_models.sh

# 运行下载脚本
./scripts/download_models.sh
```

### 4. 启动服务

```bash
chmod +x scripts/start.sh
./scripts/start.sh
```

### 5. 验证

```bash
# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 测试 API
curl http://localhost:8080/health
curl http://localhost:8081/health
curl http://localhost:8642/health
```

## 目录结构

```
livekit-agents/
├── docker-compose.yml      # 服务编排
├── .env.example            # 环境变量模板
├── config/
│   ├── livekit.yaml        # LiveKit 配置
│   └── hermes.yaml         # Hermes LLM 配置
├── models/                  # 模型目录
│   ├── funasr/
│   └── pyannote/
├── checkpoints/             # IndexTTS 模型
├── services/
│   └── index-tts/          # IndexTTS 服务
├── hermes/                  # Hermes LLM 服务
├── monitoring/
│   ├── prometheus.yml      # Prometheus 配置
│   └── grafana/            # Grafana 配置
└── scripts/
    ├── download_models.sh  # 模型下载脚本
    └── start.sh            # 启动脚本
```

## 服务端口

| 服务 | 端口 | 用途 |
|------|------|------|
| LiveKit Server | 7880/7881 | WebRTC 信令+媒体 |
| FunASR STT | 8080 | 语音识别 |
| IndexTTS | 8081 | 语音合成 |
| pyannote | 8082 | 说话人分离 |
| Hermes API | 8642 | LLM 路由 |
| Prometheus | 9090 | 指标采集 |
| Grafana | 3000 | 监控大屏 |

## 硬件要求

| 场景 | CPU | 内存 | GPU | TTS |
|------|-----|------|-----|-----|
| **当前方案** | 4核 | 8GB | 无 | 禁用（省内存） |
| 完整版 | 8核 | 16GB+ | 无 | 需启用 IndexTTS |
| 生产环境 | 8核+ | 16GB | 可选 | 需启用 IndexTTS |

### 内存预算（当前方案）

| 组件 | 内存占用 |
|------|----------|
| LiveKit Server | ~200MB |
| FunASR (STT) | ~500MB |
| Hermes LLM | ~300MB |
| pyannote | ~500MB |
| Agent Worker | ~300MB |
| **总计** | **~1.8GB** ✅ 8GB够用 |

### 启用 TTS 需要额外

- IndexTTS: ~2GB 内存
- 建议升级到 16GB 内存或禁用 pyannote

## 性能基准

- **端到端延迟**: <300ms (CPU)
- **并发用户**: 5-10人 (8GB RAM)
- **STT RTF**: ~0.05 (SenseVoiceSmall, CPU)
- **TTS 延迟**: ~200ms/句

## 故障排查

### 服务无法启动

```bash
# 查看详细日志
docker-compose logs <service-name>

# 重启服务
docker-compose restart <service-name>
```

### 模型加载失败

```bash
# 检查模型目录
ls -la models/funasr/SenseVoiceSmall

# 重新下载模型
./scripts/download_models.sh
```

### 内存不足

```bash
# 停止不需要的服务
docker-compose stop pyannote hermes

# 减少内存限制
# 编辑 docker-compose.yml 中的 deploy.resources.limits.memory
```

## 扩展开发

### 自定义 Agent

```python
# 创建 services/agents/my_agent.py
from livekit.agents import JobContext, AutoSubscribe
from livekit.agents.voice import AgentSession

async def entrypoint(ctx: JobContext):
    session = AgentSession(
        stt="funasr",
        llm="hermes",
        tts="indextts"
    )
    await session.start(agent="my-agent", room=ctx.room)
    await ctx.connect(auto_subscribe=AutoSubscribe.AUDIO_ONLY)
```

### 添加新技能

```bash
# 创建技能目录
mkdir -p skills/my-skill

# 添加技能实现
cat > skills/my-skill/skill.py << 'EOF'
from hermes.skills import Skill

class MySkill(Skill):
    name = "my-skill"
    description = "我的自定义技能"
    
    async def execute(self, context):
        # 技能逻辑
        return "结果"
EOF
```

## 参考文档

- [LiveKit 文档](https://livekit.io/docs)
- [FunASR 文档](https://github.com/modelscope/FunASR)
- [IndexTTS 文档](https://huggingface.co/IndexTeam/IndexTTS-2.5)
- [Hermes Agent 文档](https://hermes-agent.nousresearch.com/docs)

## License

MIT