Provedores Customizados

O AISCouncil suporta qualquer API LLM que implemente o formato de chat completions da OpenAI. Isso permite conectar a modelos auto-hospedados, gateways LLM corporativos, provedores alternativos e servidores de inferência locais.

O Que São Provedores Customizados

Provedores customizados são endpoints LLM definidos pelo usuário que usam o formato de API compatível com OpenAI (/v1/chat/completions com streaming SSE). A maioria dos servidores de inferência modernos e gateways LLM implementam este formato, tornando-o o padrão de fato para APIs LLM.

Casos de Uso

• Modelos auto-hospedados -- Conecte a vLLM, Text Generation Inference ou LocalAI rodando em seu próprio hardware
• Gateways LLM corporativos -- Rotear através do proxy de API da sua empresa com autenticação e logging
• Proxies locais -- Use LiteLLM ou ferramentas similares para unificar múltiplos provedores atrás de um único endpoint
• Provedores alternativos -- Conecte a qualquer provedor ainda não integrado no app
• Modelos fine-tuned -- Acesse seus modelos customizados fine-tuned em qualquer plataforma de hospedagem compatível
• Deploys air-gapped -- Use modelos rodando em uma rede local sem acesso à internet

Adicionando um Provedor Customizado via Configurações

1. Abra Settings (clique no ícone de engrenagem ou pressione Ctrl+Shift+S)
2. Vá para a seção API Keys
3. Role até Custom Providers
4. Preencha os campos:

