> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# LLM 提供商 (Provider) 集成

> OpenRouter、Anthropic、DeepSeek、Z.ai、本地服务器与 Portkey 的提供商 (Provider) 与入口 (Gateway) 配置。

<Note>
  *提供商 (Provider) 选餐厅，入口 (Gateway) 选下单方式。*
</Note>

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

<br />

## 1. 默认路由

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export OPENROUTER_API_KEY="sk-or-v1-..."
```

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/quickstart/first-llm)。

<br />

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

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

<CodeGroup>
  ```bash OpenRouter theme={"theme":{"light":"github-light","dark":"github-dark"}}
  export OPENROUTER_API_KEY="sk-or-v1-..."
  hb cfg set heavenbase.llm.default_provider openrouter
  ```

  ```bash DeepSeek theme={"theme":{"light":"github-light","dark":"github-dark"}}
  export DEEPSEEK_API_KEY="sk-..."
  hb cfg set heavenbase.llm.default_provider deepseek
  hb cfg set heavenbase.llm.presets.chat.model deepseek-v4-flash
  ```

  ```bash Anthropic theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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
  ```

  ```bash Z.ai theme={"theme":{"light":"github-light","dark":"github-dark"}}
  export ZAI_API_KEY="..."
  hb cfg set heavenbase.llm.default_provider zai
  hb cfg set heavenbase.llm.presets.chat.model glm-4.7-flash
  ```

  ```bash LM Studio theme={"theme":{"light":"github-light","dark":"github-dark"}}
  hb cfg set heavenbase.llm.default_provider lmstudio
  hb cfg set heavenbase.llm.presets.chat.model qwen3.6-flash
  ```
</CodeGroup>

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)
```

<br />

## 3. 入口 (Gateway) 示例

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export PORTKEY_API_KEY="..."
```

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb

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

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/quickstart/first-llm) §5.2 与 [高级 LLM](/features/llm/advanced)。

<br />

## 4. Anthropic 入口 (Gateway) 决策

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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()` 获取路由证据：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
runtime = hb.LLM(model="haiku", provider="anthropic", gateway="anthropic").spec.materialize()
print(runtime["base_url"])
```

<br />

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

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
runtime = hb.LLM(model="glm-flash", provider="zai", gateway="portkey").spec.materialize()
print(runtime["model"])
```

<br />

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

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

也可直接传入 proxy 设置：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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",
)
```

<br />

## 进一步探索

<Tip>
  **相关资源：**

  * [首个 LLM](/quickstart/first-llm) — 配置密钥并运行首次对话。
  * [LLM 概述](/features/llm/overview) — 预设 (Preset)、模型与解析模型。
  * [高级 LLM](/features/llm/advanced) — 入口 (Gateway) 深度、缓存与上游限制。
</Tip>

<br />