Migrare treptată către API-ul Responses
Pe această pagină
Actualizat la 3 noiembrie 2026: Maparea parametrilor indica anterior că
max_tokensîși păstrează numele în API-ul Responses; tabelul xAI îl schimbă înmax_output_tokens, iar contoarele de utilizare își schimbă, de asemenea, denumirile. Sursă: Comparație cu Chat Completions.
De ce și când să migrați
Endpoint-ul Chat Completions este marcat ca moștenit (legacy). Va continua să funcționeze, dar nu i se vor adăuga funcționalități noi. Dacă aplicația dumneavoastră are nevoie de instrumente lato-server (căutare web, executare de cod), stocarea conversațiilor sau raționament criptat, migrarea către API-ul Responses devine necesară.
Vestea bună: această migrare se poate face treptat. Nu trebuie să rescrieți totul dintr-o dată.
Pasul 1: Identificați funcționalitățile pe care le utilizați
Înainte de a migra, faceți un inventar al ceea ce utilizează aplicația dumneavoastră cu Chat Completions:
# Audit your existing code
# Look for these patterns:
# 1. Basic calls (simple text)
client.chat.completions.create(model=..., messages=...)
# 2. Streaming
client.chat.completions.create(..., stream=True)
# 3. Function calling
client.chat.completions.create(..., tools=[...])
# 4. Vision (images)
# messages with content as array [text, image_url]
# 5. Generation parameters
# temperature, max_tokens, top_p, stop, seed
Apelurile de bază și streaming-ul sunt cele mai simple de migrat. Apelarea funcțiilor necesită adaptarea formatului. Vision funcționează similar.
Pasul 2: Migrați apelurile de bază
Migrarea unui apel simplu urmează acest model:
# BEFORE — Chat Completions
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]
)
texte = response.choices[0].message.content
# AFTER — Responses API
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="You are a helpful assistant.",
input="Hello!"
)
texte = response.output_text
Maparea câmpurilor
Principalele modificări sunt:
messagescu rolulsystem→instructions(parametru dedicat)messagescu roluluser→input(șir simplu)response.choices[0].message.content→response.output_textmax_tokens→max_output_tokens, conform tabelului de mapare xAI;temperatureîși păstrează numeleresponse.usage.prompt_tokensșicompletion_tokens→input_tokensșioutput_tokens(detalii:input_tokens_details.cached_tokens,output_tokens_details.reasoning_tokens)
Pasul 3: Migrați conversațiile multi-tur
Aici este locul unde API-ul Responses simplifică lucrurile. În loc să reconstruiți istoricul la fiecare cerere, le înlănțuiți prin ID:
# BEFORE — Chat Completions (manage history yourself)
historique = [
{"role": "system", "content": "You are a helpful assistant."}
]
def envoyer_message(texte: str) -> str:
historique.append({"role": "user", "content": texte})
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=historique
)
reponse = response.choices[0].message.content
historique.append({"role": "assistant", "content": reponse})
return reponse
# AFTER — Responses API (server manages history)
dernier_id = None
def envoyer_message(texte: str) -> str:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="You are a helpful assistant.",
input=texte,
previous_response_id=dernier_id
)
dernier_id = response.id
return response.output_text
Codul este mai simplu și nu mai trebuie să gestionați manual tabloul de mesaje.
Pasul 4: Profitați de noile funcționalități
Odată migrat, puteți valorifica funcționalități exclusive API-ului Responses:
Căutare web integrată
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the latest developments in generative AI?",
tools=[{"type": "web_search"}]
)
# The response includes citations with source URLs
Stocarea răspunsurilor
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Analyze this document...",
store=True # Keeps for 30 days
)
# Retrieve later
stored = client.responses.retrieve(response.id)
Raționament criptat
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Solve this complex problem...",
include=["reasoning.encrypted_content"]
)
# The encrypted reasoning can be reused in subsequent requests
Strategia de migrare recomandată
În loc să migrați totul dintr-o dată, procedați în pași:
- Identificați apelurile Chat Completions din codul dumneavoastră
- Clasificați-le după complexitate (bazic → streaming → apelare de funcții)
- Migrați mai întâi endpoint-urile sau funcționalitățile noi (greenfield)
- Apoi migrați apelurile existente cele mai simple
- Păstrați Chat Completions pentru integrările cu terțe părți care îl necesită (LangChain, etc.)
Coexistența temporară
Este perfect acceptabil să rulați ambele endpoint-uri în paralel în timpul tranziției:
# Wrapper that abstracts the endpoint used
class GrokClient:
def __init__(self, use_responses: bool = False):
self.use_responses = use_responses
self.client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
def generate(self, system: str, user_message: str) -> str:
if self.use_responses:
response = self.client.responses.create(
model="grok-4.20-0309-reasoning",
instructions=system,
input=user_message
)
return response.output_text
else:
response = self.client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": system},
{"role": "user", "content": user_message}
]
)
return response.choices[0].message.content
Această abordare vă permite să faceți comutarea treptat, testând fiecare migrare individual.
Puncte cheie
- Migrarea poate fi treptată: nu este nevoie să rescrieți totul dintr-o dată
- Principalele modificări:
messages→input/instructions,choices[0].message.content→output_text - Conversațiile multi-tur trec de la un tablou de mesaje la un simplu
previous_response_id - API-ul Responses oferă acces la funcționalități exclusive (web_search, stocare, raționament criptat)
- Rulați ambele endpoint-uri în paralel în timpul tranziției și migrați în ordinea complexității
Testați-vă cunoștințele
API-ul moștenit este înțeles, iar migrarea este pregătită.
1. Ce înseamnă statutul de moștenit și fără stare (stateless) al Chat Completions?
Răspuns: Endpoint-ul rămâne suportat, dar nu mai evoluează: fiind fără stare, necesită retransmiterea întregului istoric la fiecare apel – API-ul Responses este calea modernă.
2. Care roluri structurează mesajele?
Răspuns: system (și developer), user, assistant – cadrul, cererile, răspunsurile: întregul istoric repornește la fiecare cerere.
3. Cum utilizați codul OpenAI existent cu Grok?
Răspuns: Schimbând base_url în https://api.x.ai/v1 și cheia API – compatibilitatea formatului se ocupă de rest, inclusiv pentru OpenAI SDK și Vercel AI SDK.
4. Ce citiți în răspuns și în utilizare?
Răspuns: choices conține răspunsuri cu finish_reason; usage detaliază tokenii, inclusiv reasoning_tokens pentru modelele de raționament – baza pentru urmărirea costurilor.
5. Cum migrați corect către API-ul Responses?
Răspuns: Treptat: noile dezvoltări în Responses, endpoint-urile existente convertite unul câte unul cu retestarea prompt-urilor – compararea celor două formate ghidează conversia.
Înțelegeți moștenirea, construiți pentru modern: planul de migrare treptată al cursului este harta dumneavoastră rutieră – fără o schimbare bruscă (big bang).