JevK5 决策模型接口接入指南：参数说明 + 代码示例

JevK5 决策型接口面向"需要机器替你做判断"的环节。它不是自由文本生成器，而是接收一段状态（state）与一个结构化问题（question），返回带概率的类型化决策结果——是/否二选、多选项排序、或对目标打分。结果是结构化的，代码可以直接拿来分支、排序、路由，无需再从自然语言里解析。

它同时提供两种形态：云端调用开箱即用，也可在自有 GPU 上自托管、数据不出域，两种形态共用同一套请求结构，迁移成本低。以下从能力、接入、调用、调试、限制与工程实践几个维度展开。

一、技术简介

JevK5 是一个强类型、结果经类型化校验的决策型接口实现，定位为判断类任务，而非写作类任务：

• 输入：state（当前上下文/状态描述）+ question（一个边界清晰的原子问题）。
• 输出：带概率的结构化结果，形态包括「是 / 否」「多选项 + 概率」「评分 + 置信度」。
• 特点：一次前向输出全部概率，不产生"写文章"式的自由文本开销，因此时延可预测。

与自由文本大模型相比，它把"不确定性"显式地返回给调用方：每个判断都带置信度，调用方据此做门控（低于阈值转人工复核）。

二、能力概览

要点：判断要拆细。一个原子问题只问一件边界清晰的事，多维度结论用代码按自有公式合并；优先级变化只需改代码系数，不必重写提示词。

三、适用场景

判断类、结果需结构化、且希望带不确定性的环节，都适合用它。

• 请求分流：把服务请求按类型排序路由，概率最低的转人工。
• 审批与风控：规则+模型结合，命中给是/否概率，低置信度进人工复核队列。
• 内容/数据质量打分：对目标给 0–100 评分与置信度，用于过滤与排序。
• 多选项决策：从若干候选中按概率排序，取 Top-K。
• 自托管敏感场景：数据不出域，云端与本地共用同一请求结构。

四、接入流程

整体接入分五步，云端与自托管流程一致：

1. 获取鉴权凭据：在控制台获取 AppCode（或 AppKey/AppSecret）。本文统一采用 AppCode 鉴权，请求头为 Authorization: APPCODE <appcode>。
2. 确认调用路径：接口以 POST 请求，路径为 /v1/systemone（完整调用地址以控制台配置为准），返回 JSON。
3. 构造请求体：填 state + question，按需指定返回形态（是/否、选项、评分）。
4. 调用并解析：读取结构化结果中的概率/置信度字段。
5. 工程化封装：加前置校验、重试、超时、置信度门控与缓存（见第九、十章）。

五、调用示例与返回结构

请求结构

POST，请求体（示例）：

{
   
  "state": "用户近30天有2笔逾期，本次申请提额",
  "question": "是否建议批准提额？",
  "output": "binary"
}

output 取值：binary（是/否）、choice（多选项）、score（评分）。

返回结构（示例）

{
   
  "result": "yes",
  "probability": 0.72,
  "confidence": 0.81,
  "latency_ms": 13
}

• probability / confidence：二分类与评分场景额外返回，可做门控。
• 选项场景返回带概率分布的选项数组，代码按概率排序取 Top-K。

多语言调用示例（Python）

import requests

URL = "/v1/systemone"          # 完整调用地址以控制台为准
APP_CODE = "YOUR_APPCODE"      # 获取入口见控制台

def decide(state: str, question: str, output: str = "binary") -> dict:
    resp = requests.post(
        URL,
        headers={
   "Authorization": f"APPCODE {APP_CODE}", "Content-Type": "application/json"},
        json={
   "state": state, "question": question, "output": output},
        timeout=5,
    )
    resp.raise_for_status()
    return resp.json()

data = decide("用户近30天有2笔逾期，本次申请提额", "是否建议批准提额？")
print(data["result"], data["probability"], data["confidence"])

调用示例（Node.js）

const URL = "/v1/systemone";            // 完整调用地址以控制台为准
const APP_CODE = "YOUR_APPCODE";

async function decide(state, question, output = "binary") {
   
  const resp = await fetch(URL, {
   
    method: "POST",
    headers: {
    Authorization: `APPCODE ${
     APP_CODE}`, "Content-Type": "application/json" },
    body: JSON.stringify({
    state, question, output }),
  });
  if (!resp.ok) throw new Error(`status ${
     resp.status}`);
  return resp.json();
}

调用示例（Java / OkHttp）

String url = "/v1/systemone";              // 完整调用地址以控制台为准
String appCode = "YOUR_APPCODE";
RequestBody body = RequestBody.create(
    MediaType.parse("application/json"),
    "{\"state\":\"用户近30天有2笔逾期\",\"question\":\"是否建议批准提额？\",\"output\":\"binary\"}");
