Vaiheittainen siirtyminen Responses APIiin
Tällä sivulla
Päivitetty 3. marraskuuta 2026: Parametrien kartoituksessa aiemmin ilmoitettiin, että
max_tokenssäilyttää nimensä Responses APIssa; xAI:n taulukko muuttaa sen muotoonmax_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 roolisystem→instructions(erillinen parametri)messages, jossa rooliuser→input(yksinkertainen merkkijono)response.choices[0].message.content→response.output_textmax_tokens→max_output_tokensxAI:n kartoitustaulukon mukaan;temperaturesäilyttää nimensäresponse.usage.prompt_tokensjacompletion_tokens→input_tokensjaoutput_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:
- Tunnista koodistasi Chat Completions -kutsut
- Luokittele ne monimutkaisuuden mukaan (perus → suoratoisto → funktiokutsut)
- Siirrä ensin uudet päätepisteet tai ominaisuudet (vihreät kentät)
- Siirrä sitten yksinkertaisimmat olemassa olevat kutsut
- 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.