跳到正文
aihot(aihot.news)· noreply@aihot.news (OpenRouter:Announcements)·· 25 天前品質評分73

OpenRouter 教程:用 LLM 從 PDF 中抽取表格

OpenRouter 教程:用 LLM 從 PDF 中抽取表格

重點導讀

OpenRouter 提供了一套完整的範例程式,示範如何將 PDF 直接送入 LLM 並以嚴格 JSON schema 取得表格行資料。

  • 輸入方式:PDF 以 file 引數送出,並附上 JSON schema,模型回傳帶型別的行。

AI 伴隨問答

自備 Key 深度分析

針對這篇報導有疑問?可直接點選快捷問題或向 AI 追問背景脈絡與技術細節:

正文

OpenRouter:Announcements·2026-10-29 08:00· 2 天前精選AI 評分76

How to Extract Tables from a PDF with an LLM

AI 導讀

OpenRouter 釋出教程,講解如何把 PDF 以檔案形式連同嚴格 JSON schema 發給能讀檔案的模型,讓表格以帶型別的行返回,括號虧損、千分位和腳註標記等清理都寫進欄位描述。

推薦理由

OpenRouter 用五份 PDF 實測了多條抽取路由,給出嚴格 JSON schema 寫法、兩類靜默失敗的檢查和各路由成本對比。

要用 LLM 從 PDF 中提取表格,先把 PDF 發給能讀取檔案的模型,同時附上一份嚴格的 JSON schema,用它描述表格中的一行。模型會返回帶型別的行:數量以整數返回,寫成 (3,878) 的虧損返回 -3878,跨兩頁的表格則返回成一個列表。

我們在五份 PDF 上做了測試,其中兩份是掃描件。所有直接讀取 PDF 的模型都把 644 個單元格全部答對。測試中的失敗都出在 PDF 到達模型所走的路徑上,其中兩次還返回了正常響應、沒有報錯。

要點速覽

  • 為一行資料定義嚴格的 JSON schema,就能把 PDF 表格轉成帶型別的行;欄位描述則負責清理括號負數、腳註標記這類內容。
  • 在我們的測試中,能讀取 PDF 的模型既能處理數字檔案,也能處理掃描件。不能讀取 PDF 的模型處理掃描件時需要 mistral-ocr 解析器。
  • 掃描件經免費的 cloudflare-ai 解析器處理後返回零行且不報錯,所以要拒絕空結果。
  • 長表格可能因輸出 token 上限而中途截斷,因此凡是 finish_reason 為“length”的響應都要拒絕。

開始之前

執行示例需要準備以下內容。

  • 一個已充值的 OpenRouter 賬戶,以及存放在 OPENROUTER_API_KEY 環境變數中的 API key。本指南用到的模型都是付費的。
  • Python 3.10 或更高版本,以及 requests 包(pip install requests)。
  • Node.js 18 或更高版本,但只有文末的 TypeScript 版本需要。
  • 一份包含表格的 PDF,可以是數字匯出的,也可以是掃描件。

如果你之前沒呼叫過這個 API,快速入門裡演示了第一次請求。

程式碼對數字版 PDF 和掃描件都能用,但結果取決於 PDF 是否帶文本層、掃描質量、解析路徑和模型。示例用了五份測試 PDF,它們都由已知資料生成,因此每個單元格都能與源資料核對。這五份分別是:一張發票、一份季度報告、一份 58 行、跨到第二頁的出貨記錄、一份掃描的採購訂單,以及一份故意做得很粗糙、帶合併單元格的掃描件。

第 1 步:如何傳送 PDF 並拿回行資料?

把下面的程式碼儲存為 extract_tables.py。它把 PDF 作為檔案內容部分發送(做法見我們的 PDF 輸入頁面),並通過結構化輸出要求返回符合你 schema 的 JSON。把 strict 設為 true 後,支援嚴格模式的提供商會讓輸出嚴格遵循 schema,於是每一行都包含全部欄位且型別正確。各提供商的支援情況不一,結構化輸出頁面說明了如何只路由到支援該功能的提供商。

import base64
import json
import os

import requests

API = "https://openrouter.ai/api/v1/chat/completions"
HEADERS = {"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"}

