API zgodne z OpenAI: przesiadka w trzech linijkach

Trzy linijki. Kierujesz base_url klienta na nowego dostawcę, podmieniasz klucz API i zastępujesz nazwę modelu nazwą tieru. Cała reszta wywołania chat completions, tablica wiadomości, streaming, narzędzia, schematy JSON, zostaje dokładnie taka, jaka była, bo zgodność z OpenAI oznacza implementację tego samego kontraktu HTTP, a nie tylko podobieństwo do niego.

Ciekawa część migracji to nie kod. To to, czego nie da się przenieść: endpointy, których jeszcze nie ma, zachowanie modelu, które zmienia się przy tym samym prompcie, i ten jeden kod błędu, którego twój kod najpewniej nie obsługuje.

Co właściwie znaczy „zgodne z OpenAI”

Chodzi o kontrakt jednego endpointu: POST /v1/chat/completions, z tym samym ciałem zapytania i tym samym kształtem odpowiedzi, łącznie z formatem server-sent events przy streamingu. Ten kontrakt stał się domyślnym interfejsem branży tak, jak API S3 stało się domyślnym dla przechowywania obiektów, i z tego samego powodu: wszystko było już pod niego napisane.

Oficjalne SDK to cienkie klienty nad tym kontraktem. W bibliotece OpenAI dla Pythona base URL to argument konstruktora, więc skierowanie go gdzie indziej to wspierana operacja, a nie obejście. Twoja logika ponawiania, obsługa streamingu i definicje typów działają dalej.

Nie oznacza to natomiast pełnej zgodności funkcji całej platformy. Zgodne usługi dobrze implementują endpoint czatu, a dalej się rozchodzą, dlatego uczciwa wersja tego tekstu to w dużej mierze lista rozbieżności.

from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ["UNION_API_KEY"],
    base_url="https://api.europeanailab.eu/v1",
)
 
response = client.chat.completions.create(
    model="eu-standard",
    messages=[{"role": "user", "content": prompt}],
    stream=True,
)

Trzy linijki w praktyce

Oto cała zmiana w Pythonie. SDK dla Node, Go i .NET przyjmują te same dwa argumenty pod innymi nazwami.

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["UNION_API_KEY"],
    base_url="https://api.europeanailab.eu/v1",
)

response = client.chat.completions.create(
    model="eu-standard",
    messages=[{"role": "user", "content": prompt}],
    stream=True,
)

Jeśli twój kod już czyta base URL ze zmiennej środowiskowej, co warto zrobić przed każdą migracją, to jest to zmiana konfiguracji, a nie wdrożenie nowego kodu. Daje ci to też najtańszy możliwy rollback: skieruj go z powrotem.

Co się przenosi, co się zmienia, czego brakuje

Tabela, której naprawdę potrzebujesz, zanim zaplanujesz pracę.

Funkcja	Status	Co zrobić
Chat completions	Działa bez zmian	Nic
Streaming (SSE)	Działa bez zmian	Poproś o zużycie w strumieniu, żeby rozliczenia były dokładne
Function calling i narzędzia	Te same kształty	Przetestuj ponownie, które narzędzie model wybiera, a nie czy potrafi
Ustrukturyzowane odpowiedzi (schemat JSON)	Te same kształty	Zawsze waliduj dalej po swojej stronie
Prompty systemowe	Działają	Spodziewaj się dostrajania sformułowań, nie struktury
Nazwy modeli	Zmieniają się	Użyj tieru: eu-lite, eu-standard, eu-long, eu-pro
Zużycie i koszt	Zmieniają się	Czytaj nagłówki odpowiedzi zamiast dashboardu
Embeddingi, obrazy, mowa	Brak	Do tego zostań przy obecnym dostawcy
Batch API	Brak	Na roadmapie, jeszcze niewdrożone
Stanowe API w stylu Assistants	Brak	Nie planujemy; trzymaj stan po swojej stronie

Trzy z tych wierszy to braki. Publikujemy je jako listę na stronie głównej, zamiast pozwolić ci odkryć je w połowie migracji, bo słowo „zgodne” mocno się wytarło przez usługi, które implementują połowę kontraktu i uznają sprawę za załatwioną.

