API-ul Responses vs. Chat Completions: De ce să migrați
Pe această pagină
API-ul Responses vs. Chat Completions
API-ul Chat Completions a fost standardul timp de ani de zile, iar o mare parte din codul disponibil online îl utilizează încă. Totuși, începând cu 2025, OpenAI l-a desemnat ca fiind învechit (legacy) și recomandă API-ul Responses pentru toate proiectele noi. Această lecție compară cele două interfețe, concentrându-se pe diferențele care impactează efectiv codul dumneavoastră.
Modificări fundamentale
Cu Chat Completions, construiam o listă de mesaje și trimiteam întreaga listă la fiecare apel. Starea conversației rezida în aplicația dumneavoastră, niciodată pe server:
from openai import OpenAI
client = OpenAI()
# Modelul vechi — Chat Completions (învechit)
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)
# Rezultat: "The capital of France is Paris."
API-ul Responses reduce acest același apel la doar doi parametri și oferă acces direct la textul generat. Mesajul de sistem devine parametrul instructions, iar extragerea conținutului nu mai necesită navigarea prin choices[0].message.content:
from openai import OpenAI
client = OpenAI()
# Modelul nou — API-ul Responses
response = client.responses.create(
model="gpt-5.6-terra",
input="What is the capital of France?"
)
print(response.output_text)
# Rezultat: "The capital of France is Paris."
Gestionarea sesiunilor lato de server
Acest aspect oferă cel mai imediat beneficiu. API-ul menține starea conversației, astfel încât trebuie doar să faceți referire la răspunsul anterior prin ID-ul său. Imaginați-vă un asistent de suport: la a zecea interacțiune, abordarea Chat Completions vă forța să retrimiteți cele nouă schimburi anterioare, ceea ce însemna că plăteați din nou pentru acei tokeni. Aici, un singur câmp este suficient:
# Prima întrebare
response = client.responses.create(
model="gpt-5.6-terra",
input="My name is Marie."
)
# A doua întrebare — contextul este păstrat automat
followup = client.responses.create(
model="gpt-5.6-terra",
input="What is my name?",
previous_response_id=response.id
)
print(followup.output_text)
# Rezultat: "Your name is Marie."
JSON garantat, nu JSON bazat pe speranță
A doua îmbunătățire majoră privește ieșirea structurată. Descrieți formatul așteptat, iar API-ul Responses garantează că răspunsul respectă schema JSON specificată de dumneavoastră, permițându-vă să faceți deserializare fără plase de siguranță. Un formular de înregistrare care extrage informații din text liber nu se mai strică doar pentru că modelul decide să adauge o propoziție introductivă înainte de JSON-ul său:
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)
# Rezultat: {"name": "Paris", "country": "France", "population": 2161000}
Apelarea funcțiilor și streaming-ul
Declararea instrumentelor urmează aceeași logică de simplificare: descriptorul funcției este declarat direct în tools, iar apelul solicitat de model apare direct în response.output, fără niveluri suplimentare de imbricare.
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-ul returnează direct apelul funcției de executat
for item in response.output:
if item.type == "function_call":
print(f"Function: {item.name}, Arguments: {item.arguments}")
# Rezultat: Function: get_meteo, Arguments: {"city": "Lyon"}
Streaming-ul nu mai returnează un flux de fragmente nediferențiate, ci evenimente tipizate. Filtrați după event.type și știți exact ce gestionați: un fragment de text, un argument de funcție sau sfârșitul generării:
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)
Ghid rapid de migrare
| Chat Completions | API-ul Responses |
|---|---|
client.chat.completions.create() | client.responses.create() |
messages=[...] | input="..." sau input=[...] |
response.choices[0].message.content | response.output_text |
| Istoric manual | previous_response_id |
response_format | text={"format": {...}} |
tools + tool_choice | tools (simplificat) |
Ar trebui să migrați imediat?
API-ul Chat Completions rămâne funcțional și nu va fi eliminat. Codul existent care rulează, nu necesită modificări și se bazează pe o pipeline de testare construită în jurul formatului vechi nu are nimic de câștigat dintr-o rescriere urgentă. Similar, dacă depindeți de o librărie terță care nu suportă încă API-ul Responses, așteptați actualizarea acesteia. Totuși, pentru orice proiect nou, răspunsul este clar: API-ul Responses este punctul de plecare, iar restul acestui curs pornește de la această premisă.
Puncte cheie
- API-ul Responses înlocuiește Chat Completions cu o interfață mai simplă
- Gestionarea sesiunilor lato de server elimină necesitatea retrimiterii istoricului
- Ieșirea structurată și apelarea funcțiilor sunt integrate nativ
- Migrarea este simplă: conceptele rămân aceleași, se schimbă doar sintaxa