Zgradite katalog /v1/models za najemnike za večmodelni prehod API

Prehod ne sme vrniti vseh modelov, ki jih pozna vsak povezan ponudnik od GET /v1/models. Vrniti bi moral modele, ki jih je overjen ključ API avtoriziral in operativno lahko poklical.

Ta razlika je pomembna, ko en API ključ omogoča dostop do več ponudnikov LLM. Neobdelana zveza zgornjih katalogov lahko vključuje modele, ki so prepovedani s pravilnikom skupine, niso na voljo po najemnikovem načrtu, nimajo zdrave poverilnice, niso združljivi z zahtevano API ali niso razporejeni v zahtevani regiji. Ti vnosi povzročajo pokvarjene izbirnike modelov in napake med izvajanjem, ki bi jih odkritje moralo preprečiti.

Praktična pogodba je močnejša: vsak oglaševani model mora prestati enaka sprejemna preverjanja, kot bi veljala za pravo zahtevo.

Določite, kaj pomeni »na voljo«

Obstoj ponudnika je samo en vnos. Model se mora pojaviti v privzetem katalogu ključa le, če so izpolnjeni vsi zahtevani pogoji:

• Prehod ima konfiguriran javni izdelek za model.
• Najemnik, ekipa in ključ API so upravičeni do tega izdelka.
• Uporabo dovoljuje veljavni komercialni načrt.
• Pravilnik dovoljuje model, ponudnika, regijo in način ravnanja s podatki.
• Obstaja vsaj ena združljiva navzgornja uvedba ali pot.
• Uporabna poverilnica ponudnika je na voljo za to pot.
• Pot podpira vsaj eno API površino, oglaševano v katalogu.
• Pot je operativno pripravljena v skladu z zdravstveno politiko prehoda.

Izraženo kot nastavljena operacija:

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

To je priporočilo, ne trditev o OpenAI shemi. Standardna shema ne definira vseh teh kontrolnikov, specifičnih za prehod. Spadajo v nadzorno ravnino prehoda in prevajalnik kataloga.

Normalizirajte odkrivanje ponudnika brez proxyja

Dejstvo: API-ji za odkrivanje ponudnikov razkrivajo različne koncepte. Seznam modelov OpenAI nudi identifikatorje in osnovne metapodatke, ne pa tudi popolne matrike zmogljivosti za vsako površino API. Anthropic razlikuje stanja življenjskega cikla in lahko vrne bogatejše informacije o zmogljivosti, ko se pridobi model ali vzdevek. Gemini razkriva polja, kot so omejitve žetonov in podprte metode generiranja. Microsoft Foundry lahko zahteva ime uvedbe v polju model in uvedba je lahko nezdružljiva z določeno API, tudi če osnovni model obstaja.

Posledično neposredno posredovanje odgovorov ponudnika ni trajna zasnova. Vsakega ponudnika API obravnavajte kot vir usklajevanja. Pretvori svoja opažanja v interni zapis, nato pa jih združi s konfiguracijo prehoda in politiko najemnika.

Uporabite kanonični kataloški zapis

Uporaben notranji zapis ločuje javno naročilo od predhodne izvedbe:

{
  "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"
    }
  ]
}

Ne izpostavljajte target_id, referenc poverilnic ali notranjega stanja usmerjanja prek standardne javne končne točke. Ta polja so podatki nadzorne ravnine. Naj bodo na voljo za sprejem poti, podporna orodja in dodeljevanje uporabe.

Ločeni ID-ji, vzdevki in uvedbe

Javni ID modela je pogodba s stranko. ID modela ponudnika identificira družino ali različico modela navzgor. Ime razmestitve identificira strežni vir, ki ga ustvari operater. Niso zamenljivi.

Pred usmerjanjem razrešite javni vzdevek z nespremenljivo revizijo kataloga. Zabeležite zahtevani ID in razrešeni cilj v dogodku uporabe. Če se vzdevek pozneje spremeni, lahko podporno osebje še vedno rekonstruira, katera uvedba je obravnavala prejšnji klic.

Sestavite katalog za overjen ključ

