LLM 提供商 (Provider) 集成

提供商 (Provider) 选餐厅，入口 (Gateway) 选下单方式。

HeavenBase 将模型由谁提供（provider）与请求如何发送（gateway）分开配置。多数项目只需设置一个 API 密钥、保留默认 openrouter 提供商 (Provider)，在需要 Portkey、LiteLLM 或原生 Anthropic 之前无需改动入口 (Gateway) 配置。

1. 默认路由

新项目设置一个 OpenRouter 密钥并使用预设 (Preset)：

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="chat" 默认解析为 deepseek-v4-flash。内置默认提供商 (Provider) 为 openrouter，默认入口 (Gateway) 为 openai，即 HeavenBase 通过 OpenAI Python SDK 访问提供商 (Provider) 的 OpenAI 兼容端点 (Endpoint)。完整提供商 (Provider) 目录与各密钥配置示例见首个 LLM。

2. 切换默认提供商 (Provider)

当大多数调用应使用同一提供商 (Provider) 时，设置 default_provider：

export OPENROUTER_API_KEY="sk-or-v1-..."
hb cfg set heavenbase.llm.default_provider openrouter

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

export ANTHROPIC_API_KEY="sk-ant-..."
hb cfg set heavenbase.llm.default_provider anthropic
hb cfg set heavenbase.llm.presets.chat.model claude-sonnet-4-6

export ZAI_API_KEY="..."
hb cfg set heavenbase.llm.default_provider zai
hb cfg set heavenbase.llm.presets.chat.model glm-4.7-flash

hb cfg set heavenbase.llm.default_provider lmstudio
hb cfg set heavenbase.llm.presets.chat.model qwen3.6-flash

比较路由时为单次调用指定显式提供商 (Provider)：

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

3. 入口 (Gateway) 示例

需要路由策略、可观测性或入口侧控制时使用 gateway="portkey"：

export PORTKEY_API_KEY="..."

import heavenbase as hb

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

进行简短 live 路由检查时，这是低成本的确定性路径：

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

Gateway	适用场景
`openai`	希望通过 OpenAI 兼容 SDK 直接调用。这是默认项。
`anthropic`	希望使用官方 Anthropic SDK 与原生 Messages 载荷。
`portkey`	需要路由、策略、可观测性或托管入口 (Gateway) 行为。
`litellm`	已通过 LiteLLM 模型名统一提供商 (Provider) 路由。
`bifrost`	运行 Bifrost 兼容 OpenAI 端点 (Endpoint)。
`mock`	需要离线确定性测试。

入口 (Gateway) 配置 walkthrough 见首个 LLM §5.2 与高级 LLM。

4. Anthropic 入口 (Gateway) 决策

HeavenBase 支持两条 Anthropic 路由。用 OpenAI SDK 兼容端点 (Endpoint) 做快速 Claude 检查及与其他 OpenAI 兼容提供商 (Provider) 的比较：

import heavenbase as hb

llm = hb.LLM(model="haiku", provider="anthropic", gateway="openai", cache=False)
print(llm.spec.materialize()["base_url"])

需要官方 Anthropic Python SDK 与 Claude Messages 格式时使用原生入口 (Gateway)：

llm = hb.LLM(model="haiku", provider="anthropic", gateway="anthropic", cache=False)
print(llm.spec.materialize()["base_url"])

当前路由为 preset -> model -> provider -> gateway，最终 URL 来自 provider 配置、gateway 配置或调用时 base_url=... 覆盖。原生入口 (Gateway) 将 HeavenBase 内部 OpenAI 风格 message/tool 历史转换为 Anthropic Messages 载荷，将规范 think 与 reasoning_effort 控制映射到 Anthropic thinking 字段，再将响应归一化回常用 include 字段。代理 (Proxy) 支持符合该模型：

Portkey 支持 OpenAI Chat Completions、OpenAI Responses 与 Anthropic Messages 入口 (Gateway) 格式。
LiteLLM 通过 anthropic/ provider 路由与 /v1/messages 透传支持 Anthropic。
Bifrost 通过 OpenAI 兼容转换为 /v1/messages，以及 provider 兼容 Anthropic SDK 端点 (Endpoint) 支持 Anthropic。

无需 live Claude 花费即可用 materialize() 获取路由证据：

runtime = hb.LLM(model="haiku", provider="anthropic", gateway="anthropic").spec.materialize()
print(runtime["base_url"])

5. GLM 与 Z.ai 路由检查

GLM 工具调用验证保持原生 OpenAI JSON tools 为默认。需要广泛兼容路由时，从通过 Portkey 的 OpenRouter 上的 glm-flash 开始。

runtime = hb.LLM(model="glm-flash", provider="zai", gateway="portkey").spec.materialize()
print(runtime["model"])

6. 代理 (Proxy) 与 VPN 说明

本地 live 检查可使用提供商 (Provider) 密钥、base URL 覆盖，以及 ~/.bashrc 中的简单 proxy 导出，包括 HTTP_PROXY、HTTPS_PROXY 与 NO_PROXY。当 VPN/TUN 模式改变 GLM、Anthropic 或 OpenRouter 可达性时使用这些导出。也可直接传入 proxy 设置：

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",
)

进一步探索

相关资源：

首个 LLM — 配置密钥并运行首次对话。
LLM 概述 — 预设 (Preset)、模型与解析模型。
高级 LLM — 入口 (Gateway) 深度、缓存与上游限制。

​1. 默认路由

​2. 切换默认提供商 (Provider)

​3. 入口 (Gateway) 示例

​4. Anthropic 入口 (Gateway) 决策

​5. GLM 与 Z.ai 路由检查

​6. 代理 (Proxy) 与 VPN 说明

​进一步探索

1. 默认路由

2. 切换默认提供商 (Provider)

3. 入口 (Gateway) 示例

4. Anthropic 入口 (Gateway) 决策

5. GLM 与 Z.ai 路由检查

6. 代理 (Proxy) 与 VPN 说明

进一步探索