def rows_schema(fields):
    """Wrap the fields of one row in a strict schema for {"rows": [...]}."""
    return {
        "type": "object",
        "properties": {"rows": {"type": "array", "items": {
            "type": "object", "properties": fields,
            "required": list(fields), "additionalProperties": False}}},
        "required": ["rows"],
        "additionalProperties": False,
    }

def extract_table(pdf_path, schema, model="anthropic/claude-haiku-5.5",
                  engine=None, max_tokens=8000):
    with open(pdf_path, "rb") as f:
        data_url = "data:application/pdf;base64," + base64.b64encode(f.read()).decode()
    body = {
        "model": model,
        "max_tokens": max_tokens,
        "messages": [{"role": "user", "content": [
            {"type": "text", "text": "Extract every row of the table in this PDF. "
                                     "Include rows from every page. "
                                     "Return only rows that are in the document."},
            {"type": "file", "file": {"filename": os.path.basename(pdf_path),
                                      "file_data": data_url}},
        ]}],
        "response_format": {"type": "json_schema",
                            "json_schema": {"name": "table", "strict": True,
                                            "schema": schema}},
    }
    if engine:
        body["plugins"] = [{"id": "file-parser", "pdf": {"engine": engine}}]

    response = requests.post(API, headers=HEADERS, json=body, timeout=300)
    response.raise_for_status()
    data = response.json()
    choice = data["choices"][0]
    if choice["finish_reason"] == "length":
        raise ValueError(f"Output stopped at max_tokens={max_tokens}. "
                         "Raise it or split the PDF.")
    rows = json.loads(choice["message"]["content"])["rows"]
    if not rows:
        raise ValueError("No rows came back. If this PDF is a scan, use a model "
                         "that reads PDFs or engine='mistral-ocr'.")
    return rows, data["usage"]["cost"]

LINE_ITEMS = rows_schema({
    "sku": {"type": "string"},
    "description": {"type": "string"},
    "qty": {"type": "integer"},
    "unit_price": {"type": "number",
                   "description": "USD, no currency symbol or thousands separator"},
    "amount": {"type": "number",
               "description": "USD, no currency symbol or thousands separator"},
})

return 之前的兩個檢查用來捕獲第 3 步和第 4 步中提到的失敗情況,請保留它們。費用來自 usage.cost,用量統計會在每個響應中給出。

在發票上執行這個函式。

from extract_tables import extract_table, LINE_ITEMS

rows, cost = extract_table("invoice.pdf", LINE_ITEMS)
for row in rows[:3]:
    print(row)
print(f"{len(rows)} rows, ${cost:.5f}")
{'sku': 'NW-4100', 'description': 'Hex bolt M8x40', 'qty': 100, 'unit_price': 60.67, 'amount': 6067.0}
{'sku': 'NW-4107', 'description': 'Flange nut M8', 'qty': 2, 'unit_price': 41.72, 'amount': 83.44}
{'sku': 'NW-4114', 'description': 'Bearing 6204-2RS', 'qty': 10, 'unit_price': 52.59, 'amount': 525.9}
10 rows, $0.00067

這次呼叫耗時約六秒。PDF 上顯示的是 6,067.00,而返回的行裡是 6067.0,這個數字不用先清理就能直接相加。去掉千位分隔符的正是欄位描述。

第 2 步:如何處理合併單元格、括號和腳註?

PDF 表格所需的大部分清理工作都可以寫進 schema 的欄位描述裡。我們的季度報告中有一個“Fiscal 2026”表頭,橫跨四個季度列;虧損用括號表示;還有兩個業務板塊名稱(Enterprise 和 Hardware resale)帶腳註標記。欄位描述負責處理括號和腳註標記。跨列表頭不需要描述,因為欄位名已經說明了每個值屬於哪個季度。

from extract_tables import extract_table, rows_schema

THOUSANDS = {"type": "integer",
             "description": "Thousands of USD. A value in parentheses, like (1,204), is negative: -1204."}
QUARTERLY = rows_schema({
    "segment": {"type": "string", "description": "Segment name without footnote markers"},
    "q1": THOUSANDS, "q2": THOUSANDS, "q3": THOUSANDS, "q4": THOUSANDS, "fy_total": THOUSANDS,
})

