Tài liệu tham khảo API Python

Tổng quan nhanh

NextPDF Python SDK cung cấp hai client, một không gian tên phương thức Abstract Syntax Tree (AST) dùng chung tên là ast, các model Pydantic cho mọi phản hồi, giao diện dòng lệnh (CLI) nextpdf, và hệ thống phân cấp ngoại lệ gồm sáu lớp. Hãy dùng trang này làm tài liệu tham khảo cho các ký hiệu giao diện lập trình ứng dụng (API) công khai khi làm việc với tài liệu Portable Document Format (PDF).

Nhập các ký hiệu công khai từ gói cấp cao nhất:

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

Mọi phương thức trích xuất đều nhận byte PDF thô (bytes) làm đối số vị trí đầu tiên và trả về một model Pydantic có kiểu. Truyền các tùy chọn dưới dạng đối số chỉ-từ-khóa. Các phương thức đồng bộ NextPDF.ast.* và bất đồng bộ AsyncNextPDF.ast.* có chữ ký giống hệt nhau. Phương thức bất đồng bộ là coroutine; hãy gọi chúng bằng await.

Client

Client đồng bộ NextPDF bao bọc client bất đồng bộ và chạy từng coroutine cho đến khi hoàn tất. AsyncNextPDF vừa là client bất đồng bộ vừa là async context manager. Hãy ưu tiên dạng context manager để lớp transport bên dưới được đóng một cách xác định.

Hàm khởi tạo

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`NextPDF(*, base_url, api_key, api_version='v1')`	Base URL, API key chỉ-từ-khóa và phiên bản API tùy chọn.	Tạo client đồng bộ chạy trên backend từ xa.	`NextPDF`	`ValueError` khi `base_url` hoặc `api_key` rỗng.	Chạy công việc bất đồng bộ theo cách đồng bộ; an toàn bên trong notebook và event loop đang chạy.
`AsyncNextPDF(*, base_url='', api_key='', api_version='v1', backend=None)`	Base URL, API key chỉ-từ-khóa, phiên bản API tùy chọn và backend tùy chọn được tiêm vào.	Tạo client bất đồng bộ chạy trên backend từ xa khi không có backend nào được tiêm vào.	`AsyncNextPDF`	`ValueError` khi `base_url` hoặc `api_key` rỗng và không có `backend` nào được cung cấp.	Truyền `backend=` để tiêm backend tùy chỉnh hoặc backend cục bộ trong kiểm thử.
`AsyncNextPDF.__aenter__()`	Không có.	Vào ngữ cảnh bất đồng bộ và trả về client.	`AsyncNextPDF`	Không dự kiến có lỗi.	Hãy dùng `async with AsyncNextPDF(...) as client:`.
`AsyncNextPDF.__aexit__(*_)`	Các đối số ngoại lệ được thu gọn.	Gọi `close()` khi thoát khỏi ngữ cảnh.	`None`	Không dự kiến có lỗi.	Giải phóng lớp transport ngay cả khi thân lệnh ném ra ngoại lệ.
`AsyncNextPDF.close()`	Không có.	Đóng backend từ xa do client sở hữu và giải phóng connection pool.	`None`	Không dự kiến có lỗi.	Gọi nhiều lần vẫn an toàn; các backend được tiêm vào không bị đóng.

Không lưu API key trong mã nguồn. Đọc base_url và api_key từ môi trường (NEXTPDF_BASE_URL, NEXTPDF_API_KEY) hoặc một trình quản lý bí mật.

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

