Rode o Onyx em um provedor de LLM personalizado compatível com OpenAI.

Resposta rápida: Add Custom LLM Provider no painel admin.

A documentação do Onyx é explícita que um provedor personalizado funciona contanto que exponha endpoints compatíveis com OpenAI, e seu formato de exemplo de Base URL é exatamente um estilo de gateway https://yourprovider.com/v1. O fluxo: abra o Admin Panel pelo ícone do seu perfil, vá para Configuration, depois Language Models, e escolha Add Custom LLM Provider. Quatro decisões importam nesse formulário. Display Name é cosmético. Provider Name precisa corresponder a uma chave de provedor LiteLLM, porque o Onyx roteia chamadas de modelo pelo LiteLLM por baixo dos panos; para um gateway compatível com OpenAI isso é openai. Base URL é o endpoint do gateway incluindo o sufixo /v1. E a seção Model Configurations é onde você registra cada id de modelo que quer disponível, soletrado exatamente como o catálogo o serve. Salve, escolha um padrão, e os chats roteiam pelo gateway imediatamente.

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

Onde o LLM se encaixa na arquitetura do Onyx.

O Onyx (onyx-dot-app no GitHub, cerca de 31 mil estrelas, antigamente Danswer) é uma plataforma de IA open-source para conhecimento corporativo: indexa fontes como Slack, Google Drive, Confluence, e dezenas de outros conectores, depois responde perguntas sobre eles através de uma UI de chat, assistentes, e fluxos de trabalho de agente. É uma das stacks de busca empresarial auto-hospedadas mais implantadas, o que é exatamente por que sua conta de LLM merece uma decisão de roteamento em vez de um padrão. O pipeline se divide claramente em dois. Indexação e recuperação, incluindo embedding de documento e reranking, rodam no próprio servidor de modelo do Onyx com modelos locais por padrão; nada disso toca seu provedor de LLM. Geração de resposta é a outra metade: uma vez que a recuperação monta as passagens relevantes, um LLM as lê e escreve a resposta fundamentada, e essa chamada passa pelo LiteLLM para qualquer provedor que o admin configurou. O fluxo de provedor personalizado troca o destino de exatamente essa metade. Como o LiteLLM encaminha o id do modelo como uma string simples para um provedor do tipo openai, os ids que você registra em Model Configurations podem ser qualquer coisa que o endpoint atrás da Base URL sirva: Claude para respostas fundamentadas cuidadosas, DeepSeek para volume, Gemini para contextos de fonte muito longos. Assistentes diferentes podem ter modelos padrão diferentes, então um assistente de suporte e um assistente de engenharia podem andar em pontos de preço diferentes através da mesma entrada de provedor.

Configuração completa, e o que continua intocado.

O formulário de provedor é a integração inteira; não há arquivo de configuração para editar ou container para reconstruir por causa disso. Depois de salvar, defina o modelo padrão para o workspace, e opcionalmente sobrescreva o modelo por assistente onde você quiser níveis de qualidade diferentes. O que deliberadamente continua intocado: conectores mantêm suas próprias credenciais, o índice não é afetado, e o modelo de embedding configurado para busca não se move. Essa separação vale a pena explicar porque torna essa uma mudança de baixo risco. Se o gateway se comportasse mal, a busca e as fontes ainda funcionariam; só a geração de resposta daria erro, e trocar o padrão de volta para um provedor anterior é um dropdown. Para times que automatizam deployments, a mesma definição de provedor pode ser semeada pela API do Onyx em vez de clicada pela UI, mas o caminho do painel admin é a superfície documentada e estável, e uma configuração única raramente justifica mais.

# 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"}]}'

Escolhendo modelos para respostas empresariais fundamentadas.

A avaliação de modelo dentro do Onyx é incomumente concreta: faça a mesma pergunta contra os mesmos conectores com dois padrões de assistente diferentes e compare qual resposta cita as passagens certas. O log de uso por chave precifica os dois candidatos na sua mistura real de perguntas.

