Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Aschur Struchtúrtha: JSON Ráthaithe

Ceacht 9 as 22 Nuashonraithe 29 Iúil 2026 Forbróir
Ar an leathanach seo
  1. Aschur Struchtúrtha: JSON Ráthaithe
  2. An fhadhb a réitíonn sé seo
  3. Pydantic in ionad Scéama JSON a scríobh de láimh
  4. Dhá chás úsáide coitianta
  5. Cad a éilíonn an mód dian
  6. Príomhphointí

Aschur Struchtúrtha: JSON Ráthaithe

Is é Aschur Struchtúrtha ceann de na gnéithe is cumhachtaí den API Freagraí. In ionad bheith ag súil go dtugann an tsamhail JSON bailí ar ais, ráthaíonn tú é trí scéama a sholáthar. Ansin, tá an tsamhail srianta go struchtúrtha chun é a leanúint. Tiontaíonn sé seo samhail teanga ó ghineadóir téacs cruthaitheach go comhpháirt iontaofa i bpíblíne próiseála uathoibrithe.

An fhadhb a réitíonn sé seo

Oibríonn sé formhór na huaire nuair a iarrann tú JSON sa leid, rud a fhágann go bhfuil an cur chuige contúirteach go díreach mar gheall air sin. Lá amháin as gach céad, cuirfidh an tsamhail ráiteas réamhráite roimh a freagra, fillfidh sí gach rud i mbloc cód Markdown, nó athainmneoidh sí réimse – agus caithfidh do json.loads() eisceacht i dtáirgeadh ar iarratas nach féidir leat a atáirgeadh.

from openai import OpenAI
client = OpenAI()

# Gan struchtúr — is féidir leis an tsamhail aon fhormáid a thabhairt ar ais
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Give me info about Paris in JSON."
)
print(response.output_text)
# Toradh neamhthuartha:
# Uaireanta JSON bailí, uaireanta téacs ina bhfuil JSON,
# uaireanta formáid gan choinne...

Athraíonn an paraiméadar text nádúr an ráthaíochta. Dearbhaíonn tú formáid json_schema mar aon leis an scéama atá ag teastáil, agus déanann an t-aschur comhréir leis: bíonn díshreabhú ina oibríocht shábháilte.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Give me information about Paris.",
    text={
        "format": {
            "type": "json_schema",
            "name": "city_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "country": {"type": "string"},
                    "population": {"type": "integer"},
                    "official_language": {"type": "string"},
                    "landmarks": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["name", "country", "population", "official_language", "landmarks"],
                "additionalProperties": False
            }
        }
    }
)

import json
data = json.loads(response.output_text)
print(f"City: {data['name']}")
print(f"Population: {data['population']:,}")
print(f"Landmarks: {', '.join(data['landmarks'])}")

# Toradh RÁTHAITHE go bhfuil sé ina JSON bailí:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur

Pydantic in ionad Scéama JSON a scríobh de láimh

Éiríonn sé tuirsiúil go tapa scéamaí a scríobh de láimh agus tá siad faoi thionchar botúin chló. Ligeann Pydantic duit iad a chur síos mar aicmí Python, an Scéama JSON a ghiniúint le model_json_schema(), agus ansin an freagra a bhailíochtú agus a chlóscríobh le model_validate_json(). Ag deireadh an tslabhra, faigheann tú oibiacht Python iomlán le huathchríochnú an eagarthóra, seachas foclóir gan ainm.

from pydantic import BaseModel
from typing import Optional
import json

class Product(BaseModel):
    name: str
    price: float
    category: str
    in_stock: bool
    description: Optional[str] = None

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Describe a high-end gaming laptop.",
    text={
        "format": {
            "type": "json_schema",
            "name": "product",
            "strict": True,
            "schema": Product.model_json_schema()
        }
    }
)

# Parsáil agus bailíochtú le Pydantic
product = Product.model_validate_json(response.output_text)
print(f"Product: {product.name}")
print(f"Price: {product.price} EUR")
print(f"In stock: {'Yes' if product.in_stock else 'No'}")

# Toradh:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes

Níl aon rud a chuireann bac ort ar struchtúir chothroma. Trí aicmí a chumasc, déanann tú cur síos ar oibiachtaí neadaithe agus liostaí d’oibiachtaí, rud a bheidh uait chomh luath agus a chruthaíonn tú próifíl custaiméara réadúil: tá teagmhálaithe i gcuideachta, agus tá seoladh ag gach teagmhálaí.

