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 genoeg om een ​​eenvoudige chatdemo te laten werken tegen 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 aan, een JSON schemamodus wordt genegeerd, een inbeddingsmodel retourneert een andere vectorgrootte, gebruiksvelden ontbreken, nieuwe pogingen geven een bijwerking dubbel in, of een providerspecifieke redeneringsoptie 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 onderdelen 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 documenten Gemini hebben toegang via OpenAI Python en TypeScript-bibliotheken en REST door de sleutel API, de basis-URL en het model te wijzigen, terwijl ook direct Gemini API gebruik wordt aanbevolen voor toepassingen die nog geen OpenAI-bibliotheken gebruiken. 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 chatvoltooiingen met OpenAIpad. vLLM biedt een OpenAI-compatibele server voor voltooiingen en chat, terwijl parameterverschillen worden gedocumenteerd. De documentatie van OpenAI Agents SDK waarschuwt dat veel niet-OpenAI providers de nieuwere Responses API nog niet ondersteunen en dat de modus Chat Completions 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 verkeersmigratie, normaliseer bekende verschillen in verzoeken en antwoorden aan de gatewaygrens, en implementeer met sleutels per applicatie en rollback-profielen.

Voorspelling: OpenAI-compatibele oppervlakken zullen nuttig blijven als integratielaag met de laagste wrijving, maar de eigen kenmerken van de provider zullen blijven uiteenlopen. Teams die een compatibiliteitscontract onderhouden, zullen nieuwe modellen sneller 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 als teams ervan uitgaan dat alle AI-oproepen eruit zien als voltooide chats en verborgen afhankelijkheden pas na de release worden ontdekt.

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

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

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.
• Hulpmiddelen: functieschema's, parallelle aanroepen, argument JSON, toolresultaatberichten, veiligheid van bijwerkingen.
• Gestructureerde uitvoer: JSON modus, JSON schema, strikte validatie, logica voor noodreparatie.
• Visie of multimodale invoer: afbeeldings-URL, base64, MIME-verwerking, detailparameters.
• Insluitingen: model-ID, vectordimensie, normalisatieverwachtingen, indexcompatibiliteit.
• Bestanden en batches: API's uploaden, taakpeilingen, annulering, uitvoerformaten.
• Redeneringsmechanismen: 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 het cachegeheugen opgeslagen tokens, redeneringstokens, tags voor kostentoewijzing.

De uitkomst 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: een compatibiliteitscontracttabel maken

Een compatibiliteitscontract is een tabel waarin voor elke applicatiefunctie 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.

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

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 dit 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: conformiteitstests schrijven vóór 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: Verzend 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 afhankelijk is.
• Streaming-parsertests: Controleer of uw client 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-aanroep, parseer de argumenten, voer een nep-tool uit, retourneer het toolresultaat en bevestig dat het model correct doorgaat.
• Tool-call streaming tests: Controleer of gedeeltelijke argumentdelta's kunnen worden gebufferd en gereconstrueerd voordat de tool wordt uitgevoerd. Als dit niet het geval is, schakelt u de incrementele uitvoering van het hulpprogramma uit voor dat profiel.
• 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 productieverkeerspatronen. Eén 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.
• Provider-specifieke 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 gereedschapskeuzes: Retourneert een consistente vorm voor assistent-tekst, gereedschapsaanroepen 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 sleutels per app en terugdraaiprofielen

Migratie moet omkeerbaar zijn zonder een nieuwe code-implementatie. Gebruik afzonderlijke API-sleutels voor elke applicatie, omgeving en team. Eén gedeelde sleutel maakt het toeschrijven van gebruik en het terugdraaien in noodgevallen moeilijker.

Een veilige implementatievolgorde ziet er als volgt uit:

1. Ontwikkelingsprofiel: Leid alleen lokaal en staging-verkeer door de gateway. Los problemen met de verzoekvorm en parser 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 migratie: Eenmaal stabiel, 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 klantenservicemedewerker die gebruikmaakt van streaming chat en tools.
• Een inhoudsclassificator die strikte JSON uitvoer vereist.
• Een zoekservice die gebruikmaakt van insluitingen 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:

• support-chatprofiel: Vereist streaming, toolaanroepen, gebufferde toolaanroepdelta's, classificatie van nieuwe pogingen en gebruiksregistratie.
• classifier-json profile: Vereist schemavalidatie, afhandeling van weigeringen en geen stille verwijdering van parameters.
• zoek-inbeddingsprofiel: Vereist een vaste vectordimensie en een indexmigratieplan als de dimensie verandert.

Elk profiel krijgt zijn eigen conformiteitstests en implementatie. 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 hard-coding providermodel-ID's.
• 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 sleutels per app en per omgeving API voor attributie en controle.
• Voer schaduwtests uit vóór zichtbaar productieverkeer.
• Implementeer één applicatie of functieklasse tegelijk.
• Houd een getest rollback-profiel beschikbaar zonder code opnieuw te implementeren.

Conclusie waar actie op ondernomen kan worden

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

Voordat u productieverkeer omdraait, noteert u 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 engineeringwerk dat dezelfde discipline verdient als een wijziging in een database, wachtrij of betalingsprovider.

Gerelateerd lezen

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