Python API 参考

速览

NextPDF Python 软件开发工具包（SDK）提供两个客户端、二者共享的同一个 ast 方法命名空间、一组为每个响应标注类型的 Pydantic 模型、一个 nextpdf 命令行界面（CLI），以及一个含六个类的异常层次结构。本页提供上述符号的参考说明。

从顶层包导入公开接口：

from nextpdf import (
    AsyncNextPDF,
    NextPDF,
    AstBuildTimeoutError,
    AstNoStructTreeError,
    NextPDFAPIError,
    NextPDFError,
    NextPDFLicenseError,
    QuotaExceededError,
)

每个提取方法都以原始 PDF 字节（bytes）作为第一个位置参数，并返回带类型标注的 Pydantic 模型。后续参数均为仅限关键字的选项。同步的 NextPDF.ast.* 方法与异步的 AsyncNextPDF.ast.* 方法签名完全相同。异步方法是协程，调用时需要使用 await。

客户端

同步的 NextPDF 客户端封装了异步客户端，并将每个协程运行到完成。异步的 AsyncNextPDF 客户端同时也是一个异步上下文管理器。建议以上下文管理器形式使用它，以便底层传输能够确定性地关闭。

构造函数

符号	参数	默认行为	返回	抛出异常或失败条件	说明
NextPDF(*, base_url, api_key, api_version='v1')	仅限关键字的基础 URL、API 密钥、可选的 API 版本。	构造一个使用远程后端的同步客户端。	NextPDF	ValueError：当 base_url 或 api_key 为空时。	方法会以同步方式执行异步工作；在 notebook 和正在运行的事件循环中调用均安全。
AsyncNextPDF(*, base_url='', api_key='', api_version='v1', backend=None)	仅限关键字的基础 URL、API 密钥、可选的 API 版本、可选的注入后端。	未注入后端时，构造一个使用远程后端的异步客户端。	AsyncNextPDF	ValueError：当 base_url 或 api_key 为空且未提供 backend 时。	传入 backend= 可在测试中注入自定义或本地后端。
AsyncNextPDF.__aenter__()	无。	进入异步上下文并返回客户端。	AsyncNextPDF	预期不会抛出。	使用 async with AsyncNextPDF(...) as client:。
AsyncNextPDF.__aexit__(*_)	被忽略的异常参数。	在上下文退出时调用 close()。	None	预期不会抛出。	即使上下文主体抛出异常，也会释放传输资源。
AsyncNextPDF.close()	无。	关闭自身拥有的远程后端并释放连接池。	None	预期不会抛出。	幂等；注入的后端不会被关闭。

请勿将 API 密钥放入源代码。请从环境（NEXTPDF_BASE_URL、NEXTPDF_API_KEY）或密钥管理器读取 base_url 和 api_key。

import os

from nextpdf import AsyncNextPDF


async def extract(pdf_bytes: bytes) -> int:
    """Return the page count of a PDF using the async client as a context manager."""
    base_url = os.environ["NEXTPDF_BASE_URL"]
    api_key = os.environ["NEXTPDF_API_KEY"]

    async with AsyncNextPDF(base_url=base_url, api_key=api_key) as client:
        document = await client.ast.get_document_ast(pdf_bytes)
        return document.page_count

同步 AST 方法 — NextPDF.ast.*

