Cloudflare/clef-flash · Hugging Face

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

• **发布公告：**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-Flash 是一个 9B 多模态模型，能够将一个状态和一组带类型的结构化问题转换为决策结果。它可以将状态以文本、JSON、图像或视频的形式读入，并在一次前向传播中为每个问题的每个允许选项返回概率。模型不会进行自由文本生成，也不需要输出解析。

Clef-Flash API 与 Jev 和 SystemOne 完全兼容。

Clef-Flash 是基于 Qwen/Qwen3.5-9B（https://huggingface.co/Qwen/Qwen3.5-9B）后训练得到的。更大的版本请参阅 Clef（https://huggingface.co/Cloudflare/clef）。

模型

• **骨干网络：**Qwen/Qwen3.5-9B 及其视觉编码器，以标准分片 safetensors 格式存储。
• **联合结构化输出头：**一个轻量的 transformer 头，读取骨干网络的最终隐藏状态，将状态中的证据路由到每个问题，并对所有问题的所有选项进行联合评分。
• **输出：**为每个问题的每个允许选项输出一个 logit。对每个问题单独应用 softmax 即可得到概率。

文件

使用方法

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

import sys

import torch
from huggingface_hub import snapshot_download

path = snapshot_download("Cloudflare/clef-flash")
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 类型的回答包含为 true 的概率。instructions 是可选的，还可以在请求中添加 images 和 videos。

from joint_schema_model import systemone

response = systemone(model, processor, {
    "model": "clef-flash",
    "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（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)

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

输入格式

每个问题包含：

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

encode_record 接受 max_length（默认 16,384 个 token）和 max_state_tokens 参数，用于限制输入大小。

结果

Decision Index

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

工作流评测

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

许可证

基于基础模型 Qwen/Qwen3.5-9B（https://huggingface.co/Qwen/Qwen3.5-9B），采用 Apache-2.0 许可证发布。