UFO-USA

2026 年 5 月 8 日，美国战争部（War.gov）通过“总统关于 UAP 遭遇的解密和报告系统”发布了首批官方解密文件。为了降低研究门槛、提升数据可用性，社区迅速推出了 War.gov UFO Markdown 归档仓库。

该仓库将原始的 120 个 PDF 文件（共 4,185 页）转换为结构化的 Markdown 格式，利用 Gemini 3.1 Flash-Lite 进行高精度 AI 辅助 OCR 转录。这不仅让海量非结构化文档变得可搜索、可引用，更为后续的自然语言处理、知识图谱构建和深度分析奠定了坚实基础。

核心亮点：结构化、高精度、可复现

1. 全量 Markdown 转换

• 覆盖范围广：涵盖 120 个官方 PDF 文件，包括事件摘要、任务报告、FBI 照片记录等。
• 页面级粒度：每个 PDF 页面独立存储为 page-####.md，便于精准引用和局部处理。
• 字典序排列：文件名采用补零页码（如 page-0001.md），确保文件系统排序与阅读顺序一致。

2. AI 辅助高精度 OCR

• 模型选择：使用 gemini-3.1-flash-lite（temperature=0），平衡速度与准确性。
• 图像处理：通过 PyMuPDF 以 200 DPI 渲染页面，调整最长边至 3000 像素并编码为 JPEG，优化识别效果。
• 结构化输出：保留 YAML Front Matter，记录源标题、文件路径、页码、总页数及生成时间，方便溯源。

3. 完善的元数据与错误追踪

• manifest.jsonl：记录每次转换尝试的状态（ok/error）、字符数及错误详情，透明展示数据处理过程。
• 错误文件保留：11 个未能成功转换的页面保留为 .error.txt，供人工复核或后续重试。
• 清单映射：提供 metadata/uap-csv.csv 和 pdf_manifest.tsv，清晰映射源记录与转换后文件夹的关系。

4. 可复现的工程流程

• 开源脚本：提供 process_dataset_with_gemini.py（转换）和 clean_converted_archive.py（清洗）脚本。
• 增量重建：脚本支持断点续传，跳过已存在的 Markdown 文件，节省 API 成本。
• 确定性清洗：自动折叠重复 Token（如数千个 [illegible] 或  ），移除本地绝对路径，确保归档干净统一。

📂 归档文件结构

.
├── converted/                  # 转换后的 Markdown 文件
│   ├── 001-65_HS1-.../
│   │   ├── page-0001.md
│   │   ├── page-0002.md
│   │   └── ...
│   └── manifest.jsonl          # 转换状态日志
├── metadata/                   # 元数据与清单
│   ├── uap-csv.csv             # 原始发布清单
│   ├── pdf_manifest.tsv        # PDF 映射清单
│   └── download_summary.json   # 下载统计
├── scripts/                    # 处理脚本
│   ├── process_dataset_with_gemini.py
│   └── clean_converted_archive.py
├── requirements.txt            # Python 依赖
└── README.md

💡 注意：downloads/（原始 PDF）、outputs/（临时文件）等目录被 .gitignore 排除，以保持仓库轻量。

快速开始：重建或继续归档

1. 环境准备

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. 配置 API Key

在 shell 中设置 Gemini API Key（切勿提交到代码库）：

export GEMINI_API_KEY='your-api-key-here'

3. 运行转换脚本

干跑测试（不调用 API）：

python3 scripts/process_dataset_with_gemini.py --dry-run

执行转换（支持并行与限流）：

python3 scripts/process_dataset_with_gemini.py \
  --output-dir converted \
  --temperature 0 \
  --workers 16 \
  --rpm 10000

常用参数说明：

• --workers N：并行工作线程数。
• --rpm N：每分钟请求限制，避免触发 API 配额。
• --force：强制重新生成已存在的页面。
• --pages 1,4,9-12：仅处理指定页面，适合调试。

4. 清洗数据

移除重复 Token 痕迹和本地路径：

# 预览清理效果
python3 scripts/clean_converted_archive.py

# 应用清理
python3 scripts/clean_converted_archive.py --apply

⚠️ 已知限制与注意事项

• AI 辅助性质：生成的 Markdown 是 AI 辅助转录结果，可能存在细微误差。对于法律或学术引用，请以原始 PDF 为准。
• 非 PDF 内容排除：初始清单中的 28 个视频和 14 张图片未包含在此 PDF 归档流程中。
• 错误页面：11 个页面因 Gemini 返回空响应而失败，详见 manifest.jsonl 中的 error 记录。

应用场景

• 语义搜索：结合向量数据库，实现跨文档的自然语言问答（如“查找 2022 年伊拉克任务报告中的异常现象描述”）。
• 知识图谱构建：提取实体（地点、时间、机型、目击者），构建 UAP 事件关联网络。
• 趋势分析：统计特定关键词（如 “orb”, “triangle”, “radar”）随时间的出现频率。
• 自动化摘要：对每份报告生成简短摘要，快速筛选高价值文档。