如何使用 Cloudflare Clef：实用 API 教程

使用 Cloudflare Clef 时，将应用证据放入 state，在 questions 中定义类型化问题，然后通过 Workers AI 调用 @cf/cloudflare/clef。读取返回的概率，再根据自己的规则选择操作。 你可以先使用 REST，再将同一份决策请求移入 Cloudflare Worker。

Clef 是一个拥有 270 亿参数的多模态决策模型。当软件需要在预定义选项之间作出判断时，它很有用：例如工单应归哪个队列、证据是否表明服务中断，或者中断看起来有多严重。官方模型参考文档介绍了托管接口。

本教程以支持工单分流为例，从模式设计讲到上线。文档和价格核查于 2026 年 10 月 3 日。代码示例已对照公开接口规范核查，但未使用实际推理账户执行。所有示例概率均为模拟数据。

目录

• 选择值得建模的决策
• 构建状态与问题模式
• 调用 Cloudflare Clef REST API
• 正确读取响应
• 在 Cloudflare Worker 中使用 Clef
• 依据自己的证据设置阈值
• 添加图片并了解自托管
• 估算 Cloudflare Clef 成本
• 修正常见集成错误
• 评估并上线工作流
• 常见问题

选择值得建模的决策

从一个范围明确、已有负责人且结果可衡量的操作开始。在本例中，应用必须将支持工单分流至 accounts、billing 或 review。正确结果意味着接收工单的团队可以直接处理问题，无须再转交其他团队。

先写下这一定义，再编写提示词。“理解客户”过于宽泛，难以评估。“识别主要未解决问题的负责团队”则为评审人员提供了具体任务。

有些决策不需要模型。如果数据库中存储的订阅状态已经决定某项功能的使用权限，就查询数据库。如果只需判断发票金额是否超过固定阈值，就在代码中比较数值。将 Clef 留给那些无法用简单规则可靠理解其含义的证据。

将选中的分流目的地与执行权限分开。分类结果为 billing 可以让工单进入账单队列，但不应仅凭这一结果批准退款。我们的 Cloudflare Clef 概览提供了有关这种职责划分的更多背景。

对于智能体应用，应在选择模型之前写明所有目标去向。当决策需要选择工具或另一个模型，而不是支持团队时，模型与工具路由工作流可作为参考。

构建状态与问题模式

使用 state 存放待评估的材料。使用每个问题的 instructions 和 criteria 定义判断标准。不要把客户撰写的文本放进可信评分规则中。

托管接口的输入模式要求提供 model、state 和 questions。每个问题都必须有 type 和 instructions；choice 和 score 还必须有 criteria。

类型	适用场景	criteria 结构
choice	选择一个具名目的地	将选项 ID 映射到描述的对象
noul	评估一个是非命题	可选的 true 与 false 描述
score	根据有序规则评估影响	从低到高排列的数组

让选项描述清楚地区分彼此。“账户访问”和“付款争议”定义了不同的职责边界。“紧急问题”和“技术问题”则存在重叠，因为紧迫程度和归属是两个不同维度。如果需要两个维度，就提出两个问题。

为证据不足和不属于现有分类的情况有意设置 review 路由。否则，每个异常请求都必须竞争某个正常目的地，这可能让看似果断的输出掩盖分类体系本身的缺陷。

构建状态时，应包含相关上下文，并明确标注信息来源。客户声称结账功能不可用，与实际观察到的服务健康检查结果，并不是同一回事。为容易变化的信息添加时间戳，标明未知字段，不要仅仅因为可以获取历史记录就把无关内容一并加入。

随应用一起管理模式版本。即使 JSON 键名保持不变，只要“重大影响”的含义改变，任务就已经发生了变化。明确的模式版本可以让之后的对比具有可解释性。

接入 API 前，先手动尝试几个反例。一位客户可能在申请重置密码时提到付款；另一位客户则可以登录，但对重复扣款提出异议。你的分流定义应该能够解释，这两张工单为什么属于不同团队。如果两位评审人员仅依靠规则还无法达成一致，应先完善规则，再让模型执行。

调用 Cloudflare Clef REST API

首先获取 Cloudflare 账户 ID 和 Workers AI API 令牌。Cloudflare 的 REST 设置指南介绍了控制台中的令牌模板；手动创建的令牌需要 Workers AI Read 和 Edit 权限。将凭证存放在本地环境变量或服务器机密存储中。

