Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Migratsioon Responses API-le etapiviisiliselt

Õppetund 12 / 12 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Miks ja millal migratsiooni teha
  2. 1. samm: Tee kindlaks, milliseid funktsioone kasutad
  3. 2. samm: Migreeri põhikutsed
  4. 3. samm: Migreeri mitme vooruga vestlused
  5. 4. samm: Kasuta uusi funktsioone
  6. Soovitatav migratsioonistrateegia
  7. Peamised punktid
  8. Testi oma teadmisi

Uuendatud 3. novembril 2026: Parameetrite kaardistamine viitas varem, et max_tokens säilitab Responses API-s oma nime; xAI tabel muudab selle max_output_tokens-iks ja kasutusloendurite nimed muutuvad samuti. Allikas: Võrdlus Chat Completionsiga.

Miks ja millal migratsiooni teha

Chat Completionsi lõpp-punkt on märgitud iganenuks. See jätkab töötamist, kuid uusi funktsioone sellele enam ei lisata. Kui sinu rakendus vajab serveripoolseid tööriistu (veebiotsing, koodi täitmine), vestluse salvestamist või krüpteeritud arutluskäiku, muutub migratsioon Responses API-le vajalikuks.

Hea uudis: seda migratsiooni saab teha etapiviisiliselt. Sul pole vaja kõike korraga ümber kirjutada.

1. samm: Tee kindlaks, milliseid funktsioone kasutad

Enne migratsiooni tee ülevaade, mida sinu rakendus Chat Completionsiga kasutab:

# Auditeeri oma olemasolevat koodi
# Otsi neid mustreid:

# 1. Põhikutsed (lihtne tekst)
client.chat.completions.create(model=..., messages=...)

# 2. Voogedastus (Streaming)
client.chat.completions.create(..., stream=True)

# 3. Funktsioonide kutsumine
client.chat.completions.create(..., tools=[...])

# 4. Visioon (pildid)
# sõnumid sisuga massiivina [text, image_url]

# 5. Generatsiooni parameetrid
# temperature, max_tokens, top_p, stop, seed

Põhikutsed ja voogedastus on kõige lihtsamini migratavad. Funktsioonide kutsumine nõuab vormingu kohandamist. Visioon toimib sarnaselt.

2. samm: Migreeri põhikutsed

Lihtsa kutse migratsioon järgib seda mustrit:

# ENNE — 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

# PÄRAST — Responses API
response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    instructions="You are a helpful assistant.",
    input="Hello!"
)
texte = response.output_text

Väljade kaardistamine

Peamised muudatused on:

  • messages rolliga system → instructions (spetsiaalne parameeter)
  • messages rolliga user → input (lihtne string)
  • response.choices[0].message.content → response.output_text
  • max_tokens → max_output_tokens, vastavalt xAI kaardistamistabelile; temperature säilitab oma nime
  • response.usage.prompt_tokens ja completion_tokens → input_tokens ja output_tokens (üksikasjad: input_tokens_details.cached_tokens, output_tokens_details.reasoning_tokens)

3. samm: Migreeri mitme vooruga vestlused

Siin lihtsustab Responses API asju oluliselt. Ajaloo iga päringuga uuesti ülesehitamise asemel aheldad päringuid ID järgi:

# ENNE — Chat Completions (haldad ajalugu ise)
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

# PÄRAST — Responses API (server haldab ajalugu)
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

Kood on lihtsam ja sa ei pea enam sõnumite massiivi käsitsi haldama.

4. samm: Kasuta uusi funktsioone

Kui oled migratsiooni teinud, saad ära kasutada funktsioone, mis on eksklusiivsed Responses API-le:

Sisseehitatud veebiotsing

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What are the latest developments in generative AI?",
    tools=[{"type": "web_search"}]
)
# Vastus sisaldab viiteid allika URL-idega

Vastuste salvestamine

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Analyze this document...",
    store=True  # Säilitab 30 päeva
)

# Hiljem kättesaamine
stored = client.responses.retrieve(response.id)

Krüpteeritud arutluskäik

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Solve this complex problem...",
    include=["reasoning.encrypted_content"]
)
# Krüpteeritud arutluskäiku saab kasutada järgnevates päringutes

Soovitatav migratsioonistrateegia

Selle asemel, et kõike korraga migreerida, tegutse samm-sammult:

  1. Tuvasta Chat Completionsi kutsed oma koodis
  2. Liigita need keerukuse järgi (põhiline → voogedastus → funktsioonide kutsumine)
  3. Migreeri esmalt uued lõpp-punktid või funktsioonid (nn roheline väli)
  4. Seejärel migreeri lihtsaimad olemasolevad kutsed
  5. Jäta Chat Completions alles kolmandate osapoolte integratsioonide jaoks, mis seda nõuavad (LangChain jne)

Ajutine kooselu

On täiesti vastuvõetav käitada mõlemat lõpp-punkti ülemineku perioodil kõrvuti:

# Wrapper, mis abstrakteerib kasutatava lõpp-punkti
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

See lähenemine võimaldab sul järk-järgult üle minna, testides iga migratsiooni eraldi.

Peamised punktid

  • Migratsioon võib olla etapiviisiline: pole vaja kõike korraga ümber kirjutada
  • Peamised muudatused: messages → input/instructions, choices[0].message.content → output_text
  • Mitme vooruga vestlused liiguvad sõnumite massiivist lihtsale previous_response_id-le
  • Responses API annab juurdepääsu eksklusiivsetele funktsioonidele (web_search, salvestamine, krüpteeritud arutluskäik)
  • Käita ülemineku ajal mõlemat lõpp-punkti kõrvuti ja migreeri keerukuse järjekorras

Testi oma teadmisi

Pärand-API on mõistetud ja migratsiooniks valmistutud.

1. Mida tähendab Chat Completionsi staatuse „pärand“ ja „olekuta“?

Vastus: Lõpp-punkti toetatakse jätkuvalt, kuid see enam ei arene: olekuta olekus nõuab see iga kutsega kogu ajaloo uuesti saatmist – Responses API on kaasaegne tee.

2. Millised rollid struktureerivad sõnumeid?

Vastus: system (ja developer), user, assistant – raamistik, päringud, vastused: kogu ajaloo taaskäivitamine iga päringuga.

3. Kuidas kasutada olemasolevat OpenAI koodi Grokiga?

Vastus: Muutes base_url väärtuseks https://api.x.ai/v1 ja API võtme – vormingu ühilduvus hoolitseb ülejäänu eest, sealhulgas OpenAI SDK ja Vercel AI SDK puhul.

4. Mida loed vastuses ja kasutuses?

Vastus: choices kannab vastuseid koos finish_reasoniga; usage details sisaldab tokeneid, sealhulgas reasoning_tokens arutlusmudelite jaoks – kulude jälgimise alus.

5. Kuidas migratsioon Responses API-le puhtalt läbi viia?

Vastus: Etapiviisiliselt: uued arendused Responsesis, olemasolevad lõpp-punktid teisendatakse ükshaaval koos viibade uuesti testimisega – kahe vormingu võrdlemine juhendab teisendamist.

Mõista pärandit, ehita kaasaegset: kursuse etapiviisiline migratsiooniplaan on sinu teekaart – ilma suure pauguta.