Esegui Onyx su un provider LLM compatibile OpenAI personalizzato.

Risposta rapida: Add Custom LLM Provider nel pannello admin.

La documentazione di Onyx è esplicita: un provider personalizzato funziona finché espone endpoint compatibili OpenAI, e la sua forma di esempio per la Base URL è esattamente in stile gateway, https://yourprovider.com/v1. Il flusso: apri il Pannello Admin dall'icona del tuo profilo, vai su Configuration, poi Language Models, e scegli Add Custom LLM Provider. Quattro decisioni contano in quel modulo. Display Name è cosmetico. Provider Name deve corrispondere a una chiave provider LiteLLM, perché Onyx instrada le chiamate ai modelli attraverso LiteLLM sotto il cofano; per un gateway compatibile OpenAI quella chiave è openai. Base URL è l'endpoint del gateway incluso il suffisso /v1. E la sezione Model Configurations è dove registri ogni id di modello che vuoi disponibile, scritto esattamente come lo serve il catalogo. Salva, scegli un default, e le chat si instradano immediatamente attraverso il gateway.

Admin Panel -> Configuration -> Language Models
  -> Add Custom LLM Provider

Display Name:   APIsRouter
Provider Name:  openai            (LiteLLM provider key)
Base URL:       https://api.apisrouter.com/v1
API Key:        sk-YOUR-APISROUTER-KEY
Model Configurations:
  claude-sonnet-4-6
  claude-haiku-4-5-20251001
  deepseek-v4-pro

Dove si colloca l'LLM nell'architettura di Onyx.

Onyx (onyx-dot-app su GitHub, circa 31K stelle, in precedenza Danswer) è una piattaforma AI open-source per la conoscenza aziendale: indicizza fonti come Slack, Google Drive, Confluence e decine di altri connettori, poi risponde a domande su di esse tramite una UI di chat, assistenti e flussi di lavoro agentici. È uno degli stack di enterprise search self-hosted più deployati che esistano, il che è esattamente il motivo per cui il suo conto LLM merita una decisione di instradamento invece di un default. La pipeline si divide nettamente in due. L'indicizzazione e il recupero, inclusi l'embedding dei documenti e il reranking, girano sul model server proprio di Onyx con modelli locali di default; niente di tutto ciò tocca il tuo provider LLM. La generazione delle risposte è l'altra metà: una volta che il recupero assembla i passaggi rilevanti, un LLM li legge e scrive la risposta fondata, e quella chiamata passa attraverso LiteLLM verso qualunque provider l'admin abbia configurato. Il flusso del provider personalizzato scambia la destinazione esattamente di questa metà. Poiché LiteLLM inoltra l'id del modello come stringa semplice a un provider di tipo openai, gli id che registri in Model Configurations possono essere qualsiasi cosa serva l'endpoint dietro la Base URL: Claude per risposte fondate e curate, DeepSeek per il volume, Gemini per contesti sorgente molto lunghi. Assistenti diversi possono avere come default modelli diversi, quindi un assistente di supporto e un assistente di ingegneria possono viaggiare su fasce di prezzo diverse attraverso lo stesso provider.

Configurazione completa, e cosa resta intatto.

Il modulo del provider è l'intera integrazione; non c'è alcun file di configurazione da modificare né container da ricostruire per esso. Dopo il salvataggio, imposta il modello predefinito per il workspace, e facoltativamente sovrascrivi il modello per assistente dove vuoi livelli di qualità diversi. Ciò che resta deliberatamente intatto: i connettori mantengono le proprie credenziali, l'indice non è interessato, e il modello di embedding configurato per la ricerca non si sposta. Questa separazione merita di essere spiegata perché rende questo un cambiamento a basso rischio. Se il gateway si comportasse male, ricerca e fonti continuerebbero comunque a funzionare; solo la generazione delle risposte darebbe errore, e riportare il default a un provider precedente è un solo menu a tendina. Per i team che automatizzano i deployment, la stessa definizione di provider può essere seminata tramite l'API di Onyx invece che cliccata nella UI, ma il percorso del pannello admin è la superficie documentata e stabile, e una configurazione una tantum raramente giustifica di più.

# confirm the gateway lists the ids you plan to register
curl -s https://api.apisrouter.com/v1/models \
  -H "Authorization: Bearer $APISROUTER_API_KEY" | head -50

# confirm a chat completion works end to end
curl -s https://api.apisrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $APISROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6",
       "messages":[{"role":"user","content":"ping"}]}'

Scegliere i modelli per risposte aziendali fondate.