Campo	Obrigatório	Descrição
Provider ID	Sim	Um identificador curto (ex: my-llm). Deve ser único, minúsculas, sem espaços
Display Name	Sim	Nome legível por humanos mostrado no dropdown de provedores
Endpoint URL	Sim	URL completa para o endpoint de chat completions (ex: https://my-api.example.com/v1/chat/completions)
API Key	Não	Bearer token para autenticação (deixe vazio se não for necessário)
Models	Sim	Lista separada por vírgulas de IDs de modelos disponíveis neste endpoint

5. Clique Save
6. O provedor aparece no dropdown de provedores ao criar ou configurar um bot

Registro Programático

Você pode registrar provedores customizados do console do navegador ou de um script:

AIS.Providers.registerCustom("my-provider", {
  name: "Meu Provedor",
  endpoint: "https://my-api.example.com/v1/chat/completions",
  models: [
    { id: "my-model-7b", name: "Meu Modelo 7B" },
    { id: "my-model-70b", name: "Meu Modelo 70B" },
  ],
  apiStyle: "openai",
});

Opções de Registro

Opção	Tipo	Padrão	Descrição
name	string	ID do Provedor	Nome de exibição
endpoint	string	Obrigatório	URL completa para o endpoint de chat completions
models	array	[{id: 'default', name: id}]	Modelos disponíveis
apiStyle	string	'openai'	Formato de API (atualmente apenas 'openai' é suportado)
extraHeaders	object	{}	Headers HTTP adicionais para incluir em toda requisição
pricing	object	null	Info de preço (para rastreamento de custos)
maxInput	number	0	Comprimento máximo de contexto de entrada (apenas para exibição)

Headers Extras

Se seu endpoint requer headers customizados (ex: para esquemas de autenticação diferentes de Bearer tokens):

AIS.Providers.registerCustom("corp-gateway", {
  name: "Gateway Corporativo",
  endpoint: "https://llm.corp.internal/v1/chat/completions",
  models: [{ id: "gpt-4o", name: "GPT-4o (via gateway)" }],
  extraHeaders: {
    "X-Corp-Token": "seu-token-interno",
    "X-Department": "engineering",
  },
});

Persistência

Provedores customizados são automaticamente salvos no localStorage sob a chave ais-custom-providers. Eles são restaurados em todo carregamento de página, então você só precisa registrá-los uma vez.

Gerenciando Provedores Customizados

Listar provedores customizados registrados

const customIds = AIS.Providers.listCustom();
// ['my-provider', 'corp-gateway']

Remover um provedor customizado

AIS.Providers.removeCustom("my-provider");

Isso remove tanto do registro runtime quanto do localStorage.

Listar todos os provedores (integrados + customizados)

const all = AIS.Providers.list();
// [{ name: 'anthropic', models: [...] }, { name: 'my-provider', models: [...] }, ...]

Como Funciona Internamente

Provedores customizados usam a mesma fábrica de streaming SSE openaiCompatible() que alimenta os provedores integrados OpenAI, xAI, OpenRouter, DeepSeek, Groq e outros. Esta fábrica:

1. Constrói um corpo de requisição padrão no formato OpenAI (model, messages, temperature, max_tokens, stream, etc.)
2. Envia uma requisição POST com header Authorization: Bearer {apiKey}
3. Parseia o stream SSE (linhas data: {...}) para deltas de conteúdo
4. Lida tanto com formatos de resposta streaming (delta) quanto non-streaming (message)
5. Extrai uso de tokens do campo usage se presente

Todos os campos de config funcionam com provedores customizados: temperature, top_p, frequency_penalty, presence_penalty, sequências de parada, formato de resposta e esforço de raciocínio.

Serviços Compatíveis

Os seguintes serviços implementam o formato de API compatível com OpenAI e funcionam como provedores customizados:

Serviço	Endpoint	Notas
LiteLLM	http://localhost:4000/v1/chat/completions	Proxy que unifica 100+ provedores
LocalAI	http://localhost:8080/v1/chat/completions	Rode modelos open-source localmente
vLLM	http://localhost:8000/v1/chat/completions	Servidor de inferência de alta performance
Text Generation Inference	http://localhost:8080/v1/chat/completions	Servidor de inferência Hugging Face
Ollama	http://localhost:11434/v1/chat/completions	Já integrado, mas pode ser adicionado como customizado também
llama.cpp (modo server)	http://localhost:8080/v1/chat/completions	Inferência C++ leve
Jan	http://localhost:1337/v1/chat/completions	App desktop com modelos locais
LM Studio	http://localhost:1234/v1/chat/completions	App desktop com gerenciamento de modelos
Cloudflare Workers AI	https://api.cloudflare.com/client/v4/accounts/{id}/ai/v1/chat/completions	Integrado, mas pode customizar
Azure OpenAI	https://{resource}.openai.azure.com/openai/deployments/{deployment}/chat/completions?api-version=2024-02-01	Requer header api-key

Solução de Problemas

Erros CORS

CORS (Cross-Origin Resource Sharing)

Quando o navegador chama um endpoint de API diretamente, o servidor deve incluir headers CORS em sua resposta. Sem eles, o navegador bloqueia a requisição por razões de segurança.

Se você ver um erro CORS no console, seu endpoint customizado precisa retornar estes headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Methods: POST, OPTIONS

Para serviços locais:

• Ollama: Defina a variável de ambiente OLLAMA_ORIGINS=* antes de iniciar
• vLLM: Adicione a flag --allowed-origins '*'
• LiteLLM: Adicione a flag --cors ou defina LITELLM_ALLOW_ORIGINS=*
• LocalAI: CORS está habilitado por padrão

Para serviços remotos atrás de reverse proxy (Nginx):

location /v1/ {
    add_header 'Access-Control-Allow-Origin' '*' always;
    add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization' always;
    add_header 'Access-Control-Allow-Methods' 'POST, OPTIONS' always;

    if ($request_method = 'OPTIONS') {
        return 204;
    }

    proxy_pass http://localhost:8000;
}

Conexão Recusada

• Verifique se a URL do endpoint está correta e o serviço está rodando
• Para serviços locais, certifique-se de que o servidor está escutando na porta esperada
• Para serviços localhost, tente 127.0.0.1 em vez (ou vice-versa)
• Verifique se nenhum firewall está bloqueando a porta

Erros de Autenticação

• Verifique se sua chave de API está correta
• Alguns serviços usam headers de auth diferentes -- use extraHeaders se o serviço não usa formato padrão Authorization: Bearer
• Azure OpenAI usa header api-key em vez de Authorization

Respostas Vazias ou Ilegíveis

• Confirme que o endpoint retorna formato SSE compatível com OpenAI (data: {"choices":[{"delta":{"content":"..."}}]})
• Alguns serviços requerem stream: true no corpo da requisição (o app envia isso por padrão)
• Verifique se o ID do modelo corresponde ao que o serviço espera
• Abra a aba Network do DevTools do navegador para inspecionar a requisição e resposta brutas