高级 LLM

默认值会藏起接线；高级模式会在有人拿剪刀前给每根线贴好标签。

1. 动机

多数应用可以一直使用 hb.LLM(preset="chat")。当传输、可复现性、SDK 互操作、图像处理或并发必须显式时，本页功能就很重要。相同的解析顺序仍然适用：Preset、Model、Provider，最后是 Gateway。

2. 选择 Gateway

默认 openai Gateway 通过 OpenAI Python SDK 访问 OpenAI 兼容端点。

Gateway	适用场景
`openai`	OpenAI 兼容端点是最简单的传输方式
`anthropic`	需要原生 Claude Messages 负载
`portkey`	Portkey 路由、策略或可观测性拥有传输
`bifrost`	Bifrost 兼容 Gateway 拥有 Provider 路由
`litellm`	LiteLLM 已经标准化 Provider 访问
`mock`	测试需要确定性离线行为

import heavenbase as hb

llm = hb.LLM(model="ds-flash", provider="deepseek", gateway="portkey")

Gateway 限制会显式失败。原生 Anthropic 不提供嵌入或图像生成，Portkey 与 OpenRouter 组合的嵌入仍被阻止，而 Bifrost 图像支持取决于其上游实现。若可选的非默认 Gateway 无法导入，HeavenBase 会回退到 openai。

3. 注册运行时形状

当现有 Gateway 已经能使用某 API 时，请在配置中添加 Provider。只有运行时参数形状确实不同时才注册 LLMGateway。

def materialize(spec, gateway, override):
    return {
        "gateway": gateway,
        "model": spec.model_id,
        "args": {**spec.args, **override},
    }


hb.LLMGateway("company-proxy", materialize).register()

请在 heavenbase.llm.gateways 下声明相同标识符，以便 LLMEngine.resolve(...) 验证。 LLMEngine 解析策略，LLMSpec 携带结果，而 LLMGateway 物化传输。

4. 控制响应缓存

HeavenBase 把规范化的聊天、嵌入与图像响应存储在专用 llm-cache 工作区中。缓存默认启用，并使用确定性策略。

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

每次调用的覆盖值接受 cache=False、cache=True 或缓存映射。可执行工具循环会自动跳过文本缓存。确定性的文本与图像写入需要稳定的生成参数。没有固定 seed 的随机请求会绕过缓存读写。

hb cfg set heavenbase.llm.cache.namespaces.text.ttl_seconds 86400
hb cfg set heavenbase.llm.cache.namespaces.embedding.enabled true

5. 复用并导出客户端

LLMSpec.hash_key() 标识完整的已解析请求默认值。 client_key() 只包含 Gateway 客户端构造字段，让兼容的 LLM 实例可以复用内存中的 SDK 客户端。

llm = hb.LLM(model="ds-flash", provider="deepseek")

spec_key = llm.spec.hash_key()
client_key = llm.spec.client_key()

OpenAI 兼容 Gateway 可以导出原始 SDK 客户端：

client = llm.to_client()
aclient = llm.to_aclient()

response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello"}],
    **llm.to_args(),
)

to_client()、to_aclient() 与 to_args() 支持 openai、portkey 和 bifrost。原生 Anthropic 使用 to_anthropic_client() 与 to_anthropic_aclient()。

6. 生成并规范化图像

image = hb.LLM(preset="imagen").imagen("A clean product render of a ceramic mug")
image.save("mug.png")

当 Ollama 提供 z-image-turbo 时，请使用 imagen-local。参考图像接受与多模态聊天相同的规范化输入：

reference = hb.LLMImage.from_any("./style-reference.png")
image = hb.LLM(preset="imagen").imagen("Apply this style to an HB mark", images=reference)

LLMImage 会规范化路径、字节、base64、URL、Provider item 与生成结果。

raw = image.to_bytes()
data_url = image.to_data_url()
pil_image = image.to_pil()

URL 支撑的值会惰性获取。超时由 heavenbase.llm.image_url_timeout 配置。

7. 修复工具调用

LLMToolCallRepair 可以移除 Markdown fence、平衡 JSON 括号、填充缺失的必需 schema 字段，并压缩 OpenAI 风格工具参数。

hb cfg set heavenbase.llm.tool_call_repair.enabled true
hb cfg set heavenbase.llm.tool_call_repair.strict false

请向 hb.LLM(...) 传入 tool_call_repair={...}，或向单次 chat 调用传入 repair_tool_calls=True。严格模式会在参数无法解析时抛出错误；非严格模式会返回原始字符串。

8. 使用自定义 Provider

custom Preset 用于未内置的 OpenAI 兼容端点：

llm = hb.LLM(
    preset="custom",
    base_url="http://localhost:9999/v1",
    model="third-party-model",
    api_key="optional-key",
)

base_url 与具体模型缺一不可。若负载家族本身不同，请改用自定义 Gateway。

9. 异步运行

import asyncio
import heavenbase as hb


async def main():
    llm = hb.LLM(preset="chat")
    text = await llm.achat("hello")
    async for chunk in llm.astream("Count to three."):
        print(chunk, end="")
    vector = await llm.aembed("semantic text")


asyncio.run(main())

每个主要同步操作都有异步对应项。异步可执行工具要求使用 achat；同步 chat 会拒绝异步 callable。

总结

Gateway 在 Model 与 Provider 解析后拥有传输形状。
缓存可见、确定，并可按 namespace 独立配置。
SDK 导出在不复制解析逻辑的前提下支持互操作。
图像与异步调用使用同一个已解析客户端模型。

进一步探索

相关资源：

LLM 概述 — Preset、Model、Provider 与 Gateway
First LLM — Provider 设置与客户端导出示例
LLM Provider — Provider 特定配置与路由检查

介绍

快速开始

核心概念

开发者

工具箱

LLM

智能体运行时

社区

1. 动机

2. 选择 Gateway

3. 注册运行时形状

4. 控制响应缓存

5. 复用并导出客户端

6. 生成并规范化图像

7. 修复工具调用

8. 使用自定义 Provider

9. 异步运行

总结

进一步探索

​1. 动机

​2. 选择 Gateway

​3. 注册运行时形状

​4. 控制响应缓存

​5. 复用并导出客户端

​6. 生成并规范化图像

​7. 修复工具调用

​8. 使用自定义 Provider

​9. 异步运行

​总结

​进一步探索

1. 动机

2. 选择 Gateway

3. 注册运行时形状

4. 控制响应缓存

5. 复用并导出客户端

6. 生成并规范化图像

7. 修复工具调用

8. 使用自定义 Provider

9. 异步运行

总结

进一步探索