rows, cost = extract_table("quarterly.pdf", QUARTERLY)
for row in rows:
    print(row)
{'segment': 'Inference API', 'q1': 1813, 'q2': 7299, 'q3': 1612, 'q4': 4422, 'fy_total': 15146}
{'segment': 'Enterprise', 'q1': 1563, 'q2': 2981, 'q3': 5544, 'q4': 7667, 'fy_total': 17755}
{'segment': 'Data products', 'q1': 3163, 'q2': 9658, 'q3': 2729, 'q4': 5854, 'fy_total': 21404}
{'segment': 'Hardware resale', 'q1': 3761, 'q2': -3878, 'q3': -9774, 'q4': -1776, 'fy_total': -11667}
{'segment': 'Professional services', 'q1': 8933, 'q2': 9511, 'q3': 7805, 'q4': 5946, 'fy_total': 32195}
{'segment': 'Total operating income', 'q1': 19233, 'q2': 25571, 'q3': 7916, 'q4': 22113, 'fy_total': 74833}

在“硬體轉售”這一行裡,(3,878) 返回成了 -3878,而且兩個片段名稱裡的腳註標記都不見了。

縱向合併的單元格也是同樣的道理。在我們粗略的掃描中,每個 Category 單元格跨六到九行。我們對這個欄位的描述是:“第一列中的類別。它是合併單元格,因此要在它覆蓋的每一行上重複填寫。”在我們的測試中,這一句說明就足以讓三個能讀 PDF 的模型在全部 30 行上都填好類別。

第 3 步:我該用哪條解析器路線?

如果模型能讀檔案,我們就把 PDF 直接交給它。如果模型不能讀檔案,我們先解析 PDF,再把結果發給模型。檔案解析器外掛的 engine 設定決定用哪個解析器。在不能讀檔案的模型上不設定它時,我們會使用 mistral-ocr,正如 PDF 輸入 頁面所述。根據你的 PDF 長什麼樣來選擇路線。

  • 能讀 PDF 的模型。 不設定 engine。Claude Haiku 5.5、GPT-6 Luna 和 Gemini 3.8 Flash 都能讀檔案,三個模型也都處理了我們那兩份掃描件。PDF 按輸入 token 計費。
  • 不能讀 PDF 的模型,配合 OCR。 使用 engine="mistral-ocr",或者不設定它。它會先對每一頁做光學字元識別(OCR),費用為每 1,000 頁 $2,另加模型的 token 費用。
  • 不能讀 PDF 的模型,配合免費解析器。 只有當每個 PDF 都有文本層時才使用 engine="cloudflare-ai"。匯出的發票和報告有文本層,掃描件沒有。

下面是把掃描版採購訂單分別交給各解析器後、再發給 deepseek/deepseek-v4.1-flash 的結果。該模型接受圖片但不接受檔案,所以 PDF 必須先經過解析器。

from extract_tables import extract_table, LINE_ITEMS

# A model that can't read PDFs, with OCR in front of it
rows, cost = extract_table("scanned.pdf", LINE_ITEMS,
                           model="deepseek/deepseek-v4.1-flash", engine="mistral-ocr")
print(f"mistral-ocr: {len(rows)} rows, ${cost:.5f}")

# The same model with the free text parser
rows, cost = extract_table("scanned.pdf", LINE_ITEMS,
                           model="deepseek/deepseek-v4.1-flash", engine="cloudflare-ai")
mistral-ocr: 6 rows, $0.00211
ValueError: No rows came back. If this PDF is a scan, use a model that reads PDFs or engine='mistral-ocr'.

這個 ValueError 來自第 1 步的空行檢查。沒有這項檢查,第二次呼叫會返回 200 OK,同時給出 finish_reason: "stop" 和 {"rows": []}。解析器在掃描件上沒找到文字,模型也正確地報告了空表格。整個過程不會丟擲任何錯誤,所以沒有這項檢查的流水線會存入零行資料,然後繼續處理下一個檔案。這是兩種靜默失敗中的第一種。我們的粗略掃描表現相同,30 行裡得了 0 分。

另外兩種路線錯誤則會明確報錯。引擎名稱拼錯會返回這個錯誤。

