---
title: AI Models
description: Vendi modelli AI dal tuo gateway: aggiungi provider OpenAI o Anthropic, sincronizza modelli, fissa i prezzi e offri un endpoint unico con chiavi e wallet.
url: https://nexcmp.com/it/docs/infrastructure/ai-models/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# AI Models {#ai-models}

> **Nel pannello admin:** System › Admin › License & updates (`/license`) per attivare il modulo. Quindi Services › AI Models: Providers (`/ai/providers`), Models (`/ai/models`), Profit (`/ai/profit`) e Audit (`/ai/audit`). I clienti utilizzano AI › API nel portale clienti.

## Descrizione {#what-it-does}

AI Models è un gateway e un livello di fatturazione sul tuo pannello. I tuoi clienti ottengono chiavi API e chiamano **un unico endpoint sul tuo dominio**, nel formato compatibile con OpenAI o Anthropic. Scegli quali modelli offrire e il costo di ciascuno per 1 milione di token. NexCMP verifica la chiave, i limiti e il wallet, invia la richiesta al provider che hai aggiunto, conteggia i token e addebita l'importo sul wallet prepagato del cliente.

**Le sorgenti dei modelli sono a tuo carico.** NexCMP viene fornito senza provider, modelli, indirizzi predefiniti o prezzi. Non fornisce modelli, chiavi API, token o account provider.

::: warning Verifica prima i termini delle tue sorgenti
Molte sorgenti di modelli limitano la rivendita o la cessione dell'accesso a terzi. Utilizza solo sorgenti che sei autorizzato a usare e rivendere, e rispetta i loro termini e le normative applicabili. Questa pagina non costituisce una consulenza legale.
:::

