# 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                       # 使用说明
```