符号	参数	默认行为	返回	抛出异常或失败条件	说明
NextPDF.ast.get_document_ast()	pdf_data: bytes；关键字 page_range_start、page_range_end、token_budget。	为所有页面构建完整的语义 AST。	AstDocument	AstNoStructTreeError、AstBuildTimeoutError、NextPDFLicenseError、QuotaExceededError。	构建超时时，请缩小页面范围。
NextPDF.ast.extract_cited_text()	pdf_data: bytes；关键字 page_index、headings_only。	提取所有带引用锚点的文本块。	list[CitedTextBlock]	NextPDFAPIError、QuotaExceededError。	设置 headings_only=True 可仅检索标题节点。
NextPDF.ast.extract_cited_tables()	pdf_data: bytes；关键字 page_range（dict，包含 start 和 end）。	提取所有带单元格级引用锚点的表格。	ExtractCitedTablesResponse	NextPDFAPIError、QuotaExceededError。	省略 page_range 可扫描整个文档。
NextPDF.ast.get_ast_node()	pdf_data: bytes、node_id: str。	按标识符检索单个节点。	GetAstNodeResponse	NextPDFError：当未找到该节点时。	node_id 的格式为 ast:{hash6}:{pageIdx}:{seq}。
NextPDF.ast.search_ast_nodes()	pdf_data: bytes；关键字 node_type、page_index、text_query、max_results=100。	返回与筛选条件匹配的浅层节点。	SearchAstNodesResponse	NextPDFAPIError。	text_query 执行不区分大小写的子串匹配。
NextPDF.ast.get_ast_diff()	original_pdf_data: bytes、modified_pdf_data: bytes。	按结构比较两个文档。	GetAstDiffResponse	NextPDFAPIError、QuotaExceededError。	报告新增、移除和变更的节点。

异步 AST 方法 — AsyncNextPDF.ast.*

每个异步方法都是协程，其参数、默认值、返回类型和失败模式与上文对应的同步方法相同。在 asyncio 运行时中调用时需要使用 await。

符号	参数	默认行为	返回	抛出异常或失败条件	说明
AsyncNextPDF.ast.get_document_ast()	pdf_data: bytes；关键字 page_range_start、page_range_end、token_budget。	为所有页面构建完整的语义 AST。	AstDocument	AstNoStructTreeError、AstBuildTimeoutError、NextPDFLicenseError、QuotaExceededError。	调用时需要 await。
AsyncNextPDF.ast.extract_cited_text()	pdf_data: bytes；关键字 page_index、headings_only。	提取所有带引用锚点的文本块。	list[CitedTextBlock]	NextPDFAPIError、QuotaExceededError。	调用时需要 await。
AsyncNextPDF.ast.extract_cited_tables()	pdf_data: bytes；关键字 page_range。	提取所有带单元格级引用锚点的表格。	ExtractCitedTablesResponse	NextPDFAPIError、QuotaExceededError。	调用时需要 await。
AsyncNextPDF.ast.get_ast_node()	pdf_data: bytes、node_id: str。	按标识符检索单个节点。	GetAstNodeResponse	NextPDFError：当未找到该节点时。	调用时需要 await。
AsyncNextPDF.ast.search_ast_nodes()	pdf_data: bytes；关键字 node_type、page_index、text_query、max_results=100。	返回与筛选条件匹配的浅层节点。	SearchAstNodesResponse	NextPDFAPIError。	调用时需要 await。
AsyncNextPDF.ast.get_ast_diff()	original_pdf_data: bytes、modified_pdf_data: bytes。	按结构比较两个文档。	GetAstDiffResponse	NextPDFAPIError、QuotaExceededError。	调用时需要 await。

将异步客户端用作上下文管理器，并发执行两次提取：

import asyncio

from nextpdf import AsyncNextPDF


async def extract_pair(first: bytes, second: bytes) -> None:
    """Extract two PDFs concurrently with one shared async client."""
    async with AsyncNextPDF(base_url="https://connect.example.com", api_key="set-from-secret") as client:
        text_blocks, tables = await asyncio.gather(
            client.ast.extract_cited_text(first),
            client.ast.extract_cited_tables(second),
        )
        print(f"text blocks: {len(text_blocks)}; tables: {tables.table_count}")

模型

每个响应都是一个 Pydantic 模型。可以从 nextpdf 或 nextpdf.models.ast 导入模型类。

