Przejdź do głównej treści
Polski— Wybierz język
Menu

Stopniowa migracja do Responses API

Lekcja 12 z 12 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Dlaczego i kiedy migrować
  2. Krok 1: Zidentyfikuj używane funkcje
  3. Krok 2: Migruj podstawowe wywołania
  4. Krok 3: Migruj konwersacje wielowątkowe
  5. Krok 4: Wykorzystaj nowe funkcje
  6. Zalecana strategia migracji
  7. Kluczowe wnioski
  8. Sprawdź swoją wiedzę

Zaktualizowano 3 listopada 2026: Mapowanie parametrów wcześniej wskazywało, że max_tokens zachowuje swoją nazwę w Responses API; tabela xAI zmienia ją na max_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:

  • messages z rolą system → instructions (dedykowany parametr)
  • messages z rolą user → input (prosty ciąg znaków)
  • response.choices[0].message.content → response.output_text
  • max_tokens → max_output_tokens, zgodnie z tabelą mapowania xAI; temperature zachowuje swoją nazwę
  • response.usage.prompt_tokens i completion_tokens → input_tokens i output_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:

  1. Zidentyfikuj wywołania Chat Completions w swoim kodzie
  2. Skategoryzuj je według złożoności (podstawowe → strumieniowanie → wywoływanie funkcji)
  3. Zmigruj najpierw nowe punkty końcowe lub funkcje (greenfield)
  4. Następnie migruj najprostsze istniejące wywołania
  5. 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.