400 {"error":{"message":"plugins.0.pdf.engine: Invalid input","code":400}}

原生引擎只適用於能讀檔案的模型。當我們還是在 DeepSeek V4.1 Flash 上設定了 engine="native" 時,請求成功了一次,隨後兩次因提供商錯誤而失敗。

400 Provider returned error: "The request was rejected. Possible causes: input exceeds the model's maximum context length, or the request contains invalid parameters."

在同一個模型上不設定 engine 時,我們試了兩次都正常,所以不要在不能讀檔案的模型上設定 native。

第 4 步:我的長表格為什麼返回時被截斷了?

模型寫出的每一行都要消耗輸出 token,所以長表格需要較高的 max_tokens。我們那份 58 行的發貨日誌根據模型不同,用了 2,500 到 7,700 個輸出 token,這讓最囉嗦的模型在 extract_table 預設的 8,000 之下幾乎沒有餘量。折算下來是每行 43 到 133 個 token。對於長表格,可以按每個預期行約 150 個 token 起步。然後測量你自己資料的每行用量,並保留 finish_reason 檢查,因為具體數量會因模型和 schema 而異。下面是上限設得太低時會發生的情況。

from extract_tables import extract_table, rows_schema

SHIPMENTS = rows_schema({
    "date": {"type": "string", "description": "YYYY-MM-DD"},
    "shipment_id": {"type": "string"},
    "origin": {"type": "string"},
    "destination": {"type": "string"},
    "weight_kg": {"type": "number", "description": "No thousands separator"},
    "status": {"type": "string"},
})

rows, cost = extract_table("shipments.pdf", SHIPMENTS, max_tokens=600)
ValueError: Output stopped at max_tokens=600. Raise it or split the PDF.

沒有 finish_reason 檢查時,這個請求會以兩種方式之一失敗。普通 JSON 解析會在被截斷的陣列上丟擲錯誤。

JSONDecodeError: Unterminated string starting at: line 1 column 627 (char 626)

第二種方式就是另一種靜默失敗。開啟 Response Healing 外掛後,JSON 能解析,你會得到 58 行中的 5 行,且不拋異常。Healing 修復的是輸出的語法,而它的文件警告說,它無法恢復被 max_tokens 截斷的輸出,所以它補不出模型根本沒寫的那些行。finish_reason 檢查能同時抓住這兩種情況。

第 5 步:如何把行寫入 CSV?

每一行都帶有 schema 中定義的鍵,因此 csv.DictWriter 可以直接從 schema 取列名,並按原樣寫入各行。Excel 能直接開啟結果檔案。

import csv

from extract_tables import extract_table
# Define SHIPMENTS here, copied from step 4

rows, cost = extract_table("shipments.pdf", SHIPMENTS, model="openai/gpt-6-luna")
with open("shipments.csv", "w", newline="") as f:
    fieldnames = list(SHIPMENTS["properties"]["rows"]["items"]["properties"])
    writer = csv.DictWriter(f, fieldnames=fieldnames)
    writer.writeheader()
    writer.writerows(rows)
print(f"Wrote {len(rows)} rows to shipments.csv (${cost:.5f})")
Wrote 58 rows to shipments.csv ($0.00130)

date,shipment_id,origin,destination,weight_kg,status
2026-09-01,SHP-88200,Savannah,Valencia,8754.6,In transit
2026-09-01,SHP-88213,Busan,Los Angeles,2074.7,Customs hold

表格延伸到了第二頁,表頭也在那裡重複出現。而 CSV 只有一個表頭,包含全部 58 行。

該用哪個模型?

我們對每條路線都在全部五份 PDF 上各跑了一次,共六頁、644 個單元格,並把每個單元格與生成這些 PDF 時所用的原始資料逐一比對。每次執行都使用上文中的 extract_table 函式和提示詞,並採用我們的預設提供商路由。每 1,000 頁的成本是按這六頁的總 usage.cost 折算出來的。模型和價格來自我們截至 2026 年 10 月 8 日的模型目錄。這些結果只描述本測試集,不代表模型的普遍表現。

