Custom（OpenAI 兼容）

TL;DR

ONGRID_CUSTOM_API_KEY=...
ONGRID_CUSTOM_BASE_URL=https://your-relay/v1     # REQUIRED — no upstream default
ONGRID_CUSTOM_MODEL=your-default-model

Provider id：custom。SDK 适配器：eino-openai（任何 OpenAI Chat Completions 兼容端点）。

Custom 槽是 Settings UI 里的第 7 张 provider 卡片。它给所有"wire 层是 OpenAI 兼容但不属于六个内置 provider 之一"的用：

• 自托管的 vLLM / TGI / llama.cpp。
• OpenRouter、Together、Fireworks、Anyscale、Groq、Mistral。
• 公司内部模型网关。
• Ongrid 还没给加专属槽的新 provider。

base URL 守卫

custom 槽必须显式 base URL。没有的话，底层 SDK 会悄悄回退到 OpenAI 的 默认（https://api.openai.com/v1），把运维的 custom key 发到错的 host。 resolver 这种情况下跳过 provider：

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

通过 env 或 Settings UI 给 BaseURL；不然 provider 永远不会出现在目录里。

env 变量

变量	默认	备注
ONGRID_CUSTOM_API_KEY	—	空 = provider 掉出
ONGRID_CUSTOM_BASE_URL	—	必填
ONGRID_CUSTOM_MODEL	—	每次调用发出的默认 model id
ONGRID_CUSTOM_MODELS	—	目录列表（SPA picker 显示的闭合集）

没有开箱默认目录 —— 按你 endpoint 支持的填。

预注册的内层 ChatModel

graph-kernel 运行时启动时为 custom provider id 预注册一个内层 ChatModel， 就算还没配 key。这就是运维从 Settings UI 期待的"启动后再配也立即路由、不 重启"的属性：

// 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, "") // model supplied per-call (picker / DefaultResolver)
    }
}

内层在启动时就在；按调的 key / baseURL 通过 LLM-settings resolver 动态解。 未配置 provider 永远到不了 picker（/v1/aiops/models 目录在 ResolveProviders 上把门），所以在真用上之前内层无害。

配置示例

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

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 默认不校 API key —— 给任意非空字符串就行。

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

把 Custom 设为默认

ONGRID_LLM_DEFAULT_PROVIDER=custom

小心 LLM resolver bug —— default_provider 没设时，resolver 会回退到字典 序第一个 provider id（anthropic）。OpenRouter 通过 custom 槽接上，但 default_provider=""，chat 调用就把 Anthropic 的 model id 发到 Anthropic 端点，不是 OpenRouter —— 认证直接挂。明确设 default_provider=custom。

怪癖

• schema 保真度 —— 假设 endpoint 说真的 OpenAI Chat Completions。剥 字段（tool_calls、finish_reason）的 endpoint 会稳定降低 agent 的函数 调用可靠性。
• 流式 —— 很多中继还不支持流式。适配器两种模式都处理；如果 Stream() 返 "streaming not supported"，chat UI 自动回退到缓冲。
• 没原生限流 —— 公司网关常按 token 限流，不显示为标准 429。 设 ONGRID_LLM_DAILY_TOKEN_LIMIT 做跨 provider 预算守卫 —— 见 预算。

另见

• OpenAI（GPT） —— 真 OpenAI 端点或 Azure OpenAI。
• 模型概览。
• 路由。