Migrera till en OpenAI-kompatibel API-gateway: Skapa ett kompatibilitetskontrakt innan du vänder baswebbadressen

Att ändra base_url, api_key och model är ofta tillräckligt för att få en enkel chattdemo att fungera mot en OpenAI-kompatibel API. Det räcker inte att bevisa att en produktionsmigrering är säker.

Festen uppträder vanligtvis senare: strömmade verktygsanrop anländer i en annan form, ett JSON-schemaläge ignoreras, en inbäddningsmodell returnerar en annan vektorstorlek, användningsfält saknas, återförsök dubbelskicka en bieffekt eller ett leverantörsspecifikt resonemangsalternativ gör ingenting tyst. Det praktiska målet är inte att fråga om en slutpunkt är "OpenAI kompatibel" i abstraktet. Målet är att definiera vilka delar av det OpenAI-formade kontraktet dina applikationer är beroende av, testa dessa delar och dirigera genom en gateway först efter att kontraktet är explicit.

Den här guiden visar hur man migrerar ett team från leverantörsspecifika SDK:er eller spridda kompatibla slutpunkter till en OpenAI-kompatibel gateway samtidigt som tillförlitlighet, användningstillskrivning och återställningsalternativ bevaras.

Vad är fakta, rekommendationer och förutsägelser i den här migreringen?

Fakta: Flera leverantörer dokumenterar OpenAI-kompatibla sökvägar eller SDK användning för delar av sina API:er. Google dokument Gemini åtkomst genom OpenAI Python och TypeScript-bibliotek och REST genom att ändra API-nyckeln, basadress och modell, samtidigt som man rekommenderar direkt Gemini API-användning för program som inte redan använder OpenAI-bibliotek. Geminis kompatibilitetsdokumentation omfattar chattslutföranden, streaming, funktionsanrop, bildförståelse, inbäddningar, resonemang-ansträngningsmappningar och leverantörsspecifika alternativ genom extra förfrågningsorgan. Tillsammans dokumenterar AI OpenAI REST och SDK kompatibilitet för flera modaliteter, men dess matris listar också OpenAI-formade ytor som inte stöds som assistenter, trådar och körningar. Mistral dokumenterar en migreringsväg för OpenAI-kompatibla klienter genom att ändra basadress och modellnamn. Groq avslöjar OpenAI-vägs slutpunkter för chattslut. vLLM erbjuder en OpenAI-kompatibel server för kompletteringar och chatt, samtidigt som parameterskillnader dokumenteras. Dokumentationen OpenAI Agents SDK varnar för att många icke-OpenAI leverantörer ännu inte stöder de nyare svaren API och att Chat Completions-läget ofta är det säkrare kompatibilitetsmålet.

Rekommendationer: Behandla kompatibilitet som ett testat ansökningskontrakt. Inventera de exakta slutpunkterna och funktionerna som dina appar använder, skapa en leverantörs- och modellkapacitetsmatris, skriv överensstämmelsetester före trafikmigrering, normalisera kända förfrågnings- och svarsskillnader vid gatewaygränsen och rulla ut med nycklar per applikation och återställningsprofiler.

Förutsägelse: OpenAI-kompatibla ytor förblir användbara som ett integrationslager med lägsta friktion, men leverantörsbaserade funktioner kommer att fortsätta att skilja sig åt. Team som upprätthåller ett kompatibilitetskontrakt kommer att kunna anta nya modeller snabbare än team som förlitar sig på informella antaganden om "drop-in-ersättning".

Steg 1: inventera varje aktuellt AI-samtal

Börja med en inventering, inte kodändringar. En migrering misslyckas när team antar att alla AI-anrop ser ut som chattslut och upptäcker dolda beroenden först efter release.

Skapa en rad per samtalswebbplats. Inkludera schemalagda jobb, interna verktyg, anteckningsböcker, bakgrundsarbetare, eval-selar och kundinriktade tjänster.

app: support-assistant
owner: customer-platform
current_provider: provider_a
current_sdk: provider_a_python_sdk
endpoint_shape: chat.completions
model: provider-a-large-2026
features:
  - streaming
  - tool_calls
  - json_schema_output
  - usage_accounting
