ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add whisper guide and cloud learning pipeline docs

Browse Source
This commit is contained in:
weishen
2026-04-15 10:18:37 +08:00
parent 7c90666361
commit e69c162353
2 changed files with 513 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

252
openclaw/xingshu/cloud-learning-audio-pipeline.md Normal file
View File

@@ -0,0 +1,252 @@
# Cloud Learning 音视频处理流水线
> 文档版本：2026-04-15
> 维护者：星枢（xingshu）
> 状态：✅ 已验证可运行
---
## 一、整体架构
```
NAS 视频源
│
▼
[阶段1] FFmpeg 音频提取
│ MP4 → MP3
▼
NAS MP3 文件库
│
▼
[阶段2] Whisper 转录
│ MP3 → 英文字幕/转写稿
▼
Macmini 本地转写稿
│
▼
[阶段3] Gemini Flash 摘要
│ 转写稿 → 结构化中文笔记
▼
Obsidian 知识库
```
---
## 二、各阶段详解
### 阶段 1：FFmpeg 音频提取
| 项目 | 说明 |
|---|---|
| **输入** | NAS 上的 `.mp4` 文件（`/volume2/work/Public Cloud Learning Sessions/`） |
| **输出** | 同目录下的同名 `.mp3` 文件 |
| **工具** | FFmpeg（Macmini 已安装：`/opt/homebrew/bin/ffmpeg`） |
| **转码参数** | `-vn -acodec libmp3lame -ab 64k -ar 22050 -ac 1`（64kbps CBR，针对人声优化）|
| **传输方式** | `ssh cat` 管道（NAS 不需要挂载）|
| **速度** | ~400x realtime（1小时视频 ≈ 9秒提取）|
**命令示例：**
```bash
# NAS → Macmini FFmpeg → 回写 NAS
ssh shenwei@192.168.3.17 "cat '/volume2/work/Public Cloud Learning Sessions/VIDEO.mp4'" \
| /opt/homebrew/bin/ffmpeg -i pipe:0 -vn -acodec libmp3lame -ab 64k -ar 22050 -ac 1 -f mp3 pipe:1 \
| ssh shenwei@192.168.3.17 "cat > '/volume2/work/Public Cloud Learning Sessions/VIDEO.mp3'"
```
**脚本位置：** `~/.openclaw/temp/xingshu/scripts/nas_audio_extract_v3.py`
---
### 阶段 2：Whisper 转录
| 项目 | 说明 |
|---|---|
| **输入** | NAS 上的 `.mp3` 文件（已由阶段1生成）|
| **输出** | 英文字幕/转写稿（纯文本）|
| **工具** | `openai-whisper`（Python 包，通过 `pip install openai-whisper` 安装）|
| **模型** | `small`（精度与速度平衡，M 系列芯片友好）|
| **硬件** | Macmini 本地运行（Neural Engine 加速）|
| **速度** | ~50x realtime（1小时音频 ≈ 40-50秒）|
| **内存** | ~1.5GB（small 模型）|
| **费用** | 完全免费（本地运行，无需 API）|
**安装命令：**
```bash
pip3 install openai-whisper
```
**调用示例：**
```python
import whisper
model = whisper.load_model("small")
result = model.transcribe("audio.mp3", language="en", fp16=False)
print(result["text"]) # 英文字幕/转写稿
```
**转写稿长度参考：** 1小时音频 ≈ 6000-8000 tokens（英文）
---
### 阶段 3：Gemini Flash 摘要
| 项目 | 说明 |
|---|---|
| **输入** | Whisper 转写的英文字幕/转写稿 |
| **输出** | 结构化中文笔记（摘要 + 关键概念 + 相关链接）|
| **工具** | Google Gemini API（直接 HTTP 调用，不依赖 summarize CLI）|
| **模型** | `gemini-3-flash-preview` |
| **费用** | ~0.075$/百万输入 tokens（3000分钟音频 ≈ ~$0.15）|
| **API Key** | `AIzaSyASNIlSc-YYP1dCqKCzk59e7MXSVrnHba0`（需有效）|
**摘要输出格式：**
```markdown
## 摘要
> [300-500字中文摘要]
---
## 关键概念
- **[概念名称]**: [一句话解释]
---
## 相关视频
> [!info]+ 交叉引用
> [[相关视频文件名]] — 关联原因
```
---
## 三、全量流水线脚本
**脚本位置：** `~/.openclaw/temp/xingshu/scripts/nas_whisper_gemini_summarize.py`
**核心逻辑：**
1. 扫描 NAS 上已完成的 `.mp3` 文件（跳过 `*.done` 中已有的）
2. `ssh cat` 下载到 Macmini 本地临时目录
3. Whisper `small` 转录
4. Gemini Flash 摘要
5. 更新 Obsidian 对应笔记（替换 `## 摘要` 到 `## 相关视频` 之间的内容）
6. 删除本地临时文件
7. 写入 `.done` 进度文件（断点续传）
**启动命令：**
```bash
cd ~/.openclaw/temp/xingshu
nohup python3 scripts/nas_whisper_gemini_summarize.py > nas_whisper_summarize_stdout.log 2>&1 &
echo "PID=$!"
```
**查看进度：**
```bash
tail -f ~/.openclaw/temp/xingshu/logs/nas_whisper_summarize.log
```
---
## 四、Obsidian 笔记模板
笔记文件位于：`~/Workspace/nexus/knowledgebase/DevOps & SRE/`
```markdown
---
title: "视频标题"
type: cloud-learning
source-type: video
category: "DevOps & SRE/01_AWS-Landing-Zone"
tags:
- AWS
- Landing-Zone
date-added: 2026-04-14
video-source: "nas:///volume2/work/Public Cloud Learning Sessions/VIDEO.mp4"
audio-source: "nas:///volume2/work/Public Cloud Learning Sessions/VIDEO.mp3"
status: summarized # raw → summarized
---
# 视频标题
**Source:** NAS `/volume2/work/Public Cloud Learning Sessions/VIDEO.mp4`
**Type:** VIDEO | **Category:** 01_AWS-Landing-Zone
**Status:** ✅ 已完成
---
## 摘要
> [Gemini Flash 生成的中文摘要]
---
## 关键概念
- **[概念名称]**: [一句话解释]
---
## 相关视频
> [!info]+ 交叉引用
> [[相关视频文件名]] — 关联原因
```
---
## 五、API Key 汇总
| 服务 | Key | 用途 | 状态 |
|---|---|---|---|
| Google Gemini | `AIzaSyASNIlSc-YYP1dCqKCzk59e7MXSVrnHba0` | 摘要生成 | ✅ 有效 |
| MiniMax | `sk-cp-H0FwKNry9PnMJm...` | Whisper 转录 | ❌ Whisper端点404，token plan不支持模型 |
> ⚠️ MiniMax API Key 目前不可用（Whisper 端点 404，文本模型 500），Whisper 改用本地模型。
---
## 六、费用估算（100个视频，~3000分钟总时长）
| 阶段 | 工具 | 费用 |
|---|---|---|
| 音频提取 | FFmpeg | $0 |
| 语音转录 | Whisper（本地） | $0 |
| 摘要生成 | Gemini Flash | ~$0.15 |
| **合计** | | **~$0.15** |
---
## 七、已知限制与注意事项
1. **Gemini API Key 必须有效**：每 24 小时检查一次 key 状态
2. **Whisper 模型选择**：`tiny` 最快但精度低，`small` 平衡，`medium`/`large` Macmini 内存不够
3. **音频质量**：Whisper 对音质敏感，背景噪音会导致转写质量下降
4. **断点续传**：脚本使用 `.done` 文件记录已完成的文件，重启不会重复处理
5. **文件命名**：文件名中的空格和特殊字符（`_`、`(`、`)`）需要正确处理
---
## 八、快捷命令速查
```bash
# 查看音频提取进度
cat ~/.openclaw/temp/xingshu/logs/nas_audio_v3.log | tail -10
# 查看转录摘要进度
tail -f ~/.openclaw/temp/xingshu/logs/nas_whisper_summarize.log
# 查看 NAS 已完成 mp3 数量
ssh shenwei@192.168.3.17 "ls '/volume2/work/Public Cloud Learning Sessions/'*.mp3 2>/dev/null | wc -l"
# 查看已处理摘要数量
cat ~/.openclaw/temp/xingshu/nas_whisper_summarize.done | wc -l
# 手动测试 Whisper
python3 -c "import whisper; m=whisper.load_model('small'); print(m.transcribe('test.mp3')['text'][:100])"
# 手动测试 Gemini
curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent?key=AIzaSyASNIlSc-YYP1dCqKCzk59e7MXSVrnHba0" \
-H 'Content-Type: application/json' \
-d '{"contents":[{"parts":[{"text":"say hi in 3 words"}]}]}'
```

