openclaw-skills/skills/kb-funasr

KB FunASR - 本地语音识别

基于阿里 FunASR 的本地语音识别工具，支持将音视频文件转换为文本和 JSON 格式。

功能特性

• 🎯 本地执行 - 完全离线运行，保护隐私
• 🚀 多模型支持 - Paraformer、SenseVoice 等模型可选
• 📝 多格式输出 - JSON、TXT 两种格式
• ⚡ 异步执行 - 支持后台运行，不阻塞主代理
• 🎬 广泛兼容 - 支持常见音视频格式（MP3、MP4、WAV 等）
• 🇨🇳 中文优化 - Paraformer 模型针对中文语音优化

安装前提

1. 安装依赖

pip install funasr modelscope

2. 配置环境变量（可选）

在 ~/.clawdbot/clawdbot.json 中添加：

{
  skills: {
    entries: {
      "kb-funasr": {
        env: {
          FUNASR_CACHE_DIR: "~/.cache/modelscope/hub"
        }
      }
    }
  }
}

或通过命令行配置：

clawdbot skills config kb-funasr FUNASR_CACHE_DIR "~/.cache/modelscope/hub"

使用方法

基本用法

# 使用默认 Paraformer 中文模型处理
python funasr.py --input video.mp4

# 后台异步执行
python funasr.py --input video.mp4 --background

指定模型

# Paraformer 中文模型（推荐）
python funasr.py --input video.mp4 --model paraformer-zh

# Paraformer 多语言模型
python funasr.py --input video.mp4 --model paraformer

# SenseVoice 多语言模型
python funasr.py --input video.mp4 --model sensevoice

指定输出目录

python funasr.py --input video.mp4 --output ./transcripts

输出文件

对于输入 video.mp4，将生成以下文件：

output/
├── video.json   # 详细结果（含时间戳）
└── video.txt    # 纯文本

JSON 格式

{
  "success": true,
  "input_file": "video.mp4",
  "model": "paraformer-zh",
  "output_files": {
    "json": "video.json",
    "txt": "video.txt"
  },
  "duration_seconds": 120.5,
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 3.2,
      "text": "这是第一段识别结果"
    },
    {
      "id": 1,
      "start": 3.2,
      "end": 6.8,
      "text": "这是第二段识别结果"
    }
  ]
}

模型对比

模型	速度	精度	适用场景
paraformer-zh	⚡⚡⚡	⭐⭐⭐⭐	中文语音（推荐）
paraformer	⚡⚡	⭐⭐⭐⭐	多语言识别
sensevoice	⚡	⭐⭐⭐⭐⭐	高精度多语言

完整示例

示例 1: 转录播客

python funasr.py --input podcast.mp3 --model paraformer-zh --background

示例 2: 生成视频识别结果

python funasr.py --input tutorial.mp4 --model paraformer

示例 3: 批量处理（配合脚本）

#!/bin/bash
for video in videos/*.mp4; do
  python funasr.py --input "$video" --model paraformer-zh
done

在 Workflow 中使用

在知识库处理流程中，如果视频没有识别结果：

# 步骤4: 下载视频后
# 步骤5: 使用 FunASR 生成识别结果
python funasr.py --input ${video_path} --model paraformer-zh --background

# 等待 FunASR 完成，然后继续后续步骤

技术细节

• 引擎: 阿里 FunASR
• 模型框架: ModelScope
• 音频采样率: 自动转换为 16kHz
• 语言: 根据模型支持不同语言

故障排查

问题: 模型下载失败

# 首次运行会自动下载，确保网络稳定
python funasr.py --input test.mp4

# 手动检查缓存目录
ls ~/.cache/modelscope/hub/

问题: 音频格式不支持

# 转换音频格式
ffmpeg -i input.avi -acodec libmp3lame output.mp3
python funasr.py --input output.mp3

问题: 依赖安装失败

# 使用清华镜像源
pip install funasr modelscope -i https://pypi.tuna.tsinghua.edu.cn/simple

性能参考

在 CPU 环境下（Intel i7）：

• paraformer-zh 模型: ~2x 实时速度（1分钟音频 ~30秒处理）
• paraformer 模型: ~1.5x 实时速度（1分钟音频 ~40秒处理）
• sensevoice 模型: ~1x 实时速度（1分钟音频 ~1分钟处理）

与 Whisper 对比

特性	FunASR	Whisper
中文识别	⭐⭐⭐⭐⭐	⭐⭐⭐
速度	⚡⚡⚡	⚡⚡
模型大小	较小	较大
多语言支持	⭐⭐⭐	⭐⭐⭐⭐⭐

许可证

本技能使用 MIT 许可证，FunASR 使用 Apache 2.0 许可证。