LLM 概述

本地与托管 Provider、六个 Gateway、一个客户端。解析模型替你记住其余一切。

1. 动机

hb.LLM 是 HeavenBase 的 Python LLM 客户端，覆盖聊天、流式输出、嵌入、图像生成、Mock 与入口 (Gateway) 路由。它会从共享的 heavenbase.llm 配置中解析 preset、model、provider 与 gateway，然后物化由 gateway 选定的请求格式。默认配置为 preset="system"、default_provider="openrouter" 与 gateway="openai"。一个 API 密钥即可开箱访问大多数主流模型。

export OPENROUTER_API_KEY="..."

import heavenbase as hb

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

2. 解析模型 (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=... 覆盖。

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：

llm = hb.LLM(model="ds-flash", max_tokens=256, temperature=0)

3. 预设 (Presets)

Preset 使用可持久化的模型别名，使用户配置保持紧凑可读。多数生产 preset 不固定 provider；更改 heavenbase.llm.default_provider 会一并切换它们。local、worker-local、embed-local、imagen-local、ocr-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`	开启 (`max`)	由默认 GPT 别名支撑的高能力推理 preset。
`worker`	`ds-flash`	关闭	确定性非思考工具调用的后台 worker preset。
`local`	`qwen3.6-flash`	关闭	本地 LM Studio 聊天 preset。
`worker-local`	`qwen3.6-flash`	关闭	本地 LM Studio worker preset。
`coder`	`sonnet`	开启	为多步实现工作启用思考的编码 preset。
`coder-pro`	`opus`	开启	面向深度实现与评审的最高端编码 preset。
`embed`	`gpt-embedding-small`	不适用	默认嵌入 preset。
`embed-local`	`embeddinggemma`	不适用	本地嵌入 preset。
`imagen`	`gpt-image-mini`	不适用	默认图像生成 preset。
`imagen-local`	`z-image-turbo`	不适用	本地 Ollama 图像生成 preset。
`ocr-local`	`glm-ocr`	关闭	本地 Ollama OCR 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 级控制。GPT-5.6 目录默认让 Luna 与 Terra 使用 high 推理强度，让 Sol 使用 medium；reason-pro 会把 Sol 覆盖为 max。anthropic 入口 (Gateway) 将 think=True 映射为 Claude Messages 自适应思考并摘要展示，将 reasoning_effort 映射为 Anthropic effort，并将原生思考块归一化回 think include 字段。每次调用的思考控制见 LLM 对话。

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

在线内置模型包含 OpenRouter 标识符，并在可用时包含直连 provider 标识符。根级 default_provider 选择使用哪个标识符，除非调用或 preset 固定了其他 provider。仅本地条目（如 embeddinggemma、z-image-turbo 与 glm-ocr）只列出本地 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.6-luna`	`gpt-nano`, `gpt-luna`, `5.6-luna`, `luna`
`gpt-5.6-terra`	`gpt-mini`, `gpt-terra`, `5.6-terra`, `terra`
`gpt-5.6-sol`	`gpt`, `gpt-sol`, `5.6`, `5.6-sol`, `sol`
`claude-haiku-4-5`	`haiku`, `haiku-4.5`
`claude-sonnet-5`	`sonnet`, `sonnet-5`
`claude-sonnet-4-6`	`sonnet`, `sonnet-4.6`
`claude-opus-5`	`opus`, `opus-5`
`claude-fable-5`	`fable`, `fable-5`
`grok-4.5`	`grok`
`gemini-3.5-flash-lite`	`gemini-flash-lite`, `gemini-lite`
`gemini-3.6-flash`	`gemini-flash`
`gemini-3.1-pro-preview`	`gemini-pro`
`kimi-k2.6`	`kimi`, `k2.6`
`kimi-k3`	`k3`
`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`
`z-image-turbo`	`z-image`, `image-local`, `imagen-local`
`glm-ocr`	`ocr`

mock 与 custom 是离线测试与调用方提供的 OpenAI 兼容 provider 的工具型模型条目。embed-v4.0 与 voyage-4-lite 是由各自 provider 提供的仅嵌入目录条目（非 OpenRouter）。z-image-turbo 是仅限 Ollama 的本地条目，而 glm-ocr 可通过 Ollama 或 oMLX 解析。完整 provider 列表与逐项配置见 LLM 提供商。

5. 入口一览 (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。

6. 各页分工 (What Lives Where)

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

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

总结

Preset 提供可读意图；Provider 决定模型在哪里运行；Gateway 决定传输方式。
一个解析后的客户端覆盖聊天、嵌入、图像生成、本地模型与确定性 Mock。
配置让模型路由保持可见，而不是把它埋进应用 wrapper。

Further Exploration

Related resources:

First LLM - 安装、配置 API 密钥，并从 CLI 运行首次 chat、embed 与会话。
LLM providers - 完整 provider 目录与逐项配置。
Configuration - preset、provider 与 gateway 背后的 heavenbase.llm 配置树。

介绍

快速开始

核心概念

开发者

工具箱

LLM

智能体运行时

社区

1. 动机

2. 解析模型 (Resolution Model)

3. 预设 (Presets)

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

5. 入口一览 (Gateways at a Glance)

6. 各页分工 (What Lives Where)

总结

Further Exploration

​1. 动机

​2. 解析模型 (Resolution Model)

​3. 预设 (Presets)

​4. 精选模型目录 (Curated Model Catalog)

​5. 入口一览 (Gateways at a Glance)

​6. 各页分工 (What Lives Where)

​总结

​Further Exploration

1. 动机

2. 解析模型 (Resolution Model)

3. 预设 (Presets)

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

5. 入口一览 (Gateways at a Glance)

6. 各页分工 (What Lives Where)

总结

Further Exploration