# meeting-minutes

**Repository Path**: cloudsky/meeting-minutes

## Basic Information

- **Project Name**: meeting-minutes
- **Description**: 本地化部署实现录音会议纪要
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 会议纪要助手 (MeetingMinutes)

> 本地录音文件 → 结构化会议纪要  
> 全本地运行 · 数据不出设备 · 多模型可选 · 断点续传

---

## 特性概览

| 特性 | 说明 |
|------|------|
| 🎙️ 多 ASR 模型可选 | 6 款 FunASR 模型，按显存/精度自由切换 |
| 🗣️ 说话人识别 | pyannote-audio，支持离线模式（无需 Token） |
| 📝 双版本纪要生成 | V1 深度分析版 / V2 精简稳定版，UI 一键切换 |
| 🤖 LLM 模型可选 | 动态拉取 Ollama 已安装模型，支持自定义输入 |
| 💾 断点续传 | 每步结果自动缓存，中断后继续不重复计算 |
| 🔄 缓存管理 | 界面显示缓存目录信息，一键清空 |
| ⚡ GPU→CPU 自动降级 | 显存不足时自动切换，不崩溃 |
| 📄 多格式导出 | Markdown + Word (.docx) 一键下载 |

---

## 系统概述

在 **6GB 显存笔记本电脑**（Windows + CUDA）上，将录音文件自动转换为结构化会议纪要。

**处理流程**（每步完成后自动释放显存，峰值不叠加）：

```
录音文件
  ↓ [1] ASR 转写（FunASR，可选模型）
  ↓ [2] 说话人识别（pyannote，可选开关）
  ↓ [3] LLM 纪要生成（Qwen2.5-7B，可选版本）
  ↓       ↓ 断点续传（每步缓存至 checkpoints/）
 输出：Markdown 纪要 + Word 纪要 + 原始转写文本
```

---

## 环境要求

| 项目 | 要求 |
|------|------|
| 操作系统 | Windows 10/11 (x64) |
| Python | ≥ 3.10 |
| GPU | NVIDIA GPU，≥ 6GB 显存（CUDA 11.8+）；无 GPU 可纯 CPU 运行 |
| 内存 | ≥ 16 GB RAM |
| 磁盘 | ≥ 20 GB 可用空间（模型文件 ~5GB） |
| ffmpeg | 已安装并加入系统 PATH |
| Ollama | 已安装并运行（用于 LLM 调用） |

---

## 安装步骤

### 1. 安装 ffmpeg

下载 ffmpeg 并添加到系统 PATH：
- 官方下载: https://ffmpeg.org/download.html
- 或使用 Chocolatey: `choco install ffmpeg`

验证安装：
```bash
ffmpeg -version
```

### 2. 安装 Ollama + LLM 模型

```bash
# 下载安装 Ollama: https://ollama.com/download/windows
# 安装完成后拉取模型（推荐 qwen2.5:7b-instruct-q4_0）:
ollama pull qwen2.5:7b-instruct-q4_0
```

### 3. 安装 Python 依赖

```bash
cd meeting-minutes
pip install -r requirements.txt
```

### 4. （推荐）下载说话人识别模型

> 💡 **推荐：使用离线模式** — 模型通过魔搭社区（ModelScope）下载，境内直连，无需任何 Token，下载后完全离线运行。

**第一步：运行下载脚本**

```bash
cd meeting-minutes
python scripts/download_pyannote_models.py
```

脚本通过 `modelscope` SDK 从魔搭社区下载以下模型（约 32MB）：
- `pyannote/speaker-diarization-3.1` 所需的所有组件

下载完成后保存在 `models/pyannote/` 目录。

**第二步：启用离线模式**

- **方式 A（推荐）**：在 Gradio UI 中勾选「🔒 离线模式（无需 Token）」
- **方式 B**：设置环境变量后启动
  ```bash
  # PowerShell:
  $env:DIARIZATION_OFFLINE_MODE = "true"
  python app.py
  ```

> ✅ 离线模式启用后，完全不需要 HF Token，所有模型本地加载，无需任何外网访问。

