API kompatibilní s OpenAI: přechod na tři řádky

Tři řádky. Nasměruješ base_url klienta na nového poskytovatele, vyměníš API klíč a název modelu nahradíš názvem úrovně. Všechno ostatní ve volání chat completions, pole messages, streamování, nástroje, JSON schémata, zůstane přesně tak, jak je, protože kompatibilní s OpenAI znamená implementovat stejný HTTP kontrakt, ne se mu jen podobat.

Na migraci není zajímavý kód. Zajímavé je to, co se nepřenese: endpointy, které zatím neexistují, chování modelu, které se u stejného promptu posune, a jeden chybový kód, který jsi nejspíš nikdy neošetřoval.

Co „kompatibilní s OpenAI“ doopravdy znamená

Znamená to kontrakt jednoho endpointu: POST /v1/chat/completions, se stejným tělem požadavku a stejným tvarem odpovědi, včetně formátu server-sent events pro streamování. Tenhle kontrakt se stal výchozím rozhraním odvětví stejně, jako se API S3 stalo výchozím pro objektová úložiště, a ze stejného důvodu: všechno už bylo napsané proti němu.

Oficiální SDK jsou tencí klienti nad tím kontraktem. V pythonové knihovně od OpenAI je base URL argument konstruktoru, takže nasměrovat ji jinam je podporovaná operace, ne hack. Tvoje logika opakování, obsluha streamu i definice typů fungují dál.

Neznamená to ale shodu funkcí napříč celou platformou. Kompatibilní služby implementují chat endpoint dobře a za ním se rozcházejí, a proto je poctivá verze tohoto článku hlavně seznam rozdílů.

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,
)

Ty tři řádky v praxi

Tady je celá změna v Pythonu. SDK pro Node, Go a .NET berou stejné dva argumenty pod jinými názvy.

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,
)

Pokud tvůj kód už čte base URL z proměnné prostředí, což stojí za to udělat před jakoukoli migrací, jde o změnu konfigurace, ne o nasazení nového kódu. Zároveň tím máš ten nejlevnější možný rollback: nasměruj ji zpátky.

Co se přenese, co se změní a co chybí

Tabulka, kterou opravdu chceš mít, než práci naplánuješ.

Funkce	Stav	Co udělat
Chat completions	Funguje beze změny	Nic
Streamování (SSE)	Funguje beze změny	Vyžádej si usage ve streamu, ať je měření přesné
Function calling a nástroje	Stejné tvary	Znovu otestuj, který nástroj model vybere, ne jestli to umí
Strukturovaný výstup (JSON schéma)	Stejné tvary	Na své straně validuj dál, vždycky
Systémové prompty	Fungují	Počítej s doladěním formulací, ne struktury
Názvy modelů	Mění se	Použij úroveň: eu-lite, eu-standard, eu-long, eu-pro
Spotřeba a cena	Mění se	Čti hlavičky odpovědi místo dashboardu
Embeddingy, obrázky, řeč	Chybí	Na tohle si nech současného poskytovatele
Batch API	Chybí	Na roadmapě, zatím nevydané
Stavové API ve stylu Assistants	Chybí	Neplánuje se; stav drž na své straně

Tři z těch řádků jsou absence. Zveřejňujeme je jako seznam na hlavní stránce, místo abychom tě nechali je objevit uprostřed migrace, protože „kompatibilní“ je slovo, které vytahaly služby, jež implementují půlku kontraktu a prohlásí to za hotové.

Proč se z názvů modelů stávají názvy úrovní

Kupuješ úroveň, ne model. eu-standard je tahoun, eu-long zvládne milion tokenů kontextu, eu-pro je na náročné uvažování a každá odpovídá pojmenovanému open-weight modelu, který je i s licencí zveřejněný na stránce o transparentnosti AI.

Důvodem je obměna. Open-weight modely se mění každých pár měsíců a natvrdo zapsat dnešní název modelu do aplikace znamená nové nasazení pokaždé, když se obor pohne. Úroveň je slib o schopnostech a ceně, který přežije výměnu modelu pod ní, a když model vyměníme, řekneme to, místo abychom potichu změnili, co dělá tvůj kód.

Záleží i na licencích a jsou dost krátké na to, aby sis je přečetl. Většina toho, co provozujeme, je pod Apache 2.0 nebo MIT, a proto se stejné váhy vůbec smějí legálně poskytovat z evropského hardwaru.

Co se mění v odpovědích, ne v API

Tahle část týmy překvapuje, tak si na ni vyhraď čas. Změna poskytovatele je změna modelu a modely se liší způsoby, které žádná vrstva kompatibility neschová.

Formátování ujíždí. Prompt vyladěný tak, aby jeden model vracel čistý markdown, může u jiného vyprodukovat úvodní omáčku. Obvykle je to oprava na jeden řádek, ale je to oprava.

Úsudek při volání nástrojů se liší. Tvar volání funkce je stejný; ochota modelu ji zavolat ne. Existují modely, které volají až moc ochotně, i modely, které odpovídají z paměti.

Odmítání se liší. Některé open-weight modely se vyhýbají faktickým otázkám o politice nebo historii. Bereme to jako vadu, jednou přesměrujeme na model, který to slepé místo nemá, a v hlavičce X-EU-Routed ti řekneme, že jsme to udělali. Celé je to popsané na stránce o transparentnosti AI.

