企业官网建设流程全解析

如何用 Jev/SystemOne API 调用 Clef-Flash：/v1/systemone 请求与响应体完全指南（含三种答案类型）

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

Clef-Flash是 Cloudflare 以 Apache-2.0 协议发布的 9B 多模态决策模型，其 API 与Jev / SystemOne完全兼容：通过POST /v1/systemone发送一个state（当前状态）和一组带类型的问题，模型在单次前向推理中直接返回每个问题每个选项的概率——没有自由文本生成，也无需解析输出。本文带你逐字段拆解请求体与响应体，并完整覆盖choice、score、noul三种答案类型。

⚡ 30 秒上手：一次 systemone 调用

本地运行时，仓库里的 joint_schema_model.py 直接提供了systemone函数，签名就是「请求体进、响应体出」：

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

from joint_schema_model import load_release_model, systemone # 自动下载模型（backbone + 联合 schema 头 + 处理器） model, processor = load_release_model("Cloudflare/clef-flash", device="cuda") request_body = { "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?"}, }, } response = systemone(model, processor, request_body) print(response["answers"])

环境要求：torch2.11 +transformers5.10.2，单张 H200 可运行；处理图片/视频输入时另需pillow。官方内部评测中 Clef-Flash 的中位延迟仅38.8ms（p95 为 122.4ms），适合在线决策场景。

📥 请求体逐字段拆解（POST /v1/systemone）

必填字段：model / state / questions

每个问题包含：

• type：choice（命名选项）、score（有序等级）或noul（是/否），三选一；
• instructions：要决策什么。可选——省略时直接以问题 ID 作为指令；
• criteria：选项定义，含义随类型变化（见下表）。

三种问题类型速查表

可选多模态字段：images / videos

请求体还可携带images（PIL 图片列表）、videos（视频帧数组）以及media_kwargs（透传给图像/视频处理器的参数）。模型基于带视觉编码器的 Qwen3.5-9B 主干（见 config.json），因此文本与图文混合记录可以在同一批中处理。

📤 响应体逐字段解析

systemone返回的响应体包含三个顶层字段：model（回显请求）、answers（按问题 ID 索引的字典）、usage。所有概率与置信度均保留 4 位小数。

三种答案类型对照表（重点）

对应的字段转换逻辑在 joint_schema_model.py#L523-L543 的systemone_answer函数中实现，score的期望分与choice的 argmax 一目了然。

以下响应示例与上文请求体一一对应（数值为示意）：

{ "model": "clef-flash", "answers": { "department": { "type": "choice", "choice": "technical", "confidence": 0.8732, "probabilities": { "billing": 0.1268, "technical": 0.8732 } }, "urgency": { "type": "score", "score": 1.5124, "confidence": 0.6210, "legend": { "0": "Can wait", "1": "This week", "2": "Today" }, "probabilities": { "0": 0.1890, "1": 0.6210, "2": 0.1900 } }, "outage": { "type": "noul", "noul": 0.9412 } }, "usage": { "input_tokens": 96, "output_tokens": 0 } }

两个值得记住的细节：

1. usage.output_tokens恒为 0——输出是结构化概率而非生成文本，input_tokens则是最终送入模型的 token 总数；
2. 概率按问题独立归一——模型对每个问题输出每个允许选项一个 logit，逐题 softmax 得到概率，因此多问题之间互不「抢 token」。

🛡️ 校验规则与常见报错

systemone入口（joint_schema_model.py#L546-L576）会先做参数校验，请求不合法时直接抛ValueError：

• model不是字符串或缺少state→model and state are required
• questions不是非空字典 →at least one question is required
• type不在noul/choice/score中 →<问题ID>: type must be noul, choice, or score
• choice/score的criteria为空 →<问题ID>: criteria must not be empty
• 问题结构本身超出长度上限（默认 16,384 token）→schema requires N tokens before state...，此时 state 部分会被截断到可用空间

📁 关键文件速查

掌握「state+ 三种类型问题 → 三种类型答案」这条主线，你就能把 Clef-Flash 无缝接入任何 Jev / SystemOne 工作流了 🎯

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