Local Asr

本地 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
• 转录后自动附带 AI 总结提示词，Agent 可一步完成总结
• API 返回转录、截图、归档、摘要等阶段耗时；可通过 include_summary_prompt=false 跳过摘要准备
• 输出 Markdown 格式，便于阅读和编辑

依赖

系统依赖

Python 包

默认安装在 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 核对设备、依赖、权重 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++ 说话人聚类：

单人 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/ 不存在时先按上文创建并安装。

步骤 0：环境检测（自动）

在执行转录前，检查 assets/skill-env.json 是否存在，且其中 FUNASR_SERVER_DEFAULT_MODEL 为 moss-mlx、FUNASR_PYTHON 指向已安装 MLX-Audio 的 Python。旧配置需要加 --force 重新检测：

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

若配置仍指向旧环境，运行 python3 scripts/init_env.py --force，并确认其中的 FUNASR_PYTHON 指向 venv/bin/python。

如果检测失败（退出码非0），按提示运行安装脚本：

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

安装完成后会自动重新检测并生成 skill-env.json。

步骤 1：启动/检查服务

cd <skill目录> && export PATH="$PWD/venv/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && curl -s http://127.0.0.1:8765/health

如果服务未运行，后台启动：

cd <skill目录> && export PATH="$PWD/venv/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && python3 scripts/server.py --idle-timeout 600 &

等待服务就绪（轮询 /health 直到返回 200）。

步骤 2：转录文件

cd <skill目录> && export PATH="$PWD/venv/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && curl -s -X POST http://127.0.0.1:8765/transcribe \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/path/to/audio.aac"}'

注意：diarize 默认为 true，无需显式传入。如需禁用，传 "diarize": false。 视频文件（mp4、mov 等）会自动启用关键帧截图提取（extract_slides），无需手动传入。如需禁用，显式传 "extract_slides": false。 单人讲课/语音可传 "fast": true 关闭说话人分离，仍使用默认 MOSS；"model": "paraformer" 或 "model": "paraformer-onnx" 可调用原 FunASR 管线。

响应中包含以下关键字段：

• output_path: 转录输出的 Markdown 文件路径
• text: 转录全文
• summary_prompt: AI 总结提示词（已自动附带，无需额外调用 /summary）
• text_preview: 转录文本前 500 字预览

步骤 3：说话人识别与认领（默认 MOSS 路径）

转录响应中的 speaker_identification 逐人显示每个说话人是否已被声纹库识别（{"S01": {"name": "杨律师", "score": 0.74}, "S02": null}；首次空库时全部为 null）。已命中的说话人在 Markdown 中直接显示注册名。

speaker_states 为每位说话人给出完整状态，按状态决定下一步动作：

• matched：已命中注册声纹（name 为注册名），无需询问；
• unknown：有声纹向量但未达阈值，可认领注册——按下述流程询问用户；
• insufficient_audio：总发言不足 3 秒，无声纹向量，只能根据用户说明在 Markdown 中为本稿标注，不能注册；
• extraction_failed：声纹提取/识别失败，本次无法识别或认领，可提示用户重试；
• disabled：说话人声纹识别未启用（fast/显式关闭/CAM++ 不可用），跳过认领流程。

当存在 unknown 状态的说话人时，必须先向用户逐一确认身份再继续。询问前，先根据响应 segments（每段含 speaker 与 text）为每位未识别说话人生成一段简要叙述，随问题一并呈现，供用户凭内容判断身份——这是打标的主要依据，不要只报编号：

叙述格式（每位说话人 2-3 句，基于其全部发言归纳）：

• 发言占比：该说话人发言时长/段数占全会的比例；
• 内容概述：他说了什么——诉求、立场、给出的信息、向谁发问；
• 身份线索：自称（"我是杨律师"）、被对方称呼（"张女士"）、角色口吻（咨询方/解答方/主导方）。

示例呈现："转录完成，共 2 位说话人。发言人1（占 35% 发言）：自述是房东，询问拖欠房租的起诉流程，多次被对方称为'张女士'。发言人2（占 65% 发言）：以律师口吻分析证据和诉讼策略，开头说'诶，张女士'。请问这两位分别是谁？"

用户回答"是我"、"客户张三"或"不用标"后，对命名的说话人执行认领注册：

curl -s -X POST http://127.0.0.1:8765/speaker/register \
  -H "Content-Type: application/json" \
  -d '{"name": "<用户确认的名字>", "embedding": <响应 speaker_embeddings 中该标签的数组>, "source_file": "<文件名>", "source_label": "S01"}'

• 认领完成后当前 Markdown 无需重跑；下一份录音中同一人将自动识别标注。
• 用户表示"不用标"的说话人保持匿名，不注册。用户只是说明某说话人本稿身份而不愿长期注册时，直接在 Markdown 中标注，不调用注册。
• 客户或第三方声纹的注册须先取得其单独同意（声纹属敏感个人信息）；本人声纹无此要求。完整流程、阈值与纠错见 references/speaker-registry.md。
• 推荐入口（auto_transcribe.py）可用 --json 获取完整响应（含识别结果与向量）、--save-result 保存结果文件；认领时用 python3 scripts/speaker_registry.py claim <名字> --result <结果JSON> --label S01 按标签确定性取向量，避免手工复制 192 个浮点数。

