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

Migracja z wersji legacy i najlepsze praktyki

Lekcja 14 z 14 Zaktualizowano 29 lipca 2026 Zaawansowany
Na tej stronie
  1. Od chat/completions do responses
  2. Dlaczego warto odejść od punktu końcowego legacy
  3. Co zmienia się między tymi punktami końcowymi
  4. Przeprowadzanie migracji
  5. Praktyki, które przetrwają migracje
  6. Kluczowe wnioski
  7. Sprawdź swoją wiedzę

Od chat/completions do responses

Wiele produkcyjnych integracji Grok nadal opiera się na /v1/chat/completions, często bez świadomej decyzji: SDK OpenAI było już wdrożone, wystarczyło zmienić bazowy URL i klucz, aby wszystko działało. Ta lekcja przeprowadzi Cię przez przejście na /v1/responses, czyli główny punkt końcowy, a następnie rozszerzy zakres o praktyki, które utrzymają integrację w dobrej kondycji w długim terminie, niezależnie od migracji.

Dlaczego warto odejść od punktu końcowego legacy

/v1/chat/completions jest nadal utrzymywany i Twoje żądania będą dalej działać. Problemem nie jest awaria, lecz stagnacja: przyszły rozwój koncentruje się wyłącznie na /v1/responses, poprawki specyficzne dla punktu końcowego legacy mają niższy priorytet, a pewne zaawansowane funkcje – agenci, narzędzia natywne – są tam po prostu niedostępne.

Nie ma więc pilności, jeśli Twoja aplikacja działa dziś poprawnie. Istnieje jednak niepisany termin: każda funkcja, którą zechcesz wdrożyć w nadchodzących miesiącach, będzie wymagała migracji. Lepiej wykonać tę pracę na spokojnie, niż gdy wymusi ją potrzeba produktowa.

Co zmienia się między tymi punktami końcowymi

Punkt końcowy legacy oczekuje klasycznego formatu messages, który znasz:

# Legacy: /v1/chat/completions
payload = {
    "model": "grok-4.20-0309",
    "messages": [
        {"role": "system", "content": "Instructions..."},
        {"role": "user", "content": "Question"}
    ]
}

/v1/responses przyjmuje wzbogacony format, który natywnie obsługuje narzędzia, agentów i złożone przepływy konwersacyjne; szczegóły znajdziesz w dokumentacji xAI. W praktyce główna konsekwencja dotyczy strony klienta: jeśli używasz SDK OpenAI do komunikacji z API Grok, migracja może wymagać zmiany SDK lub przejścia na natywne SDK xAI. Sprawdź ten punkt przed oszacowaniem nakładu pracy, ponieważ często zmienia to projekt z „zamiany URL-a“ na „zamianę zależności“.

Przeprowadzanie migracji

Zacznij od inwentaryzacji i potraktuj ją poważnie. Bezpośrednie wywołania HTTP łatwo znaleźć, ale API rzadko jest wywoływane z jednego miejsca: SDK – OpenAI, natywne xAI – często współistnieją w tej samej bazie kodu, usługi pośrednie, takie jak proxy lub bramy, mogą przepisywać żądania, a skrypty wsadowe czy potoki danych żyją swoim życiem z dala od kodu aplikacji. To właśnie o nich zapominasz i to one psują się trzy tygodnie po migracji.

Następnie migruj małymi krokami, zaczynając od najmniej krytycznych integracji. Flaga funkcji (feature flag) pozwala przełączać jedną ścieżkę kodu na raz i, co kluczowe, cofnąć zmiany bez ponownego wdrażania:

# Feature flag for progressive migration
if feature_flags.get("use_responses_api"):
    response = call_responses_api(prompt)
else:
    response = call_chat_completions(prompt)

Ta flaga ma sens tylko wtedy, gdy reszta kodu ignoruje, który punkt końcowy odpowiedział. Stąd trzeci element konfiguracji: funkcja normalizująca, która sprowadza oba formaty odpowiedzi do jednej struktury, dzięki czemu migracja pozostaje ograniczona do jednej warstwy.

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"]
        }

Praktyki, które przetrwają migracje