La valutazione dei modelli dentro Onyx è insolitamente concreta: fai la stessa domanda contro gli stessi connettori con due default di assistente diversi e confronta quale risposta cita i passaggi giusti. Il log di utilizzo per chiave prezza entrambi i candidati sul tuo reale mix di domande.

• Rispondere in modo fondato è lavoro ricco di input: il modello legge passaggi recuperati che superano di gran lunga la risposta che scrive. Il prezzo per token di input imposta quindi il costo per domanda più del prezzo di output.
• claude-sonnet-4-6 è un forte default per il workspace: disciplinato nel restare dentro le fonti recuperate e resistente a inventare policy che non sono nei documenti.
• Gli assistenti ad alto traffico (helpdesk IT, FAQ HR) funzionano bene su claude-haiku-4-5-20251001 o deepseek-v4-pro, dove il prezzo a volume mantiene prevedibile il costo per postazione.
• I documenti sorgente lunghi favoriscono gli id a contesto lungo; gemini-3.1-pro-preview merita di essere testato per assistenti che caricano nel contesto grandi documenti di design o contratti.
• Registra diversi id in un unico provider e assegnali per assistente. Livelli di qualità per team battono un unico modello di compromesso globale.

Pagamento a consumo · sotto i prezzi ufficiali

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

Le modalità di errore specifiche di Onyx.

Provider Name non è un'etichetta di testo libero. Deve corrispondere a una chiave provider LiteLLM, e per un gateway quella chiave è openai. Un nome inventato fallisce al momento della richiesta con un errore di provider LiteLLM anche se il modulo si è salvato correttamente. La Base URL vuole il suffisso /v1. La documentazione stessa di Onyx mostra forme di endpoint che terminano in /v1; senza di esso, il percorso chat-completions si risolve male e le richieste danno 404 al gateway. Gli id dei modelli vivono in Model Configurations. Un modello mai registrato lì non può essere selezionato come default, e un errore di battitura in un id registrato emerge come errore model-not-found al primo utilizzo, non al momento del salvataggio. L'elenco /v1/models del gateway è la grafia autorevole. Se la tua UI admin manca del campo Base URL nel modulo dei modelli personalizzati, hai incontrato una regressione UI segnalata in alcune release del 2026 piuttosto che una funzionalità mancante; aggiornare ripristina il campo. E ricorda quale metà hai spostato: se i risultati di ricerca sembrano sbagliati o obsoleti, si tratta di indicizzazione e connettori, che non toccano mai il provider personalizzato. Solo le risposte generate si instradano attraverso il gateway.

Chi instrada Onyx tramite un gateway.

• Team self-hosted che sostituiscono account per fornitore con un unico endpoint, una chiave, e un utilizzo per chiave che si mappa in modo pulito su un workspace o un dipartimento.
• Aziende che hanno standardizzato su Onyx per la ricerca interna e vogliono risposte fondate di qualità Claude senza un rapporto di fatturazione separato con Anthropic.
• Team di piattaforma che eseguono più assistenti a livelli di qualità diversi, prezzati per assistente tramite id di modello registrati su un unico provider.
• Valutatori che confrontano la qualità delle risposte tra famiglie di modelli su corpus identici, dove ogni candidato è un id registrato invece di una nuova integrazione di provider.
• Sviluppatori senza accesso alla fatturazione di un dato fornitore. L'accesso basato su ricarica senza obbligo di carta rimuove la dipendenza dalla registrazione per provider.

Verifica l'endpoint e fai debug della prima chat.

I due controlli curl sopra coprono la metà del gateway prima ancora di toccare il modulo: gli id che intendi registrare devono comparire in /v1/models, e un chat completion diretto dovrebbe rispondere. Dentro Onyx, i fallimenti si localizzano rapidamente. Un errore di provider che nomina LiteLLM significa che il Provider Name non è una chiave valida; impostalo su openai. Un errore di autenticazione alla prima chat significa che l'API Key non appartiene all'endpoint in Base URL. Un errore model-not-found è una discrepanza di id tra Model Configurations e il catalogo. Risposte che si generano ma ignorano i tuoi documenti sono un problema di recupero o di connettore, a monte del provider LLM del tutto. Una volta che le chat fluiscono, la console di APIsRouter mostra modello per richiesta, conteggi dei token e spesa. Per uno strumento da workspace dove ogni domanda porta contesto recuperato, quel numero di token per domanda è la base onesta per la pianificazione della capacità, e una chiave per workspace trasforma il log di utilizzo in un report di costo a livello di dipartimento.

Domande frequenti