Documentazione

Connessione di un provider IA e registrazione di un modello

Tre livelli da non confondere

La connessione di un modello in Sapphire I.C.D.S. è composta da tre registrazioni separate. Il provider descrive il servizio esterno: la sua chiave stabile, l'URL di base, l'adattatore installato e il segreto di accesso. Il modello memorizza l'identificatore del modello presso quel provider e i relativi limiti tecnici. Il profilo definisce il comportamento operativo: istruzione di sistema, budget di contesto, dimensione della risposta e parametri aggiuntivi. Questa separazione consente di usare uno stesso modello in più modalità, evita di duplicare la chiave API e impedisce di sostituire i limiti reali del modello con le impostazioni di un'attività specifica.

La configurazione si esegue nella sezione amministrativa AI Settings. L'accesso deve essere concesso tramite Helix. Prima di iniziare, procuratevi dal provider i valori aggiornati di base URL, model ID e dei limiti del modello scelto, e verificate che l'adattatore corrispondente sia già installato nell'ambiente server Sapphire. Una stringa inserita nel modulo non installa da sola una libreria.

Passaggio 1. Creare il provider

Aprite la sezione dei provider e create una nuova registrazione. Il campo Vendor key deve contenere un identificatore macchina breve e stabile, ad esempio acme_ai. Usate lettere latine minuscole, numeri e trattini bassi. Non includete il dominio, il piano tariffario, la regione o la versione del modello: la chiave collega le configurazioni e deve sopravvivere alle normali modifiche del prodotto.

Display name è destinato agli operatori e può essere leggibile. In Base URL indicate l'indirizzo HTTPS di base documentato dell'API del provider, senza il percorso di un modello specifico e senza token nella query string. Non copiate un URL dalla console del browser e non aggiungete una route finale casuale. Se il fornitore propone diverse API compatibili, usate la variante per la quale è installato l'adattatore.

Vendor key deve corrispondere alla variant del provider installato rilevata dal loader standard della piattaforma. Nel runtime attuale, il campo Provider library è metadata fallback compatibile e, quando vendor key non è vuoto, normalmente non determina l'adattatore. Non è un percorso di file né un meccanismo di installazione di una nuova libreria. Se la provider variant necessaria non è installata, assegnate l'attività all'amministratore del deployment.

In Secret name si mantiene normalmente il nome del segreto adottato per quell'adattatore, mentre in Secret value si inserisce la chiave API ricevuta. Il segreto non deve essere incluso nel nome, nell'URL, nella descrizione, in uno screenshot, in un ticket o nel JSON del profilo. Dopo il salvataggio, l'interfaccia mostra solo l'esistenza del segreto, non il valore originale. Durante una modifica, lasciate vuoto il campo del valore se non occorre cambiare la chiave; un nuovo valore non vuoto comporta la rotazione del segreto. Un ordine pratico consiste nel creare prima il provider disattivato, salvare il segreto, controllare gli altri campi e solo allora attivare la registrazione.

Passaggio 2. Registrare il modello

Passate alla sezione dei modelli e selezionate il provider appena creato. Model key deve corrispondere esattamente all'identificatore accettato dall'API, inclusi trattini, punti e suffisso di versione. Non è un alias arbitrario. Per un nome più comodo esiste un campo Display name separato.

Riportate quindi i tre limiti dalla scheda ufficiale del modello. Maximum context è il limite complessivo della finestra di contesto. Maximum input è l'input massimo consentito. Maximum output è il limite della risposta generata. Tutti i valori sono numeri interi positivi espressi in token. Input e output, singolarmente, non possono superare il contesto completo. Non usate un valore di contesto pubblicitario se l'API o il piano scelto ne consente uno inferiore.

Tokenizer variant determina il metodo di stima dei token. Indicate la variante supportata esatta, se nota. Se per una nuova famiglia è disponibile solo una stima prudenziale, usate il nome concordato per tale variante, non il nome del modello scelto a caso. Il campo è obbligatorio: un tokenizer errato non causa un'imprecisione puramente estetica, ma un calcolo scorretto del momento di compattazione e della dimensione consentita della richiesta.

Ordine di attivazione sicuro

Create il provider con l'URL HTTPS corretto e un adattatore installato.
Salvate il segreto e assicuratevi che nell'elenco compaia l'indicatore della sua presenza.
Create il modello con il model key esatto e limiti verificati.
Create un profilo separato per questo modello; senza profilo non è definita alcuna politica operativa.
Attivate inizialmente modello e provider per una verifica limitata, quindi assegnate il profilo predefinito.

Per la verifica, aprite una nuova sessione IA, selezionate esplicitamente il profilo creato ed eseguite una richiesta breve senza strumenti, ad esempio chiedendo una sola riga di testo. Una nuova sessione esclude l'influenza della precedente scelta del profilo e della cronologia accumulata. Dopo la risposta di base, verificate lo streaming e solo in seguito gli scenari con strumenti. La disponibilità degli strumenti è gestita dal catalogo e dai diritti dei gruppi, non dalla registrazione del provider o del modello.

Errori comuni

Errore di autorizzazione: verificate la presenza del segreto, la sua validità e l'appartenenza al progetto corretto, quindi ruotatelo solo se necessario.
Model not found: confrontate il model key carattere per carattere con la documentazione dell'API e assicuratevi che il modello sia consentito all'account.
Route errata: verificate la base URL, l'adattatore selezionato e l'assenza di un percorso modello nell'indirizzo di base.
Rifiuto durante il salvataggio dei limiti: tutti e tre i valori devono essere positivi, mentre input e output non devono superare context.
Il modello non compare durante l'uso: provider, modello e profilo devono essere attivi; il profilo deve fare riferimento alla stessa coppia ed essere disponibile all'utente corrente.

Non modificate contemporaneamente segreto, URL, model key e limiti di un profilo attivo. Apportate una modifica alla volta e registrate l'esito della verifica. Per cambiare generazione di modello è più sicuro registrare un nuovo modello e un nuovo profilo, testarli separatamente e poi cambiare il profilo predefinito. In questo modo resta disponibile un percorso di ripristino chiaro, senza alterare il significato delle registrazioni esistenti.

Accettazione e manutenzione

Dopo una richiesta minima riuscita, annotate nella documentazione di lavoro vendor key, model key, scopo del profilo, fonte dei limiti e data della verifica. Non annotate il segreto. Verificate separatamente il comportamento quando il provider è temporaneamente disattivato: l'utente deve ricevere un errore comprensibile, non un'attesa infinita. Se il servizio dispone di più regioni o route tariffarie, trattatele come configurazioni consapevoli invece di cambiare la base URL durante la diagnostica.

Riesaminate periodicamente i limiti confrontandoli con la documentazione aggiornata del fornitore. Una modifica del nome commerciale del modello non implica sempre un nuovo identificatore API, e un nuovo identificatore non garantisce la stessa tokenizer variant. Ogni modifica di questo tipo segue lo stesso ciclo: registrazione separata, profilo, sessione di prova, verifica della risposta e solo dopo passaggio degli utenti.