跳转到主要内容
llm("hello") 与 llm.chat("hello") 是同一调用。更短才是重点。
chat 是 hb.LLM 的主要文本入口。它接收 prompt、单条消息或消息列表，执行对话补全，并仅通过 include 投影返回你请求的字段。

​
1. 对话与调用 (Chat and Call)

LLM 可调用，因此 llm("hello") 与 llm.chat("hello") 等价。用 system=... 传入 system prompt，在构造时或调用时设置 provider 参数：

​
2. 消息输入 (Message Inputs)

chat 与 stream 接受单个字符串、一条 OpenAI 风格消息字典，或消息列表：
格式化器也接受带 model_dump()、to_dict()、dict()、json()，或 role 与 content 属性的对象，因此 Pydantic 模型与 SDK 消息对象无需手动转换即可传入。

​
3. 多模态图像 (Multimodal Images)

对多模态模型，用 images= 传入图像输入。HeavenBase 将每个输入归一化为 LLMImage，并向最后一条 user 消息追加 OpenAI 兼容的 image_url 内容部分。
images= 接受 LLMImage、URL、data URL、base64 字符串、本地路径、类 bytes 对象、二进制文件对象、provider 风格字典、Pillow 图像，以及 numpy 兼容的 ndarray。单个值或可迭代对象均可。完整 LLMImage API 见 Advanced LLM。

​
4. 流式输出 (Streaming)

需要增量到达时使用 stream：
chat 在内部走同一条流式路径并汇总最终响应。这使常规 chat、推理流、用量统计、结构化输出与 tool call 共用一条响应管线，因此无论你汇总还是迭代，include 字段含义一致。

​
5. Include 投影 (Include Projection)

include 参数选择响应字段。传 None 使用默认 text 值，传字符串选单字段，传列表选多个。未知字段名会抛出带上下文的错误。
  • text：最终 assistant 文本，不含单独推理块。
  • think：推理或思考内容，当 provider 单独流式输出时可用。
  • content：用 <think> 标签包裹的 think，后接 text。
  • message：OpenAI 格式的 assistant 响应字典，含 role、content 及可选 tool_calls；不是完整历史。
  • delta：本次推理调用产生的新 OpenAI 格式消息。若有可执行工具，包括 assistant tool-call 消息、一条或多条 role="tool" 结果消息，以及最终 assistant 响应。
  • messages：完整对话历史：归一化输入消息加 delta。
  • tool_calls：来自 assistant 响应的归一化 OpenAI tool_calls。
  • usage：本次调用的 provider 用量计数。常见键为 prompt_tokens、completion_tokens 与 total_tokens；流式 usage 块通过累加数值计数器、每个键保留首个非数值来合并。
  • raw：原始 provider 载荷。
  • elapsed：请求耗时（秒）。
  • created_at：本地响应创建时间戳。
  • structured：解析后的结构化输出。
当 stream 包含 delta 或 messages 时，渐进内容仍正常到达，HeavenBase 会发出一条最终元数据块，其中 text/think 为空并带上完整的消息 delta。单字段 include 且 reduce=True（默认）时，直接返回值而非单键字典。

​
6. 思考与推理 (Thinking and Reasoning)

推理 preset 默认启用规范 think 选项。可在每次调用覆盖，HeavenBase 将 think=True 与 think=False 都转换为 OpenAI 兼容入口 (Gateway) 的 gateway 级 extra_body.reasoning。模型支持时，将 think 与 reasoning_effort 及可选推理预算配对使用：
CLI 输出在打印正常答案文本前，将可见思考块包裹在 <think> 与 </think> 中。anthropic 入口 (Gateway) 将 think 映射为原生 Claude thinking，并将思考块归一化回 think include 字段。传 think=False 可完全抑制响应及其消息历史中的推理内容。

​
7. CLI 对话与 MCP 工具 (CLI Chat and MCP Tools)

hb llm chat 以 chat preset 发送单条消息。用 --preset、--model、--provider 覆盖 preset、model 或 provider；用 --verbose 查看解析后的 spec；用 --input 从文件读取 prompt。
添加 --mcp 可在单轮 agentic 调用中附加 MCP 工具。HeavenBase 将每个来源导入为工具集 (Toolkit)，让模型调用工具直至产生最终 assistant 响应，然后打印 tool call 与 tool 结果，再输出最终答案。MCP 来源接受 URL 或规范 namespace.toolkit:version 引用。负版本号表示相对最新版本的偏移：-1 为最新，-2 为次新。工具循环由 --max-steps 上限控制，默认 20 个 assistant 步。
用 --copy / -cp 将最终响应复制到剪贴板，用 --json 输出 JSON 载荷而非纯文本。
交互式多轮 tool use 请改用 hb llm session。完整可执行工具契约见 Sessions 与 Tool Use。

​
Further Exploration

Related resources:
  • LLM Overview - preset、模型目录与解析模型。
  • Tool Use - 仅 schema 与可执行工具、MCP 工具集 (Toolkit) 与结构化输出。
  • First LLM - hb llm 与 hb.LLM 快速入门导览。