AI Engineering Academy · Lektion

Instructor: Typisierte Extraktion mit Pydantic

Instructor: Typisierte Extraktion mit Pydantic ist eine kostenlose AI Engineering Academy-Lektion auf CoddyKit. Dies ist Lektion 1 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des AI Engineering Academy-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der AI Engineering Academy-Kurs umfasst insgesamt 4 Lektionen.

Was ist die Instructor-Bibliothek?

Die Bibliothek instructor ist ein schlanker Wrapper um den OpenAI-Client, der eine zuverlässige strukturierte Extraktion ermöglicht. Statt darauf zu hoffen, dass das Modell gültiges JSON zurückgibt, setzt instructor Ihr Pydantic-Schema durch und startet bei einem Validierungsfehler automatisch einen neuen Versuch. Dadurch entfällt die Notwendigkeit, eigene Parsing- und Wiederholungslogik zu schreiben.

Instructor installieren

Installieren Sie instructor mit einem einzigen pip-Befehl. Dafür benötigen Sie pydantic v2 und das openai-SDK. Nach der Installation versehen Sie den OpenAI-Client mit instructor.patch(), um den erweiterten Client zu erhalten, der bei jedem Aufruf den Parameter response_model unterstützt.

pip install instructor openai pydantic

Den OpenAI-Client patchen

Instructor funktioniert, indem der standardmäßige OpenAI-Client gepatcht wird. Der Aufruf instructor.from_openai(client) gibt einen neuen Client zurück, bei dem jeder Aufruf von chat.completions.create das Schlüsselwortargument response_model akzeptiert. Der zugrunde liegende API-Aufruf bleibt identisch – instructor ergänzt lediglich die Schemaüberprüfung.

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

Ihr Pydantic-Schema definieren

Definieren Sie die gewünschte Datenstruktur als Pydantic BaseModel. Feldnamen, Typen und Docstrings werden automatisch in das an das Modell gesendete JSON Schema umgewandelt. Verwenden Sie klare, aussagekräftige Feldnamen, damit das Modell versteht, welche Werte es eintragen soll. Fügen Sie für Geschäftsregeln Validatoren hinzu.

from pydantic import BaseModel, Field
from typing import Optional

class PersonExtract(BaseModel):
    name: str = Field(description='Full name of the person')
    age: Optional[int] = Field(None, description='Age in years if mentioned')
    email: Optional[str] = Field(None, description='Email address if present')
    company: Optional[str] = Field(None, description='Company or employer')

Eine Extraktionsanfrage durchführen

Übergeben Sie Ihre Pydantic-Modellklasse als response_model an den gepatchten Client. Instructor erstellt im Hintergrund einen Tool-Aufruf, das Modell füllt die Felder aus, und instructor deserialisiert das Ergebnis in ein typisiertes Python-Objekt. Für die zurückgegebenen Daten stehen Ihnen vollständige IDE-Autovervollständigung und Typsicherheit zur Verfügung.

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[
        {'role': 'user', 'content': 'Alice Smith, 34, works at Acme Corp. Email: alice@acme.com'}
    ]
)
print(result.name)   # Alice Smith
print(result.email)  # alice@acme.com

Automatischer Wiederholungsversuch bei Validierungsfehlern

Wenn die vom Modell zurückgegebenen Daten die Pydantic-Validierung nicht bestehen, sendet instructor den Validierungsfehler automatisch an das Modell zurück und fordert es auf, seine Antwort zu korrigieren. Mit dem Parameter max_retries können Sie die maximale Anzahl der Wiederholungsversuche konfigurieren. Diese selbstheilende Schleife verhindert die meisten vereinzelten Extraktionsfehler ohne zusätzlichen Code.

import instructor
from openai import OpenAI
from pydantic import BaseModel, field_validator

client = instructor.from_openai(OpenAI())

class Product(BaseModel):
    name: str
    price_usd: float

    @field_validator('price_usd')
    @classmethod
    def must_be_positive(cls, v):
        if v <= 0:
            raise ValueError('Price must be positive')
        return v

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=Product,
    max_retries=3,
    messages=[{'role': 'user', 'content': 'Widget costs $12.99'}]
)

Verschachtelte Modelle für komplexe Strukturen

Instructor verarbeitet verschachtelte Pydantic-Modelle nahtlos. Sie können tief verschachtelte Schemata mit Listen, optionalen Unterobjekten und diskriminierten Unions definieren. Das Modell erhält das vollständige JSON Schema und muss alle erforderlichen Felder ausfüllen. Damit eignet sich dieser Ansatz ideal für die Extraktion strukturierter Objekte wie Rechnungen oder Lebensläufe mit mehreren Abschnitten.

from pydantic import BaseModel
from typing import List

class LineItem(BaseModel):
    description: str
    quantity: int
    unit_price: float

class Invoice(BaseModel):
    vendor: str
    invoice_number: str
    total_amount: float
    line_items: List[LineItem]

result = client.chat.completions.create(
    model='gpt-4o',
    response_model=Invoice,
    messages=[{'role': 'user', 'content': invoice_text}]
)

