Migration från äldre system och bästa praxis
På denna sida
Från chat/completions till responses
Många produktionsintegrationer med Grok förlitar sig fortfarande på /v1/chat/completions, ofta utan ett aktivt val: OpenAI SDK fanns redan på plats, du behövde bara byta bas-URL och nyckel så fungerade allt. Den här lektionen guidar dig genom bytet till /v1/responses, den primära slutpunkten, och vidgar sedan perspektivet till metoder som håller en integration frisk över tid, oavsett migration.
Varför lämna den äldre slutpunkten
/v1/chat/completions underhålls fortfarande och dina förfrågningar kommer att fortsätta fungera. Problemet är inte driftstopp, utan stagnation: framtida utveckling fokuserar uteslutande på /v1/responses, felrättningar specifika för den äldre slutpunkten prioriteras lägre, och vissa avancerade funktioner – agenter, inbyggda verktyg – är helt enkelt inte tillgängliga där.
Det finns alltså ingen akut brådska om din applikation fungerar korrekt idag. Det finns dock en implicit deadline: varje funktion du vill införa under de kommande månaderna kommer att kräva att du har migrerat. Det är bättre att hantera detta arbete i lugn och ro än när ett produktbehov tvingar fram det.
Vad som skiljer sig mellan de två slutpunkterna
Den äldre slutpunkten förväntar sig det klassiska messages-formatet du känner till:
# Legacy: /v1/chat/completions
payload = {
"model": "grok-4.20-0309",
"messages": [
{"role": "system", "content": "Instructions..."},
{"role": "user", "content": "Question"}
]
}
/v1/responses använder ett berikat format som nativt stöder verktyg, agenter och komplexa konversationsflöden; xAI:s dokumentation ger detaljerna. I praktiken är den viktigaste konsekvensen på klientsidan: om du använder OpenAI SDK för att kommunicera med Grok API kan migrationen innebära att du måste byta SDK eller växla till det nativa xAI SDK. Kontrollera denna punkt innan du uppskattar arbetsinsatsen, eftersom det ofta flyttar projektet från “byta en URL” till “byta ett beroende”.
Genomföra migrationen
Börja med en inventering, och ta den på allvar. Direkta HTTP-anrop är lätta att hitta, men API:et anropas sällan från ett enda ställe: SDK:n – OpenAI, nativ xAI – samexisterar ofta i samma kodbas, mellanliggande tjänster som proxyar eller gateways kan skriva om förfrågningar, och batch-skript eller datapipelines lever sina egna liv långt från applikationskoden. Det är dessa du glömmer, och det är dessa som slutar fungera tre veckor efter migrationen.
Migrera sedan i små bitar, börja med de minst kritiska integrationerna. En funktionsflagga låter dig växla en kodväg i taget och, vilket är avgörande, rulla tillbaka utan ny distribution:
# Feature flag for progressive migration
if feature_flags.get("use_responses_api"):
response = call_responses_api(prompt)
else:
response = call_chat_completions(prompt)
Denna flagga är bara meningsfull om resten av din kod struntar i vilken slutpunkt som svarade. Därför kommer den tredje delen av setupen: en normaliseringsfunktion som får båda svarsformaten att återgå till en enda struktur, så att migrationen hålls begränsad till ett enda lager.
def normalize_response(raw_response, endpoint):
"""Normalizes responses regardless of the endpoint used."""
if endpoint == "responses":
return {
"content": raw_response["output"]["content"],
"usage": raw_response["usage"]
}
else: # chat/completions
return {
"content": raw_response["choices"][0]["message"]["content"],
"usage": raw_response["usage"]
}
Metoder som överlever migrationer
Denna normaliseringsfunktion illustrerar en bredare princip: isolera din kod bakom ett abstrakt gränssnitt, även om du bara använder en leverantör. Det som kostar dyrt vid ett byte av slutpunkt, version eller leverantör är aldrig själva anropet, utan antalet platser som beror på det.
class ClientLLM:
def completer(self, messages, model=None):
"""Abstract interface for LLM calls."""
raise NotImplementedError
class ClientGrok(ClientLLM):
def completer(self, messages, model=None):
model = model or GROK_MODEL
# Grok-specific implementation
pass
Logga sedan varje anrop på ett strukturerat sätt. Fem metadatapunkter räcker, och de har bara värde tillsammans: modellen som användes och dess version, antalet tokens för indata, utdata och de som serverades från cache, kostnaden för förfrågan, latens – TTFT och total varaktighet – och slutligen HTTP-statuskoden. Utan dessa spår blir en kvalitetsincident efter migrationen en debatt om känslor. Med dem jämför du två populationer av förfrågningar och avgör saken på tio minuter.
Bygg slutligen en regressionstestsvit för dina kritiska prompts, att köra innan varje byte av modell eller slutpunkt. Den kontrollerar tre distinkta saker: att svaret respekterar det förväntade formatet, JSON eller Markdown beroende på fall; att nyckelinformation faktiskt finns där; och att dina skyddsräcken fortfarande håller. En mer prestandaoptimerad modell som subtilt kringgår dina säkerhetsinstruktioner är en regression, även om dess svar verkar bättre.
I stabilt läge förtjänar fyra signaler permanent övervakning: felraten per slutpunkt och per modell, kvalitetsavdrift mätt genom automatisk eller mänsklig utvärdering, aviserade avvecklingar publicerade av xAI, och din konsumtion i relation till dina nuvarande nivågränser. De två sista är de enda som varnar dig före incidenten snarare än efter.
Viktiga punkter
- Slutpunkten
/v1/chat/completionsär föråldrad och får inga nya funktioner - Migrera progressivt till
/v1/responsesmed hjälp av funktionsflaggor - Skapa ett abstraktionslager för att normalisera svar mellan de två slutpunkterna
- Använd låsta versioner i produktion och alias i utveckling
- Underhåll regressionstester för prompts och kontinuerlig övervakning
- Centralisera modellkonfiguration för att underlätta framtida migrationer
Testa dina kunskaper
Nivåer, tokens, cache, livscykel: att driva Grok i produktion.
1. Hur utvecklas kontots hastighetsbegränsningar?
Svar: Via automatiska nivåer: konsumtion driver upp RPM/TPM per modell – och Enterprise förhandlar utöver detta; vissa nivåhopp är oåterkalleliga.
2. Vilka är de fyra typerna av debiterade tokens?
Svar: Indata, utdata, resonemang och cachade tokens (lästa från cache) – fält för svarskostnad specificerar dessa, slutpunkten för tokenisering hjälper till att prognostisera.
3. Hur fungerar API:ets automatiska cache?
Svar: Upprepade prefix serveras från cache till en reducerad kostnad: att hålla prompts stabila i början av förfrågan maximerar cacheläsningarna – en viktig hävstång för kostnaderna.
4. Vad behöver du veta om modellivscykler?
Svar: Alias (latest) följer uppdateringar, låsta versioner garanterar reproducerbarhet – du väljer det ena eller det andra beroende på användningsfall, och håller koll på avvecklingar.
5. Hur hanterar man en migration från en äldre modell?
Svar: Inventera användningen, växla till det aktuella utbudet medan du testar om kritiska prompts, och övervaka sedan kostnader och kvalitet efter bytet – migration är ett projekt, inte en sed-kommando.
Med förståelse för begränsningar, räknade tokens, utnyttjad cache och hanterade versioner: stabil drift vilar på dessa fyra discipliner.