步骤 4：生成 AI 总结

根据 summary_prompt（或直接根据 text 内容），Agent 生成结构化 JSON 总结：

{
  "full_summary": "至少400字，分成2-3段，交代背景、问题、关键事实、数据、风险与行动建议",
  "speaker_summary": [
    {
      "speaker_order": "发言人1",
      "speaker_name": "如能识别请写姓名，否则写未知",
      "summary": "至少180字，涵盖该发言人的观点、依据、数据、态度与潜在影响"
    }
  ],
  "highlights": ["6-10条重点，每条60-100字"],
  "keywords": ["5-8个关键词"]
}

步骤 5：注入总结到文件

重要：不要只描述注入操作，必须实际执行以下命令。

将步骤 3 生成的 JSON 写入临时文件，然后调用脚本注入（比 curl 注入更可靠，无需 JSON 转义）：

export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && cat > /tmp/summary_<文件名>.json << 'JSONEOF'
{步骤3生成的JSON内容}
JSONEOF
python3 <skill目录>/scripts/summary.py inject "<output_path>" /tmp/summary_<文件名>.json

脚本会自动：

• 解析 JSON 并格式化为 Markdown
• 注入到 Markdown 文件的正确位置
• 添加 <!-- AI-SUMMARY:START --> / <!-- AI-SUMMARY:END --> 标记

步骤 6：验证注入结果（必须执行）

注入后必须执行验证，确认摘要确实写入文件。如果验证失败，必须重试步骤 5。

export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && python3 <skill目录>/scripts/summary.py verify "<output_path>"

• 如果输出 ✅ 摘要已存在 且 ✅ 发言人覆盖完整 → 成功，向用户报告完成
• 如果输出 ❌ 摘要不存在 → 失败，回到步骤 5 重试
• 如果输出 ❌ 摘要遗漏发言人 / ❌ 摘要出现稿件中不存在的发言人 / ❌ 缺少必需章节（退出码非零）→ 说明总结遗漏/虚构发言人或缺章节，回到步骤 4 按 speaker_states/正文标签重新生成总结后再次注入；覆盖不完整或缺章节的摘要不得作为已验收交付
• inject 命令本身也会在覆盖不完整或缺必需章节时以非零退出（打印"摘要质量未通过"，注入内容保留为草稿）：写入成功 ≠ 质量通过，见非零退出必须回到步骤 4 重新生成，不得当作已交付
• 总结 JSON 中同一发言人出现多条（重复凑人数，包括其中一条摘要为空）时，inject 直接拒绝写入并指出重复标签 → 重新生成含全部发言人的总结
• 输出 ⚠️ 发言人覆盖无法验证（fast/无发言行结构稿件）→ 章节完整即可交付，如实说明覆盖未验证
• HTTP /inject_summary、/verify_summary 的 success 只表示调用执行成功；质量以响应中的 quality_passed / speaker_coverage 字段为准，不得只凭 success 宣布已交付

完整流程示例

用户：转录这个音频
  ↓
Agent：
  1. 检查/启动服务
  2. POST /transcribe {"file_path": "xxx.aac"}  ← 一次调用拿到转录+识别结果+提示词
  3. 按 speaker_states 处理：unknown 说话人询问用户身份 → POST /speaker/register 认领注册
     （insufficient_audio 只能本稿标注，不能注册）
  4. 根据转录内容直接生成总结 JSON（speaker_order 逐字用稿件发言标签）
  5. 写 JSON 到临时文件 → python3 summary.py inject 注入
  6. python3 summary.py verify 验证（含发言人覆盖）→ 失败则重试步骤 4-5
  ↓
用户：收到带 AI 总结的 Markdown 文件

使用流程

首次使用：环境检测与依赖安装

重要：首次使用前必须先检测环境是否满足要求。

运行环境检测：

python3 scripts/check_env.py

检测脚本会检查以下环境要求：

如果环境检测失败：

1. Python3 命令不可用：

   # macOS 使用 homebrew 安装 Python
   brew install python@3.14

2. curl 不可用：

   # macOS 确保 curl 已安装
   brew install curl

3. 验证环境修复后，重新运行检测：

   python3 scripts/check_env.py

首次使用：安装依赖和下载模型

运行安装脚本完成环境配置：

/opt/homebrew/bin/python3.11 -m venv venv
source venv/bin/activate
python3 scripts/setup.py

安装脚本会自动：

1. 检查 Apple Silicon 和 Python 版本（默认双后端安装需 3.10–3.12）
2. 安装依赖包（FastAPI、FunASR/CAM++、MLX-Audio 等；旧管线依赖一并保留）
3. 下载 MOSS 和 CAM++ 模型到 ModelScope 缓存；--legacy 只安装旧 FunASR 模型

验证安装状态：

python3 scripts/setup.py --verify