LLM Provider 集成

Provider 选择厨房；Gateway 决定订单由服务员、API 还是信鸽送达。

1. 动机

HeavenBase 将模型由谁提供与请求如何传输分开。这样，应用意图可以保持稳定，而凭据、端点与 Gateway 策略可随环境变化。

provider 拥有模型托管、凭据与 base URL。
gateway 拥有 SDK 或代理传输形状。
model 在一个规范别名背后拥有 Provider 特定标识符。

2. 使用默认路由

一枚 OpenRouter 密钥可覆盖最广泛的内置模型集合：

export OPENROUTER_API_KEY="sk-or-v1-..."

import heavenbase as hb

llm = hb.LLM(preset="chat", cache=False)
text = llm.chat("Reply with exactly: hb-ok", max_tokens=8)

默认路由为 preset -> model -> openrouter -> openai。这里的 openai 指 OpenAI 兼容 Gateway，而不一定是模型宿主。

3. 选择托管 Provider

Provider id	凭据	默认端点家族
`openrouter`	`OPENROUTER_API_KEY`	OpenRouter
`openai`	`OPENAI_API_KEY`	OpenAI
`anthropic`	`ANTHROPIC_API_KEY`	Anthropic
`grok`	`XAI_API_KEY`	xAI
`gemini`	`GEMINI_API_KEY`	Google OpenAI 兼容层
`deepseek`	`DEEPSEEK_API_KEY`	DeepSeek
`moonshot`, `moonshot-zh`	`MOONSHOT_API_KEY`	Moonshot 全球或中国区
`zai`, `zai-zh`	`ZAI_API_KEY`	Z.ai 全球或中国区
`minimax`	`MINIMAX_API_KEY`	MiniMax
`cohere`	`COHERE_API_KEY`	Cohere 嵌入
`voyage`	`VOYAGE_API_KEY`	Voyage 嵌入
`dashscope`	`DASHSCOPE_API_KEY`	阿里云 DashScope

当多数调用应共享一个宿主时，请设置默认 Provider：

export DEEPSEEK_API_KEY="sk-..."
hb cfg set heavenbase.llm.default_provider deepseek
hb cfg set heavenbase.llm.presets.chat.model deepseek-v4-flash

比较路由时，可为单次调用固定 Provider：

fast = hb.LLM(model="ds-flash", provider="deepseek", cache=False)
claude = hb.LLM(model="haiku", provider="anthropic", cache=False)
grok = hb.LLM(model="grok", provider="grok", cache=False)

4. 选择 Gateway

Gateway	传输
`openai`	通过 OpenAI Python SDK 访问 OpenAI 兼容端点
`anthropic`	官方 Anthropic SDK 与原生 Messages 负载
`portkey`	Portkey 路由、策略与可观测性
`litellm`	LiteLLM Provider 适配器生态
`bifrost`	Bifrost 兼容 Provider 路由
`mock`	确定性离线适配器

export PORTKEY_API_KEY="..."

llm = hb.LLM(preset="chat", gateway="portkey", cache=False)

当 Claude Messages 负载或 Anthropic SDK 行为很重要时，请使用原生 Anthropic Gateway：

llm = hb.LLM(model="haiku", provider="anthropic", gateway="anthropic")

5. 不花钱检查路由

print Apply Profile 会解析脱敏路由视图，但不会调用模型。

llm = hb.LLM(
    model="haiku",
    provider="anthropic",
    gateway="anthropic",
)
route = llm.spec.engine.apply(llm.spec, profile="print")

print(route["bindings"]["provider"]["base_url"])

最终 URL 来自 Provider 配置、Gateway 配置或调用时的 base_url=... 覆盖。 print Profile 会脱敏密钥。原始 spec.to_dict() binding 可能包含密钥，绝不能记录。

6. 运行本地 Provider

Provider id	默认 URL	典型用途
`ollama`	`http://localhost:11434/v1`	本地聊天、图像生成与 OCR
`lmstudio`	`http://localhost:1234/v1`	本地聊天与嵌入
`omlx`	`http://localhost:8000/v1`	Apple Silicon OpenAI 兼容服务
`vllm`	`http://localhost:8000/v1`	自托管 OpenAI 兼容服务

打包的本地 Preset 会保持 Provider 显式：

local 与 worker-local 使用 LM Studio 和 qwen3.6-flash。
embed-local 使用 LM Studio 和 embeddinggemma。
imagen-local 使用 Ollama 和 z-image-turbo。
ocr-local 使用 Ollama 和 glm-ocr。

服务器在其他位置运行时，请覆盖环境 URL：

export LM_STUDIO_BASE_URL="http://127.0.0.1:1234/v1"

7. 谨慎处理代理

标准 HTTP_PROXY、HTTPS_PROXY 与 NO_PROXY 值适用于许多 SDK 路由。调用时传值会让路由在应用代码中保持可见：

llm = hb.LLM(
    preset="chat",
    http_proxy="http://127.0.0.1:7890",
    https_proxy="http://127.0.0.1:7890",
    no_proxy="localhost,127.0.0.1",
)

本地 Provider 默认会清除继承的代理，避免 loopback 调用意外离开机器。当 VPN 或 TUN 模式改变连通性时，请检查物化路由。

总结

Provider 选择托管；Gateway 选择传输。
规范 Model 别名让路由变化远离应用逻辑。
脱敏的 print Apply Profile 无需实时请求即可提供路由证据。
本地 Preset 会固定其运行时所需的 Provider。

进一步探索

相关资源：

First LLM — 配置凭据并运行首次调用
LLM 概述 — Preset 与 Model 目录
高级 LLM — Gateway 限制、缓存与客户端导出

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

1. 动机

2. 使用默认路由

3. 选择托管 Provider

4. 选择 Gateway

5. 不花钱检查路由

6. 运行本地 Provider

7. 谨慎处理代理

总结

进一步探索

​1. 动机

​2. 使用默认路由

​3. 选择托管 Provider

​4. 选择 Gateway

​5. 不花钱检查路由

​6. 运行本地 Provider

​7. 谨慎处理代理

​总结

​进一步探索

1. 动机

2. 使用默认路由

3. 选择托管 Provider

4. 选择 Gateway

5. 不花钱检查路由

6. 运行本地 Provider

7. 谨慎处理代理

总结

进一步探索