PDFs und Dateien
Ein Modell zu einem Dokument befragen, nativ oder über OCR: Formate, Grenzen, Kosten und Fehler.
Wann nutzen
Verträge, Rechnungen, Aufsätze, Scans: Fragen zu einem Dokument stellen, Felder extrahieren, zusammenfassen. Zwei Wege führen zum Modell:
Nativer file-Teil | OCR (Plugin file-parser) | |
|---|---|---|
| Funktioniert mit | Modellen, die file in architecture.input_modalities führen | jedem Textmodell |
| Quelle | URL oder Base64-Data-URL; bei manchen Anbietern eine Datei-ID | Base64-PDF als Data-URL oder HTTP(S) bei aktiviertem Laden |
| Das Modell liest | das Dokument, wie der Anbieter es verarbeitet | extrahierten Text vom konfigurierten OCR-Modell |
| Gescannte Seiten | hängt vom Modell ab | werden per OCR gelesen |
| Grenzen | je Route | 8 PDFs, je 1.000 Seiten, zusammen 4 MiB extrahierter Text |
| Kosten | Eingabe-Tokens | OCR je Seite plus Eingabe-Tokens des Texts |
| Streaming | wie üblich | erst die Extraktion, dann beginnt der Stream |
Den nativen Weg nutzen, wenn ein Modell mit file-Eingabe passt. OCR nutzen, wenn das Modell keine Dateieingabe hat oder die Seiten Scans sind. Das Gateway extrahiert nie von selbst: Ein file-Teil an ein Modell ohne Dateieingabe scheitert mit 404 no_endpoint. Die Einstellungen des Plugins und eine vollständige OCR-Anfrage in curl, Node und Python stehen im PDF-Parser.
Minimalbeispiel
Der native Weg: ein Textteil mit der Frage und ein file-Teil mit einem einseitigen PDF als Data-URL. Er braucht ein Modell, das file als Eingabe führt; hat der Katalog keines, die OCR-Anfrage unten nutzen.
Anfrageformat
Der Dateiteil:
{ "type": "file", "file": { "filename": "invoice.pdf", "file_data": "data:application/pdf;base64,JVBERi0xLjQK..." } }
| Feld | Wert |
|---|---|
file.file_data | Eine http(s)-URL oder eine Base64-Data-URL data:application/pdf;base64,<data> |
file.file_id | ID einer zuvor hochgeladenen Datei; gilt nur beim ausstellenden Anbieter. |
file.filename | Optional; hilft dem Modell, mehrere Dateien zu unterscheiden. |
file_data oder file_id ist Pflicht (sonst 400). PDF ist der übertragbare Typ; andere Dokumenttypen hängen von der Route ab.
Eine Route kann Typen, Größe und Anzahl von Dateien begrenzen. Das Gateway prüft eingebettete Daten vor dem Aufruf und nennt Route und Feld in issues (unsupported_media_type, media_type_mismatch, media_too_large, too_many_media). Natives URL-Material kann bei Bedarf und aktiviertem Laden über den geschützten Medienlader angepasst werden.
Der OCR-Weg ergänzt ein Plugin; dieses Beispiel nutzt Base64:
"plugins": [{ "id": "file-parser", "pdf": { "engine": "mistral-ocr" } }]
- Eingabe: eine Data-URL
data:application/pdf;base64,..., die dekodiert mit%PDF-beginnt, oder eine HTTP(S)-PDF-URL bei aktiviertemmedia_transport.fetch_enabled. Datei-IDs und andere Medientypen bleiben unverfügbar. - Anzahl: höchstens 8 PDFs je Anfrage, je höchstens 1.000 Seiten. Die Body-Grenze von 50 MiB gilt; Base64 macht ein PDF etwa ein Drittel größer.
- Ergebnis: extrahierter Text ersetzt den
file-Teil; übriger Nachrichtentext bleibt. Insgesamt gelten 4 MiB und die Kontextgrenze des Modells. - Zeitpunkt: Extraktion läuft einmal je Anfrage vor dem Stream, auch bei Anbieter-Fallbacks.
- Engine:
pdf.engineist optional (Standardmistral-ocr);"enabled": falseschaltet das Plugin aus.
Details
- Verfügbare Engines werden über
preprocessing.ocr_enginesnormalen OCR-Modellen zugeordnet. Unbekannte oder nicht zugeordnete Engines bleiben unverfügbar; fehlende Konfiguration ergibtfeature_unavailable. - Das Laden prüft Host-Regeln und öffentliche Adressen bei jeder Weiterleitung, mit Redirect-, Byte- und Zeitgrenzen sowie PDF-MIME- und Signaturprüfung.
- Das PDF-Plugin nutzt das Mistral-OCR-Protokoll. Bei Image-Chat-OCR wie LightOnOCR rendert ein konfigurierter interner Medienworker höchstens 16 Seiten als Bilder; ohne ihn bleiben PDFs für diese Route unverfügbar. Verschlüsselte PDFs werden nicht gerendert.
Modell wählen
- Nativ: im Katalog nach Eingabe
filefiltern, Route prüfen; sonst OCR nutzen. - OCR: jedes Textmodell mit genug Kontext.
Faustregel: 500 bis 1.000 Tokens je dichter Textseite, bis zu 100.000 für 100 Seiten. Deutscher Text und Tabellen brauchen mehr.
Kosten
Nativer Weg: Der Anbieter macht aus dem Dokument Eingabe-Tokens (Text und oft Seitenbilder); usage.prompt_tokens zeigt, wie viele. Das Gateway kann sie vorab nicht zählen und reserviert das ganze Kontextfenster der Route als Prompt. Reine Bildanfragen können eine verifizierte Schätzung verwenden (siehe Bildverständnis).
OCR-Weg: OCR-Modelle rechnen je Seite oder je Token ab; die aktuellen Preise stehen im OCR-Katalog und auf jeder Modellseite. Der Vorverarbeitungsbeleg nennt die Abrechnungsbasis und optional token_usage, sofern der Anbieter diese liefert. usage.cost_details.ocr_cost (EUR) mit ocr_documents ist in usage.cost enthalten, auch bei Chat-Fallbacks nur einmal je Dokument. Extrahierter Text zählt danach als normale Chat-Eingabe.
Eine Anfrage zu einem gescannten PDF hat damit drei Teile: die OCR-Seiten (oder OCR-Tokens), den extrahierten Text als Eingabe-Tokens des Chatmodells und die Antwort als Ausgabe-Tokens. usage.cost ist ihre Summe; cost_details zeigt die Teile.
Reservierung vor dem Aufruf
- Ein konsistentes, lesbares eingebettetes PDF bis 8 MiB reserviert seine Seitenzahl plus 10 %, mindestens eine zusätzliche Seite, höchstens 1.000 Seiten. Ein einseitiges PDF reserviert deshalb zwei OCR-Seiten zuzüglich Inferenz.
- Verschlüsselte, beschädigte oder nicht unterstützte PDFs, fehlende Parser-Ressourcen und unbekannte Seitenzahlen behalten die Obergrenze von 1.000 Seiten.
- Native Dateien behalten die Kontextfenster-Reservierung.
remedy_hintunterscheidet bei 402 die Methode.
Bei seitenbasierter OCR zählen danach nur tatsächlich verarbeitete Seiten; tatsächliche Nutzung über der Schätzung bleibt zahlbar.
Häufige Fehler
| Status, Typ | Ursache und Abhilfe |
|---|---|
404 no_endpoint | Das Modell hat keine Dateieingabe und das Plugin ist aus. Abhilfe: plugins ergänzen oder ein Modell aus remedy_hint wählen. |
501 feature_unavailable | Laden entfernter PDFs ist deaktiviert oder die OCR-Modellzuordnung fehlt. Abhilfe: Ein eingebettetes PDF senden oder begrenztes Laden und OCR vom Betreiber konfigurieren lassen. |
400 invalid_parameter, Issue invalid_value | Die Daten dekodieren nicht zu einem PDF (%PDF-), oder mehr als 8 PDFs. Abhilfe: Gültige PDFs senden, höchstens 8. |
400 invalid_parameter, Issue not_available bei plugins[].pdf.engine | Eine unbekannte Engine. Abhilfe: Eine konfigurierte Engine nutzen oder engine weglassen; ein nicht zugeordneter Standard bleibt unverfügbar. |
400 context_length_exceeded | Der extrahierte Text passt nicht in das Modell. Die OCR ist bereits berechnet. Abhilfe: Das Dokument teilen oder ein Modell mit mehr Kontext wählen. |
413 payload_too_large | Body über 50 MiB oder extrahierter Text über 4 MiB. Abhilfe: Weniger oder kürzere PDFs senden. |
402 insufficient_credits | Die Seitenzahl mit Aufschlag, ersatzweise 1.000 Seiten, oder der native Kontext übersteigt Key-Limit oder Guthaben. Abhilfe: remedy_hint lesen; Guthaben aufladen, Limit erhöhen oder das Dokument aufteilen. |
| Fehler des Medienladers | Verstoß gegen die Ladegrenzen oben oder Quellfehler. Abhilfe: issues und remedy_hint prüfen; erlaubte öffentliche PDF-URL oder eingebettete Daten nutzen. |
502 provider_error, provider_invalid_response | Der OCR-Dienst ist ausgefallen oder lieferte ein unbrauchbares Ergebnis, etwa mehr als 1.000 Seiten. Abhilfe: Einmal wiederholen; das Dokument teilen. |
Bewährte Praxis
- Ein echtes Dokument auf beiden Wegen testen und Antwortqualität und
usage.costvergleichen. - Nur die benötigten Seiten senden. Das PDF selbst zuschneiden: OCR berechnet je Seite, das Modell je Token.
- Extrahierter Text wird nicht zurückgegeben. Erneutes Senden mit Plugin extrahiert und berechnet erneut. Einmal eine vollständige strukturierte Extraktion erfragen und mit der Antwort weiterarbeiten.
- Dokumenttext ist nicht vertrauenswürdig und kann Anweisungen enthalten. Extrahierte Beträge und Daten vor Nutzung an der Quelle prüfen.
- Bei Seiten, auf die das Layout ankommt (Tabellen, Formulare), die Seite als Bild rendern und mit Bildverständnis vergleichen.
- Dokumente über 1.000 Seiten oder 4 MiB Text aufteilen.
Für KI-Agenten
- Endpunkt: [
POST /chat/completions](https://tokenlane.de/docs/gateway/post-L2NoYXQvY29tcGxldGlvbnM.md?lang=de); das Dokument steht inmessages[].content[]. - Nativer Teil:
{"type":"file","file":{"filename":"x.pdf","file_data":"<URL oder data:application/pdf;base64,...>"}}; das Modell brauchtfileinarchitecture.input_modalities. - OCR:
"plugins":[{"id":"file-parser","pdf":{"engine":"mistral-ocr"}}]ergänzen;data:application/pdf;base64,...oder HTTP(S) bei aktiviertem Laden nutzen; Datei-IDs bleiben unverfügbar; höchstens 8 PDFs, je 1.000 Seiten, zusammen 4 MiB Text. - Grenzen: Body 50 MiB; der extrahierte Text muss in den Kontext des Modells passen.
- Kosten: native Eingabe-Tokens; OCR in
usage.cost_details.ocr_cost(EUR) zuzüglich Tokens. Reservierung: lesbare PDF-Seiten plus 10 % (mindestens eine extra, höchstens 1.000); unbekannte Seiten bleiben bei 1.000; native Dateien beim ganzen Kontextfenster. Tatsächliche Nutzung ist zahlbar. - Fehler: 404
no_endpoint, 400invalid_parameter(Issue-Codesnot_available,invalid_value,media_*), 501feature_unavailable, Fehler des Medienladers, 413, 402, 502.