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

Responses API vs Chat Completions: Miksi siirtyä?

Oppitunti 2 / 22 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Responses API vs Chat Completions
  2. Perustavanlaatuiset muutokset
  3. Palvelinpuolen istunnonhallinta
  4. Taattu JSON, ei toiveikas JSON
  5. Funktiokutsut ja suoratoisto
  6. Pikaopas migraatioon
  7. Kannattaako siirtyä heti?
  8. Keskeiset asiat

Responses API vs Chat Completions

Chat Completions API toimi vuosia alan standardina, ja suurin osa netistä löytämästäsi koodista käyttää sitä edelleen. Vuodesta 2025 lähtien OpenAI on kuitenkin merkinnyt sen vanhentuneeksi (legacy) ja suosittelee Responses API:a kaikkiin uusiin projekteihin. Tässä oppitunnissa vertaamme näitä kahta rajapintaa keskittyen eroihin, jotka vaikuttavat todellisuudessa koodiisi.

Perustavanlaatuiset muutokset

Chat Completionsissa rakensit viestilistan ja lähetit koko listan jokaisella kutsulla. Keskustelun tila säilyi sovelluksessasi, ei palvelimella:

from openai import OpenAI
client = OpenAI()

# Vanha malli — Chat Completions (vanhentunut)
response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"},
    ]
)
print(response.choices[0].message.content)
# Tulos: "The capital of France is Paris."

Responses API tiivistää saman kutsun kahteen parametriin ja tarjoaa suoran pääsyn generoituun tekstiin. Järjestelmäviesti muuttuu instructions-parametriksi, eikä sisällön hakeminen enää vaadi navigointia polussa choices[0].message.content:

from openai import OpenAI
client = OpenAI()

# Uusi malli — Responses API
response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the capital of France?"
)
print(response.output_text)
# Tulos: "The capital of France is Paris."

Palvelinpuolen istunnonhallinta

Tämä tarjoaa välittömimmän hyödyn. API hallinnoi keskustelun tilaa, joten sinun tarvitsee vain viitata edelliseen vastaukseen sen ID:n avulla. Kuvittele tukipalveluassistentti: kymmenennellä vuorolla Chat Completions -lähestymistapa pakotti sinut lähettämään uudelleen edelliset yhdeksän vaihtoa, mikä tarkoitti, että maksoit näistä tokeneista uudelleen. Tässä yksi kenttä riittää:

# Ensimmäinen kysymys
response = client.responses.create(
    model="gpt-5.6-terra",
    input="My name is Marie."
)

# Toinen kysymys — konteksti säilyy automaattisesti
followup = client.responses.create(
    model="gpt-5.6-terra",
    input="What is my name?",
    previous_response_id=response.id
)
print(followup.output_text)
# Tulos: "Your name is Marie."

Taattu JSON, ei toiveikas JSON

Toinen merkittävä parannus koskee strukturoitua tulostetta. Kuvailet odotetun muodon, ja Responses API takaa, että vastaus noudattaa JSON-skeemaasi – voit purkaa (deserialize) tiedot ilman varmistusmekanismeja. Rekisteröintilomake, joka poimii tietoa vapaasta tekstistä, ei enää hajoa vain siksi, että malli päättää lisätä johdantolauseen ennen JSON-osuutta:

from pydantic import BaseModel

class City(BaseModel):
    name: str
    country: str
    population: int

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Give me information about Paris.",
    text={"format": {"type": "json_schema", "json_schema": {
        "name": "city",
        "strict": True,
        "schema": City.model_json_schema()
    }}}
)
print(response.output_text)
# Tulos: {"name": "Paris", "country": "France", "population": 2161000}

Funktiokutsut ja suoratoisto

Työkalujen määrittely noudattaa samaa yksinkertaistamislogiikkaa: funktiokuvaus määritellään litteästi tools-kenttään, ja mallin pyytämä kutsu ilmestyy suoraan kohtaan response.output ilman ylimääräisiä sisäkkäisyystasoja.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the weather like in Lyon?",
    tools=[{
        "type": "function",
        "name": "get_meteo",
        "description": "Get the weather for a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "Name of the city"}
            },
            "required": ["city"]
        }
    }]
)

# API palauttaa suoritettavan funktiokutsun suoraan
for item in response.output:
    if item.type == "function_call":
        print(f"Function: {item.name}, Arguments: {item.arguments}")
# Tulos: Function: get_meteo, Arguments: {"city": "Lyon"}

Suoratoisto ei enää palauta erottamattomien palasten virtaa, vaan tyypitettyjä tapahtumia. Suodatat event.type:n perusteella ja tiedät tarkasti, mitä käsittelet – olipa kyseessä tekstinpätkä, funktion argumentti tai generoinnin loppu:

stream = client.responses.create(
    model="gpt-5.6-terra",
    input="Tell a short story.",
    stream=True
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Pikaopas migraatioon

Chat CompletionsResponses API
client.chat.completions.create()client.responses.create()
messages=[...]input="..." tai input=[...]
response.choices[0].message.contentresponse.output_text
Manuaalinen historiaprevious_response_id
response_formattext={"format": {...}}
tools + tool_choicetools (yksinkertaistettu)

Kannattaako siirtyä heti?

Chat Completions API toimii edelleen, eikä sitä olla poistamassa. Olemassa oleva koodi, joka toimii, ei vaadi muutoksia ja luottaa vanhaan muotoon rakennettuun testiputkeen, ei hyödy kiireellisestä uudelleenkirjoituksesta. Samoin, jos riiput kolmannen osapuolen kirjastosta, joka ei vielä tue Responses API:a, odota sen päivitystä. Minkä tahansa uuden projektin kohdalla vastaus on kuitenkin selkeä: Responses API on lähtökohta, ja tämän kurssin loppuosa etenee tästä olettamuksesta.

Keskeiset asiat

  • Responses API korvaa Chat Completionsin yksinkertaisemmalla rajapinnalla
  • Palvelinpuolen istunnonhallinta poistaa tarpeen lähettää historiaa uudelleen
  • Strukturoitu tuloste ja funktiokutsut ovat natiivisti integroituja
  • Migraatio on suoraviivaista: käsitteet pysyvät samoina, vain syntaksi muuttuu