# FunASR 部署架构说明

## 当前实际部署方式

**FunASR 是本地 Python FastAPI 服务，不是 Docker 容器。**

### 为什么不用 Docker？

1. **网络限制**：国内无法拉取阿里云镜像仓库
   ```
   registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.4.7
   ```

2. **已验证可行**：本地 Python 服务通过测试，STT 功能正常

### 部署方式对比

| 方案 | 状态 | 端口 | 说明 |
|------|------|------|------|
| **FunASR (本地 Python)** | ✅ 运行中 | 8080 | FastAPI + SenseVoiceSmall |
| LiveKit Server | ✅ Docker | 7880 | 官方镜像 |
| Prometheus/Grafana | ⚠️ 可选 | 9090/3000 | 监控面板 |
| Hermes LLM | ❌ 未部署 | 8642 | 用户连接外部 API |

### FunASR 本地服务详情

**启动命令**：
```bash
# 方式1：直接运行
python3 services/funasr_stt_server.py

# 方式2：使用启动脚本
./scripts/start_funasr.sh
```

**服务信息**：
- PID: 9348（启动后自动运行）
- 地址: http://localhost:8080
- 健康检查: `curl http://localhost:8080/health`
- 模型: SenseVoiceSmall（内置 VAD）

**STT 测试**：
```bash
# 验证服务正常
curl -s http://localhost:8080/health
# 返回: {"status":"healthy","model_loaded":true,...}
```

### docker-compose.yml 状态

FunASR 配置被注释掉（Line 37-38）：
```yaml
# 启动命令: ./scripts/start_funasr.sh
# 服务地址: http://localhost:8080
# funasr:
#   image: registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-cpu-0.4.7
```

注释原因：
- 国内网络无法访问阿里云镜像仓库
- 本地 Python 服务已验证可用
- 避免 Docker Hub 拉取超时

### 组件间通信架构

```
┌─────────────────────────────────────────────┐
│           Agent Worker (Python)              │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │ STT     │  │ LLM     │  │ TTS     │    │
│  │ HTTP    │  │ HTTP    │  │ Local   │    │
│  └────┬────┘  └────┬────┘  └────┬────┘    │
│       │             │             │         │
│  ┌────▼────┐  ┌────▼────┐  ┌────▼────┐    │
│  │FunASR   │  │Agnes AI │  │Edge TTS │    │
│  │:8080    │  │(云端)   │  │(本地)   │    │
│  └─────────┘  └─────────┘  └─────────┘    │
└─────────────────────────────────────────────┘
              ↕
┌─────────────────────────────────────────────┐
│         LiveKit Server (Docker)              │
│         :7880 / :7881                        │
│         WebRTC SFU + Agent 路由             │
└─────────────────────────────────────────────┘
```

### 总结

- **FunASR STT**: 本地 Python FastAPI 服务（推荐）
- **LiveKit Server**: Docker 容器
- **LLM/TTS**: 云端 API + 本地服务混合
- **监控**: 可选 Prometheus + Grafana

## 更新记录

- 2026-09-21: 明确 FunASR 为本地 Python 服务，非 Docker
- 2026-09-21: 添加网络限制说明