Dlaczego nazwy modeli zamieniają się w nazwy tierów

Kupujesz tier, a nie model. eu-standard to koń pociągowy, eu-long przyjmuje 1 mln tokenów kontekstu, eu-pro to model do ciężkiego rozumowania, a każdy odpowiada konkretnemu modelowi open-weight, opublikowanemu razem z licencją na stronie o przejrzystości AI.

Powodem jest rotacja. Modele open-weight są zastępowane co kilka miesięcy, a wpisanie na sztywno dzisiejszej nazwy modelu do aplikacji oznacza nowe wdrożenie przy każdym ruchu na rynku. Tier to obietnica co do możliwości i ceny, która przetrwa wymianę modelu pod spodem, a gdy go wymieniamy, mówimy o tym, zamiast po cichu zmieniać to, co robi twój kod.

Licencje też mają znaczenie i są na tyle krótkie, że da się je przeczytać. Większość tego, co uruchamiamy, jest na licencji Apache 2.0 albo MIT, i dlatego te same wagi można w ogóle legalnie serwować z europejskiego sprzętu.

Co zmienia się w odpowiedziach, a nie w API

Ta część zaskakuje zespoły, więc zarezerwuj na nią czas. Zmiana dostawcy to zmiana modelu, a modele różnią się w sposób, którego żadna warstwa zgodności nie ukryje.

Formatowanie się rozjeżdża. Prompt dostrojony tak, żeby jeden model generował czysty markdown, na innym może dać wstęp przed odpowiedzią. Zwykle to poprawka w jednej linijce, ale to wciąż poprawka.

Ocena, kiedy wywołać narzędzie, jest inna. Kształt wywołania funkcji jest identyczny; gotowość modelu do jego wywołania już nie. Istnieją modele, które wywołują narzędzia zbyt chętnie, i takie, które odpowiadają z pamięci.

Odmowy są inne. Niektóre modele open-weight uchylają się od pytań o fakty z polityki czy historii. Traktujemy to jako wadę i raz przekierowujemy zapytanie do modelu bez tego martwego punktu, a w nagłówku X-EU-Routed informujemy, kiedy to zrobiliśmy. Pełny opis jest na stronie o przejrzystości AI.

Praktyczna odpowiedź to zestaw testowy. Zachowaj dwadzieścia prawdziwych zapytań z oczekiwanymi wynikami, puść je na obu dostawcach i osobiście przeczytaj różnice. Dwadzieścia wystarczy, by wyłapać regresje w formatowaniu i wyborze narzędzi, a jest to na tyle mało, że naprawdę to zrobisz.

Koszty i rozliczenia po zmianie

Cennik za token to wszędzie ten sam pomysł, ale zmienia się miejsce, w którym czytasz liczby. Każda odpowiedź niesie informację, ile kosztowało zapytanie:

• X-EU-Tokens-In i X-EU-Tokens-Out, rozliczone tokeny.
• X-EU-Cost-EUR, ile zeszło z twojego salda za to zapytanie.
• X-EU-Balance-EUR, ile zostało.
• X-EU-Model-Tier, który tier faktycznie je obsłużył.

Dzięki temu twoje własne logi odpowiadają na pytanie o koszt dla każdej funkcji, klienta i endpointu, bez czekania, aż miesięczna faktura się z tobą nie zgodzi. Stawki stojące za tymi liczbami są w cenniku, a to, jak w ogóle myśleć o koszcie tokenów, łącznie z tym, dlaczego wyjście jest droższe od wejścia, omawia tekst ile kosztuje API AI za token.

Jeden nawyk, który warto zabrać ze sobą: ustawiaj max_tokens przy każdym wywołaniu. To najskuteczniejsza pojedyncza kontrola kosztów w każdym API rozliczanym za tokeny, a zajmuje jedną linijkę.

Błędy, limity i 402, którego nie obsługujesz

Twoja obsługa błędów najpewniej obejmuje 429 i 500. Przedpłacony kredyt dodaje jeszcze jeden.

