Modelink

Jev 使用说明

Jev 是 TypeSafe 推出的 System One 模型：它不生成自由文本，而是根据你预先定义的答案范围，返回类型化的判断结果和概率，适合把分类、路由、打分、是否放行等判断嵌入业务流程。Modelink 为 Jev 提供两个专用入口，两者都不走 /v1/chat/completions，请求体中没有 messages 数组，也不支持流式输出。

两个调用入口

入口协议适用场景
POST /v1/systemoneJev System One 原生契约直接使用 Jev 语义：state 加 questions map，题型为 noul / choice / score
POST /v1/decisionsOpenAI Decisions 原生契约已有 OpenAI Decisions 客户端或代码：input 加 questions 数组，题型为 predicate / choice / score

警告

两套请求结构不能混用。调用 /v1/decisions 时，如果本次请求可以转换为 Jev System One 且被调度到 decisions-jev 渠道，平台会自动完成转换；无法转换的请求只在 decisions-openai 渠道中调度，详见渠道兼容与调度。

调用前准备

  • 在 Modelink 控制台创建 API Key，并确认账号具备 Jev 的调用权限。
  • 根据业务区域选择接入点：海外 https://api.modelink.ai，中国大陆 https://api.qnaigc.com。
  • 确认模型 ID。通常使用别名 jev-latest；生产环境建议固定版本（如 jev-1.13.0），避免版本漂移。两个入口的 model 都会按平台模型市场解析（支持别名），响应中的 model 固定为解析后的模型，不会透出上游渠道模型名。实际可用 ID 以控制台为准。
项目Jev 原生契约OpenAI Decisions 契约
接口POST /v1/systemonePOST /v1/decisions
海外端点https://api.modelink.ai/v1/systemonehttps://api.modelink.ai/v1/decisions
大陆端点https://api.qnaigc.com/v1/systemonehttps://api.qnaigc.com/v1/decisions
认证Authorization: Bearer <api_key>同上
请求格式Content-Type: application/json同上
流式输出不支持不支持；显式传 stream: true 返回 400
支持的输入文本、JSON 对象、文本数组文本或 user 文本消息数组；图片不支持

请求与响应

两个入口的请求参数、请求/响应 schema、示例和错误响应统一维护在 API Reference，本文不再重复：

  • System One 决策 API：POST /v1/systemone，请求使用 state 与 questions 对象；题型为 noul / choice / score，响应返回同键的 answers 对象。
  • OpenAI Decisions API：POST /v1/decisions，请求使用 input 与 questions 数组；题型为 predicate / choice / score，响应按题目顺序返回 answers 数组。

两个入口都返回顶层 model 与 usage。/v1/systemone 的 usage 只有 input_tokens 和 output_tokens；/v1/decisions 经 Jev 渠道回译时还会返回两者之和的 total_tokens。

与 Jev 契约的字段对照

维度/v1/systemone（Jev）/v1/decisions（OpenAI Decisions）
上下文state：string、object 或 arrayinput：string 或 user 消息数组
问题集合questions：id 到 Question 的 mapquestions：数组
是非判断noul，返回 noul 概率predicate，返回 probability
选择choice 加 criteria 映射choice 加 choices[].value（string / boolean）
打分score 加 criteria 有序数组score 加 levels[].label
题名对象键，必须非空name 可选、可为 null、可重复
响应answers 为 mapanswers 为数组，保持请求顺序
置信度choice / score 返回 confidence同左；noul 与 predicate 均无 confidence
流式不支持不支持；显式 stream: true 返回 400

渠道兼容与调度

两个入口共用同一套鉴权、模型解析、限流和计费链路，区别在入口协议与可用上游渠道：

  • /v1/systemone 对外始终返回 Jev 契约。上游可以是 decisions-jev（直接调用 Jev System One）或 decisions-openai（平台把 Jev 契约转换为 OpenAI Decisions）。
  • /v1/decisions 保留原生请求形态。平台先判断请求能否转换为 Jev：
    • 顶层只包含 model、input、questions、stream，且 input 为纯文本或 user 文本消息时，可在两种渠道中调度。
    • 出现 input_image、非 user 消息或顶层扩展字段（如 safety_identifier）等内容时，只能走 decisions-openai 渠道。
    • 如果该模型只有 decisions-jev 渠道，请求会返回 400，错误码为 protocol_unsupported。
  • /v1/systemone 的请求结构中没有 stream 字段，传入该字段会被忽略并按非流式处理；/v1/decisions 传 stream: true 则会在入口直接返回 400。
  • Jev 本身不支持图片输入：input_image 在转换为 Jev 时会被显式拒绝，不会被静默丢弃。

用阈值处理判断结果

Jev 返回格式正确，不代表判断一定正确。生产环境建议结合概率、置信度和确定性规则决定下一步，例如：

const response = await fetch("https://api.modelink.ai/v1/systemone", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MODELINK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "jev-latest",
    state: ticket,
    questions: {
      department: {
        type: "choice",
        instructions: "这条反馈应该由哪个团队处理？",
        criteria: {
          billing: "付款、账单与退款问题",
          technical: "报错、故障与集成问题",
        },
      },
      asks_refund: {
        type: "noul",
        instructions: "客户是否明确提出退款请求？",
      },
    },
  }),
});

const { answers } = await response.json();

if (
  answers.department.choice === "billing" &&
  answers.department.confidence >= 0.8 &&
  answers.asks_refund.noul >= 0.8
) {
  // 自动分流到账单团队
} else {
  // 交给人工复核或其他流程
}

限制与排错

  • Jev 只做结构化判断，不生成文案。摘要、对话或开放式任务继续使用对应的 Chat 模型。
  • 两套入口的请求结构不能混用：/v1/systemone 使用 state 和 map questions，/v1/decisions 使用 input 和数组 questions。
  • state 目前只接受文本类输入，不支持图片、音频和视频。
  • 平台对转换为 Jev 的响应做完整性校验：缺失答案、缺失 usage、缺失 confidence、概率未覆盖全部选项或档位、题型不匹配都会返回上游错误，不会补零或伪造字段。
  • 常见错误：400 请求结构、参数或模型校验失败（/v1/decisions 传 stream: true 属于此类）；401 / 403 认证失败或无权限，不要重试；429 触发限流，建议指数退避后重试；5xx 上游或网关异常，可有限重试并准备降级方案。完整状态码、错误体和示例见 API Reference。
  • 可用模型、限流额度和具体错误码以 Modelink 控制台与 API Reference 为准。

更多背景可参考 TypeSafe 官方 API 文档。

Last updated

© 2026 Modelink. All rights reserved.

构建来自Clarify