Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Autorizzazioni e limiti delle raccolte

Lezione 8 di 16 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Il rischio specifico delle basi di conoscenza
  2. Due chiavi, due ruoli
  3. L’autorizzazione AddFileToCollection
  4. Quote e relativi costi
  5. Isola, ruota, monitora
  6. Un file, più raccolte
  7. Punti chiave

Il rischio specifico delle basi di conoscenza

Una base di conoscenza aziendale non è mai banale: contiene note interne, rapporti riservati e contratti in fase di negoziazione. Se i controlli di accesso falliscono, non perdi solo un singolo file: esponi l’intera base, completa di un motore di ricerca per trovare esattamente ciò che conta. Il sistema di autorizzazioni di xAI mitiga questo rischio separando i diritti, mentre le quote regolano l’utilizzo e la fatturazione.

Due chiavi, due ruoli

L’ecosistema xAI si basa su due credenziali per ambiti distinti:

ChiaveUtilizzoAmbito
XAI_API_KEYCaricamento file e ricercaOperazioni di lettura e utilizzo
XAI_MANAGEMENT_API_KEYGestione delle raccolteOperazioni di amministrazione

Questa separazione applica concretamente il principio del privilegio minimo. Uno sviluppatore che collega un chatbot di supporto alla tua base deve poter interrogare la raccolta, mai eliminarla. Fornendogli solo la chiave standard, un errore di script o una chiave compromessa non possono distruggere un indice costruito nel corso di mesi.

L’autorizzazione AddFileToCollection

Una chiave API di gestione non è onnipotente per impostazione predefinita. I suoi diritti sono espliciti e il più critico per le raccolte è AddFileToCollection. Senza di essa, puoi creare ed elencare le raccolte ma non aggiungere nemmeno un documento: una situazione confusa, poiché tutto sembra funzionare fino al momento dell’ingestione. La generazione di una chiave corretta prevede quattro passaggi:

  1. Accedi alla console xAI
  2. Crea una nuova chiave API di gestione
  3. Abilita l’autorizzazione AddFileToCollection
  4. Archivia la chiave in modo sicuro: variabile d’ambiente o gestore di segreti

Quando manca l’autorizzazione, l’API è esplicita e restituisce un errore 403:

{
  "error": {
    "message": "Insufficient permissions",
    "type": "permission_error",
    "code": 403
  }
}

Il tuo primo passo dovrebbe essere verificare i diritti della chiave nella console piuttosto che sospettare della richiesta, la cui sintassi non ha nulla a che fare con il rifiuto.

Quote e relativi costi

Tre limiti regolano lo spazio di archiviazione per account: 100.000 file totali, 100 GB di capacità cumulativa e 100 MB per singolo file nelle raccolte. Questo valore è più del doppio dei 48 MB consentiti dalla sola API Files, permettendoti di includere documenti che non potresti inviare come allegati diretti.

Sul fronte della fatturazione, due voci spiccano: la Ricerca nelle raccolte viene fatturata a 2,50 $ ogni 1.000 chiamate di ricerca, mentre gli Allegati file costano 10 $ ogni 1.000 chiamate. La differenza è significativa e influenza le scelte architetturali. In caso di utilizzo intensivo, interrogare una raccolta indicizzata costa molto meno che riallegare lo stesso documento a ogni domanda.

Se le tue esigenze superano queste quote, il supporto xAI può concedere un aumento. Prepara la tua richiesta con dati concreti: numero target di file, volume totale e frequenza di ricerca prevista, evitando stime vaghe. Questo accelera l’elaborazione della richiesta.

Isola, ruota, monitora

La prima pratica riguarda le chiavi. Assegna chiavi diverse a ogni ambiente, così uno script di sviluppo non potrà mai toccare la base di produzione. Non fornire mai una chiave di gestione a un servizio il cui unico bisogno è la ricerca. Ruota inoltre queste chiavi regolarmente, specialmente dopo che un collaboratore con accesso ai segreti ha lasciato l’azienda.

La seconda riguarda la struttura. Invece di un’unica raccolta in cui coesistono documentazione pubblica e contratti, separa le tue basi per livello di riservatezza: una base “pubblica” per la documentazione aperta, una “interna” per i documenti aziendali e una “riservata” per i dati sensibili. Ogni servizio riceve così solo l’accesso necessario e la domanda “questo chatbot può citare un contratto?” trova risposta per progettazione.

La terza è il monitoraggio. Controlla i tuoi consumi nella console xAI, imposta un avviso per qualsiasi aumento imprevisto del volume di ricerca, spesso primo segno di un ciclo incontrollato, e tieni un registro scritto di quali servizi accedono a quali raccolte.

Un file, più raccolte

Questo isolamento non richiede di duplicare i documenti, poiché lo stesso file può appartenere a più raccolte. Un rapporto tecnico appare così in “product-documentation” per il team tecnico, in “quarterly-reports” per la direzione e in “support-base” per il servizio clienti. Viene archiviato una sola volta, conta una sola volta verso le tue quote e rimane ricercabile in tutti e tre i contesti: visualizzazioni tematiche per pubblico, senza copie divergenti.

Punti chiave

  • Due chiavi API distinte: standard per l’utilizzo, Gestione per l’amministrazione
  • L’autorizzazione AddFileToCollection è essenziale per popolare le raccolte
  • I limiti sono 100.000 file, 100 GB e 100 MB per file
  • Separa le tue raccolte per livello di riservatezza
  • Un file può appartenere a più raccolte senza duplicazione