跳转到主要内容
二十家提供商、六个入口、一个客户端。解析模型替你记住其余一切。
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")

​
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=... 覆盖。 
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)

​
2. 预设 (Presets)

Preset 使用可持久化的模型别名，使用户配置保持紧凑可读。多数生产 preset 不固定 provider；更改 heavenbase.llm.default_provider 会一并切换它们。embed-local、mock、custom 等本地与特殊 preset 保留各自的 provider，因为它们需要专用配置。
Preset模型别名默认 Thinking说明
systemds-flash关闭短编排调用的默认轻量系统 LLM。
tinygemma关闭低延迟离线工作用的小型聊天模型。
chatds-flash关闭快速非思考回答的通用聊天 preset。
chat-prods-pro关闭更强但仍默认避免推理的聊天 preset。
reasonds-pro开启面向较难任务、在支持时暴露思考的推理 preset。
reason-progpt开启由默认 GPT 别名支撑的高能力推理 preset。
workerds-flash关闭确定性非思考工具调用的后台 worker preset。
codersonnet开启为多步实现工作启用思考的编码 preset。
coder-proopus开启面向深度实现与评审的最高端编码 preset。
embedgpt-embedding-small不适用默认嵌入 preset。
embed-localembeddinggemma不适用本地嵌入 preset。
imagengpt-image-mini不适用默认图像生成 preset。
mockmock离线测试与 demo 用的非 LLM 确定性 mock preset。
customcustom调用方提供调用方提供的 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 对话。

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

在线内置模型包含 OpenRouter 标识符，并在可用时包含直连 provider 标识符。根级 default_provider 选择使用哪个标识符，除非调用或 preset 固定了其他 provider。仅本地条目（如 embeddinggemma）只列出本地 provider。
规范模型别名
deepseek-v4-flashds-flash, deepseek-flash, deepseek-chat
deepseek-reasonerds-flash-thinking, deepseek-flash-thinking
deepseek-v4-prods, ds-pro, dsv4, dsv4-pro, deepseek, deepseek-v4, deepseek-pro
gpt-5.4-nanogpt-nano, 5.4-nano
gpt-5.4-minigpt-mini, 5.4-mini
gpt-5.5gpt, 5.5
gpt-5.5-progpt-pro, 5.5-pro
claude-haiku-4-5haiku, haiku-4.5
claude-sonnet-4-6sonnet, sonnet-4.6
claude-opus-4-8opus, opus-4.8
gemini-3.1-flash-litegemini-flash-lite, gemini-lite
gemini-3.5-flashgemini-flash
gemini-3.1-pro-previewgemini-pro
kimi-k2.6kimi, k2.6
glm-5.2glm
glm-4.7-flashglm-flash, glm-4.7
gemma-4-26b-a4b-itgemma4, gemma4-26b, gemma4-26b-a4b, gemma4-26b-a4b-it, gemma, gemma-26b, gemma-26b-a4b, gemma-26b-a4b-it
qwen3.6-flashqwen3.6, qwen3.6-flash, qwen3.6-35b, qwen3.6-35b-a3b, qwen, qwen-flash, qwen-35b, qwen-35b-a3b
embeddinggemmaembeddinggemma-300m
text-embedding-3-smallgpt-embedding, gpt-embedding-small, text-embedding-small
embed-v4.0cohere, cohere-embedding, cohere-embedding-v4, embed-v4
voyage-4-litevoyage, voyage-lite
gpt-5-image-minigpt-image-mini, image-mini
gpt-5.4-image-2gpt-image, gpt-image-2, image-2
mock 与 custom 是离线测试与调用方提供的 OpenAI 兼容 provider 的工具型模型条目。embed-v4.0 与 voyage-4-lite 是由各自 provider 提供的仅嵌入目录条目（非 OpenRouter）。完整 provider 列表与逐项配置见 LLM 提供商。

​
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。

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

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

​
Further Exploration

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