Collegare un modello AI personalizzato: endpoint, chiavi e fallback
Configura un modello compatibile con OpenAI in Mono, verifica la connessione e distingui risposte testuali ed esecuzione di strumenti.
Un endpoint personalizzato invia le richieste a un server scelto da te. Il modello può funzionare sul computer o presso un fornitore: inserire un indirizzo non lo esegue sul telefono. Inizia con una richiesta breve e senza informazioni sensibili.
Mono by Reunified ti permette di usare un tuo modello, e le risposte di un modello che esegui tu non costano nulla in Mono. Mono è attualmente in lista d’attesa. Questa guida mostra le impostazioni e ti dà una checklist da usare quando avrai accesso. Anche se un server si dichiara compatibile, provalo con la tua app e il tuo modello esatti.
1. Raccogli i dati corretti
Ti servono l’URL base dell’API, l’ID esatto del modello e, se richiesta, una chiave API. Segui le istruzioni di chi gestisce il server. L’indirizzo di un sito, una pagina di download di un modello o l’URL di un server MCP non sono un endpoint API per modelli.
Mono invia le richieste di testo al percorso Chat Completions sotto l’indirizzo che inserisci, quindi inserisci la base dell’API, non il percorso completo. Per esempio, se il tuo fornitore indica https://models.example.com/v1/chat/completions, inserisci https://models.example.com/v1. È un indirizzo inventato, non un servizio reale.
Controlla cos’altro supporta il modello. Il fatto che risponda in testo non vuol dire che supporti immagini, strumenti, streaming o tutte le opzioni di richiesta.
2. Configura un solo ruolo
Apri Impostazioni, poi Integrazioni, e attiva Modello di testo in Endpoint personalizzati. Inserisci URL dell’endpoint, chiave API e ID del modello nei rispettivi campi. Non mettere chiavi in messaggi di chat o screenshot. Un server locale senza accesso protetto può non richiedere una chiave, ma questo non lo rende sicuro da aprire su internet.
Parti dal modello di testo. Mono ha impostazioni separate per i modelli di testo, di codice e di supporto, quindi cambiarne uno non cambia gli altri. Annota quale hai modificato, così saprai da dove partire se qualcosa si rompe più avanti.
Con un modello di testo personalizzato, alcune funzioni, come strumenti e skill, potrebbero non funzionare come con i modelli integrati di Mono. Prova prima una conversazione semplice. Se un flusso ha bisogno di skill, una buona risposta di testo non dimostra che il flusso funzionerà.
3. Decidi il comportamento di fallback
Ogni modello personalizzato ha un interruttore «Usa il modello predefinito se non raggiungibile», attivo per impostazione predefinita. Non dare per scontato che ogni funzione reagisca allo stesso modo a un server fuori uso. Provalo: ferma il server e guarda cosa succede nella funzione che usi.
Se le tue richieste devono andare solo al tuo server, per privacy o per costi, disattiva questo interruttore e prova cosa succede quando il server non risponde. Controlla dove vanno davvero le richieste; un’impostazione sullo schermo non basta. Cambiare il modello di testo lascia comunque da controllare gli altri modelli e gli strumenti collegati.
Leggi la guida alla privacy e il confronto dei costi prima di inviare materiale sensibile.
4. Esegui una prova piccola
Chiedi: «Restituisci le tre parole rosso, verde, blu su righe separate». Controlla che la risposta arrivi, che i log del server (se ci sono) mostrino il modello scelto e che la pagina dei consumi del fornitore corrisponda al tuo test.
Poi prova una funzione che ti serve davvero, come una conversazione più lunga. Cambia una cosa alla volta. Annota versione dell’app, versione del server, ID del modello e data; un risultato per una combinazione non significa che funzioneranno tutti i modelli.
Se il server è sul tuo computer, prova anche dalla vera rete del telefono. Sul telefono, localhost è il telefono stesso. Usa un metodo di connessione con accesso protetto supportato dal tuo server, invece di aprire su internet un servizio non protetto.
5. Individua il primo livello che fallisce
| Sintomo | Primo controllo |
|---|---|
| Tempo scaduto | Server attivo, dispositivo in grado di raggiungerlo, regole di rete |
| Accesso negato | Chiave corretta, account e requisiti di accesso |
| Errore «non trovato» | URL base, e se il percorso /chat/completions è stato aggiunto due volte |
| Modello sconosciuto | ID esatto del modello disponibile su quel server |
| Testo corretto, flusso non funzionante | Strumenti o altre funzioni che servono al flusso |
Togli i segreti da qualsiasi log che condividi. Accedere al sito del fornitore non dimostra che la tua chiave API funzioni, e un test di testo riuscito non significa che il modello di codice sia configurato.
6. Mantieni reversibile la configurazione
Annota le impostazioni precedenti, senza i segreti. Dopo aver cambiato server, ripeti il piccolo test e controlla i costi sia nell’app sia presso il fornitore. Controlla le altre impostazioni dei modelli prima di definire una configurazione «locale» o «privata».
Iscriviti alla lista Mono. Se vuoi collegare un servizio esterno invece di cambiare modello, usa la guida MCP.
