> ## 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 概述

> HeavenBase 中统一的 LLM 访问：聊天、流式输出、嵌入、图像生成与入口 (Gateway) 路由。

<Note>
  *二十家提供商、六个入口、一个客户端。解析模型替你记住其余一切。*
</Note>

`hb.LLM` 是 HeavenBase 的 Python LLM 客户端，覆盖聊天、流式输出、嵌入、图像生成、Mock 与入口 (Gateway) 路由。它会从共享的 `heavenbase.llm` 配置中解析 preset、model、provider 与 gateway，然后物化由 gateway 选定的请求格式。

默认配置为 `preset="system"`、`default_provider="openrouter"` 与 `gateway="openai"`。一个 API 密钥即可开箱访问大多数主流模型。

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

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

llm = hb.LLM()
text = llm.chat("Reply with exactly: hb-ok")
```

<br />

## 1. 解析模型 (Resolution Model)

HeavenBase 不会要求你在代码里硬编码某家 provider 的 SDK 调用。相反，四个由配置支撑的概念解析每一次请求：

* `preset`：命名快捷方式，例如 `system`、`chat`、`reason`、`coder`、`embed`、`imagen`、`mock` 或 `custom`。
* `model`：规范模型键或别名，例如 `ds-flash`、`sonnet`、`gpt` 或 `gpt-image-mini`。
* `provider`：模型由谁提供。常规模型 preset 继承 `heavenbase.llm.default_provider`；显式 `provider=` 与 preset 级 provider 固定会覆盖它。
* `gateway`：请求如何传输。默认 `openai` 入口 (Gateway) 通过 OpenAI Python SDK 访问 OpenAI 兼容端点 (Endpoint)；`anthropic` 使用官方 Anthropic SDK 与原生 Messages 载荷。

解析路径为 `preset -> model -> provider -> gateway`。最终 URL 来自 `provider.base_url`、`gateway.base_url` 或调用时 `base_url=...` 覆盖。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb.LLM()                                      # preset="system" -> ds-flash on openrouter via openai
hb.LLM(model="ds-flash")                      # explicit model, provider inherited
hb.LLM(model="ds-flash", provider="deepseek") # pin the provider
hb.LLM(preset="reason")                       # reasoning preset
hb.LLM(preset="mock")                         # offline deterministic
```

