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

# KB FunASR Skill

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

## 什么时候使用

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

## 环境变量

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

## 命令

```bash
# 基本用法（使用 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 | 错误信息 |

## 成功示例

```json
{
  "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": "这是第二段识别结果"
    }
  ]
}
```

## 错误示例

### 模型未下载

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

### 文件不存在

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

### 内存不足

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

## 安装

```bash
# 1. 安装依赖
pip install funasr modelscope

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

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

## 在 kb-workflow 中的使用

```bash
# 步骤 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：中文优化，精度更高