openclaw/skills/kb-funasr/SKILL.md

name, description

name	description
kb-funasr	本地语音识别 - 使用阿里 FunASR 进行中文优化的语音识别

KB FunASR Skill

kb-funasr - 本地语音识别，使用阿里 FunASR 将音视频文件转换为文本。

什么时候使用

• kb-workflow 步骤 4 的备选方案：当 Whisper 效果不佳时
• 中文语音识别（Paraformer 模型对中文优化）
• 需要高精度中文识别

环境变量

变量名	必需	说明
FUNASR_CACHE_DIR	否	FunASR 模型缓存目录

命令

# 基本用法（使用 Paraformer 中文模型，推荐）
python3 funasr_tool.py --input video.mp4

# 指定模型
python3 funasr_tool.py --input video.mp4 --model paraformer-zh

# 指定输出目录
python3 funasr_tool.py --input video.mp4 --output ./output

# 后台异步执行
python3 funasr_tool.py --input video.mp4 --background

参数说明

参数	说明	默认值
--input	输入音视频文件路径	必需
--model	FunASR 模型类型	paraformer-zh
--output	输出目录	文件所在目录
--background	后台异步执行	False

模型选项

模型	说明	推荐场景
paraformer-zh	Paraformer 中文模型	推荐，中文优化
paraformer	Paraformer 多语言模型	多语言场景
sensevoice	SenseVoice 模型	高精度需求

输出格式 Schema

必需字段

字段	类型	说明
success	boolean	是否识别成功
input_file	string	输入文件路径
model	string	使用的模型

可选字段

字段	类型	说明
output_files	object	输出文件路径
duration_seconds	number	音频时长
segments	array	识别分段
error	string	错误信息

成功示例

{
  "success": true,
  "input_file": "content/downloads/bilibili_BV1xx411c7mD.mp4",
  "model": "paraformer-zh",
  "output_files": {
    "json": "content/bilibili_BV1xx411c7mD_funasr.json",
    "txt": "content/bilibili_BV1xx411c7mD_funasr.txt"
  },
  "duration_seconds": 630.5,
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 3.2,
      "text": "这是第一段识别结果"
    },
    {
      "id": 1,
      "start": 3.2,
      "end": 6.5,
      "text": "这是第二段识别结果"
    }
  ]
}

错误示例

模型未下载

{
  "success": false,
  "error": "模型未找到",
  "model": "paraformer-zh",
  "suggestion": "首次运行时会自动下载模型，请确保网络连接正常"
}

文件不存在

{
  "success": false,
  "error": "输入文件不存在",
  "input_file": "content/downloads/missing.mp4"
}

内存不足

{
  "success": false,
  "error": "内存不足",
  "suggestion": "尝试使用较小的模型或处理较短的音频片段"
}

安装

# 1. 安装依赖
pip install funasr modelscope

# 2. 首次运行时自动下载模型
python3 funasr_tool.py --input test.mp4

# 3. 复制技能
cp -r kb-funasr/ ~/.openclaw/skills/

在 kb-workflow 中的使用

# 步骤 4 的备选方案（当 Whisper 效果不佳时）
python3 ~/.openclaw/skills/kb-funasr/funasr_tool.py \
    --input "content/downloads/bilibili_BV1xx411c7mD.mp4" \
    --model paraformer-zh \
    --output "content/"

# 输出：
# - bilibili_BV1xx411c7mD_funasr.json (完整结果)
# - bilibili_BV1xx411c7mD_funasr.txt (纯文本)

# 完成后进入步骤 5（深度分析）

注意事项

• 首次运行：首次运行时会自动下载模型文件（约 1GB），需要稳定网络
• 中文优化：Paraformer 模型对中文识别效果优于 Whisper
• 耗时操作：语音识别可能需要几分钟到几十分钟
• 文件格式：支持 MP3、MP4、WAV、FLAC、OGG、M4A 等常见格式
• 与 Whisper 对比：
  • Whisper：通用性强，支持多语言
  • FunASR：中文优化，精度更高