# 独立自动转写 / 人声分离服务

算力服务器 CPU 单队列运行 FunASR Paraformer（含 FSMN VAD / CT-Transformer 标点）与 HTDemucs；48 仅进行有界素材准备、状态管理、对象存储归档。CPU 推理不占用千问或视频高清的显存。systemd 限制 4 核 / 12GiB；Python 推理线程 2；一次一个作业。

## 安装

Python 3.12 独立环境，先从官方 `https://download.pytorch.org/whl/cpu` 安装 torch/torchaudio 2.6.0 CPU wheel，再安装 `requirements.txt`。运行 `prepare_models.py` 下载 `models.json` 中固定 SHA-256 的官方语音模型运行文件；模型说明文档可变化，不参与运行文件校验。运行 `services/smart-edit/prepare_separation.py` 安装固定 SHA-256 的官方 HTDemucs。权重不进入 Git。

`node services/audio-processing/build.cjs` 产出 bundle 和 Python 脚本，安装到 `/opt/audio-processing/current/`。设置仅 root 可读的 `/etc/audio-processing.env`：

- `AUDIO_API_TOKEN`：独立随机密钥，至少 32 字符。
- `AUDIO_PORT=18342`，`AUDIO_HOST=127.0.0.1`。
- `AUDIO_PYTHON=/opt/audio-processing/venv/bin/python`。
- `AUDIO_DATA_DIR=/var/lib/audio-processing`，由专用 `audio-processing` 用户持有。
- `SMART_EDIT_ASR_MODEL`、`SMART_EDIT_VAD_MODEL`、`SMART_EDIT_PUNC_MODEL`：三个完整本地模型目录。
- `SMART_EDIT_SEPARATION_MODEL_DIR`：HTDemucs 目录。
- `HF_HOME`、`MODELSCOPE_CACHE`、`XDG_CACHE_HOME`：服务数据目录下的可写缓存。

部署 `audio-processing.service` 和私有反向 SSH 隧道，沿用专用受限隧道账号，仅增加 localhost 18342 监听权限。主项目配置 `SMART_EDIT_AUDIO_URL=http://127.0.0.1:18342` 与匹配的 `SMART_EDIT_AUDIO_TOKEN`。模型或服务不可用时能力接口返回 false，不自动切回主机重推理。

## 协议与恢复

全部接口需要 Bearer 认证，禁止面向公网暴露。

1. `POST /v1/audio-jobs`：`{id,tenant,plan:{operation,sha256,bytes}}`，operation 为 transcribe / separate；id 与 tenant 是 64 位十六进制。
2. 新任务为 awaiting-input；`PUT /v1/audio-jobs/:id/input` 上传原始 WAV。流式校验大小和 SHA-256，通过后才入队。
3. `GET /v1/audio-jobs/:id` 返回真实状态、字幕时间戳或两音轨校验值。分离结果通过 `/vocals`、`/background` 下载。
4. `GET /health` 认证后返回能力与队列状态；启动时检查模型和依赖是否存在。

客户端编号取决于用户隔离标识、持久主任务编号、操作和输入内容；重试复用同一任务，参数冲突 409。状态先 fsync 再确认成功；先持久化结果再清理输入，避免重启丢失结果。正在执行的任务重启后继续，最多三次。网络中断和队列繁忙保存为可恢复状态，失败不会冒充生成结果。

仅允许 180 秒以内 PCM WAV、1/2 声道、固定采样率；分离输入必须 44.1kHz 双声道。单文件 ≤70MiB；30 个待处理/待上传作业、200 个记录；结果 7 天清理；剩余磁盘不足10GiB停止接新处理。每作业10分钟处理超时。请求不能指定模型、命令或本地路径；推理关闭联网更新，模型代码禁止 trust_remote_code。

模型来源：[FunASR](https://github.com/modelscope/FunASR)、[官方 Paraformer](https://modelscope.cn/models/iic/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch)、[Demucs](https://github.com/facebookresearch/demucs)。保留安装包许可证和模型说明。

真实 API 验证脚本：`AUDIO_QA_ENV=/etc/audio-processing.env <venv-python> scripts/qa/audio-processing-service.py speech.wav mixed.wav output-dir --restart`。仅在专用测试或空闲服务部署窗口使用 `--restart`；使用合成测试语音，脚本会重启该服务验证恢复。凭据、模型、输入和输出不提交 Git。