Cloudflare/clef · Hugging Face

来源：https://huggingface.co/Cloudflare/clef

• **官方公告：**Cloudflare 博客上的 Clef 决策模型介绍（https://blog.cloudflare.com/clef-decision-models）
• **Decision Index 榜单：**clef-evals.workers-ai-mle.workers.dev（https://clef-evals.workers-ai-mle.workers.dev/）

Clef 是一个 27B 多模态模型，能够将状态（state）和类型化问题的 schema 转换为决策结果。它以文本、JSON、图片或视频的形式读取状态，并在单次前向传播中为每个问题的每个合法选项返回一个概率值。它不进行自由文本生成，也不需要任何输出解析。

Clef 的 API 与 Jev 和 SystemOne 完全兼容。

Clef 基于 Qwen/Qwen3.8-27B（https://huggingface.co/Qwen/Qwen3.8-27B）进行后训练。更小、更快的变体请参见 Clef-Flash（https://huggingface.co/Cloudflare/clef-flash）。

模型（Model）

• 主干网络（Backbone）：Qwen/Qwen3.8-27B，包含其视觉编码器，以标准分片 safetensors 格式存储。
• **联合 schema 头（Joint schema head）：**一个小型 transformer 头部，读取主干网络的最终隐藏状态，将状态中的证据路由到每个问题，并联合对所有问题的所有选项进行打分。
• **输出（Output）：**每个问题的每个合法选项对应一个 logit 值。对每个问题应用 softmax 即可得到概率。

文件（Files）

使用方法（Usage）

在单张 H200 上使用 torch 2.11 和 transformers 5.10.2 测试通过。图像和视频输入还需要 pillow。

import sys

import torch
from huggingface_hub import snapshot_download

path = snapshot_download("Cloudflare/clef")
sys.path.insert(0, path)
from joint_schema_model import collate_records, encode_record, load_release_model

model, processor = load_release_model(path, device="cuda")

record = {
    "state": {"invoice": {"vendor": "Acme", "total": 1250.0, "currency": "USD", "status": "overdue"}},
    "questions": {
        "status": {
            "type": "choice",
            "instructions": "What is the invoice status?",
            "criteria": {"paid": "Invoice is paid.", "overdue": "Invoice is past due.", "draft": "Not sent."},
        },
        "large": {"type": "noul", "instructions": "Is the total above 1000 USD?"},
    },
}

encoded = encode_record(processor.tokenizer, record, processor=processor)
batch = collate_records([encoded], processor.tokenizer.pad_token_id, torch.device("cuda"))
with torch.inference_mode():
    logits = model(batch)[0]

for question, question_logits in zip(encoded.questions, logits):
    probabilities = question_logits.float().softmax(-1).tolist()
    print(question.question_id, dict(zip(question.option_ids, probabilities)))

Jev / SystemOne API

systemone 接受 Jev/SystemOne 的 POST /v1/systemone 请求体，并返回相同的响应体：model、按问题 ID 索引的 answers，以及 usage。choice 类型的回答包含 choice、confidence 和 probabilities；score 类型的回答包含预期的 score、confidence、legend 和 probabilities；noul 类型的回答包含为真的概率。instructions 是可选的，请求中还可以添加 images 和 videos。

from joint_schema_model import systemone

response = systemone(model, processor, {
    "model": "clef",
    "state": "Our checkout started returning errors and orders are blocked.",
    "questions": {
        "department": {
            "type": "choice",
            "instructions": "Which team should handle the message?",
            "criteria": {"billing": "Payments or invoices", "technical": "Bugs or outages"},
        },
        "urgency": {"type": "score", "criteria": ["Can wait", "This week", "Today"]},
        "outage": {"type": "noul", "instructions": "Is a service down?"},
    },
})
print(response["answers"])

图片与视频（Images and video）

在记录中添加 images（PIL 图像）或 videos（帧数组），并将处理器传给 encode_record。可选的处理器参数放在 media_kwargs 中。

from PIL import Image

record = {
    "state": {"task": "Review the attached receipt."},
    "images": [Image.open("receipt.jpg")],
    "questions": {
        "legible": {"type": "noul", "instructions": "Is the receipt total legible?"},
    },
}
encoded = encode_record(processor.tokenizer, record, processor=processor)

纯文本记录和多模态记录可以在同一个批次中混合使用。

输入格式（Input format）

每个问题包含：

• type：noul（真/假）、choice（命名选项）或 score（有序选项）
• instructions：要决策的内容；可选，省略时使用问题 ID
• criteria：choice 类型为选项 ID 到描述的映射；score 类型为从 0 开始索引的选项描述列表；noul 类型可为 true 和 false 提供可选描述

encode_record 接受 max_length（默认 16,384 个 token）和 max_state_tokens 参数以限制输入规模。

结果（Results）

Decision Index

以下为我们在内部运行 Decision Index（https://clef-evals.workers-ai-mle.workers.dev/）0.2.1 套件的分基准测试结果。得分为百分比；ForecastBench 为 Brier 分数，数值越低越好。最后两行为请求延迟（毫秒），数值越低越好。每行的最优值以粗体标出。

工作流评测（Workflow evals）

来自 Typesafe Evals（https://evals.typesafe.ai/）的四个端到端业务工作流上的决策准确率，以共识参考标签进行评分。所有模型均在相同的数据集版本和案例集上进行评分。

许可证（License）

基于基础模型 Qwen/Qwen3.8-27B（https://huggingface.co/Qwen/Qwen3.8-27B），以 Apache-2.0 许可证发布。