clefdecideEnglish

Clef API 中文教程

在 Cloudflare Workers AI 上调用 clef-flash、clef 与 clef-omni。想先试文字/图片?用在线试用(Flash)。独立站点,非 Cloudflare 官方文档。

接口与认证

向 …/ai/run/@cf/cloudflare/clef-flash(或 …/clef、…/clef-omni)发送 POST,带 Workers AI 权限的 API Token;在 Worker 里用 AI 绑定。

请求参数

字段必填说明
model是clef-flash / clef / clef-omni,须与 URL 一致。
state是要判断的内容;过长会按剩余上下文截断。
questions是1–64 个带类型的问题。
images否最多 4 张内嵌图(data URL)。
audio否 · Omni最多 4 段音频。仅 Clef-omni。
videos否 · Omni最多 2 段视频。仅 Clef-omni。

三种问题类型

类型适用返回
noul是/否“是”的概率
choice多选一最可能选项与各选项概率
score有序等级加权分数与各等级概率

题型在三个模型上相同;变化的是 state 媒介(音视频仅 Omni)。下面是 2026-10-03 用 Clef-Flash 跑出的结果:

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

文字示例(Flash)

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"]
      }
    }
  }'

多模态示例(Omni)

curl https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run/@cf/cloudflare/clef-omni \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "clef-omni",
    "state": "Review the installation: a photo of the unit, an audio clip of it running, and a short video of the fan.",
    "images": ["data:image/png;base64,<base64-png>"],
    "audio": ["data:audio/mpeg;base64,<base64-mp3>"],
    "videos": ["data:video/mp4;base64,<base64-mp4>"],
    "questions": {
      "label_visible": { "type": "noul", "instructions": "Is the model and serial number label visible in the photo?" },
      "sounds_normal": { "type": "noul", "instructions": "Does the unit sound smooth, without rattling or grinding?" },
      "fan_running": { "type": "noul", "instructions": "Is the fan running in the video?" }
    }
  }'

返回格式

{
  "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 }
}

在 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-FlashClef-omniClef
规模9B30B MoE(约 3B 激活)27B
价格(仅输入)$0.038/M$0.15/M$0.24/M
托管上下文24,00064,00064,000
原生音视频否是否

大批量文字/图片用 Flash;音视频用 Omni;难例或要更大上下文用 Clef。对比页:三模型对比。

成本估算

短工单约 184 输入 token,约 1000 px 商品图约 823。按 Flash $0.038/M,每 1,000 次大约分别 $0.007 与 $0.031。音视频示例见价格计算器。

常见问题

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

Clef 不生成文字,只回答你定义好的问题,并给每个可选答案一个概率。详见 Clef vs LLM 评审(英文)。

音视频要用哪个模型?

只有 Clef-omni 原生支持 audio 与 videos。本站图片分类仍默认 Clef-Flash。

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

最多 64 个问题;Flash/Clef 最多 4 张图;Omni 另可最多 4 段音频、2 段视频(音视频合计解码 ≤16 MiB)。

资料来源:Workers AI 模型页与 2026-10-09 博客,核对于 2026-10-11。