Request req = new Request.Builder()
    .url(url)
    .addHeader("Authorization", "APPCODE " + appCode)
    .post(body)
    .build();
try (Response resp = client.newCall(req).execute()) {
   
    String json = resp.body().string();
    // 解析 result / probability / confidence
}

调用示例（PHP / cURL）

function decide(string $state, string $question, string $output = "binary"): array {
   
    $url = "/v1/systemone";            // 完整调用地址以控制台为准
    $appCode = "YOUR_APPCODE";
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode(["state" => $state, "question" => $question, "output" => $output], JSON_UNESCAPED_UNICODE),
        CURLOPT_HTTPHEADER => ["Authorization: APPCODE " . $appCode, "Content-Type: application/json"],
    ]);
    $out = curl_exec($ch);
    curl_close($ch);
    return json_decode($out, true);
}

六、在线调试实录

在线调试建议先跑通最小用例，再逐步加维度。一个服务请求分流的实录示例：

1. 构造 state：请求正文摘要 + 关键标签。
2. question 设为"该请求应归入哪个类别？"，output 用 choice，候选为「售后 / 售前 / 退款 / 投诉」。
3. 返回带概率分布的选项数组，代码取概率最高的类别，并把 confidence 低于 0.6 的单子转人工。
4. 实测：短判断约 13ms（p50，4B 版），较长的中文输入约 91ms。

调试时重点观察：概率是否可解释、置信度是否稳定、长文本是否超时。

七、调用限制与规范

• 鉴权：统一 Authorization: APPCODE <appcode>；也可用 AppKey/AppSecret 签名认证。
• 方法与格式：POST，Content-Type: application/json，返回 JSON。
• 原子问题：一次只问一件边界清晰的事，多维度结论用代码合并。
• 频控与配额：单账户 QPS 上限、每日配额以控制台实时配置为准；高频调用方建议客户端侧加频控与幂等。
• 合规：涉及个人/敏感数据时做最小必要、传输加密、日志脱敏，用途受限，必要时用户告知；自托管可让数据不出域。

八、能力边界与免责

• 支持：结构化判断（是/否、选项、评分）+ 概率/置信度；云端与自托管两种形态；Jev 格式兼容；MCP 接入。
• 不支持：自由文本生成、多轮长上下文写作、复杂推理链。它是判断引擎，不是写作引擎。
• 边界：置信度是模型输出，不等于真值；概率用于排序/门控，不替代人工最终决策。
• 免责：决策结果仅供参考，调用方对基于该结果做出的业务决策自行负责。

九、错误码与排查

排查思路：先看 HTTP 状态码分类（鉴权/参数/限流/服务），再看响应体；重试只针对幂等的读类判断，写类业务加幂等键。

十、技术 FAQ

Q1：它和自由文本大模型的区别？
A1：它返回带概率的结构化决策（是/否、选项、评分），代码直接消费；不生成自由文本，时延可预测。

Q2：置信度有什么用？
A2：Choice 与 Score 额外返回 confidence，可做门控——低于阈值自动转人工复核，把不确定性显式交给流程。

Q3：能不能私有化部署？
A3：开放权重、可自有 GPU 自托管，数据不出域；云端与本地共用同一套请求结构，迁移成本低。

Q4：存量 Jev 代码怎么接入？
A4：已按 Jev 格式写好的代码，替换 Base URL、API key 与 model 即可，请求结构不变。

Q5：支持 MCP 吗？
A5：提供接口级 MCP 服务，支持 MCP 的客户端可直接配置。

Q6：多维度判断怎么办？
A6：拆成多个原子问题分别提问，再由代码按自有公式合并；改优先级只动代码系数。

Q7：报错无结果怎么排查？
A7：先按 HTTP 状态码分四类（鉴权/参数/限流/服务），再看响应体；读类判断可重试，写类加幂等键。

Q8：适合接在小程序/APP/ERP 里吗？
A8：请求结构标准（POST + JSON），语言无关，可在各端或其后端服务中接入。

十一、内容小结

JevK5 决策型接口把"判断"从文本里抽出来，变成带概率的结构化结果，代码可直接分支、排序、路由。工程上值得关注的三点：

• 拆细问题：原子问题 + 代码合并，比"一个大提示词"更可维护。
• 利用置信度：低置信度转人工，把不确定性交给流程而非硬编码阈值。
• 工程化封装：前置校验、频控幂等、超时重试、结果缓存，敏感场景走自托管。

它是判断引擎而非写作引擎：适合结果需结构化、要带不确定性的场景，不适用自由文本生成。决策结果仅供参考，业务最终决策由调用方负责。