Migreren naar een OpenAI-compatibele API-gateway: stel een compatibiliteitscontract op voordat u de basis-URL omdraait

Het wijzigen van base_url, api_key en model is vaak voldoende om een ​​eenvoudige chatdemo te laten werken met een OpenAI-compatibele API. Het is niet voldoende om te bewijzen dat een productiemigratie veilig is.

De fouten verschijnen meestal later: gestreamde toolaanroepen komen in een andere vorm binnen, een JSON-schemamodus wordt genegeerd, een insluitingsmodel retourneert een andere vectorgrootte, gebruiksvelden ontbreken, nieuwe pogingen geven een bijwerking dubbel in, of een providerspecifieke redeneeroptie doet stil niets. Het praktische doel is niet om te vragen of een eindpunt in abstracte zin ‘OpenAI-compatibel’ is. Het doel is om te definiëren van welke delen van het OpenAI-vormige contract uw applicaties afhankelijk zijn, deze delen te testen en pas via een gateway te routeren nadat het contract expliciet is.

Deze handleiding laat zien hoe u een team kunt migreren van providerspecifieke SDK's of verspreide compatibele eindpunten naar één OpenAI-compatibele gateway, terwijl de betrouwbaarheid, gebruiksattributie en terugdraaiopties behouden blijven.

Wat zijn feiten, aanbevelingen en voorspellingen bij deze migratie?

Feiten: verschillende providers documenteren OpenAI-compatibele paden of SDK-gebruik voor delen van hun API's. Google documenteert Gemini-toegang via OpenAI Python- en TypeScript-bibliotheken en REST door de API-sleutel, basis-URL en model te wijzigen, terwijl ook direct Gemini API-gebruik wordt aanbevolen voor applicaties die nog geen gebruik maken van OpenAI-bibliotheken. De compatibiliteitsdocumentatie van Gemini omvat het voltooien van chats, streaming, het aanroepen van functies, het begrijpen van afbeeldingen, insluitingen, toewijzingen van redeneringsinspanningen en providerspecifieke opties via extra verzoekteksten. Samen documenteert AI OpenAI REST- en SDK-compatibiliteit voor meerdere modaliteiten, maar de matrix vermeldt ook niet-ondersteunde OpenAI-vormige oppervlakken zoals Assistants, Threads en Runs. Mistral documenteert een migratiepad voor OpenAI-compatibele clients door de basis-URL en modelnaam te wijzigen. Groq onthult eindpunten voor het voltooien van chats via OpenAI-pad. vLLM biedt een OpenAI-compatibele server voor voltooiingen en chat, terwijl parameterverschillen worden gedocumenteerd. De OpenAI Agents SDK-documentatie waarschuwt dat veel niet-OpenAI-providers de nieuwere Responses API nog niet ondersteunen en dat de Chat Completions-modus vaak het veiligere compatibiliteitsdoel is.

Aanbevelingen: behandel compatibiliteit als een getest applicatiecontract. Inventariseer de exacte eindpunten en functies die uw apps gebruiken, maak een matrix met provider- en modelcapaciteiten, schrijf conformiteitstests vóór de verkeersmigratie, normaliseer bekende verschillen in verzoeken en antwoorden aan de gatewaygrens, en rol deze uit met sleutels per applicatie en rollback-profielen.

Voorspelling: OpenAI-compatibele oppervlakken zullen nuttig blijven als integratielaag met de laagste wrijving, maar de kenmerken van de provider zullen blijven uiteenlopen. Teams die een compatibiliteitscontract onderhouden, zullen sneller nieuwe modellen kunnen adopteren dan teams die vertrouwen op informele aannames van 'drop-in replacement'.

Stap 1: inventariseer elke huidige AI-oproep

Begin met een inventarisatie, niet met codewijzigingen. Een migratie mislukt wanneer teams ervan uitgaan dat alle AI-oproepen eruitzien als voltooiing van een chat en verborgen afhankelijkheden pas na de release ontdekken.

Maak één rij per oproepsite. Inclusief geplande taken, interne tools, notebooks, achtergrondmedewerkers, evaluatieharnassen en klantgerichte services.

app: ondersteuningsassistent
eigenaar: klantplatform
huidige_provider: provider_a
current_sdk: provider_a_python_sdk
endpoint_shape: chat.completions
model: provider-a-large-2026
kenmerken:
  - streamen
  - tool_calls
  - json_schema_output
  - gebruiksboekhouding
latency_budget_ms: 8000
retry_policy: retry_429_5xx_no_tool_side_effects
maandelijkse_volume_schatting: 2,4 miljoen verzoeken
rollback_contact: oncall-klantplatform