未知关键字参数会成为 provider 请求默认值，因此调参留在调用处，而不是包一层 wrapper：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
llm = hb.LLM(model="ds-flash", max_tokens=256, temperature=0)
```

<br />

## 2. 预设 (Presets)

Preset 使用可持久化的模型别名，使用户配置保持紧凑可读。多数生产 preset 不固定 provider；更改 `heavenbase.llm.default_provider` 会一并切换它们。`embed-local`、`mock`、`custom` 等本地与特殊 preset 保留各自的 provider，因为它们需要专用配置。

| Preset        | 模型别名                  | 默认 Thinking | 说明                                |
| ------------- | --------------------- | ----------- | --------------------------------- |
| `system`      | `ds-flash`            | 关闭          | 短编排调用的默认轻量系统 LLM。                 |
| `tiny`        | `gemma`               | 关闭          | 低延迟离线工作用的小型聊天模型。                  |
| `chat`        | `ds-flash`            | 关闭          | 快速非思考回答的通用聊天 preset。              |
| `chat-pro`    | `ds-pro`              | 关闭          | 更强但仍默认避免推理的聊天 preset。             |
| `reason`      | `ds-pro`              | 开启          | 面向较难任务、在支持时暴露思考的推理 preset。        |
| `reason-pro`  | `gpt`                 | 开启          | 由默认 GPT 别名支撑的高能力推理 preset。        |
| `worker`      | `ds-flash`            | 关闭          | 确定性非思考工具调用的后台 worker preset。      |
| `coder`       | `sonnet`              | 开启          | 为多步实现工作启用思考的编码 preset。            |
| `coder-pro`   | `opus`                | 开启          | 面向深度实现与评审的最高端编码 preset。           |
| `embed`       | `gpt-embedding-small` | 不适用         | 默认嵌入 preset。                      |
| `embed-local` | `embeddinggemma`      | 不适用         | 本地嵌入 preset。                      |
| `imagen`      | `gpt-image-mini`      | 不适用         | 默认图像生成 preset。                    |
| `mock`        | `mock`                | 离线          | 测试与 demo 用的非 LLM 确定性 mock preset。 |
| `custom`      | `custom`              | 调用方提供       | 调用方提供的 OpenAI 兼容 provider preset。 |

Preset 思考默认值使用规范 `think` 选项。HeavenBase 通过 `extra_body.reasoning` 在 OpenAI 兼容入口 (Gateway)（`openai`、`portkey`、`bifrost`、`litellm`）上对 `think=True` 与 `think=False` 施加 gateway 级控制。`anthropic` 入口 (Gateway) 将 `think=True` 映射为 Claude Messages 自适应思考并摘要展示，将 `reasoning_effort` 映射为 Anthropic `effort`，并将原生思考块归一化回 `think` include 字段。每次调用的思考控制见 [LLM 对话](/features/llm/chat)。

<br />

## 3. 精选模型目录 (Curated Model Catalog)

在线内置模型包含 OpenRouter 标识符，并在可用时包含直连 provider 标识符。根级 `default_provider` 选择使用哪个标识符，除非调用或 preset 固定了其他 provider。仅本地条目（如 `embeddinggemma`）只列出本地 provider。

| 规范模型                     | 别名                                                                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `deepseek-v4-flash`      | `ds-flash`, `deepseek-flash`, `deepseek-chat`                                                                            |
| `deepseek-reasoner`      | `ds-flash-thinking`, `deepseek-flash-thinking`                                                                           |
| `deepseek-v4-pro`        | `ds`, `ds-pro`, `dsv4`, `dsv4-pro`, `deepseek`, `deepseek-v4`, `deepseek-pro`                                            |
| `gpt-5.4-nano`           | `gpt-nano`, `5.4-nano`                                                                                                   |
| `gpt-5.4-mini`           | `gpt-mini`, `5.4-mini`                                                                                                   |
| `gpt-5.5`                | `gpt`, `5.5`                                                                                                             |
| `gpt-5.5-pro`            | `gpt-pro`, `5.5-pro`                                                                                                     |
| `claude-haiku-4-5`       | `haiku`, `haiku-4.5`                                                                                                     |
| `claude-sonnet-4-6`      | `sonnet`, `sonnet-4.6`                                                                                                   |
| `claude-opus-4-8`        | `opus`, `opus-4.8`                                                                                                       |
| `gemini-3.1-flash-lite`  | `gemini-flash-lite`, `gemini-lite`                                                                                       |
| `gemini-3.5-flash`       | `gemini-flash`                                                                                                           |
| `gemini-3.1-pro-preview` | `gemini-pro`                                                                                                             |
| `kimi-k2.6`              | `kimi`, `k2.6`                                                                                                           |
| `glm-5.2`                | `glm`                                                                                                                    |
| `glm-4.7-flash`          | `glm-flash`, `glm-4.7`                                                                                                   |
| `gemma-4-26b-a4b-it`     | `gemma4`, `gemma4-26b`, `gemma4-26b-a4b`, `gemma4-26b-a4b-it`, `gemma`, `gemma-26b`, `gemma-26b-a4b`, `gemma-26b-a4b-it` |
| `qwen3.6-flash`          | `qwen3.6`, `qwen3.6-flash`, `qwen3.6-35b`, `qwen3.6-35b-a3b`, `qwen`, `qwen-flash`, `qwen-35b`, `qwen-35b-a3b`           |
| `embeddinggemma`         | `embeddinggemma-300m`                                                                                                    |
| `text-embedding-3-small` | `gpt-embedding`, `gpt-embedding-small`, `text-embedding-small`                                                           |
| `embed-v4.0`             | `cohere`, `cohere-embedding`, `cohere-embedding-v4`, `embed-v4`                                                          |
| `voyage-4-lite`          | `voyage`, `voyage-lite`                                                                                                  |
| `gpt-5-image-mini`       | `gpt-image-mini`, `image-mini`                                                                                           |
| `gpt-5.4-image-2`        | `gpt-image`, `gpt-image-2`, `image-2`                                                                                    |

`mock` 与 `custom` 是离线测试与调用方提供的 OpenAI 兼容 provider 的工具型模型条目。`embed-v4.0` 与 `voyage-4-lite` 是由各自 provider 提供的仅嵌入目录条目（非 OpenRouter）。完整 provider 列表与逐项配置见 [LLM 提供商](/integrations/llm-providers)。

<br />

## 4. 入口一览 (Gateways at a Glance)

入口 (Gateway) 是在 preset、model 与 provider 解析完成后，HeavenBase 使用的传输适配层。provider 决定模型由谁提供；gateway 决定请求如何发送。`heavenbase.llm.default_gateway` 默认为 `openai`，仅当调用、preset 或 provider 未固定 gateway 时使用。

| Gateway     | 适用场景                                                   |
| ----------- | ------------------------------------------------------ |
| `openai`    | 通过 OpenAI 兼容端点 (Endpoint) 使用 OpenAI Python SDK。这是默认选项。 |
| `anthropic` | 使用官方 Anthropic Python SDK 与原生 Messages 载荷。             |
| `portkey`   | 需要 Portkey 路由、策略、可观测性或 gateway 侧控制时。                   |
| `bifrost`   | 运行 Bifrost 兼容 gateway，并需要 provider 前缀模型路由时。            |
| `litellm`   | 已通过 LiteLLM Python gateway 标准化 provider 路由时。           |
| `mock`      | 测试与 demo 需要确定性离线行为时。                                   |

若当前环境无法导入非默认 gateway，`hb.LLM` 会回退到 `openai` gateway，避免缺少可选依赖导致解析失败。gateway 物化、思考控制、客户端导出及各 gateway 的临时上游限制见 [高级 LLM](/features/llm/advanced)。

<br />

## 5. 各页分工 (What Lives Where)

LLM 章节按能力逐层展开，每页只增加一层：

* [LLM 对话](/features/llm/chat) — `chat`、`stream`、消息输入、多模态图像、响应投影与推理控制。
* [嵌入](/features/llm/embeddings) — `embed`、批处理、去重、缓存与本地嵌入 provider。
* [工具调用](/features/llm/tool-use) — 仅 schema 与可执行工具、MCP 工具集 (Toolkit)、结构化输出与 CLI 工具循环。
* [会话](/features/llm/sessions) — 无状态设计、`LLMSession`、CLI 会话与已解析 spec 检查。
* [高级 LLM](/features/llm/advanced) — 入口 (Gateway)、响应缓存、客户端导出、图像生成、`LLMImage`、工具调用修复与异步 API。

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [First LLM](/quickstart/first-llm) - 安装、配置 API 密钥，并从 CLI 运行首次 chat、embed 与会话。
  * [LLM providers](/integrations/llm-providers) - 完整 provider 目录与逐项配置。
  * [Configuration](/features/configuration) - preset、provider 与 gateway 背后的 `heavenbase.llm` 配置树。
</Tip>

<br />