latency_budget_ms: 8000
retry_policy: retry_429_5xx_no_tool_side_effects
monthly_volume_estimate: 2.4M requests
rollback_contact: oncall-customer-platform

Klassificera varje samtal efter slutpunkt och funktion, inte bara efter modell. Ett enda modellnamn kan dölja mycket olika kompatibilitetskrav beroende på hur det används.

Inventeringschecklista

• Chatt: meddelanden, systeminstruktioner, temperatur, top-p, max tokens, stoppsekvenser.
• Streaming: serversända händelseparser, sista bitar, användning i stream, avbrytningsbeteende.
• Verktyg: funktionsscheman, parallella anrop, argument JSON, verktygsresultatmeddelanden, biverkningssäkerhet.
• Strukturerade utdata: JSON-läge, JSON-schema, strikt validering, reservreparationslogik.
• Vision eller multimodal input: bildadress, base64, MIME-hantering, detaljparametrar.
• Inbäddningar: modell-ID, vektordimension, normaliseringsförväntningar, indexkompatibilitet.
• Filer och batch: ladda upp API:er, jobbundersökningar, annullering, utdataformat.
• Resoneringskontroller: resonemang, tankebudget, dolda tokens, leverantörsspecifika inställningar.
• Fel: hastighetsgränsform, timeoutform, innehållspolicyfel, statuskoder som går att försöka igen.
• Användning och fakturering: prompttokens, slutförandetokens, cachade tokens, resonemangstokens, kostnadsfördelningstaggar.

Utdata från detta steg är en beroendekarta. Den talar om vilka appar som kan migrera med en enkel OpenAI-kompatibel API profil och vilka appar som behöver adapterarbete.

Steg 2: Skapa en kompatibilitetsavtalstabell

Ett kompatibilitetskontrakt är en tabell som säger, för varje programfunktion, vad gatewayen måste garantera och hur du ska testa den. Det bör vara tillräckligt specifikt för teknik- och produktteam att fatta beslut om lansering.

Denna tabell förhindrar också överlöfte. Om en leverantör stöder chatt och inbäddningar men inte ett fil- eller assistentliknande arbetsflöde, ska det stå i kontraktet. "Unsupported" är ett giltigt migreringsresultat när det undviker en produktionsöverraskning.

Steg 3: skapa modellprofiler istället för att sprida modell-ID:n

Ersätt inte ett hårdkodat modell-ID med ett annat hårdkodat modell-ID i varje app. Använd modellprofiler.

profile: support-chat-fast
openai_model_alias: support-chat-fast
provider: provider_b
provider_model: provider-b/chat-large-fast
endpoint: chat.completions
features:
  streaming: true
  tools: true
  structured_outputs: schema_validated
  vision: false
  embeddings: false
request_policy:
  drop_unsupported_params: false
  reject_unknown_params: true
  pass_through_extra_body: ["reasoning_effort"]
fallback_profile: support-chat-safe
cost_center_required: true

Den här profilen ger applikationer ett stabilt namn medan gatewayen äger leverantörsmapping. Den hanterar också leverantörer som använder namnavgränsade modell-ID:n snarare än ett platt modellnamnområde. Appen frågar efter support-chat-fast; gatewayen avgör om den för närvarande mappas till en Together-stil namnavgränsad modell, en Gemini-kompatibel modell, en Mistral-kompatibel modell, en Groq-chattmodell, en egenvärderad vLLM-slutpunkt eller ett annat godkänt mål.

Avvägningen är förvaltningsoverhead. Profiler måste dokumenteras, granskas och versioneras. Fördelen är att migreringar, återställningar och modellersättningar inte kräver att alla program omdistribueras.

Steg 4: skriv överensstämmelsetest före migrering

Konformitetstester är små, repeterbara kontroller som verifierar ditt kontrakt mot varje målprofil. De bör köras före den första lanseringen och närhelst en leverantör, modell, SDK eller gatewayadapter ändras.

Minsta testsvit