from pydantic import BaseModel

class Address(BaseModel):
    street: str
    city: str
    postal_code: str
    country: str

class Contact(BaseModel):
    last_name: str
    first_name: str
    email: str
    phone: str
    address: Address

class Company(BaseModel):
    name: str
    sector: str
    employees: int
    contacts: list[Contact]

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Generate a fictional company profile in the tech sector "
          "with 2 contacts.",
    text={
        "format": {
            "type": "json_schema",
            "name": "company",
            "strict": True,
            "schema": Company.model_json_schema()
        }
    }
)

company = Company.model_validate_json(response.output_text)
print(f"Company: {company.name} ({company.sector})")
for c in company.contacts:
    print(f"  - {c.first_name} {c.last_name}: {c.email}")

Dhá chás úsáide coitianta

Is é an chéad cheann ná eastóscadh: téacs scríofa a thiontú ina thaifead inúsáidte. Déantar fógra comhdhála atá scríofa i dteanga nádúrtha ina shraith bunachair sonraithe le teideal, dáta, suíomh, agus líon freastalaithe – gan slonn rialta, agus gan briseadh gach uair a athraíonn an foclaíocht.

class Event(BaseModel):
    title: str
    date: str
    location: str
    attendees: int

text = """
The PyCon France 2026 conference will be held on November 15 and 16
at the Palais des Congrès in Lyon. More than 800 Python developers
are expected for this edition.
"""

response = client.responses.create(
    model="gpt-5.6-terra",
    input=f"Extract the information from this event:\n{text}",
    text={
        "format": {
            "type": "json_schema",
            "name": "event",
            "strict": True,
            "schema": Event.model_json_schema()
        }
    }
)

evt = Event.model_validate_json(response.output_text)
print(f"{evt.title} - {evt.date} at {evt.location} ({evt.attendees} attendees)")
# Toradh: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)

Is é an dara ceann ná aicmiú. Trí áireamh a dhearbhú, sriant tú an tsamhail go foclóir dúnta: ní féidir léi “réasúnta dearfach” nó “dearfach” a fhreagairt nuair a bhíonn positive ag teastáil ó do chód. Sin an difríocht idir luach is féidir leat a úsáid go díreach agus luach ar gá duit a normalú ina dhiaidh sin.

from enum import Enum

class Sentiment(str, Enum):
    positive = "positive"
    negative = "negative"
    neutral = "neutral"

class Analysis(BaseModel):
    sentiment: Sentiment
    confidence: float
    keywords: list[str]

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Analyze this comment: 'Great service, fast delivery!'",
    text={
        "format": {
            "type": "json_schema",
            "name": "sentiment_analysis",
            "strict": True,
            "schema": Analysis.model_json_schema()
        }
    }
)

analysis = Analysis.model_validate_json(response.output_text)
print(f"Sentiment: {analysis.sentiment.value} ({analysis.confidence:.0%})")
# Toradh: Sentiment: positive (95%)

Cad a éilíonn an mód dian

Tagann malartú leis an ráthaíocht: nuair atá strict: True, caithfidh an scéima cloí le fo-thacar sonrach de Scéama JSON. Is iad na srianta seo an phríomhchúis le hearráidí 400 do thosaitheoirí, mar sin is fearr iad a bheith ar eolas agat sula mbuaileann tú leo:

  • Caithfear gach airí a liostú in required
  • Caithfidh additionalProperties a bheith False
  • Cineálacha tacaithe: string, number, integer, boolean, array, object, null
  • Gan oneOf ná anyOf le cineálacha measctha
  • Úsáid Optional[str], a aistríonn go {"anyOf": [{"type": "string"}, {"type": "null"}]}

Go minic, cuireann an riail faoi required iontas ar dhaoine: ní léirítear réimse roghnach trína bhaint den liosta, ach trí chead a thabhairt don luach null, díreach mar a dhéanann Optional[str] ar thaobh Pydantic.

Príomhphointí

  • Ráthaíonn Aschur Struchtúrtha go leanann an freagra do scéama JSON
  • Úsáid text={"format": {"type": "json_schema", ...}} san API Freagraí
  • Is é Pydantic an uirlis idéalach chun scéamaí a shainiú agus a bhailíochtú
  • Cumasaigh strict: True chun comhlíonadh scéama ráthaithe a fháil
  • Ideálach d’eastóscadh sonraí, aicmiú, agus giniúint struchtúrtha