Come creare un'API LLM partner senza esporre le chiavi grezze del provider

Un partner API per l'accesso LLM non dovrebbe essere un sottile involucro attorno alle chiavi del fornitore. Se partner, rivenditori o applicazioni dei clienti necessitano di accesso delegato ai modelli linguistici, la piattaforma necessita di un proprio piano di controllo, gateway, livello di policy, pipeline di misurazione e runbook operativi. In caso contrario, la fatturazione a livello di fornitore, i limiti a livello di fornitore e le credenziali condivise diventeranno gli unici controlli tra l'integrazione di un partner e un incidente molto costoso.

L'obiettivo è semplice: consentire a soggetti esterni di utilizzare le funzionalità LLM attraverso la tua piattaforma mantenendo private le credenziali del fornitore a monte, applicando diritti specifici del partner, misurando l'utilizzo fatturabile e offrendo ai partner sufficiente trasparenza per creare clienti affidabili.

Architettura di riferimento

Un partner pratico API è composto da due parti principali: un piano di controllo e un gateway di richiesta.

Il piano di controllo gestisce le organizzazioni partner, le applicazioni, gli ambienti, le chiavi delegate API, i diritti dei modelli, i livelli di limite di velocità, i limiti di spesa, i termini di fatturazione, gli endpoint webhook e i record di controllo. È qui che le regole commerciali e operative diventano policy leggibili dalle macchine.

Il gateway di richiesta riceve il traffico del partner, autentica la chiave delegata, valuta la policy, applica la quota, instrada al provider del modello selezionato, registra l'utilizzo e restituisce metadati di risposta visibili al partner. In un LLM aziendale maturo API, questo gateway è anche il luogo in cui il routing del modello, i nuovi tentativi, il failover, i controlli dei contenuti e l'osservabilità vengono applicati in modo coerente.

Il limite importante è questo: i partner ricevono solo le chiavi emesse dalla tua piattaforma. Non ricevono mai le credenziali grezze del fornitore. Le chiavi del provider upstream rimangono nell'archivio segreto della tua piattaforma e vengono utilizzate solo dal gateway o dai lavoratori backend.

Modello di fatto attorno al quale costruire

Quelli che seguono sono fatti supportati dalla piattaforma pubblica e dalla documentazione cloud, non supposizioni su una singola implementazione:

• Alcuni fornitori LLM supportano chiavi con ambito di progetto, account di servizio, accesso ai modelli a livello di progetto e limiti di tariffa a livello di progetto.
• Le linee guida cloud per le API SaaS multi-tenant separano comunemente l'amministrazione delle policy, la decisione e l'applicazione delle policy per ridurre l'accesso accidentale tra tenant.
• API gateway e piani di controllo SaaS possono applicare limitazioni e controlli delle quote specifici del tenant, inclusi livelli di velocità, burst e quota.
• La fatturazione SaaS basata sull'utilizzo dipende dalla raccolta dell'attività del tenant, dall'aggregazione e dalla riconciliazione con i record di fatturazione.
• Le chiavi di idempotenza sono un modello documentato per ritentare in modo sicuro le richieste di modifica dello stato API senza creare effetti collaterali duplicati.
• Le intestazioni di risposta al limite di velocità standardizzate possono aiutare i clienti a comprendere i limiti, la quantità rimanente, i tempi di reimpostazione e il comportamento dei nuovi tentativi.

Il consiglio è di combinare questi modelli in un livello di accesso LLM rivolto ai partner di tua proprietà, invece di chiedere a ogni partner di integrarsi direttamente con ciascun fornitore di modelli upstream.

Passaggio 1: definisci il tenant e il modello di identità

Non identificare il traffico dei partner con una sola stringa di chiavi API. Un partner utile API necessita di identificatori separati perché la fatturazione, la revisione degli abusi, il debug delle quote e le indagini sull'assistenza spesso pongono domande diverse.

Come minimo, crea identificatori per:

• Organizzazione partner: la società esterna incaricata.
• Applicazione partner: un'integrazione, un prodotto, un plug-in o un'applicazione del rivenditore specifica.
• Ambiente: produzione, gestione temporanea, sandbox o sviluppo.
• Cliente finale: il cliente, l'area di lavoro, l'account o il tenant del partner, quando consentito contrattualmente e tecnicamente disponibile.
• API chiave: la credenziale delegata utilizzata per autenticare le richieste.
• ID richiesta: un identificatore univoco per tracciare una richiesta attraverso il gateway, chiamate al provider, eventi di utilizzo e log di supporto.