Ta funkcja normalizująca ilustruje szerszą zasadę: odizoluj swój kod za pomocą abstrakcyjnego interfejsu, nawet jeśli używasz tylko jednego dostawcy. To, co podczas zmiany punktu końcowego, wersji lub dostawcy kosztuje najwięcej, to nie samo wywołanie, lecz liczba miejsc, które od niego zależą.

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

Następnie loguj każde wywołanie w sposób ustrukturyzowany. Wystarczy pięć punktów metadanych, a wartość mają tylko razem: użyty model i jego wersja, liczba tokenów wejściowych, wyjściowych i obsłużonych z cache, koszt żądania, opóźnienie – TTFT i całkowity czas trwania – oraz na koniec kod statusu HTTP. Bez tych śladów incydent jakościowy po migracji staje się debatą opartą na wrażeniach. Dzięki nim porównujesz dwie populacje żądań i podejmujesz decyzję w dziesięć minut.

Na koniec zbuduj zestaw testów regresyjnych dla swoich krytycznych promptów, do uruchamiania przed każdą zmianą modelu lub punktu końcowego. Sprawdza on trzy różne rzeczy: czy odpowiedź respects oczekiwany format (JSON lub Markdown, w zależności od przypadku), czy kluczowe informacje faktycznie się w niej pojawiają, oraz czy Twoje guardrails nadal działają. Model wydajniejszy, który subtelnie omija Twoje instrukcje bezpieczeństwa, stanowi regresję, nawet jeśli jego odpowiedzi wydają się lepsze.

W stanie ustalonym cztery sygnały zasługują na stały monitoring: wskaźnik błędów na punkt końcowy i model, dryf jakości mierzony oceną automatyczną lub ludzką, komunikaty o wycofaniu (deprecation) publikowane przez xAI oraz Twoje zużycie względem obecnych limitów poziomu (tier). Dwa ostatnie to jedyne, które ostrzegają Cię przed incydentem, a nie po nim.

Kluczowe wnioski

  • Punkt końcowy /v1/chat/completions jest wersją legacy i nie otrzymuje już nowych funkcji
  • Migruj stopniowo do /v1/responses, używając flag funkcji
  • Stwórz warstwę abstrakcji, aby normalizować odpowiedzi między tymi dwoma punktami końcowymi
  • Używaj przypiętych wersji w produkcji i aliasów w środowisku deweloperskim
  • Utrzymuj testy regresyjne promptów i ciągły monitoring
  • Centralizuj konfigurację modeli, aby ułatwić przyszłe migracje

Sprawdź swoją wiedzę

Poziomy, tokeny, cache, cykl życia: operowanie Grok w produkcji.

1. Jak ewoluują limity szybkości konta?

Odpowiedź: Poprzez automatyczne poziomy: zużycie podnosi RPM/TPM na model – a Enterprise negocjuje ponad to; niektóre skoki poziomów są nieodwracalne.

2. Jakie są cztery rodzaje rozliczanych tokenów?

Odpowiedź: Tokeny wejściowe, wyjściowe, rozumowania i cache (odczytane z pamięci podręcznej) – pola kosztu odpowiedzi szczegółowo je opisują, punkt końcowy tokenize pomaga w prognozowaniu.

3. Jak działa automatyczny cache API?

Odpowiedź: Powtarzające się prefiksy są obsługiwane z cache po obniżonej stawce: utrzymanie stabilności promptów na początku żądania maksymalizuje współczynnik trafień cache – to główny dźwignia kosztów.

4. Co musisz wiedzieć o cyklach życia modeli?

Odpowiedź: Aliasy (latest) podążają za aktualizacjami, przypięte wersje gwarantują powtarzalność – wybierasz jedno lub drugie w zależności od przypadku użycia i śledzisz wycofania.

5. Jak przeprowadzić migrację z modelu legacy?

Odpowiedź: Sporządź inwentaryzację użycia, przełącz się na aktualny zakres, ponownie testując krytyczne prompty, a następnie monitoruj koszty i jakość po zmianie – migracja to projekt, a nie polecenie sed.

Gdy zrozumiesz limity, policzysz tokeny, wykorzystasz cache i zarządzasz wersjami: spokojne operacje opierają się na tych czterech dyscyplinach.