Looge üürnikuteadlik /v1/models kataloog mitme mudeli API lüüsi jaoks

Lüüs ei tohiks tagastada iga mudelit, mis on kõigile ühendatud pakkujatele teada alates GET /v1/models. See peaks tagastama mudelid, millele autentitud võti API on volitatud ja millel on töövõimeline helistamine.

See eristus on oluline, kui üks API klahv tagab juurdepääsu mitmele LLM-i pakkujale. Ülesvoolu kataloogide töötlemata liit võib sisaldada mudeleid, mis on meeskonnapoliitikaga keelatud, pole rentniku plaani alusel saadaval, millel puudub terve mandaat, mis ei ühildu nõutud numbriga API või mida pole nõutavas piirkonnas juurutatud. Need kirjed tekitavad katkisi mudelivalijaid ja käitusvigu, mida avastus oleks pidanud ära hoidma.

Praktiline leping on tugevam: iga reklaamitud mudel peab läbima samad sisseastumiskontrollid, mis kehtivad tegeliku taotluse korral.

Määratlege, mida „saadaval” tähendab

Pakkuja olemasolu on ainult üks sisend. Mudel peaks ilmuma võtme vaikekataloogis ainult siis, kui kõik nõutavad tingimused on tõesed:

• Lüüsil on mudeli jaoks konfigureeritud avalik toode.
• Üürnikul, meeskonnal ja API võtmel on õigus sellele tootele.
• Kehtiv äriplaan lubab seda kasutada.
• Eeskirjad lubavad mudeli, pakkuja, piirkonna ja andmetöötlusrežiimi.
• Olemas on vähemalt üks ühilduv ülesvoolu juurutus või marsruut.
• Selle marsruudi jaoks on saadaval kasutatav teenusepakkuja mandaat.
• Marsruut toetab vähemalt ühte API kataloogis reklaamitavat pinda.
• Marsruut on lüüsi tervisepoliitika kohaselt tööks valmis.

Väljendatud toiminguna:

visible_models(key) =
  configured_products
  ∩ tenant_entitlements
  ∩ team_grants
  ∩ key_grants
  ∩ commercial_rights
  ∩ policy_eligible_routes
  ∩ compatible_deployments
  ∩ operationally_ready_routes

See on soovitus, mitte väide OpenAI skeemi kohta. Standardskeem ei määratle kõiki neid lüüsipõhiseid juhtelemente. Need kuuluvad lüüsi juhttasandisse ja kataloogi kompilaatorisse.

Pakkuja leidmise normaliseerimine ilma puhverserverita

Fakt: pakkuja tuvastamise API-d paljastavad erinevaid kontseptsioone. OpenAI mudeliloend sisaldab identifikaatoreid ja põhilisi metaandmeid, kuid mitte täielikku võimaluste maatriksit iga API pinna jaoks. Anthropic eristab elutsükli olekuid ja võib mudeli või pseudonüümi hankimisel tagastada rikkalikuma teabe võimekuse kohta. Gemini paljastab sellised väljad nagu lubade piirangud ja toetatud genereerimismeetodid. Microsoft Foundry võib nõuda väljale model juurutuse nime ja juurutus võib olla kokkusobimatu konkreetse API-ga isegi siis, kui selle aluseks olev mudel on olemas.

Järelikult ei ole pakkuja vastuste otse edastamine vastupidav kujundus. Käsitlege iga pakkujat API kooskõlastusallikana. Teisendage selle vaatlused sisemiseks kirjeks, seejärel ühendage need lüüsi konfiguratsiooni ja rentniku poliitikaga.

Kasutage kanoonilist kataloogikirjet

Kasulik sisemine kirje eraldab avaliku lepingu eelnevast rakendamisest:

{
  "catalog_revision": "cat_2026_11_05_0182",
  "public_model_id": "reasoning-large",
  "lifecycle": "active",
  "api_surfaces": ["chat.completions", "responses"],
  "input_modalities": ["text", "image"],
  "output_modalities": ["text"],
  "limits": {
    "context_tokens": 200000,
    "max_output_tokens": 32000
  },
  "capabilities": {
    "tools": true,
    "structured_output": true,
    "batch": false
  },
  "entitlement_profile": "advanced-reasoning",
  "routes": [
    {
      "provider": "provider-a",
      "target_type": "deployment",
      "target_id": "prod-reasoning-east",
      "region": "us-east",
      "state": "ready"
    }
  ]
}

Ärge avaldage standardse avaliku lõpp-punkti kaudu target_id, mandaadiviiteid ega sisemist marsruutimise olekut. Need väljad on juhttasandi andmed. Hoidke need kättesaadavaks, et võimaldada juurdepääsu, tugitööriistade ja kasutamise omistamist.

Eri ID-d, varjunimed ja juurutused