将下面的原创示例保存为 decision.json。它针对同一张工单提出了三个相关问题：

{
  "model": "clef",
  "state": {
    "ticket": "I paid yesterday, but password resets still do not let me sign in.",
    "paymentStatus": "settled",
    "serviceHealth": "unknown"
  },
  "questions": {
    "owner": {
      "type": "choice",
      "instructions": "Choose the team for the primary unresolved issue.",
      "criteria": {
        "accounts": "Sign-in, credentials, or account access",
        "billing": "Unresolved charges, refunds, or payment disputes",
        "review": "Missing evidence or no matching team"
      }
    },
    "accessBlocked": {
      "type": "noul",
      "instructions": "Does the customer report being unable to sign in?"
    },
    "impact": {
      "type": "score",
      "instructions": "Rate the disruption supported by this ticket.",
      "criteria": [
        "No current disruption",
        "Partial disruption with a workaround",
        "Customer cannot access the service"
      ]
    }
  }
}

设置好 CLOUDFLARE_ACCOUNT_ID 和 CLOUDFLARE_API_TOKEN 后，发送该文件：

curl --fail-with-body \
  "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/ai/run/@cf/cloudflare/clef" \
  -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-binary @decision.json

端点中的模型与请求体选择器有意保持一致：@cf/cloudflare/clef 对应 "model": "clef"。先从这个小请求开始，可以更容易地定位认证错误和模式错误。

第一次请求成功后，将去除敏感信息的响应保存为开发样例，并在旁边记录模式版本。有了这份固定样例，就可以在每次修改界面时测试响应处理，而无须每次都发起付费推理请求。

对于生产环境调用方，应设置请求超时，区分推理失败与答案不确定，并明确兜底目的地。在有限的重试预算内重试临时故障。重试不应导致外围应用重复创建同一张支持工单。

正确读取响应

REST API 使用 Cloudflare 的响应封装。在检查 HTTP 状态和 success 后，从 result 读取模型输出。Workers AI 绑定则直接返回模型输出。

根据 Clef 输出模式，相关路径如下：

值	REST 响应路径	Worker 绑定路径
选中的团队	result.answers.owner.choice	answers.owner.choice
各团队的概率	result.answers.owner.probabilities	answers.owner.probabilities
报告的访问受阻情况	result.answers.accessBlocked.noul	answers.accessBlocked.noul
预期影响等级	result.answers.impact.score	answers.impact.score
输入用量	result.usage.input_tokens	usage.input_tokens

noul 答案是一个包含数值型 noul 字段的对象，而不是单独的布尔值。Choice 和 score 答案还包含 confidence。Score 是按概率加权的等级索引，因此可能落在两个等级之间。

例如，在等级 0、1、2 上分别分配 0.10、0.20、0.70 的模拟影响概率，会得到 1.60。这个值既不是严重程度标签，也不是 160% 的风险估计。你的策略需要将它转换为实际操作所需的含义。

分流之前，校验预期的问题 ID 和答案类型。将缺失或格式错误的字段视为集成故障，并使用与普通 review 分类不同的日志类别。这一区分有助于判断应该修复应用代码，还是改进决策设计。

在 Cloudflare Worker 中使用 Clef

在已有 Worker 项目中，将 AI 绑定合并到 Wrangler 配置：

{
  "ai": {
    "binding": "AI"
  }
}

将前面的 decision.json 复制到 Worker 入口文件旁边。以下 JavaScript 示例导入这份固定请求体，并返回分流建议：

import decisionInput from "./decision.json";

export default {
  async fetch(_request, env) {
    try {
      const result = await env.AI.run(
        "@cf/cloudflare/clef",
        decisionInput
      );
      const owner = result.answers?.owner;
      const allowed = ["accounts", "billing", "review"];
      const probability = owner?.probabilities?.[owner.choice];

      if (
        owner?.type !== "choice" ||
        !allowed.includes(owner.choice) ||
        typeof probability !== "number" ||
        probability < 0 || probability > 1
      ) {
        throw new Error("Unexpected owner answer");
      }

      // Illustrative threshold: replace after evaluation.
      const route = probability >= 0.85 ? owner.choice : "review";
      return Response.json({ route, probability });
    } catch {
      return Response.json(
        { route: "review", error: "Decision unavailable" },
        { status: 503 }
      );
    }
  }
};

