Przewodnik dewelopera po zestawie SDK NextPDF dla języka Python

W skrócie

Zestaw SDK NextPDF dla języka Python to lekki, typowany klient punktu końcowego NextPDF Connect. Za walidację danych wejściowych w formacie Portable Document Format (PDF), obsługę poświadczeń i zasady współbieżności odpowiada aplikacja. Zestaw SDK odpowiada za konstruowanie żądania, transport i typowanie odpowiedzi. Zachowaj wyraźną granicę: bezpiecznie wczytaj plik PDF, wybierz klienta, wywołaj potrzebną metodę z przestrzeni nazw ast i obsłuż konkretny błąd.

Skorzystaj z tego przewodnika, gdy budujesz wokół zestawu SDK usługi ekstrakcji, zadania wsadowe asyncio, narzędzia dla agentów sztucznej inteligencji (AI) lub przepływy pracy w wierszu poleceń. Przewodnik zakłada, że znasz już omówienie i szybki start, korzystasz z języka Python 3.10 lub nowszego oraz masz punkt końcowy NextPDF Connect.

Granica architektury

Warstwa	Należy do	Odpowiedzialność	Czego tu nie umieszczać
Źródło danych wejściowych	Aplikacja	Autoryzuj wywołującego, zweryfikuj źródło PDF i wybierz zasady ekstrakcji.	Literałów adresu Uniform Resource Locator (URL) punktu końcowego ani poświadczeń.
Konstruowanie klienta	Aplikacja	Odczytaj base_url i api_key ze środowiska lub z menedżera sekretów.	Zakodowanych na stałe sekretów.
NextPDF / AsyncNextPDF	SDK	Zbuduj żądanie, wywołaj Connect i zwróć typowane modele Pydantic.	Logiki domenowej ani zasad przechowywania.
Przestrzeń nazw metody ast	SDK	Odwzoruj wywołanie metody na punkt końcowy Connect i przeanalizuj odpowiedź.	Zasad ponawiania ani wycofywania wykraczających poza skonfigurowane zachowanie.
Punkt końcowy NextPDF Connect	Wdrożenie	Uruchom ekstrakcję oraz wymuś uwierzytelnianie, limity i licencjonowanie.	Autoryzacji aplikacji.

Zestaw SDK nigdy nie wykonuje optycznego rozpoznawania znaków (OCR). Jeśli plik PDF jest zeskanowany lub zawiera tylko obrazy, uruchom OCR przed ekstrakcją. Traktuj ten krok jako zadanie aplikacji poza tą granicą.

Cykl życia w czasie wykonania

Etap	Zachowanie	Działanie dewelopera
Konstruowanie klienta	base_url i api_key są walidowane; pusta wartość któregokolwiek z nich powoduje zgłoszenie ValueError.	Odczytaj oba ze środowiska; nigdy nie umieszczaj ich bezpośrednio w kodzie.
Tworzenie backendu	Zdalny backend otwiera połączenie z puli do Connect.	Używaj tego samego klienta we wszystkich wywołaniach, zamiast konstruować go dla każdego żądania.
Wywołanie metody	Metoda z przestrzeni nazw ast serializuje żądanie, wysyła bajty pliku PDF i analizuje odpowiedź, tworząc model Pydantic.	Przekaż już zweryfikowane bytes.
Mapowanie błędów	Zestaw SDK mapuje niepomyślny status protokołu Hypertext Transfer Protocol (HTTP) na konkretną podklasę wyjątku.	Najpierw przechwyć najbardziej szczegółową klasę.
Zamknięcie	AsyncNextPDF.close() zwalnia pulę połączeń; asynchroniczny menedżer kontekstu wywołuje tę metodę za Ciebie.	Użyj async with lub wywołaj close() w bloku finally.

Zalecana struktura aplikacji

Ścieżka	Przeznaczenie
app/pdf/clients.py	Zbuduj skonfigurowanego klienta NextPDF lub AsyncNextPDF i zapisz go w pamięci podręcznej.
app/pdf/extraction.py	Warstwa aplikacji opakowująca wywołania z przestrzeni nazw ast.
app/pdf/validation.py	Walidacja źródła PDF, limity rozmiaru i kontrola zawartości.
tests/pdf/	Testy ekstrakcji, trybów awarii i asynchronicznego przetwarzania wsadowego.

Oddziel walidację PDF od ekstrakcji. Do warstwy ekstrakcji przekazuj wyłącznie autoryzowane bajty o sprawdzonym rozmiarze, a punkt końcowy traktuj jako kolejną warstwę obrony w głąb.

import os

from nextpdf import NextPDF


def build_client() -> NextPDF:
    """Construct a synchronous client from environment configuration.

    Raises:
        KeyError: When a required environment variable is missing.
    """
    base_url = os.environ["NEXTPDF_BASE_URL"]
    api_key = os.environ["NEXTPDF_API_KEY"]
    return NextPDF(base_url=base_url, api_key=api_key)

