Crea un catalogo tenant-aware /v1/models per un gateway multi-modello API

Un gateway non dovrebbe restituire tutti i modelli conosciuti da ogni provider connesso da GET /v1/models. Dovrebbe restituire i modelli che la chiave autenticata API è autorizzata e operativamente in grado di chiamare.

Questa distinzione è importante quando una chiave API fornisce l'accesso a più fornitori LLM. Un'unione non elaborata di cataloghi upstream può includere modelli vietati dai criteri del team, non disponibili nel piano del tenant, privi di credenziali integre, incompatibili con il API richiesto o non distribuiti nell'area richiesta. Tali voci producono selettori di modelli non funzionanti ed errori di runtime che il rilevamento avrebbe dovuto prevenire.

Il contratto pratico è più forte: ogni modello pubblicizzato deve superare gli stessi controlli di ammissione che si applicherebbero a una richiesta reale.

Definisci cosa significa "disponibile"

L'esistenza del provider è solo un input. Un modello dovrebbe apparire nel catalogo predefinito di una chiave solo quando tutte le condizioni richieste sono vere:

• Il gateway ha un prodotto pubblico configurato per il modello.
• Il tenant, il team e la chiave API hanno diritto a quel prodotto.
• Il piano commerciale applicabile ne consente l'utilizzo.
• La policy consente il modello, il fornitore, la regione e la modalità di gestione dei dati.
• Esiste almeno una distribuzione o un percorso upstream compatibile.
• Per quel percorso è disponibile una credenziale del fornitore utilizzabile.
• Il percorso supporta almeno una API superficie pubblicizzata nel catalogo.
• Il percorso è pronto dal punto di vista operativo in base ai criteri di integrità del gateway.

Espresso come operazione sugli insiemi:

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

Questa è una raccomandazione, non un reclamo sullo schema OpenAI. Lo schema standard non definisce tutti questi controlli specifici del gateway. Appartengono al piano di controllo del gateway e al compilatore del catalogo.

Normalizza il rilevamento del provider senza proxy

Fatto: le API di rilevamento dei provider espongono concetti diversi. L'elenco dei modelli di OpenAI fornisce identificatori e metadati di base, ma non una matrice di capacità completa per ogni superficie API. Anthropic distingue gli stati del ciclo di vita e può restituire informazioni più complete sulle capacità quando viene recuperato un modello o un alias. Gemini espone campi come limiti di token e metodi di generazione supportati. Microsoft Foundry potrebbe richiedere un nome di distribuzione nel campo model e una distribuzione può essere incompatibile con un particolare API anche quando esiste il modello sottostante.

Di conseguenza, l'inoltro diretto delle risposte del fornitore non è una struttura durevole. Tratta ciascun provider API come origine di riconciliazione. Converti le sue osservazioni in un record interno, quindi combinale con la configurazione del gateway e la policy del tenant.

Utilizza un record di catalogo canonico

Un utile record interno separa il contratto pubblico dall'implementazione a monte:

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

Non esporre target_id, riferimenti a credenziali o stato di routing interno tramite l'endpoint pubblico standard. Questi campi sono dati del piano di controllo. Tienili a disposizione per l'ammissione al percorso, gli strumenti di supporto e l'attribuzione dell'utilizzo.

ID, alias e implementazioni separate

Un ID modello pubblico è un contratto cliente. Un ID modello del provider identifica una famiglia o una versione del modello upstream. Un nome di distribuzione identifica una risorsa di servizio creata dall'operatore. Non sono intercambiabili.

Risolvi un alias pubblico in una revisione del catalogo immutabile prima del routing. Registra sia l'ID richiesto che la destinazione risolta nell'evento di utilizzo. Se l'alias cambia in seguito, il personale di supporto può comunque ricostruire quale distribuzione ha gestito una chiamata precedente.

Compila il catalogo per la chiave autenticata

