Vytvorte katalóg /v1/models so zreteľom na nájomníkov pre bránu s viacerými modelmi API

Brána by nemala vrátiť každý model známy každému pripojenému poskytovateľovi z GET /v1/models. Mal by vrátiť modely, ktoré je autentifikovaný kľúč API autorizovaný a funkčne schopný volať.

Na tomto rozdiele záleží, keď jeden kľúč API poskytuje prístup k viacerým poskytovateľom LLM. Neupravené spojenie upstream katalógov môže zahŕňať modely, ktoré sú zakázané tímovou politikou, nedostupné podľa plánu nájomníka, chýbajú im zdravé poverenia, nekompatibilné s požadovaným API alebo nie sú nasadené v požadovanom regióne. Tieto záznamy spôsobujú nefunkčné nástroje na výber modelov a chyby spustenia, ktorým malo odhalenie zabrániť.

Praktická zmluva je silnejšia: každý inzerovaný model musí prejsť rovnakými vstupnými kontrolami, aké by sa vzťahovali na skutočnú požiadavku.

Definovať, čo znamená „k dispozícii“

Existencia poskytovateľa je len jeden vstup. Model by sa mal objaviť v predvolenom katalógu kľúča, len ak sú splnené všetky požadované podmienky:

• Brána má pre model nakonfigurovaný verejný produkt.
• Nájomník, tím a kľúč API majú nárok na tento produkt.
• Použitie povoľuje príslušný komerčný plán.
• Zásady umožňujú model, poskytovateľa, región a režim spracovania údajov.
• Existuje aspoň jedno kompatibilné nasadenie alebo smerovanie.
• Pre túto trasu sú k dispozícii použiteľné poverenia poskytovateľa.
• Trasa podporuje aspoň jeden API povrch inzerovaný v katalógu.
• Trasa je funkčne pripravená podľa zdravotných pravidiel brány.

Vyjadrené ako operácia súboru:

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

Toto je odporúčanie, nie tvrdenie o schéme OpenAI. Štandardná schéma nedefinuje všetky tieto ovládacie prvky špecifické pre bránu. Patria do riadiacej roviny brány a kompilátora katalógu.

Normalizácia zisťovania poskytovateľa bez jeho proxy servera

Fakt: Rozhrania API na vyhľadávanie poskytovateľov odhaľujú rôzne koncepty. Zoznam modelov OpenAI poskytuje identifikátory a základné metadáta, ale nie kompletnú maticu schopností pre každý povrch API. Anthropic rozlišuje stavy životného cyklu a môže vrátiť bohatšie informácie o schopnostiach, keď sa získa model alebo alias. Gemini odhaľuje polia, ako sú limity tokenov a podporované metódy generovania. Microsoft Foundry môže vyžadovať názov nasadenia v poli model a nasadenie môže byť nekompatibilné s konkrétnym API, aj keď základný model existuje.

Priame preposielanie odpovedí poskytovateľa teda nie je trvalou koncepciou. S každým poskytovateľom API zaobchádzajte ako so zdrojom vyrovnania. Preveďte jeho pozorovania na interný záznam a potom ich skombinujte s konfiguráciou brány a politikou nájomníka.

Použiť kanonický katalógový záznam

Užitočný interný záznam oddeľuje verejnú zákazku od predchádzajúcej implementácie:

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

Neodhaľujte target_id, referencie poverení ani stav interného smerovania prostredníctvom štandardného verejného koncového bodu. Tieto polia sú údaje riadiacej roviny. Majte ich k dispozícii na smerovanie prístupu, podporných nástrojov a pripisovania použitia.

Samostatné ID, aliasy a nasadenia

Verejné ID modelu je klientskou zmluvou. ID modelu poskytovateľa identifikuje nadradenú modelovú rodinu alebo verziu. Názov nasadenia identifikuje zdroj poskytovania vytvorený operátorom. Nie sú zameniteľné.

Pred smerovaním vyriešte verejný alias s nemennou revíziou katalógu. Zaznamenajte požadované ID aj vyriešený cieľ v udalosti použitia. Ak sa alias neskôr zmení, pracovníci podpory môžu stále rekonštruovať, ktoré nasadenie zvládlo predchádzajúci hovor.

Zostavte katalóg pre overený kľúč

