# PDF 文件處理討論

**作者**：M4  
**日期**：2026-05-07  

---

## 問題

目前 Momentry 無法處理 PDF：
- ffprobe 無法解析 PDF（回傳錯誤）
- 無對應 processor 腳本
- 無 text extraction 工具安裝

---

## 方案提案

### 核心想法：PDF = 多頁圖片，每頁 = 1 幀 video

```
PDF (10頁)
  │
  ├── 頁 1 → page_001.jpg ─→ OCR + YOLO + Face（如同單幀 video）
  ├── 頁 2 → page_002.jpg ─→ OCR + YOLO + Face
  ├── ...
  └── 頁 10 → page_010.jpg ─→ OCR + YOLO + Face
  
  + pdftotext → raw text → BM25 search
```

### 需要安裝的工具

| 工具 | 用途 | 安裝方式 |
|------|------|---------|
| `poppler`（pdftoppm, pdftotext） | PDF→圖片、PDF→文字 | `brew install poppler` |
| `tesseract`（選配） | 圖片 OCR（目前已用 PaddleOCR） | `brew install tesseract` |

---

## 設計選項

### A. 新增 `pdf_processor.py`

專用 processor，處理 PDF 的完整流程：

```
pdf_processor.py
  1. pdftoppm  → page_001.jpg ... page_N.jpg（每頁一張圖）
  2. pdftotext → raw_text.txt（直接提取文字）
  3. (選) tesseract → 對圖片 OCR（若 pdftotext 效果差）
  4. 輸出 JSON：每頁結果 + 全文
```

**優點**：獨立、專注、可慢慢優化
**缺點**：無法複用現有 YOLO/Face/Ocr processors

### B. 註冊 PDF → 拆成多張單幀 video → 分別註冊

將 PDF 每頁轉為 JPEG，分別註冊為單幀 video：

```
PDF
  → pdftoppm → page_001.jpg (註冊為單幀 video)
               page_002.jpg (註冊為單幀 video)
               ...
               
  每個 page_N.jpg 可跑 face / yolo / ocr（現有 processor 不需改）
  + pdftotext 產出全文 chunk，獨立進 search
```

**優點**：完全複用現有 processor（YOLO/Face/OCR 對單幀 video 已可用）
**缺點**：多個 UUID，管理複雜

### C. 混合方案（建議 🏆）

```
PDF → PDF Processor (新增)
  ├── pdftotext → text → chunk → BM25 search
  └── pdftoppm → page images
        └── 對每頁執行現有：OCR (PaddleOCR) + YOLO + Face
              └── 結果彙整到同一個 file_uuid
```

## 待討論

| 項目 | 問題 |
|------|------|
| 註冊方式 | PDF 用獨立 `POST /api/v1/documents/register` 還是共用 `files/register`？ |
| 資料表 | 沿用 `videos` table 還是新增 `documents` table？ |
| Processor dependency | YOLO/Face 對文件頁面是否有意義？ |
| PDF 文字搜尋 | 純文字 BM25 search（簡單）vs 完整 embedding search（複雜） |
| 優先級 | 這是現在要做的事還是 roadmap 項目？ |