Il compilatore del catalogo deve ricevere un'entità autenticata, non semplicemente un ID tenant. Lo stesso tenant può avere chiavi di produzione, chiavi di sviluppo, chiavi cliente limitate e account di servizio con concessioni di modelli diversi.

Una sequenza di compilazione deterministica è:

1. Carica la revisione del catalogo base immutabile.
2. Risolvi l'appartenenza al tenant, l'appartenenza al team e le sovvenzioni specifiche per le chiavi.
3. Applica restrizioni relative a piano, area geografica, residenza dei dati e fornitore.
4. Rimuovi percorsi senza credenziali valide o distribuzioni compatibili.
5. Valuta la disponibilità del percorso utilizzando l'istantanea dello stato corrente.
6. Aggrega le rotte sopravvissute nei record del modello pubblico.
7. Restituisce solo API superfici supportate da almeno un percorso sopravvissuto.

Utilizza la semantica dell'intersezione quando esistono sia concessioni di team che chiavi. Una chiave assegnata a un team ristretto non dovrebbe garantire un accesso più ampio semplicemente perché l'inquilino possiede un piano più ampio. Ciò rende il controllo degli accessi del modello AI per i team software prevedibile e riduce la divulgazione accidentale.

Mantieni identico il comportamento dell'elenco e del recupero

GET /v1/models/{model} deve eseguire lo stesso predicato di autorizzazione dell'operazione di elenco. Altrimenti, un utente malintenzionato può enumerare gli identificatori nascosti confrontando le risposte riuscite, vietate e non trovate.

Per un modello che la chiave non può vedere, restituisce lo stesso errore pubblico utilizzato per un modello sconosciuto. Non rivelare se un altro tenant può utilizzarlo, quale provider lo ospita o quale diritto lo sbloccherebbe. Le API amministrative possono esporre ragioni più dettagliate agli operatori autorizzati.

Rappresenta API la compatibilità in modo esplicito

L'esistenza di un modello non implica il supporto per ogni endpoint. Completamenti chat, risposte, incorporamenti, generazione di immagini, tempo reale, batch e Anthropic Messaggi hanno contratti di richiesta e streaming diversi.

L'ammissione al percorso dovrebbe quindi accettare sia un modello che una API superficie:

admit(key, public_model_id, api_surface, request_features)

Il risultato dovrebbe identificare una revisione del catalogo compatibile e uno o più percorsi idonei. Ad esempio, un modello può supportare chat.completions ma non responses oppure supportare le risposte solo quando sono assenti gli strumenti integrati. Un singolo valore booleano come supports_responses potrebbe non essere sufficiente quando la compatibilità dipende dalle funzionalità richieste.

Raccomandazione: pubblica funzionalità conservative. Pubblicizzare una funzionalità solo quando il gateway può applicarla sul set di percorsi idonei o può selezionare un percorso che la supporti in modo deterministico. Non dedurre input di immagini, chiamate di strumenti o output strutturato dal nome della famiglia di un provider.

Preserva SDK la compatibilità aggiungendo metadati

Mantieni stabili i campi standard previsti dai client compatibili con OpenAI:

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

Un'estensione con spazio dei nomi riduce il rischio di collisione, ma alcuni client scartano campi sconosciuti. Se le applicazioni necessitano di dati di selezione dettagliati, fornire un endpoint di informazioni sul modello autenticato separato con uno schema con versione. Mantieni /v1/models abbastanza piccolo per SDK, strumenti da riga di comando e selettori di modelli.

Scegli elenchi stabili o con filtri sanitari

Esistono due politiche di disponibilità ragionevoli.

Catalogo filtrato in base all'integrità: nasconde un modello quando nessun percorso è attualmente integro. Ciò riduce al minimo le chiamate non riuscite, ma i cataloghi possono fluttuare durante gli incidenti e invalidare le selezioni lato client.

Catalogo stabile: continua a elencare i prodotti autorizzati segnalando availability: temporarily_unavailable. Ciò è più semplice per gli strumenti di automazione e migrazione, ma i clienti possono comunque tentare le chiamate a meno che non comprendano l'estensione.

