Przejdź do głównej treści
Polski— Wybierz język
Menu

Strukturalne wydobywanie encji

Lekcja 13 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Strukturalne wydobywanie encji
  2. Podstawowy potok ekstrakcji
  3. Przykład 1: Ekstrakcja z CV
  4. Przykład 2: Ekstrakcja z e-maila handlowego
  5. Ekstrakcja wsadowa
  6. Ocena jakości ekstrakcji
  7. Zbuduj swój wzorzec przed optymalizacją
  8. Kluczowe wnioski

Lekcja zaktualizowana 3 listopada 2026 r. na podstawie dokumentacji OpenAI: parametry temperature i top_p są akceptowane wyłącznie przy wysiłku rozumowania (reasoning effort) ustawionym na none, podczas gdy modele GPT-5.6 domyślnie przeprowadzają rozumowanie (medium). Wywołania ustawiające te parametry muszą zatem określać reasoning={"effort": "none"} (Responses API) lub reasoning_effort="none" (Chat Completions). Źródła: Using GPT-6 · GPT-5.6 Terra.

Strukturalne wydobywanie encji

Strukturalne wydobywanie encji to jedno z najczęściej wymaganych zastosowań w środowisku produkcyjnym: przekształcanie tekstu swobodnego (e-maile, dokumenty, strony internetowe) w dane, z których Twoja aplikacja może faktycznie skorzystać. Łącząc wyjście strukturalne ze specjalistycznymi promptami, możesz zbudować niezawodne potoki ekstrakcji bez konieczności trenowania dedykowanego modelu NER.

Podstawowy potok ekstrakcji

Cała specyfika ekstrakcji tkwi w prompcie systemowym poniższej funkcji i zasługuje ona na szczególną uwagę. Nakładają się tu trzy instrukcje: wydobywaj tylko to, co jest obecne, używaj null dla brakujących danych i nigdy nie wnioskuj informacji, które nie zostały wyraźnie wspomniane.

To ostatnie zdanie jest w praktyce najważniejsze. Pozostawiony sam sobie model chętnie uzupełni prawdopodobny numer SIRET lub zgadnie miasto na podstawie kodu pocztowego, kierując się najlepszymi intencjami. W przypadku ekstrakcji przeznaczonej dla systemu biznesowego taka usłużność jest poważną wadą: gdy dane trafią już do bazy, nie ma sposobu, by odróżnić to, co odczytano, od tego, co założono. Ustawienie temperature na 0.0 służy temu samemu celowi – przy dwóch przebiegach tego samego dokumentu chcesz uzyskać takie samo wyjście, choćby po to, by móc odtworzyć incydent.

import json
from openai import OpenAI

client = OpenAI()

def extract_entities(text: str, schema: dict,
                     instructions: str = "") -> dict:
    """Wydobywa strukturalne encje z tekstu swobodnego."""
    system = (
        "Jesteś wyspecjalizowanym ekstraktorem encji. "
        "Wydobywaj TYLKO informacje obecne w tekście. "
        "Jeśli informacje brakują, użyj null. "
        "NIGDY nie wnioskuj informacji, które nie zostały wyraźnie wspomniane."
    )
    if instructions:
        system += f"\n\nDodatkowe instrukcje: {instructions}"

    response = client.responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature wymaga effort none
        instructions=system,
        input=f"Tekst do analizy:\n\n{text}",
        text={
            "format": {
                "type": "json_schema",
                "name": "extraction",
                "schema": schema,
                "strict": True
            }
        },
        temperature=0.0
    )
    return json.loads(response.output_text)

Przykład 1: Ekstrakcja z CV

CV jest doskonałym polem testowym, ponieważ łączy stabilne sekcje z całkowicie dowolnym układem. Poniższy schemat grupuje dane kontaktowe w obiekcie identity, gdzie prawie każde pole może przyjmować wartość null – kandydat może nie podać numeru telefonu, a uczynienie tego pola wymaganym właściwie zachęciłoby model do jego wymyślenia.

Umiejętności nie są prostymi ciągami znaków, lecz obiektami z trzema atrybutami, co pozwala zachować zadeklarowany poziom i sklasyfikować każdą umiejętność. Bez tych wyliczeń „Scrum“ i „Python“ znalazłyby się obok siebie na tej samej płaskiej liście, co jest bezużyteczne dla filtra próbującego wyizolować języki programowania. Zwróć też uwagę na pole end_date w doświadczeniach, które może przyjmować wartość null, podczas gdy start_date jest wymagane: w ten sposób kodujesz obecne stanowisko, nie wymyślając własnych konwencji typu „present“ czy „9999“. W testowym CV ta subtelność uwidacznia się w wierszu dotyczącym firmy TechCorp.