Prekladač katalógu by mal dostať overený princíp, nielen ID nájomníka. Ten istý nájomca môže mať produkčné kľúče, vývojové kľúče, obmedzené zákaznícke kľúče a servisné účty s rôznymi modelovými grantmi.

Dedeterministická postupnosť kompilácie je:

1. Načítať nemennú revíziu základného katalógu.
2. Vyriešte členstvo v nájomníkovi, členstvo v tíme a granty špecifické pre kľúč.
3. Použite obmedzenia týkajúce sa plánu, geografickej polohy, umiestnenia údajov a poskytovateľa.
4. Odstráňte trasy bez platných poverení alebo kompatibilných nasadení.
5. Vyhodnoťte pripravenosť trasy pomocou aktuálneho stavu stavu.
6. Agregovať prežívajúce trasy do verejných záznamov modelov.
7. Len návrat API povrchy podporované aspoň jednou zachovanou trasou.

Použite sémantiku prieniku, keď existujú tímové aj kľúčové granty. Kľúč priradený obmedzenému tímu by nemal obnoviť širší prístup len preto, že nájomca vlastní širší plán. Vďaka tomu je riadenie prístupu k modelu AI pre softvérové tímy predvídateľné a znižuje sa náhodné prezradenie.

Uchovávajte zoznam a načítajte rovnaké správanie

GET /v1/models/{model} musí spustiť rovnaký autorizačný predikát ako operácia zoznamu. V opačnom prípade môže útočník vymenovať skryté identifikátory porovnaním úspešných, zakázaných a nenájdených odpovedí.

Pre model, ktorý kľúč nevidí, vráťte rovnakú verejnú chybu, aká bola použitá pre neznámy model. Neprezrádzajte, či ho môže používať iný nájomca, ktorý poskytovateľ ho hostí alebo aké oprávnenie by ho odomklo. Administratívne rozhrania API môžu autorizovaným operátorom odhaliť podrobnejšie dôvody.

Explicitne reprezentovať API kompatibilitu

Existencia modelu neznamená podporu pre každý koncový bod. Dokončenia četu, odpovede, vloženia, generovanie obrázkov, správy v reálnom čase, dávkové a Anthropic správy majú rôzne požiadavky a zmluvy o streamovaní.

Vstup na trasu by preto mal akceptovať model aj povrch API:

admit(key, public_model_id, api_surface, request_features)

Výsledok by mal identifikovať kompatibilnú revíziu katalógu a jednu alebo viac vhodných ciest. Model môže napríklad podporovať chat.completions, ale nie responses, alebo podporovať odpovede iba vtedy, keď chýbajú vstavané nástroje. Jedna logická hodnota, napríklad supports_responses, môže byť nedostatočná, ak kompatibilita závisí od požadovaných funkcií.

Odporúčanie: zverejniť konzervatívne možnosti. Funkciu inzerujte iba vtedy, keď ju brána dokáže vynútiť v rámci vhodnej sady trás alebo môže vybrať cestu, ktorá ju deterministicky podporuje. Neodvodzujte obrazový vstup, volanie nástroja ani štruktúrovaný výstup z priezviska poskytovateľa.

Zachovanie kompatibility SDK pri pridávaní metadát

Štandardné polia očakávané OpenAI-kompatibilnými klientmi ponechajte stabilné:

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

Rozšírenie s menným priestorom znižuje riziko kolízie, ale niektorí klienti zahadzujú neznáme polia. Ak aplikácie potrebujú podrobné údaje o výbere, poskytnite samostatný overený koncový bod informácií o modeli s verziou schémy. Udržujte /v1/models dostatočne malé pre súpravy SDK, nástroje príkazového riadka a nástroje na výber modelov.

Vyberte stabilné alebo zdravotné záznamy

Existujú dve zásady primeranej dostupnosti.

Katalóg podľa zdravotného stavu: skryť model, keď žiadna trasa momentálne nie je v poriadku. To minimalizuje neúspešné hovory, ale katalógy sa môžu počas incidentov meniť a zrušiť výbery na strane klienta.

Stabilný katalóg: pri nahlasovaní availability: temporarily_unavailable pokračovať v uvádzaní oprávnených produktov. Je to jednoduchšie pre nástroje na automatizáciu a migráciu, ale klienti sa môžu aj tak pokúšať o hovory, pokiaľ rozšíreniu nerozumejú.

