Izgradite /v1/models katalog s obzirom na stanare za višemodelni API pristupnik

Gateway ne bi trebao vratiti svaki model poznat svakom povezanom pružatelju od GET /v1/models. Trebao bi vratiti modele koje je autentificirani ključ API ovlašten i operativno sposoban pozvati.

Ova je razlika važna kada jedan API ključ omogućuje pristup višestrukim pružateljima LLM-a. Sirova unija gornjih kataloga može uključivati ​​modele koji su zabranjeni timskim pravilima, nedostupni prema planu zakupca, nedostaju im zdrave vjerodajnice, nekompatibilni sa traženim API ili nisu raspoređeni u potrebnoj regiji. Ti unosi proizvode pokvarene birače modela i pogreške u vremenu izvođenja koje je otkrivanje trebalo spriječiti.

Praktični ugovor je jači: svaki oglašeni model mora proći iste prijemne provjere koje bi se primijenile na pravi zahtjev.

Definirajte što znači "dostupno"

Postojanje pružatelja samo je jedan unos. Model bi se trebao pojaviti u zadanom katalogu ključa samo kada su svi potrebni uvjeti istiniti:

• Gateway ima konfiguriran javni proizvod za model.
• Zakupac, tim i ključ API imaju pravo na taj proizvod.
• Primjenjivi komercijalni plan dopušta njegovu upotrebu.
• Pravila dopuštaju model, pružatelja usluga, regiju i način rukovanja podacima.
• Postoji najmanje jedna kompatibilna uzvodna implementacija ili ruta.
• Upotrebljiva vjerodajnica pružatelja usluga dostupna je za tu rutu.
• Ruta podržava najmanje jednu API površinu oglašenu u katalogu.
• Ruta je operativno spremna prema zdravstvenoj politici pristupnika.

Izraženo kao operacija skupa:

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

Ovo je preporuka, a ne tvrdnja o OpenAI shemi. Standardna shema ne definira sve ove kontrole specifične za gateway. Oni pripadaju kontrolnoj ravni pristupnika i kompajleru kataloga.

Normalizirajte otkrivanje pružatelja bez proxyja

Činjenica: API-ji za otkrivanje pružatelja usluga otkrivaju različite koncepte. Popis modela OpenAI daje identifikatore i osnovne metapodatke, ali ne i potpunu matricu mogućnosti za svaku API površinu. Anthropic razlikuje stanja životnog ciklusa i može vratiti bogatije informacije o mogućnostima kada se dohvati model ili alias. Gemini izlaže polja kao što su ograničenja tokena i podržane metode generiranja. Microsoft Foundry može zahtijevati naziv implementacije u polju model, a implementacija može biti nekompatibilna s određenim API čak i kada temeljni model postoji.

Slijedom toga, izravno prosljeđivanje odgovora pružatelja usluga nije trajan dizajn. Tretirajte svakog pružatelja API kao izvor usklađivanja. Pretvorite svoja zapažanja u interni zapis, a zatim ih kombinirajte s konfiguracijom pristupnika i pravilima stanara.

Koristite kanonski kataloški zapis

Korisni interni zapis odvaja javni ugovor od prethodne implementacije:

