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-Flash | Clef-omni | Clef | |
|---|---|---|---|
| 规模 | 9B | 30B MoE(约 3B 激活) | 27B |
| 价格(仅输入) | $0.038/M | $0.15/M | $0.24/M |
| 托管上下文 | 24,000 | 64,000 | 64,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。