Partielle Extraktionen streamen

Für umfangreiche Extraktionsaufgaben unterstützt instructor partielles Streaming über instructor.Partial[YourModel]. Während das Modell Tokens erzeugt, erhalten Sie in Echtzeit teilweise ausgefüllte Modellinstanzen. Das ist nützlich, um den Fortschritt in einer Benutzeroberfläche anzuzeigen oder Felder zu verarbeiten, sobald sie eintreffen, statt auf die vollständige Antwort zu warten.

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

for partial in client.chat.completions.create_partial(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[{'role': 'user', 'content': long_text}]
):
    print(partial.name, partial.email)

Listen von Objekten extrahieren

Wenn Sie mehrere Entitäten aus einem einzelnen Dokument extrahieren möchten, verpacken Sie Ihr Modell in List[YourModel]. Instructor verarbeitet das JSON-Array-Schema und deserialisiert jedes Element in ein typisiertes Python-Objekt. Dieser Ansatz eignet sich gut, um alle in einem Artikel erwähnten Personen, alle Transaktionen in einem Kontoauszug oder alle Datumsangaben in einem Vertrag zu extrahieren.

from pydantic import BaseModel
from typing import List

class Mention(BaseModel):
    entity: str
    entity_type: str  # PERSON, ORG, DATE, LOCATION
    context: str

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=List[Mention],
    messages=[{'role': 'user', 'content': article_text}]
)
for mention in result:
    print(f'{mention.entity} ({mention.entity_type})')

Das passende Modell für die Extraktion auswählen

Nicht jede Extraktion erfordert GPT-4o. Bei einfachen flachen Schemata mit weniger als 10 Feldern liefert gpt-4o-mini zu einem Zehntel der Kosten nahezu identische Ergebnisse. Verwenden Sie GPT-4o für komplexe verschachtelte Schemata, lange Dokumente oder Fälle, in denen die Trefferquote entscheidend ist. Führen Sie immer einen Benchmark mit einem Ausschnitt Ihrer echten Daten durch, bevor Sie ein Modell für die Produktion auswählen.

# Cost comparison for 1000 extractions
# GPT-4o-mini: ~$0.002 per call = $2.00 total
# GPT-4o: ~$0.015 per call = $15.00 total
# Test both on 50 samples and compare F1 score
# before committing to the expensive model

Extraktionen protokollieren und debuggen

Instructor stellt für die Beobachtbarkeit ein hooks-System bereit. Registrieren Sie einen on_completion-Callback, um für jede Extraktion die rohe API-Antwort, den Token-Verbrauch und die Anzahl der Wiederholungsversuche zu protokollieren. So erkennen Sie, welche Dokumenttypen die meisten Fehler verursachen, und können Ihre Schemata oder Prompts entsprechend anpassen.

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

@client.on('completion:response')
def log_usage(response):
    usage = response.usage
    print(f'Tokens: {usage.prompt_tokens}+{usage.completion_tokens}')

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[{'role': 'user', 'content': text}]
)

Kurze Überprüfung

Testen Sie Ihr Verständnis der instructor-Bibliothek für typisierte Extraktionen.

Zusammenfassung der Lektion

In dieser Lektion haben Sie gelernt: instructor patcht den OpenAI-Client, damit dieser einen response_model-Parameter akzeptiert, der Pydantic-Schemata durchsetzt. Automatische Wiederholungsversuche bei Validierungsfehlern machen Extraktionen ohne manuelle Fehlerbehandlung robust. Verschachtelte Modelle und die Extraktion von Listen ermöglichen es, komplexe Dokumente mit mehreren Entitäten in vollständig typisierte Python-Objekte zu überführen. Als Nächstes behandeln wir unvollständige und fehlende Daten in extrahierten Schemata.

Häufig gestellte Fragen

Ist die Lektion „Instructor: Typisierte Extraktion mit Pydantic“ kostenlos?

Ja — der vollständige Text von „Instructor: Typisierte Extraktion mit Pydantic“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des AI Engineering Academy-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der AI Engineering Academy-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Instructor: Typisierte Extraktion mit Pydantic“?

Verwenden Sie die Bibliothek instructor, um den OpenAI-Client zu erweitern, sodass er Antworten automatisch erneut anfordert und gegen Ihr Pydantic-Schema validiert, bis die Extraktion erfolgreich is… Du übst AI Engineering Academy mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um AI Engineering Academy zu starten?

Keine Vorkenntnisse erforderlich. AI Engineering Academy auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 1 von 4.

Wie lange dauert die Lektion „Instructor: Typisierte Extraktion mit Pydantic“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser AI Engineering Academy-Lektion Code schreiben und ausführen?

Ja. Jede AI Engineering Academy-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

Instructor: Typisierte Extraktion mit Pydantic
Unvollständige und fehlende Daten verarbeiten
Batch-Verarbeitung mit Async und Queues
Schema-Weiterentwicklung und Abwärtskompatibilität

← Zurück zu AI Engineering Academy