Configurazione AI Model Xference in ConvyAI
Panoramica
Xference porta l'inferenza LLM su infrastruttura italiana dedicata, permettendo di adottare funzionalità generative senza far transitare i dati delle conversazioni fuori dal territorio nazionale. È pensato per i contesti in cui la localizzazione del dato è un requisito, non un'opzione.
Prerequisiti
- Un endpoint Xference e una chiave API.
- Credenziali configurate in Impostazioni Generative AI.
Crea un AI Model Xference
Vai su Generative AI → AI Models e clicca su Nuovo Modello → Xference.
Opzioni di configurazione
| Campo | Descrizione |
|---|---|
| AI Model name | Un nome univoco per identificare questo AI Model. |
| Check as default | Imposta questo AI Model come predefinito per il tenant. |
| Fast recognition | Abilita la modalità di riconoscimento rapido per questo modello. |
| Xference Api Key | La chiave API della tua istanza Xference. Viene mascherata dopo il salvataggio. |
| Xference Endpoint | L'URL della tua istanza Xference. |
| Intent threshold | Punteggio di confidenza minimo affinché un intent venga considerato valido. |
Parametri avanzati
| Parametro | Default | Descrizione |
|---|---|---|
| Prompt version | v3 | Versione del prompt di sistema applicata durante l'utilizzo del modello nei nodi Knowledge Base. |
| Completion model | - | Il modello di completion da invocare. Inserisci uno dei modelli attualmente esposti da Xference (Qwen 3.6, Gemma 4 3B, Gemma 4 12B) o un altro nome modello, come campo di testo libero. |
| Embedding model | BAAI/bge-m3 | Il modello di embedding esposto da Xference, usato durante l'indicizzazione e il retrieval della Knowledge Base. |
| Thinking Budget | - | Il budget di token per il reasoning del modello, come numero intero. Lascia vuoto per usare il default del modello, inserisci 0 per disattivare il reasoning, oppure inserisci un valore per impostare il budget. Il valore vale sia per i nodi Knowledge Base sia per i nodi AI Agent, quindi lo configuri una sola volta. |
| Max token completion | - | Numero massimo di token nella risposta generata. |
| Temperature | - | Controlla la creatività delle risposte. Valori più bassi (0.0–0.3) producono output più deterministici; valori più alti (0.7–1.0) producono risposte più varie. |
| Top P | - | Parametro di nucleus sampling. Limita la selezione dei token alla massa di probabilità più alta. |
| Frequency penalty | - | Riduce la ripetizione di token già apparsi nell'output. |
| Presence penalty | - | Incoraggia il modello a introdurre nuovi argomenti penalizzando i token già apparsi. |
| Number of extracted chunks | 3 | Quanti chunk della Knowledge Base vengono recuperati e passati al modello come contesto durante la RAG. |
I parametri opzionali partono vuoti sui nuovi AI Model. Un campo vuoto significa che il parametro non viene inviato e vale il default del modello; ogni valore inserito, compreso 0, viene inviato così com'è. Vedi Parametri opzionali.
Utilizzo di un AI Model Xference
Una volta configurato, un AI Model Xference può essere usato ovunque sia previsto un AI Model generativo:
- Nel nodo AI Agent del FlowDesigner e nel nodo AI Agent dell'Agentic Designer - inclusi tool MCP Server, funzioni JavaScript e analisi immagini.
- Nel nodo Knowledge Base, per la classificazione degli intent e le risposte ancorate alla RAG.
Intent, entità e test
La configurazione di intent ed entità e il test del modello sono funzionalità condivise tra tutti i provider di AI Model. Consulta Intent, Entità & Test per la documentazione completa.
Note e limitazioni
- Thinking Budget è un budget di token, non un livello come il reasoning effort degli altri provider. Se e come un modello lo usa dipende dal modello: usa la console di test per verificare il comportamento del tuo modello prima del deploy.
- Il reasoning del modello non compare mai nella risposta restituita all'utente finale.
- ConvyAI non riporta i token di reasoning effettivamente consumati e il rispetto del budget dipende dal provider. Se il budget è troppo basso per la risposta, il modello può restituire una risposta incompleta o vuota: la console di test mostra i messaggi restituiti dal provider.
- Gli AI Model già configurati mantengono i valori salvati. Rivedi Max token completion, che non è più precompilato con
1000sui nuovi AI Model. - Un indice creato con il modello di embedding
BAAI/bge-m3non è compatibile con indici creati con un modello di embedding diverso. Adottare Xference su una Knowledge Base esistente richiede la creazione di un nuovo indice e una reindicizzazione completa dei contenuti. Vedi Indicizzazione.