AI Engineering Academy · Lekcja

Instructor: ekstrakcja typowana z Pydantic

Użyj biblioteki instructor do rozszerzenia klienta OpenAI tak, aby automatycznie ponawiał próby i walidował odpowiedzi względem schematu Pydantic aż do pomyślnego zakończenia ekstrakcji.

Lekcja 1 z 413 kroki

Instructor: ekstrakcja typowana z Pydantic to bezpłatna lekcja AI Engineering Academy na CoddyKit. To lekcja 1 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej AI Engineering Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs AI Engineering Academy zawiera 4 lekcji w sumie.

Czym jest biblioteka Instructor?

Biblioteka instructor to cienka nakładka na klienta OpenAI, która sprawia, że ustrukturyzowane wydobywanie danych jest niezawodne. Zamiast liczyć na to, że model zwróci poprawny JSON, instructor wymusza użycie określonego przez Państwa schematu Pydantic i automatycznie ponawia próbę, jeśli walidacja się nie powiedzie. Eliminuje to konieczność samodzielnego pisania niestandardowej logiki parsowania i ponawiania prób.

Instalowanie Instructor

Bibliotekę instructor można zainstalować za pomocą pojedynczego polecenia pip. Wymaga ona pydantic v2 oraz SDK openai. Po instalacji należy zmodyfikować klienta OpenAI za pomocą instructor.patch(), aby uzyskać rozszerzonego klienta obsługującego parametr response_model przy każdym wywołaniu.

pip install instructor openai pydantic

Modyfikowanie klienta OpenAI

Instructor działa poprzez modyfikację standardowego klienta OpenAI. Wywołanie instructor.from_openai(client) zwraca nowego klienta, w którym każde wywołanie chat.completions.create przyjmuje argument nazwany response_model. Wywołanie bazowego API pozostaje identyczne — instructor dodaje jedynie wymuszanie zgodności ze schematem.

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

Definiowanie schematu Pydantic

Kształt danych, które mają zostać zwrócone przez model, należy zdefiniować jako Pydantic BaseModel. Nazwy pól, typy i docstringi są automatycznie konwertowane na schemat JSON wysyłany do modelu. Należy używać jasnych, opisowych nazw pól, aby model wiedział, jakie wartości wstawić. Dla reguł biznesowych należy dodać walidatory.

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')

Wykonywanie wywołania wydobywania danych

Klasę modelu Pydantic należy przekazać do zmodyfikowanego klienta jako response_model. Instructor w tle konstruuje wywołanie narzędzia, model wypełnia pola, a instructor deserializuje wynik do typowanego obiektu Pythona. Otrzymują Państwo pełne uzupełnianie kodu w IDE oraz bezpieczeństwo typów dla zwróconych danych.

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

Automatyczne ponawianie po nieudanej walidacji

Jeśli dane zwrócone przez model nie przejdą walidacji Pydantic, instructor automatycznie przesyła błąd walidacji z powrotem do modelu i prosi go o poprawienie odpowiedzi. Maksymalną liczbę ponowień można skonfigurować za pomocą parametru max_retries. Ta samonaprawiająca się pętla eliminuje większość pojedynczych błędów wydobywania danych bez dodatkowego kodu.

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'}]
)

Modele zagnieżdżone dla złożonych struktur

Instructor bezproblemowo obsługuje zagnieżdżone modele Pydantic. Można definiować głęboko zagnieżdżone schematy zawierające listy, opcjonalne obiekty podrzędne i unie rozróżniane. Model otrzymuje pełny schemat JSON i musi wypełnić wszystkie wymagane pola, dzięki czemu rozwiązanie idealnie nadaje się do wydobywania ustrukturyzowanych obiektów, takich jak faktury lub życiorysy z wieloma sekcjami.

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

Strumieniowe wydobywanie częściowych wyników

