Bailíochtú le JSON Schema agus Zod
Ar an leathanach seo
An ceacht nuashonraithe an 3 Samhain, 2026 bunaithe ar dhoiciméadú OpenAI: ní ghlactar le
temperatureagustop_pach le hiarracht réasúnaíochta denone, cé go ndéanann samhlacha GPT-5.6 réasúnú go huathoibríoch (medium). Caithfidh glaonna a shocraíonn na paraiméadair seoreasoning={"effort": "none"}(API Freagraí) nóreasoning_effort="none"(Críochnú Comhrá) a shonrú dá bhrí sin. Foinse: GPT-6 a úsáid · GPT-5.6 Terra.
Bailíochtú le JSON Schema agus Zod
Ráthaíonn Aschur Struchtúrtha struchtúr na freagra, ach ní ráthaíonn sé bailíocht shéimeantach na sonraí. D’fhéadfadh réimse “ríomhphost” teaghrán a bheith ann nach ríomhphost bailí é. Is é bailíochtú taobh an chliaint ag baint úsáide as JSON Schema nó Zod an comhlánú riachtanach do phíblíne láidir.
Cén fáth bailíochtú a dhéanamh tar éis glacadh
Déan stoc a ghlacadh ar an méid a ráthaíonn an API, agus éireoidh an roinnt oibre soiléir. Cinntíonn Aschur Struchtúrtha OpenAI go bhfuil an JSON bailí go sintacteach, go n-urramaítear na cineálacha dearbhaithe—fanann teaghrán ina theaghrán, fanann slánuimhir ina slánuimhir—go bhfuil gach réimse riachtanach i láthair, agus go mbaineann luachanna atá faoi shriain ag enum leis an liosta. Ar na ceithre phointe seo, is féidir leat do chód a scríobh le muinín.
Tá gach rud eile ortsa, ag clúdach ceithre theaghlach fadhbanna. Éalaíonn srianta formáide ón scéima dochta: ní chuireann aon rud cosc ar an tsamhail jean.dupont(at)example.fr a thabhairt ar ais i réimse email, nó dáta i bhformáid 15/03/2026 nuair a bhíonn tú ag súil le ISO. Ní dhéantar seiceáil ar theorainneacha ach an oiread, ná ar fhad teaghráin ná ar raon uimhreacha: rachaidh aois 350 tríd gan pliocadh. Fanann comhsheasmhacht tras-réimse as láimh—tá end_date níos luaithe ná start_date bailí go hiomlán mar JSON. Agus níl aon chúis go mbainfeadh bailíocht ghnó leas as an API: caithfidh SIRET (Aitheantas Gnó Francach) a bheith ceithre dhigit dhéag, ach is eolas do fearainn féin é sin, ní eolas an díchódóra.
Roinneann na ceithre theaghlach seo tréith uafásach: ní chruthaíonn siad aon earráidí infheicthe. Ní bheidh ríomhphost míchumtha a shábháiltear sa bhunachar sonraí le feiceáil go dtí go dteipeann ar an fheachtas ríomhphoist seachtainí ina dhiaidh sin. Sin é an riail: déan bailíochtú sula ndéanann tú buanú, riamh ina dhiaidh.
Bailíochtú Python le jsonschema
Is é an toradh praiticiúil ná go dteastaíonn dhá scéima uait don sonra céanna. Téann an chéad cheann chuig an API, gan bheith ach chomh lag is gá, teoranta don méid a ghlacann mód dochta. Fanann an dara ceann leatsa agus iompraíonn sé na srianta mionghrádacha—format, pattern, minimum, maximum. Is dealú imní é an dúbailt seo dealraitheach: cuimsíonn ceann amháin giniúint, cosnaíonn an ceann eile do stóráil. Sa sampla thíos, ní fheictear ach an t-enum róil i ngach ceann, toisc gurb é sin an t-aon srian is féidir leis an dá leibhéal a shloinneadh.
import json
from jsonschema import validate, ValidationError
# Schema for OpenAI API (strict, no format/pattern)
api_schema = {
"type": "object",
"properties": {
"email": {"type": "string"},
"age": {"type": "integer"},
"role": {"type": "string", "enum": ["admin", "user", "viewer"]}
},
"required": ["email", "age", "role"],
"additionalProperties": False
}
# Extended schema for client-side validation
validation_schema = {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"pattern": r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z]{2,}$"
},
"age": {
"type": "integer",
"minimum": 0,
"maximum": 150
},
"role": {"type": "string", "enum": ["admin", "user", "viewer"]}
},
"required": ["email", "age", "role"]
}
def validate_response(data: dict) -> tuple[bool, str]:
"""Validates the LLM response against the extended schema."""
try:
validate(instance=data, schema=validation_schema)
return True, "Valid"
except ValidationError as e:
return False, f"Error: {e.message}"
Bailíochtú le Pydantic
Is minic go mbíonn Pydantic níos áisiúla ná jsonschema le haghaidh bailíochtú i Python, agus tá an difríocht le feiceáil sa méid a fhaigheann tú ar aschur. Insíonn jsonschema duit sea nó ní hea agus fágann sé leat foclóir, á láimhseáil trí data["email"] gan aon chabhair ón eagarthóir. Tugann Pydantic oibiacht chlóscríofa ar ais: oibríonn uathchríochnú, braitear mílitriú in ainm airí ag am scríofa, agus sreabhann na sonraí ina dhiaidh sin gan tiontú.
Léiríonn an tsamhail ContactExtraction teorainneacha go díreach sna dearbhuithe réimse. Clúdaíonn an field_validator ar date_extraction an cás nach féidir le haon chlóscríobh a ghabháil: is teaghrán é an teaghrán go deimhin, ach caithfidh sé dáta fíor a léiriú—sásaíonn 2026-02-31 aon pattern réasúnach ach níl sé ann. Taispeánann an fheidhm eastóscána an slabhra iomlán, ón scéima lag a sheoltar chuig an API go dtí an tástáil bhailíochtaithe.
from pydantic import BaseModel, Field, field_validator
from pydantic import EmailStr
from datetime import date
class ContactExtraction(BaseModel):
"""Validation schema for contact extraction."""
last_name: str = Field(min_length=2, max_length=100)
first_name: str = Field(min_length=2, max_length=100)
email: EmailStr
phone: str = Field(pattern=r"^\+?[0-9\s\-\.]{10,15}$")
company: str
title: str
extraction_date: str
@field_validator("extraction_date")
@classmethod
def validate_date(cls, v):
try:
date.fromisoformat(v)
return v
except ValueError:
raise ValueError(f"Invalid date: {v}")
def extract_and_validate(text: str) -> ContactExtraction:
"""Extracts a contact and validates the data."""
# Schema for API (without fine-grained constraints)
api_schema = {
"type": "object",
"properties": {
"last_name": {"type": "string"},
"first_name": {"type": "string"},
"email": {"type": "string"},
"phone": {"type": "string"},
"company": {"type": "string"},
"title": {"type": "string"},
"extraction_date": {"type": "string"}
},
"required": ["last_name", "first_name", "email", "phone",
"company", "title", "extraction_date"],
"additionalProperties": False
}
response = client.responses.create(
model="gpt-5.6-terra",
instructions="Extract contact information. "
"Date format: YYYY-MM-DD.",
input=text,
text={
"format": {
"type": "json_schema",
"name": "contact",
"schema": api_schema,
"strict": True
}
}
)
data = json.loads(response.output_text)
# Pydantic validation with fine-grained constraints
return ContactExtraction(**data)
Bailíochtú le Zod (TypeScript/Node.js)
Má tá do chúldeireadh i TypeScript, is é Zod an uirlis tagartha, agus tugann sé buntáiste nach gá do Pydantic a sholáthar: díorthaíonn z.infer an cineál TypeScript go díreach ón scéima bailíochtúcháin. Déanann tú cur síos ar an gcruth uair amháin, agus ansin tá a fhios ag an tiomsaitheoir struchtúr Invoice gan duit comhéadan comhthreomhar a chothabháil, mar sin níl aon riosca divergeance ann.
Léiríonn an scéima sonraisc thíos an roinnt oibre: ar thaobh an API, ní ach teaghrán é siret; ar thaobh Zod, caithfidh sé a bheith ceithre dhigit dhéag go beacht agus gan a bheith ann ach digití amháin. Ardaíonn an parse deiridh eisceacht mura n-oiriúnaíonn na sonraí, agus sin an iompar atá ag teastáil—is fearr earráid ard a chuireann stop le próiseáil na doiciméad ná sonraisc SIRET fantaisíochta a stóráiltear sa bhunachar sonraí i measc na mílte eile.
import { z } from "zod";
import OpenAI from "openai";
const client = new OpenAI();
// Zod schema with fine-grained validations
const InvoiceSchema = z.object({
number: z.string().regex(/^[A-Z]{2}-\d{4}-\d{4}$/),
date: z.string().date(),
amount_excl_tax: z.number().positive(),
vat_rate: z.number().min(0).max(100),
amount_incl_tax: z.number().positive(),
supplier: z.object({
name: z.string().min(2),
siret: z.string().length(14).regex(/^\d+$/),
}),
});
type Invoice = z.infer<typeof InvoiceSchema>;
async function extractInvoice(text: string): Promise<Invoice> {
const response = await client.responses.create({
model: "gpt-5.6-terra",
instructions: "Extract invoice data.",
input: text,
text: {
format: {
type: "json_schema",
name: "invoice",
schema: {
type: "object",
properties: {
number: { type: "string" },
date: { type: "string" },
amount_excl_tax: { type: "number" },
vat_rate: { type: "number" },
amount_incl_tax: { type: "number" },
supplier: {
type: "object",
properties: {
name: { type: "string" },
siret: { type: "string" },
},
required: ["name", "siret"],
additionalProperties: false,
},
},
required: ["number", "date", "amount_excl_tax",
"vat_rate", "amount_incl_tax", "supplier"],
additionalProperties: false,
},
strict: true,
},
},
});
const data = JSON.parse(response.output_text);
// Zod validation with fine-grained constraints
return InvoiceSchema.parse(data);
}
Patrún: athiarracht le ceartúchán
Nuair a theipeann ar an mbailíochtú, seol an earráid ar ais chuig an tsamhail le haghaidh ceartúcháin. Athraíonn an frithghníomh seo nádúr na teipe: ní eisceacht a bhrúnn suas chuig an úsáideoir a thuilleadh é dáta sa fhormáid mícheart, ach turas breise timpeall cúpla céad millisoicind nach dtugann aon duine faoi deara. Tá an mheicníocht simplí—athinstillimid an teachtaireacht bhailíochtúcháin isteach i leid na chéad iarrachta eile, ionas go bhfuil a fhios ag an tsamhail go beacht cad a chuaigh mícheart in ionad buille faoi thuairim a dhéanamh go dall den dara huair.
Éilíonn an tsuaimhneas seo teorainneacha, áfach. Cuir teorainn le líon na n-iarrachtaí, nó chosnóidh srian dodhéanta—pattern ró-docht d’uimhreacha eachtracha, mar shampla—glaoonna ort i lúb. Agus déan monatóireacht ar an ráta athiarrachta: má théann ceathrú de do chuid eastóscán trí athiarracht, tá an fhadhb sa leid tosaigh nó sa scéima, ní sa tsamhail.
def extract_with_retry(prompt: str, schema: dict,
validator, max_retries: int = 3) -> dict:
"""Extracts and validates with automatic retry."""
last_error = None
for attempt in range(max_retries):
input_text = prompt
if last_error:
input_text += (f"\n\nWARNING: Your previous response had "
f"this validation error: {last_error}\n"
f"Correct and try again.")
response = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature requires effort none
input=input_text,
text={"format": {"type": "json_schema",
"name": "data",
"schema": schema,
"strict": True}},
temperature=0.1
)
data = json.loads(response.output_text)
is_valid, error = validator(data)
if is_valid:
return data
last_error = error
raise ValueError(f"Failed after {max_retries} attempts: {last_error}")
Binse tástála do chuireadh féilire
Tóg scéima Pydantic chun imeachtaí a eastóscadh—teideal, dáta, am, suíomh, rannpháirtithe—ansin plugáil é taobh thiar de ghlao Aschur Struchtúrtha. Déan tástáil ar chúig ríomhphost ina bhfuil cuireadh, ag déanamh cinnte go n-áirítear ceann amháin ar a laghad ina bhfuil an t-am scríofa amach (“Déardaoin déanach sa mhaidin”) agus ceann ina bhfuil an suíomh intuigthe (“mar is gnách sa seomra comhdhála”). Is iad seo na cásanna a bhriseann bailíochtú, agus is iad sin a bhíonn i gceannas i mbosca isteach fíor.
Ansin cuir athiarracht uathoibríoch leis agus tomhais dhá fhigiúr: an ráta ratha ar an gcéad iarracht agus an ráta tar éis athiarrachta. Inseoidh an dara ceann duit cad a cheannaíonn ceartúchán duit, an chéad cheann an chóir duit do threoracha a athoibriú seachas brath ar an dara seans.
Príomhphointí
- Ráthaíonn Aschur Struchtúrtha struchtúr, ní bailíocht shéimeantach
- Úsáid dhá scéima: ceann amháin don API (docht), ceann eile le haghaidh bailíochtú cliant
- Is iad Pydantic (Python) agus Zod (TypeScript) na huirlisí tagartha
- Ceartaíonn an patrún athiarrachta le haiseolas formhór na n-earráidí bailíochtúcháin
- Déan bailíochtú taobh an chliaint i gcónaí sula ndéanann tú buanú ar shonraí