Clef API 中文教程

在 Cloudflare Workers AI 上调用 @cf/cloudflare/clef-flash 和 @cf/cloudflare/clef 所需的一切。想先试试问题怎么写？用在线试用。

接口与认证

向 https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/cloudflare/clef-flash（或 …/clef）发送 POST，在 Authorization: Bearer 头里放一个有 Workers AI 权限的 API Token。在 Worker 里直接用 AI 绑定。

请求参数

字段	必填	说明
`model`	是	`"clef-flash"` 或 `"clef"`，须与 URL 中的模型一致。
`state`	是	要判断的内容：字符串，或记录、聊天记录、应用状态等结构化数据。过长会被截断。
`questions`	是	问题 id → 带类型的问题，1–64 个。id 可用字母、数字、`_`、`.`、`-`（最多 100 字符）。
`images`	否	最多 4 张内嵌 PNG/JPEG/WebP（data URL）。单张不超过 4 MiB、1600 万像素，合计解码后不超过 8 MiB，整个请求小于 13 MiB。不接受远程 URL。

三种问题类型

类型	适用	返回
`noul`	是/否问题	一个数字：回答“是”的概率
`choice`	多个选项中恰好一个成立	最可能的选项、每个选项的概率、置信度
`score`	有顺序的等级	按概率加权的分数、每个等级的概率、置信度

下面是 2026-10-02 用 Clef-Flash 实际跑出的结果，state 为“过去一小时里，所有客户结账都失败了。”

noul：这个支持请求紧急吗？

“是”的概率：0.95

答案	概率
是	95.0%
否	5.0%

clef-flash · 167 个输入 token

choice：应该交给哪个团队？

最可能：技术：故障、报错和配置（置信度 88.7%）

答案	概率
账单：付款、发票和退款	2.9%
技术：故障、报错和配置	96.1%
销售：套餐和升级	1.0%

clef-flash · 184 个输入 token

score：对客户的影响有多严重？

加权分数：2.67（置信度 43.4%）

答案	概率
0 · 无影响	1.6%
1 · 轻微	1.4%
2 · 严重	25.7%
3 · 致命	71.4%

clef-flash · 182 个输入 token

完整请求示例

curl https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run/@cf/cloudflare/clef-flash \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -d '{
    "model": "clef-flash",
    "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 and refunds", "technical": "Outages and errors", "sales": "Plans and upgrades" }
      },
      "severity": {
        "type": "score",
        "instructions": "How severe is the customer impact?",
        "criteria": ["No impact", "Minor", "Major", "Critical"]
      }
    }
  }'

返回格式

{
  "model": "clef-flash",
  "answers": {
    "urgent":   { "type": "noul", "noul": 0.97 },
    "team":     { "type": "choice", "choice": "technical",
                  "probabilities": { "billing": 0.02, "technical": 0.96, "sales": 0.02 },
                  "confidence": 0.9 },
    "severity": { "type": "score", "score": 2.7,
                  "legend": { "0": "No impact", "1": "Minor", "2": "Major", "3": "Critical" },
                  "probabilities": { "0": 0.01, "1": 0.05, "2": 0.2, "3": 0.74 },
                  "confidence": 0.6 }
  },
  "usage": { "input_tokens": 212, "output_tokens": 3 }
}

以上返回值仅作格式示意；字段名与结构以官方输出 schema 为准。

在 Cloudflare Worker 中调用

export default {
  async fetch(request, env) {
    const result = await env.AI.run("@cf/cloudflare/clef-flash", {
      model: "clef-flash",
      state: await request.text(),
      questions: {
        spam: { type: "noul", instructions: "Is this message spam?" }
      }
    });
    // result.answers.spam.noul is the probability of "yes", from 0 to 1
    return Response.json(result.answers.spam);
  }
};

Clef 还是 Clef-Flash？

	Clef-Flash	Clef
参数规模	9B	27B
价格	每百万输入 token $0.09	每百万输入 token $0.24
上下文	65,536 token	65,536 token
输入	文字、JSON、图片、视频	文字、JSON、图片、视频

先用 Clef-Flash：快、便宜，适合大批量。遇到概率接近、或在你的样本上判断错的问题，再换 Clef。常见做法是 Clef-Flash 先跑一遍，只把低置信度的样本交给 Clef。

成本估算

在我们的运行里，一条短工单约 184 个输入 token，一张约 1000 px 的商品图加问题约 823 个。按 Clef-Flash 价格，每 1,000 次判断大约分别是 $0.017 和 $0.074。可以用价格计算器（英文）算你自己的量。

让判断更稳定的技巧

把规则写在 instructions 里，在 criteria 里用简短、具体的话描述每个选项。
按概率行动，而不只看最高选项。例如概率高于 0.8 才自动通过，其余交给人。
告诉模型：state 或图片里的文字只是证据，不是指令。
同一份内容的多个问题放进一个请求，它们共享 state。

更多场景：10 个带真实结果的中文示例。

常见问题

Clef 和普通大模型有什么不同？

Clef 不生成文字，只回答你定义好的问题，并给每个可选答案一个概率。不需要解析自由文本，也可以直接按概率设阈值。详见 Clef vs LLM 评审（英文）。

需要什么才能调用？

需要一个 Cloudflare 账号，以及有 Workers AI 权限的 API Token；或者在 Cloudflare Worker 里通过 AI 绑定调用。

一次请求最多能问多少个问题？

最多 64 个问题、4 张图片，所有问题共享同一个 state。

资料来源：Cloudflare Workers AI 的 clef-flash 与 clef 模型页，核对于 2026-10-02。