W przypadku dużych zadań wydobywania danych instructor obsługuje częściowe strumieniowanie za pomocą instructor.Partial[YourModel]. W miarę generowania tokenów przez model otrzymują Państwo w czasie rzeczywistym częściowo wypełnione instancje modelu. Przydaje się to do wyświetlania postępu w interfejsie użytkownika lub przetwarzania pól natychmiast po ich otrzymaniu, zamiast oczekiwania na pełną odpowiedź.

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)

Wydobywanie list obiektów

Gdy trzeba wydobyć wiele encji z jednego dokumentu, należy opakować model w List[YourModel]. Instructor obsługuje schemat tablicy JSON i deserializuje każdy element do typowanego obiektu Pythona. Ten wzorzec dobrze sprawdza się przy wydobywaniu wszystkich osób wymienionych w artykule, wszystkich transakcji z wyciągu lub wszystkich dat z umowy.

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

Wybór właściwego modelu do wydobywania danych

Nie każde wydobywanie danych wymaga GPT-4o. W przypadku prostych płaskich schematów z mniej niż 10 polami gpt-4o-mini daje niemal identyczne wyniki przy jednej dziesiątej kosztu. GPT-4o należy używać w przypadku złożonych zagnieżdżonych schematów, długich dokumentów lub sytuacji, w których istotna jest kompletność. Przed wyborem modelu do produkcji należy zawsze przeprowadzić test porównawczy na próbce rzeczywistych danych.

# 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

Rejestrowanie i debugowanie wydobywania danych

Instructor udostępnia system hooks zapewniający obserwowalność. Należy zarejestrować wywołanie zwrotne on_completion, aby rejestrować surową odpowiedź API, użycie tokenów i liczbę ponowień dla każdego wydobycia. Pomaga to ustalić, które typy dokumentów powodują najwięcej błędów, oraz odpowiednio dostroić schematy lub prompty.

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

Szybki sprawdzian

Sprawdź swoją wiedzę na temat biblioteki instructor do typowanego wydobywania danych.

Odpowiedz w interaktywnej lekcji

Podsumowanie rozdziału

W tym rozdziale nauczyłeś się, że instructor modyfikuje klienta OpenAI, aby akceptował parametr response_model wymuszający schematy Pydantic, automatyczne ponawianie po nieudanej walidacji sprawia, że wydobywanie danych jest niezawodne bez ręcznej obsługi błędów, a modele zagnieżdżone i wydobywanie list pozwalają analizować złożone dokumenty zawierające wiele encji i konwertować je na w pełni typowane obiekty Pythona. W następnej części zajmiemy się częściowymi i brakującymi danymi w wydobywanych schematach.

Bezpłatny start

Ucz się Python dzięki korepetycjom AI — za darmo

Pisz i uruchamiaj kod w przeglądarce, otrzymuj natychmiastową pomoc od korepetytora AI dostępnego 24/7 i kontynuuj naukę w sieci lub w aplikacji.

Kursy: 30
Lekcje: 120

Zacznij naukę bezpłatnie Wyświetl pełny kurs

Często zadawane pytania

Czy lekcja „Instructor: ekstrakcja typowana z Pydantic” jest bezpłatna?

Tak — pełny tekst „Instructor: ekstrakcja typowana z Pydantic” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu AI Engineering Academy, przejdź na CoddyKit PRO. Kurs AI Engineering Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Instructor: ekstrakcja typowana z Pydantic”?

Użyj biblioteki instructor do rozszerzenia klienta OpenAI tak, aby automatycznie ponawiał próby i walidował odpowiedzi względem schematu Pydantic aż do pomyślnego zakończenia ekstrakcji. Ćwiczysz AI Engineering Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć AI Engineering Academy?

Nie wymagamy żadnego doświadczenia. AI Engineering Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 1 z 4.

Ile czasu zajmuje lekcja „Instructor: ekstrakcja typowana z Pydantic”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji AI Engineering Academy?

Tak. Każda lekcja AI Engineering Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

Instructor: ekstrakcja typowana z Pydantic
Obsługa częściowych i brakujących danych
Przetwarzanie wsadowe z async i kolejkami
Ewolucja schematów i zgodność wsteczna

← Powrót do AI Engineering Academy