--- title: Provider IA description: Collega un endpoint IA compatibile con OpenAI per AI Chat e l'AI Agent: attiva il modulo IA, inserisci endpoint e chiave, testalo e imposta i limiti. url: https://nexcmp.com/it/docs/ai/ai-providers/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # Provider IA {#ai-provider} > **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 {#what-it-does} 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 {#requirements} | 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](https://nexcmp.com/it/docs/ai/ai-agent/#requirements). | ## Prepara l'infrastruttura {#prepare-the-infrastructure} 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: ```bash 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 {#connect-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 — , ms` o l'errore restituito dal provider. ![Pagina del provider AI con il modulo AI attivato e il modulo di connessione compilato con valori di esempio](https://nexcmp.com/it/docs/images/ai/ai-providers-01-connection.webp) ### Cosa comporta il salvataggio {#what-saving-does} - 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 {#verify} 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 {#limits-notes} - **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](https://nexcmp.com/it/docs/ai/ai-chat/) e [AI Agent](https://nexcmp.com/it/docs/ai/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](https://nexcmp.com/it/docs/customers/legal/). - **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 {#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. |