Wzorzec klienta synchronicznego

Używaj synchronicznego klienta NextPDF w skryptach, zadaniach wsadowych i notatnikach. Zweryfikuj dane wejściowe przed wywołaniem zestawu SDK i obsłuż konkretne błędy, które to wywołanie może zgłosić.

from pathlib import Path

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

MAX_PDF_BYTES = 100 * 1024 * 1024  # Reject documents above 100 MiB for the in-memory path.


def read_pdf(path: Path) -> bytes:
    """Read and validate a PDF from disk.

    Raises:
        ValueError: When the file is missing, empty, oversized, or not a PDF.
    """
    if not path.is_file():
        raise ValueError(f"Not a file: {path}")
    data = path.read_bytes()
    if not data:
        raise ValueError("PDF is empty")
    if len(data) > MAX_PDF_BYTES:
        raise ValueError("PDF exceeds the configured size limit; use the CLI streaming path")
    if not data.startswith(b"%PDF-"):
        raise ValueError("File does not look like a PDF")
    return data


def extract_text(client: NextPDF, path: Path) -> list[CitedTextBlock]:
    """Extract cited text blocks, handling the most specific failures first."""
    pdf_bytes = read_pdf(path)
    try:
        return 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 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

Pojedyncza pozycja wyniku ma następujący kształt:

block = blocks[0]
print(block.text)                  # the extracted text
print(block.citation.page_index)   # 0-based page index
print(block.citation.confidence)   # 0.0 - 1.0

Wzorzec asynchroniczny i przetwarzanie wsadowe

Używaj asynchronicznego klienta AsyncNextPDF w środowiskach asyncio, takich jak FastAPI. Skonstruuj jednego klienta jako asynchroniczny menedżer kontekstu i udostępniaj go współbieżnym wywołaniom; nie otwieraj klienta osobno dla każdego dokumentu. Ogranicz współbieżność za pomocą semafora, aby przestrzegać limitów punktu końcowego.

import asyncio
import os

from nextpdf import (
    AsyncNextPDF,
    ExtractCitedTablesResponse,
    NextPDFError,
    QuotaExceededError,
)


async def extract_tables_batch(
    pdfs: list[bytes],
    *,
    max_concurrency: int = 4,
) -> list[ExtractCitedTablesResponse | None]:
    """Extract tables from many PDFs concurrently with one shared client.

    Returns one response per input PDF, or None where extraction failed.
    """
    base_url = os.environ["NEXTPDF_BASE_URL"]
    api_key = os.environ["NEXTPDF_API_KEY"]
    semaphore = asyncio.Semaphore(max_concurrency)

    async with AsyncNextPDF(base_url=base_url, api_key=api_key) as client:

        async def one(pdf_bytes: bytes) -> ExtractCitedTablesResponse | None:
            async with semaphore:
                try:
                    return await client.ast.extract_cited_tables(pdf_bytes)
                except QuotaExceededError as error:
                    # Surface the backpressure signal; do not silently drop it.
                    raise RuntimeError(f"Quota exceeded; retry after {error.retry_after}s") from error
                except NextPDFError:
                    return None

        return await asyncio.gather(*(one(pdf) for pdf in pdfs))

Nigdy nie zostawiaj pustego except. Zareaguj na błąd, zamień go na zdefiniowany wynik albo zgłoś ponownie.

Punkty rozszerzeń

Punkt rozszerzenia	Zastosowanie	Ograniczenie
AsyncNextPDF(backend=...)	Wstrzykiwanie w testach niestandardowego lub lokalnego backendu.	Backend musi spełniać protokół Pdfbackend.
Argument api_version	Przypięcie wersji interfejsu application programming interface (API) Connect.	Domyślnie v1; zmieniaj tylko wtedy, gdy punkt końcowy obsługuje docelową wersję.
Konfiguracja środowiska	Przekaż NEXTPDF_BASE_URL i NEXTPDF_API_KEY do interfejsu wiersza poleceń (CLI) i serwera Model Context Protocol (MCP).	Traktuj klucz jako sekret o zasięgu ograniczonym do danego obciążenia.
Serwer MCP (python -m nextpdf.mcp)	Udostępnianie narzędzi ekstrakcji agentom obsługującym MCP.	Wymaga dodatku nextpdf[mcp] i kontrolowanego punktu końcowego.

Przepływ pracy programisty