Questa struttura evita la comune modalità di errore in cui un'integrazione compromessa o rumorosa può essere descritta solo come "traffico del partner X". Ti consente inoltre di sospendere un'applicazione o un ambiente senza disabilitare l'intera attività del partner.

Passaggio 2: rilascia le chiavi del partner delegato

Le chiavi partner devono essere oggetti della piattaforma di prima classe, non token statici in un foglio di lavoro. Ogni chiave deve avere metadati e associazioni di policy:

• ID organizzazione partner
• ID domanda
• Ambiente
• Sono consentiteAPI superfici, ad esempio chat, incorporamenti, batch o generazione di immagini
• Alias del modello consentiti
• Vincoli regionali o di residenza dei dati, ove applicabile
• Livello limite di tariffa
• Regola del limite di spesa o del saldo prepagato
• Ora di creazione, ora dell'ultimo utilizzo, proprietario e stato di rotazione

Archivia solo il materiale delle chiavi sottoposte ad hashing, ove possibile, espone i segreti completi solo una volta al momento della creazione e supporta la rotazione senza tempi di inattività. Un pratico modello di rotazione consente due chiavi attive durante una breve finestra di transizione, con log di controllo che mostrano quale chiave è stata utilizzata per ciascuna richiesta.

Passaggio 3: separa i diritti dal routing

Il diritto di un partner di utilizzare un modello non dovrebbe essere implicito nel codice di routing attualmente supportato. Mantieni i controlli dei diritti espliciti e separati dalla selezione del fornitore.

Ad esempio, una richiesta per model: premium-reasoning dovrebbe prima superare una decisione relativa alle norme:

• Questo partner è autorizzato a utilizzare l'alias del modello?
• L'applicazione partner è autorizzata a utilizzarlo in questo ambiente?
• La richiesta si trova all'interno della regione consentita o del confine dati?
• Il contratto è attivo e in regola?
• Il partner rientra nelle soglie di spesa, quota e abuso?

Solo dopo tale decisione il routing dovrebbe scegliere il provider upstream, il progetto del provider, il deploy o il percorso di fallback. Ciò è importante perché le modifiche al routing del modello sono frequenti dal punto di vista operativo. Le modifiche ai diritti dovrebbero essere deliberate e controllabili.

Passaggio 4: pubblica un partner stabile API Superficie

I partner necessitano di un comportamento stabile anche quando i fornitori a monte cambiano. Utilizza gli alias del tuo modello e le descrizioni delle funzionalità invece di esporre direttamente il nome del modello di ogni fornitore.

Un piccolo esempio:

POST /v1/chat/completions
Authorization: Bearer partner_key_...
Idempotency-Key: job_01J7...
X-Partner-Customer-Id: customer_123

{
  "model": "standard-chat",
  "messages": [
    {"role": "user", "content": "Summarize this support thread."}
  ],
  "metadata": {
    "ticket_id": "T-44821",
    "workflow": "support_summary"
  }
}

Il partner richiede standard-chat. Il tuo gateway associa l'alias al provider e al modello attualmente approvati, in base a diritti, disponibilità, prezzo, latenza, regione e regole di qualità.

Evita però di nascondere tutte le differenze tra i fornitori. Se due alias di modello hanno finestre di contesto, supporto di output strutturato, comportamento di chiamata degli strumenti, profili di latenza o disponibilità regionale diversi, documenta chiaramente tali differenze. L'astrazione dovrebbe semplificare l'integrazione, non creare comportamenti sorprendenti.

Passaggio 5: applica le quote prima delle chiamate al fornitore

I limiti dei fornitori sono dei limiti utili, ma l'applicazione a livello di partner rientra nella tua piattaforma. Un progetto di un fornitore a monte può servire molti partner, oppure un partner può avere diverse applicazioni con contratti diversi. Affidarsi solo ai limiti tariffari a livello di fornitore non può esprimere queste distinzioni in modo chiaro.

Applica i controlli delle quote prima di effettuare chiamate upstream:

• Richieste al minuto per chiave partner
• Token al minuto per organizzazione partner
• Richieste simultanee per applicazione
• Quota di unità fatturabili giornaliera o mensile
• Saldo prepagato o soglia di credito
• Limiti per cliente finale ove richiesto

Per le richieste sincrone, rifiutare chiaramente quando la richiesta non può essere accettata. Per i carichi di lavoro asincroni e batch, considera l'ammissione alla coda separatamente dalla quota di esecuzione. È possibile accettare un caricamento in batch, ma i singoli processi devono comunque essere misurati e interrotti quando vengono raggiunti i limiti dei partner.

