Salt la conținutul principal
Română— Alege o limbă
Meniu

Migrare treptată către API-ul Responses

Lecția 12 din 12 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. De ce și când să migrați
  2. Pasul 1: Identificați funcționalitățile pe care le utilizați
  3. Pasul 2: Migrați apelurile de bază
  4. Pasul 3: Migrați conversațiile multi-tur
  5. Pasul 4: Profitați de noile funcționalități
  6. Strategia de migrare recomandată
  7. Puncte cheie
  8. Testați-vă cunoștințele

Actualizat la 3 noiembrie 2026: Maparea parametrilor indica anterior că max_tokens își păstrează numele în API-ul Responses; tabelul xAI îl schimbă în max_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:

  • messages cu rolul system → instructions (parametru dedicat)
  • messages cu rolul user → input (șir simplu)
  • response.choices[0].message.content → response.output_text
  • max_tokens → max_output_tokens, conform tabelului de mapare xAI; temperature își păstrează numele
  • response.usage.prompt_tokens și completion_tokens → input_tokens și output_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:

  1. Identificați apelurile Chat Completions din codul dumneavoastră
  2. Clasificați-le după complexitate (bazic → streaming → apelare de funcții)
  3. Migrați mai întâi endpoint-urile sau funcționalitățile noi (greenfield)
  4. Apoi migrați apelurile existente cele mai simple
  5. 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).