Nano PDF 開源 PDF 工具拆解：用 Gemini 改投影片的機制、成本與風險

用 AI 摘要這篇文章：

ChatGPT Claude Perplexity Google Grok

Nano PDF 是一個把「自然語言改 PDF」這件事做成命令列工具的開源專案，背後的引擎是 Google 的 Gemini 3 Pro Image 圖像模型。它真正有意思的地方不是「丟給 AI 重畫一頁」，而是它用 Tesseract OCR 把被覆蓋掉的可搜尋文字層重新縫回去，讓改完的 PDF 還能選字、還能搜尋。這個設計在原始碼裡查得到、是真的。但它也是一個八個月沒更新、單一作者、沒有測試、安裝還會踩坑的早期工具，要用之前得先把成本和風險算清楚。

這篇把原始碼層的機制、它踩到的安裝坑、以及「PDF 內容會送 Google」這件必須先講的事一次說明白，讓你判斷要不要為了它去開 Gemini 付費帳單、裝 Poppler 跟 Tesseract。

一句話：它做什麼，邊界在哪

Nano PDF 解決的任務是「用一句話改 PDF 投影片的內容」。你給它一頁、給它一句指令（例如把日期改成 2025 年 10 月），它就把那一頁渲染成圖、連同指令送給 Gemini 3 Pro Image 生成一頁新的圖、再把新圖塞回原本的 PDF。它適合的是投影片、Pitch Deck、報告這類「頁面感」很重的文件，不是要逐字精確排版的合約或表格。

一個必須先講清楚的邊界：它走的是圖像生成路線。模型叫 gemini-3-pro-image-preview（原始碼 ai_utils.py 第 57 行），回傳型態包含 IMAGE，所以它產出的是一張重新畫過的頁面，不是在原檔上改幾個字。這代表字型、排版、精確度都取決於模型當下畫得準不準，你把它當「精確編輯器」會失望，把它當「整頁重生成」比較接近事實。

真正值得拆的設計：OCR 把文字層縫回去

如果只是「PDF 截圖丟給 AI 重畫」，這工具其實沒什麼特別。它跟一堆陽春方案拉開距離的關鍵，是原始碼 pdf_utils.py 第 93 行這一行：生成完新頁面圖之後，它呼叫 pytesseract.image_to_pdf_or_hocr，用 Tesseract 對那張新圖做一次 OCR，產生一個帶有隱藏文字層的 PDF，再把這層文字蓋回去。

白話講，就是 AI 重畫完之後，工具會再幫這張「死圖」補上一層可被選取、可被複製、可被搜尋的文字。改過的投影片才不會變成只能看不能選的圖片，丟進協作流程或檢索系統時還認得字。這個機制是它在原始碼層最實在的價值，也是判斷它「值不值得裝」時最該放大來看的一段。

這層文字層為什麼值得單獨講？因為它直接決定改完的 PDF 還能不能進入你既有的工作流。一份失去文字層的 PDF，在 Google Drive 或 Notion 裡搜尋不到內容、複製不出數字、螢幕閱讀器唸不出來、合併到別份文件時只剩圖。很多把「AI 改圖」當賣點的工具到這一步就停了，產出漂亮但等同死圖。Nano PDF 多做的這一步 OCR，讓產物勉強回到「文件」而不是「圖片」的分類，這是它跟純改圖方案最實際的差別。代價是 OCR 本身有極限，這個後面會講。

Pin

整條工作流程拆開是這樣：先用 Poppler（pdf2image 與 pdftotext）把目標頁渲染成圖、抽出文字；把圖和你的指令送進 Gemini；拿回新頁面圖後，用 Tesseract 補文字層；最後用 pypdf 把新頁面拼回原文件。所以它有兩個系統級依賴必須先裝：poppler 和 tesseract，原始碼 pdf_utils.py 第 9 行的 check_system_dependencies 會在啟動時檢查這兩個指令在不在，缺了會直接擋住並給各作業系統的安裝提示。這也是它最容易卡住的第一關。

兩個系統依賴的安裝指令，原始碼裡也寫好了：macOS 是 brew install poppler tesseract，Windows 是 choco install poppler tesseract，Linux 則是 sudo apt-get install poppler-utils tesseract-ocr。這三個平台它都有跑 CI 驗證安裝。換句話說，裝系統依賴這關不難，難的是後面那個 typer 依賴坑，那是 Python 套件層的問題。