符号	种类	关键字段	说明
AstDocument	文档根	schema_version、source_hash、page_count、root: AstNode、estimated_tokens（属性）。	由 get_document_ast() 返回。可接受 schemaVersion、sourceHash、pageCount 等别名。
AstNode	树节点	id、type: NodeType、page_index、bbox、text_content、attributes、children: list[AstNode]、pdf_object_number、mcid。	承载文档树的递归节点。
AstNodeMeta	响应元数据	etag、pages_processed。	冻结；附加于节点响应和搜索响应。
AstNodeShallow	搜索命中	id、type: NodeType、page_index、bbox、text_content、attributes、children_count。	冻结；无深层子节点。
BoundingBox	值对象	x、y、width、height (各为 0.0–1.0)。	归一化的页面坐标。
CitationAnchor	值对象	node_id、page_index、bbox: BoundingBox、confidence、content_hash。	每个块的来源记录。
CitedTextBlock	文本块	text、citation: CitationAnchor、node_type、chunk_index、depth。	extract_cited_text() 返回列表中的每一项。
CitedTableBlock	表格块	table_node_id、page_index、citation_anchor、row_count、col_count、rows。	冻结；单个表格。
CitedTableCell	表格单元格	row、col、row_span、col_span、text、bbox、confidence。	冻结；单个单元格。
NodeType	枚举	document、section、heading、paragraph、list、table、figure 等。	节点类型值的字符串枚举。
GetAstNodeResponse	响应	node: AstNode、meta: AstNodeMeta。	由 get_ast_node() 返回。
SearchAstNodesResponse	响应	nodes: list[AstNodeShallow]、total_matches、truncated、meta。	由 search_ast_nodes() 返回。
ExtractCitedTablesResponse	响应	tables: list[CitedTableBlock]、table_count、pages_processed。	由 extract_cited_tables() 返回。
AstDiffEntry	差异项	type（added/removed/changed）、node_id、node_type、page_index、text_preview。	差异中的一条变更。
AstDiffSummary	差异汇总	added_node_count、removed_node_count、changed_node_count。	汇总计数。
GetAstDiffResponse	响应	original_page_count、modified_page_count、summary: AstDiffSummary、diff: list[AstDiffEntry]、pages_processed。	由 get_ast_diff() 返回。

从已提取的文本块中读取引用锚点：

from nextpdf import CitedTextBlock


def describe(block: CitedTextBlock) -> str:
    """Render a text block with its page index and confidence."""
    anchor = block.citation
    return f"[page {anchor.page_index}, confidence {anchor.confidence:.2f}] {block.text[:80]}"

CLI 命令

在终端中使用 nextpdf 命令运行提取。传入 --base-url 和 --api-key，或在环境中设置 NEXTPDF_BASE_URL 和 NEXTPDF_API_KEY。除 version 外，每个命令都需要连接设置。当 PDF_PATH 为 - 时，从标准输入读取 PDF 字节。

符号	参数	默认行为	返回	抛出异常或失败条件	说明
nextpdf extract text	PDF_PATH；--format {json,markdown,plain}、--page、--headings-only。	以 JSON 形式输出引用文本块。	写入标准输出或 --output 文件。	遇到任何 NextPDFError 时退出码为 1。	--page 选择页面索引（从 0 开始计数）。
nextpdf extract tables	PDF_PATH；--format {json,csv}、--page-start、--page-end。	以 JSON 形式输出表格。	写入标准输出或 --output 文件。	遇到任何 NextPDFError 时退出码为 1。	--format csv 为每个表格写入一个 CSV 块。
nextpdf ast	PDF_PATH；--page-start、--page-end、--token-budget。	以 JSON 形式输出完整的语义 AST。	写入标准输出或 --output 文件。	遇到任何 NextPDFError 时退出码为 1。	使用 --token-budget 可限定响应大小。
nextpdf info	PDF_PATH。	输出文档元数据：页数、架构版本、源哈希、估算 token 数、根摘要。	将 JSON 写入标准输出或 --output 文件。	遇到任何 NextPDFError 时退出码为 1。	轻量级检查命令。
nextpdf version	无。	打印已安装的 SDK 版本。	写入标准输出。	预期不会抛出。	不联系服务器；无需凭据。
python -m nextpdf.mcp	无（读取 NEXTPDF_BASE_URL、NEXTPDF_API_KEY）。	通过标准 input/output 运行 Model Context Protocol 服务器。	长时间运行的服务器进程。	RuntimeError：当环境变量未设置时。	需要 nextpdf[mcp] 附加组件。

