Markdown 版本
AI-translated from English; not yet reviewed by a fluent editor.
# 如何使用 Cloudflare Clef-omni 检查支持工单
> Cloudflare Clef-omni 接受工单状态、类型化问题以及可选的图像、音频或视频输入。本指南仅依据文档，介绍其 Workers AI 请求、响应、价格和限制。
By BIG CHANGE Editorial
Published: 2026-10-10T13:09:00.735Z
Updated: 2026-10-10T13:09:00.735Z
Canonical: https://bigchange.ai/blog/cloudflare-clef-omni-support-ticket-guide
AI-generated conceptual illustration by BIG CHANGE.
Cloudflare 于 10 月 9 日发布 Clef-omni，将其作为托管在 Workers AI 上的决策模型，可同时检查文本和图像、音频片段或视频。对应用开发者而言，合适的测试范围很明确：向模型提供工单状态和固定问题集，检查回答，并由人工决定如何分流。本指南依据 [Cloudflare 当前的模型文档](https://developers.cloudflare.com/workers-ai/models/clef-omni/) 和 [发布示例](https://blog.cloudflare.com/clef-faster-cheaper-multimodal/)。BIG CHANGE 没有调用该 API，也没有测量它在支持工单上的准确性。
Workers AI 上的模型 ID 是 `@cf/cloudflare/clef-omni` 。它是决策模型：调用方定义类型化问题和允许选项，然后接收这些选项的评分。它不会撰写支持回复。Cloudflare 还发布了开放权重，但以下步骤使用其托管端点。Cloudflare 给出的速度和基准数据是其自身说法，不能证明此工作流在你的工单上会有怎样的表现。
## 准备访问权限和范围有限的问题集
你需要一个有 Workers AI 权限的 Cloudflare 账户、账户 ID、Workers AI API 令牌，以及安装了 `requests` 的 Python，或能够发送相同 HTTP 请求的工具。 [Cloudflare 的 REST 设置指南](https://developers.cloudflare.com/workers-ai/get-started/rest-api/) 说明了在控制面板何处复制账户 ID 并创建令牌。手动创建的令牌需要 `Workers AI - Read` 和 `Workers AI - Edit` 权限。不要把令牌放进工单或源代码管理系统。
发送真实工单或附件，就会把客户内容发送给 Cloudflare 处理。 [Cloudflare 的 Workers AI 数据使用页面](https://developers.cloudflare.com/workers-ai/platform/data-usage/) 称，未经明确同意，不会用这些内容训练 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 模型示例中的 [确切端点和字段](https://developers.cloudflare.com/workers-ai/models/clef-omni/)：
```python
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 的 [发布请求](https://blog.cloudflare.com/clef-faster-cheaper-multimodal/) 将可选媒体分别放入 `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 附加到相应数组：
```python
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。
编码前检查限制。 [模型页面](https://developers.cloudflare.com/workers-ai/models/clef-omni/) 允许最多四张 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 模型文档](https://developers.cloudflare.com/workers-ai/models/clef-omni/)，于 2026 年 10 月 10 日查阅。关于托管模型 ID、API 字段和示例、媒体与上下文限制、响应格式及所列 token 价格的主要参考。文档描述服务行为；BIG CHANGE 未执行该请求。
- [Cloudflare Clef-omni 发布文章](https://blog.cloudflare.com/clef-faster-cheaper-multimodal/)，2026 年 10 月 9 日。确认发布日期并提供嵌入媒体的请求示例。性能和基准数据均为 Cloudflare 自身说法。
- [Cloudflare Workers AI REST 设置](https://developers.cloudflare.com/workers-ai/get-started/rest-api/)，最后更新于 2026 年 9 月 15 日，2026 年 10 月 10 日查阅。说明如何获取账户 ID 和 API 令牌，并列出手动创建令牌所需的权限。
- [Cloudflare Workers AI 数据使用](https://developers.cloudflare.com/workers-ai/platform/data-usage/)，最后更新于 2026 年 4 月 21 日，2026 年 10 月 10 日查阅。说明 Cloudflare 如何处理客户内容、其关于未经明确同意不用于训练和服务改进的限制、使用独立存储服务时可能发生的存储，以及适用协议的边界。它不能确定开发者是否可以提交某个特定工单或录音。
## Sources
- [Cloudflare Clef-omni 模型文档](https://developers.cloudflare.com/workers-ai/models/clef-omni/) — 托管模型 ID、请求和输出 schema、媒体限制、token 计费、价格和上下文；这是文档，不是 BIG CHANGE 的测试。
- [Introducing Clef-omni](https://blog.cloudflare.com/clef-faster-cheaper-multimodal/) — 发布日期和嵌入媒体的请求示例；厂商关于性能和基准的说法不是独立证据。
- [入门：Workers AI REST API](https://developers.cloudflare.com/workers-ai/get-started/rest-api/) — 账户 ID、Workers AI 令牌设置，以及手动创建令牌所需权限。
- [Workers AI 数据使用](https://developers.cloudflare.com/workers-ai/platform/data-usage/) — 最后更新于 2026 年 4 月 21 日；Cloudflare 称其会为提供 Workers AI 而处理输入，未经明确同意不会将内容用于训练或服务改进；使用存储服务时可能会存储内容。请检查适用协议和数据规则。