# 本地语音转写服务（eai_agentplatform-asr）

> 这份文件是给**运维/交付工程师**看的，装完机器后遇到「转写失败」时先读它。
> 服务的 systemd 单元里 `Documentation=` 指向本文件。

---

## 它是什么

一个只监听回环地址的 Python 服务，提供 OpenAI 兼容的转写端点：

| 端点 | 用途 |
|---|---|
| `POST /v1/audio/transcriptions` | 转写（含说话人分离） |
| `GET /v1/models` | 健康探测用的探针端点 |

- **监听**：`127.0.0.1:8090` —— 只回环，不在局域网上暴露
- **模型**：faster-whisper large-v3 + pyannote 3.1
- **为什么要它**：把客户会议录音的转写留在本机。平台默认语音路由指向它，
  音频不出本机；它不可用时平台才回退云端，并在界面上标注「音频已离开本机」。

---

## 怎么确认它是好的

```bash
systemctl status eai_agentplatform-asr          # active (running)
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8090/v1/models   # 期望 200
journalctl -u eai_agentplatform-asr -n 50 --no-pager
```

平台侧从**后台 → AI 路由 → 语音**看 `本地` 那条的 `healthy` 是否为真；
或直接打后端接口：

```bash
curl -s -H "Authorization: Bearer <token>" http://127.0.0.1:8080/api/ai/routes/audio
```

---

## 它挂了会怎样（重要）

**不会报错给用户，而是静默回退云端。** 这正是需要有人盯着它的原因：

1. `audio_route_auto` 探测到本地不健康 → 改选 `fallback_routes` 里的云端路由；
2. 转写照常成功，但**录音已经出了本机**；
3. 界面在转写结果上标注「音频已离开本机」——这是唯一的用户可见信号。

所以：**如果这台机器的定位是「音频不许出本机」，本服务必须一直 active。**
单元里 `Restart=always` 就是这个意思；不要改成 `on-failure`。

---

## 排障顺序

| 症状 | 先看这里 |
|---|---|
| 服务起不来 | `journalctl -u eai_agentplatform-asr -n 100` |
| CUDA OOM | 显存被别的进程占了（本机 llama-server 常态占约 5G，卡总共 8G）。见 `bugs_and_errors.md` E06 |
| 加载模型挂住不报错 | 是否有分支想回 `huggingface.co`。本机到那边不通，`HF_HUB_OFFLINE=1` / `TRANSFORMERS_OFFLINE=1` 会让它立刻失败而不是挂起 |
| 平台显示本地不健康但服务是好的 | 端口对不上。端口写在 unit 的 `ExecStart --port` 与后端 `config/ai_config.json` 的 `audio_route_local_whisper.base_url` 两处，改一处没用 |
| 平台显示本地不健康，且刚重启过服务 | 平台每 30 分钟探一次。后台点一次保存/重载会立刻重探（`POST /api/ai/reload`） |

---

## 装 / 卸

装：`sudo bash deploy/install_asr_local.sh`（见 `DELIVERY.md` 第 2.5 节）

卸（会删掉 13.5 GB 的 venv 与模型，先确认目标机不再需要本地转写）：

```bash
sudo systemctl disable --now eai_agentplatform-asr
sudo rm -rf /opt/eai_agentplatform-asr
sudo rm -f /etc/systemd/system/eai_agentplatform-asr.service
sudo systemctl daemon-reload
```

卸完记得把后台的**默认语音路由**切到云端，否则 `audio_route_auto` 会一直
在一条永远不健康的本地路由上打转，每次都白等一轮探测超时。