1. Zainstaluj zestaw SDK za pomocą pip install nextpdf albo użyj pip install nextpdf[mcp] dla serwera agentowego.
2. Odczytaj NEXTPDF_BASE_URL i NEXTPDF_API_KEY ze środowiska, aby żaden sekret nie trafił do systemu kontroli wersji.
3. Dla każdego źródła PDF sprawdź istnienie, rozmiar i magiczne bajty %PDF- przed wywołaniem zestawu SDK.
4. Zbuduj jednego klienta na proces i używaj go ponownie; w przypadku asyncio utrzymuj go otwartego za pomocą async with.
5. Wywołuj najbardziej zawężoną metodę z przestrzeni nazw ast odpowiednią do zadania: extract_cited_text() dla tekstu, extract_cited_tables() dla tabel, a get_document_ast() tylko wtedy, gdy potrzebujesz pełnego drzewa.
6. Przechwyć najbardziej szczegółowy wyjątek, na który możesz zareagować, a następnie użyj NextPDFError jako rozwiązania awaryjnego.
7. W przypadku dokumentów większych niż 100 MiB użyj strumieniowej ścieżki CLI, zamiast materializować każdy blok w pamięci.
8. Uruchom mypy w trybie ścisłym i dodaj test trybu awarii dla każdego obsługiwanego wyjątku.

Obsługa błędów

Błąd	Wyjątek	Zalecana reakcja
Nieotagowany PDF, heurystyka wyłączona	AstNoStructTreeError (HTTP 422)	Włącz tryb heurystyczny w punkcie końcowym lub dostarcz otagowany PDF.
Przekroczenie limitu czasu kompilacji po stronie serwera	AstBuildTimeoutError (HTTP 504)	Zmniejsz zakres stron i ponów próbę.
Wymagany poziom licencji	NextPDFLicenseError (HTTP 402)	Uaktualnij licencję serwera lub użyj dozwolonej funkcji jako ścieżki awaryjnej.
Limit szybkości lub limit przydziału	QuotaExceededError (HTTP 429)	Poczekaj retry_after sekund, a następnie ponów próbę z mechanizmem wycofywania.
Inny błąd HTTP	NextPDFAPIError	Sprawdź status_code i error_code; zarejestruj zdarzenie i zwróć zdefiniowany błąd.
Dowolny błąd zestawu SDK	NextPDFError	Ostateczne rozwiązanie awaryjne; nigdy nie dopuść, aby wydostał się jako nieobsłużony wyjątek.

Punkt końcowy zgłasza błędy z semantyką statusu HTTP zgodną z Request for Comments (RFC) 9110 oraz treściami błędów możliwymi do odczytu maszynowego zgodnymi z RFC 9457. Każdy wyjątek zachowuje pierwotny status_code. Mapuj te błędy na własne odpowiedzi błędów, zamiast ujawniać wywołującym szczegóły transportu.

Bezpieczne ustawienia domyślne

Zagadnienie	Wartość domyślna	Kiedy zmienić
Wersja API	v1.	Zmieniaj tylko wtedy, gdy punkt końcowy obsługuje nowszą wersję.
Weryfikacja Transport Layer Security (TLS)	Włączona; nie udostępniono żadnego niezabezpieczonego przełącznika.	Nigdy nie wyłączaj jej dla ruchu produkcyjnego.
Poświadczenia	Odczytywane ze środowiska; nigdy niezapisywane bezpośrednio w kodzie.	W środowisku produkcyjnym użyj menedżera sekretów.
Limit rozmiaru w pamięci	Odrzucanie na ścieżce klienta plików PDF większych niż 100 MiB.	Obniż go dla usług wielodostępnych; w przypadku większych plików użyj CLI.
Współbieżność	Ograniczona semaforem w partiach asynchronicznych.	Dostrajaj ją do limitu punktu końcowego, a nie do liczby rdzeni hosta.
Rejestrowanie	Rejestrowanie nazwy pliku, rozmiaru, statusu i czasu trwania.	Nigdy nie rejestruj bajtów pliku PDF ani klucza API.

Lista kontrolna testów

• Testy konstruowania potwierdzają, że pusty base_url lub api_key powoduje zgłoszenie ValueError.
• Testy walidacji obejmują brakujące, puste, zbyt duże dane wejściowe oraz dane niebędące plikami PDF.
• Testy ekstrakcji potwierdzają zwracane typy modeli oraz obecność CitationAnchor w każdym bloku.
• Testy trybów awarii obejmują AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError oraz NextPDFAPIError.
• Testy asynchroniczne potwierdzają, że klient działa jako menedżer kontekstu async with oraz że współbieżność pozostaje w granicach ograniczenia semafora.
• Testy cyklu życia potwierdzają, że close() zwalnia transport i jest idempotentne.
• Wstrzyknij testowy backend za pomocą AsyncNextPDF(backend=...), aby testy działały bez aktywnego punktu końcowego.

Zobacz też

• Dokumentacja interfejsu API dla języka Python — wszystkie metody klienta, modele i wyjątki.
• Interfejs CLI dla języka Python — strumieniowa ekstrakcja dla dużych dokumentów.
• Serwer MCP dla języka Python — narzędzia ekstrakcji dla agentów AI.
• Omówienie zestawu SDK dla języka Python — wybór backendu i ograniczenia.