Stopniowa migracja do Responses API
Na tej stronie
Zaktualizowano 3 listopada 2026: Mapowanie parametrów wcześniej wskazywało, że
max_tokenszachowuje swoją nazwę w Responses API; tabela xAI zmienia ją namax_output_tokens, a nazwy liczników użycia również ulegają zmianie. Źródło: Porównanie z Chat Completions.
Dlaczego i kiedy migrować
Punkt końcowy Chat Completions został oznaczony jako przestarzały (legacy). Będzie nadal działał, ale nie zostaną do niego dodane nowe funkcje. Jeśli Twoja aplikacja wymaga narzędzi po stronie serwera (wyszukiwanie w sieci, wykonywanie kodu), przechowywania konwersacji lub szyfrowanego rozumowania, migracja do Responses API staje się konieczna.
Dobra wiadomość: migracja ta może odbywać się stopniowo. Nie musisz przepisywać wszystkiego naraz.
Krok 1: Zidentyfikuj używane funkcje
Przed migracją zrób przegląd tego, czego Twoja aplikacja używa w ramach Chat Completions:
# Audyt istniejącego kodu
# Szukaj tych wzorców:
# 1. Podstawowe wywołania (prosty tekst)
client.chat.completions.create(model=..., messages=...)
# 2. Strumieniowanie
client.chat.completions.create(..., stream=True)
# 3. Wywoływanie funkcji
client.chat.completions.create(..., tools=[...])
# 4. Wizja (obrazy)
# wiadomości z zawartością jako tablica [text, image_url]
# 5. Parametry generowania
# temperature, max_tokens, top_p, stop, seed
Podstawowe wywołania i strumieniowanie są najprostsze do migracji. Wywoływanie funkcji wymaga dostosowania formatu. Wizja działa podobnie.
Krok 2: Migruj podstawowe wywołania
Migracja prostego wywołania przebiega według tego schematu:
# PRZED — 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
# PO — Responses API
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="You are a helpful assistant.",
input="Hello!"
)
texte = response.output_text
Mapowanie pól
Główne zmiany to:
messagesz roląsystem→instructions(dedykowany parametr)messagesz roląuser→input(prosty ciąg znaków)response.choices[0].message.content→response.output_textmax_tokens→max_output_tokens, zgodnie z tabelą mapowania xAI;temperaturezachowuje swoją nazwęresponse.usage.prompt_tokensicompletion_tokens→input_tokensioutput_tokens(szczegóły:input_tokens_details.cached_tokens,output_tokens_details.reasoning_tokens)
Krok 3: Migruj konwersacje wielowątkowe
To właśnie tutaj Responses API upraszcza sprawę. Zamiast rekonstruować historię przy każdym żądaniu, łączysz je za pomocą identyfikatora:
# PRZED — Chat Completions (zarządzaj historią samodzielnie)
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
# PO — Responses API (serwer zarządza historią)
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
Kod jest prostszy i nie musisz już ręcznie zarządzać tablicą wiadomości.
Krok 4: Wykorzystaj nowe funkcje
Po migracji możesz skorzystać z funkcji dostępnych wyłącznie w Responses API:
Wbudowane wyszukiwanie w sieci
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the latest developments in generative AI?",
tools=[{"type": "web_search"}]
)
# Odpowiedź zawiera cytaty z adresami URL źródeł
Przechowywanie odpowiedzi
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Analyze this document...",
store=True # Przechowuje przez 30 dni
)
# Pobierz później
stored = client.responses.retrieve(response.id)
Szyfrowane rozumowanie
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Solve this complex problem...",
include=["reasoning.encrypted_content"]
)
# Szyfrowane rozumowanie może być ponownie wykorzystane w kolejnych żądaniach
Zalecana strategia migracji
Zamiast migrować wszystko naraz, działaj etapami:
- Zidentyfikuj wywołania Chat Completions w swoim kodzie
- Skategoryzuj je według złożoności (podstawowe → strumieniowanie → wywoływanie funkcji)
- Zmigruj najpierw nowe punkty końcowe lub funkcje (greenfield)
- Następnie migruj najprostsze istniejące wywołania
- Zachowaj Chat Completions dla integracji zewnętrznych, które tego wymagają (LangChain itp.)
Tymczasowa koegzystencja
Całkowicie dopuszczalne jest uruchamianie obu punktów końcowych obok siebie podczas przejścia:
# Wrapper abstrahujący używany punkt końcowy
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
Podejście to pozwala na stopniowe przełączanie się, testując każdą migrację indywidualnie.
Kluczowe wnioski
- Migracja może być stopniowa: nie trzeba przepisywać wszystkiego naraz
- Główne zmiany:
messages→input/instructions,choices[0].message.content→output_text - Konwersacje wielowątkowe przechodzą z tablicy wiadomości na prosty parametr
previous_response_id - Responses API daje dostęp do ekskluzywnych funkcji (web_search, storage, encrypted reasoning)
- Uruchamiaj oba punkty końcowe obok siebie podczas przejścia i migruj według stopnia złożoności
Sprawdź swoją wiedzę
Przestarzałe API zrozumiane – migracja przygotowana.
1. Co oznacza status legacy i bezstanowości Chat Completions?
Odpowiedź: Punkt końcowy pozostaje wspierany, ale nie rozwija się już dalej: będąc bezstanowym, wymaga ponownego wysyłania całej historii przy każdym wywołaniu – Responses API to nowoczesna ścieżka.
2. Jakie role strukturyzują wiadomości?
Odpowiedź: system (oraz developer), user, assistant – ramy, żądania, odpowiedzi: pełna historia restartuje się przy każdym żądaniu.
3. Jak użyć istniejącego kodu OpenAI z Grok?
Odpowiedź: Zmieniając base_url na https://api.x.ai/v1 oraz klucz API – kompatybilność formatu zajmuje się resztą, w tym SDK OpenAI i Vercel AI SDK.
4. Co odczytujesz w odpowiedzi i użyciu?
Odpowiedź: choices przenosi odpowiedzi z finish_reason; usage szczegółowo opisuje tokeny, w tym reasoning_tokens dla modeli rozumujących – baza do śledzenia kosztów.
5. Jak czysto migrować do Responses API?
Odpowiedź: Stopniowo: nowe разработки w Responses, istniejące punkty końcowe konwertowane jeden po drugim z ponownym testowaniem promptów – porównanie obu formatów kieruje konwersją.
Zrozum przestarzałe rozwiązania, buduj pod nowoczesne: plan stopniowej migracji z tego kursu to Twoja mapa drogowa – bez wielkiego wybuchu.