从某个页面范围将表格提取为逗号分隔值（CSV）：

nextpdf extract tables invoice.pdf --format csv --page-start 0 --page-end 2 --output tables.csv

异常

异常层次结构位于 nextpdf.models.errors，并从 nextpdf 重新导出。请先捕获代码能够处理的最具体类，再回退到基类。服务器以与 RFC 9110 一致的 HTTP 状态语义表示失败。每个异常都携带其原始的 status_code，并在适用时携带 error_code。

符号	基类	status_code	何时抛出	说明
NextPDFError	Exception	可选	所有 SDK 错误的基类。	携带可选的 status_code。作为最后的回退捕获。
NextPDFAPIError	NextPDFError	必需	Connect 端点返回了 HTTP 错误。	附带 error_code。
NextPDFLicenseError	NextPDFAPIError	402	服务器要求该功能使用更高层级的许可证。	error_code 为 license/tier-required。
QuotaExceededError	NextPDFAPIError	429	超出速率限制或配额。	携带 retry_after；重试前请遵守该值。
AstNoStructTreeError	NextPDFAPIError	422	该 PDF 未加标签且未启用启发式回退。	请启用启发式模式或提供带标签的 PDF。
AstBuildTimeoutError	NextPDFAPIError	504	服务器上的 AST 构建超时。	请缩小页面范围后重试。

from nextpdf import (
    NextPDF,
    AstBuildTimeoutError,
    NextPDFAPIError,
    NextPDFError,
    QuotaExceededError,
)


def extract_text(client: NextPDF, pdf_bytes: bytes) -> int:
    """Extract cited text, handling the most specific failures first."""
    try:
        blocks = client.ast.extract_cited_text(pdf_bytes)
    except QuotaExceededError as error:
        raise RuntimeError(f"Quota exceeded (retry after {error.retry_after}s)") from error
    except AstBuildTimeoutError as error:
        raise RuntimeError("AST build timed out; reduce the page range") from error
    except NextPDFAPIError as error:
        raise RuntimeError(f"API error {error.status_code}: {error}") from error
    except NextPDFError as error:
        raise RuntimeError(f"SDK error: {error}") from error
    return len(blocks)

开发说明

• 同步的 NextPDF 客户端将每个调用委派给 AsyncNextPDF。可以安全地从 notebook 或已运行事件循环的线程中调用，因为在检测到正在运行的循环时，协程会被派发到工作线程。
• 建议以异步上下文管理器形式使用 async with AsyncNextPDF(...) as client:，以便连接池能够确定性地关闭。当你直接构造 AsyncNextPDF 时，请自行调用 close()。
• 持有者令牌绝不会被记录，也不会写入错误消息；传输层安全（TLS）验证默认启用。请勿将凭据嵌入源代码；应从环境或密钥管理器读取。
• 所有模型都是 Pydantic v2 类；部分响应模型是冻结（不可变）的。请将提取出的块视为只读值。
• CLI 在遇到任何 NextPDFError 时以状态码 1 退出，并将消息打印到标准错误。请将该退出码接入流水线。

另请参阅

• Python SDK 开发者指南 — 架构、异步批处理和失败处理。
• Python CLI — 终端提取与大文件的流式处理。
• Python MCP 服务器 — 向 AI 智能体公开提取工具。
• RFC 9110（HTTP 语义）和 RFC 9457（HTTP API 的问题详情）描述了 Connect 端点返回的状态语义和机器可读的错误主体。权威文本请参阅 IETF RFC 索引。