Praktická odpověď je testovací sada. Nech si dvacet skutečných požadavků s očekávanými výstupy, spusť je proti oběma poskytovatelům a rozdíly si přečti sám. Dvacet stačí na zachycení regresí ve formátování a výběru nástrojů a je to dost málo na to, abys to opravdu udělal.

Cena a měření po přechodu

Účtování po tokenech je všude stejná myšlenka, ale mění se, kde čísla čteš. Každá odpověď nese, kolik požadavek stál:

• X-EU-Tokens-In a X-EU-Tokens-Out, naměřené tokeny.
• X-EU-Cost-EUR, kolik se za tenhle požadavek odečetlo z tvého zůstatku.
• X-EU-Balance-EUR, kolik zbývá.
• X-EU-Model-Tier, která úroveň ho skutečně zpracovala.

Tvoje vlastní logy tak umí odpovědět na otázku ceny podle funkce, zákazníka i endpointu, bez čekání na měsíční fakturu, která s tebou nebude souhlasit. Sazby za těmi čísly najdeš na stránce s cenami a jak o ceně tokenů přemýšlet obecně, včetně toho, proč je výstup dražší než vstup, rozebírá článek kolik stojí AI API za token.

Jeden zvyk stojí za to přenést: nastav max_tokens u každého volání. Je to ta nejúčinnější kontrola nákladů v jakémkoli API účtovaném po tokenech a je to jeden řádek.

Chyby, limity a 402, kterou jsi neošetřil

Tvoje ošetření chyb nejspíš pokrývá 429 a 500. Předplacený kredit přidává ještě jednu.

1. 402, nedostatečný zůstatek. Požadavek se odmítne s odkazem na dobití, nic se dodatečně nefakturuje a tvůj zůstatek nikdy neklesne pod nulu. Ošetři to jako chybu autentizace: upozorni, neopakuj ve smyčce.
2. 429, rate limit nebo strop. Respektuj Retry-After. Stropy si nastavuješ sám, pro každý klíč, v eurech za den a za měsíc.
3. 502 a 503, upstream nedostupný. Opakuj s backoffem. Co se děje při výpadku a jaké omezení za tím stojí (jediný poskytovatel), popisuje stavová stránka.
4. Neúspěšné požadavky jsou zdarma. Pokud se nevrátila použitelná odpověď, z tvého zůstatku se nic neodečte, a požadavek přesměrovaný na slabší model se účtuje nižší z obou sazeb.

Strop pro nové účty jednou zaskočí každého: 25 € denně po prvních 48 hodin, bez ohledu na zůstatek. Existuje proto, že uniklý klíč první den je nejdražší chyba, jakou nová integrace udělá.

Udělá tě kompatibilita doopravdy přenositelným?

Zčásti, a stojí za to přesně říct, kterou částí. Kontrakt na drátě přenositelný je: jakoukoli službu, která mluví chat completions, můžeš vyměnit za stejným klientem. Už to samo odstraní nejhrubší formu lock-inu, tu, kdy odchod znamená přepsat celou integrační vrstvu.

Přenositelné není všechno, co jsi postavil nad konkrétním modelem. Prompty ladené celé měsíce, few-shot příklady vybrané kvůli zvláštnostem jednoho modelu, evaluační sady hodnocené podle výstupního stylu jednoho modelu a každý práh, který jsi nastavil podle toho, jak se ten model choval. Nic z toho se čistě nepřenese a nic z toho není vidět v diagramu architektury.

Ber proto model jako závislost s verzí, ne jako konstantu. Drž prompty v souborech, ne rozházené po kódu, testovací sadu drž v repozitáři a zapiš si, proč má práh právě tu hodnotu. Týmy, které to dělají, změní poskytovatele za odpoledne. Týmy, které ne, stráví čtvrtletí zjišťováním, co jejich prompty vlastně kompenzovaly.

Checklist migrace

Půl dne pro malou službu, sprint pro něco se skutečným provozem.

1. Přesuň base URL do konfigurace, pokud tam ještě není. Všechno níže je pak jednodušší.
2. Vyber úroveň podle zátěže, ne podle názvu. Klasifikace a extrakce patří na levnou úroveň; jen práce náročná na uvažování potřebuje tu drahou.
3. Sestav testovací sadu. Dvacet skutečných požadavků, očekávané výstupy, commitnuté do repozitáře.
4. Spusť oba poskytovatele vedle sebe na malém podílu provozu a porovnej výsledky.
5. Napoj hlavičky s cenou do toho, co už logueš.
6. Přidej větev pro 402, a když už jsi u toho, strop pro každý klíč.
7. Nech starého poskytovatele nakonfigurovaného ještě čtrnáct dní. Migraci, kterou vrátíš jednou změnou konfigurace, můžeš udělat v obyčejné úterý.

Proti kterému poskytovateli to vyhodnocení spustit, je samostatná otázka a čtyři realistické možnosti srovnává článek srovnání evropských poskytovatelů AI. Prvních deset požadavků je zdarma a minimální dobití je 10 €, takže vyhodnocení stojí méně než porada o tom, jestli ho dělat. Celý kontrakt, s curl a Pythonem ke zkopírování, je v dokumentaci API a kde se ty požadavky zpracovávají, krok za krokem, najdeš v článku kam jdou tvoje prompty.