Cloudflare 于 10 月 9 日发布 Clef-omni，将其作为托管在 Workers AI 上的决策模型，可同时检查文本和图像、音频片段或视频。对应用开发者而言，合适的测试范围很明确：向模型提供工单状态和固定问题集，检查回答，并由人工决定如何分流。本指南依据 Cloudflare 当前的模型文档 和 发布示例。BIG CHANGE 没有调用该 API，也没有测量它在支持工单上的准确性。
Workers AI 上的模型 ID 是 @cf/cloudflare/clef-omni 。它是决策模型：调用方定义类型化问题和允许选项，然后接收这些选项的评分。它不会撰写支持回复。Cloudflare 还发布了开放权重，但以下步骤使用其托管端点。Cloudflare 给出的速度和基准数据是其自身说法，不能证明此工作流在你的工单上会有怎样的表现。
准备访问权限和范围有限的问题集
你需要一个有 Workers AI 权限的 Cloudflare 账户、账户 ID、Workers AI API 令牌，以及安装了 requests 的 Python，或能够发送相同 HTTP 请求的工具。 Cloudflare 的 REST 设置指南 说明了在控制面板何处复制账户 ID 并创建令牌。手动创建的令牌需要 Workers AI - Read 和 Workers AI - Edit 权限。不要把令牌放进工单或源代码管理系统。
发送真实工单或附件，就会把客户内容发送给 Cloudflare 处理。 Cloudflare 的 Workers AI 数据使用页面 称，未经明确同意，不会用这些内容训练 Workers AI 提供的模型或改进服务；页面还称，将 Workers AI 与 R2 或 KV 等存储服务搭配使用时，内容可能会被存储。发送客户工单前，请检查适用的 Cloudflare 协议和组织的客户数据规则，并在可行时尽量减少或遮蔽个人信息。Cloudflare 关于不用于训练的声明本身，并不能证明你有权发送某位特定客户的数据。
先从文本开始，以便在添加媒体前检查响应。Cloudflare 自己的支持示例使用状态 Checkout has been failing for every customer for the last hour ，并提出三个问题：是否紧急（noul，是/否类型）、应由哪个团队处理（choice），以及影响有多严重（score）。这是文档中的示例，不是实际观察到的事件。API 接受字符串或结构化对象/数组作为 state。 questions 映射必须包含 1 到 64 个问题 ID；每个问题都有类型和说明，而 choice 和 score 使用 criteria 定义允许的回答。
发送文本请求
在环境中设置 CLOUDFLARE_AUTH_TOKEN ，并替换下方的账户 ID。此 Python 请求采用了 Cloudflare 模型示例中的 确切端点和字段：
import os
import requests
account_id = "your-account-id"
token = os.environ["CLOUDFLARE_AUTH_TOKEN"]
payload = {
"model": "clef-omni",
"state": "Checkout has been failing for every customer for the last hour.",
"questions": {
"urgent": {
"type": "noul",
"instructions": "Is this support request urgent?",
},
"team": {
"type": "choice",
"instructions": "Which team should handle this request?",
"criteria": {
"billing": "Payments, invoices, and refunds",
"technical": "Outages, errors, and configuration",
"sales": "Plans and upgrades",
},
},
"severity": {
"type": "score",
"instructions": "How severe is the customer impact?",
"criteria": ["No impact", "Minor", "Major", "Critical"],
},
},
}
response = requests.post(
f"https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/cloudflare/clef-omni",
headers={"Authorization": f"Bearer {token}"},
json=payload,
timeout=60,
)
response.raise_for_status()
print(response.json())检查成功时，在响应中查找 answers 条目，并核对相同的 urgent、 team 和 severity ID。Cloudflare 将第一项描述为紧急概率，第二项描述为所选团队及其选项概率，第三项描述为概率加权分数，其最低等级为零。API 还记录了 model 和 usage 响应字段。将其映射到应用前，先检查账户返回的完整 JSON。概率是模型针对给定问题和状态的输出，并不保证真实工单应进入该队列。采取行动前，让人工将工单及附件与建议路由进行比对。
添加照片、录音或视频
Cloudflare 的 发布请求 将可选媒体分别放入 images、 audio 和 videos 数组，形式为嵌入的 base64 data: URL。例如，其示例使用 data:image/png;base64,...、 data:audio/mpeg;base64,... 和 data:video/mp4;base64,...。要在 POST 前向 Python payload 添加一个本地文件 requests.post，请将其编码并把 data URL 附加到相应数组：
import base64
from pathlib import Path
def add_media(payload, field, file_path, mime_type):
raw = Path(file_path).read_bytes()
encoded = base64.b64encode(raw).decode("ascii")
payload.setdefault(field, []).append(f"data:{mime_type};base64,{encoded}")
# Examples: use only the files present in the ticket, with their real MIME types.
# add_media(payload, "images", "photo.png", "image/png")
# add_media(payload, "audio", "recording.mp3", "audio/mpeg")
# add_media(payload, "videos", "clip.mp4", "video/mp4")在 POST 前运行 add_media 。保持 state 内容客观，并说明每个附件是什么；只问现有工单和媒体能够回答的问题。Cloudflare 的发布示例使用设备照片、声音录音和风扇视频，针对可见和可听细节提出三个是/否问题。支持应用可以在 state 中保存自己的工单字段，并在 criteria 中保存允许的队列，但应根据实际工作流检查这些定义。该服务不接受远程媒体 URL。
编码前检查限制。 模型页面 允许最多四张 PNG、JPEG 或 WebP 图像，每张最多 4 MiB、1600 万像素，解码后图像总量最多 8 MiB；最多四段音频，每段最多 8 MiB、300 秒；以及两段视频，每段最多 16 MiB、60 秒。音频和视频解码后的合计上限为 16 MiB。视频按每秒两帧抽样；若请求中的每段视频都带音轨，则音轨会与画面一并使用。图像成本取决于缩放后的图像，每张最多计 1,024 个 token。如果附件过大或过长，请让人工选取相关的较短片段，或仅做文本检查并单独查看原始媒体。不要把裁剪或缩短的文件当作完整证据。
检查费用、上下文和失败处理
Cloudflare 当前列出的 Clef-omni 价格为 每百万输入 token 0.15 美元 ，并称不收取输出 token 费用。媒体按该费率转换为输入 token。模型页面称，音频每分钟约 780 个 token；最高分辨率视频每分钟最多约 15,400 个 token，若视频有声音还会增加音频 token。图像费用取决于缩放后的图像，每张上限为 1,024 个 token。这些是计费规则，并非每个附件的固定价格。
托管模型的上下文窗口为 64,000 个 token。媒体和问题都计入其中。若超出窗口，Cloudflare 称请求会失败；否则，长文本 state 可能会被截断以适应窗口。因此，返回了答案并不能证明模型考虑了长工单中的每一行。请求失败时，检查 HTTP 错误，并在文档限制内缩小或移除附件后再试。请求成功时，检查预期的问题 ID 是否齐全，保留原始工单供审核，并根据证据核对建议路由。模型概率可以帮助审核者集中注意力，但要建立服务保证或安全的自动阈值，需要在你自己的标注工单上评估。
重大变化
Cloudflare 于 10 月 9 日发布的版本，将音频和视频加入托管 Clef 决策模型路径；该路径此前已用于包含文本和图像的类型化问题。开发者可在一次 Workers AI 请求中提交一条工单状态及受支持的媒体，并收到按固定 schema 标注的答案。应用团队仍需决定 schema 中应包含哪些问题、在自己的工单上测试表现，并在回复或路由操作前要求人工批准。
来源与延伸阅读
- Cloudflare Clef-omni 模型文档，于 2026 年 10 月 10 日查阅。关于托管模型 ID、API 字段和示例、媒体与上下文限制、响应格式及所列 token 价格的主要参考。文档描述服务行为；BIG CHANGE 未执行该请求。
- Cloudflare Clef-omni 发布文章，2026 年 10 月 9 日。确认发布日期并提供嵌入媒体的请求示例。性能和基准数据均为 Cloudflare 自身说法。
- Cloudflare Workers AI REST 设置，最后更新于 2026 年 9 月 15 日，2026 年 10 月 10 日查阅。说明如何获取账户 ID 和 API 令牌，并列出手动创建令牌所需的权限。
- Cloudflare Workers AI 数据使用，最后更新于 2026 年 4 月 21 日，2026 年 10 月 10 日查阅。说明 Cloudflare 如何处理客户内容、其关于未经明确同意不用于训练和服务改进的限制、使用独立存储服务时可能发生的存储，以及适用协议的边界。它不能确定开发者是否可以提交某个特定工单或录音。
