voelspriet/aiwhisperer
GitHub: voelspriet/aiwhisperer
一款用于 PDF 脱敏分块、突破云端 AI 上传限制并降低敏感数据暴露风险的工具。
Stars: 46 | Forks: 6
# AIWhisperer
[](https://www.python.org/downloads/)
[](https://creativecommons.org/publicdomain/zero/1.0/)
[](https://github.com/voelspriet/aiwhisperer/releases)
** 基于 DPG Media 课程。Whisper 你的文档给 AI——以降低暴露敏感数据的风险。**
## 为什么这个工具存在
**问题 1：文件太大无法上传**
你有一个 170 MB 的调查文件。你尝试使用云 AI：
- ChatGPT：“上传失败”
- Claude.ai：“不支持大于 31 MB 的文件”
- Gemini：“文件大于 100 MB”
你的文件太大以至于不能失败，但又大到无法上传。AIWhisperer 将 PDF 转换为文本（体积缩小最高达 92%）并将其拆分成云 AI 可以处理的块。
**问题 2：太敏感而无法上传，本地运行又太慢**
你有机密文档。本地 AI 是安全的，但速度令人痛苦——云 AI 几分钟完成，本地 AI 却要数小时。因此你仍然上传到云 AI，但未脱敏，只希望一切顺利。
AIWhisperer 给你一条中间路径：本地脱敏，云端分析，本地解码。你获得云 AI 的速度，同时减少敏感数据的暴露。
## 它是如何工作的
| 步骤 | 位置 | 发生什么 |
|:----:|:-----:|:-------------|
| 1 | 本地 | **转换** - PDF 转文本（对扫描页使用 OCR） |
| 2 | 本地 | **拆分** - 分成块（每块 500 页） |
| 3 | 本地 | **编码** - 用占位符替换名称 |
| | | `John Smith` → `PERSON_001` |
| | | `+31 6 12345678` → `PHONE_001` |
| | | 保存 `mapping.json` 到本地 |
| 4 | 云端 | **上传** 脱敏文件到 AI（NotebookLM 等） |
| 5 | 云端 | **AI 分析** - 发现模式，构建时间线 |
| 6 | 本地 | **下载** AI 输出 |
| 7 | 本地 | **解码** - 使用 `mapping.json` 还原真实名称 |
**这减少了——但不能完全消除——暴露敏感数据的风险。始终在上传前检查脱敏输出。**
## 你可以对 AI “低语”什么？
一旦文档脱敏，就可以向 AI 提问：
- **构建时间线** - “创建所有事件的编年时间线”
- **发现联系** - “谁和谁沟通？绘制关系图”
- **识别模式** - “哪些电话号码一起出现？哪些地点重叠？”
- **总结** - “这份 4000 页调查的关键发现是什么？”
- **提取数据** - “列出所有带有日期和金额的财务交易”
- **交叉引用** - “哪些人出现在多个文档中？”
AI 使用 `PERSON_001`、`PHONE_002`、`PLACE_003`。分析完成后，AIWhisperer 还原真实名称：`PERSON_001` → `John Smith`、`PHONE_002` → `+32 489 66 70 88` 等。
**结果：** 在减少敏感数据暴露的情况下实现 AI 驱动的分析。
## 重要警告
**ALWAYS CHECK THE OUTPUT BEFORE UPLOADING TO AI.**
此工具并不完美。检测可能遗漏内容。在上传任何脱敏文档前：
1. **检查脱敏输出** - 打开文件并验证敏感数据是否已被替换
2. **先使用 `--dry-run`** - 查看在提交前会检测到什么
3. **检查唯一标识符** - 职位、罕见事件或具体描述仍可能识别身份：
- 不良：`"PERSON_001, the mayor of Springfield"` → 仍可识别
- 不良：`"PERSON_001 arrested in Europe's largest drug bust"` → 事件本身识别了该人
- 良好：`"PERSON_001 transferred money to PERSON_002"` → 安全
4. **先用样本数据测试** - 在处理真实机密文档前先测试
5. **你需承担责任** - 此工具是辅助，但 **你** 必须验证输出是否安全
**没有检测是 100% 准确的。** 拼写不寻常的名称、新模式或边缘情况可能漏过。拿不准时，请手动检查。
## 这个工具背后的故事
此工具源于一次真实调查：一个 170 MB 的可卡因走私案卷宗，包含法院命令、窃听记录、基站数据、逮捕令、银行对账单和审讯协议。
问题在于？你不应该将机密文件上传到云 AI。即使你想这么做：
- ChatGPT：“上传失败”
- Gemini：“文件大于 100 MB”
- Claude.ai：“你不得上传大于 31 MB 的文件”
解决方案？**本地编码 → 云端分析 → 本地解码。**
阅读完整故事：**[用 AI 快速阅读大规模刑事调查](https://www.digitaldigging.org/p/speed-reading-a-massive-criminal)** - *如何在 20 分钟内弄懂 4,713 页而不泄露数据*
## 概念
```
BEFORE: "On 16/10/2023, officers arrested John Smith at 123 Harbor Road.
He was hired by Marcus Johnson."
AFTER: "On 16/10/2023, officers arrested PERSON_001 at ADDRESS_001.
He was hired by PERSON_002."
AI OUTPUT: "Timeline shows PERSON_001 arrested on 16/10/2023, connected to
PERSON_002 who runs COMPANY_001, COMPANY_002 and COMPANY_003"
DECODED: "Timeline shows John Smith arrested on 16/10/2023, connected to
Marcus Johnson who runs Hideout 1, Hideout 2 and Hideout 3"
```
**变化的内容：** 姓名、地点、电话、邮箱、IBAN、车辆、地址
**保持不变的内容：** 结构、关系、模式、日期、金额
## 快速开始
### 安装
#### 选项 1：macOS 应用（Apple Silicon）
从 [Releases](https://github.com/voelspriet/aiwhisperer/releases) 下载 `.dmg` 安装程序——无需 Python。
1. 下载 `AIWhisperer-x.x.x-arm64.dmg`
2. 打开 DMG 并运行 `install.command`
3. 在终端运行 `aiwhisperer --help`
注意：该应用未签名。首次运行时，右键点击并选择“打开”以绕过 Gatekeeper。
#### 选项 2：pip 安装（所有平台）
```
# 使用 spaCy 和 OCR 支持安装（推荐）
pip install aiwhisperer[spacy,ocr]
# 下载荷兰语语言模型
python -m spacy download nl_core_news_sm
# 其他可用语言：en, de, fr, it, es
# 检查已安装内容和缺失项
aiwhisperer check
```
`check` 命令会精确显示已安装内容及如何修复缺失依赖：
```
$ aiwhisperer check
AIWhisperer Dependency Check
===================================
Python: 3.10.5 (OK)
PDF Conversion:
[x] marker-pdf: Installed (best accuracy)
[x] pymupdf: Installed
[x] tesseract: Installed (OCR fallback)
NER Detection:
[x] spaCy: Installed (v3.8.11)
Language Models:
[x] nl: nl_core_news_sm
[ ] en: en_core_web_sm
-> Fix: python -m spacy download en_core_web_sm
```
### 命令行
**两种工作流：**
```
# 工作流程 1：非机密文件（仅转换）
aiwhisperer convert document.pdf
# 工作流程 2：机密文件（一步转换 + 清洗）
aiwhisperer convert document.pdf --sanitize
```
**大型机密文件的完整工作流：**
```
# 步骤 1：转换并清洗（对大文件使用拆分）
aiwhisperer convert investigation.pdf --split --max-pages 500 --sanitize
# 创建：
# investigation_part1.txt ← 纯文本
# investigation_part1_sanitized.txt ← 发送至 AI
# investigation_part1_mapping.json ← 保留此文件 LOCAL
# 重要：在上传前检查清洗后的文件！
# 确保没有敏感数据泄露。
# 步骤 2：将清洗后的文件上传至 NotebookLM
# 要求 AI 构建时间线、发现模式等。
# 步骤 3：保存 AI 输出，然后解码还原真实名称
aiwhisperer decode ai_analysis.txt -m investigation_part1_mapping.json
# 结果：完整分析并恢复真实名称
```
对于较小文件（小于约 50 MB），可以跳过 `--split` 参数。
### Python API
```
from aiwhisperer import encode, decode, Mapping
from aiwhisperer.converter import convert_pdf
# 转换 PDF 为文本
text, metadata = convert_pdf("investigation.pdf")
# 编码
sanitized, mapping = encode(text, language='nl')
# 保存
open("sanitized.txt", "w").write(sanitized)
mapping.save("mapping.json")
# 重要：在上传前检查 sanitized.txt！
# ... 将 sanitized.txt 发送至 AI，获取分析结果 ...
# 解码
ai_output = open("ai_analysis.txt").read()
final = decode(ai_output, mapping)
open("final_report.txt", "w").write(final)
```
## PDF 转换
AIWhisperer 包含内置的 PDF 转文本功能，支持对扫描文档使用 OCR。
### OCR 后端
| 后端 | 准确度 | 安装 |
|------|--------|------|
| **marker-pdf**（推荐） | 优秀 | `pip install marker-pdf` |
| **pytesseract**（备用） | 良好 | `pip install pymupdf pytesseract pdf2image` + Tesseract |
marker-pdf 底层使用 Surya OCR——目前最准确的 OCR 解决方案之一。
### 用法
```
# 转换 PDF（自动选择最佳后端）
aiwhisperer convert document.pdf
# 强制使用特定后端
aiwhisperer convert document.pdf --backend marker
# 将大 PDF 拆分为多个文本文件
aiwhisperer convert large.pdf --split --max-pages 500
# 仅显示 PDF 信息
aiwhisperer convert document.pdf --info
```
### 安装 Tesseract（备用）
如果 marker-pdf 不适用于你：
```
# macOS
brew install tesseract tesseract-lang
# Ubuntu/Debian
apt install tesseract-ocr tesseract-ocr-nld tesseract-ocr-deu tesseract-ocr-fra
# Windows：从 https://github.com/UB-Mannheim/tesseract/wiki 下载
```
## 检测到什么内容
| 类别 | 示例 | 捕获内容 |
|------|------|----------|
| **人物** | `Jan de Vries`, `El Mansouri Brahim` | 通过 NER 和上下文模式识别的姓名 |
| **地点** | `Antwerpen`, `te Wuustwezel` | 城市、`te X`、`richting X` 模式 |
| **电话** | `+32 489 66 70 88`, `052/26.08.60` | 比利时、荷兰及国际格式 |
| **邮箱** | `jan@example.com` | 标准邮箱模式 |
| **IBAN** | `BE44 3770 8065 345` | 欧洲银行账户 |
| **车辆** | `Fiat Ducato`, `BMW X5` | 50 多个汽车品牌和型号 |
| **道路** | `N133`, `A12`, `E19` | 欧洲道路编号 |
| **街道** | `Stationstraat`, `Koning Albertlaan` | 荷兰/比利时街道名 |
| **地址** | `Dorpstraat 31/301` | 包含门牌号的完整地址 |
| **出生日期** | `26/04/1993`（附近有“geboren”） | 上下文中的出生日期 |
| **ID** | `123456782` | 荷兰 BSN（验证通过）、比利时国家编号 |
## 常见问题
### 为什么不直接上传到 AI？
**安全性。** 刑事调查、医疗记录、法律文件——你不应该将这些上传到云 AI。AIWhisperer 让你在不暴露真实数据的情况下获得 AI 分析。
**大小限制。** 大多数聊天机器人无法处理大文件：
- ChatGPT：“上传失败”
- Gemini：“文件大于 100 MB”
- Claude.ai：“不得上传大于 31 MB 的文件”
原始工作流使用 **Claude Code**（本地运行，无上传限制）进行文件转换，并使用 **NotebookLM** 分析脱敏文本。
### AI 能否从上下文中猜出 PERSON_001 是谁？
可以，如果有唯一标识符。请参见上方的 **⚠️ 重要警告** 部分。始终在上传前检查脱敏输出。
### 扫描版 PDF 怎么办？
AIWhisperer 处理的是文本。对于扫描文档：
1. 先用 OCR 将 PDF 转换为文本（Claude Code 可协助）
2. 然后脱敏文本输出
3. 原始文章描述了以这种方式处理 565 页扫描内容的过程
### 为什么是 6 种语言？
每种语言都有独立的 spaCy NER 模型，基于本地文本训练：
- `nl` 荷兰语 - `nl_core_news_sm`
- `en` 英语 - `en_core_web_sm`
- `de` 德语 - `de_core_news_sm`
- `fr` 法语 - `fr_core_news_sm`
- `it` 意大利语 - `it_core_news_sm`
- `es` 西班牙语 - `es_core_news_sm`
### 这能在法庭上采纳吗？
**可以。** AI 不是证据。它是一盏探照灯。
你在法庭上出示原始数据并解释推理过程。辩护方可检查相同文档。他们不需要审核算法，因为算法没有生成证据——只生成了路线图。
这就像 Ctrl+F 不破坏证据链一样，模式识别在匿名数据上也不会破坏。它加速了调查，但不会取代验证。
**示例：** 假设 AI 发现：*“PERSON_A 在转账给 COMPANY_X 前三天与 PERSON_B 见面。”* 这不是你在法庭上提交的结论。这是一个线索。你回到原始文档——第 847 页、第 1,203 页、第 3,421 页。证据就在那里。AI 帮你找到该看哪里——用 20 分钟代替 5 天。
### 检测准确度如何？
检测使用多层机制：
1. **spaCy NER** - 上下文感知的姓名和地点识别
2. **模式匹配** - 对结构化数据（电话、邮箱、IBAN）具有高置信度
3. **上下文标记** - 捕获 NER 可能遗漏的 `te Wuustwezel`、`richting Antwerpen` 等模式
始终使用 `--dry-run` 进行测试运行，查看会检测到什么。
### 如果漏掉了怎么办？
`--dry-run` 标志会显示确切将被替换的内容。如果遗漏了：
1. 检查是否应添加该模式
2. 对于一次性情况，在上传前手动编辑
3. 在 GitHub 上报告问题
### 能否对多个文档使用一致的占位符？
可以。重用相同的映射：
```
mapping = Mapping()
for doc in documents:
sanitized, mapping = encode(doc, mapping=mapping)
# PERSON_001 在所有文档中指代同一人
```
## 实际结果
来自原始调查：
- **输入：** 170 MB PDF，4,713 页，1,053,356 个词
- **转换后：** 13.8 MB 文本（缩小 92%）
- **处理时间：** 20 分钟（相比 5 天人工）
- **输出：** 包含所有关联的完整时间线
机器擅长它擅长的事——模式识别、重复提取、组织混乱。你擅长人类做的事——判断、上下文、知道什么时候不对劲。
## 支持的语言
| 代码 | 语言 | 模型 |
|------|------|-------|
| `nl` | 荷兰语 | `nl_core_news_sm` |
| `en` | 英语 | `en_core_web_sm` |
| `de` | 德语 | `de_core_news_sm` |
| `fr` | 法语 | `fr_core_news_sm` |
| `it` | 意大利语 | `it_core_news_sm` |
| `es` | 西班牙语 | `es_core_news_sm` |
## 高级选项
### 脱敏策略
```
aiwhisperer encode doc.txt --strategy replace # PERSON_001 (default, reversible)
aiwhisperer encode doc.txt --strategy redact # [PERSON] (not reversible)
aiwhisperer encode doc.txt --strategy mask # J** d* V**** (partial)
aiwhisperer encode doc.txt --strategy hash # a1b2c3d4 (one-way)
```
### 检测后端
```
aiwhisperer encode doc.txt --backend hybrid # spaCy + patterns (default)
aiwhisperer encode doc.txt --backend patterns # patterns only (no spaCy needed)
```
### 预览检测
```
aiwhisperer encode doc.txt --dry-run # Shows what would be replaced
aiwhisperer analyze doc.txt # Full detection statistics
```
## 致谢与引用
### 原始故事
**[用 AI 快速阅读大规模刑事调查](https://www.digitaldigging.org/p/speed-reading-a-massive-criminal)**
*如何在 20 分钟内弄懂 4,713 页而不泄露数据*
作者：Henk van Ess，2026 年 1 月
### 代码来源
- 脱敏策略基于 [mstack.nl](https://mstack.nl/blogs/anonymize-pii-llm/)
- spaCy NER 集成遵循 [spaCy 文档](https://spacy.io/)
- BSN 验证使用荷兰 [11-检验算法](https://nl.wikipedia.org/wiki/Burgerservicenummer)
- 可选：[Microsoft Presidio](https://github.com/microsoft/presidio)、[GLiNER](https://github.com/urchade/GLiNER)
### Henk van Ess 增加的功能
- 车辆品牌/型号检测
- 道路编号检测（N/A/E/R）
- 基于上下文的定位检测
- 基于上下文的姓名检测
- 为 AI 上下文生成图例
- 大文件分块支持
- 真实世界测试与验证
## 许可证
CC0 1.0 通用 - 公共领域
“这就是当今真正的技能：知道该按哪些按钮，以及知道何时停止按下并开始思考。”
标签：AI上传, CC0许可, NotebookLM, OCR, PDF压缩, PDF瘦身, 二进制发布, 云AI分析, 分块处理, 占位符替换, 大文件处理, 安全上传, 开源工具, 敏感数据, 数据匿名化, 数据脱敏, 文件大小优化, 文本提取, 文档处理, 文档拆分, 映射表, 本地预处理, 网络安全, 调查文件分析, 逆向工具, 隐私保护