Passaggio 6: restituisci segnali di limite di velocità prevedibili

429 Too Many Requests risposte opache creano ticket di supporto evitabili. Restituisce segnali di quota visibili al partner in caso di risposte riuscite e limitate.

Una risposta utile può includere:

RateLimit-Limit: 600;w=60
RateLimit-Remaining: 42
RateLimit-Reset: 17
Retry-After: 17
X-Request-Id: req_01J8...

Consigli:

• Documenta se si applicano limiti per chiave, applicazione, organizzazione, modello o endpoint.
• Tempi di reimpostazione della restituzione su cui i client possono agire.
• Utilizza Retry-After per risposte limitate.
• Mantieni i corpi degli errori stabili e leggibili dal computer.
• Non esporre i componenti interni del provider upstream a meno che i partner non ne abbiano bisogno per eseguire il debug del comportamento.

Ciò semplifica la creazione di client partner e riduce le tempeste di nuovi tentativi durante i picchi di traffico.

Passaggio 7: utilizza l'idempotenza per il lavoro fatturabile

Qualsiasi endpoint che crea lavoro statale o fatturabile deve supportare le chiavi di idempotenza. Ciò è particolarmente importante per processi di generazione asincrona, invii batch, acquisti di crediti, tentativi attivati da webhook e attività a lunga esecuzione.

La regola di implementazione è semplice: quando un partner ripete la stessa richiesta con la stessa chiave di idempotenza all'interno della finestra di conservazione, restituisce il risultato originale invece di creare lavoro duplicato.

Rendi espliciti i casi limite:

• Per quanto tempo vengono conservati i record di idempotenza
• A quale endpoint e chiave partner è limitata la chiave di idempotenza
• Cosa succede se la stessa chiave viene riutilizzata con parametri di richiesta diversi
• Se le richieste non riuscite vengono memorizzate nella cache
• Come si applica l'idempotenza ai job batch parzialmente completati

Per il lavoro LLM fatturabile, archivia dati sufficienti sulle impronte digitali delle richieste per rilevare le mancate corrispondenze dei parametri senza conservare contenuti di payload sensibili non necessari.

Passaggio 8: genera eventi di utilizzo immutabili

Non considerare le fatture del fornitore come fonte di verità per la fatturazione dei partner. Le fatture dei fornitori di solito non conoscono i contratti dei partner, le regole di markup, i livelli dei rivenditori, gli ID dei clienti finali o il flusso di lavoro delle controversie. Emetti invece un evento di utilizzo immutabile quando ciascuna richiesta raggiunge uno stato terminale.

Un evento di utilizzo dovrebbe includere:

• ID organizzazione partner
• ID applicazione e ambiente
• API ID chiave, non la chiave non elaborata
• ID cliente finale se fornito e consentito
• ID richiesta e ID correlazione fornitore
• Alias del modello e modello del fornitore a monte
• Token di input, token di output, token memorizzati nella cache o altre unità fatturabili
• Base dei costi del fornitore quando disponibile
• Unità di fatturazione del partner, margine di profitto, prelievo di credito o tariffa del contratto
• Stato, classe di errore, latenza e numero di tentativi
• Timestamp e versione dello schema

Questi eventi alimentano dashboard dei partner, esportazioni di fatturazione, rilevamento di anomalie, contatori delle quote e riconciliazione. Mantieni il flusso di eventi di sola aggiunta. Le correzioni dovrebbero essere eventi di aggiustamento, non modifiche silenziose.

Passaggio 9: riconcilia ogni giorno

La misurazione è utile solo se riconcilia. Crea un processo quotidiano che confronti i tuoi eventi di utilizzo con l'utilizzo del fornitore a monte, le fatture del fornitore, i saldi del credito e i record di fatturazione rivolti ai partner.

Il processo di riconciliazione dovrebbe identificare:

• Richieste accettate dal gateway ma mancano eventi di utilizzo del terminale
• Utilizzo del provider che non può essere mappato a una richiesta del partner
• Differenze nel conteggio dei token tra i report del provider e i record del gateway
• Tentativi fatturati in modo errato
• Accrediti manuali, rimborsi e correzioni di fatturazione
• Partner prossimi all'impegno di spesa, esaurimento del prepagato o crescita insolita

Questo è anche il luogo in cui finanza, supporto e ingegneria necessitano degli stessi ID. Se il dashboard, la voce della fattura, l'evento di registro e il record del fornitore non possono essere collegati insieme, le controversie diventano indagini manuali.