Classificeer elke oproep op eindpunt en functie, niet alleen op model. Eén enkele modelnaam kan zeer verschillende compatibiliteitsvereisten verbergen, afhankelijk van hoe deze wordt gebruikt.

Voorraadchecklist

• Chat: berichten, systeeminstructies, temperatuur, top-p, max. tokens, stopreeksen.
• Streaming: parser van door de server verzonden gebeurtenissen, laatste delen, gebruik in de stream, annuleringsgedrag.
• Tools: functieschema's, parallelle aanroepen, argument-JSON, toolresultaatberichten, veiligheid van bijwerkingen.
• Gestructureerde uitvoer: JSON-modus, JSON-schema, strikte validatie, logica voor fallback-reparatie.
• Visie of multimodale invoer: afbeeldings-URL, base64, MIME-afhandeling, detailparameters.
• Insluitingen: model-ID, vectordimensie, normalisatieverwachtingen, indexcompatibiliteit.
• Bestanden en batches: upload-API's, taakpeiling, annulering, uitvoerformaten.
• Redeerbeheersing: redeneerinspanning, denkbudget, verborgen tokens, providerspecifieke instellingen.
• Fouten: vorm van snelheidslimiet, time-outvorm, fouten in het inhoudsbeleid, statuscodes die opnieuw kunnen worden geprobeerd.
• Gebruik en facturering: prompttokens, voltooiingstokens, in de cache opgeslagen tokens, redeneringstokens, tags voor kostentoewijzing.

De uitvoer van deze stap is een afhankelijkheidskaart. Het vertelt u welke apps kunnen migreren met een eenvoudig OpenAI-compatibel API-profiel en welke apps adapterwerk nodig hebben.

Stap 2: bouw een compatibiliteitscontracttabel

Een compatibiliteitscontract is een tabel waarin voor elke toepassingsfunctie staat wat de gateway moet garanderen en hoe u deze gaat testen. Het moet specifiek genoeg zijn voor engineering- en productteams om implementatiebeslissingen te nemen.

Deze tabel voorkomt ook overbeloven. Als een provider chat en insluitingen ondersteunt, maar geen bestanden- of assistent-achtige workflow, moet het contract dit vermelden. “Niet ondersteund” is een geldig migratieresultaat als het een productieverrassing voorkomt.

Stap 3: maak modelprofielen in plaats van model-ID's te verspreiden

Vervang niet in elke app de ene hardgecodeerde model-ID door een andere hardgecodeerde model-ID. Gebruik modelprofielen.

profiel: ondersteuning-chat-snel
openai_model_alias: ondersteuning-chat-snel
aanbieder: aanbieder_b
provider_model: provider-b/chat-groot-snel
eindpunt: chat.completions
kenmerken:
  streaming: waar
  gereedschap: waar
  gestructureerde_outputs: schema_validated
  visie: vals
  inbedding: vals
verzoekbeleid:
  drop_unsupported_params: false
  afwijzen_onbekende_params: waar
  pass_through_extra_body: ["redeneringsinspanning"]
fallback_profile: ondersteuning-chat-veilig
cost_center_required: waar

Dit profiel geeft applicaties een stabiele naam, terwijl de gateway eigenaar is van de providertoewijzing. Het verwerkt ook providers die model-ID's met naamruimte gebruiken in plaats van een platte modelnaamruimte. De app vraagt ​​om support-chat-fast; de gateway beslist of dat momenteel wordt toegewezen aan een naamruimtemodel in Together-stijl, een Gemini-compatibel model, een Mistral-compatibel model, een Groq-chatmodel, een zelf-gehost vLLM-eindpunt of een ander goedgekeurd doel.

De afweging is bestuursoverhead. Profielen moeten worden gedocumenteerd, beoordeeld en bijgewerkt. Het voordeel is dat bij migraties, rollbacks en modelvervangingen niet elke applicatie opnieuw hoeft te worden geïmplementeerd.

Stap 4: schrijf conformiteitstests vóór de migratie

Conformiteitstests zijn kleine, herhaalbare controles die uw contract verifiëren aan de hand van elk doelprofiel. Ze moeten worden uitgevoerd vóór de eerste implementatie en telkens wanneer een provider, model, SDK of gateway-adapter verandert.

Minimale testsuite