Workers 绑定指南说明了配置方式，以及如何使用 npx wrangler dev 进行本地开发。本地开发期间，Workers AI 推理仍然使用 Cloudflare 资源，并可能产生费用。

这个固定样例端点演示了绑定调用、响应读取和兜底处理。接入真实工单时，需要使用应用现有的身份认证、输入校验和请求限制。在服务器端构建可信问题模式；通过边界明确的输入结构接收工单证据，不要暴露一个不受限制的推理代理。

0.85 这一阈值仅用于说明策略应该放在哪里。它不是 Clef 的默认值，也不是经过实验验证的推荐值。下一步应根据自己的评估结果选择阈值并替换它。

依据自己的证据设置阈值

只有当高概率能够预测你实际收到的案例会取得可靠结果时，它才有用。不要将独立的 confidence 字段解读为经过独立验证的成功率。选定策略使用的统计量，记录下来，并评估使用这一统计量的完整策略。

对于队列分流，可以从选中选项的概率开始。也可以查看最大概率与第二大概率之间的差距。账户团队与账单团队的概率相近，可能说明用户确实有混合意图，也可能说明分类描述区分不够明确。

构建带标签的验证集，对比多个候选阈值。对于每个阈值，衡量自动处理工单中的分流准确率，以及转交复核的比例。提高阈值通常会以覆盖率换取更严格的筛选，但合适的工作点取决于你的数据和错误成本。

考虑一个包含 1,000 张工单的模拟验证集。某个阈值自动分流了 800 张，其中 720 张正确：覆盖率为 80%，已分流案例的准确率为 90%。更严格的阈值分流了 500 张，其中 480 张正确：覆盖率为 50%，已分流准确率为 96%。没有哪个策略在所有情况下都更好。应将新增人工复核的成本与把客户分配给错误团队的成本进行比较。同时还要观察，随着阈值提高，哪些类别退出了自动处理范围；整体指标改善可能掩盖服务质量的不均衡。

进行校准时，将预测按概率区间分组，对比预测概率与实际正确率。如果预测概率约为 0.90 的案例只有 70% 正确，说明这些概率在该样本上过于自信。将校准工作与最终留出集评估分开。

针对不同操作使用不同策略。把工单分错队列和修改账户凭证会带来不同后果。我们的提示词安全工作流讨论了可与显式执行控制并行使用的决策检查。

添加图片并了解自托管

对于托管视觉决策，在请求中添加 images，使用内嵌数据 URL，或包含 content_type 和 base64 的对象。托管输入规范接受 PNG、JPEG 和 WebP；不接受普通远程图片 URL。该规范规定最多 4 张图片，每张最多 4 MiB、1,600 万像素，解码后总大小最多 8 MiB，请求体最多 13 MiB。

一个实用的入门任务是判断截图中是否明显出现了登录错误。为图片配上聚焦的问题和相关上下文。如果应用需要提取精确数字，应先验证提取结果，再执行算术规则。

Hugging Face 模型卡描述了另一条运行路径：下载发布文件，加载主干网络和联合模式头，然后使用附带的 joint_schema_model 辅助工具。其示例使用 load_release_model 和 systemone。该发布采用 Apache-2.0 许可证，文档中的测试环境为单张 H200、PyTorch 2.11 和 Transformers 5.10.2。

本地辅助工具还介绍了 PIL 图片和视频帧数组。这并不代表托管服务支持视频：当前托管模式记录了图片输入，没有视频请求字段。这些本地工具默认的编码上限是 16,384 个 token，与托管服务的上下文窗口不同；请检查你实际部署的配置。

当对服务环境的控制需求足以支撑运维投入时，可以选择自托管。需要为 GPU 显存、批处理、监控和升级预留资源。首次集成时，托管 API 可以减少需要同时排查的系统数量。

估算 Cloudflare Clef 成本

截至 2026 年 10 月 3 日核查，Workers AI 定价表列出的 Clef 价格为每百万输入 token 0.24 美元，Clef-flash 为每百万输入 token 0.09 美元。

以 100,000 次请求、每次平均 1,200 个输入 token 的示例工作量计算，总输入用量为 1.2 亿 token。按公布费率计算，Clef 为 28.80 美元，Clef-flash 为 10.80 美元。这些计算仅涵盖扣除额度前的模型输入费用，未计入其他平台成本，并非完整的月账单估算。

