Migrace z legacy systémů a osvědčené postupy
Na této stránce
Od chat/completions k responses
Mnoho produkčních integrací Grok stále spoléhá na /v1/chat/completions, často bez explicitního rozhodnutí: SDK od OpenAI už bylo nasazené, stačilo jen změnit base URL a klíč a vše fungovalo. Tato lekce tě provede přechodem na /v1/responses, což je hlavní endpoint, a následně rozšíří záběr o praktiky, které udrží integraci zdravou z dlouhodobého hlediska, ať už migruješ, nebo ne.
Proč opustit legacy endpoint
/v1/chat/completions je stále udržován a tvé požadavky budou nadále fungovat. Problémem není výpadek, ale stagnace: budoucí vývoj se soustředí výhradně na /v1/responses, opravy specifické pro legacy endpoint mají nižší prioritu a některé pokročilé funkce – agenti, nativní nástroje – tam prostě nejsou dostupné.
Pokud tedy tvoje aplikace dnes běží správně, není kam spěchat. Existuje však implicitní deadline: každá funkce, kterou budeš chtít v nadcházejících měsících adoptovat, bude vyžadovat provedenou migraci. Je lepší tuto práci zvládnout v klidu, než aby tě k ní donutila produktová potřeba.
Co se mezi dvěma endpointy mění
Legacy endpoint očekává klasický formát messages, který znáš:
# Legacy: /v1/chat/completions
payload = {
"model": "grok-4.20-0309",
"messages": [
{"role": "system", "content": "Instructions..."},
{"role": "user", "content": "Question"}
]
}
/v1/responses přijímá obohacený formát, který nativně podporuje nástroje, agenty a složité konverzační toky; podrobnosti najdeš v dokumentaci xAI. V praxi to má hlavní dopad na stranu klienta: pokud používáš OpenAI SDK pro komunikaci s Grok API, migrace může zahrnovat změnu SDK nebo přechod na nativní xAI SDK. Tento bod si ověř před odhadem pracnosti, protože často posune projekt z kategorie „nahraď URL“ do kategorie „nahraď závislost“.
Realizace migrace
Začni inventurou a ber ji vážně. Přímé HTTP volání se hledají snadno, ale API se málokdy volá z jednoho místa: SDK – OpenAI i nativní xAI – často koexistují ve stejném kódu, mezilehlé služby jako proxy nebo brány mohou přepisovat požadavky a dávkové skripty či datové pipeline žijí svým životem daleko od kódu aplikace. Právě na ty zapomeneš a právě ty se rozbijí tři týdny po migraci.
Poté migruj po malých částech, začínaje nejméně kritickými integracemi. Feature flag ti umožní přepínat jednu cestu kódu po druhé a co je klíčové, vrátit se zpět bez nutnosti nového nasazení:
# Feature flag for progressive migration
if feature_flags.get("use_responses_api"):
response = call_responses_api(prompt)
else:
response = call_chat_completions(prompt)
Tento flag dává smysl pouze tehdy, pokud zbytek tvého kódu ignoruje, který endpoint odpověděl. Odtud plyne třetí část nastavení: normalizační funkce, která vrátí oba formáty odpovědí do jedné struktury, aby migrace zůstala uzavřena v jedné vrstvě.
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"]
}
Praktiky, které přežijí migrace
Tato normalizační funkce ilustruje širší princip: izoluj svůj kód za abstraktní rozhraní, i když používáš pouze jednoho poskytovatele. To, co při změně endpointu, verze nebo poskytovatele nejvíce prodraží, není samotné volání, ale počet míst, která na něm závisí.
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
Dále loguj každé volání strukturovaným způsobem. Stačí pět metadatových bodů a hodnotu mají pouze společně: použitý model a jeho verze, počet vstupních tokenů, výstupních tokenů a tokenů obsloužených z cache, cena požadavku, latence – TTFT a celková doba trvání – a nakonec HTTP status kód. Bez těchto stop se incident kvality po migraci změní v debatu o pocitech. S nimi porovnáš dvě populace požadavků a rozhodneš se během deseti minut.
Nakonec si vytvoř sadu regresních testů pro své kritické prompty, kterou spustíš před jakoukoli změnou modelu nebo endpointu. Kontroluje tři odlišné věci: zda odpověď respektuje očekávaný formát (JSON nebo Markdown, podle případu), zda se tam skutečně objevují klíčové informace a zda tvá ochranná pravidla (guardrails) stále drží. Výkonnější model, který jemně obchází tvé bezpečnostní instrukce, představuje regresi, i když jeho odpovědi vypadají lépe.
V ustáleném stavu si zaslouží trvalý monitoring čtyři signály: míra chyb na endpoint a model, drift kvality měřený automatickým nebo lidským hodnocením, oznámení o ukončení podpory (deprecations) zveřejněná xAI a tvoje spotřeba vůči aktuálním limitům tvého tarifu. Poslední dva jsou jediné, které tě upozorní před incidentem, nikoliv až po něm.
Klíčové poznatky
- Endpoint
/v1/chat/completionsje legacy a již nepřijímá nové funkce - Migruj postupně na
/v1/responsespomocí feature flagů - Vytvoř abstraktní vrstvu pro normalizaci odpovědí mezi oběma endpointy
- V produkci používej připnuté verze, ve vývoji aliasy
- Udržuj regresní testy promptů a prováděj kontinuální monitoring
- Centralizuj konfiguraci modelů pro usnadnění budoucích migrací
Ověř si své znalosti
Tarify, tokeny, cache, životní cyklus: provozování Grok v produkci.
1. Jak se vyvíjejí limity rychlosti účtu?
Odpověď: Prostřednictvím automatických tierů: spotřeba zvyšuje RPM/TPM na model – a Enterprise vyjednává nad rámec; některé skoky mezi tiery jsou nevratné.
2. Jaké jsou čtyři typy účtovaných tokenů?
Odpověď: Vstupní, výstupní, reasoning tokeny a tokeny z cache (čtené z cache) – pole nákladů v odpovědi je detailně popisují, endpoint tokenize pomáhá s předpovědí.
3. Jak funguje automatická cache API?
Odpověď: Opakované prefixy jsou obsluhovány z cache za sníženou sazbu: udržování stabilních promptů na začátku požadavku maximalizuje úspěšnost zásahu cache – což je hlavní páka pro snížení nákladů.
4. Co potřebuješ vědět o životních cyklech modelů?
Odpověď: Aliasy (latest) sledují aktualizace, připnuté verze garantují reprodukovatelnost – pro každý use case si vybereš jedno nebo druhé a sleduješ ukončení podpory (deprecations).
5. Jak řešit migraci z legacy modelu?
Odpověď: Proveď inventuru využití, přepni se na aktuální řadu při opětovném testování kritických promptů, poté monitoruj náklady a kvalitu po přepnutí – migrace je projekt, nikoliv příkaz sed.
Když pochopíš limity, spočítáš tokeny, využiješ cache a spravuješ verze: klidný provoz stojí na těchto čtyřech disciplínách.