• Gyllene prompttest: Skicka deterministiska prompter och verifiera svarsform, finishorsak, säkerhetsbeteende och grundläggande semantiska krav. Kräv inte exakta ordalydelser om inte applikationen verkligen beror på den.
• Strömmande parsertester: Bekräfta att din klient kan analysera varje bit, rekonstruera slutlig text, hantera annullering och upptäcka slutförande av stream.
• Tool-call round trips: Tvinga fram ett verktygsanrop, analysera argumenten, kör ett falskt verktyg, returnera verktygsresultatet och bekräfta att modellen fortsätter korrekt.
• Strömmande tester för verktygsanrop: Verifiera att partiella argumentdelta kan buffras och rekonstrueras innan verktyget körs. Om inte, inaktivera inkrementell verktygskörning för den profilen.
• JSON schemavalidering: Testa giltig utdata, ogiltig utdata, saknade fält, extra fält och fall av avslag eller fel.
• Bädda in dimensionskontroller: Bekräfta vektorlängd, numerisk typ och kompatibilitet med målvektorindexet innan du återanvänder ett befintligt index.
• Försök igen och idempotenstest: Simulera 429, 500, timeout och partiella strömningsfel. Se till att verktygets biverkningar inte upprepas av misstag.
• Användningsavstämning: Jämför gatewayanvändningsposter med leverantörsrapporterade användningsfält och dina förväntningar på faktureringsreskontra.

Håll testerna nära produktionstrafikmönster. En enda "skriv en dikt"-uppmaning bevisar nästan ingenting om ett arbetsflöde som beror på verktyg, JSON, inbäddningar och användningsredovisning.

Steg 5: normalisera egenheter vid gatewayens gräns

En OpenAI-kompatibel gateway bör minska ändringar i programkod, men den bör inte låtsas som att alla leverantörer beter sig identiskt. Använd adaptrar för kända skillnader och gör beteendet synligt.

Begär normalisering

• Modellalias: Mappa stabila app-vända profilnamn till leverantörsspecifika modell-ID:n.
• Inte stödda parametrar: Avvisa parametrar som inte stöds med ett tydligt fel som standard. Tyst släppning är bekvämt under demos och farligt i produktionen.
• Leverantörsspecifika alternativ: Tillåt kontrollerade pass-through-fält, som resonemang eller tankekontroller, endast i dokumenterade modellprofiler.
• Meddelandeomvandling: Normalisera system-, utvecklare-, användare-, assistent- och verktygsmeddelanden där målleverantören förväntar sig en annan form.
• Timeoutbudgetar: Använd en deadline på applikationsnivå istället för att låta SDK standardvärden ackumuleras.

Svarsnormalisering

• Text- och verktygsval: Returnera en konsekvent form för assistenttext, verktygsanrop och avslutningsskäl.
• Strömmande bitar: Normalisera vanliga delta och dokumentera där buffring krävs.
• Användningsfält: Användning från butiksleverantör plus normaliserad uppmaning, slutförande och totalt antal token där tillgängligt.
• Felform: Mappa statuskoder, återförsökbarhet, leverantörsfelkod och begäran-ID till ett felschema.
• Kostnadsmetadata: Bifoga app-, team-, profil-, leverantörs-, modell- och miljöetiketter för senare analys.

Den huvudsakliga avvägningen är portabilitet kontra leverantörsstyrka. Normalisering till den minsta gemensamma ytan förbättrar utbytbarheten. Genom att tillåta leverantörsspecifika fält bevaras avancerade funktioner, men varje pass-through-alternativ blir en del av profildokumentationen och testmatrisen.

Steg 6: rulla ut med nycklar per app och återställningsprofiler

Migreringen bör vara reversibel utan en omdistribuering av kod. Använd separata API-nycklar för varje applikation, miljö och team. En enda delad nyckel försvårar användningstillskrivning och nödåterställning.

En säker lanseringssekvens ser ut så här:

