Skip to Content
API 参考Decisions 判断

Decisions API

Decisions API 用来让模型对一段内容做类型化判断,而不是生成文本。你提供要判断的内容和一组问题,模型对每个问题返回一个结构化答案:是/否的概率、从选项中选一个、或在分级量表上打分,并附带每个选项的概率和置信度。

适合分类、路由、审核、打分、过滤等需要「程序直接拿结果做分支」的场景。模型只能在你给定的选项和分级里作答,不会返回选项以外的内容,也不需要解析自由文本。

首次使用判断模型时,建议先阅读 Jev 使用指南,其中包含快速开始、问题设计、返回结果说明与场景示例。本页为字段级参考。

端点

三条路径背后是同一批模型、同一套计费,区别只在请求和响应的格式。按你使用的客户端选一条:

路径格式适合
POST https://api.ofox.ai/v1/decisionsOfoxAI 统一格式(问题为数组)cURL、任意 HTTP 客户端、OpenAI SDK
POST https://api.ofox.ai/openai/v1/decisions同上已把 OpenAI SDK 的 base_url 设为 https://api.ofox.ai/openai/v1 的项目
POST https://api.ofox.ai/typesafe/v1/systemoneTypeSafe 官方 System One 格式(问题为对象)TypeSafe 官方 SDK,或照着 TypeSafe 官方文档写的代码

认证方式与其他接口相同:Authorization: Bearer <你的 OFOXAI_API_KEY>。只支持非流式,一次请求同步返回全部答案。

可用模型

模型 ID说明
typesafe/jev-latestTypeSafe Jev,专用判断模型。仅文本或 JSON 输入,64K 上下文。可简写为 jev-latest
openai/gpt-6-luna三条路径都可调用;可读图片(在消息数组里传 input_image)

支持该接口的完整模型列表见模型页 。对普通对话模型(如 openai/gpt-4o)调用会返回 endpoint_not_supported。

统一格式:/v1/decisions

请求参数

参数类型必填说明
modelstring✅模型 ID,如 typesafe/jev-latest
inputstring | object | array✅要判断的内容,见输入格式
questionsarray✅问题列表,每个元素是一个问题对象。答案按同样顺序返回
safety_identifierstring—稳定的终端用户 ID,仅对 OpenAI 模型生效

输入格式

input 支持三种写法:

  • 文本:一个字符串。
    "input": "客户留言:我被重复扣款了,两封邮件都没人回,今天必须退款。"
  • 结构化数据:一个 JSON 对象,原样交给模型。问题里可以用反引号引用字段名,如 `message`。
    "input": { "ticket_id": 4812, "message": "我被重复扣款了。", "plan": "pro" }
  • 消息数组:[{ "role", "content" }],content 为字符串或内容块列表,内容块只支持 input_text 与 input_image。图片仅对可读图片的模型有效,Jev 不读图片,传图片会返回 400。

问题对象

字段适用类型说明
type全部predicate(是/否)、choice(单选)、score(分级打分)
name全部可选,但建议填写。原样带回答案里,便于对应。同一请求内不能重复
instructions全部问题本身。字符串,或包含问题和参考数据的 JSON 对象
criteriapredicate可选,{ "true": "...", "false": "..." },说明「是」和「否」各指什么
choiceschoice必填。选项数组,每项为 { "value": "billing", "description": "扣款、退款" },description 可省略。最多 255 项
levelsscore必填。按从低到高排列的级别数组,每项为 { "label": "low", "description": "..." }。2–10 级

请求示例

Terminal
curl https://api.ofox.ai/v1/decisions \ -H "Authorization: Bearer $OFOX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "typesafe/jev-latest", "input": "客户留言:我被重复扣款了,两封邮件都没人回,今天必须退款。", "questions": [ { "type": "predicate", "name": "is_frustrated", "instructions": "客户是否不满?" }, { "type": "choice", "name": "category", "instructions": "这张工单属于哪一类?", "choices": [ { "value": "billing", "description": "扣款与退款" }, { "value": "bug", "description": "产品故障" }, { "value": "other", "description": "其他" } ] }, { "type": "score", "name": "urgency", "instructions": "需要多快由人工回复?", "levels": [ { "label": "low", "description": "一周内即可" }, { "label": "medium", "description": "应尽快回复" }, { "label": "high", "description": "今天必须回复" } ] } ] }'

响应格式

{ "model": "typesafe/jev-latest", "answers": [ { "type": "predicate", "name": "is_frustrated", "probability": 0.97 }, { "type": "choice", "name": "category", "choice": "billing", "confidence": 1, "probabilities": [ { "value": "billing", "probability": 1 }, { "value": "bug", "probability": 0 }, { "value": "other", "probability": 0 } ] }, { "type": "score", "name": "urgency", "score": 2, "confidence": 1, "legend": { "0": "low: 一周内即可", "1": "medium: 应尽快回复", "2": "high: 今天必须回复" }, "probabilities": [ { "value": 0, "label": "low", "probability": 0 }, { "value": 1, "label": "medium", "probability": 0 }, { "value": 2, "label": "high", "probability": 1 } ] } ], "usage": { "prompt_tokens": 407, "completion_tokens": 72, "total_tokens": 479 } }

answers 与 questions 一一对应、顺序相同。各类型答案的字段:

类型字段说明
predicateprobability答案为「是」的概率,0–1
choicechoice概率最高的选项
probabilities每个选项的概率,合计为 1
confidence模型对这次判断有多确定,0–1,见概率与置信度
scorescore按概率加权的级别值,从 0 开始,可以落在两级之间(如 1.43)
legend级别编号到描述的对照
probabilities每一级的概率
confidence同上