resume_schema = {
    "type": "object",
    "properties": {
        "identity": {
            "type": "object",
            "properties": {
                "full_name": {"type": "string"},
                "email": {"type": ["string", "null"]},
                "phone": {"type": ["string", "null"]},
                "location": {"type": ["string", "null"]},
                "linkedin": {"type": ["string", "null"]}
            },
            "required": ["full_name", "email", "phone",
                          "location", "linkedin"],
            "additionalProperties": False
        },
        "current_title": {"type": ["string", "null"]},
        "years_experience": {"type": ["integer", "null"]},
        "skills": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "level": {
                        "type": "string",
                        "enum": ["beginner", "intermediate",
                                 "advanced", "expert"]
                    },
                    "category": {
                        "type": "string",
                        "enum": ["language", "framework", "tool",
                                 "methodology", "soft_skill"]
                    }
                },
                "required": ["name", "level", "category"],
                "additionalProperties": False
            }
        },
        "experiences": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "company": {"type": "string"},
                    "title": {"type": "string"},
                    "start_date": {"type": "string"},
                    "end_date": {"type": ["string", "null"]},
                    "description": {"type": "string"}
                },
                "required": ["company", "title", "start_date",
                              "end_date", "description"],
                "additionalProperties": False
            }
        },
        "education": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "institution": {"type": "string"},
                    "degree": {"type": "string"},
                    "year": {"type": ["string", "null"]}
                },
                "required": ["institution", "degree", "year"],
                "additionalProperties": False
            }
        },
        "languages": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "language": {"type": "string"},
                    "level": {
                        "type": "string",
                        "enum": ["a1", "a2", "b1", "b2",
                                 "c1", "c2", "native"]
                    }
                },
                "required": ["language", "level"],
                "additionalProperties": False
            }
        }
    },
    "required": ["identity", "current_title", "years_experience",
                  "skills", "experiences", "education", "languages"],
    "additionalProperties": False
}

resume_text = """
Marie Dupont - Senior Full Stack Developer
Email: [email protected] | Tel: +33 6 12 34 56 78
Paris, France | linkedin.com/in/mariedupont

8 years of experience in web development.

Skills: Python (expert), TypeScript (advanced), React (advanced),
Django (expert), PostgreSQL (advanced), Docker (intermediate),
Scrum (advanced)

Experience:
- TechCorp (2022-present): Lead Full Stack Developer
  Principal architect of a B2B SaaS platform, team of 6 devs.
- StartupAI (2019-2022): Senior Developer
  Development of ML APIs in Python/FastAPI.

Education:
- EPITECH Paris, Master in Computer Science (2017)

Languages: French (native), English (C1), Spanish (B1)
"""

result = extract_entities(resume_text, resume_schema)

Przykład 2: Ekstrakcja z e-maila handlowego

Drugi przykład zmienia charakter: nie kopiujemy już tylko informacji, lecz prosimy model o ich interpretację. Pola intent (zamiar) i urgency (pilność) to osądy – żadne zdanie w e-mailu nie brzmi „to jest prośba o wycenę, wysoki priorytet“. To właśnie jest coś, czego nie potrafi zrobić klasyczny potok ekstrakcji oparty na regułach lub wyrażeniach regularnych, i to dokładnie uzasadnia użycie tutaj LLM, a nie gdzie indziej.

Reszta schematu wraca do faktów podlegających weryfikacji: wspomniane produkty, kwoty z ich kontekstem, daty i ich znaczenie, wymagane działania. Pole summary zamyka obiekt i służy człowiekowi, który będzie przeglądał kolejkę, a nie kodowi. Jeden punkt czujności przy tym mieszanym schemacie: błąd w osądzie dotyczącym urgency nie unieważnia kwot, ale może zdarzyć się odwrotnie, ponieważ model, który źle zrozumie zamiar, czasem czyta resztę przez pryzmat tego nieporozumienia. Jeśli klasyfikacja jest kluczowa dla Twojego routingu, wydziel ją do osobnego wywołania.

email_schema = {
    "type": "object",
    "properties": {
        "intent": {
            "type": "string",
            "enum": ["quote_request", "complaint", "information",
                     "order", "partnership", "other"]
        },
        "urgency": {
            "type": "string",
            "enum": ["critical", "high", "normal", "low"]
        },
        "sender": {
            "type": "object",
            "properties": {
                "name": {"type": ["string", "null"]},
                "company": {"type": ["string", "null"]},
                "email": {"type": ["string", "null"]}
            },
            "required": ["name", "company", "email"],
            "additionalProperties": False
        },
        "mentioned_products": {
            "type": "array",
            "items": {"type": "string"}
        },
        "mentioned_amounts": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "value": {"type": "number"},
                    "currency": {"type": "string"},
                    "context": {"type": "string"}
                },
                "required": ["value", "currency", "context"],
                "additionalProperties": False
            }
        },
        "key_dates": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "date": {"type": "string"},
                    "significance": {"type": "string"}
                },
                "required": ["date", "significance"],
                "additionalProperties": False
            }
        },
        "required_actions": {
            "type": "array",
            "items": {"type": "string"}
        },
        "summary": {"type": "string"}
    },
    "required": ["intent", "urgency", "sender",
                  "mentioned_products", "mentioned_amounts",
                  "key_dates", "required_actions", "summary"],
    "additionalProperties": False
}