1. 402, niewystarczające saldo. Zapytanie zostaje odrzucone z linkiem do doładowania, nic nie jest fakturowane później, a twoje saldo nigdy nie spada poniżej zera. Obsłuż to jak błąd uwierzytelnienia: wyślij alert, nie ponawiaj w pętli.
2. 429, limit zapytań albo pułap. Respektuj Retry-After. Pułapy ustawiasz ty, dla każdego klucza, w euro dziennie i miesięcznie.
3. 502 i 503, usługa upstream niedostępna. Ponawiaj z backoffem. Co dzieje się podczas awarii i jakie ograniczenie jednego dostawcy za tym stoi, opisuje strona statusu.
4. Nieudane zapytania są darmowe. Jeśli nie wróciła użyteczna odpowiedź, nic nie schodzi z twojego salda, a zapytanie przekierowane do słabszego modelu jest rozliczane według niższej z dwóch stawek.

Pułap dla nowych kont zaskakuje ludzi raz: 25 € dziennie przez pierwsze 48 godzin, niezależnie od salda. Istnieje, bo klucz, który wycieknie pierwszego dnia, to najdroższy błąd, jaki może popełnić nowa integracja.

Czy zgodność naprawdę daje przenośność?

Częściowo i warto precyzyjnie powiedzieć, która część. Kontrakt na poziomie protokołu jest przenośny: każdą usługę mówiącą językiem chat completions można podpiąć za tym samym klientem. Już to usuwa najbardziej prymitywną formę uzależnienia od dostawcy, tę, w której odejście oznacza przepisanie warstwy integracji.

Nieprzenośne jest wszystko, co zbudowano na konkretnym modelu. Prompty dostrajane miesiącami, przykłady few-shot dobrane pod dziwactwa jednego modelu, zestawy ewaluacyjne oceniane według stylu wyjścia jednego modelu i każdy próg ustawiony na podstawie obserwacji jego zachowania. Nic z tego nie przenosi się czysto i nic z tego nie widać na diagramie architektury.

Traktuj więc model jak zależność z wersją, a nie jak stałą. Trzymaj prompty w plikach, a nie porozrzucane po kodzie, trzymaj zestaw testowy w repozytorium i zapisuj, dlaczego próg ma taką, a nie inną wartość. Zespoły, które tak robią, zmieniają dostawcę w jedno popołudnie. Zespoły, które tego nie robią, spędzają kwartał na odkrywaniu, co ich prompty kompensowały.

Lista kontrolna migracji

Pół dnia dla małej usługi, sprint dla czegoś z prawdziwym ruchem.

1. Przenieś base URL do konfiguracji, jeśli jeszcze go tam nie ma. Wszystko poniżej jest łatwiejsze, gdy to już działa.
2. Wybierz tier według obciążenia, a nie według nazwy. Klasyfikacja i ekstrakcja należą do taniego tieru; tylko praca wymagająca ciężkiego rozumowania potrzebuje drogiego.
3. Zbuduj zestaw testowy. Dwadzieścia prawdziwych zapytań, oczekiwane wyniki, zapisane w repozytorium.
4. Uruchom obu dostawców równolegle na małej części ruchu i porównaj wyniki.
5. Podłącz nagłówki kosztów do tego, co już logujesz.
6. Dodaj ścieżkę dla 402, a przy okazji pułap dla każdego klucza.
7. Zostaw starego dostawcę skonfigurowanego przez dwa tygodnie. Migrację, którą da się cofnąć jedną zmianą w konfiguracji, możesz przeprowadzić w zwykły wtorek.

Na którym dostawcy przeprowadzić tę ewaluację, to osobne pytanie, a cztery realistyczne opcje zestawia porównanie europejskich dostawców AI. Pierwsze dziesięć zapytań jest za darmo, a minimalne doładowanie to 10 €, więc ewaluacja kosztuje mniej niż spotkanie o tym, czy ją robić. Pełny kontrakt, z curl i Pythonem do skopiowania, jest w dokumentacji API, a to, gdzie te zapytania są przetwarzane, krok po kroku, opisuje tekst dokąd trafiają twoje prompty.