指令長相：edit 能批次，add 只能一次一頁

它有兩個主要指令。edit 可以一次改多頁，每一頁配一句各自的指令，像這樣：

nano-pdf edit deck.pdf \
  1 "Update date to Oct 2025" \
  5 "Add company logo" \
  10 "Fix typo in footer"

原始碼 main.py 第 133 行用 ThreadPoolExecutor(max_workers=10) 處理這些頁面，所以多頁是平行跑的，最多十頁同時送 Gemini。這裡的細節是：平行處理只有 edit 路徑才有。

另一個指令 add 用來插入全新的頁面，例如在開頭加一張標題頁。但 add 的簽名（main.py 第 165 行）每次只吃一個頁碼和一句指令，也就是你沒辦法一個指令加好幾頁。GitHub 上有一個還沒合併的 PR #3 就是在要求做批次新增，到現在仍掛著。如果你打算一次補好幾張新頁，目前得一個一個指令慢慢跑。

新增頁面時它有個貼心的設計：如果你沒給 --style-refs，add 預設拿第一頁當視覺風格參考（main.py 第 227 行起），把參考頁的圖連同你的指令一起送給 Gemini，請模型「對齊這個字型、配色、版面」。這讓新頁面看起來像原本就屬於這份投影片，而不是硬塞一張外來的圖。--use-context 這個開關在 edit 預設是關的、在 add 預設是開的，行為不一樣，手動跑的時候要注意。

Pin

能力只證明一半：品質、穩定度要自己驗

以下三件事，原始碼和官方資料只能證明「它做得到」，沒辦法證明「做得好」，得你自己拿非機密樣本去試：

生成出來的視覺品質就是其一。模型把整頁重畫一次，字型準不準、圖表對不對、配色會不會跑掉，取決於 Gemini 3 Pro Image 當下畫成什麼樣，原始碼沒辦法保證。再來是 OCR 文字層的準確度，Tesseract 對風格化字體或小字的辨識本來就有極限，README 自己的疑難排解段也承認「對風格化字體或小字可能不完美」。穩定度同樣存疑，GitHub 上 issue #2 回報模型有時只回文字不回圖，會直接拋出「No image generated」錯誤中斷，到現在還沒解。

所以如果你要把 Nano PDF 用在「交件前最後一關」這種不能出錯的場景，風險偏高。它比較適合當作「快速產出一版草稿、再人工微調」的起點。

會改變你決定的硬限制

免費方案跑不動。原始碼 ai_utils.py 第 63 到 70 行專門捕捉 Gemini 的配額與帳單錯誤，然後直接告訴你「這個工具需要已開通計費的付費 API key，免費層的 key 不支援圖像生成」。所以它不是免費工具，你得在 Google AI Studio 拿一把 key、還要在自己的 Google Cloud 專案開通計費。每一頁生成都是要花錢的 API 呼叫，--resolution 可以選 4K、2K、1K 三檔（預設 4K）來在品質和成本之間取捨。README 沒有給每頁實際花多少錢的數字，只連到 Google 的定價頁，所以你得自己去查 Gemini 3 Pro Image 每張圖的計價，再乘上你要改的頁數，才是真實成本。批次改一份十幾頁的投影片，帳單會比直覺得高一些。

你的 PDF 內容會送 Google，而且 Google 搜尋預設是開的。這是這類 BYOK 工具最該先講清楚的一條。你的投影片頁面圖、抽出來的文字，都會送進 Google Gemini API；更要注意的是 --disable-google-search 這個開關的存在，反過來代表「Google 搜尋預設是開啟的」（main.py 第 111 行 enable_search = not disable_google_search），也就是你的指令內容還可能再被送去 Google 搜尋一次。換句話說，機密文件、未公開的財報投影片、含個資的資料，都不該丟進這個工具；真的要用，至少先加 --disable-google-search 降低外洩面。這條比任何功能介紹都更影響你的決策。