{
  "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 izlažite target_id, reference vjerodajnica ili interno stanje usmjeravanja kroz standardnu javnu krajnju točku. Ta su polja podaci kontrolne ravnine. Neka budu dostupni za pristup ruti, alate za podršku i dodjelu upotrebe.

Odvojeni ID-ovi, aliasi i implementacije

Javni ID modela je ugovor s klijentom. ID modela pružatelja identificira uzvodnu obitelj ili verziju modela. Naziv implementacije identificira resurs posluživanja koji je stvorio operater. Nisu međusobno zamjenjivi.

Razriješite javni alias na nepromjenjivu reviziju kataloga prije usmjeravanja. Zabilježite i traženi ID i razriješeni cilj u događaju korištenja. Ako se alias kasnije promijeni, osoblje za podršku još uvijek može rekonstruirati koja je implementacija obradila prethodni poziv.

Sastavite katalog za provjereni ključ

Sastavljač kataloga trebao bi primiti ovjerenog principala, a ne samo ID stanara. Isti zakupac može imati proizvodne ključeve, razvojne ključeve, ograničene korisničke ključeve i račune usluga s različitim dodjelama modela.

Deterministički niz kompilacije je:

1. Učitaj reviziju nepromjenjivog osnovnog kataloga.
2. Riješite članstvo zakupca, članstvo u timu i grantove specifične za ključeve.
3. Primijenite ograničenja plana, geografije, boravišta podataka i pružatelja usluga.
4. Ukloni rute bez valjanih vjerodajnica ili kompatibilnih implementacija.
5. Procijenite spremnost rute pomoću trenutne snimke stanja.
6. Grupirajte preživjele rute u javne zapise modela.
7. Vrati samo API površina koje podržava najmanje jedna preživjela ruta.

Koristite semantiku presjeka kada postoje i timska i ključna odobrenja. Ključ dodijeljen ograničenom timu ne bi trebao vratiti širi pristup samo zato što stanar posjeduje širi plan. To čini kontrolu pristupa modelu umjetne inteligencije za softverske timove predvidljivom i smanjuje slučajno otkrivanje.

Održavanje popisa i dohvaćanja identičnim

GET /v1/models/{model} mora pokrenuti isti autorizacijski predikat kao operacija popisa. Inače, napadač može nabrojati skrivene identifikatore uspoređujući uspješne, zabranjene i nenađene odgovore.

Za model koji ključ ne vidi, vraća istu javnu pogrešku korištenu za nepoznati model. Nemojte otkrivati ​​može li ga drugi stanar koristiti, koji ga pružatelj hostira ili koje bi ga pravo otključalo. Administrativni API-ji mogu izložiti detaljnije razloge ovlaštenim operaterima.

Izričito predstavljanje API kompatibilnosti

Postojanje modela ne podrazumijeva podršku za svaku krajnju točku. Završeci čavrljanja, odgovori, ugrađivanja, generiranje slika, stvarno vrijeme, serije i Anthropic Poruke imaju različite zahtjeve i ugovore o strujanju.

Pristup ruti stoga treba prihvatiti i model i API površinu:

admit(key, public_model_id, api_surface, request_features)

Rezultat bi trebao identificirati kompatibilnu reviziju kataloga i jednu ili više prihvatljivih ruta. Na primjer, model može podržavati chat.completions, ali ne i responses, ili podržavati odgovore samo ako nema ugrađenih alata. Jedan Booleov kao što je supports_responses može biti nedovoljan kada kompatibilnost ovisi o traženim značajkama.

Preporuka: objavite konzervativne mogućnosti. Oglašavajte značajku samo kada je pristupnik može nametnuti u prihvatljivom skupu ruta ili može odabrati rutu koja je deterministički podržava. Ne izvodite zaključke o unosu slike, pozivu alata ili strukturiranom izlazu iz imena obitelji pružatelja.

Očuvajte SDK kompatibilnost uz dodavanje metapodataka

Održavajte stabilna standardna polja koja očekuju OpenAI-kompatibilni klijenti:

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

Proširenje prostora imena smanjuje rizik od kolizije, ali neki klijenti odbacuju nepoznata polja. Ako aplikacije trebaju detaljne podatke o odabiru, osigurajte zasebnu autentificiranu krajnju točku informacija o modelu s verziranom shemom. Neka /v1/models bude dovoljno mali za SDK-ove, alate naredbenog retka i birače modela.

Odaberite stabilne ili zdravstveno filtrirane popise

Postoje dva pravila razumne dostupnosti.

Katalog filtriran prema ispravnosti: sakrijte model kada nijedna ruta trenutno nije ispravna. Ovo minimizira neuspjele pozive, ali katalozi mogu fluktuirati tijekom incidenata i poništiti odabire na strani klijenta.

Stabilni katalog: nastavite s popisom naslovljenih proizvoda uz izvješćivanje availability: temporarily_unavailable. Ovo je lakše za alate za automatizaciju i migraciju, ali klijenti i dalje mogu pokušavati pozivati ako ne razumiju proširenje.

Praktična zadana postavka je sakriti modele koji nisu implementirani, zabranjeni, povučeni ili nepodobni za vjerodajnice, dok zadržavaju privremeno nedostupne modele s eksplicitnim statusom za pouzdane klijente. Krajnja točka minimalne kompatibilnosti može izostaviti nedostupne unose ako postojeći klijenti ne mogu protumačiti metapodatke o statusu.

Predviđanje: klijenti s bogatijim odabirom modela sve će više ovisiti o metapodacima o mogućnostima i dostupnosti. Sve dok to ponašanje ne bude općenito pouzdano, pristup ruti na strani poslužitelja mora ostati mjerodavan.

Predmemorija sastavljenih kataloga bez posluživanja zastarjelih odobrenja

Sastavite kataloge izvan staze zahtjeva gdje je to moguće. Ključ predmemorije trebao bi sadržavati najmanje:

(tenant_id, key_id, entitlement_version, catalog_revision, policy_revision)

Poništi zahvaćene unose kada se promijeni članstvo u timu, dodjela modela, planovi cijena, vjerodajnice davatelja, stanje implementacije ili politika usmjeravanja. Vrijednosti kratkog vremena života nisu zamjena za događaje opoziva: čak i kratak ustajali prozor može otkriti novi zabranjeni model.

Usklađivanje davatelja može biti asinkrono. Tijekom prekida kontrolne ravnine pružatelja, sačuvajte posljednji poznati katalog, zabilježite njegovo vrijeme promatranja i spriječite da nove nesigurne rute postanu prihvatljive. Ovo održava popis responzivnim bez tretiranja ustajalog otkrića kao dokaza da je nova ruta upotrebljiva.

Testirajte katalog kao pristupni ugovor

Najjače svojstvo usklađenosti je jednostavno: za svaki model i API površinu vraćenu ključu, pristup ruti mora uspjeti pod istim katalogom i revizijom zdravlja.

Dodaj automatizirane testove za:

• Dopušteni ključ koji vidi i dohvaća svoje dodijeljene modele.
• Zabranjeni ključ koji ne vidi niti unose popisa niti dohvatljive metapodatke.
• Ograničenja tima sužavaju, umjesto da proširuju pristup ključu.
• Implementacija samo za chat koja se ne oglašava za odgovore.
• Onemogućena vjerodajnica koja uklanja svoje ovisne rute.
• Alias koji rješava očekivanu nepromjenjivu reviziju kataloga.
• Umirovljeni model nestaje iz zadanog kataloga.
• Poništenje predmemorije nakon dodjele, članstva ili promjene pravila.
• Nepoznati i skriveni ID-ovi modela koji proizvode nerazlučive javne pogreške.
• Svaka reklamirana sposobnost ima najmanje jednu prihvatljivu rutu.

Sintetička ispitivanja mogu dodati dokaz da ruta radi, ali troše kvotu, mogu koštati i ne mogu pokriti svaku kombinaciju značajki. Koristite ih za reprezentativne klase ruta i kombinirajte ih sa stanjem implementacije, provjerama vjerodajnica i stvarnim stanjem prometa.

Zabilježite dovoljno dokaza za objašnjenje odluka

Za svaki prihvaćeni ili odbijeni zahtjev, zabilježite reviziju kataloga, traženi javni ID modela, API površinu, riješenu rutu, ugovor o mogućnostima, reviziju pravila i strukturirani razlog pristupa. Izbjegavajte pohranjivanje brzog sadržaja isključivo u ovu svrhu.

Slijed implementacije je jednostavan: definirajte kanonski zapis, izgradite usklađivače pružatelja, sastavite prikaze po ključu, napravite popis i dohvatite dijeljenje jednog autorizacijskog predikata, povežite pristup ruti s istom revizijom i dodajte negativne testove prije omogućavanja predmemorije. Nakon što su ti dijelovi postavljeni, /v1/models postaje pouzdan odgovor na pitanje "što ovaj ključ može nazvati?" umjesto labavo filtriranog inventara.

Povezano čitanje

• dizajniranje Responses API sloja kompatibilnosti