Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

response_format-manuaalinen käyttö

Oppitunti 5 / 12 Päivitetty 30. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Tarkempi hallinta response_format-menetelmällä
  2. Työnkulku
  3. Täydellinen esimerkki
  4. Erot parse()-metodiin verrattuna
  5. Jäsennys ilman Pydanticia
  6. Milloin valita response_format
  7. Virheenkäsittely
  8. Keskeiset asiat

Tarkempi hallinta response_format-menetelmällä

Manuaalinen menetelmä response_format-parametrin avulla antaa sinulle täyden hallinnan jäsennykseen. Toisin kuin parse(), joka palauttaa tyypitetyn objektin, tämä lähestymistapa palauttaa JSON-merkkijonon, jonka jäsennät itse – Pydantic-malli tarjoaa vain skeeman (model_json_schema()) ja suorittaa validoinnin jälkikäteen. Valitse tämä menetelmä, kun tarvitset joustavuutta tai työskentelet ympäristössä, jossa Pydanticia ei ole käytettävissä.

Työnkulku

Käytettäessä response_format-parametria prosessi etenee kahdessa vaiheessa:

  1. API palauttaa JSONin merkkijonona kentässä response.choices[0].message.content
  2. Jäsennät tämän merkkijonon valitsemallasi menetelmällä

Täydellinen esimerkki

from openai import OpenAI
from pydantic import BaseModel

client = OpenAI(
    api_key="your-xai-key",
    base_url="https://api.x.ai/v1"
)

class MovieReview(BaseModel):
    title: str
    rating: float
    summary: str
    recommend: bool

response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[{
        "role": "user",
        "content": "Review the movie Inception"
    }],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "movie_review",
            "schema": MovieReview.model_json_schema()
        }
    }
)

# Sisältö on JSON-merkkijono
json_string = response.choices[0].message.content
print(type(json_string))  # <class 'str'>
print(json_string)
# {"title": "Inception", "rating": 9.2, "summary": "...", "recommend": true}

# Manuaalinen jäsennys Pydanticilla
parsed = MovieReview.model_validate_json(json_string)
print(parsed.title)  # "Inception"

Erot parse()-metodiin verrattuna

Näkökulmaparse()response_format
Palautusarvo(Response, ParsedModel)Vain Response
JäsennysAutomaattinenManuaalinen
Tietojen käyttöparsed.kenttäjson.loads() tai model_validate_json()
JoustavuusVakioMaksimaalinen
VirheenkäsittelySisäänrakennettuSinun vastuullasi

Jäsennys ilman Pydanticia

Sinun ei tarvitse käyttää Pydanticia tuloksen jäsentämiseen. Myös vakio json-moduuli toimii:

import json

response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[{
        "role": "user",
        "content": "Analyze this text and extract entities"
    }],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "entities",
            "schema": {
                "type": "object",
                "properties": {
                    "people": {
                        "type": "array",
                        "items": { "type": "string" }
                    },
                    "places": {
                        "type": "array",
                        "items": { "type": "string" }
                    }
                }
            }
        }
    }
)

data = json.loads(response.choices[0].message.content)
print(data["people"])  # ["Marie Curie", "Pierre Curie"]
print(data["places"])      # ["Paris", "Warsaw"]

Milloin valita response_format

response_format loistaa aina, kun haluat tarkastella tai tutkia JSONia ennen sen muuntamista objektiksi. Yleisin tapaus on lokitus: tuotantoympäristössä raakana JSONina säilyttäminen ennen muunnosta on usein auditointi- tai vianetsintävaatimus, eikä parse() tarjoa tätä sieppauspistettä. Seuraavaksi tulee skeema-kysymys: jos rajapintasopimuksesi on raaka JSON-skeema – jaettu muiden tiimien kanssa, työkalun generoima tai versioidtu erillään Python-koodista – sen suora pakottaminen on uskollisempaa kuin sen uudelleenrakentaminen Pydantic-mallina. Lopuksi, kaikki projektit eivät toimi Pydantic-ekosysteemissä: jos validointisi kulkee toisen kehyksen läpi tai läpi putkistosi spesifin välivaiheen käsittelyn, response_format antaa sinulle JSONin sellaisenaan ja jättää sinut hallitsemaan seuraavia vaiheita.

Virheenkäsittely

Manuaalisessa menetelmässä sinun on käsiteltävä jäsennysvirheet itse:

import json

try:
    data = json.loads(response.choices[0].message.content)
except json.JSONDecodeError as e:
    print(f"Jäsennysvirhe: {e}")

Käytännössä tämän virheen ei pitäisi koskaan esiintyä, sillä API takaa kelvollisen JSONin. Puolustava käsittely on kuitenkin edelleen paras käytäntö tuotantoympäristöissä.

Keskeiset asiat

  • response_format palauttaa JSON-merkkijonon kohteessa response.choices[0].message.content
  • Jäsennys on sinun vastuullasi: json.loads(), model_validate_json() tai jokin muu menetelmä
  • Voit käyttää raakaa JSON-skeemaa Pydantic-mallin sijaan
  • Joustavampi kuin parse(), mutta vaatii enemmän koodin kirjoittamista
  • Palautettu JSON on taatusti kelvollinen – jäsennysvirheitä ei pitäisi esiintyä