/local-asr

name: local-asr
homepage: https://github.com/cat-xierluo/legal-skills
author: 杨卫薪律师（微信ywxlaw）
version: "2.3.4"
license: MIT
description: 使用本地 ASR 服务将音频或视频文件转录为带时间戳和说话人的 Markdown，Apple Silicon 默认使用 MOSS-MLX，保留 FunASR 原生及 ONNX 管线供显式选择；支持认领式声纹注册，本人声纹注册后自动识别标注。支持 mp4、mov、mp3、wav、m4a 等格式；用于会议记录、电话录音、视频字幕和播客转录。

本地 ASR 语音转文字（MOSS 默认）

本 skill 提供本地语音识别服务，将音频或视频文件转换为结构化的 Markdown 文档。 本技能原名 `funasr-transcribe`；现以 `local-asr` 统一入口，默认引擎为 MOSS-MLX，FunASR 为可显式选择的保留后端。

功能概述

• 支持多种音视频格式（mp4、mov、mp3、wav、m4a、flac 等）
• 自动生成时间戳
• 支持说话人分离（diarization，默认启用）
• **ONNX 加速模式**：支持 `paraformer-onnx` 与实验性的 `SenseVoice-Small ONNX`
• **MOSS-MLX 默认模式**：Apple Silicon 上使用 MOSS 同时转写、标时间戳和区分匿名说话人；长录音分段后用 CAM++ 链接跨段标签
• **FunASR 保留模式**：显式指定 `--model paraformer` 或 `--model paraformer-onnx` 调用原管线
• **单人快速模式**：`--fast` / `"fast": true` 关闭 diarization，不改变所选模型
• **Paraformer ONNX 后处理优化**：`paraformer-onnx` 单人/多人路径都会先 VAD 分段，再清理文本输出、恢复标点并输出句子级时间戳；单人路径使用全局标点恢复，多人路径使用逐段标点以保留 speaker 对齐
• **视频关键帧截图提取**：视频默认自动提取，`--no-slides` 可跳过耗时截图步骤
• **声纹注册与说话人识别**：本人声纹经认领注册后，后续转录自动识别并直接标注注册名；详见 [`references/speaker-registry.md`](references/speaker-registry.md)
• 转录后自动附带 AI 总结提示词，Agent 可一步完成总结
• API 返回转录、截图、归档、摘要等阶段耗时；可通过 `include_summary_prompt=false` 跳过摘要准备
• 输出 Markdown 格式，便于阅读和编辑

依赖

系统依赖

| 依赖 | 安装方式 | |------|----------| | Apple Silicon 原生 Python 3.10–3.12（建议 3.11；完整旧管线也需此范围） | macOS: `brew install python@3.11` | | curl | macOS 通常自带；如缺失可执行 `brew install curl` | | ffmpeg（MOSS 音频归一化必需，也用于视频处理） | macOS: `brew install ffmpeg` |

Python 包

| 包名 | 用途 | 安装命令 | |------|------|----------| | `funasr` | FunASR 原生推理与 CAM++ diarization | `pip install -r assets/requirements.txt` | | `funasr-onnx` | Paraformer / SenseVoice ONNX 加速 | `pip install -r assets/requirements.txt` | | `opencv-python`、`imagehash` | 视频关键帧提取 | `pip install -r assets/requirements.txt` | | `mlx-audio[stt]` | Apple Silicon 默认 MOSS 后端 | `python3 -m pip install -r assets/requirements-moss-mlx.txt` |

默认安装在 Apple Silicon 上同时保留 FunASR/CAM++ 依赖并安装 MOSS-MLX；`python3 scripts/setup.py --legacy` 只安装原 FunASR 管线。非 Apple Silicon 使用旧管线时，启动服务前设置 `FUNASR_SERVER_DEFAULT_MODEL=paraformer`，或运行 `server-onnx.py`；CLI 仍须显式传 `--model paraformer`（或 `--model paraformer-onnx`）。 `funasr-onnx` 0.4.1 要求 NumPy ≤1.26.4，因此两套后端同装需 Python 3.10–3.12；Python 3.13+ 的 NumPy 2 环境不能据此保证旧 ONNX 路线可用。

首次安装或更换后端时，按 [`references/model-backends.md`](references/model-backends.md) 核对设备、依赖、权重 ID、下载时机和启用命令；下方保留默认后端的最短安装路径。

推荐使用技能目录内被 Git 忽略的虚拟环境，避免把 MLX-Audio 依赖装进系统 Python：

cd <skill目录>
/opt/homebrew/bin/python3.11 -m venv venv
source venv/bin/activate
python3 scripts/setup.py

以后从同一环境运行 `python3 scripts/server.py` 和 `python3 scripts/auto_transcribe.py`。已配置旧环境的用户可在该环境安装 MOSS 依赖；本机如果已经使用 `venv/`，可直接运行 `venv/bin/python`。

若已有旧版环境，首次使用默认 MOSS 前，在**启动 `server.py` 的同一个 Python 环境**安装 MOSS 依赖：

python3 -m pip install -r assets/requirements-moss-mlx.txt

`setup.py` 默认从 ModelScope 下载 MOSS 权重与 CAM++；若跳过模型下载，首次调用会优先从 Hugging Face 获取 MOSS，失败时改用 ModelScope。显式选择旧 FunASR 管线不需要 MOSS 依赖。MLX 后端仅支持 Apple Silicon macOS；长录音需要现有的 CAM++ 模型链接分段说话人。MOSS 的 `[S01]` 等标签只表示同一份录音中的匿名说话人，不识别真实姓名。