TypeSafe 原生格式:/typesafe/v1/systemone

与 TypeSafe 官方 API  的请求和响应格式一致,适合直接使用 TypeSafe SDK 或迁移已有代码。和统一格式相比有三处不同:

统一格式 /v1/decisionsTypeSafe 原生格式
要判断的内容inputstate
问题数组,用 name 标识对象,键名即问题 ID
是/否问题type: "predicate",答案字段 probabilitytype: "noul",答案字段 noul
选项与级别choices / levels 数组都写在 criteria 里:choice 用 {选项: 描述} 对象,score 用描述字符串数组
用量字段prompt_tokens / completion_tokensinput_tokens / output_tokens
Terminal
curl https://api.ofox.ai/typesafe/v1/systemone \ -H "Authorization: Bearer $OFOX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "jev-latest", "state": "Help! My payouts have been failing for 3 days.", "questions": { "is_urgent": { "type": "noul", "instructions": "Does this convey urgency?" }, "department": { "type": "choice", "instructions": "Which team should handle this?", "criteria": { "billing": "Payments, invoicing, refunds", "technical": "Bugs, outages, integrations", "sales": "Pricing, upgrades" } }, "frustration": { "type": "score", "instructions": "How frustrated is the customer?", "criteria": ["Calm", "Frustrated", "Very angry"] } } }'
{ "model": "typesafe/jev-latest", "answers": { "is_urgent": { "type": "noul", "noul": 0.95 }, "department": { "type": "choice", "choice": "billing", "confidence": 0.85, "probabilities": { "billing": 0.9, "technical": 0.1, "sales": 0 } }, "frustration": { "type": "score", "score": 1.03, "confidence": 0.95, "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" }, "probabilities": { "0": 0, "1": 0.97, "2": 0.03 } } }, "usage": { "input_tokens": 399, "output_tokens": 73 } }

SDK 接入

OpenAI SDK

OpenAI 官方 SDK 提供 client.decisions.create(),base_url 指向 https://api.ofox.ai/v1 即可,请求体使用统一格式。示例见上方 Python 标签页。需使用包含 Decisions API 的 SDK 版本(实测 openai Python 3.31.0 可用)。

TypeSafe SDK

TypeSafe 官方 SDK 把 base_url 指向 https://api.ofox.ai/typesafe,api_key 换成 OfoxAI API Key,其余代码不变:

typesafe_sdk.py
# pip install typesafe-sdk import os from typesafe_sdk import TypeSafeClient, Noul, Choice, Score with TypeSafeClient(base_url="https://api.ofox.ai/typesafe", api_key=os.environ["OFOX_API_KEY"]) as client: r = client.system_one( model="jev-latest", state={"message": "我被重复扣款了,两封邮件都没人回,今天必须退款。"}, questions={ "urgent": Noul(instructions="客户是否要求今天处理?"), "dept": Choice( instructions="应该由哪个团队处理?", criteria={"billing": "扣款、发票、退款", "technical": "故障、接入", "sales": "价格、升级"}, ), "anger": Score(instructions="客户有多不满?", criteria=["平静", "不满但礼貌", "非常愤怒"]), }, ) print(r.nouls["urgent"].noul) # 0.98 print(r.choices["dept"].choice) # billing print(r.scores["anger"].score) # 1.92

概率与置信度

  • 概率回答「答案是什么」:probability、probabilities 是模型对各个答案的校准概率。
  • 置信度回答「该不该信这次判断」:confidence 由概率分布推出,分布越集中越高。两个选项各 0.5 时,choice 仍会给出一个,但 confidence 很低。

常见做法是在代码里设阈值:置信度高时自动执行,低时转人工或交给更强的模型复核。

计费

按 token 计费,单价见模型页 。typesafe/jev-latest 只按输入 token 计费,输出不计费(completion_tokens / output_tokens 照常返回)。

一次请求里的所有问题共享同一份输入,把多个问题放进同一请求比拆成多次调用便宜得多,也更快。

限制

项目限制
请求体最大 32 MiB
上下文Jev 为 64K token,超出返回 400
choice 选项最多 255 个
score 级别2–10 级
JSON 嵌套input/state、instructions、criteria 各自最多 64 层
流式不支持

常见报错

HTTP · type报错原文原因处理方法
400 invalid_request_errorquestion "a" has kind choice and requires criteria optionschoice 问题没有 choices补上选项数组
400 invalid_request_errorquestion name "a" is used more than once两个问题的 name 相同改成不重复的名字
400 invalid_request_errorToo many score levels. Must have at most 10 levels.score 级别超过 10 个合并级别,或拆成多个问题
400 invalid_request_errordecision input carries an "input_image" part, which Typesafe cannot read给 Jev 传了图片去掉图片,或改用可读图片的模型
400 invalid_request_errorInvalid request payload在 /v1/decisions 上使用了 TypeSafe 原生格式(state + 对象形式的 questions)改用统一格式,或改调 /typesafe/v1/systemone
400 endpoint_not_supportedModel 'openai/gpt-4o' does not support the /v1/decisions endpoint on this platform.该模型不是判断模型换用可用模型
404 model_not_foundModel 'typesafe/jev-9' not found模型 ID 写错使用 typesafe/jev-latest
404 invalid_request_errorUnsupported API endpoint.路径写成了 /v1/systemoneTypeSafe 原生格式的路径是 /typesafe/v1/systemone

其他通用错误见错误处理。

最后更新于