Структурирано извличане на entidades
На тази страница
Урокът е актуализиран на 3 ноември 2026 г. въз основа на документацията на OpenAI: параметрите
temperatureиtop_pсе приемат само при усилие за разсъждение (reasoning effort) отnone, докато моделите GPT-5.6 разсъждават по подразбиране (medium). Следователно заявките, които задават тези параметри, трябва да включватreasoning={"effort": "none"}(Responses API) илиreasoning_effort="none"(Chat Completions). Източници: Използване на GPT-6 · GPT-5.6 Terra.
Структурирано извличане на entidades
Структурираното извличане на entidades е едно от най-търсените приложения в производствена среда: трансформиране на свободен текст (имейли, документи, уеб страници) в данни, които Вашето приложение може реално да използва. Чрез комбиниране на структуриран изход със специализирани подкани (prompts), можете да изградите надеждни конвейери за извличане, без да обучавате специализиран NER модел.
Основен конвейер за извличане
Цялата специфика на извличането се крие в системната подкана на функцията по-долу и тя заслужава внимателно разглеждане. Тук се припокриват три инструкции: извлечете само това, което присъства, използвайте null за липсващи данни и никога не правете изводи за информация, която не е изрично спомената.
Последното изречение е най-важното на практика. Оставен на собствените си устройства, моделът с удоволствие ще попълни правдоподобен номер SIRET или ще отгатне град въз основа на телефонен код, с най-добри намерения. За извличане, предназначено за бизнес система, тази услужливост е сериозен недостатък: веднъж щом данните са в базата данни, няма начин да се различи какво е било прочетено от това, което е било предположено. Задаването на temperature на 0.0 служи на същата цел – при две изпълнения на един и същи документ искате един и същи изход, макар и само за да възпроизведете инцидент.
import json
from openai import OpenAI
client = OpenAI()
def extract_entities(text: str, schema: dict,
instructions: str = "") -> dict:
"""Извлича структурирани entidades от свободен текст."""
system = (
"You are a specialized entity extractor. "
"Extract ONLY information present in the text. "
"If information is missing, use null. "
"NEVER infer information not explicitly mentioned."
)
if instructions:
system += f"\n\nAdditional instructions: {instructions}"
response = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature requires effort none
instructions=system,
input=f"Text to analyze:\n\n{text}",
text={
"format": {
"type": "json_schema",
"name": "extraction",
"schema": schema,
"strict": True
}
},
temperature=0.0
)
return json.loads(response.output_text)
Пример 1: Извличане от автобиография
Автобиографията е отлична тестова среда, защото комбинира стабилни секции с напълно свободен формат. Схемата по-долу групира контактните данни в обект identity, където почти всяко поле може да бъде null – кандидатът може да не предостави телефонен номер и правенето на това поле задължително би поканило модела да го измисли.
Уменията не са просто низове, а обекти с три атрибута, което Ви позволява да запазите посоченото ниво и да категоризирате всяко умение. Без тези изброими типове (enums), „Scrum“ и „Python“ биха се озовали рамо до рамо в един плосък списък, безполезен за филтър, опитващ се да изолира езици за програмиране. Обърнете внимание и на полето end_date в опита, което може да бъде null, докато start_date не е: така кодирате текуща позиция, без да измисляте собствена конвенция като „present“ или „9999“. В тестовата автобиография тази тънкост се проявява в реда за 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)
Пример 2: Извличане от търговски имейл
Вторият пример променя естеството си: вече не просто копираме информация, а искаме от модела да я интерпретира. intent (намерение) и urgency (спешност) са преценки – нито едно изречение в имейла не казва „това е заявка за оферта, висок приоритет“. Това е точно това, което класически конвейер за извличане, базиран на правила или регулярни изрази, не може да направи, и това е точно оправданието за използване на LLM тук, а не другаде.
Останалата част от схемата се връща към проверими факти: споменати продукти, суми с техния контекст, дати и тяхното значение, необходими действия. Полето summary затваря обекта и служи на човека, който ще преглежда опашката, а не на кода. Един момент на бдителност при тази смесена схема: грешка в преценката за urgency не инвалидира сумите, но обратното може да се случи, защото модел, който не разбира намерението, понякога чете останалото през тази погрешна призма. Ако класификацията е критична за Вашето насочване, отделете я в отделно извикване.
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
}
Пакетно извличане
За обработка на големи обеми, паралелизирайте Вашите извличания. Последователен цикъл върху хиляда документи прекарва повечето време в чакане на мрежата; с asyncio тези чакания се припокриват и пакетът се обработва за част от времето.
Семафорът не е декоративна подробност. Без него, стартирането на хиляда задачи наведнъж ще насити Вашата квота и ще задейства грешки за ограничаване на скоростта (rate limit), които струват повече при повторните опити, отколкото спестяват в скорост. Задайте стойността на max_concurrent, като наблюдавате собствените си лимити, като десет е предпазлива начална точка. Обърнете внимание и на return_exceptions=True: то предотвратява един единствен дефектен документ да срине целия пакет, оставяйки Ви да сортирате неуспехите след това.
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
async def extract_batch(texts: list[str], schema: dict,
max_concurrent: int = 10) -> list[dict]:
"""Паралелно извличане с контрол на конкурентността."""
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 requires effort none
instructions="Extract entities from the provided text. "
"Use null for missing fields.",
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)
Оценяване на качеството на извличането
Конвейер за извличане без анотиран тестов набор е конвейер, чиято надеждност никой не познава, а впечатлението, оставено от три примера, прочетени на ръка, почти винаги се оказва твърде оптимистично. Функцията по-долу сравнява полученото извличане поле по поле спрямо ръчно установен еталон, връщайки обща прецизност заедно с разбивка на несъответствията.
Тази разбивка е полезната част: грешките почти никога не са разпределени равномерно. Едно поле концентрира проблемите – често това е неясна дата, имплицитно ниво на умение или лошо дефинирана категория – и едно единствено изречение, добавено към системната подкана, го оправя. Без това измерване бихте настройвали подканата наслуки, възможно е дори да влошите поле, което вече е работело добре.
def evaluate_extraction(expected: dict, obtained: dict,
fields: list[str]) -> dict:
"""Сравнява полученото извличане с еталона."""
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
}
Изградете своя еталон преди оптимизация
Изберете тип документ от Вашата област – договори, фактури, отчети – и дефинирайте схема за извличане от поне десет полета, умишлено смесвайки лесни полета с такива, за които знаете, че са двусмислени. Съберете пет примерни документа с техните очаквани извличания, написани на ръка: тази стъпка е досадна, отнема един час, но тя е това, което придава стойност на цялата последваща работа.
След това стартирайте конвейера, измерете прецизността и прочетете списъка с грешки поле по поле. Най-дефектното поле ще Ви каже какво да коригирате в подканата; второ измерване ще Ви каже дали корекцията действително е помогнала – или дали е влошила друго поле в процеса, което се случва по-често, отколкото бихте си помислили, щом допълнителна инструкция измести вниманието на модела.
Ключови изводи
- Структурираното извличане замества специализираните NER модели за повечето случаи на употреба
- Използвайте
temperature=0.0, за да максимизирате консистентността - Правете незадължителните полета nullable, а не optional
- Паралелизирайте с asyncio за големи обеми
- Систематично оценявайте качеството с анотиран тестов набор
- Инструкциите в системната подкана насочват съдържанието, схемата ограничава структурата