**备选方案：使用在线模式（需要 HuggingFace Token）**

如需使用在线模式（自动从 HuggingFace Hub 下载模型）：

1. 注册 HuggingFace: https://huggingface.co/join
2. 访问 https://huggingface.co/pyannote/speaker-diarization-3.1 并**接受使用协议**
3. 在 https://huggingface.co/settings/tokens 创建 Token
4. 在 UI 中填入 Token，或设置环境变量 `HF_TOKEN`
5. **加速下载**：设置境内镜像环境变量后再启动
   ```bash
   $env:HF_ENDPOINT = "https://hf-mirror.com"
   python app.py
   ```

---

## 启动

```bash
python app.py
```

浏览器访问: http://127.0.0.1:7860

---

## 使用说明

### 配置面板（左侧）

| 选项 | 说明 |
|------|------|
| 音频文件 | 拖拽或点击上传（支持 mp3/wav/m4a/ogg/flac 等） |
| ASR 转写模型 | 选择语音转文字模型（6 款可选，自动适配显存） |
| 说话人识别 | 勾选启用（推荐离线模式）；不勾选则转写无说话人标注 |
| HF Token | 在线模式需要；离线模式留空 |
| Ollama 模型 | 动态拉取已安装模型列表，支持手动输入 |
| 纪要生成版本 | V1 深度分析版 / V2 精简稳定版 |
| 缓存信息 | 显示缓存目录路径、文件数、占用空间 |
| 清空缓存 | 一键删除所有断点续传缓存 |

### 操作按钮

| 按钮 | 说明 |
|------|------|
| 🚀 开始处理 | 启动完整三步流水线 |
| 🔄 重新生成纪要 | 仅重新跑 LLM 步骤（跳过 ASR + 说话人识别） |
| 🔄 刷新 Ollama 模型列表 | 拉取最新的 Ollama 已安装模型 |

### 输出结果

处理完成后，右侧面板显示：
- **会议纪要**（Markdown 实时渲染）
- **原始转写文本**（含时间戳和说话人标注）
- **下载按钮**：导出 `.md` 和 `.docx`

---

## 功能详解

### ASR 转写模型选择

支持 6 款 FunASR 模型，在 UI 下拉框中切换：

| 模型 Key | 名称 | 显存需求 | 说明 |
|-----------|------|---------|------|
| `paraformer-large-vad-punc` | Paraformer-Large（默认）⭐ | ~8GB | 原始默认版，综合效果最佳 |
| `paraformer-large-vad-punc-native` | Paraformer-Large（原生 VAD） | ~5GB | 内建标点，更省显存 |
| `sensevoice-small` | SenseVoiceSmall 🚀 | ~1.5GB | 多语言，速度极快，6GB 首选 |
| `paraformer-large` | Paraformer-Large（纯净版） | ~4GB | 不带 VAD/标点 |
| `paraformer` | Paraformer 标准版 | ~1.5GB | 68M 参数，低配设备 |
| `paraformer-tiny` | Paraformer-Tiny 🪶 | ~200MB | 超轻量，命令词场景 |

**显存保护机制**：
- 启动前自动预估显存需求，不足时弹窗提示并自动降级
- GPU OOM 时自动切换至 CPU 模式，不中断流程

### 纪要生成版本选择

| 版本 | 名称 | 板块数 | 温度 | 特点 | 适合场景 |
|------|------|-------|------|------|---------|
| `v1` | V1 深度分析版 | 11 个 | 0.3 | 含观点碰撞、风险矩阵、效率评估等 | 正式高层会议 |
| `v2` | V2 精简稳定版 | 5 个 | 0.1 | 忠实提取、不编造、结果稳定 | 日常会议纪要（默认） |

切换版本后，已有缓存会自动失效并重新生成纪要，无需手动清缓存。

### 断点续传与缓存

所有中间结果自动保存至 `checkpoints/` 目录（按音频文件 MD5 索引）：

