
Jev
用 Jev System One API 把用户输入转成带类型的判断结果
Jev 是 TypeSafe AI 提供的 System One Model,它不生成文字,而是按你预先定义的 choice、score、noul 三类问题,把一段输入判定成带类型的结构化数值。本文讲清准备工作、请求结构、三种问题类型的写法、完整可跑示例,以及响应字段与限流、计费要点。
Jev 是 TypeSafe AI 提供的 System One Model 的模型名。它和常见的对话模型走的不是同一条路:它不负责把回答「写出来」,而是接收一段输入文本,针对你事先定义好的若干问题,返回带类型的判断结果——一个选项、一个分数,或者一个 0 到 1 的置信度。典型用法是把它放在人和业务程序之间做「前处理」:一条投诉进来,先判定它属于哪一类、有多重要、有多紧急,再由普通程序按这些数值决定后续流程。如果你正在做客服分流、工单打标、内容审核前置判断这类需要「快速给出结构化结论」的场景,可以先用本站的 Jev 工具页了解入口,再按下面的步骤接入 API。
需要先说明一点:Jev 的价值在于判断速度与输出结构,而不是生成质量。它把「用语言组织答案」这一步省掉,直接输出定量值,因此响应通常远快于让对话模型生成一段 JSON,同时因为不需要自由发挥,幻觉问题也被大幅压缩。下面从准备工作开始,一步步把请求跑通。
准备工作
账号与 API Key
Jev 的正式 API 需要账号体系与 Bearer 认证。流程是:先在 TypeSafe AI 的控制台注册账号,然后在控制台里创建 API Key。之后每次请求都要在 HTTP 头里带上这个 Key:
Authorization: Bearer ${API_KEY}
控制台里还能查看当前额度余额与用量情况:点击账号区域进入 Settings,再进入 Billing 页面可以看到剩余额度,Usage 页面可以看到 token 数与请求数随时间的变化。这些页面的具体位置与名称可能随产品迭代调整,以官网当前信息为准。
计费与免费额度
Jev 原则上是一个付费模型,但计费方式比较特殊:只对输入 token 计费,输出部分不计费。用量页面里会以小字标注类似「按每百万输入 token 计价、输出免费」的说明。此外账号会按月获得一小笔免费额度,有效期一个月,超出部分才需要补充账单信息。具体的单价、免费额度金额与有效期属于易变信息,请以官网当前公布为准,不要按本文的旧数字做预算。
限流与上下文限制
接入前需要知道几个硬约束,它们会直接影响你的并发设计:
- 速率限制:同时存在每秒 token 数与每分钟请求数两个维度的上限,具体数值以官网为准。
- 上下文长度:单个请求有总 token 上限,其中一部分要留给状态文本与最长的提问描述,剩余才是你的输入内容。输入过长会被截断或拒绝,长文本要先做裁剪。
- 输入类型:只接受文本。可以是字符串、JSON 对象,或文本值的数组;图片、音频、视频都不支持。
本地验证环境(可选)
如果只想先验证请求结构、不想立刻消耗额度,可以搭一个本地兼容层:用一个本地推理服务(例如 llama.cpp 暴露的 OpenAI 兼容端点)承接上游,再由一个转换程序把 System One 风格的请求翻译成对话请求,让本地模型按固定格式吐出判断值。这条路适合开发期调试与内网场景,但输出数值与正式模型必然存在差异,只能用来验证「请求能不能通、字段对不对」,不能用来校准阈值。
本地环境需要先装 Bun 运行时,然后克隆转换程序、安装依赖、写配置文件、启动服务。配置项大致包括:上游地址、上游 API Key、上游模型名、监听地址与端口、超时秒数、最大并发、最大排队数、格式错误重试次数、最大输出 token 数、每次调用的问题数上限与结果数上限。其中上游模型名必须与上游服务实际返回的模型标识完全一致,否则程序会判定为未就绪而拒绝工作。可以先用 curl 请求上游的模型列表接口,从返回的 JSON 里取出模型标识字段,原样填进配置。启动后本地服务会监听你配置的端口,请求格式与正式 API 基本一致,只是模型名不同。
操作步骤
第一步:确定要问什么
Jev 的请求核心不是「提示词」,而是「问题清单」。你要先把业务判断拆成若干个可以独立回答的问题,每个问题选一种类型。三种类型如下:
| 类型 | 目标 | 返回字段 |
|---|---|---|
| choice | 从给定选项里选一个 | choice、probabilities、confidence |
| score | 按给定评价档位打分 | score、legend、probabilities、confidence |
| noul | 判断某条陈述成立的程度 | noul(0 到 1 之间的值) |
三种类型可以在同一个请求里混用。每个问题会被并行、独立地评估,因此增加问题数量几乎不会拉长响应时间,也不会因为问题变多而互相干扰上下文。
第二步:拼装请求体
请求体有两个顶层字段:state 放被评估的文本,questions 放问题集合。每个问题用你自定义的名称作为键,值里包含类型、提问说明,以及该类型对应的结构:
{
"model": "jev-latest",
"state": "<被评估的文本>",
"questions": {
"<问题名>": {
"type": "choice | score | noul",
"instructions": "<针对该类型的问题描述>",
...
}
}
}
各类型的附加结构不同:
- choice:需要
criteria对象,键是选项名,值是该选项的定义。 - score:需要
criteria数组,按从低到高的顺序列出各档位的名称。 - noul:不需要 criteria,只写 instructions 即可。
第三步:发送请求
用 curl 发一个包含三种类型问题的请求:
curl -X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer ${API_KEY}" \
-d '{
"model": "jev-latest",
"state": "intel 的 xe 驱动或 Intel ARC PRO B70 相关,在 Ubuntu 24.04 LTS、Kernel 6.17.0-42 的配置下发生的问题,请调查并说明。",
"questions": {
"category": {
"type": "choice",
"instructions": "输入内容的类别是以下哪一种?",
"criteria": {
"serious": "情感或精神层面重要的对话",
"technical": "技术咨询",
"investigation": "非技术但需要调查的对话",
"other": "闲聊或并不严肃的日常对话"
}
},
"importance": {
"type": "score",
"instructions": "输入内容的重要程度如何?",
"criteria": ["不重要", "稍重要", "重要", "很重要", "严重"]
},
"urgent": {
"type": "noul",
"instructions": "这个咨询是否要求紧急处理"
}
}
}'
注意 model 字段可以填 jev-latest 这样的别名,响应里会回显实际使用的模型版本号。
第四步:读取响应
响应结构由 model、answers、usage 三部分组成。answers 下的键与你请求里的问题名一一对应,每个答案按类型给出不同字段。usage 给出本次消耗的输入与输出 token 数——由于只对输入计费,input_tokens 才是你真正要关注的成本项。
解读时有几个要点:
- choice 的
choice是最终选项,probabilities是各选项的概率分布,confidence是这次判断的把握程度。如果最高概率与其他选项差距很小,说明输入本身模棱两可,业务上应当走人工复核而不是硬分。 - score 的
score是落在档位刻度上的连续值,可能落在两档之间;legend把刻度映射回档位名称;probabilities是各档位的概率。当分数落在两档中间时,confidence通常偏低,这本身就是「需要更细分析」的信号。 - noul 只给一个 0 到 1 的值,越接近 1 表示该陈述成立的程度越高。
一个完整示例
下面用一条客服投诉走完整流程:先判定类别与紧急度,再根据数值决定路由。
输入文本:一位客户表示买了产品却无法正常工作,要求退款,语气激烈。
请求:沿用上面的三段式结构,把 state 换成投诉原文,问题保持 category / importance / urgent 三个。
响应(正式模型):
{
"model": "jev-1.13.0",
"answers": {
"category": {
"type": "choice",
"choice": "technical",
"confidence": 0.98,
"probabilities": {
"other": 0.0,
"technical": 0.99,
"investigation": 0.01,
"serious": 0.0
}
},
"importance": {
"type": "score",
"score": 2.26,
"confidence": 0.6,
"legend": {
"0": "不重要",
"1": "稍重要",
"2": "重要",
"3": "很重要",
"4": "严重"
},
"probabilities": {
"0": 0.02,
"1": 0.08,
"2": 0.55,
"3": 0.33,
"4": 0.02
}
},
"urgent": {
"type": "noul",
"noul": 0.21
}
},
"usage": {
"input_tokens": 566,
"output_tokens": 79
}
}
解读:类别被判定为技术类,概率 0.99,几乎无歧义;重要度得分 2.26,落在「重要」与「很重要」之间,置信度 0.6 属于中等,说明模型认为这条内容确实重要但档位边界模糊;紧急度 0.21,说明模型并不认为它要求紧急处理。
业务侧处理:程序读到 category.choice == "technical" 且 urgent.noul 低于阈值,就把工单直接派给技术部门,而不是先让聊天机器人做一轮安抚式回复。这正是 Jev 的设计意图——把「先判断、再处理」中的判断环节交给一个快速、结构化的模型,避免真正着急的客户被机器人挡在门外、怒气进一步升级。
如果换成同一请求在本地兼容层上的输出,类别同样是 technical,但概率分布更分散(technical 约 0.9),重要度得分约 1.65、置信度约 0.32,紧急度约 0.08。数值方向一致但幅度不同,这提示你:阈值必须在正式模型上校准,本地结果只能用于验证链路。
注意事项
模型名必须精确匹配
在本地兼容层场景下,上游模型标识写错会导致服务判定为未就绪,请求全部失败。正式 API 用 jev-latest 别名可以规避版本号变动带来的问题,但如果你的业务对输出稳定性要求高,建议在响应里记录实际返回的模型版本号,便于回溯。
输入长度与内容
单请求上下文有上限,且其中一部分被状态信息与最长提问描述占用。超长工单、整段聊天记录需要先摘要或截断再送入。另外只支持文本输入,多模态内容必须先转成文字描述。
速率与并发
每秒 token 数与每分钟请求数两个维度都会限流。批量处理历史数据时要做客户端侧的排队与退避,不要一次性打满。本地兼容层也有最大并发与最大排队数的配置,超出后会拒绝请求。
计费口径
只对输入计费、输出免费,这意味着「多问几个问题」的成本远低于「把输入写得更长」。设计问题清单时可以放心增加维度,但要控制 state 的长度。单价、免费额度、限流数值都会调整,务必以官网当前信息为准。
数值不是绝对真理
同一段文本在不同模型版本、不同 criteria 措辞下会得到不同数值。criteria 的档位名称与定义顺序会影响结果,调整措辞后要重新跑一批样本验证分布是否漂移。对于 confidence 偏低的结果,业务上应当设计人工复核分支,而不是直接按最高概率硬判。
不要把它当生成模型用
Jev 不产出自然语言回答。如果你的需求是「给用户回一段话」,那是对话模型的职责;Jev 的职责是在那之前把输入拆解成可编程的数值。把两者串起来用,才是它被设计出来的位置。