Passaggio 10: crea runbook operativi

Un partner API è una superficie di prodotto esterna, quindi il comportamento operativo deve essere pianificato prima che si verifichino incidenti. Come minimo, scrivi runbook per queste situazioni:

• Chiave partner compromessa: revoca o sospende una chiave, avvisa il partner, conserva i log di controllo e fornisci un percorso di rotazione.
• Utilizzo fuori controllo: applica limiti di emergenza, metti in pausa un'applicazione o richiedi l'approvazione per un ulteriore utilizzo.
• Interruzione del provider: failover su un provider approvato o restituzione di un errore stabile con indicazioni per nuovi tentativi.
• Esaurimento quota: mostra se il partner deve attendere, eseguire l'upgrade, acquistare crediti o ridurre il traffico.
• Riproduzione webhook: verifica le firme, utilizza l'idempotenza e monitora i tentativi di recapito degli eventi.
• Correzione della fatturazione: crea eventi di aggiustamento e preserva i record di utilizzo originali.

I runbook dovrebbero definire chi può eseguire ciascuna azione. Sospendere una chiave è diverso dalla disabilitazione di un'organizzazione partner. Aumentare una quota è diverso dalla modifica di un contratto. I controlli di emergenza necessitano di audit trail.

Compromessi

Un gateway Partner API aggiunge latenza e responsabilità operativa. Questo è il costo del controllo di credenziali, quote, routing, fatturazione e visibilità a livello di contratto del partner.

Quote rigorose proteggono i margini e riducono gli abusi, ma possono creare errori inutili se il comportamento burst e le indicazioni per i nuovi tentativi non sono progettati correttamente. Un sistema di quote utile prevede limiti rigidi e comportamento burst documentato.

La misurazione dettagliata migliora la trasparenza della fatturazione e i risultati del supporto, ma aumenta gli obblighi di fidelizzazione, privacy e riconciliazione. Raccogli gli identificatori necessari per le operazioni e la fatturazione, ma evita di archiviare contenuti grezzi di richieste e risposte nei record di fatturazione a meno che non vi siano chiare basi contrattuali e di conformità.

L'astrazione del modello semplifica le integrazioni dei partner, ma un'astrazione eccessiva può nascondere differenze sostanziali. I partner non hanno bisogno di conoscere tutti i dettagli di implementazione del provider, ma devono sapere quando un alias del modello cambia i limiti del contesto, i formati di output, le aspettative di latenza o la disponibilità regionale.

Elenco di controllo per l'implementazione

• Rilascia chiavi partner di proprietà della piattaforma invece di condividere le credenziali del fornitore.
• Mappona ogni chiave a partner, applicazione, ambiente, diritti, quota e record di fatturazione.
• Mantieni i controlli di autorizzazione e diritti separati dalla logica di routing.
• Utilizza alias di modelli stabili con funzionalità e limiti documentati.
• Applica i controlli delle quote prima delle chiamate del provider upstream.
• Restituisce intestazioni del limite di frequenza ed errori leggibili dal computer.
• Richiedi chiavi di idempotenza per gli endpoint che creano lavoro statale o fatturabile.
• Emetti eventi di utilizzo immutabili al completamento della richiesta.
• Riconcilia l'utilizzo con i record del fornitore e le fatture dei partner.
• Mantieni runbook per compromissioni chiave, utilizzo fuori controllo, interruzione del provider, esaurimento della quota, riproduzione del webhook e correzione della fatturazione.

Conclusione attuabile

Il partner più sicuro API per l'accesso LLM non è un proxy che inoltra richieste con credenziali nascoste. Si tratta di un sistema di accesso delegato con un proprio modello di identità, livello di policy, applicazione delle quote, contatore di utilizzo, processo di riconciliazione e trasparenza nei confronti dei partner.

Inizia dai limiti del controllo: chiavi partner, diritti espliciti, controlli delle quote pre-chiamata, endpoint idempotenti con cambio di stato ed eventi di utilizzo immutabili. Aggiungi quindi la maturità operativa: dashboard, riconciliazione, semantica dei limiti di velocità e runbook sugli incidenti. Questa architettura consente ai partner di sfruttare le funzionalità LLM senza ricevere chiavi grezze del fornitore, offrendo al tempo stesso alla piattaforma un controllo sufficiente per gestire costi, abusi, affidabilità e controversie sulla fatturazione.

Lettura correlata

• progettazione di chiavi API regolamentate per integrazioni di team e partner