Avalik mudeli ID on kliendileping. Pakkuja mudeli ID identifitseerib ülesvoolu mudelipere või versiooni. Juurutuse nimi identifitseerib operaatori loodud teenindusressurssi. Need ei ole omavahel asendatavad.

Enne marsruutimist lahendage avalik pseudonüüm muutumatuks kataloogi versiooniks. Salvestage kasutussündmuses nii taotletud ID kui ka lahendatud sihtmärk. Kui pseudonüüm hiljem muutub, saavad tugitöötajad siiski taastada, milline juurutus käsitles varasemat kõnet.

Koostage autentitud võtme jaoks kataloog

Kataloogi koostaja peaks saama autentitud printsipaali, mitte lihtsalt rentniku ID. Samal rentnikul võivad olla tootmisvõtmed, arendusvõtmed, piiratud kliendivõtmed ja teenusekontod erinevate mudelitoetustega.

Deterministlik kompileerimisjada on:

1. Laadige muutumatu baaskataloogi versioon.
2. Lahendage üürniku liikmelisust, meeskonnaliikmelisust ja võtmepõhiseid toetusi.
3. Rakendage plaani, geograafilise asukoha, andmete elukoha ja teenusepakkuja piiranguid.
4. Eemaldage marsruudid ilma kehtivate mandaatide või ühilduvate juurutusteta.
5. Hinda marsruudi valmisolekut praeguse terviseseisundi hetktõmmise abil.
6. Säilinud marsruudide koondamine avalikesse mudelikirjetesse.
7. Tagasi ainult API pinda, mida toetab vähemalt üks säilinud marsruut.

Kasutage ristmiku semantikat, kui on olemas nii meeskonna- kui ka võtmetoetused. Piiratud meeskonnale määratud võti ei tohiks taastada laiemat juurdepääsu ainult seetõttu, et üürnikul on laiem plaan. See muudab AI mudeli juurdepääsukontrolli tarkvarameeskondade jaoks prognoositavaks ja vähendab juhuslikku avalikustamist.

Hoidke loend ja laadige käitumine identsena

GET /v1/models/{model} peab käivitama sama autoriseerimispredikaadi nagu loendi toiming. Vastasel juhul võib ründaja loendada peidetud identifikaatoreid, võrreldes edukaid, keelatud ja leidmata vastuseid.

Mudelile, mida võti ei näe, tagastage sama avalik viga, mida kasutati tundmatu mudeli puhul. Ärge avaldage, kas teine ​​üürnik saab seda kasutada, milline pakkuja seda hostib või milline õigus selle avab. Administratiivsed API-d võivad volitatud operaatoritele esitada üksikasjalikumad põhjused.

Esitab selgesõnaliselt API ühilduvust

Mudelite olemasolu ei tähenda iga lõpp-punkti tuge. Vestluse lõpetamised, vastused, manustamine, piltide genereerimine, reaalajas, pakett ja Anthropic Sõnumitel on erinevad päringu- ja voogesituslepingud.

Seetõttu peaks marsruudil lubama nii mudelit kui ka API pinnast:

admit(key, public_model_id, api_surface, request_features)

Tulemus peaks tuvastama ühilduva kataloogi versiooni ja ühe või mitu sobilikku marsruuti. Näiteks võib mudel toetada chat.completions, kuid mitte responses või toetada vastuseid ainult siis, kui sisseehitatud tööriistad puuduvad. Ühest tõeväärtusest, näiteks supports_responses, ei pruugi piisata, kui ühilduvus sõltub soovitud funktsioonidest.

Soovitus: avaldage konservatiivsed võimalused. Reklaamige funktsiooni ainult siis, kui lüüs suudab selle jõustada üle sobiva marsruudi või saab valida marsruudi, mis seda deterministlikult toetab. Ärge järeldage teenusepakkuja perekonnanimest kujutise sisendit, tööriista kutsumist ega struktureeritud väljundit.

Säilita SDK ühilduvus metaandmete lisamisel

Hoidke OpenAIühilduvate klientide oodatud standardväljad stabiilsed:

{
  "id": "reasoning-large",
  "object": "model",
  "created": 1793836800,
  "owned_by": "gateway",
  "x_gateway": {
    "catalog_revision": "cat_2026_11_05_0182",
    "lifecycle": "active",
    "api_surfaces": ["chat.completions", "responses"],
    "input_modalities": ["text", "image"],
    "availability": "available"
  }
}

Nimeruumiga laiendus vähendab kokkupõrkeohtu, kuid mõned kliendid jätavad tundmatud väljad kõrvale. Kui rakendused vajavad üksikasjalikke valikuandmeid, esitage eraldi autentitud mudeliteabe lõpp-punkt koos versioonitud skeemiga. Hoidke /v1/models SDK-de, käsureatööriistade ja mudelivalijate jaoks piisavalt väike.

Valige stabiilsed või tervisefiltriga kirjed

On olemas kaks mõistlikku saadavuse reeglit.