Ekstrakcja wsadowa

Aby przetwarzać duże wolumeny, sparalelizuj swoje ekstrakcje. Sekwencyjna pętla po tysiącu dokumentów spędza większość czasu na oczekiwaniu na sieć; dzięki asyncio te czasy oczekiwania nakładają się na siebie, a partia jest przetwarzana w ułamku czasu.

Semafor nie jest ozdobnym detalem. Bez niego uruchomienie tysiąca zadań naraz nasyci Twój limit i wywoła błędy ograniczenia częstotliwości (rate limit), które kosztują więcej przy ponownych próbach, niż oszczędzają na szybkości. Ustaw wartość max_concurrent, obserwując własne limity, przy czym dziesięć to ostrożny punkt wyjścia. Zwróć też uwagę na return_exceptions=True: zapobiega to sytuacji, w której jeden źle sformatowany dokument crashes całą partię, pozostawiając Ci sortowanie niepowodzeń na później.

import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI()

async def extract_batch(texts: list[str], schema: dict,
                          max_concurrent: int = 10) -> list[dict]:
    """Równoległa ekstrakcja z kontrolą współbieżności."""
    semaphore = asyncio.Semaphore(max_concurrent)

    async def extract_one(text: str) -> dict:
        async with semaphore:
            response = await async_client.responses.create(
                model="gpt-5.6-terra",
                reasoning={"effort": "none"},  # temperature wymaga effort none
                instructions="Wydobyj encje z dostarczonego tekstu. "
                             "Użyj null dla brakujących pól.",
                input=text,
                text={
                    "format": {
                        "type": "json_schema",
                        "name": "extraction",
                        "schema": schema,
                        "strict": True
                    }
                },
                temperature=0.0
            )
            return json.loads(response.output_text)

    tasks = [extract_one(t) for t in texts]
    return await asyncio.gather(*tasks, return_exceptions=True)

Ocena jakości ekstrakcji

Potok ekstrakcji bez anotowanego zbioru testowego to potok, którego niezawodności nikt nie zna, a wrażenie pozostawione przez trzy przykłady przeczytane ręcznie prawie zawsze okazuje się zbyt optymistyczne. Poniższa funkcja porównuje uzyskaną ekstrakcję pole po polu z ręcznie ustalonym wzorcem, zwracając ogólną precyzję wraz z zestawieniem rozbieżności.

To zestawienie jest najbardziej użyteczną częścią: błędy prawie nigdy nie są rozłożone równomiernie. Jedno pole koncentruje problemy – często jest to niejednoznaczna data, domniemany poziom umiejętności lub słabo zdefiniowana kategoria – a pojedyncze zdanie dodane do promptu systemowego naprawia sytuację. Bez tego pomiaru dostosowywałbyś prompt na ślepo, potencjalnie pogarszając pole, które już działało poprawnie.

def evaluate_extraction(expected: dict, obtained: dict,
                       fields: list[str]) -> dict:
    """Porównuje uzyskaną ekstrakcję ze wzorcem."""
    correct = 0
    total = len(fields)
    errors = []

    for field in fields:
        val_expected = expected.get(field)
        val_obtained = obtained.get(field)

        if val_expected == val_obtained:
            correct += 1
        else:
            errors.append({
                "field": field,
                "expected": val_expected,
                "obtained": val_obtained
            })

    return {
        "precision": correct / total if total > 0 else 0,
        "correct": correct,
        "total": total,
        "errors": errors
    }

Zbuduj swój wzorzec przed optymalizacją

Wybierz typ dokumentu ze swojej domeny – umowy, faktury, raporty – i zdefiniuj schemat ekstrakcji składający się z co najmniej dziesięciu pól, celowo mieszając pola łatwe z tymi, o których wiesz, że są niejednoznaczne. Złóż pięć przykładowych dokumentów z ich oczekiwanymi ekstrakcjami, zapisanymi ręcznie: ten krok jest żmudny, zajmuje godzinę, ale to on nadaje wartość całej późniejszej pracy.

Następnie uruchom potok, zmierz precyzję i przeczytaj listę błędów pole po polu. Najbardziej zawodne pole powie Ci, co poprawić w prompcie; drugi pomiar wskaże, czy poprawka faktycznie pomogła – czy może pogorszyła inne pole w tym procesie, co zdarza się częściej, niż mogłoby się wydawać, gdy tylko dodatkowa instrukcja przesunie uwagę modelu.

Kluczowe wnioski

  • Strukturalna ekstrakcja zastępuje dedykowane modele NER w większości przypadków użycia
  • Używaj temperature=0.0, aby zmaksymalizować spójność
  • Uczyń pola opcjonalne nullable, zamiast czynić je opcjonalnymi w sensie strukturalnym
  • Sparalelizuj z asyncio dla dużych wolumenów
  • Systematycznie oceniaj jakość za pomocą anotowanego zbioru testowego
  • Instrukcje w prompcie systemowym kierują treścią, schemat ogranicza strukturę