• Gouden prompttests: stuur deterministische prompts en verifieer de reactievorm, de eindreden, het veiligheidsgedrag en de fundamentele semantische vereisten. Vereist geen exacte formulering, tenzij de toepassing er echt van afhangt.
• Streaming-parsertests: controleer of uw klant elk deel kan parseren, de uiteindelijke tekst kan reconstrueren, annuleringen kan afhandelen en voltooiing van de stream kan detecteren.
• Tool-call round trips: Forceer een tool call, ontleed de argumenten, voer een nep-tool uit, retourneer het toolresultaat en bevestig dat het model correct doorgaat.
• Tool-call streaming-tests: controleer of delta's van gedeeltelijke argumenten kunnen worden gebufferd en gereconstrueerd voordat de tool wordt uitgevoerd. Als dit niet het geval is, schakelt u de incrementele uitvoering van het hulpprogramma voor dat profiel uit.
• JSON-schemavalidatie: Test geldige uitvoer, ongeldige uitvoer, ontbrekende velden, extra velden en gevallen van weigering of fouten.
• Dimensiecontroles insluiten: Bevestig de vectorlengte, het numerieke type en de compatibiliteit met de doelvectorindex voordat u een bestaande index opnieuw gebruikt.
• Opnieuw proberen en idempotentietests: Simuleer 429-, 500-, time-out- en gedeeltelijke streamfouten. Zorg ervoor dat bijwerkingen van het gereedschap niet per ongeluk worden herhaald.
• Gebruiksafstemming: vergelijk gatewaygebruiksrecords met door de provider gerapporteerde gebruiksvelden en de verwachtingen van uw factureringsgrootboek.

Houd tests dicht bij de patronen van productieverkeer. Een enkele ‘schrijf een gedicht’-prompt bewijst bijna niets over een workflow die afhankelijk is van tools, JSON, insluitingen en gebruiksregistratie.

Stap 5: normaliseer eigenaardigheden aan de gatewaygrens

Een OpenAI-compatibele gateway zou het aantal wijzigingen in de applicatiecode moeten verminderen, maar mag niet doen alsof elke provider zich op dezelfde manier gedraagt. Gebruik adapters voor bekende verschillen en maak het gedrag zichtbaar.

Normalisatie aanvragen

• Modelaliassen: Wijs stabiele app-gerichte profielnamen toe aan providerspecifieke model-ID's.
• Niet-ondersteunde parameters: weiger standaard niet-ondersteunde parameters met een duidelijke fout. Stil laten vallen is handig tijdens demo's en gevaarlijk tijdens de productie.
• Providerspecifieke opties: Sta gecontroleerde doorgeefvelden, zoals redeneer- of denkbesturingselementen, alleen toe in gedocumenteerde modelprofielen.
• Berichtconversie: Normaliseer systeem-, ontwikkelaars-, gebruikers-, assistent- en toolberichten waarbij de doelprovider een andere vorm verwacht.
• Time-outbudgetten: pas één deadline op applicatieniveau toe in plaats van dat SDK-standaardwaarden zich ophopen.

Reactienormalisatie

• Tekst- en toolkeuzes: Retourneer een consistente vorm voor assistenttekst, toolaanroepen en afwerkingsredenen.
• Streaming-brokken: Normaliseer algemene delta's en documenteer waar buffering vereist is.
• Gebruiksvelden: sla het eigen gebruik van de provider op, plus genormaliseerde prompt-, voltooiings- en totale tokentellingen, indien beschikbaar.
• Foutvorm: Breng statuscodes, herkansing, providerfoutcode en verzoek-ID samen in één foutschema.
• Kostenmetagegevens: voeg app-, team-, profiel-, provider-, model- en omgevingslabels toe voor latere analyse.

De belangrijkste afweging is draagbaarheid versus de macht van de provider. Normaliseren tot het kleinste gemeenschappelijke oppervlak verbetert de uitwisselbaarheid. Door providerspecifieke velden toe te staan, blijven de geavanceerde mogelijkheden behouden, maar elke pass-through-optie wordt onderdeel van de profieldocumentatie en testmatrix.

Stap 6: uitrollen met per-app-sleutels en rollback-profielen

De migratie zou omkeerbaar moeten zijn zonder dat de code opnieuw hoeft te worden geïmplementeerd. Gebruik afzonderlijke API-sleutels voor elke applicatie, omgeving en team. Eén gedeelde sleutel maakt het toeschrijven van gebruik en het terugdraaien van noodgevallen moeilijker.

Een veilige implementatievolgorde ziet er als volgt uit:

