Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Vaiheittainen siirtyminen Responses APIiin

Oppitunti 12 / 12 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Miksi ja milloin siirtyä
  2. Vaihe 1: Tunnista käyttämäsi ominaisuudet
  3. Vaihe 2: Siirrä peruskutsut
  4. Vaihe 3: Siirrä monivaiheiset keskustelut
  5. Vaihe 4: Hyödynnä uusia ominaisuuksia
  6. Suositeltu siirtymästrategia
  7. Keskeiset asiat
  8. Testaa tietosi

Päivitetty 3. marraskuuta 2026: Parametrien kartoituksessa aiemmin ilmoitettiin, että max_tokens säilyttää nimensä Responses APIssa; xAI:n taulukko muuttaa sen muotoon max_output_tokens, ja käyttömittarit muuttavat myös nimiään. Lähde: Comparison with Chat Completions.

Miksi ja milloin siirtyä

Chat Completions -päätepiste on merkitty vanhentuneeksi. Se toimii edelleen, mutta siihen ei lisätä uusia ominaisuuksia. Jos sovelluksesi tarvitsee palvelinpuolen työkaluja (verkkohaku, koodin suoritus), keskustelujen tallennusta tai salattua päättelyä, siirtyminen Responses APIiin käy välttämättömäksi.

Hyvät uutiset: tämä siirtymä voi tapahtua vaiheittain. Sinun ei tarvitse kirjoittaa kaikkea uudelleen kerralla.

Vaihe 1: Tunnista käyttämäsi ominaisuudet

Ennen siirtymää käy läpi, mitä sovelluksesi käyttää Chat Completionsissa:

# 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

Peruskutsut ja suoratoisto ovat helpoimpia siirtää. Funktiokutsut vaativat muodon mukauttamista. Visio toimii samalla tavalla.

Vaihe 2: Siirrä peruskutsut

Yksinkertaisen kutsun siirtäminen noudattaa tätä kaavaa:

# 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

Kenttien kartoitus

Tärkeimmät muutokset ovat:

  • messages, jossa rooli system → instructions (erillinen parametri)
  • messages, jossa rooli user → input (yksinkertainen merkkijono)
  • response.choices[0].message.content → response.output_text
  • max_tokens → max_output_tokens xAI:n kartoitustaulukon mukaan; temperature säilyttää nimensä
  • response.usage.prompt_tokens ja completion_tokens → input_tokens ja output_tokens (tiedot: input_tokens_details.cached_tokens, output_tokens_details.reasoning_tokens)

Vaihe 3: Siirrä monivaiheiset keskustelut

Tässä Responses API yksinkertaistaa asioita. Historian uudelleenrakentamisen sijaan jokaisella pyynnöllä ketjutat ne ID:n avulla:

# 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

Koodi on yksinkertaisempaa, eikä sinun tarvitse enää hallita viestitaulukkoa manuaalisesti.

Vaihe 4: Hyödynnä uusia ominaisuuksia

Kun siirtymä on tehty, voit hyödyntää ominaisuuksia, jotka ovat yksinoikeudella Responses APIssa:

Sisäänrakennettu verkkohaku

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

Vastausten tallennus

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)

Salattu päättely

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

Suositeltu siirtymästrategia

Kaiken siirtämisen sijaan kerralla, etene vaiheittain:

  1. Tunnista koodistasi Chat Completions -kutsut
  2. Luokittele ne monimutkaisuuden mukaan (perus → suoratoisto → funktiokutsut)
  3. Siirrä ensin uudet päätepisteet tai ominaisuudet (vihreät kentät)
  4. Siirrä sitten yksinkertaisimmat olemassa olevat kutsut
  5. Pidä Chat Completions käytössä kolmansien osapuolten integraatioissa, jotka sitä vaativat (LangChain jne.)

Väliaikainen rinnakkaiselo

On täysin hyväksyttävää ajaa molempia päätepisteitä rinnakkain siirtymävaiheen aikana:

# 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

Tämä lähestymistapa antaa sinulle mahdollisuuden siirtyä vähitellen testaamalla jokaista siirtymää erikseen.

Keskeiset asiat

  • Siirtymä voi olla vaiheittainen: kaikkea ei tarvitse kirjoittaa uudelleen kerralla
  • Tärkeimmät muutokset: messages → input/instructions, choices[0].message.content → output_text
  • Monivaiheiset keskustelut siirtyvät viestitaulukosta yksinkertaiseen previous_response_id:hen
  • Responses API tarjoaa pääsyn yksinoikeudella oleviin ominaisuuksiin (web_search, tallennus, salattu päättely)
  • Aja molempia päätepisteitä rinnakkain siirtymän aikana ja siirry monimutkaisuusjärjestyksessä

Testaa tietosi

Vanhentunut API ymmärretty – ja siirtymä valmisteltu.

1. Mitä Chat Completionsin vanhentunut ja tilaton status tarkoittaa?

Vastaus: Päätepiste pysyy tuettuna, mutta se ei enää kehity: tilattomana se vaatii koko historian lähettämistä uudelleen jokaisella kutsulla – Responses API on moderni polku.

2. Mitkä roolit jäsentävät viestejä?

Vastaus: system (ja developer), user, assistant – puitteet, pyynnöt, vastaukset: koko historia alkaa alusta jokaisella pyynnöllä.

3. Miten käytät olemassa olevaa OpenAI-koodia Grokin kanssa?

Vastaus: Muuttamalla base_url osoitteeksi https://api.x.ai/v1 ja API-avaimen – muotoyhteensopivuus hoitaa loput, mukaan lukien OpenAI SDK ja Vercel AI SDK.

4. Mitä luet vastauksesta ja käytöstä?

Vastaus: choices sisältää vastaukset finish_reason-tietoineen; usage yksityiskohtaistaa tokenit, mukaan lukien reasoning_tokens päättelymalleille – perusta kustannusten seurannalle.

5. Miten siirryt puhtaasti Responses APIiin?

Vastaus: Vaiheittain: uusi kehitys Responsesissa, olemassa olevat päätepisteet muunnetaan yksi kerrallaan kehotteet uudelleentestaamalla – kahden muodon vertailu ohjaa muunnosta.

Ymmärrä vanhentunut, rakenna modernille: kurssin vaiheittainen siirtymäsuunnitelma on tiekarttasi – ilman suurta pamausta.