裝不起來的第一個坑：typer[all]。專案的 pyproject.toml 把 typer[all] 列為依賴，但 PyPI 上現在的 typer（0.27.1）已經拿掉了 [all] 這個 extra，issue #4（2026 年 4 月開的）確認 pip install nano-pdf 會裝不乾淨或跳警告。實際的解法是改用 uvx nano-pdf，uv 解析這顆壞依賴的能力比 pip 好，README 也是用 uvx 當主要安裝路徑。如果你堅持用 pip，要有心理準備會在這關卡一下。

它是一個早期、接近停滯的單人專案。授權是 MIT（允許商業使用，這部分乾淨），但專案活躍度很誠實地告訴你它的成熟度：到目前為止約 1300 多顆星、80 多個 fork，數字不算冷門，社群確實注意到了它；但 main 分支最後一次 commit 停在 2025 年 12 月 3 日，之後八個月沒有更新；三個 PyPI 版本（0.1.0、0.2.0、0.2.1）全部擠在 2025 年 11 月底那兩天發完就沒了；沒有任何 GitHub Release；CI 只跑 ruff lint 和安裝檢查，沒有單元測試；實際上是一位作者 Gavriel Cohen 加另一位貢獻者兩個人的專案，作者帳號也沒有留公司或地點資訊。把它當「有趣但有風險的早期實驗」來用，比當「穩定維護中的生產工具」更接近事實。一旦撞到 bug，能不能等到作者修，是個未知數。

還有一個藏在原始碼、README 沒寫的限制：當你開啟 --use-context 把整份文件文字當脈絡送進去時，每一頁的文字會被截斷在前 2000 字元（pdf_utils.py 第 67 行的 clean_text[:2000]）。長文件或字密集的頁面，模型拿到的脈絡其實是截斷版，這會影響生成的準確度。

跟其他 AI 投影片工具的定位差別

Nano PDF 處理的是「已經存在的 PDF 投影片」，方向是改既有內容。如果你要的是「從無到有生成一份簡報」，那是另一類工具的任務：例如 Banana Slides 這類開源 AI 簡報產生器做的是從主題生出投影片，PPT Master 走的是把文件轉成可編輯投影片的工作流，兩者跟 Nano PDF「拿現成 PDF 去改」是不同的入口。Nano PDF 的位置比較像是這些生成工具下游的「事後修改層」，而不是取代它們。

如果你在意的是命令列、本地終端、把 AI 接進既有流程這個角度，Operit AI 把終端機和本地大模型接起來的方向也能參考，雖然它處理的不是 PDF。共同點是這類工具都把「要不要把內容送雲端」當核心取捨，差別在 Nano PDF 的雲端是強制、無法避開的 Gemini 圖像生成。

值不值得裝：低成本驗證的第一步

如果你看到這裡還想試，最省成本的驗證路徑是：先用 brew install poppler tesseract（macOS）或對應的系統指令把兩個系統依賴裝好，再用 uvx nano-pdf 跑（避開 pip 那個 typer 坑），準備一份你不在乎被 Google 看到的非機密投影片當樣本，先開 --disable-google-search，跑一頁 edit 看結果。

判斷標準很具體：跑完那一頁，選起來看文字能不能被選取複製（驗證 OCR re-hydration 有沒有真的作用）、視覺風格有沒有跑掉（驗證圖像生成對你的文件類型準不準）、有沒有噴出「No image generated」這類錯誤（驗證你會不會撞到 issue #2 的穩定度問題）。三項都還能接受，再考慮開通 Gemini 付費方案正式用；只要有一項明顯不行，就先別投入。這個工具的設計誠實可核對，但它是不是適合你的工作流，只有你自己跑一頁才知道。

有幾種情境可以直接跳過這個工具，不必浪費額度：文件屬於機密、未公開財報、含個資或醫療資料的，光是把內容送 Google Gemini API 這一條就不該冒險，--disable-google-search 也只能擋住搜尋那層，擋不住圖像生成本身就是雲端處理；需要逐字精確、合約級排版的文件，圖像重生成路線先天不適合；以及預期「裝完就能穩定量產」的團隊，這個專案的成熟度還撐不住這個期待。反過來說，如果你的投影片是非機密的對外材料、你本來就習慣命令列、能接受產出一版草稿再手調，它那條 OCR 縫文字層的設計確實是同類截圖重畫方案裡少見會多做的一步。