Un'impostazione pratica pratica consiste nel nascondere i modelli non distribuiti, vietati, ritirati o non idonei per le credenziali, mantenendo al tempo stesso i modelli temporaneamente non disponibili con uno stato esplicito per i client attendibili. L'endpoint di compatibilità minima può omettere le voci non disponibili se i client esistenti non riescono a interpretare i metadati dello stato.

Previsione: i clienti con una selezione di modelli più ricca dipenderanno sempre più dai metadati di capacità e disponibilità. Fino a quando tale comportamento non sarà ampiamente affidabile, l'ammissione del percorso lato server deve rimanere autorevole.

Memorizza nella cache i cataloghi compilati senza fornire concessioni obsolete

Compila cataloghi all'esterno del percorso della richiesta, ove possibile. Una chiave di cache dovrebbe includere almeno:

(tenant_id, key_id, entitlement_version, catalog_revision, policy_revision)

Invalida le voci interessate quando cambiano l'appartenenza al team, le concessioni dei modelli, i piani tariffari, le credenziali del fornitore, lo stato di distribuzione o i criteri di routing. I valori con durata di vita breve non sostituiscono gli eventi di revoca: anche una breve finestra obsoleta può esporre un nuovo modello proibito.

La riconciliazione del fornitore può essere asincrona. Durante un'interruzione del piano di controllo del fornitore, preserva l'ultimo catalogo conosciuto, registra il tempo di osservazione e impedisci che nuove rotte incerte diventino idonee. Ciò mantiene l'elenco reattivo senza considerare la scoperta obsoleta come prova che un nuovo percorso è utilizzabile.

Prova il catalogo come contratto di ammissione

La proprietà di conformità più forte è semplice: per ogni modello e API superficie restituita a una chiave, l'ammissione del percorso deve avere esito positivo con lo stesso catalogo e revisione di integrità.

Aggiungi test automatizzati per:

• Una chiave autorizzata a visualizzare e recuperare i modelli assegnati.
• Una chiave vietata che non vede né le voci dell'elenco né i metadati recuperabili.
• Le restrizioni del team restringono, anziché ampliare, l'accesso alle chiavi.
• Un'implementazione di sola chat non pubblicizzata per le risposte.
• Una credenziale disabilitata che rimuove i suoi percorsi dipendenti.
• Un alias che risolve la revisione immutabile prevista del catalogo.
• Un modello ritirato che scompare dal catalogo predefinito.
• Invalidamento della cache dopo la modifica di sovvenzioni, abbonamenti o norme.
• ID modello sconosciuti e nascosti che producono errori pubblici indistinguibili.
• Ogni funzionalità pubblicizzata ha almeno un percorso idoneo.

Le sonde sintetiche possono aggiungere prove del funzionamento di un percorso, ma consumano quota, possono costare denaro e non possono coprire tutte le combinazioni di funzionalità. Utilizzali per classi di percorsi rappresentativi e combinali con lo stato di distribuzione, i controlli delle credenziali e lo stato reale del traffico.

Registrare prove sufficienti per spiegare le decisioni

Per ogni richiesta accettata o rifiutata, registrare la revisione del catalogo, l'ID del modello pubblico richiesto, la API superficie, il percorso risolto, il contratto di capacità, la revisione della policy e un motivo di ammissione strutturato. Evita di archiviare contenuti immediati esclusivamente per questo scopo.

La sequenza di implementazione è semplice: definire il record canonico, creare riconciliatori del provider, compilare visualizzazioni per chiave, creare elenchi e recuperare condividere un predicato di autorizzazione, connettere l'ammissione del percorso alla stessa revisione e aggiungere test negativi prima di abilitare le cache. Una volta che questi pezzi sono a posto, /v1/models diventa una risposta affidabile alla domanda "come può chiamare questa chiave?" anziché un inventario vagamente filtrato.

Lettura correlata

• progettazione di un livello di compatibilità delle risposte API