1. Utvecklingsprofil: Led endast lokal och mellanliggande trafik genom gatewayen. Åtgärda problem med begäran-form och parser.
2. Skuggtester: Spela om representantförfrågningar till den nya profilen utan att påverka användarsynliga utdata. Jämför schemats giltighet, verktygsbeteende, latensklass och användningsfält.
3. Liten produktionsdel: Flytta en låg procentandel av trafiken eller en intern hyresgäst. Titta på fel, återförsök, kvalitetssignaler för användaren och kostnad.
4. Expansion per app: Migrera en app i taget. Migrera inte chatt, inbäddningar, batch och filer tillsammans om de inte delar samma riskprofil.
5. Återställningsprofil: Håll en känd-bra leverantörs-/modellprofil tillgänglig bakom samma app-vända alias eller en snabb konfigurationsväxel.
6. Lås efter migrering: När de är stabila, ta bort direktleverantörsnycklar från applikationsmiljöer så att trafiken inte kan kringgå gatewaykontroller.

Återställning bör testas som vilken annan väg som helst. Om en modellprofil kan bytas i gatewayen, testa den omkopplaren under en lugn period och bekräfta att programloggar, användningsanalys och faktureringstillskrivning förblir sammanhängande.

Exempel: ersätter spridda slutpunkter med ett gatewaykontrakt

Anta att ett team har tre appar:

• En kundsupportassistent som använder strömmande chatt och verktyg.
• En innehållsklassificerare som kräver strikt JSON-utdata.
• En söktjänst som använder inbäddningar lagrade i en vektordatabas.

En riskfylld migrering skulle ändra alla tre apparna till samma basadress och välja tre nya modell-ID:n. En säkrare migrering skiljer kontrakten åt:

• support-chattprofil: Kräver streaming, verktygsanrop, buffrade verktygsanropsdelta, försök igen klassificering och användningsloggning.
• classifier-json profile: Kräver schemavalidering, vägranshantering och ingen tyst parameterborttagning.
• sökinbäddningsprofil: Kräver en fast vektordimension och en indexmigreringsplan om dimensionen ändras.

Varje profil får sina egna överensstämmelsetester och lansering. Supportassistenten kan behöva arbeta med streamingadapter. Klassificeraren kan passera snabbt om schemavalideringen är extern i förhållande till modellen. Inbäddningstjänsten kan kräva ett nytt index snarare än ett modellbyte på plats. Gatewayen ger teamet en OpenAI-kompatibel basadress, men kompatibilitetsavtalet håller migreringen ärlig.

Checklista för migrering

• Lista alla AI-samtalswebbplatser, inklusive bakgrundsjobb och interna skript.
• Klassificera samtal efter slutpunkt, funktion, modell, ägare och återställningsväg.
• Definiera app-vända modellprofiler istället för hårdkodande leverantörsmodell-ID:n.
• Skapa en kapacitetsmatris för varje leverantör och modellprofil.
• Avvisa parametrar som inte stöds om inte en profil uttryckligen tillåter pass-through.
• Testa streaming, verktyg, strukturerade utdata, inbäddningar, fel, återförsök och användningsfält.
• Använd API-nycklar per app och per miljö för attribution och kontroll.
• Kör skuggtester innan användarsynlig produktionstrafik.
• Rulla ut en app eller funktionsklass åt gången.
• Håll en testad återställningsprofil tillgänglig utan omdistribuering av kod.

Aktiv slutsats

En OpenAI-kompatibel API-gateway är mest värdefull när den blir ett kontrollerat migreringslager, inte bara en annan webbadress. Bas-URL-omkopplaren minskar mekaniska kodändringar. Kompatibilitetsavtalet minskar den operativa risken.

Innan du vänder på produktionstrafik, skriv ner vad dina applikationer faktiskt kräver: strömningsbeteende, verktygssemantik, schemagarantier, inbäddningsdimensioner, återförsöksregler, användningsfält och felbetydelser. Konvertera dessa krav till modellprofiler, adapterregler och överensstämmelsetester. Lansera sedan med nycklar per app, analyser och återställningsprofiler.

Om den enkla chattvägen fungerar, se det som en bra början. Behandla resten av migreringen som ingenjörsarbete som förtjänar samma disciplin som ett byte av databas, kö eller betalningsleverantör.

Relaterad läsning

• strukturerad utdatavalidering mellan flera modellleverantörer
• modellersättning runbook
• användningsanalys och tokenavstämning i en gateway