hmo
04db423416
- 70 skills with code and documentation - Add .gitignore (ignore __pycache__, output/, temp/, venv/) - Clean up test intermediates and caches
234 lines
6.4 KiB
Markdown
234 lines
6.4 KiB
Markdown
# piano-lesson-highlight-generator 环境配置文档
|
||
|
||
> **最后更新**: 2026-04-03
|
||
> **Python 版本**: 3.12.13
|
||
> **PyTorch 版本**: 2.5.1+cu121 (CUDA 12.1)
|
||
> **faster-whisper**: 1.2.1
|
||
|
||
---
|
||
|
||
## 🚨 环境路径（最重要，先看这个）
|
||
|
||
**实际使用的 Python 环境**：
|
||
```
|
||
D:\ProgramData\anaconda3\envs\py312_cuda\python.exe
|
||
```
|
||
|
||
### ⚠️ 两个容易混淆的 conda 安装
|
||
|
||
| 路径 | 类型 | PyTorch | CUDA | 能用吗？ |
|
||
|------|------|---------|------|---------|
|
||
| `D:\AI\Miniconda3\python.exe` | Miniconda（base） | 2.11.0+**cpu** | **False** | ❌ **不能用**，转录会超时 |
|
||
| `D:\ProgramData\anaconda3\envs\py312_cuda\python.exe` | Anaconda（新建） | 2.5.1+**cu121** | **True** | ✅ **用这个** |
|
||
|
||
**所有运行命令都必须使用**：
|
||
```bash
|
||
"D:/ProgramData/anaconda3/envs/py312_cuda/python.exe"
|
||
```
|
||
|
||
**绝对不要用**：
|
||
```bash
|
||
"D:/AI/Miniconda3/python.exe" # CPU 版本，转录超时
|
||
conda activate py312_cuda # bash 中不工作
|
||
```
|
||
|
||
### 为什么需要新建环境
|
||
|
||
原环境 `D:\AI\Miniconda3` 的 PyTorch 是纯 CPU 版本（2.11.0+cpu），转录 100 分钟视频需要 100+ 分钟，会超时。
|
||
|
||
**必须使用** `D:\ProgramData\anaconda3\envs\py312_cuda\python.exe`。
|
||
|
||
---
|
||
|
||
## 环境创建步骤
|
||
|
||
### 1. 创建 conda 环境
|
||
|
||
```bash
|
||
"D:/ProgramData/anaconda3/Scripts/conda.exe" create -n py312_cuda python=3.12 -y
|
||
```
|
||
|
||
### 2. 安装 CUDA PyTorch
|
||
|
||
```bash
|
||
"D:/ProgramData/anaconda3/envs/py312_cuda/python.exe" -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
|
||
```
|
||
|
||
> 注意：必须安装 `+cu121` 版本，不是 CPU 版本。
|
||
|
||
### 3. 安装 Python 依赖
|
||
|
||
```bash
|
||
"D:/ProgramData/anaconda3/envs/py312_cuda/python.exe" -m pip install faster-whisper zhconv pypinyin pyyaml
|
||
```
|
||
|
||
### 4. 验证环境
|
||
|
||
```bash
|
||
"D:/ProgramData/anaconda3/envs/py312_cuda/python.exe" -c "
|
||
import torch
|
||
from faster_whisper import WhisperModel
|
||
print(f'Python: 3.12')
|
||
print(f'PyTorch: {torch.__version__}')
|
||
print(f'CUDA: {torch.cuda.is_available()}')
|
||
print(f'faster-whisper: OK')
|
||
"
|
||
```
|
||
|
||
预期输出：
|
||
```
|
||
Python: 3.12
|
||
PyTorch: 2.5.1+cu121
|
||
CUDA: True
|
||
faster-whisper: OK
|
||
```
|
||
|
||
### 5. 本地模型路径
|
||
|
||
Whisper large-v3 模型需要下载到本地：
|
||
```
|
||
D:/AI/LM-Models/faster-whisper/large-v3/
|
||
```
|
||
|
||
包含文件：
|
||
- `config.json`
|
||
- `model.bin`
|
||
- `preprocessor_config.json`
|
||
- `tokenizer.json`
|
||
- `vocabulary.json`
|
||
|
||
如果模型不在该路径，脚本会尝试从 HuggingFace 下载（很慢）。
|
||
|
||
### 6. 完整依赖清单
|
||
|
||
| 包 | 版本 | 用途 |
|
||
|---|------|------|
|
||
| Python | 3.12.13 | 运行时 |
|
||
| torch | 2.5.1+cu121 | GPU 加速 |
|
||
| torchvision | 0.20.1+cu121 | 图像处理 |
|
||
| torchaudio | 2.5.1+cu121 | 音频处理 |
|
||
| faster-whisper | 1.2.1 | Whisper 转录 |
|
||
| ctranslate2 | 4.7.1 | Whisper 后端 |
|
||
| zhconv | 1.4.3 | 繁体转简体 |
|
||
| pypinyin | 0.55.0 | 拼音转换（AI 纠错） |
|
||
| pyyaml | 6.0.3 | 配置文件解析 |
|
||
| av | 17.0.0 | 音视频处理 |
|
||
| numpy | 2.4.3 | 数值计算 |
|
||
| onnxruntime | 1.24.4 | Whisper 推理 |
|
||
| tokenizers | 0.22.2 | 文本分词 |
|
||
|
||
---
|
||
|
||
## 已知问题
|
||
|
||
### 问题 0：原环境 D:\AI\Miniconda3 没有 GPU 支持（关键！）
|
||
|
||
**原 session 的错误记录**：之前有 AI 记录了 `D:\AI\Miniconda3` "具备 GPU 加速能力"——**这是错的！**
|
||
|
||
验证：
|
||
```bash
|
||
"D:/AI/Miniconda3/python.exe" -c "import torch; print(torch.cuda.is_available())"
|
||
# 输出: False
|
||
```
|
||
|
||
该环境的 PyTorch 是 `2.11.0+cpu`，**纯 CPU 版本**。之前能跑通是因为复用了已有的 `full_transcript.json`，没有重新转录。如果需要重新转录，**必须用有 CUDA 的环境**。
|
||
|
||
### 问题 1：Python 3.8 环境无法安装 faster-whisper
|
||
|
||
`matanyone` 环境（Python 3.8.20）有 GPU PyTorch，但 `tokenizers` 包需要 Python >= 3.9，导致无法安装 faster-whisper。
|
||
|
||
**解决方案**：创建 Python 3.12 环境（见上文）。
|
||
|
||
### 问题 2：conda activate 在 bash 中不工作
|
||
|
||
bash 工具中 `conda activate py312_cuda` 会报错。
|
||
|
||
**解决方案**：直接使用完整路径调用 Python：
|
||
```bash
|
||
"D:/ProgramData/anaconda3/envs/py312_cuda/python.exe" script.py
|
||
```
|
||
|
||
---
|
||
|
||
## GPU 资源管理
|
||
|
||
### 转录前清理
|
||
|
||
脚本会在转录前自动清理残留的 Python 进程，释放 GPU 显存。
|
||
|
||
### 转录后释放
|
||
|
||
转录完成后，脚本会：
|
||
1. `del model` — 删除模型对象
|
||
2. `gc.collect()` — 强制垃圾回收
|
||
3. `torch.cuda.empty_cache()` — 清空 CUDA 缓存
|
||
|
||
### 如果 GPU 显存未释放
|
||
|
||
手动清理：
|
||
```bash
|
||
cmd /c "taskkill /F /IM python.exe /T"
|
||
```
|
||
|
||
---
|
||
|
||
## 运行命令模板
|
||
|
||
```bash
|
||
cd .opencode/skills/piano-lesson-highlight-generator
|
||
|
||
# 知识点提取 + config 生成
|
||
"D:/ProgramData/anaconda3/envs/py312_cuda/python.exe" scripts/extract_terms_from_ppt.py <pptx路径> <视频路径> <config输出路径>
|
||
|
||
# 精华视频生成
|
||
"D:/ProgramData/anaconda3/envs/py312_cuda/python.exe" scripts/generate_highlights.py --config <config路径>
|
||
```
|
||
|
||
---
|
||
|
||
## 项目目录结构
|
||
|
||
```
|
||
projects/piano-lesson-highlights/
|
||
├── data/ # 原始输入数据
|
||
│ ├── lesson2/
|
||
│ │ ├── video.mp4 # 原始视频
|
||
│ │ └── course.pptx # 配套 PPT
|
||
│ └── lesson3/
|
||
│ └── ...
|
||
└── cases/ # 每个案例的工作区
|
||
├── lesson2/
|
||
│ ├── config.yaml # 自动生成的配置
|
||
│ ├── intermediates/
|
||
│ │ └── full_transcript.json # 完整转录（可复用）
|
||
│ └── output/
|
||
│ ├── v1_final.mp4 # 最终精华视频
|
||
│ ├── subs/
|
||
│ │ ├── v1_original.srt
|
||
│ │ ├── v1_terms.srt
|
||
│ │ └── v1_ai.srt
|
||
│ └── intermediates/
|
||
│ ├── clip1.mp4 ~ clipN.mp4
|
||
│ ├── clip1_fade.mp4 ~ clipN_fade.mp4
|
||
│ ├── clip1.json ~ clipN.json
|
||
│ ├── concated.mp4
|
||
│ └── concat_list.txt
|
||
└── lesson3/
|
||
└── ...
|
||
```
|
||
|
||
---
|
||
|
||
## 技能代码位置
|
||
|
||
```
|
||
.opencode/skills/piano-lesson-highlight-generator/
|
||
├── scripts/
|
||
│ ├── extract_terms_from_ppt.py # 知识点提取 + 转录 + config 生成
|
||
│ └── generate_highlights.py # 精华视频生成
|
||
├── SKILL.md # 技能说明
|
||
├── STATUS.md # 会话状态
|
||
├── ENVIRONMENT.md # 本文件
|
||
└── README.md # 使用说明
|
||
```
|