Chart of five PDF table extraction routes on the same five PDFs, six pages and 644 cells. GPT-6 Luna: 644 of 644 cells correct, $0.77 per 1,000 pages, 10.1 seconds per PDF. Claude Haiku 5.5: 644, $1.00, 8.4 s. Gemini 3.8 Flash: 644, $8.04, 16.4 s. DeepSeek V4.1 Flash with mistral-ocr: 642, $3.09, 25.0 s. DeepSeek V4.1 Flash with cloudflare-ai: 434, $1.92, 21.3 s.

在這個測試集上,GPT-6 Luna 和 Claude Haiku 5.5 是成本最低、且每個單元格都正確的路線,連那張粗糙的掃描件也不例外,兩者的標價都是每百萬輸入 token 0.10 美元。因此它們很適合作為在你自己的 PDF 上做的第一輪測試。Gemini 3.8 Flash 的準確率同樣高,但在相同檔案上每頁成本要貴八到十倍。它的標價是每百萬輸入 token 1.50 美元,2026 年 10 月 21 日起打折至 0.75 美元。

OCR 路線的成本比 DeepSeek 的低 token 價格所暗示的要高,因為每 1,000 頁 2 美元的 OCR 費用會加到每次請求上,這一點在 usage.cost 中可以看到。它的兩處錯誤是 Enterprise 和 Hardware resale 上的腳註標記,儘管 schema 要求刪除這些標記,它還是保留了。免費解析器把三份數字版 PDF 全部處理正確,但兩份掃描件完全錯誤。

成本一列是按每條路線六頁推算的。可以用它來比較各條路線,但在選定之前,請先用一個黃金評測集在你自己的 PDF 樣本上測量準確率、時間和成本,因為頁面越密整合本越高,其他版式也可能表現不同。

什麼時候一個 PDF 庫就夠了?

如果你的 PDF 全是數字版,且每張表只有一個表頭行,那麼像 pdfplumber 這樣的免費庫就能找到表格。我們在同樣的檔案上運行了它。它找到了三份數字版 PDF 中的每一張表,並把每個單元格作為字串返回,例如 ‘6,067.00’ 或 ‘(3,878)’。季度報告的兩級表頭返回成了兩行,合併單元格里是 None;發貨日誌返回成了兩張獨立的表,每頁一張。它在兩份掃描件裡什麼都沒找到,因為掃描件沒有可讀取的文本層。

所以,當你的表格簡單、PDF 是數字版時,一個庫就夠了。一旦你要為合併表頭、分頁和數字格式編寫清理程式碼,第 2 步的 schema 維護起來反而更省事。

TypeScript 中的同一請求

請求體在任何語言裡都一樣。把它儲存為 extract.mjs,然後在 Node.js 18 或更高版本上用 node extract.mjs invoice.pdf 執行。

import { readFileSync } from "node:fs";
import { basename } from "node:path";

const path = process.argv[2];
const fileData = `data:application/pdf;base64,${readFileSync(path).toString("base64")}`;

const money = { type: "number", description: "USD, no currency symbol or thousands separator" };
const schema = {
  type: "object",
  properties: { rows: { type: "array", items: {
    type: "object",
    properties: { sku: { type: "string" }, description: { type: "string" },
                  qty: { type: "integer" }, unit_price: money, amount: money },
    required: ["sku", "description", "qty", "unit_price", "amount"],
    additionalProperties: false } } },
  required: ["rows"],
  additionalProperties: false,
};

const res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
             "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "openai/gpt-6-luna",
    messages: [{ role: "user", content: [
      { type: "text", text: "Extract every row of the table in this PDF. Include rows from every page. Return only rows that are in the document." },
      { type: "file", file: { filename: basename(path), file_data: fileData } },
    ] }],
    response_format: { type: "json_schema", json_schema: { name: "table", strict: true, schema } },
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
const data = await res.json();
const choice = data.choices[0];
if (choice.finish_reason !== "stop") throw new Error(`Unexpected finish_reason: ${choice.finish_reason}`);
const { rows } = JSON.parse(choice.message.content);
if (rows.length === 0) throw new Error("No rows came back.");
console.log(rows.length + " rows, finish_reason=" + choice.finish_reason + ", $" + data.usage.cost);
10 rows, finish_reason=stop, $0.00020275