使用代表性请求返回的实际用量，替换假设的平均值。较长的工单历史、详细的评分规则、重试和视觉输入都可能改变工作量。也要跟踪人工复核成本：如果更便宜的推理产生了更多人工工作，整个工作流未必更便宜。

在相同的带标签案例上，使用同一套接受策略对比模型。试用 Clef-flash时，将端点标识符改为 @cf/cloudflare/clef-flash，同时把请求体选择器改为 "model": "clef-flash"。除了成本，也要记录延迟和质量，不要只根据 token 单价选择。

修正常见集成错误

早期故障通常属于以下四类之一：

症状	首先检查的内容
认证失败	账户 ID、令牌权限范围与环境变量加载
请求校验失败	必填 instructions、criteria 结构与模型选择器
JavaScript 读到 undefined 答案	REST 响应封装与绑定直接输出的区别
决策看似合理但不适用	证据质量、选项重叠与缺少复核路由

不要因为另一个 Workers AI 模型接受聊天式 messages 请求体，就把它发给 Clef。应使用 Clef 文档规定的决策规范。同样，不要将 answers.owner 当作字符串解析，也不要期待在聊天补全文本字段中获得自然语言解释。

对于较长记录，应有意识地选择相关证据。托管模型页面列出的上下文窗口为 65,536 个 token，并说明过长的文本状态会被截断。在触及这一边界之前，先保留决策所需的关键事实。

当预测看起来不对时，端到端检查一个案例：实际发送的完整证据、模式版本、完整概率分布，以及最终应用规则。如果一开始就更换模型，原有的数据或策略错误可能仍然存在。

评估并上线工作流

先使用能代表预期路由、语言和信息缺失模式的历史工单。在不参考模型输出的情况下，为主要未解决问题标注标签。在将标签作为可靠参考之前，先解决评审人员之间的分歧。

将数据划分为开发集、验证集和留出集。使用开发集完善模式，使用验证集设置阈值，使用留出集作出是否发布的最终决策。避免将同一段对话中近乎重复的工单分散到不同数据集。

至少跟踪分流正确率、复核率、各路由错误、响应延迟、推理失败和每个获接受决策的成本。单独检查少见路由；出色的整体平均值可能掩盖一个样本少但很重要的类别中反复发生的错误。

维护一个小型错误台账，为每个经复核的失败案例记录原因：证据缺失、规则含糊、模型错误或应用策略错误。这些类别对应不同的修复方法。将修正后的案例加入回归样例集，但不要反复针对最终留出集调优。简单的确定性基线也很有价值：它可以告诉你，新增推理步骤对工作流的改善是否足以抵消其复杂度。

自动分流之前先运行影子模式：在现有业务照常运行时，记录 Clef 会如何选择。将这些建议与真实结果比较。随后仅对少量、可回退的流量启用自动分流，并保留即时兜底方案。

为每个结果保存模型标识符、模式版本、决策策略和输入来源。产品、支持分类或客户使用的语言发生变化时，应检查分布漂移。Jev 文档中心提供了围绕类型化决策构建应用的相关资料。

常见问题

不部署 Worker 也能使用 Cloudflare Clef 吗？

可以。使用限定账户的 REST 端点和 Workers AI 令牌即可。当你希望将决策调用与请求处理和应用策略放在一起时，Worker 就会很有用。

应该使用 choice，还是多个 noul 问题？

当应用必须从互相竞争的选项中选择一个目的地时，使用 choice。当多个独立条件可能同时成立时，使用多个 noul 问题。在解读结果前，先定义这些条件能否重叠。

Clef 能替代聊天模型吗？

将它用于答案已明确规定的决策。如果下一步需要撰写邮件，可以将选中的路由和经过验证的上下文交给合适的生成工作流。其输出仍需遵守同样的应用规则。

分数高是否意味着模型很有把握？

不是。影响分数高，意味着概率质量倾向于评分规则中较高的等级。置信度描述的是分布的另一种属性。检查实际概率，并评估真正控制操作的那个统计量。

首先应该构建什么？

实现一个决策、一个明确的兜底方案，以及一个小型带标签评估集。当你能够解释失败原因，并衡量可接受的覆盖率后，再扩展模式或添加其他工作流。