1. Ontwikkelingsprofiel: Leid alleen lokaal en staging-verkeer door de gateway. Los verzoekvorm- en parserproblemen op.
2. Schaduwtests: speel representatieve verzoeken opnieuw af voor het nieuwe profiel zonder de voor de gebruiker zichtbare uitvoer te beïnvloeden. Vergelijk schemavaliditeit, toolgedrag, latentieklasse en gebruiksvelden.
3. Klein productiesegment: verplaats een laag percentage verkeer of één interne tenant. Bekijk fouten, nieuwe pogingen, gebruikersgerichte kwaliteitssignalen en kosten.
4. Uitbreiding per app: Migreer één app tegelijk. Migreer chat, insluitingen, batches en bestanden niet samen, tenzij ze hetzelfde risicoprofiel delen.
5. Rollback-profiel: Houd een bekend provider-/modelprofiel beschikbaar achter dezelfde app-gerichte alias of een snelle configuratieschakelaar.
6. Vergrendeling na de migratie: Zodra deze stabiel zijn, verwijdert u directe providersleutels uit applicatieomgevingen, zodat verkeer de gateway-controles niet kan omzeilen.

Het terugdraaien moet worden getest zoals elk ander pad. Als er in de gateway van modelprofiel kan worden gewisseld, test deze dan tijdens een rustige periode en controleer of de applicatielogboeken, gebruiksanalyses en factureringsattributie coherent blijven.

Voorbeeld: verspreide eindpunten vervangen door één gatewaycontract

Stel dat een team drie apps heeft:

• Een klantondersteuningsassistent die gebruikmaakt van streamingchat en tools.
• Een inhoudsclassificator die strikte JSON-uitvoer vereist.
• Een zoekservice die insluitingen gebruikt die zijn opgeslagen in een vectordatabase.

Bij een riskante migratie zouden alle drie de apps naar dezelfde basis-URL worden gewijzigd en drie nieuwe model-ID's worden gekozen. Een veiligere migratie scheidt de contracten:

• ondersteuningchatprofiel: vereist streaming, toolaanroepen, gebufferde toolaanroepdelta's, classificatie van nieuwe pogingen en gebruiksregistratie.
• classifier-json profiel: vereist schemavalidatie, afhandeling van weigeringen en geen stille verwijdering van parameters.
• profiel voor zoekinsluiting: vereist een vaste vectordimensie en een indexmigratieplan als de dimensie verandert.

Elk profiel krijgt zijn eigen conformiteitstests en uitrol. De ondersteuningsassistent heeft mogelijk streamingadapterwerk nodig. De classificator kan snel slagen als schemavalidatie extern aan het model plaatsvindt. Voor de insluitingsservice is mogelijk een nieuwe index vereist in plaats van een interne modelwissel. De gateway geeft het team één OpenAI-compatibele basis-URL, maar het compatibiliteitscontract houdt de migratie eerlijk.

Migratiechecklist

• Vermeld elke AI-oproepsite, inclusief achtergrondtaken en interne scripts.
• Classificeer aanroepen op eindpunt, functie, model, eigenaar en terugdraaipad.
• Definieer app-gerichte modelprofielen in plaats van hardcoderende model-ID's van providers.
• Maak een mogelijkhedenmatrix voor elke provider en elk modelprofiel.
• Weiger niet-ondersteunde parameters, tenzij een profiel expliciet pass-through toestaat.
• Teststreaming, tools, gestructureerde uitvoer, insluitingen, fouten, nieuwe pogingen en gebruiksvelden.
• Gebruik API-sleutels per app en per omgeving voor attributie en controle.
• Voer schaduwtests uit vóór zichtbaar productieverkeer.
• Implementeer één applicatie of functieklasse tegelijk.
• Houd een getest rollback-profiel beschikbaar zonder dat de code opnieuw moet worden geïmplementeerd.

Bruikbare conclusie

Een OpenAI-compatibele API-gateway is het meest waardevol als deze een gecontroleerde migratielaag wordt, en niet slechts een andere URL. De basis-URL-schakelaar vermindert mechanische codewijzigingen. Het compatibiliteitscontract vermindert het operationele risico.

Voordat u het productieverkeer omdraait, moet u opschrijven wat uw applicaties daadwerkelijk nodig hebben: streaminggedrag, tool-semantiek, schemagaranties, insluitingsdimensies, regels voor opnieuw proberen, gebruiksvelden en foutbetekenissen. Zet deze vereisten om in modelprofielen, adapterregels en conformiteitstesten. Rol het vervolgens uit met sleutels per app, analyses en terugdraaiprofielen.

Als het eenvoudige chatpad werkt, beschouw het dan als een goed begin. Behandel de rest van de migratie als technisch werk dat dezelfde discipline verdient als een wijziging van een database, wachtrij of betalingsprovider.

Gerelateerde informatie

• gestructureerde uitvoervalidatie bij meerdere modelaanbieders
• modelvervanging en rollback-runbook
• gebruiksanalyse en tokenafstemming in een gateway