261
openclaw/xingshu/whisper-guide.md Normal file
View File

@@ -0,0 +1,261 @@
# Whisper 本地语音转录完全指南
> 文档版本：2026-04-15
> 维护者：星枢（xingshu）
> 状态：✅ Macmini 已验证可运行
---
## 一、Whisper 是什么
Whisper 是 OpenAI 开源的自动语音识别（ASR）模型，可将音频文件转录为文字。支持 99 种语言，尤其对英文识别精度极高。
**两种使用方式：**
| 方式 | 说明 | 费用 |
|---|---|---|
| **本地运行** | 模型下载到本地 Mac/PC | **免费** |
| OpenAI API | 调用 OpenAI Whisper API | 按分钟计费 |
本指南使用**本地运行**方式。
---
## 二、支持的模型
| 模型 | 参数量 | 英文 WER* | 中文 CER* | 本地内存占用 | Macmini 兼容性 |
|---|---|---|---|---|---|
| `tiny` | 39M | 5.2% | ~10% | ~1GB | ✅ |
| `base` | 74M | 3.5% | ~8% | ~1GB | ✅ |
| **`small`** | 244M | 2.7% | ~5% | ~1.5GB | **✅ 推荐** |
| `medium` | 769M | 2.3% | ~4% | ~5GB | ⚠️ 可能 OOM |
| `large` | 1550M | 2.0% | ~3% | ~10GB | ❌ OOM |
> \* WER = Word Error Rate，CER = Character Error Rate，越低越准确。
**推荐：`small` 模型**（精度与资源占用的最佳平衡）
---
## 三、安装
### 3.1 前置条件
```bash
# 确认 Python 版本（需 3.8+）
python3 --version
# 确认 pip 可用
pip3 --version
```
### 3.2 安装 Whisper
```bash
pip3 install openai-whisper
```
**如果遇到权限错误（macOS）：**
```bash
pip3 install --user openai-whisper
```
**首次运行会自动下载模型文件**（~500MB/small 模型），无需手动下载。
---
## 四、快速测试
### 4.1 单文件测试（tiny 模型，最快）
```python
import whisper
model = whisper.load_model("tiny") # 首次运行会下载模型
result = model.transcribe("audio.mp3", language="en")
print(result["text"])
```
### 4.2 完整示例（small 模型）
```python
import whisper
# 加载模型（只需加载一次）
model = whisper.load_model("small")
# 转录
result = model.transcribe(
"audio.mp3",
language="en", # 指定语言，不指定则自动检测
fp16=False, # Macmini 用 CPU，必须 False
verbose=True, # 显示进度
)
print("语言检测:", result["language"])
print("转写稿:", result["text"])
print("分段数:", len(result["segments"]))
```
### 4.3 命令行测试
```bash
# 安装后可直接在命令行使用
whisper audio.mp3 --model small --language en
```
---
## 五、Python API 详解
### 5.1 核心方法
```python
import whisper
model = whisper.load_model("small")
# 完整参数
result = model.transcribe(
audio="path/to/file.mp3",
# 语言设置
language="en", # 指定语言，不填则自动检测
# prompt="", # 可选，引导模型偏好（如专有名词）
# 输出控制
fp16=False, # CPU 必须 False，GPU 可 True
temperature=0.0, # 0=确定性，>0=随机性
condition_on_previous_text=True, # 利用前一段上下文
# 任务模式
task="transcribe", # transcribe 或 translate（中译英）
# 段落切分
word_timestamps=False, # True=输出每个词的起止时间
# 日志
verbose=True,
)
```
### 5.2 返回值结构
```python
{
"text": "完整的转写文本...",
"language": "en",
"segments": [
{
"id": 0,
"start": 0.0, # 秒
"end": 5.5,
"text": " Can you see my screen already?",
"words": [...] # 如果 word_timestamps=True
},
...
],
"language_probability": 0.99
}
```
### 5.3 批量转录
```python
import whisper
import glob
model = whisper.load_model("small")
audio_files = glob.glob("*.mp3")
for audio_file in audio_files:
print(f"Processing: {audio_file}")
result = model.transcribe(audio_file, language="en", fp16=False)
# 保存转写稿
with open(audio_file + ".txt", "w") as f:
f.write(result["text"])
```
---
## 六、Macmini M4 Pro 性能实测
| 音频时长 | 文件大小 | 模型 | 转录耗时 | 速度比 |
|---|---|---|---|---|
| ~54 分钟 | 3MB | `small` | ~43s | ~75x realtime |
| ~54 分钟 | 3MB | `tiny` | ~10s | ~320x realtime |
| ~1 小时 | 22MB | `small` | ~90s | ~40x realtime |
**速度经验：** `small` 模型处理 1 小时音频约 1-2 分钟，内存占用稳定在 ~1.5GB。
---
## 七、在流水线中的使用
本项目不使用 Whisper API，而是通过 Python 脚本调用本地模型：
```python
import whisper
def whisper_transcribe(mp3_path: str) -> str:
"""单文件转录，返回英文字幕/转写稿"""
model = whisper.load_model("small") # 模型只加载一次
result = model.transcribe(
mp3_path,
language="en",
fp16=False,
)
return result["text"].strip()
# 使用
transcript = whisper_transcribe("/path/to/audio.mp3")
```
---
## 八、常见问题
### Q1: `fp16 is not supported on CPU` 警告
**正常**，Macmini 用 CPU 运行，Whisper 自动降级到 FP32。不影响精度。
### Q2: `SIGKILL` / 进程被杀死
**内存不足**，模型太大。改用更小的模型：
```python
model = whisper.load_model("tiny") # 最省内存
```
### Q3: 中文识别不准
指定语言参数提升精度：
```python
result = model.transcribe("audio.mp3", language="zh") # 中文
result = model.transcribe("audio.mp3", language="en") # 英文
```
### Q4: 如何加速转录
- 用 `tiny` 或 `base` 模型（牺牲精度换速度）
- Macmini M 系列芯片无需特殊优化（Neural Engine 自动加速）
- 避免同时跑多个转录任务
### Q5: 支持哪些音频格式
支持 FFmpeg 支持的所有格式：`mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` 等。
---
## 九、卸载
```bash
pip3 uninstall openai-whisper
# 删除已下载的模型（默认缓存位置）
rm -rf ~/.cache/whisper
```
---
## 十、相关资源
- **GitHub**: https://github.com/openai/whisper
- **模型下载**: 首次调用 `load_model()` 时自动下载
- **缓存位置**: `~/.cache/whisper/`
- **本项目脚本**: `~/.openclaw/temp/xingshu/scripts/nas_whisper_gemini_summarize.py`