Provider IA

Dove nell'amministrazione: System › Settings › AI provider (/settings/ai). L'interruttore del modulo IA si trova lì e in System › Admin › License & updates (/license), scheda Module.

Descrizione

AI Chat (chat di supporto automatico) e AI Agent (amministrazione delle VM in linguaggio naturale) non includono un modello integrato. Scegli il tuo provider: qualsiasi servizio che offra una API chat/completions compatibile con OpenAI, ad esempio OpenAI, OpenRouter, un gateway LiteLLM o il tuo server vLLM. NexCMP memorizza l'endpoint e la chiave API (cifrata) e li utilizza per tutte le funzionalità di intelligenza artificiale. Paghi direttamente il provider.

Requisiti

Elemento	Requisito
Endpoint	Un URL di base compatibile con OpenAI (https://api.openai.com/v1, https://ai.example.com/v1). NexCMP aggiunge /chat/completions a un URL che termina con /v1; per qualsiasi altro URL aggiunge /v1/chat/completions; un URL che termina già con /chat/completions viene utilizzato così com'è.
Modello	Un modello che supporta la chiamata di strumenti (funzioni). Sia l'AI Chat che l'Agent dipendono da esso.
Chiave API	Una chiave per quell'endpoint. È preferibile una chiave con un limite di spesa lato provider (ad esempio una chiave virtuale LiteLLM con un budget mensile).
Rete	Il server del pannello deve raggiungere l'endpoint tramite HTTP(S). Un URL inserito nel modulo può puntare solo a Internet sulle porte 80, 443, 8080 o 8443; per utilizzare un indirizzo interno, salva prima il provider ed esegui il test in un secondo momento.
Dipendenze	Il modulo AI attivo. Per l'Agent vedi AI Agent.

Prepara l'infrastruttura

1. Registrati presso il provider e crea una chiave API. Se il provider supporta budget o limiti di frequenza, imposta un limite mensile.

2. Prendi nota dell'URL di base e del nome esatto del modello (e, facoltativamente, fino a quattro modelli di fallback).

3. Testalo dal server NexCMP prima di inserirlo:

   curl -s https://ai.example.com/v1/chat/completions \
     -H "Authorization: Bearer XXXX" -H "Content-Type: application/json" \
     -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Reply with one word: OK"}]}'

   Una risposta JSON con choices[0].message.content indica che l'endpoint funziona.

Collega in NexCMP

1. Apri System › Settings › AI provider.

2. Nella scheda Module AI attiva il modulo on. Finché non è attivo, i clienti non vedono l'AI Chat o l'AI Agent nel portale. (Puoi attivarlo anche in License & updates.)

3. Nella scheda Connection compila:

   Campo	Esempio	Note
   Usa questo provider	on	Richiede un URL di base, un modello e una chiave per essere attivato.
   Nome visualizzato	LiteLLM	Fino a 60 caratteri.
   URL di base (compatibile con OpenAI)	https://ai.example.com/v1	http:// o https://, fino a 300 caratteri, senza spazi.
   Chiave API del provider	sk-XXXX	Memorizzata crittograficamente; in seguito vengono mostrati solo gli ultimi 4 caratteri. Lascia vuoto per mantenere la chiave salvata.
   Modello predefinito	gpt-4o-mini	Lettere, cifre e - _ . / : @.
   Modelli di fallback	gemini-2.5-flash	Separati da virgola, fino a 4. Utilizzati quando il modello predefinito fallisce.
   Livello di ragionamento	Predefinito (non inviato)	Minimal, Low, Medium o High. Per i modelli di ragionamento (Gemini, serie o) un livello basso risponde molto più velocemente. Lascia su Default per i modelli normali.

4. Clicca su Save, quindi su Test connection. Il test invia una breve domanda e mostra Connected — <model>, <ms> ms o l'errore restituito dal provider.

Cosa comporta il salvataggio

• Le impostazioni del provider vengono salvate come un'unica voce di configurazione e la chiave viene crittografata con AES-256-GCM, vincolata a questo scopo, utilizzando la chiave master dell'installazione.
• Le impostazioni di supporto Primary model e Fallback model (utilizzate da AI Chat) vengono impostate automaticamente sul tuo modello predefinito e sul primo modello di fallback.
• La modifica viene registrata nel registro di audit (endpoint, modello, indicazione se la chiave è cambiata — mai la chiave).

Verifica

1. Test connection diventa verde.
2. Accedi al portale come cliente di prova: il menu ora offre AI Chat (o la bolla della chat) e AI Agent.
3. Chiedi all'AI Chat "What is my balance?". Una risposta che riporta il tuo saldo reale dimostra che il provider gestisce correttamente le chiamate agli strumenti.

Limiti e note

• Un unico provider. NexCMP utilizza un singolo provider configurato per Chat, Agent e analisi dei ticket. I modelli di fallback offrono resilienza all'interno di quel provider.
• Sicurezza della chiave. La chiave salvata viene inviata esclusivamente all'endpoint salvato. Se modifichi l'URL di base, devi reinserire la chiave prima di eseguire il test.
• Limiti per cliente. AI Chat è riservata ai clienti autenticati, con limiti di messaggi al minuto e per chat. L'Agent ha una quota giornaliera di chiamate per account. Vedi AI Chat e AI Agent.
• Privacy. Le domande dei clienti e i dati letti dall'IA per quel cliente (in sola lettura) vengono inviati al tuo provider. Specificatelo nella vostra privacy policy.
• Controllo dei costi. NexCMP non conteggia i costi dell'IA; utilizza le funzionalità di budget del provider.
• Il modulo può essere disattivato in qualsiasi momento: le voci di menu AI scompaiono e le route AI rispondono con 404 module_disabled. Alcuni job in background di AI Chat (analisi ticket, risposte differite) applicano la modifica al riavvio successivo del pannello.

Troubleshooting

Sintomo	Causa	Soluzione
base_url must be an http(s) URL	Schema mancante o spazi	Usa https://host/v1.
api_key is required to enable the provider	Nessuna chiave memorizzata	Inserisci la chiave e salva.
base_url and model are required to enable the provider	Campo vuoto	Compila entrambi.
"Base URL bloccato: solo http(s) pubblico, porte 80/443/8080/8443"	Test di un indirizzo interno non salvato o di un'altra porta	Salva prima il provider, quindi esegui il test.
api_key is required (enter the key again when you change the endpoint)	Il Base URL differisce da quello salvato	Reinserisci la chiave.
model: letters, digits and - _ . / : @	Carattere non valido	Usa l'ID modello esatto del provider.
fallback_models: up to 4 model names	Troppi	Mantieni quattro o meno.
Il test fallisce con 401	Chiave errata	Controlla la chiave e l'endpoint.
Il test fallisce con 404 o "model not found"	Percorso o modello errato	Controlla il base URL (/v1) e l'ID del modello.
Too many tests — wait a minute (429)	Più di 10 test al minuto	Attendi.
Il portale non mostra ancora alcun menu IA	Modulo disattivato o provider non "in use"	Attiva il modulo e abilita il provider.