Phương thức AST đồng bộ — `NextPDF.ast.*`

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`NextPDF.ast.get_document_ast()`	`pdf_data: bytes`; từ khóa `page_range_start`, `page_range_end`, `token_budget`.	Xây dựng Semantic AST đầy đủ cho mọi trang.	`AstDocument`	`AstNoStructTreeError`, `AstBuildTimeoutError`, `NextPDFLicenseError`, `QuotaExceededError`.	Hãy thu hẹp khoảng trang khi quá trình xây dựng hết thời gian chờ.
`NextPDF.ast.extract_cited_text()`	`pdf_data: bytes`; từ khóa `page_index`, `headings_only`.	Trích xuất tất cả các khối văn bản kèm neo trích dẫn.	`list[CitedTextBlock]`	`NextPDFAPIError`, `QuotaExceededError`.	Đặt `headings_only=True` để chỉ lấy các nút tiêu đề.
`NextPDF.ast.extract_cited_tables()`	`pdf_data: bytes`; từ khóa `page_range` (`dict` với `start` và `end`).	Trích xuất tất cả các bảng kèm neo trích dẫn ở cấp độ ô.	`ExtractCitedTablesResponse`	`NextPDFAPIError`, `QuotaExceededError`.	Bỏ qua `page_range` để quét toàn bộ tài liệu.
`NextPDF.ast.get_ast_node()`	`pdf_data: bytes`, `node_id: str`.	Lấy về một nút theo mã định danh của nó.	`GetAstNodeResponse`	`NextPDFError` khi không tìm thấy nút.	`node_id` có định dạng `ast:{hash6}:{pageIdx}:{seq}`.
`NextPDF.ast.search_ast_nodes()`	`pdf_data: bytes`; từ khóa `node_type`, `page_index`, `text_query`, `max_results=100`.	Trả về các nút nông khớp với bộ lọc.	`SearchAstNodesResponse`	`NextPDFAPIError`.	`text_query` là phép khớp chuỗi con không phân biệt chữ hoa chữ thường.
`NextPDF.ast.get_ast_diff()`	`original_pdf_data: bytes`, `modified_pdf_data: bytes`.	So sánh hai tài liệu theo cấu trúc.	`GetAstDiffResponse`	`NextPDFAPIError`, `QuotaExceededError`.	Báo cáo các nút được thêm, bị xóa và thay đổi.

Phương thức AST bất đồng bộ — `AsyncNextPDF.ast.*`

Mỗi phương thức bất đồng bộ là một coroutine, có cùng tham số, giá trị mặc định, kiểu trả về và chế độ thất bại như phiên bản đồng bộ tương ứng. Hãy gọi phương thức đó bằng await bên trong một runtime asyncio.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`AsyncNextPDF.ast.get_document_ast()`	`pdf_data: bytes`; từ khóa `page_range_start`, `page_range_end`, `token_budget`.	Xây dựng Semantic AST đầy đủ cho mọi trang.	`AstDocument`	`AstNoStructTreeError`, `AstBuildTimeoutError`, `NextPDFLicenseError`, `QuotaExceededError`.	`await` kết quả.
`AsyncNextPDF.ast.extract_cited_text()`	`pdf_data: bytes`; từ khóa `page_index`, `headings_only`.	Trích xuất tất cả các khối văn bản kèm neo trích dẫn.	`list[CitedTextBlock]`	`NextPDFAPIError`, `QuotaExceededError`.	`await` kết quả.
`AsyncNextPDF.ast.extract_cited_tables()`	`pdf_data: bytes`; từ khóa `page_range`.	Trích xuất tất cả các bảng kèm neo trích dẫn ở cấp độ ô.	`ExtractCitedTablesResponse`	`NextPDFAPIError`, `QuotaExceededError`.	`await` kết quả.
`AsyncNextPDF.ast.get_ast_node()`	`pdf_data: bytes`, `node_id: str`.	Lấy về một nút theo mã định danh của nó.	`GetAstNodeResponse`	`NextPDFError` khi không tìm thấy nút.	`await` kết quả.
`AsyncNextPDF.ast.search_ast_nodes()`	`pdf_data: bytes`; từ khóa `node_type`, `page_index`, `text_query`, `max_results=100`.	Trả về các nút nông khớp với bộ lọc.	`SearchAstNodesResponse`	`NextPDFAPIError`.	`await` kết quả.
`AsyncNextPDF.ast.get_ast_diff()`	`original_pdf_data: bytes`, `modified_pdf_data: bytes`.	So sánh hai tài liệu theo cấu trúc.	`GetAstDiffResponse`	`NextPDFAPIError`, `QuotaExceededError`.	`await` kết quả.

Dùng client bất đồng bộ làm context manager để chạy đồng thời hai lần trích xuất:

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}")

Model

Mọi phản hồi đều là model Pydantic. Nhập các lớp model từ nextpdf hoặc nextpdf.models.ast.

