跳到正文
RadarAI· OpenRouter：Announcements（RSS）·· 4 小时前AI 评分71

OpenRouter 教程：用 LLM 从 PDF 中抽取表格

AI 导读

OpenRouter 发布教程，讲解如何把 PDF 作为文件连同严格 JSON schema 发给能读文件的模型，让表格以带类型的行返回。作者用五份 PDF（含两份扫描件）实测多条抽取路线，能直接读 PDF 的模型答对全部 644 个单元格，失败主要来自解析器路径和输出 token 截断，教程给出空结果与 finish_reason 为 length 两项检查及各路线成本对比。

正文

OpenRouter：Announcements·2026-10-29 08:00· 48 分钟前精选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}

在 Hardware resale 这一行中，(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），在模型 token 费用之外，每 1,000 页收费 $2。
  • 不能读取 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。

常见问题

LLM 能读取扫描版 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 而非 base64 接收 PDF，因此需要先托管文件。文件 URL 仅在列出文件输入的模型上可用，因此第 3 步中 DeepSeek 配合 mistral-ocr 的方案在批处理中不可用，而在 OpenAI 模型上只能通过 Responses API 使用。我们在本指南中没有测量批处理运行情况。

  • 如果你在 LangChain 中构建此功能，ChatOpenRouter 会透传 PDF 输入，并支持使用 with_structured_output 的严格 JSON schema。

  • 如果你的源文档是图片而非 PDF，如何向 LLM 发送图片 介绍了图片内容部分。

来源：OpenRouter：Announcements · openrouter.ai

来源：RadarAI · aihot.news

OpenRouter部署工程教程实践#教程/实践#RAG#部署/工程