212 lines
4.2 KiB
Markdown
212 lines
4.2 KiB
Markdown
# KB Whisper - 本地语音识别
|
||
|
||
基于 Whisper.cpp 的本地语音识别工具，支持将音视频文件转换为文本、字幕和 JSON 格式。
|
||
|
||
## 功能特性
|
||
|
||
- 🎯 **本地执行** - 完全离线运行，保护隐私
|
||
- 🚀 **多模型支持** - 从 tiny 到 large，根据需求选择速度/精度
|
||
- 📝 **多格式输出** - JSON、SRT、TXT 三种格式
|
||
- ⚡ **异步执行** - 支持后台运行，不阻塞主代理
|
||
- 🎬 **广泛兼容** - 支持常见音视频格式（MP3、MP4、WAV 等）
|
||
|
||
## 安装前提
|
||
|
||
### 1. 安装 whisper.cpp
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://github.com/ggerganov/whisper.cpp.git ~/whisper.cpp
|
||
|
||
# 编译
|
||
cd ~/whisper.cpp
|
||
make
|
||
|
||
# 下载模型（至少需要一个模型）
|
||
./models/download-ggml-model.sh tiny
|
||
./models/download-ggml-model.sh base # 可选
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
|
||
在 `~/.clawdbot/clawdbot.json` 中添加：
|
||
|
||
```json5
|
||
{
|
||
skills: {
|
||
entries: {
|
||
"kb-whisper": {
|
||
env: {
|
||
WHISPER_CPP_PATH: "~/whisper.cpp"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
或通过命令行配置：
|
||
|
||
```bash
|
||
clawdbot skills config kb-whisper WHISPER_CPP_PATH "~/whisper.cpp"
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 基本用法
|
||
|
||
```bash
|
||
# 使用默认 tiny 模型处理
|
||
python whisper.py --input video.mp4
|
||
|
||
# 使用 base 模型（推荐，平衡速度和精度）
|
||
python whisper.py --input video.mp4 --model base
|
||
|
||
# 后台异步执行
|
||
python whisper.py --input video.mp4 --background
|
||
```
|
||
|
||
### 指定输出目录
|
||
|
||
```bash
|
||
python whisper.py --input video.mp4 --output ./transcripts
|
||
```
|
||
|
||
### 处理音频文件
|
||
|
||
```bash
|
||
python whisper.py --input podcast.mp3 --model base
|
||
```
|
||
|
||
## 输出文件
|
||
|
||
对于输入 `video.mp4`，将生成以下文件：
|
||
|
||
```
|
||
output/
|
||
├── video.json # 详细结果（含时间戳）
|
||
├── video.srt # 字幕格式
|
||
└── video.txt # 纯文本
|
||
```
|
||
|
||
### JSON 格式
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"input_file": "video.mp4",
|
||
"model": "base",
|
||
"output_files": {
|
||
"json": "video.json",
|
||
"srt": "video.srt",
|
||
"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": "这是第二段字幕"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 模型对比
|
||
|
||
| 模型 | 速度 | 精度 | 适用场景 |
|
||
|------|------|------|----------|
|
||
| tiny | ⚡⚡⚡ | ⭐ | 快速预览、实时转录 |
|
||
| base | ⚡⚡ | ⭐⭐⭐ | 日常使用（推荐） |
|
||
| small | ⚡ | ⭐⭐⭐⭐ | 高质量需求 |
|
||
| medium | ⭐ | ⭐⭐⭐⭐⭐ | 专业用途 |
|
||
| large | 🐢 | ⭐⭐⭐⭐⭐ | 最高精度要求 |
|
||
|
||
## 完整示例
|
||
|
||
### 示例 1: 转录播客
|
||
|
||
```bash
|
||
python whisper.py --input podcast.mp3 --model base --background
|
||
```
|
||
|
||
### 示例 2: 生成视频字幕
|
||
|
||
```bash
|
||
python whisper.py --input tutorial.mp4 --model small
|
||
```
|
||
|
||
### 示例 3: 批量处理（配合脚本）
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
for video in videos/*.mp4; do
|
||
python whisper.py --input "$video" --model base
|
||
done
|
||
```
|
||
|
||
## 在 Workflow 中使用
|
||
|
||
在知识库处理流程中，如果视频没有字幕：
|
||
|
||
```bash
|
||
# 步骤4: 下载视频后，如果没有字幕
|
||
# 步骤5: 使用 Whisper 生成字幕
|
||
python whisper.py --input ${video_path} --model base --background
|
||
|
||
# 等待 Whisper 完成，然后继续后续步骤
|
||
```
|
||
|
||
## 技术细节
|
||
|
||
- **引擎**: Whisper.cpp（C++ 实现，性能优异）
|
||
- **音频采样率**: 自动转换为 16kHz
|
||
- **语言**: 自动检测（支持 99 种语言）
|
||
- **GPU 支持**: whisper.cpp 支持 CUDA 加速（需编译时启用）
|
||
|
||
## 故障排查
|
||
|
||
### 问题: 找不到 whisper.cpp
|
||
|
||
```bash
|
||
# 检查环境变量
|
||
echo $WHISPER_CPP_PATH
|
||
|
||
# 手动测试
|
||
~/whisper.cpp/main --help
|
||
```
|
||
|
||
### 问题: 模型未下载
|
||
|
||
```bash
|
||
cd ~/whisper.cpp
|
||
./models/download-ggml-model.sh tiny
|
||
```
|
||
|
||
### 问题: 音频格式不支持
|
||
|
||
```bash
|
||
# 转换音频格式
|
||
ffmpeg -i input.avi -acodec libmp3lame output.mp3
|
||
python whisper.py --input output.mp3
|
||
```
|
||
|
||
## 性能参考
|
||
|
||
在 CPU 环境下（Intel i7）：
|
||
|
||
- **tiny 模型**: ~1x 实时速度（1分钟音频 ~1分钟处理）
|
||
- **base 模型**: ~0.5x 实时速度（1分钟音频 ~2分钟处理）
|
||
- **small 模型**: ~0.25x 实时速度（1分钟音频 ~4分钟处理）
|
||
|
||
## 许可证
|
||
|
||
本技能使用 MIT 许可证，Whisper.cpp 使用 MIT 许可证。
|