Ký hiệu	Loại	Trường chính	Ghi chú
`AstDocument`	Gốc tài liệu	`schema_version`, `source_hash`, `page_count`, `root: AstNode`, `estimated_tokens` (property).	Được trả về bởi `get_document_ast()`. Chấp nhận các bí danh `schemaVersion`, `sourceHash` và `pageCount`.
`AstNode`	Nút cây	`id`, `type: NodeType`, `page_index`, `bbox`, `text_content`, `attributes`, `children: list[AstNode]`, `pdf_object_number`, `mcid`.	Nút đệ quy mang theo cây tài liệu.
`AstNodeMeta`	Siêu dữ liệu phản hồi	`etag`, `pages_processed`.	Bất biến; được gắn vào các phản hồi nút và tìm kiếm.
`AstNodeShallow`	Kết quả tìm kiếm	`id`, `type: NodeType`, `page_index`, `bbox`, `text_content`, `attributes`, `children_count`.	Bất biến; không chứa nút con ở tầng sâu.
`BoundingBox`	Đối tượng giá trị	`x`, `y`, `width`, `height` (mỗi giá trị từ `0.0`–`1.0`).	Tọa độ được chuẩn hóa trong phạm vi một trang.
`CitationAnchor`	Đối tượng giá trị	`node_id`, `page_index`, `bbox: BoundingBox`, `confidence`, `content_hash`.	Bản ghi nguồn gốc cho mỗi khối.
`CitedTextBlock`	Khối văn bản	`text`, `citation: CitationAnchor`, `node_type`, `chunk_index`, `depth`.	Mỗi mục trong danh sách `extract_cited_text()`.
`CitedTableBlock`	Khối bảng	`table_node_id`, `page_index`, `citation_anchor`, `row_count`, `col_count`, `rows`.	Bất biến; một bảng.
`CitedTableCell`	Ô bảng	`row`, `col`, `row_span`, `col_span`, `text`, `bbox`, `confidence`.	Bất biến; một ô.
`NodeType`	Enum	`document`, `section`, `heading`, `paragraph`, `list`, `table`, `figure`, và các loại khác.	Enum chuỗi cho các giá trị loại nút.
`GetAstNodeResponse`	Phản hồi	`node: AstNode`, `meta: AstNodeMeta`.	Được trả về bởi `get_ast_node()`.
`SearchAstNodesResponse`	Phản hồi	`nodes: list[AstNodeShallow]`, `total_matches`, `truncated`, `meta`.	Được trả về bởi `search_ast_nodes()`.
`ExtractCitedTablesResponse`	Phản hồi	`tables: list[CitedTableBlock]`, `table_count`, `pages_processed`.	Được trả về bởi `extract_cited_tables()`.
`AstDiffEntry`	Mục khác biệt	`type` (`added`/`removed`/`changed`), `node_id`, `node_type`, `page_index`, `text_preview`.	Một thay đổi trong một diff.
`AstDiffSummary`	Tổng số khác biệt	`added_node_count`, `removed_node_count`, `changed_node_count`.	Số lượng tổng hợp.
`GetAstDiffResponse`	Phản hồi	`original_page_count`, `modified_page_count`, `summary: AstDiffSummary`, `diff: list[AstDiffEntry]`, `pages_processed`.	Được trả về bởi `get_ast_diff()`.

Đọc neo trích dẫn từ một khối văn bản đã trích xuất:

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]}"

Lệnh CLI

Lệnh nextpdf chạy tác vụ trích xuất từ terminal. Truyền --base-url và --api-key, hoặc đặt NEXTPDF_BASE_URL và NEXTPDF_API_KEY trong môi trường. Mọi lệnh ngoại trừ version đều cần kết nối đã được thiết lập. PDF_PATH với giá trị - sẽ đọc byte PDF từ đầu vào chuẩn.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`nextpdf extract text`	`PDF_PATH`; `--format {json,markdown,plain}`, `--page`, `--headings-only`.	Xuất các khối văn bản có trích dẫn dưới dạng JavaScript Object Notation (JSON).	Ghi vào đầu ra chuẩn hoặc tệp `--output`.	Mã thoát 1 cho bất kỳ `NextPDFError` nào.	`--page` chọn chỉ mục trang theo cơ sở 0.
`nextpdf extract tables`	`PDF_PATH`; `--format {json,csv}`, `--page-start`, `--page-end`.	Xuất các bảng dưới dạng JSON.	Ghi vào đầu ra chuẩn hoặc tệp `--output`.	Mã thoát 1 cho bất kỳ `NextPDFError` nào.	`--format csv` ghi một khối giá trị phân tách bằng dấu phẩy (CSV) cho mỗi bảng.
`nextpdf ast`	`PDF_PATH`; `--page-start`, `--page-end`, `--token-budget`.	Xuất Semantic AST đầy đủ dưới dạng JSON.	Ghi vào đầu ra chuẩn hoặc tệp `--output`.	Mã thoát 1 cho bất kỳ `NextPDFError` nào.	Dùng `--token-budget` để giới hạn kích thước phản hồi.
`nextpdf info`	`PDF_PATH`.	Xuất siêu dữ liệu tài liệu: số trang, phiên bản schema, source hash, số token ước tính và tóm tắt nút gốc.	Ghi JSON vào đầu ra chuẩn hoặc tệp `--output`.	Mã thoát 1 cho bất kỳ `NextPDFError` nào.	Lệnh kiểm tra nhẹ.
`nextpdf version`	Không có.	In phiên bản SDK đã cài đặt.	Ghi vào đầu ra chuẩn.	Không dự kiến có lỗi.	Không liên hệ với máy chủ; không cần thông tin xác thực.
`python -m nextpdf.mcp`	không có (đọc `NEXTPDF_BASE_URL`, `NEXTPDF_API_KEY`).	Chạy máy chủ Model Context Protocol qua input/output chuẩn.	Tiến trình máy chủ chạy dài hạn.	`RuntimeError` khi các biến môi trường chưa được đặt.	Cần extra `nextpdf[mcp]`.