Prevajalnik kataloga mora prejeti overjenega principala, ne le ID-ja najemnika. Isti najemnik ima lahko proizvodne ključe, razvojne ključe, omejene ključe strank in storitvene račune z različnimi odobritvami modela.

Deterministično zaporedje prevajanja je:

1. Naloži revizijo nespremenljivega osnovnega kataloga.
2. Razrešite članstvo najemnika, članstvo v skupini in nepovratna sredstva, specifična za ključ.
3. Uporabite omejitve načrta, geografije, podatkovnega prebivališča in ponudnika.
4. Odstranite poti brez veljavnih poverilnic ali združljivih uvedb.
5. Ocenite pripravljenost poti z uporabo trenutnega zdravstvenega posnetka.
6. Združite preživele poti v javne zapise modelov.
7. Vrni samo API površin, ki jih podpira vsaj ena preživela pot.

Uporabite semantiko presečišča, ko obstajata odobritev ekipe in ključa. Ključ, dodeljen omejeni skupini, ne bi smel obnoviti širšega dostopa samo zato, ker ima najemnik širši načrt. To naredi nadzor dostopa modela AI za skupine programske opreme predvidljiv in zmanjša nenamerno razkritje.

Ohranjanje enakega vedenja seznama in pridobivanja

GET /v1/models/{model} mora izvajati isti avtorizacijski predikat kot operacija seznama. V nasprotnem primeru lahko napadalec našteje skrite identifikatorje s primerjavo uspešnih, prepovedanih in nenajdenih odgovorov.

Za model, ki ga ključ ne vidi, vrni isto javno napako, uporabljeno za neznani model. Ne razkrijte, ali ga lahko uporablja drug najemnik, kateri ponudnik ga gosti ali katero pooblastilo bi ga odklenilo. Administrativni API-ji lahko pooblaščenim operaterjem razkrijejo podrobnejše razloge.

Izrecno predstavi API združljivost

Obstoj modela ne pomeni podpore za vsako končno točko. Zaključki klepeta, odgovori, vdelave, ustvarjanje slik, realni čas, paketna sporočila in Anthropic Sporočila imajo različne zahteve in pogodbe za pretakanje.

Dostop do poti mora torej sprejeti tako model kot API površino:

admit(key, public_model_id, api_surface, request_features)

Rezultat mora identificirati združljivo revizijo kataloga in eno ali več primernih poti. Na primer, model lahko podpira chat.completions, vendar ne responses, ali pa podpira odzive samo, če ni vgrajenih orodij. Ena logična vrednost, kot je supports_responses, morda ne zadostuje, če je združljivost odvisna od zahtevanih funkcij.

Priporočilo: objavite konzervativne zmožnosti. Oglašujte funkcijo le, če jo lahko prehod uveljavi v naboru ustreznih poti ali lahko izbere pot, ki jo deterministično podpira. Ne sklepajte o vnosu slike, klicanju orodja ali strukturiranem izhodu iz družinskega imena ponudnika.

Ohranite SDK združljivost ob dodajanju metapodatkov

Ohranite stabilna standardna polja, ki jih pričakujejo OpenAI-združljivi odjemalci:

{
  "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"
  }
}

Razširitev imenskega prostora zmanjša tveganje trka, vendar nekateri odjemalci zavržejo neznana polja. Če aplikacije potrebujejo podrobne izbirne podatke, zagotovite ločeno overjeno končno točko informacij o modelu s shemo različic. /v1/models naj bo dovolj majhen za SDK-je, orodja ukazne vrstice in izbirnike modelov.

Izberite stabilne ali zdravstveno filtrirane sezname

Obstajata dva pravilnika o razumni razpoložljivosti.

Katalog s filtriranjem zdravja: skrij model, ko nobena pot trenutno ni zdrava. To zmanjša število neuspešnih klicev, vendar lahko katalogi med incidenti nihajo in razveljavijo izbire na strani odjemalca.

Stabilen katalog: nadaljujte z navajanjem upravičenih izdelkov ob poročanju availability: temporarily_unavailable. To je lažje za orodja za avtomatizacijo in selitev, vendar lahko stranke še vedno poskušajo klicati, razen če razumejo razširitev.

