Responses API vs Chat Completions: Miksi siirtyä?
Tällä sivulla
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 Completions | Responses API |
|---|---|
client.chat.completions.create() | client.responses.create() |
messages=[...] | input="..." tai input=[...] |
response.choices[0].message.content | response.output_text |
| Manuaalinen historia | previous_response_id |
response_format | text={"format": {...}} |
tools + tool_choice | tools (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