AI Models è un prodotto distinto da **AI Chat and AI Agent** (modulo **AI**, vedi [provider AI](https://nexcmp.com/it/docs/ai/ai-providers/)). I due moduli non dipendono l'uno dall'altro.

## Requisiti {#requirements}

| Elemento | Requisito |
|---|---|
| Modulo | **AI Models** attivato in License & updates, Modules. È disattivato per impostazione predefinita. |
| Provider | Una o più sorgenti di modelli che sei autorizzato a rivendere, ciascuna con una API compatibile con OpenAI (`/chat/completions`), una API compatibile con Anthropic (`/messages`) o entrambe. Ciascuna richiede un URL di base e una chiave API. |
| Rete | Il pannello deve raggiungere ciascun provider tramite **HTTPS sulla porta 443** a un nome di dominio pubblico. Un provider su un host interno, un'altra porta o in semplice HTTP deve essere elencato in **Allowed internal hosts** (impostazione `ai_endpoint_allow`). |
| Clienti | Un account cliente con un indirizzo email verificato e un saldo nel wallet. |
| Hardware | Nessuno. NexCMP si limita a inoltrare le richieste: nessuna GPU e nessun file di modello. |

## Prepara l'infrastruttura {#prepare-the-infrastructure}

1. Ottieni una chiave API da ciascuna sorgente di modelli che intendi utilizzare e annota il relativo URL di base (ad esempio `https://api.example.com/v1`).
2. Verifica i termini della sorgente relativi alla rivendita.
3. Se una sorgente è in esecuzione all'interno della tua rete, stabilisci il suo indirizzo, ad esempio `http://10.0.0.5:8000/v1`. Inserirai `10.0.0.5:8000` in **Allowed internal hosts**.

## Collega in NexCMP {#connect-in-nexcmp}

### 1. Attiva il modulo {#_1-turn-the-module-on}

Apri **System › Admin › License & updates**, individua la scheda **Module** e attiva **AI Models**. Il menu si ricarica e appare **Services › AI Models**. Finché il modulo è disattivato, le pagine del cliente, quelle di amministrazione e il gateway rispondono tutte con `404 module_disabled` e nessun provider viene contattato.

![La scheda Module con lo switch AI Models attivato](https://nexcmp.com/it/docs/images/infrastructure/ai-models-01-modules.webp)

### 2. Aggiungi un provider {#_2-add-a-provider}

1. Apri **AI Models › Providers** e seleziona **Add provider**.
2. Inserisci uno **slug** breve, un **name** (visibile solo a te), il **type** (OpenAI-compatible, Anthropic-compatible o Both), il **base URL**, la **API key** e una **priority** (un numero più basso viene tentato per primo).
3. Salva. La chiave viene memorizzata in modo cifrato e in seguito ne vengono mostrati solo gli ultimi quattro caratteri. È possibile inserire una chiave solo da una sessione amministratore autenticata.

Usa **Both** solo per un gateway che gestisce realmente entrambi i formati. NexCMP **non** converte tra i due formati: un modello fornito da un provider compatibile con OpenAI viene raggiunto su `/ai/v1/chat/completions`, mentre uno fornito da un provider compatibile con Anthropic su `/ai/v1/messages`.

![La pagina Providers che elenca tre provider di esempio con tipo, priorità e stato](https://nexcmp.com/it/docs/images/infrastructure/ai-models-02-providers.webp)

### 3. Testa la connessione {#_3-test-the-connection}

Scegli **Test connection** sul provider. NexCMP legge `GET <base URL>/models` con la chiave e restituisce **ok**, oppure il motivo dell'errore: **auth** (chiave errata), **blocked**, **billing** o **unreachable**. I test sono limitati a 6 al minuto.

### 4. Sincronizza i modelli {#_4-sync-the-models}

Scegli **Sync models**. NexCMP legge l'elenco dei modelli del provider e aggiunge ciascun nuovo modello **disattivato e senza prezzo**. Un modello non più presente nell'elenco del provider viene contrassegnato. Finché il modulo è attivo, l'elenco viene sincronizzato automaticamente anche ogni 6 ore (impostazione `ai_models_sync_hours`).

### 5. Imposta i prezzi e attiva i modelli {#_5-set-prices-and-switch-models-on}

1. Apri **AI Models › Models**.
2. Per ogni modello che desideri vendere, imposta il **prezzo di vendita** in dollari USA per 1 milione di token: **input**, **cached input** e **output**.
3. Facoltativamente, inserisci il tuo **costo** per il modello. In questo modo **Profit** mostrerà le entrate a fronte dei costi per giorno e per modello, e un prezzo di vendita inferiore al costo più il margine minimo (impostazione `ai_min_margin_pct`, 10 per impostazione predefinita) verrà rifiutato a meno che tu non confermi una perdita intenzionale. **Set price from cost** utilizza un ricarico a tua scelta; non è previsto alcun ricarico predefinito.
4. Attiva il modello. Un modello senza prezzo di vendita non può essere attivato. Un prezzo di cached input lasciato a zero viene fatturato al prezzo di input.

![La pagina Models con i prezzi di vendita di input, cached input e output e gli interruttori di attivazione](https://nexcmp.com/it/docs/images/infrastructure/ai-models-03-models.webp)

### 6. Routes e failover {#_6-routes-and-failover}

Su un modello, **Routes** elenca i provider che lo gestiscono, in ordine. Aggiungi un secondo provider come fallback, definisci l'ordine e, facoltativamente, assegna un nome di modello diverso per ciascun provider (il nome inviato al provider può differire da quello pubblicato). Quando un provider restituisce un errore del server, un errore di autorizzazione o fatturazione, un modello mancante o un limite di frequenza, NexCMP prova la route successiva. Se una lettura va in timeout dopo l'invio della richiesta, **non** viene inviata a un altro provider, evitando doppi addebiti.

Ogni provider è regolato a `ai_provider_rpm` richieste al minuto (50 per impostazione predefinita). Se un provider continua a restituire errori di autorizzazione o fatturazione, NexCMP avvisa l'amministratore su Telegram, se configurato.

### 7. Attiva l'interruttore di vendita {#_7-open-the-sale-switch}

Nella parte superiore delle pagine AI Models, l'**interruttore di vendita** (impostazione `feature_ai_models`) è disattivato per impostazione predefinita. Finché rimane disattivato, i clienti vedono che il servizio non è ancora aperto e il listino prezzi pubblico lo segnala come non disponibile. Verifica che almeno un modello sia attivo, abbia un prezzo di vendita e una route con una chiave, quindi attivalo.

### Cosa possono fare i clienti {#what-customers-can-do}

Nel portale clienti, **AI › API**:

- **Models** mostra i tuoi modelli e i relativi prezzi, l'URL di base e comandi di esempio già pronti.
- **API Keys**: crea, rinomina, ruota, disabilita ed elimina chiavi. Il segreto viene mostrato una sola volta; viene memorizzato solo un hash. Per ciascuna chiave: modelli consentiti, scadenza, un soft budget (invia un avviso) e un hard budget (blocca con `402`), richieste al minuto e token al minuto.
- **Usage** per modello, chiave e giorno, con esportazione.
- **Logs**: registrazioni delle richieste filtrabili (orario, chiave, modello, token, costo, stato, latenza). **Prompt e risposte non vengono registrati.** I log vengono conservati per 90 giorni per impostazione predefinita (`ai_log_retention_days`).
- **Settings**: un budget dell'account e l'indirizzo email per gli avvisi di budget.
- **Playground**: chatta con un modello, confronta i modelli affiancati e copia il codice corrispondente.

![La pagina API Keys del cliente con gli URL di base per entrambi i formati API](https://nexcmp.com/it/docs/images/infrastructure/ai-models-04-keys.webp)

Gli endpoint del gateway, sul tuo dominio:

```text
POST /ai/v1/chat/completions      OpenAI-compatible
POST /ai/v1/messages              Anthropic-compatible (also /ai/v1/messages/count_tokens)
GET  /ai/v1/models                model list
GET  /ai/v1/models/pricing        public price list, no key needed
```

### Wallet e fatturazione {#wallet-and-billing}

L'utilizzo dell'AI viene addebitato sullo stesso wallet prepagato di qualsiasi altro servizio. Prima che una richiesta venga inviata a un provider, NexCMP riserva l'importo massimo stimato per il costo della richiesta; se il saldo è inferiore al minimo (`ai_min_balance_cents`, 20 centesimi per impostazione predefinita) o insufficiente, la richiesta viene rifiutata con `402 insufficient_balance` e **nessun provider viene contattato**. L'utilizzo viene aggregato per account e registrato nelle voci mastro del wallet ogni ora, con una scansione ogni 5 minuti; l'utilizzo non ancora contabilizzato viene già sottratto dal saldo visibile al gateway.

I rivenditori possono vendere AI Models sul proprio dominio: il loro ricarico o sconto si applica al tuo prezzo di vendita e al loro wholesale wallet viene addebitato il prezzo all'ingrosso. Un interruttore AI dedicato per rivenditore, attivo per impostazione predefinita, controlla chi può venderlo.

## Verifica {#verify}

1. Dopo il passaggio 3, **Test connection** mostra **ok** e il conteggio dei modelli.
2. Dopo il passaggio 4 i nuovi modelli compaiono nell'elenco, disattivati e senza prezzo.
3. Come cliente con un wallet ricaricato, crea una chiave ed effettua una chiamata al gateway:

   ```bash
   curl https://your-domain/ai/v1/chat/completions \
     -H "Authorization: Bearer sk-ai-…" -H "Content-Type: application/json" \
     -d '{"model":"model-one","messages":[{"role":"user","content":"hello"}]}'
   ```

   Una risposta `200` restituisce la risposta del modello. **Usage** mostra la richiesta, e **Profit** la mostra se hai inserito un costo.
4. Con il wallet a zero, la stessa chiamata restituisce `402 insufficient_balance`.

## Limiti e note {#limits-and-notes}

- Il modulo non include provider, modelli o prezzi predefiniti e non acquisisce mai listini prezzi da un provider.
- I tool eseguiti sul lato provider con addebito per chiamata, come la ricerca web, vengono rifiutati poiché non possono essere misurati. Viene inoltrato solo un set ristretto di parametri di richiesta.
- Il consumo di token viene ricavato dalla risposta del provider; se la risposta non ne contiene, NexCMP lo stima e contrassegna la registrazione come stimata.
- Gli errori restituiti da un provider vengono ripuliti prima di raggiungere il cliente (nomi, host, indirizzi e il nome del modello del provider vengono rimossi). I clienti non vedono mai quale provider ha gestito la richiesta.
- I clienti raggiungono il gateway tramite il dominio del tuo pannello, pertanto il protocollo TLS di tale dominio deve essere operativo.
- NexCMP non fornisce accordi sul livello di servizio (SLA), fine-tuning o hosting GPU per questo modulo.

## Troubleshooting {#troubleshooting}

| Sintomo | Causa e soluzione |
|---|---|
| Tutte le pagine di AI Models e il gateway rispondono con `404 module_disabled` | Il modulo è disattivato. Attiva **AI Models** in License & updates, Modules. |
| L'aggiunta di un provider fallisce con `endpoint_host_not_allowed`, `endpoint_must_be_https` o `invalid_endpoint_port` | L'URL di base deve utilizzare HTTPS sulla porta 443 con un nome di dominio pubblico. Per un host interno, un'altra porta o HTTP standard, inserisci `host:port` in **Allowed internal hosts**. |
| `blocked_endpoint` | L'indirizzo è un IP o il nome si risolve in un indirizzo privato. Inseriscilo in **Allowed internal hosts** se questa è la configurazione desiderata. |
| **Test connection** restituisce `auth` | La chiave è errata o non dispone dei permessi necessari. Inserisci nuovamente la chiave. |
| Impossibile attivare un modello (`no_price`) | Imposta prima un prezzo di vendita. |
| I clienti ricevono `503 ai_unavailable` | L'opzione di vendita è disattivata, oppure l'interruttore AI del rivenditore è disattivato. |
| I clienti ricevono `503 upstream_unavailable` | Nessun instradamento attivo provvisto di chiave serve questo modello nel formato richiesto. Verifica i route del modello e la tipologia di provider. |
| I clienti ricevono `402 insufficient_balance` | Il saldo del wallet è inferiore al minimo o insufficiente per la richiesta. Invita il cliente a effettuare una ricarica. |