| 缓存阶段 | 保存内容 | 失效条件 |
|---------|---------|---------|
| `asr_done` | 转写结果（含时间戳） | 切换 ASR 模型 / 上传新文件 |
| `diarization_done` | 说话人标注结果 | ASR 结果变更 |
| `llm_done` | 最终会议纪要 | 切换纪要版本 / ASR 内容变更 |

**缓存有效性保护**：
- ASR 内容指纹（MD5）校验：防止换音频误用旧纪要
- 模型版本标签：切换模型/版本自动清除对应缓存

---

## 配置说明

所有关键配置在 `config.py` 中，可通过环境变量覆盖：

### 基础配置

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `HF_TOKEN` | (空) | HuggingFace Token（在线模式需要） |
| `HF_ENDPOINT` | (空) | HuggingFace 境内镜像地址（如 `https://hf-mirror.com`） |
| `DIARIZATION_OFFLINE_MODE` | false | 离线模式（true = 无需 HF Token） |
| `DIARIZATION_CONFIG_PATH` | configs/pyannote_offline.yaml | 离线模式配置文件路径 |
| `OLLAMA_BASE_URL` | http://localhost:11434 | Ollama 服务地址 |
| `OLLAMA_MODEL` | qwen2.5:7b-instruct-q4_0 | 默认 LLM 模型名称 |
| `ASR_DEVICE` | auto | 设备选择（cuda / cpu） |
| `LOG_LEVEL` | INFO | 日志级别（DEBUG / INFO / WARNING / ERROR） |

### ASR 模型配置

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `ASR_MODEL_KEY` | paraformer-large-vad-punc | 选中的 ASR 模型 key（需在 `ASR_MODELS` 中已注册） |

可在 `config.py` 的 `ASR_MODELS` 字典中注册自定义模型。

### 纪要版本配置

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `MINUTES_VERSION` | v2 | 默认纪要生成版本（v1 / v2） |

---

## 项目结构

```
meeting-minutes/
├── app.py                          # Gradio Web UI 主入口
├── config.py                       # 全局配置文件（模型注册表、参数阈值）
├── requirements.txt                # Python 依赖
├── README.md                      # 本文件
├── configs/                       # 离线模式配置文件
│   └── pyannote_offline.yaml     # pyannote 离线加载配置
├── models/                        # 本地模型目录（离线模式用）
│   └── pyannote/                 # pyannote 模型文件
├── scripts/                       # 工具脚本
│   └── download_pyannote_models.py  # 首次下载 pyannote 模型
├── pipeline/                      # 核心处理流水线
│   ├── __init__.py
│   ├── audio_preprocessor.py      # ffmpeg 预处理 + VAD 分段
│   ├── asr_engine.py             # FunASR 推理（多模型、GPU→CPU 降级）
│   ├── diarization_engine.py      # pyannote-audio 说话人识别
│   ├── llm_engine.py             # Ollama LLM 纪要生成（版本分发）
│   └── memory_manager.py         # GPU 显存管理工具
├── utils/                        # 工具模块
│   ├── __init__.py
│   ├── checkpoint.py              # 断点续传管理器（含 ASR 指纹校验）
│   ├── text_merger.py            # 时间轴文本 + 说话人对齐
│   └── output_formatter.py       # Markdown / Word 输出
├── prompts/                      # LLM Prompt 模板
│   ├── __init__.py
│   ├── meeting_minutes.py        # V1 深度分析版 Prompt（11 板块）
│   └── meeting_minutes_v2.py    # V2 精简稳定版 Prompt（5 板块）
├── checkpoints/                   # 断点续传缓存目录
└── outputs/                      # 输出文件目录（.md / .docx）
```

---

## 常见问题

### Q: 显存不足（Out of Memory）？

A: 本工具采用三步串行调度，峰值显存不超过单步最大需求。如仍出现 OOM：

- **自动降级**：GPU OOM 时自动切换至 CPU 模式（速度变慢但不中断）
- 切换至更轻量 ASR 模型（推荐 `sensevoice-small`，仅需 ~1.5GB）
- 关闭说话人识别（节省 ~1GB）
- 将 LLM 改为更小模型（如 `qwen2.5:3b`）