Praktično privzeto je skriti modele, ki so nerazporejeni, prepovedani, umaknjeni ali neprimerni za poverilnice, hkrati pa ohraniti začasno nerazpoložljive modele z eksplicitnim statusom za zaupanja vredne stranke. Končna točka minimalne združljivosti lahko izpusti nerazpoložljive vnose, če obstoječi odjemalci ne morejo interpretirati metapodatkov o stanju.

Napoved: odjemalci z bogatejšo izbiro modelov bodo vse bolj odvisni od metapodatkov o zmogljivosti in razpoložljivosti. Dokler to vedenje ni na splošno zanesljivo, mora sprejem poti na strani strežnika ostati verodostojen.

Predpomnite prevedene kataloge brez serviranja zastarelih odobritev

Kjer je mogoče, sestavite kataloge zunaj poti zahteve. Ključ predpomnilnika mora vsebovati vsaj:

(tenant_id, key_id, entitlement_version, catalog_revision, policy_revision)

Razveljavi prizadete vnose, ko se spremenijo članstvo v ekipi, odobritve modela, cenovni načrti, poverilnice ponudnika, stanje uvedbe ali politika usmerjanja. Vrednosti kratkega časa življenja niso nadomestek za dogodke preklica: celo kratko zastarelo okno lahko izpostavi na novo prepovedan model.

Uskladitev ponudnika je lahko asinhrona. Med izpadom nadzorne ravnine ponudnika ohranite zadnji znani katalog, zabeležite njegov čas opazovanja in preprečite, da bi nove negotove poti postale primerne. To ohranja odzivnost seznama, ne da bi zastarela odkritja obravnavala kot dokaz, da je nova pot uporabna.

Preizkusi katalog kot pogodbo o sprejemu

Najmočnejša lastnost skladnosti je preprosta: za vsak model in API površino, vrnjeno na ključ, mora biti sprejem poti uspešen v istem katalogu in zdravstveni reviziji.

Dodaj samodejne teste za:

• Dovoljen ključ, ki vidi in pridobiva svoje dodeljene modele.
• Prepovedan ključ, ki ne vidi niti vnosov na seznamu niti metapodatkov, ki jih je mogoče pridobiti.
• Omejitve ekipe, ki zožijo, namesto da razširijo dostop do ključev.
• Uvedba samo za klepet ni oglaševana za odgovore.
• Onemogočena poverilnica, ki odstranjuje svoje odvisne poti.
• Vzdevek, ki razreši pričakovano nespremenljivo revizijo kataloga.
• Upokojitveni model izginja iz privzetega kataloga.
• Razveljavitev predpomnilnika po odobritvi, članstvu ali spremembi pravilnika.
• Neznani in skriti ID-ji modela, ki ustvarjajo nerazločljive javne napake.
• Vsaka oglaševana zmogljivost ima vsaj eno primerno pot.

Sintetične sonde lahko dodajo dokaze, da pot deluje, vendar porabijo kvoto, lahko stanejo denar in ne morejo pokriti vseh kombinacij funkcij. Uporabite jih za reprezentativne razrede poti in jih kombinirajte s stanjem namestitve, preverjanji poverilnic in dejanskim stanjem prometa.

Zabeležite dovolj dokazov za razlago odločitev

Za vsako sprejeto ali zavrnjeno zahtevo zabeležite revizijo kataloga, zahtevani javni ID modela, API površino, razrešeno pot, pogodbo o zmogljivosti, revizijo pravilnika in razlog za strukturiran sprejem. Izogibajte se shranjevanju takojšnje vsebine samo za ta namen.

Zaporedje implementacije je preprosto: definirajte kanonični zapis, zgradite usklajevalnike ponudnika, sestavite poglede po ključu, naredite seznam in pridobite skupno rabo enega avtorizacijskega predikata, povežite sprejem poti z isto revizijo in dodajte negativne teste, preden omogočite predpomnilnike. Ko so ti deli na svojem mestu, /v1/models postane zanesljiv odgovor na "kaj lahko kliče ta ključ?" namesto ohlapno filtriranega inventarja.

Sorodno branje

• oblikovanje plasti združljivosti Responses API