Praktickým predvoleným nastavením je skryť modely, ktoré nie sú nasadené, zakázané, vyradené alebo nevhodné pre poverenia, pričom sa ponechajú dočasne nedostupné modely s explicitným stavom pre dôveryhodných klientov. Koncový bod minimálnej kompatibility môže vynechať nedostupné položky, ak existujúci klienti nedokážu interpretovať metadáta stavu.

Predpoved: bohatší klienti s výberom modelov budú čoraz viac závisieť od metadát schopností a dostupnosti. Kým nebude toto správanie všeobecne spoľahlivé, prístup k smerovaniu na strane servera musí zostať smerodajný.

Vyrovnávať kompilované katalógy bez poskytovania zastaraných grantov

Ak je to možné, kompilujte katalógy mimo cesty požiadavky. Kľúč vyrovnávacej pamäte by mal obsahovať aspoň:

(tenant_id, key_id, entitlement_version, catalog_revision, policy_revision)

Zrušte platnosť dotknutých položiek, keď sa zmení členstvo v tíme, modelové granty, cenové plány, poverenia poskytovateľa, stav nasadenia alebo pravidlá smerovania. Hodnoty krátkej doby životnosti nenahrádzajú udalosti zrušenia: aj krátke zatuchnuté okno môže odhaliť novo zakázaný model.

Odsúhlasenie poskytovateľa môže byť asynchrónne. Počas výpadku riadiacej roviny poskytovateľa si uchovajte posledný známy katalóg, zaznamenajte čas jeho pozorovania a zabráňte tomu, aby sa nové neisté trasy stali vhodnými. Vďaka tomu bude zoznam reagovať bez toho, aby sa zastarané objavy považovali za dôkaz použiteľnosti novej trasy.

Otestujte katalóg ako zmluvu o prijatí

Najsilnejšia vlastnosť zhody je jednoduchá: pre každý model a API povrch vrátený na kľúč musí byť prístup k trase úspešný v rámci rovnakého katalógu a zdravotnej revízie.

Pridať automatické testy pre:

• Povolený kľúč, ktorý vidí a načítava priradené modely.
• Zakázaný kľúč, ktorý nevidí položky zoznamu ani metadáta, ktoré sa dajú získať.
• Tímové obmedzenia zužujú, nie rozširujú, kľúčový prístup.
• Nasadenie iba pre čet nie je inzerované pre odpovede.
• Zakázané poverenie odstraňuje jeho závislé trasy.
• Alias, ktorý zodpovedá očakávanej nemennej revízii katalógu.
• Vyradený model mizne z predvoleného katalógu.
• Zrušenie platnosti vyrovnávacej pamäte po zmene grantov, členstiev alebo pravidiel.
• Neznáme a skryté ID modelov spôsobujúce nerozoznateľné verejné chyby.
• Každá inzerovaná schopnosť má aspoň jednu vhodnú trasu.

Syntetické sondy môžu pridať dôkaz, že trasa funguje, ale spotrebúvajú kvótu, môžu stáť peniaze a nedokážu pokryť všetky kombinácie funkcií. Použite ich pre reprezentatívne triedy trás a kombinujte ich so stavom nasadenia, kontrolami poverení a skutočným stavom premávky.

Zaznamenajte dostatok dôkazov na vysvetlenie rozhodnutí

Pre každú prijatú alebo zamietnutú požiadavku zaznamenajte revíziu katalógu, požadované verejné ID modelu, API povrch, vyriešenú trasu, zmluvu o spôsobilosti, revíziu pravidiel a štruktúrovaný dôvod prijatia. Vyhnite sa ukladaniu výziev len na tento účel.

Sekvencia implementácie je jednoduchá: definujte kanonický záznam, vytvorte zosúlaďovače poskytovateľov, kompilujte zobrazenia podľa kľúča, vytvorte zoznam a načítajte zdieľanie jedného autorizačného predikátu, pripojte prístup k trase k rovnakej revízii a pridajte negatívne testy pred povolením vyrovnávacej pamäte. Keď sú tieto časti na svojom mieste, /v1/models sa stane spoľahlivou odpoveďou na otázku „Čo môže tento kľúč volať?“ namiesto voľne filtrovaného inventára.

Súvisiace čítanie

• navrhovanie vrstvy kompatibility Responses API