Tervisefiltriga kataloog: peita mudel, kui ükski marsruut pole hetkel terve. See vähendab ebaõnnestunud kõnesid, kuid kataloogid võivad vahejuhtumite ajal kõikuda ja muuta kliendipoolsed valikud kehtetuks.

Stabiilne kataloog: jätkake vastavate toodete loetlemist, esitades samal ajal availability: temporarily_unavailable. See on automatiseerimise ja migratsioonitööriistade jaoks lihtsam, kuid kliendid võivad siiski proovida helistada, kui nad laiendist aru ei saa.

Praktiline vaikeseade on peita mudelid, mis on kasutusele võtmata, keelatud, kasutuselt kõrvaldatud või mandaadiga mittesobivad, säilitades samal ajal ajutiselt kättesaamatud mudelid, millel on usaldusklientide jaoks selge olek. Minimaalse ühilduvuse lõpp-punkt võib kättesaamatud kirjed välja jätta, kui olemasolevad kliendid ei suuda oleku metaandmeid tõlgendada.

Prognoos: rikkalikumad mudelivaliku kliendid sõltuvad üha enam võimekuse ja saadavuse metaandmetest. Kuni see käitumine on üldiselt usaldusväärne, peab serveripoolne marsruudi lubamine jääma autoriteetseks.

Koostatud kataloogide vahemällu hoidmine ilma aegunud toetusi andmata

Võimalusel koostage kataloogid väljaspool päringu teed. Vahemälu võti peab sisaldama vähemalt järgmist:

(tenant_id, key_id, entitlement_version, catalog_revision, policy_revision)

Mõjutatud kirjete kehtetuks tunnistamine, kui muutub meeskonna liikmelisus, mudelitoetused, hinnaplaanid, pakkuja mandaadid, juurutamise olek või marsruutimispoliitika. Lühikesed eluea väärtused ei asenda tühistamissündmusi: isegi lühike aegunud aken võib paljastada äsja keelatud mudeli.

Pakkuja vastavusseviimine võib olla asünkroonne. Pakkuja juhtlennuki katkestuse ajal säilitage viimane teadaolev kataloog, registreerige selle vaatlusaeg ja vältige uute ebakindlate marsruutide abikõlblikuks muutumist. See muudab loendi tundlikuks, ilma et see käsitleks aegunud avastust tõendina, et uus marsruut on kasutatav.

Kataloogi testimine sisseastumislepinguna

Kõige tugevam vastavusomadus on lihtne: iga võtmele tagastatud mudeli ja API pinna puhul peab marsruudi lubamine õnnestuma sama kataloogi ja seisukorra versiooni alusel.

Automaattestide lisamine:

• Lubatud võti, mis näeb ja otsib talle määratud mudeleid.
• Keelatud võti, mis ei näe loendikirjeid ega leitavaid metaandmeid.
• Meeskonnapiirangud pigem kitsendavad kui laiendavad võtmejuurdepääsu.
• Ainult vestlusega juurutust vastuste jaoks ei reklaamita.
• Keelatud mandaat, mis eemaldab oma sõltuvad marsruudid.
• Alias, mis lahendab eeldatava muutumatu kataloogi versiooni.
• Vaikekataloogist kaob kasutuselt kõrvaldatud mudel.
• Vahemälu kehtetuks tunnistamine pärast toetuste, liikmelisuse või eeskirjade muutmist.
• Tundmatud ja peidetud mudeli ID-d, mis tekitavad eristamatuid avalikke vigu.
• Igal reklaamitud võimalusel on vähemalt üks sobilik marsruut.

Sünteetilised sondid võivad lisada tõendeid marsruudi toimimise kohta, kuid need tarbivad kvooti, ​​võivad maksta raha ega suuda katta kõiki funktsioonide kombinatsioone. Kasutage neid tüüpiliste marsruudiklasside jaoks ja kombineerige need juurutamise oleku, mandaadi kontrollimise ja tegeliku liikluse seisundiga.

Salvestage otsuste selgitamiseks piisavalt tõendeid

Iga vastuvõetud või tagasilükatud taotluse puhul registreerige kataloogi versioon, taotletud avalik mudeli ID, API pind, lahendatud marsruut, võimeleping, eeskirjade läbivaatamine ja struktureeritud vastuvõtmise põhjus. Vältige viipade sisu salvestamist ainult sel eesmärgil.

Rakenduse järjestus on lihtne: määrake kanooniline kirje, looge pakkujate kooskõlastajad, koostage võtmepõhised vaated, koostage loend ja hankige jagage ühte autoriseerimispredikaati, ühendage marsruudi lubamine sama redaktsiooniga ja lisage enne vahemälu lubamist negatiivsed testid. Kui need osad on paigas, saab /v1/models usaldusväärseks vastuseks küsimusele „mida see võti võib kutsuda?” mitte lõdvalt filtreeritud laoseisu.

Seotud lugemine

• Responses API ühilduvuskihi kujundamine