Questa guida illustra come creare, gestire e utilizzare le credenziali AI (segreti condivisi) per LLM, modelli di embedding e strumenti AI personalizzati nel plugin Discourse AI.
Livello utente richiesto: Amministratore
Riepilogo
Le credenziali AI offrono un modo centralizzato e sicuro per gestire i segreti di autenticazione, come le chiavi API, all’interno della configurazione di Discourse AI. Invece di incollare le chiavi API grezze in ogni modello LLM, definizione di embedding o strumento personalizzato singolarmente, crei una credenziale una sola volta e la fai riferimento ovunque sia necessaria.
Quando ruoti una chiave (ad esempio, la tua chiave API OpenAI), la aggiorni in un solo punto e ogni LLM, embedding o strumento che utilizza la credenziale aggiorna automaticamente il cambiamento.
Questa documentazione copre:
- Creazione e gestione delle credenziali
- Collegamento delle credenziali a LLM e modelli di embedding
- Utilizzo delle credenziali negli strumenti AI personalizzati
- Protezione dall’eliminazione e ciclo di vita delle credenziali
- L’API per gestire le credenziali in modo programmatico
Cos’è una credenziale?
Una credenziale è un segreto denominato e riutilizzabile archiviato centralmente in Discourse AI. Ha due campi principali:
| Campo | Descrizione |
|---|---|
| Nome | Un’etichetta unica e leggibile dall’uomo (ad es. “Chiave API OpenAI”). Massimo 100 caratteri. |
| Valore | Il segreto effettivo (chiave API, token, ecc.). Massimo 10.000 caratteri. |
Una credenziale può essere riferita da tre tipi di entità :
- Modelli LLM — come chiave API principale
- Definizioni di embedding — come chiave API principale
- Strumenti AI personalizzati — come legami di segreti denominati accessibili da JavaScript
Inoltre, alcuni parametri del provider LLM di tipo “segreto” (ad es. access_key_id per AWS Bedrock) fanno riferimento alle credenziali.
Creazione e gestione delle credenziali
Accesso alla pagina delle credenziali
Vai su Admin → Plugins → Discourse AI → Credenziali, oppure visita direttamente /admin/plugins/discourse-ai/ai-secrets.
[screenshot placeholder: pagina elenco credenziali che mostra le colonne nome, utilizzato da e pulsante modifica]
Creazione di una nuova credenziale
- Nella pagina delle credenziali, clicca su “Nuova credenziale”.
- Inserisci un Nome per la credenziale (ad es. “Chiave API OpenAI”).
- Inserisci il Valore — la chiave API o il token effettivo. Questo campo viene visualizzato come un campo password.
- Clicca su “Salva”.
[screenshot placeholder: modulo editor credenziale con campi nome e valore]
Puoi anche creare credenziali in linea mentre configuri un LLM, un embedding o uno strumento. Una finestra di dialogo modale ti permette di aggiungere una nuova credenziale senza uscire dalla pagina corrente, e la credenziale appare immediatamente nel menu a discesa del selettore.
Modifica di una credenziale
- Nella pagina elenco delle credenziali, clicca su “Modifica” accanto alla credenziale.
- Aggiorna il Nome o il Valore come necessario.
- Clicca su “Salva”.
Quando visualizzi una credenziale esistente, il valore segreto è mascherato (********) nella vista elenco. Il valore effettivo viene mostrato solo nella pagina di modifica della credenziale individuale.
Eliminazione di una credenziale
Una credenziale non può essere eliminata se è attualmente riferita da qualsiasi LLM, embedding o strumento. Se tenti di eliminare una credenziale in uso, l’interfaccia mostra un messaggio che elenca le entità che la riferiscono, con collegamenti alle loro pagine di modifica.
Per eliminare una credenziale:
- Prima, rimuovi o riassegna tutti i riferimenti alla credenziale da qualsiasi LLM, embedding o strumento.
- Torna alla pagina di modifica della credenziale.
- Clicca su “Elimina” e conferma l’azione.
Collegamento delle credenziali a LLM e embedding
Modelli LLM
Quando configuri un modello LLM nella pagina delle impostazioni LLM, puoi selezionare una credenziale esistente da un menu a discesa invece di incollare direttamente una chiave API. A runtime, il modello risolve il segreto dalla credenziale collegata.
Per i segreti specifici del provider — come access_key_id di AWS Bedrock — l’ID della credenziale viene archiviato all’interno dei parametri del provider e risolto in modo trasparente quando il modello effettua richieste API.
Definizioni di embedding
I modelli di embedding funzionano allo stesso modo. Quando configuri una definizione di embedding, seleziona una credenziale dal menu a discesa. Il modello di embedding verifica che sia presente una credenziale o una chiave API in linea e utilizza il valore della credenziale a runtime.
Utilizzo delle credenziali negli strumenti AI personalizzati
Gli strumenti AI personalizzati utilizzano un modello di contratto e legame per i segreti, che mantiene la definizione dello strumento portatile (esportabile/importabile) mentre i segreti rimangono locali al sito.
Passo 1: Dichiarare i contratti di segreto
Quando crei o modifichi uno strumento, dichiari quali segreti richiede lo strumento aggiungendo voci ai suoi contratti di credenziale. Ogni voce ha un alias — un identificatore semplice che utilizza lettere, numeri e trattini bassi.
Nella pagina editor dello strumento, clicca su “Aggiungi credenziale” per aggiungere una nuova voce di contratto e assegnarle un nome alias, ad esempio external_api_key.
[screenshot placeholder: editor strumento che mostra i campi alias credenziale e i selettori credenziale]
I nomi alias devono corrispondere al pattern [a-zA-Z0-9_] ed essere unici all’interno dello strumento.
Passo 2: Legare le credenziali agli alias
Accanto a ogni alias dichiarato nella pagina di configurazione dello strumento, seleziona una credenziale esistente dal menu a discesa. Questo crea un legame tra l’alias e la credenziale.
Il legame viene convalidato per garantire:
- Che la credenziale selezionata esista
- Che l’alias sia dichiarato nei contratti dello strumento
Passo 3: Accedere ai segreti a runtime in JavaScript
All’interno del JavaScript di uno strumento, accedi ai segreti utilizzando l’API secrets.get():
function invoke(params) {
const apiKey = secrets.get("external_api_key");
const result = http.get("https://api.example.com/data", {
headers: { "Authorization": "Bearer " + apiKey }
});
return JSON.parse(result.body);
}
Sostituisci external_api_key con il nome alias che hai dichiarato nei contratti di credenziale dello strumento.
Tutti gli alias dichiarati devono avere legami di credenziale prima che lo strumento possa essere eseguito. Se mancano legami, l’esecuzione viene bloccata con un messaggio di errore che elenca gli alias non legati.
Esempio: uno strumento con piĂą credenziali
Supponiamo di creare uno strumento che chiama due API diverse. Dichiara due contratti di credenziale:
| Alias | Descrizione |
|---|---|
weather_api_key |
Chiave per l’API dei dati meteorologici |
geocode_api_key |
Chiave per l’API di geocodifica |
Poi lega ogni alias alla credenziale appropriata nella pagina di configurazione dello strumento.
Nello script:
function invoke(params) {
const weatherKey = secrets.get("weather_api_key");
const geocodeKey = secrets.get("geocode_api_key");
const location = http.get(
"https://geocode.example.com/search?q=" + encodeURIComponent(params.city),
{ headers: { "X-Api-Key": geocodeKey } }
);
const coords = JSON.parse(location.body);
const forecast = http.get(
"https://weather.example.com/forecast?lat=" + coords.lat + "&lon=" + coords.lon,
{ headers: { "Authorization": "Bearer " + weatherKey } }
);
return JSON.parse(forecast.body);
}
Tracciamento dell’utilizzo delle credenziali
Ogni credenziale traccia dove viene riferita. Nella pagina elenco delle credenziali, la colonna “Utilizzato da” mostra i collegamenti a ogni LLM, embedding o strumento che attualmente utilizza quella credenziale.
Questa visibilitĂ ti aiuta a:
- Comprendere l’impatto prima di ruotare o aggiornare un segreto
- Identificare credenziali non utilizzate che possono essere rimosse in sicurezza
- Navigare rapidamente alle entitĂ che dipendono da una credenziale
Riferimento API
Tutti gli endpoint richiedono l’autenticazione amministratore e si trovano nel percorso /admin/plugins/discourse-ai/ai-secrets.
| Metodo | Percorso | Descrizione |
|---|---|---|
GET |
/ai-secrets |
Elenca tutte le credenziali (valori mascherati) |
GET |
/ai-secrets/:id |
Mostra una singola credenziale (valore non mascherato) |
POST |
/ai-secrets |
Crea una nuova credenziale |
PUT |
/ai-secrets/:id |
Aggiorna una credenziale |
DELETE |
/ai-secrets/:id |
Elimina una credenziale (restituisce 409 se in uso) |
Corpo della richiesta per creazione e aggiornamento:
{
"ai_secret": {
"name": "Chiave API OpenAI",
"secret": "sk-..."
}
}
Tutte le operazioni di creazione, aggiornamento ed eliminazione vengono registrate nel registro azioni dello staff. I valori segreti sono trattati come sensibili e non vengono mai scritti nei log.
Migrazione automatica dalle chiavi API in linea
Le installazioni esistenti che in precedenza utilizzavano chiavi API in linea vengono migrate automaticamente. La migrazione:
- Legge tutti i modelli LLM e le definizioni di embedding non seminati che hanno una chiave API in linea.
- Deduplica per chiave API e provider — se due modelli condividono la stessa chiave e provider, ricevono una singola credenziale.
- Crea record di credenziale con nomi generati automaticamente come “Chiave API OpenAI”, “Chiave API AWS Bedrock”, ecc.
- Aggiorna i record del modello LLM e della definizione di embedding per riferire le nuove credenziali.
- Gestisce i valori
access_key_iddi AWS Bedrock nei parametri del provider — estrae la chiave grezza, crea una credenziale e sostituisce il valore in linea con l’ID della credenziale.
Questa migrazione viene eseguita automaticamente durante l’aggiornamento ed è irreversibile. Non è richiesta alcuna azione manuale.
Problemi comuni e soluzioni
“Questa credenziale è attualmente in uso e non può essere eliminata”
Ciò significa che uno o più LLM, embedding o strumenti riferiscono la credenziale. Controlla la colonna “Utilizzato da” nella pagina elenco delle credenziali per identificare e riassegnare o rimuovere quei riferimenti prima di eliminare.
“Mancano legami di credenziali richiesti” durante l’esecuzione di uno strumento
Tutti gli alias di credenziale dichiarati nei contratti di uno strumento devono avere legami. Apri la pagina di modifica dello strumento, verifica che ogni alias abbia una credenziale selezionata nel menu a discesa e salva.
Il valore della credenziale viene mostrato come ********
Questo è un comportamento previsto. I valori segreti sono mascherati nelle viste elenco per motivi di sicurezza. Per visualizzare o modificare il valore effettivo, clicca su “Modifica” sulla credenziale specifica.
Ho ruotato una chiave ma le funzionalitĂ AI continuano a fallire
Dopo aver aggiornato il valore di una credenziale, verifica che il test LLM (nella pagina delle impostazioni LLM) abbia esito positivo. Se la nuova chiave ha permessi diversi o appartiene a un account diverso, controlla i requisiti di configurazione del provider.
Domande frequenti
Posso ancora utilizzare chiavi API in linea invece di credenziali?
Le chiavi API in linea legacy continuano a funzionare per le configurazioni esistenti. Tuttavia, le credenziali sono l’approccio consigliato perché semplificano la rotazione delle chiavi e riducono la duplicazione.
I valori delle credenziali sono crittografati a riposo?
I valori delle credenziali sono archiviati nel database. Seguono lo stesso modello di sicurezza di altri dati sensibili di Discourse. Assicurati che il tuo database sia adeguatamente protetto e che i backup siano gestiti in modo appropriato.
Cosa succede quando importo uno strumento che utilizza credenziali?
Le importazioni di strumenti includono gli alias dei contratti di credenziale ma non i valori segreti effettivi. Dopo aver importato uno strumento, dovrai creare o selezionare credenziali per ogni alias dichiarato nella pagina di configurazione dello strumento.
Posso condividere una singola credenziale tra piĂą LLM?
Sì. Più LLM e embedding possono riferire la stessa credenziale. Questo è particolarmente utile quando utilizzi la stessa chiave API del provider in diverse configurazioni di modello.