English · 简体中文
内容块¶
PAR 中的消息通过 content_block list 携带结构化内容,而非扁平字符串。当你调用 Runtime.invoke 时,响应消息包含这些块的列表——文本、工具调用、工具结果或图像。列表中的每个块都可以独立持有 cache_control 字段,provider 适配器(`Anthropic、`Openai)在线路格式中发出该字段用于 prompt 缓存。
Types 中的 message 类型如下:
type message = {
role : message_role;
content_blocks : content_block list;
tool_calls : tool_call list option;
tool_call_id : string option;
name : string option;
}
content_blocks 替代了旧的 content : string option 字段。每个块是 content_block 的一个变体,各有自己的 cache_control 槽位。
块类型¶
type content_block =
| Text_block of {
text : string;
cache_control : cache_control option;
}
| Tool_use_block of {
id : string;
name : string;
arguments : Yojson.Safe.t;
cache_control : cache_control option;
}
| Tool_result_block of {
tool_use_id : string;
content : string;
cache_control : cache_control option;
}
| Image_block of {
source : image_source;
media_type : string;
data : string;
detail : string option;
cache_control : cache_control option;
}
| Reasoning_block of {
text : string;
signature : string option;
cache_control : cache_control option;
}
| Redacted_reasoning_block of {
data : string;
cache_control : cache_control option;
}
Text_block 持有纯文本。LLM 的响应文本和用户输入都落在这里。
Tool_use_block 表示 LLM 请求调用工具。id 匹配 provider 的工具使用标识符;name 是工具名称;arguments 是 JSON 负载。
Tool_result_block 将工具处理器的输出携带回对话。tool_use_id 将其链接到发起的 Tool_use_block。
Image_block 持有图像数据,可以是 URL 引用或 base64 编码的字节。media_type 是 MIME 类型(如 "image/png")。
Reasoning_block 持有推理模型的思维链(o1/o3、DeepSeek-R1、Claude extended thinking)。它装的是推理文本而非面向用户的答案,text_of_message 会刻意跳过它。signature 是 Anthropic 的 thinking 签名:当 assistant 消息同时携带 tool_use 时,该块必须连同签名原样回传,因此引擎会把推理块放在记录下来的 assistant 消息最前面。
Redacted_reasoning_block 持有 Anthropic 在隐去推理内容时替换进去的不透明载荷。它没有文本,同样必须回传才能让往返保持合法。
只有在 provider 能重放时,推理块才会进入线路:Anthropic 适配器会丢弃没有签名的 Reasoning_block(来自其他 provider,或来自推理还不是块的旧对话),因为 Anthropic 拒绝没有签名的 thinking 块。OpenAI 适配器从不回传推理——o1/o3 与多数 OpenAI 兼容 API 都不接受输入里的推理内容。
llm_response.reasoning 持有单次响应的同一批块,引擎会把这些块复制到记录的 assistant 消息中、并置于文本之前。
构造¶
用记录语法手动构造每个变体:
(* 简单文本块 *)
let block = Text_block {
text = "Hello, world!";
cache_control = None;
}
(* 带 prompt 缓存的文本块 *)
let cached = Text_block {
text = "System prompt content";
cache_control = Some { type_ = `Ephemeral; ttl = Some `Five_min };
}
(* 来自处理器的工具结果 *)
let result = Tool_result_block {
tool_use_id = "call_abc123";
content = "42";
cache_control = None;
}
(* 来自 LLM 响应的工具使用 *)
let tool_use = Tool_use_block {
id = "call_abc123";
name = "calculator";
arguments = `Assoc [("expression", `String "6 * 7")];
cache_control = None;
}
(* 来自 URL 的图像 *)
let img = Image_block {
source = Url "https://example.com/photo.png";
media_type = "image/png";
data = "";
detail = None;
cache_control = None;
}
(* 来自 base64 的图像 *)
let img_b64 = Image_block {
source = Base64 "iVBORw0KGgo...";
media_type = "image/png";
data = "";
detail = None;
cache_control = None;
}
相比手工拼装这些记录,更推荐使用「图像块」一节中的 Message 辅助函数。
通过填充记录来构建完整消息:
let msg : Types.message = {
role = User;
content_blocks = [
Text_block { text = "What is 2+2?"; cache_control = None };
];
tool_calls = None;
tool_call_id = None;
name = None;
}
辅助函数¶
Message 模块提供三个辅助函数用于常见的字符串到块的转换。
content_of_string¶
将字符串包装在单个 Text_block 中,cache_control = None。空字符串返回空列表。
Message.content_of_string "Hello"
(* [Text_block { text = "Hello"; cache_control = None }] *)
Message.content_of_string ""
(* [] *)
string_of_content¶
从所有 Text_block 和 Tool_result_block 变体中提取文本并连接它们。非文本块(Tool_use_block、Image_block)被静默跳过。
Message.string_of_content [
Text_block { text = "Hello "; cache_control = None };
Tool_use_block { id = "x"; name = "t"; arguments = `Assoc []; cache_control = None };
Text_block { text = "world"; cache_control = None };
]
(* "Hello world" *)
text_of_message¶
便捷包装器。等价于 Message.string_of_content msg.content_blocks。
content_opt¶
如果消息有可提取的文本则返回 Some text,内容为空则返回 None。用于对响应进行模式匹配。
match Message.content_opt resp with
| Some text -> Printf.printf "Got: %s\n" text
| None -> Printf.printf "No text in response\n"
cache_control¶
每个块变体都携带一个可选的 cache_control 字段:
type cache_control = {
type_ : [`Ephemeral];
ttl : cache_ttl option;
}
type cache_ttl = [`Five_min | `One_hour]
type_ 目前始终是 `Ephemeral。该类型是变体而非简单别名,因此 PAR 可以在不破坏性变更的情况下引入持久缓存模式。ttl 是存活时间提示。`Anthropic 线路格式识别这两个值;其他 provider 优雅地忽略 cache_control。
设置 cache_control¶
有三种方式标记块用于缓存。
直接构造。 内联构建 cache_control 值:
Text_block {
text = "Expensive system prompt";
cache_control = Some { type_ = `Ephemeral; ttl = Some `Five_min };
}
Cache_breakpoint.mark_message。 标记消息 content_blocks 列表中的最后一个块。这是缓存整个消息的推荐面向用户的 API:
let marked_msg = Cache_breakpoint.mark_message ~ttl:`One_hour msg
(* msg.content_blocks 中的最后一个块现在设置了 cache_control *)
该函数遍历到最后一个块并对其应用 cache_control,无论变体类型。如果 content_blocks 为空,则为空操作。
Engine 自动标记。 Engine 在每次 LLM 往返前内部调用 apply_breakpoints。它根据 provider 的缓存能力评估断点候选(系统提示、每条消息、每个工具),然后自动标记选定的块。你不需要自己调用它;它作为 ReAct 循环的一部分运行。
Provider 支持¶
Prompt 缓存目前由 `Anthropic 线路格式支持。当 provider 适配器遇到设置了 cache_control 的块时,它在 JSON 负载中发出相应字段。`Openai 和 `Ollama 适配器静默忽略 cache_control,所以在这些 provider 上设置它是无害的。
图像块¶
Image_block 携带对图像数据的引用及其 MIME 类型。Url 指向远程 URL 托管的图像;provider 获取它。Base64 直接在块中嵌入原始字节。detail 是 provider 相关的分辨率提示——OpenAI 接受 "auto"、"low" 或 "high",其他 provider 忽略它。
构造图像块¶
使用 Message 辅助函数,而不是手工拼装记录——它们能保证 cache_control 与 detail 一致:
open Par
(* 远程图像——由 provider 拉取,字节不经过 PAR *)
let remote = Message.image_url "https://example.com/photo.png" ()
(* 显式指定 MIME 类型与分辨率提示 *)
let remote_hd = Message.image_url "https://example.com/photo.jpg"
~media_type:"image/jpeg" ~detail:"high" ()
(* 字节已在手中——会做校验,因此可能失败 *)
let inline = match Message.image_base64 ~data:"iVBORw0KGgo..." ~media_type:"image/png" () with
| Ok block -> block
| Error msg -> failwith msg
(* 本地文件——读取并做 base64 编码;MIME 类型由扩展名推断 *)
let local = match Message.image_file "assets/photo.png" () with
| Ok block -> block
| Error msg -> failwith msg
Message.media_type_of_extension 映射 .png、.jpg、.jpeg、.gif 与 .webp。.bmp 不做推断,因为两个受支持的 provider 都不接受它;其他格式请显式传 ~media_type,否则调用直接报错,而不是静默猜测。
上限与校验¶
承载图像字节的构造函数是「调用方把并非自己产生的数据交给 PAR」的边界,因此它们 校验数据,而不是信任数据:
| 规则 | 取值 |
|---|---|
| 解码后载荷上限 | 5 MiB(Message.max_image_bytes;可用 ?max_bytes 逐次覆盖) |
| 接受的 MIME 类型 | image/png、image/jpeg、image/gif、image/webp(Message.supported_image_media_types) |
| base64 载荷 | 必须可解码;超长字符串在解码之前按编码长度拒绝 |
| 空载荷 | 拒绝 |
| 未知文件扩展名 | 未显式给 ?media_type 时拒绝 |
image_file 在读取之前先检查文件大小,所以过大的文件不会被读进内存。
image_base64 同样返回 result;image_file 一直都是。
image_url 不做校验:它携带的是引用而非字节,其 media_type 只是 provider
可能忽略的提示。
5 MiB 是 Anthropic 文档给出的单图上限;OpenAI 允许更大,所用 provider 支持更大时
请抬高 ?max_bytes。这些上限是 PAR 自己的契约——它们不代表某个 provider 接受过
任何具体图片。
把图像发给模型¶
Runtime.invoke 接受纯字符串。多模态输入请用 Runtime.invoke_content,它接受内容块列表:
let result = Runtime.invoke_content rt ~agent_id:"vision"
~content:[
Message.text "这张图里有什么?";
Message.image_url "https://example.com/photo.png" ();
] ()
Runtime.invoke 是 Runtime.invoke_content 的薄封装——它把字符串包成单个文本块。两者共用同一份实现,因此不会出现行为分叉。
Python 输入¶
Python 绑定提供相同的同步操作和内容构造函数:
from par_runtime import Runtime, text, image_url, image_base64, image_file
# rt 是已经初始化、并注册了 "vision" agent 的 Runtime。
response_json = rt.invoke_content("vision", [
text("描述这张图片"),
image_url("https://example.com/photo.png", detail="low"),
], save=True, update_current=True)
local_image = image_file("assets/photo.jpg")
inline_image = image_base64("iVBORw0KGgo...", media_type="image/png")
构造函数返回 SDK 已有的带标签数组 JSON 块,不引入另一套 provider 专属输入格式。
invoke_content 返回与 invoke 相同的 JSON 响应。
save=True 持久化本次调用的对话,update_current=False 不覆盖共享的当前对话状态。
文件辅助函数在 I/O 失败时抛出 OSError,内容校验不通过时抛出 ImageError
(ValueError 的子类):未知扩展名、不支持的 MIME 类型、畸形或超长的 base64、
超过 MAX_IMAGE_BYTES 的文件。MAX_IMAGE_BYTES 与 SUPPORTED_IMAGE_MEDIA_TYPES
已导出,便于调用方预先检查;max_bytes= 可逐次覆盖上限。格式错误的内容块在调用
provider 前抛出 PARInvokeError。用户输入只接受文本和图像块,不接受
Tool_use_block 或 Tool_result_block。
新增 detail 字段以前保存的图像块仍可解码:缺少的 detail 默认为 None。
新内容块在保存和加载后会保留该提示。OCaml 的 image_file 辅助函数在读取失败时
也会关闭文件通道。
Provider 线路格式¶
| Provider | 图像编码方式 |
|---|---|
`Openai |
仅当消息携带图像时,content 才切换为数组形态([{type:"text",...}, {type:"image_url",...}])。不含图像的消息保持纯字符串形态,因此既有请求载荷不变。Base64 源以 data URI 发送(data:<media_type>;base64,<data>)——这是 OpenAI 唯一接受的内联形式。detail 输出为 image_url.detail。 |
`Anthropic |
输出 {"type":"image","source":{...}}。base64 情形下 media_type 与 data 位于 source 内部,符合 Anthropic 的 schema。 |
`Ollama 适配器沿用 OpenAI 的编码方式。
携带内容的工具结果¶
过去工具只能返回一个 JSON 载荷,runtime 会在模型看到之前把它拍平成文本。 产出「模型必须亲眼看」的东西的工具——截图、图表、渲染出来的页面——现在可以 直接返回内容块:
let tb = Runtime.register_tool rt ~name:"shot" ~description:"Takes a screenshot"
~input_schema:(`Assoc [])
~handler:(fun _ _ ->
Success_content [
Message.text "a screenshot of the dashboard";
Message.image_file "assets/dashboard.png" ();
]) ()
Success_content 是 handler_result 的新构造子。这些块成为会话中的工具
结果,下一次模型调用就会带上它们。返回 Success json 的工具(常见情形)
行为不变:载荷仍被拍平成文本块。
携带图片的工具结果在线路格式上:
| Provider | 工具结果编码 |
|---|---|
`Openai |
tool 消息切换为数组 content 形式,图片作为 image_url 部件。模型必须支持视觉。 |
`Anthropic |
tool_result.content 变成数组形式:一个文本部件加一个 {"type":"image","source":{...}} 部件。 |
中间件同样作用于富内容:pii_mask 与 sanitize_tool_output 会清洗文本块
(图片是二进制载荷,不动),logging 记录这次成功。声明了 output_schema
却返回富内容的工具会被记为「未校验」——schema 描述的是 JSON 载荷,而这里
没有载荷可校验。
Python handler¶
Python 的工具 handler 返回 JSON,因此富内容通过一个两侧共读的信封传递:
import json
from par_runtime import text, image_file, tool_content
def shot(_input_json: str) -> str:
return json.dumps(tool_content(
text("a screenshot of the dashboard"),
image_file("assets/dashboard.png"),
))
rt.register_tool_with_handler("shot", "Takes a screenshot", '{"type": "object"}', shot)
信封的键是 Types.tool_content_key(_par_content),块沿用与其他地方完全
相同的 tagged-array JSON,因此 Python 构造的载荷能被 OCaml runtime 原样读取。
不支持¶
富内容是工具结果的形状。workflow 的 Tool_call 步会以 Invalid_input 拒绝
它:workflow 步的输出是 engine 存储并返回的 JSON 值。
从 string 迁移¶
旧的 message 类型有 content : string option。新的类型用 content_blocks : content_block list 替代。迁移方法:
(* 旧模式 *)
let msg = {
role = User;
content = Some "hello";
tool_calls = None;
tool_call_id = None;
name = None;
}
(* 新模式 *)
let msg = {
role = User;
content_blocks = Message.content_of_string "hello";
tool_calls = None;
tool_call_id = None;
name = None;
}
对于多块内容,显式构建列表:
let msg = {
role = User;
content_blocks = [
Text_block { text = "Describe this image:"; cache_control = None };
Image_block {
source = Url "https://example.com/photo.png";
media_type = "image/png";
data = "";
cache_control = None;
};
];
tool_calls = None;
tool_call_id = None;
name = None;
}
读回内容通过相同的辅助函数工作,所以之前直接使用 msg.content 的代码应该切换到 Message.text_of_message msg 或 Message.content_opt msg。
另请参阅¶
- Agent API — Runtime 配置、agent 配置、工具注册
- Streaming API — 带内容块事件的 token 流式传输
- 中间件 API — 看到内容块的管道钩子