Custom (OpenAI-compatible)

TL;DR

ONGRID_CUSTOM_API_KEY=...
ONGRID_CUSTOM_BASE_URL=https://your-relay/v1     # OBRIGATÓRIO — sem default upstream
ONGRID_CUSTOM_MODEL=your-default-model

Provider id: custom. Adapter SDK: eino-openai (qualquer endpoint compatível com OpenAI Chat Completions).

O slot Custom é o 7º card de provider na UI de Settings. Existe para tudo que é compatível com OpenAI no nível wire mas não é um dos seis providers embutidos:

• vLLM / TGI / llama.cpp self-hosted.
• OpenRouter, Together, Fireworks, Anyscale, Groq, Mistral.
• Gateways internos corporativos de modelo.
• Providers novos que aparecem antes do Ongrid adicionar um slot dedicado a eles.

A guard de base-URL

O slot custom exige uma base URL explícita. Sem uma, o SDK subjacente cairia silenciosamente para o default da OpenAI (https://api.openai.com/v1), enviando a chave custom do operador para o host errado. O resolver pula o provider nesse caso:

// internal/manager/biz/setting/llm.go:155
if pk.id == model.LLMProviderCustom && strings.TrimSpace(baseURL) == "" {
    continue
}

Forneça uma BaseURL via env ou Settings UI; caso contrário o provider nunca aparece no catálogo.

Env vars

Var	Padrão	Notas
ONGRID_CUSTOM_API_KEY	—	Vazio = provider removido
ONGRID_CUSTOM_BASE_URL	—	OBRIGATÓRIO
ONGRID_CUSTOM_MODEL	—	Id de modelo padrão enviado em cada call
ONGRID_CUSTOM_MODELS	—	Lista do catálogo (conjunto fechado que o picker do SPA mostra)

Não há catálogo padrão de fábrica — preencha com o que seu endpoint suporta.

ChatModel interno pré-registrado

O runtime do graph-kernel pré-registra um ChatModel interno para o provider id custom no boot, mesmo quando nenhuma chave está configurada ainda. Essa é a propriedade "configurado DEPOIS do boot rotea imediatamente, sem restart" que operadores esperam da UI de Settings:

// cmd/ongrid/main.go:2457
for _, id := range []string{
    llm.ProviderOpenAI, llm.ProviderAnthropic, llm.ProviderZhipu,
    llm.ProviderGemini, llm.ProviderDeepSeek, llm.ProviderKimi, llm.ProviderCustom,
} {
    if _, ok := innerModels[id]; !ok {
        addInner(id, "") // modelo fornecido por-call (picker / DefaultResolver)
    }
}

O interno existe no boot; a chave / baseURL por-call é resolvida dinamicamente via o resolver de settings-LLM. Providers não-configurados nunca alcançam o picker (o catálogo /v1/aiops/models gateia em ResolveProviders), então o interno é inofensivo até que seja realmente necessário.

Exemplos de configuração

OpenRouter

ONGRID_CUSTOM_API_KEY=sk-or-v1-...
ONGRID_CUSTOM_BASE_URL=https://openrouter.ai/api/v1
ONGRID_CUSTOM_MODEL=anthropic/claude-sonnet-4
ONGRID_CUSTOM_MODELS=anthropic/claude-sonnet-4,anthropic/claude-opus-4,meta-llama/llama-3.3-70b

vLLM local

ONGRID_CUSTOM_API_KEY=sk-not-checked-by-vllm
ONGRID_CUSTOM_BASE_URL=http://vllm.internal:8000/v1
ONGRID_CUSTOM_MODEL=Qwen2.5-72B-Instruct
ONGRID_CUSTOM_MODELS=Qwen2.5-72B-Instruct

vLLM não valida API keys por padrão — defina qualquer string não-vazia.

Groq

ONGRID_CUSTOM_API_KEY=gsk_...
ONGRID_CUSTOM_BASE_URL=https://api.groq.com/openai/v1
ONGRID_CUSTOM_MODEL=llama-3.3-70b-versatile

Mistral

ONGRID_CUSTOM_API_KEY=...
ONGRID_CUSTOM_BASE_URL=https://api.mistral.ai/v1
ONGRID_CUSTOM_MODEL=mistral-large-latest

Tornando o Custom o padrão

ONGRID_LLM_DEFAULT_PROVIDER=custom

Cuidado com o bug do resolver LLM — se default_provider não está setado, o resolver cai para o primeiro provider id ordenado (anthropic). Com OpenRouter conectado pelo slot custom mas default_provider="", chamadas de chat vão para o id de modelo Anthropic no endpoint Anthropic, não OpenRouter — o que falha em auth. Defina default_provider=custom explicitamente.

Pegadinhas

• Fidelidade do schema — assume que o endpoint fala OpenAI Chat Completions real. Endpoints que retiram campos (tool_calls, finish_reason) vão degradar a confiabilidade do function-calling do agent.
• Streaming — muitos relays ainda não suportam streaming. O adapter trata ambos os modos; se Stream() errar com "streaming not supported", a UI de chat auto-cai para buffered.
• Sem rate-limit nativo — gateways corporativos frequentemente impõem rate limits por-token que não aparecem como 429s padrão. Defina ONGRID_LLM_DAILY_TOKEN_LIMIT para um guard de budget cross-provider — veja Budget.

Veja também

• OpenAI (GPT) — para o endpoint real OpenAI ou Azure OpenAI.
• Visão geral dos modelos.
• Roteamento.