如需离线运行或固定模型路径，可通过已安装的 `modelscope` 预下载模型，并把实际输出目录传给 `--model-id`：

python3 -c "from modelscope.hub.snapshot_download import snapshot_download; print(snapshot_download('OpenMOSS/MOSS-Transcribe-Diarize'))"
python3 scripts/transcribe.py /path/to/meeting.m4a --model-id /path/to/downloaded/model

MOSS 长录音默认按约 600 秒切段，并在目标点附近选择连续静音；`FUNASR_MOSS_CHUNK_SECONDS=300` 可缩短为约 5 分钟（须重启服务）。分段说话人由 CAM++ 声纹启发式链接，短插话仍可能拆成多个标签；总发言不足 3 秒的说话人会在 `warnings` 中提示人工核对。输出时间戳越界、缺失标签或达到生成上限时会报错；近乎零波形能量的整段会跳过推理，幻觉句会被剔除并提示。此处不保证实际会议中的说话人准确率，需要对真实样本人工复核。

MOSS 性能与可选量化

默认使用原始 MOSS 权重。MLX-Audio 可把本地权重转换为 4-bit 或 8-bit 模型；量化主要减少权重与运行内存，**不保证更快或维持同样的说话人标签**。在 M1 Max 上，约 4 分半的重复合成双人语音中，原始权重两次用时 13.4/14.7 秒，4-bit 为 18.4/19.4 秒，8-bit 为 21.6/20.3 秒；量化模型更慢。短真实通话片段的量化输出还出现额外的短说话人标签，未经人工真值核对。此测试不能代替真实长录音验收。

若设备内存不足，可从**已下载的原始模型目录**生成独立量化副本，再显式选择它（目录应放在技能仓库外；首次转换需要足够的临时磁盘空间）：

python3 -m mlx_audio.convert --hf-path /path/to/original-moss-model --mlx-path /path/to/moss-q8 --quantize --q-bits 8 --model-domain stt
python3 scripts/transcribe.py /path/to/meeting.m4a --model-id /path/to/moss-q8

常驻服务可设置 `FUNASR_MOSS_MODEL_ID=/path/to/moss-q8` 后重启；恢复默认时移除该环境变量。API 请求中的 `quantize` 只控制旧 ONNX INT8 路线，**不会**量化 MOSS；CLI 没有 MOSS 自动量化开关。`FUNASR_MOSS_CHUNK_SECONDS` 可在 60–600 秒间调整输出预算与切点，但更短的分段会增加 CAM++ 跨段链接和切点风险，不应仅凭速度更改默认值。

所需权限与安全说明

读取用户指定的本地音视频，写入 Markdown、截图及技能目录下的 `archive/`。服务默认只监听 `127.0.0.1:8765`；CLI 经本机 HTTP 调用该服务，不上传音频到云端。首次安装依赖或模型时会联网访问包索引、ModelScope 或 Hugging Face，之后本地缓存可复用。脚本会调用 `ffmpeg`、Python 子进程和本地文件操作；无需 ASR API Key。含客户录音的 `archive/` 与本机生成的 `assets/skill-env.json` 仅供本地使用，不属于分享材料。

首次需要运行 ONNX 模式时，直接执行：

python3 scripts/setup.py --legacy

即可同时安装 `funasr-onnx` 及其依赖；`SenseVoiceSmall` 仅在显式指定 `model=sensevoice` 时按需下载。

ONNX 质量调参

`paraformer-onnx` 默认使用质量优先的参数组合；单人路径会复用多人路径的 ONNX VAD 分段 ASR，但不执行 CAM++ 说话人聚类：

| 参数 | 默认值 | 说明 | |------|--------|------| | `FUNASR_ONNX_TEXT_SOURCE` | `preds` | 使用清理后的 ONNX `preds` 文本；如遇到异常可设为 `raw_tokens` 回退 | | `FUNASR_SERVER_ONNX_THREADS` | `4` | ONNX Runtime 推理线程数，主要影响速度，不直接改善识别质量 | | `FUNASR_ONNX_COMPAT_CACHE` | `~/.cache/funasr-onnx-compat` | ONNX 兼容导出缓存目录；兼容导出会复制模型目录，可删除该缓存后重新生成 |

单人 `paraformer-onnx` 会将各 VAD 片段的识别文本先拼接，再做一次全局标点恢复；这样比逐片段恢复标点更接近原生 `paraformer`，也能减少重复调用标点模型的耗时。

ONNX 句子级时间戳是根据字符位置和 token 时间戳做的近似映射，适合定位段落和发言轮次，不应视为逐字强对齐结果。

已验证不建议作为默认的调参方向：

• 调大 VAD 静音阈值会减少切段并提速，但 90 秒多人样本上文本相似度下降明显。
• 合并相邻 VAD 段或整段转录更容易出现错字、重复和长音频塌缩，因此单人和多人 ONNX 都不再默认整段转录。
• 给 VAD 片段额外 padding 会引入边界重复，整体质量不如默认切段。

Agent 默认工作流（转录 + 自动总结）

当用户请求转录音频/视频时，应遵循以下流程，**一次性完成转录和 AI 总结**：

**前置步骤（必须第一个执行）：进入技能目录并设置 PATH。** 某些执行环境（如 agent-executor headless 模式）的 PATH 被限制为只有插件目录，`curl`、`python3` 等系统命令找不到。必须先执行：

cd <skill目录> && export PATH="$PWD/venv/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"

> 之后所有 bash 命令都必须在同一命令块中跟在这行后面，或在每个命令块开头重复。`venv/` 不存在时先按上文创建并安装。

步骤