一行代码调用Clef：Jev/SystemOne /v1/systemone兼容API实战指南

一行代码调用Clef：Jev/SystemOne /v1/systemone兼容API实战指南

【免费下载链接】clef项目地址: https://ai.gitcode.com/hf_mirrors/Cloudflare/clef

Clef 是 Cloudflare 开源的 27B 多模态决策模型，它的 API 与 Jev / SystemOne 的POST /v1/systemone接口完全兼容。你只需要一行代码调用 joint_schema_model.py 中的systemone()函数，传入一段"状态描述 + 问题清单"，即可拿到每个问题所有选项的概率——无自由文本生成，也无需解析任何输出。

💡 一句话理解：其他大模型输出"看起来像答案的文本"，Clef 直接输出"每个选项的概率"。

一、Clef 是什么？为什么叫"决策模型"？

Clef 从 Qwen3.8-27B 后训练而来（见 README.md），架构由两部分组成：

它的核心工作流只有三步：

1. 读取state（一段文本、JSON、图片甚至视频）
2. 读取questions（带类型和允许选项的问题清单）
3. 在单次前向传播中为每个问题的每个选项输出一个 logit，softmax 后即概率

没有逐 token 生成、没有 JSON 解析、没有幻觉文本——这正是/v1/systemone兼容 API 存在的意义：用一次调用完成整个决策。

二、快速上手：一行代码调用 systemone API

环境准备

官方在单卡 H200 上测试通过，依赖如下（图片/视频输入还需pillow）：

pip install torch==2.11.* transformers==5.10.2 huggingface_hub pillow

第 1 步：下载并加载模型

import sys from huggingface_hub import snapshot_download path = snapshot_download("Cloudflare/clef") sys.path.insert(0, path) from joint_schema_model import load_release_model, systemone model, processor = load_release_model(path, device="cuda")

load_release_model会自动加载主干权重、联合 Schema 头（配置见 joint_head_config.json）以及分词器与处理器（tokenizer.json、processor_config.json）。

第 2 步：一行调用（核心）

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"])

就这一行，Clef 会对 3 个问题联合决策并返回完整答案。请求体、响应体与 Jev/SystemOne 的/v1/systemone接口格式一致，可以直接替换掉原有的 Jev / SystemOne 端点调用。

三、三种题型：noul、choice 与 score

questions中每个问题都有固定的type，答案字段也因此确定（实现见 joint_schema_model.py 的systemone_answer）：

响应体顶层只有三个字段：model、按问题 ID 索引的answers、以及usage（含input_tokens/output_tokens）。

四、请求与响应字段速查

请求体（Request）

响应体（Response）：model+answers（含置信度与全部选项概率）+usage。完整示例可对照 README.md 的 "Jev / SystemOne API" 一节。

五、多模态输入：让 Clef 看图片和视频

除了纯文本，state还可以配合images/videos传入图片与视频帧：

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

纯文本记录和多模态记录可以在同一个 batch中混合处理，对批量场景非常友好。

六、性能参考

根据 README.md 中的 Decision Index 0.2.1 基准（与 Jev、Clef-flash 等模型同榜对比），Clef 在多项业务决策任务上领先，例如：

在端到端工作流评估中，Clef 的发票处理"精确动作"得分64.7（Jev 为 61.8）、安全事件"精确动作"62.9均为最高。对延迟敏感的场景可关注更小的 Clef-flash 变体（中位延迟仅 38.8 ms）。

七、常见问题 FAQ

Q1：输入长度有限制吗？默认最大 16,384 tokens，encode_record还可通过max_state_tokens单独限制 state 长度，防止超长输入撑爆上下文。

Q2：Clef 和 Clef-flash 怎么选？Clef 是 27B 全尺寸版本（本仓库），精度最高；Clef-flash 是更小更快的变体，延迟低一个数量级，适合高吞吐在线服务。

Q3：可以本地部署吗？许可证是什么？可以。权重为标准分片 safetensors，Apache-2.0 许可（LICENSE），可自由商用。若偏好 git 方式获取：

git clone https://gitcode.com/hf_mirrors/Cloudflare/clef

Q4：和直接调 LLM 输出 JSON 相比优势在哪？单次前向出全部答案，无逐 token 延迟；输出天然结构化且带概率，无需正则/JSON 解析，也不存在"生成非法 JSON"的风险。

总结

• 兼容性强：请求/响应与 Jev、SystemOne 的/v1/systemone完全一致，可无缝替换
• 调用极短：加载后一行systemone(model, processor, request)即完成决策
• 输出可信：每个选项都带概率和置信度，天然支持阈值策略与审计
• 多模态原生：文本、JSON、图片、视频均可作为 state 输入

核心入口只有一个文件：joint_schema_model.py（systemone函数位于 第 547–576 行），配合 README.md 的输入格式表，10 分钟即可跑通你的第一个决策请求。

【免费下载链接】clef项目地址: https://ai.gitcode.com/hf_mirrors/Cloudflare/clef