Trích xuất các bảng dưới dạng giá trị phân tách bằng dấu phẩy (CSV) từ một khoảng trang:

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

Ngoại lệ

Hệ thống phân cấp ngoại lệ nằm trong nextpdf.models.errors và được tái xuất từ nextpdf. Hãy bắt lớp cụ thể nhất mà mã của bạn có thể xử lý, sau đó mới bắt lớp cơ sở. Máy chủ báo cáo lỗi theo ngữ nghĩa trạng thái Hypertext Transfer Protocol (HTTP) của Request for Comments (RFC) 9110. Mỗi ngoại lệ đều mang theo status_code gốc và, nếu có, một error_code.

Ký hiệu	Lớp cơ sở	`status_code`	Khi nào được ném ra	Ghi chú
`NextPDFError`	`Exception`	tùy chọn	Lớp cơ sở cho mọi lỗi SDK.	Mang theo một `status_code` tùy chọn. Hãy bắt lớp này cuối cùng làm phương án dự phòng.
`NextPDFAPIError`	`NextPDFError`	bắt buộc	Endpoint Connect đã trả về một lỗi HTTP.	Bổ sung `error_code`.
`NextPDFLicenseError`	`NextPDFAPIError`	`402`	Máy chủ yêu cầu giấy phép ở bậc cao hơn cho tính năng này.	`error_code` là `license/tier-required`.
`QuotaExceededError`	`NextPDFAPIError`	`429`	Đã vượt quá giới hạn tốc độ hoặc hạn mức.	Mang theo `retry_after`; hãy tuân theo nó trước khi thử lại.
`AstNoStructTreeError`	`NextPDFAPIError`	`422`	PDF không được gắn thẻ, và phương án dự phòng theo phỏng đoán không được bật.	Hãy bật chế độ phỏng đoán hoặc cung cấp PDF có gắn thẻ.
`AstBuildTimeoutError`	`NextPDFAPIError`	`504`	Quá trình xây dựng AST đã hết thời gian chờ trên máy chủ.	Hãy thu hẹp khoảng trang rồi thử lại.

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)

Ghi chú phát triển

Client đồng bộ NextPDF ủy thác mọi lệnh gọi cho AsyncNextPDF. Bạn có thể gọi nó từ notebook hoặc thread đang chạy một event loop, vì nó điều phối coroutine sang worker thread khi phát hiện loop đang chạy.
Hãy ưu tiên dạng async context manager async with AsyncNextPDF(...) as client: để connection pool được đóng một cách xác định. Khi khởi tạo AsyncNextPDF trực tiếp, hãy tự gọi close().
Bearer token không bao giờ được ghi log hay đưa vào thông báo lỗi, và việc xác minh Transport Layer Security (TLS) được bật theo mặc định. Không nhúng thông tin xác thực vào mã nguồn; hãy đọc chúng từ môi trường hoặc trình quản lý bí mật.
Tất cả các model đều là lớp Pydantic v2; một số model phản hồi bị đóng băng (bất biến). Hãy coi các khối đã trích xuất là giá trị chỉ đọc.
CLI thoát với mã trạng thái 1 cho bất kỳ NextPDFError nào và in thông báo ra đầu lỗi chuẩn. Hãy nối mã thoát đó vào các pipeline.

Xem thêm

Hướng dẫn dành cho nhà phát triển Python SDK — kiến trúc, gộp lô bất đồng bộ và xử lý lỗi.
Python CLI — trích xuất từ terminal và truyền luồng cho các tệp lớn.
Máy chủ Python MCP — cung cấp các công cụ trích xuất cho các agent trí tuệ nhân tạo (AI).
RFC 9110 (HTTP Semantics) và RFC 9457 (Problem Details for HTTP APIs) mô tả ngữ nghĩa trạng thái và phần thân lỗi máy có thể đọc do endpoint Connect trả về. Hãy xem chỉ mục RFC của IETF để đọc văn bản chính thức.