deploy standalone ASR pipeline on tools-pve

2026-09-18 02:32:14 -07:00
parent f30f72b295
commit b23f00f41a
38 changed files with 182773 additions and 0 deletions
@@ -0,0 +1,51 @@
+# ASR Pipeline on tools-pve
+
+独立的录音转写、精修、人工审核和导出服务。WebUI 与 Agent API 共用 `192.168.50.49:8788`；worker 调用 unRaid 上的 Qwen3-ASR/CAM++ 服务以及 ZenMux 模型 API。
+
+## 数据边界
+
+- `/mnt/truenas/personal/ASR-Pipeline` → 容器 `/data`：原始录音、转写、ASR 原始响应、草稿、正式稿、日志和 SQLite 在线备份。
+- `/opt/asr-pipeline/state` → 容器 `/state`：活动 SQLite、worker heartbeat、revision queue。SQLite WAL 不放在 NFS。
+- `/srv/asr/inbox`：指向 TrueNAS inbox 的宿主机链接，供 `scp`/`sftp` 上传。
+- `.env`：仅存在 Arcane Project / tools-pve，权限 `0600`，不进入 Git。
+
+SSH 大文件建议先上传为 `.part`，完成后在同一目录原子改名为受支持扩展名：
+
+```bash
+scp call.m4a tools@192.168.50.49:/srv/asr/inbox/call.m4a.part
+ssh tools@192.168.50.49 'mv /srv/asr/inbox/call.m4a.part /srv/asr/inbox/call.m4a'
+```
+
+## Agent API
+
+所有 `/api/v1/*` 路由使用 `Authorization: Bearer $ASR_AGENT_TOKEN`。
+
+```bash
+curl -X POST http://192.168.50.49:8788/api/v1/jobs \
+  -H "Authorization: Bearer $ASR_AGENT_TOKEN" \
+  -H 'X-Filename: call.m4a' -H 'X-Title: 项目通话' \
+  -H 'X-Context: 参与人和项目背景' --data-binary @call.m4a
+
+curl -H "Authorization: Bearer $ASR_AGENT_TOKEN" \
+  http://192.168.50.49:8788/api/v1/jobs/JOB_ID
+```
+
+路由：
+
+- `POST /api/v1/jobs`：上传并创建异步任务。
+- `GET /api/v1/jobs?limit=&offset=&status=`：分页查询。
+- `GET /api/v1/jobs/{id}`：任务详情、事件时间线与产物链接。
+- `GET /api/v1/jobs/{id}/artifacts/{transcript|draft|result}`：读取产物。
+- `GET /api/v1/jobs/{id}/reviews`：待人工确认项。
+- `POST /api/v1/jobs/{id}/reviews/{question_id}`：JSON `{"answer":"..."}`。
+- `POST /api/v1/jobs/{id}/retry`：重试失败任务。
+
+`/healthz` 仅表示 Web 进程存活；`/readyz` 同时检查数据库与 worker heartbeat。
+
+## 通知
+
+`ASR_NOTIFY_BACKEND=none|telegram|hermes`。Telegram 需要 `TELEGRAM_BOT_TOKEN` 与 `TELEGRAM_CHAT_ID`；Hermes 需要一个明确存在的签名 webhook URL 与共享密钥。发送失败只影响提醒，不改变任务结果。
+
+## 运维
+
+项目由 Arcane Git Sync 管理，自动同步、自动 pull 和自动 redeploy 均关闭。Compose 变更先在 Git 中验证，再对 tools-pve 的准确 Sync 手动同步。活动数据库每小时通过 SQLite backup API 写到 `/data/backups/*.latest`。