Bérlő-tudatos /v1/models katalógus készítése többmodell API átjáróhoz
A modellfelderítést engedélyezési és útvonal-készenléti szerződésként kezelje. Készítsen egy bérlő-tudatos /v1/models katalógust, amely csak azokat a modelleket sorolja fel, amelyeket az egyes API kulcsok használhatnak az egyes támogatott API felületeken.
Egy átjáró nem adhat vissza minden olyan modellt, amelyet minden csatlakoztatott szolgáltató ismer a GET /v1/models-tól. Azokat a modelleket kell visszaadnia, amelyeket a hitelesített API kulcs jogosult és működésileg hívható.
Ez a megkülönböztetés akkor számít, ha egy API kulcs több LLM-szolgáltatóhoz biztosít hozzáférést. Az upstream katalógusok nyers uniója tartalmazhat olyan modelleket, amelyeket a csapatszabályzat tilt, a bérlő terve szerint nem érhetők el, hiányzik az egészséges hitelesítési adat, nem kompatibilis a kért API számmal, vagy nincsenek a kívánt régióban telepítve. Ezek a bejegyzések hibás modellválasztókat és futásidejű hibákat eredményeznek, amelyeket a felfedezésnek meg kellett volna akadályoznia.
A gyakorlati szerződés erősebb: minden meghirdetett modellnek ugyanazon a felvételi ellenőrzésen kell átesnie, mint egy valódi kérésre.
Határozza meg, mit jelent az „elérhető”
A szolgáltató létezése csak egy bemenet. A modell csak akkor jelenhet meg a kulcs alapértelmezett katalógusában, ha minden szükséges feltétel teljesül:
- Az átjáró rendelkezik egy konfigurált nyilvános termékkel a modellhez.
- A bérlő, a csapat és a API kulcs jogosult a termékre.
- A vonatkozó kereskedelmi terv lehetővé teszi a használatát.
- A házirend lehetővé teszi a modellt, a szolgáltatót, a régiót és az adatkezelési módot.
- Legalább egy kompatibilis upstream telepítés vagy útvonal létezik.
- Az útvonalhoz használható szolgáltatói hitelesítési adatok állnak rendelkezésre.
- Az útvonal legalább egy, a katalógusban meghirdetett API felületet támogat.
- Az útvonal üzemkész az átjáró egészségügyi szabályzata értelmében.
Beállított műveletként kifejezve:
visible_models(key) =
configured_products
∩ tenant_entitlements
∩ team_grants
∩ key_grants
∩ commercial_rights
∩ policy_eligible_routes
∩ compatible_deployments
∩ operationally_ready_routesEz egy ajánlás, nem pedig a OpenAI sémával kapcsolatos állítás. A szabványos séma nem határozza meg az összes átjáró-specifikus vezérlőt. Az átjáró vezérlősíkjába és katalógusfordítójába tartoznak.
A szolgáltató felderítésének normalizálása proxy nélkül
Tény: A szolgáltató-felderítési API-k különböző fogalmakat tesznek közzé. A OpenAI modelllistája azonosítókat és alapvető metaadatokat tartalmaz, de nem teljes képességmátrixot minden API felülethez. A Anthropic megkülönbözteti az életciklus-állapotokat, és gazdagabb képességinformációkat tud visszaadni egy modell vagy álnév lekérésekor. A Gemini olyan mezőket tesz közzé, mint a tokenkorlátok és a támogatott generálási módszerek. A Microsoft Foundry megkövetelheti a telepítési név megadását a model mezőben, és előfordulhat, hogy a központi telepítés nem kompatibilis egy adott API számmal, még akkor is, ha az alapul szolgáló modell létezik.
Ennek következtében a szolgáltatói válaszok közvetlen továbbítása nem egy tartós megoldás. Minden egyes szolgáltatót API kezeljen egyeztetési forrásként. A megfigyeléseket alakítsa át belső rekordokká, majd kombinálja őket átjárókonfigurációval és bérlői szabályzattal.
Kanonikus katalógusrekord használata
Egy hasznos belső rekord választja el a közbeszerzési szerződést az upstream megvalósítástól:
{
"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 tegye ki a target_id, hitelesítő adatok hivatkozásait vagy belső útválasztási állapotát a szabványos nyilvános végponton keresztül. Ezek a mezők vezérlősík adatok. Tartsa elérhetővé őket a hozzáférési útvonalak, a támogatási eszközök és a használati hozzárendelés érdekében.
Külön azonosítók, álnevek és telepítések
A nyilvános modellazonosító egy ügyfélszerződés. A szolgáltatói modellazonosító azonosít egy upstream modellcsaládot vagy verziót. A telepítési név azonosítja az operátor által létrehozott kiszolgáló erőforrást. Nem cserélhetők fel.
A nyilvános alias feloldása egy megváltoztathatatlan katalógus-revízióra az útválasztás előtt. Rögzítse mind a kért azonosítót, mind a megoldott célt a használati eseményben. Ha az alias később megváltozik, a támogató személyzet továbbra is rekonstruálhatja, hogy melyik telepítés kezelte a korábbi hívást.
A hitelesített kulcs katalógusának összeállítása
A katalógus-fordítónak hitelesített megbízót kell kapnia, nem csupán bérlői azonosítót. Ugyanannak a bérlőnek lehetnek termelési kulcsai, fejlesztési kulcsai, korlátozott ügyfélkulcsai és szolgáltatási fiókjai különböző modellengedélyekkel.
Egy determinisztikus fordítási sorozat a következő:
- Töltse be a megváltoztathatatlan alapkatalógus-változatot.
- Bérlői tagság, csapattagság és kulcsspecifikus támogatások megoldása.
- Alkalmazza a tervre, a földrajzi elhelyezkedésre, az adatok tartózkodási helyére és a szolgáltatóra vonatkozó korlátozásokat.
- Érvényes hitelesítési adatok vagy kompatibilis telepítések nélküli útvonalak eltávolítása.
- Értékelje ki az útvonal készenlétét az aktuális állapotfelvétel segítségével.
- A fennmaradt útvonalak összesítése nyilvános modellrekordokba.
- Csak API olyan felület visszaküldése, amelyet legalább egy fennmaradt útvonal támogat.
Használja a metszésszemantikát, ha csapat- és kulcsengedélyek is léteznek. Egy korlátozott csoporthoz rendelt kulcs nem állíthatja vissza a szélesebb hozzáférést pusztán azért, mert a bérlő szélesebb tervvel rendelkezik. Ez kiszámíthatóvá teszi az AI-modell hozzáférés-vezérlését szoftvercsapatok számára, és csökkenti a véletlen nyilvánosságra hozatalt.
A lista tartása és a viselkedés azonos lekérése
AGET /v1/models/{model}-nek ugyanazt az engedélyezési predikátumot kell futtatnia, mint a listaműveletnek. Ellenkező esetben a támadó a sikeres, a tiltott és a nem található válaszok összehasonlításával rejtett azonosítókat sorolhat fel.
Olyan modellnél, amelyet a kulcs nem lát, adja vissza ugyanazt a nyilvános hibát, mint egy ismeretlen modellnél. Ne fedje fel, hogy egy másik bérlő használhatja-e, melyik szolgáltató üzemelteti, vagy melyik jogosultság oldja fel a zárolást. Az adminisztratív API-k részletesebb okokat tárhatnak fel a jogosult kezelők előtt.
Kifejezetten képviseli a API kompatibilitást
Egy modell létezése nem jelenti az összes végpont támogatását. A csevegés befejezése, a válaszok, a beágyazások, a képgenerálás, a valós idejű, a kötegelt és Anthropic üzenetek különböző kérési és streamelési szerződésekkel rendelkeznek.
Az útvonalengedélynek ezért modellt és API felületet is el kell fogadnia:
admit(key, public_model_id, api_surface, request_features)Az eredménynek egy kompatibilis katalógusváltozatot és egy vagy több alkalmas útvonalat kell azonosítania. Például egy modell támogatja a chat.completions, de nem a responses jelet, vagy csak akkor támogatja a válaszokat, ha a beépített eszközök hiányoznak. Egyetlen logikai érték, például supports_responses, nem lehet elegendő, ha a kompatibilitás a kért szolgáltatásoktól függ.
Javaslat: tegye közzé a konzervatív képességeket. Csak akkor hirdessen egy funkciót, ha az átjáró kényszerítheti azt a jogosult útvonalkészleten keresztül, vagy kiválaszthat egy olyan útvonalat, amely determinisztikusan támogatja azt. Ne következtessen képbevitelre, eszközhívásra vagy strukturált kimenetre a szolgáltató családnevéből.
A SDK kompatibilitás megőrzése metaadatok hozzáadása közben
Tartsa stabilan a OpenAI-kompatibilis ügyfelek által elvárt szabványos mezőket:
{
"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"
}
}A névteres bővítmény csökkenti az ütközések kockázatát, de egyes ügyfelek elvetik az ismeretlen mezőket. Ha az alkalmazásoknak részletes kiválasztási adatokra van szükségük, adjon meg egy külön hitelesített modellinformációs végpontot egy verziószámmal ellátott sémával. A /v1/models legyen elég kicsi az SDK-k, parancssori eszközök és modellválasztók számára.
Válasszon stabil vagy egészségügyi szempontból szűrt listákat
Két ésszerű rendelkezésre állási szabályzat létezik.
Egészségügyi szűrésű katalógus: modell elrejtése, ha jelenleg nincs egészséges útvonal. Ez minimalizálja a sikertelen hívások számát, de a katalógusok ingadozhatnak incidensek során, és érvényteleníthetik az ügyféloldali kiválasztásokat.
Stabil katalógus: Folytassa a megnevezett termékek felsorolását a availability: temporarily_unavailable bejelentése közben. Ez egyszerűbb az automatizálás és az áttelepítés eszközei számára, de az ügyfelek továbbra is próbálkozhatnak hívásokkal, hacsak nem értik a melléket.
Gyakorlati alapértelmezés az, hogy elrejti a nem telepített, tiltott, visszavont vagy hitelesítő adatokkal nem rendelkező modelleket, miközben megtartja az ideiglenesen nem elérhető modelleket, amelyek kifejezetten megbízható ügyfelek státuszával rendelkeznek. A minimális kompatibilitási végpont kihagyhatja a nem elérhető bejegyzéseket, ha a meglévő ügyfelek nem tudják értelmezni az állapotmetaadatokat.
Előrejelzés: A gazdagabb modellválasztó kliensek egyre inkább függnek a képességektől és a rendelkezésre állási metaadatoktól. Amíg ez a viselkedés nagyjából megbízható, a szerveroldali útvonalengedélynek mérvadónak kell maradnia.
Az összeállított katalógusok gyorsítótárazása elavult támogatások nélkül
Ha lehetséges, állítson össze katalógusokat a kérési útvonalon kívül. A gyorsítótár kulcsának legalább a következőket kell tartalmaznia:
(tenant_id, key_id, entitlement_version, catalog_revision, policy_revision)Érvénytelenítse az érintett bejegyzéseket, ha megváltozik a csapattagság, a modelltámogatások, az árképzési tervek, a szolgáltatói hitelesítési adatok, a telepítési állapot vagy az útválasztási szabályzat. A rövid élettartamú értékek nem helyettesítik a visszavonási eseményeket: még egy rövid elavult ablak is felfedhet egy újonnan tiltott modellt.
A szolgáltatói egyeztetés lehet aszinkron is. A szolgáltatói vezérlősík leállása során őrizze meg az utolsó ismert katalógust, rögzítse annak megfigyelési idejét, és akadályozza meg, hogy az újonnan bizonytalan útvonalak jogosulttá váljanak. Ezzel a listázás továbbra is érzékeny marad anélkül, hogy az elavult felfedezést annak bizonyítékaként kezelné, hogy egy új útvonal használható.
Tesztelje be a katalógust felvételi szerződésként
A legerősebb megfelelőségi tulajdonság egyszerű: minden modellhez és API felülethez, amelyet egy kulcshoz visszaküldenek, az útvonalra való belépést ugyanazon katalógus és állapotfelülvizsgálat alapján kell végrehajtani.
Automatikus tesztek hozzáadása a következőhöz:
- Egy engedélyezett kulcs a hozzárendelt modellek megtekintésére és lekérésére.
- Tiltott kulcs, amely nem lát sem listabejegyzéseket, sem visszakereshető metaadatokat.
- A csapatkorlátozások szűkítik, nem pedig szélesítik a kulcsokhoz való hozzáférést.
- Csak csevegést biztosító telepítést nem hirdetnek a Responses számára.
- Egy letiltott hitelesítő adat eltávolítja a függő útvonalait.
- Egy álnév, amely a várható megváltoztathatatlan katalógus-revízióra felel meg.
- Egy visszavonult modell eltűnik az alapértelmezett katalógusból.
- A gyorsítótár érvénytelenítése a támogatások, a tagságok vagy az irányelvek módosítása után.
- Ismeretlen és rejtett modellazonosítók, amelyek megkülönböztethetetlen nyilvános hibákat okoznak.
- Minden meghirdetett lehetőség legalább egy alkalmas útvonallal rendelkezik.
A szintetikus szondák bizonyítékot adhatnak arra, hogy egy útvonal működik, de kvótát fogyasztanak, pénzbe kerülhetnek, és nem képesek minden funkciókombinációt lefedni. Használja őket reprezentatív útvonalosztályokhoz, és kombinálja őket a telepítési állapottal, a hitelesítő adatok ellenőrzésével és a valós forgalmi állapottal.
Rögzítsen elegendő bizonyítékot a döntések magyarázatához
Minden elfogadott vagy elutasított kérelemnél jegyezze fel a katalógus átdolgozását, a kért nyilvános modellazonosítót, a API felületet, a megoldott útvonalat, a képességszerződést, a szabályzat felülvizsgálatát és a strukturált felvételi okot. Kerülje a felszólító tartalom kizárólag erre a célra való tárolását.
A megvalósítási sorrend egyszerű: definiálja a kanonikus rekordot, hozzon létre szolgáltatói egyeztetőket, állítson össze kulcsonkénti nézeteket, hozzon létre listát és kérjen le egyetlen engedélyezési predikátumot, kapcsolja össze az útvonal-engedélyezést ugyanahhoz a változathoz, és adjon hozzá negatív teszteket a gyorsítótárak engedélyezése előtt. Ha ezek a darabok a helyükre kerültek, a /v1/models megbízható válasz lesz a „mit hívhat ez a kulcs?” kérdésre. a lazán szűrt készlet helyett.