### Q: 生成的纪要与语音内容不一致？

A: 可能原因与解决方案：

1. **缓存污染**：切换了音频文件但命中了旧缓存 → 点击「清空缓存」按钮
2. **ASR 转写质量**：尝试切换至更高质量的 ASR 模型（如 `paraformer-large-vad-punc`）
3. **LLM 不稳定**：切换至 V2 精简稳定版（温度 0.1，更确定）

### Q: "无法连接 Ollama"？

A: 确认 Ollama 已启动：
```bash
ollama serve
```

如 Ollama 在另一个端口运行，在 UI 中修改 Ollama 服务地址，或设置环境变量：
```bash
$env:OLLAMA_BASE_URL = "http://localhost:11434"
```

### Q: FunASR 模型下载慢？

A: 模型从魔搭社区（ModelScope）自动下载，境内直连。首次运行需下载 ~1-2GB。

自定义缓存路径：
```bash
$env:MODELSCOPE_CACHE = "D:\modelscope_cache"
python app.py
```

### Q: 说话人识别一直失败？

A: 推荐使用**离线模式**（勾选 UI 中的「🔒 离线模式」），无需任何 Token，完全本地运行。

> 首次使用需运行 `python scripts/download_pyannote_models.py` 下载模型（通过魔搭社区，境内直连）。

如果仍失败，排查步骤：
1. 确认已勾选「离线模式」
2. 确认 `models/pyannote/` 目录下有模型文件
3. 如果不需要区分说话人，关闭此功能即可

### Q: 纪要生成结果时好时坏？

A: 这是 7B 模型在复杂 Prompt 下的已知问题。建议：

1. **切换至 V2 精简稳定版**（默认已设置为 V2）
2. V2 的 Prompt 长度仅为 V1 的 10.8%，温度更低（0.1），结果更稳定
3. 如需要 V1 的深度分析能力，可在 UI 中手动切换回 V1

### Q: 超长录音（>30分钟）处理失败？

A: 系统内置 Map-Reduce 策略自动处理超长文本：
- ≤30分钟：直接传入 LLM
- >30分钟：自动分块 → 每块生成摘要 → 汇总生成最终纪要

无需手动操作，系统自动处理。

### Q: 离线模式下载模型时提示连接失败？

A: 下载脚本使用魔搭社区（ModelScope），境内直连。如失败请检查：
1. 确认能访问 `https://www.modelscope.cn`（浏览器打开测试）
2. 确认已安装 `modelscope`：`pip install modelscope>=1.11.0`
3. 备选方案 — 使用 Git LFS 手动下载：
   ```bash
   git lfs install
   git clone https://www.modelscope.cn/pyannote/speaker-diarization-3.1.git models/pyannote/speaker-diarization-3.1
   ```

---

## 技术栈

| 组件 | 方案 | 显存需求 |
|------|------|---------|
| ASR | FunASR（ModelScope） | 0.2GB ~ 8GB（取决于模型选择） |
| 说话人识别 | pyannote-audio 3.1 | ~1.0 GB |
| LLM | Qwen2.5-7B GGUF（Ollama） | ~4.5 GB |
| UI | Gradio 5.x | ~0 GB |
| **峰值显存**（串行） | | **≤ 8GB**（取决于所选 ASR 模型） |

---

## 版本历史

### v2.0（当前版本）
- ✅ 新增纪要生成版本化（V1 深度版 / V2 精简稳定版）
- ✅ 新增 ASR 模型可配置（6 款模型 + UI 下拉框）
- ✅ 新增 LLM 模型可配置（动态拉取 Ollama 模型列表）
- ✅ 新增缓存目录显示 + 一键清空
- ✅ 修复 CUDA OOM 未捕获导致降级失效的 Bug
- ✅ 修复换音频后返回旧纪要的缓存污染 Bug
- ✅ 新增 ASR 内容指纹校验机制

### v1.0（初始版本）
- 初始版本，固定 ASR/LLM 模型，V1 Prompt（11 板块深度版）