• Responder de forma fundamentada é pesado em entrada: o modelo lê passagens recuperadas que ofuscam a resposta que escreve. O preço por token de entrada, portanto, define seu custo por pergunta mais do que o preço de saída.
• claude-sonnet-4-6 é um padrão forte de workspace: disciplinado em ficar dentro das fontes recuperadas e resistente a inventar política que não está nos documentos.
• Assistentes de alto tráfego (helpdesk de TI, FAQ de RH) rodam bem em claude-haiku-4-5-20251001 ou deepseek-v4-pro, onde preço de volume mantém o custo por assento previsível.
• Documentos de fonte longos favorecem ids de contexto longo; gemini-3.1-pro-preview vale a pena testar para assistentes que puxam documentos de design ou contratos grandes para o contexto.
• Registre vários ids em uma entrada de provedor e atribua-os por assistente. Níveis de qualidade por time superam um modelo de compromisso global.

Pague pelo uso · abaixo do preço oficial

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

Modos de falha específicos do Onyx.

Provider Name não é um rótulo de texto livre. Precisa corresponder a uma chave de provedor LiteLLM, e para um gateway essa chave é openai. Um nome inventado falha em tempo de requisição com um erro de provedor LiteLLM mesmo que o formulário tenha salvado normalmente. A Base URL quer o sufixo /v1. A própria documentação do Onyx mostra formatos de endpoint terminando em /v1; sem ele, o caminho de chat-completions se resolve errado e as requisições dão 404 no gateway. Ids de modelo vivem em Model Configurations. Um modelo que você nunca registrou ali não pode ser selecionado como padrão, e um erro de digitação em um id registrado aparece como um erro model-not-found no primeiro uso, não no momento de salvar. A listagem /v1/models do gateway é a grafia autoritativa. Se sua UI de admin está faltando o campo Base URL no formulário de modelos personalizados, você esbarrou em uma regressão de UI reportada em alguns releases de 2026 em vez de um recurso ausente; atualizar restaura o campo. E lembre qual metade você moveu: se os resultados de busca parecem errados ou desatualizados, isso é indexação e conectores, que nunca tocam o provedor personalizado. Só as respostas geradas roteiam pelo gateway.

Quem roteia o Onyx por um gateway.

• Times auto-hospedados substituindo contas por fornecedor por um endpoint, uma chave, e uso por chave que mapeia limpo para um workspace ou departamento.
• Empresas que padronizaram no Onyx para busca interna e querem respostas fundamentadas com qualidade Claude sem uma relação de faturamento separada com a Anthropic.
• Times de plataforma rodando vários assistentes em níveis de qualidade diferentes, precificados por assistente através de ids de modelo registrados em um provedor.
• Avaliadores comparando qualidade de resposta entre famílias de modelo em corpora idênticos, onde cada candidato é um id registrado em vez de uma nova integração de provedor.
• Desenvolvedores sem acesso ao faturamento de um determinado fornecedor. O acesso baseado em recarga sem exigência de cartão remove a dependência de cadastro por provedor.

Verifique o endpoint e depure o primeiro chat.

As duas checagens de curl acima cobrem a metade do gateway antes de você tocar no formulário: os ids que você planeja registrar precisam aparecer em /v1/models, e uma chat completion direta deve responder. Dentro do Onyx, as falhas se localizam rápido. Um erro de provedor nomeando LiteLLM significa que o Provider Name não é uma chave válida; defina-o como openai. Um erro de autenticação no primeiro chat significa que a API Key não pertence ao endpoint em Base URL. Um erro model-not-found é um descompasso de id entre Model Configurations e o catálogo. Respostas que geram mas ignoram seus documentos são um problema de recuperação ou conector, a montante do provedor de LLM inteiramente. Assim que os chats fluem, o console da APIsRouter mostra modelo, contagens de token e gasto por requisição. Para uma ferramenta de workspace onde toda pergunta carrega contexto recuperado, esse número de tokens por pergunta é a base honesta para planejamento de capacidade, e uma chave por workspace transforma o log de uso em um relatório de custo por departamento.

Perguntas frequentes