指令碼會檢查 HTTP 狀態,然後執行與 Python 版本相同的兩項檢查。除非 finish_reason 為 “stop” 且 rows 至少有一行,否則它會中止。

結論

用 LLM 從 PDF 中提取表格只需一次請求,把 PDF 作為檔案部分,並配上一個描述單行的嚴格 schema。在我們的測試中,準確率來自模型直接讀取 PDF,而風險來自 PDF 所走的路線。對掃描件使用文本解析器、對長表格觸及 token 上限,這兩種情況返回的響應看起來都很正常。extract_table 中的兩項檢查能同時捕獲這兩種情況,所以無論你執行哪個版本的程式碼,都要保留它們。在確定一條路線之前,先用你自己的 PDF 樣本跑一遍,比較行、時間和 usage.cost。

常見問題

大語言模型能讀取掃描版 PDF 嗎?

可以,前提是模型直接讀取 PDF,或者你把它交給 mistral-ocr 解析器處理。三個能讀 PDF 的模型都正確識別了我們提供的兩份掃描件,DeepSeek V4.1 Flash 搭配 mistral-ocr 也一樣。而像 cloudflare-ai 這樣的文本解析器遇到掃描件會返回空結果,而且不報錯,因為掃描件沒有文本層。

在我們測試的六個頁面上,按 2026 年 10 月的價格計算,GPT-6 Luna 折算下來約為每 1,000 頁 0.77 美元,Claude Haiku 5.5 為 1.00 美元。經由 mistral-ocr 處理的模型還要額外支付每 1,000 頁 2 美元的 OCR 費用。請查詢當前價格,並根據自己最初的幾次請求來閱讀 usage.cost,因為表格密集的頁面成本更高。

模型會編造出 PDF 裡沒有的行嗎?

在我們對五份測試 PDF 做的 25 次提取中,沒有發現編造出來的行,但這並不能排除在其他文件上出現這種情況。更大的風險是漏行,原因可能是輸出在 token 上限處被截斷,或者解析器沒有找到文本。請把行數或小計與文件本身核對一下。

對於表頭簡單的數字版 PDF,pdfplumber 免費,而且在我們測試的數字版檔案中找到了每一張表格。它把每個單元格作為文本返回,會把多級表頭拆成單獨的行,但在我們的掃描件中什麼也沒找到。Camelot 和 Tabula 是另外兩個免費選項,不過本指南沒有測試它們。

後續步驟

  • PDF 輸入介紹瞭如何用 URL 而不是 base64 傳送 PDF、解析器引擎及其價格,以及檔案註解——它讓你可以把解析結果回傳,這樣就不必為同一份 PDF 重複支付解析費用。

  • 結構化輸出講解了嚴格的 JSON schema,以及如何只路由到支援它們的提供商。

  • 預設把模型、系統提示詞和提供商設定儲存在同一個名稱下。把提取指令寫進預設的系統提示詞,並在每個服務中呼叫 @preset/your-name,這樣它們就都使用同一套配置。每次請求時仍要在 response_format 中傳送 schema,因為預設文件並沒有把它列入預設所儲存的設定項。我們的預設指南詳細介紹了配置步驟。

  • 如果要處理積壓的 PDF,Batch API 會以非同步方式運行同樣的請求,通常 24 小時內完成。anthropic/claude-haiku-5.5:batch 和 openai/gpt-6-luna:batch 按標準每 token 價格的一半計費。批處理請求只接受以公開 URL 形式提供的 PDF,不接受 base64,所以要先託管檔案。檔案 URL 只在支援檔案輸入的模型上可用,因此第 3 步中 DeepSeek 搭配 mistral-ocr 的方案在批處理中不可用;在 OpenAI 模型上,檔案 URL 只能通過 Responses API 使用。本指南沒有對批處理執行進行測量。

  • 如果你在 LangChain 裡構建這套流程,ChatOpenRouter 可以透傳 PDF 輸入,並支援配合 with_structured_output 使用嚴格的 JSON schema。

  • 如果你的源文件是圖片而不是 PDF,如何向大語言模型傳送圖片介紹了圖片內容部分。

來源:OpenRouter:Announcements · openrouter.ai

來源: aihot (aihot.news)
開啟原文

讀者討論

理性交流 · 即時討論