把 Jev 接入你的系统

快速开始

先在测试台验证一个判断

从 Playground 开始最容易理解 Jev 的输入与输出。确认问题定义合理后，再创建 API key 接入产品。

1. 1

   打开测试台

   登录后进入 Jev AI 测试台，输入一段真实业务状态。

2. 2

   准备 state

   可以是一段文本、JSON 对象或文本数组；先把判断所需的上下文放在一起。

3. 3

   添加问题

   根据目标选择 choice、score 或 noul，也可以在一次调用中混合使用。

4. 4

   连接到代码

   在工作区创建 API key，通过 SDK 或 REST 请求调用正式接口。

输入

让 state 包含判断所需的上下文

state 是所有问题共同读取的内容。简单场景使用字符串；需要同时参考工单、订单和规则时，使用 JSON 对象更清晰。

当前输入边界：Jev 接受文本、JSON 对象和文本数组，暂不支持图片、音频和视频。

问题类型

用最小问题组合出业务判断

每个 question 最好只问一个具体、边界清晰的问题。多个问题会针对同一份 state 并行评估，不需要为了拆分判断而串联多次请求。

{
  "type": "noul",
  "instructions": "这个消息是否表达了紧迫性？",
  "criteria": {
    "true": "明确表示需要立即处理",
    "false": "没有表达紧迫性"
  }
}

"instructions": {
  "potential_duplicate": {
    "name": "John Smith",
    "location": "Oakland, California",
    "last_employer": "Google"
  },
  "question": "这份简历是否属于与 `potential_duplicate` 相同的人？"
}

{
  "state": "救命！我的付款已经连续 3 天失败了。",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "哪个团队应该处理这个请求？",
      "criteria": {
        "billing": "付款、发票、退款",
        "technical": "错误、故障、集成",
        "sales": "定价、升级、新账号"
      }
    }
  }
}

{
  "state": "救命！我的付款已经连续 3 天失败了。",
  "model": "jev-latest",
  "questions": {
    "frustration": {
      "type": "score",
      "instructions": "客户有多沮丧？",
      "criteria": ["平静", "不满", "非常愤怒"]
    }
  }
}

{
  "state": "救命！我的付款已经连续 3 天失败了。",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "这是否表达了紧迫性？",
      "criteria": {
        "true": "明确表示需要立即处理",
        "false": "没有表达紧迫性"
      }
    }
  }
}

输出

响应为代码准备了什么

result.answers 会沿用你发送的 question ID。类型化输出保证字段形状，但业务系统仍应根据风险设置阈值，并在必要时保留人工复核。

• answers： Choice 返回选择、概率和 confidence；Score 返回 score、legend、各等级概率和 confidence；Noul 返回 noul。
• usage： 包含 input_tokens 和 output_tokens，部分响应还会提供美元计价的 cost。
• elapsedMs： 从发送请求到收到结果的耗时，包含校验，不等同于纯模型推理时间。

概率与置信度是自动化决策的信号，不是业务正确率的保证。高风险动作应设置更高阈值或转人工。

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 296, "output_tokens": 20 }
}

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 },
      "confidence": 0.81
    }
  },
  "usage": { "input_tokens": 318, "output_tokens": 34 }
}

{
  "model": "jev-1.13.0",
  "answers": {
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
      "probabilities": { "0": 0.0, "1": 0.95, "2": 0.05 },
      "confidence": 0.92
    }
  },
  "usage": { "input_tokens": 304, "output_tokens": 18 }
}

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 307, "output_tokens": 20 }
}

API 参考

评估 state，返回结构化 answers

完整 HTTP API 参考：对一份 state 和一组 typed questions 进行评估，并按每个问题返回结构化答案。

Authorization: Bearer <API_KEY>
Content-Type: application/json

curl -X POST https://bestjevai.com/v1/systemone \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "救命！我的付款已经连续 3 天失败了。",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "这是否表达了紧迫性？"
      }
    }
  }'

{
  "state": "救命！我的付款已经连续 3 天失败了。",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "这是否表达了紧迫性？"
    }
  }
}

请把 API key 保存在服务端环境变量中，不要写入浏览器代码或提交到版本库。请求字段、问题类型、响应结构、错误码和重试方式已在本页列出。

Agent 使用

在编码 Agent 中使用 Jev

Jev Agent Skill 会教会 Codex、Claude Code、Cursor 等兼容 Agent 如何调用这个 API 做边界清晰的判断，同时把执行权和权限留在你的应用中。

npx skills add jev-ai/jev-agent-skill

export JEV_API_KEY="sk_your_key_here"
export JEV_LANGUAGE="zh-CN"

使用 Jev Agent skill。请把这张客服工单准确分类到 billing、technical、account 或 sales 其中一个团队。返回选择结果、概率和 confidence。暂时不要联系客户，也不要修改工单。

工单：我的年度套餐被重复扣款了，我需要退款。

使用 Jev Agent skill，在执行下面的工具调用前判断是否可以不经过人工批准。考虑副作用、可逆性、范围和政策。如果有风险或不确定，不要执行。

工具：delete_customer_records
参数：{where: last_login < 2023-01-01}
政策：破坏性数据库操作必须先备份并获得人工批准。

使用 Jev Agent skill 为这个任务选择一个已批准的模型。优先考虑质量，再考虑上下文容量和成本。返回选择结果、概率，以及是否需要升级。暂时不要调用任何模型。

任务：审查一份 100k token 的客户争议。
候选：fast-model（32k、低成本）、reasoning-model（200k、高成本）、fallback-model（128k、中等成本）。

使用 Jev Agent skill 判断下面的证据是否足以发布这个主张。考虑来源质量、时效性、直接支持程度和矛盾证据。返回 yes 概率以及还缺少的验证工作。暂时不要发布。

主张：我们的 API 将处理耗时中位数降低了 40%。
证据：上月对 120 个案例做的内部基准测试；没有生产流量数据；一份旧报告显示提升了 12%。

使用 Jev Agent skill 检查这个任务是否真的完成。返回 complete、verify_more 或 incomplete 之一。考虑目标、修改的文件、运行的测试、已知缺口，以及是否在目标环境验证过。

目标：为生产接口增加 API key 鉴权。
已完成：增加了 Authorization 检查和 API key 查询。
验证：单元测试通过；生产请求和限流行为尚未测试。

错误处理

错误码与重试

接口使用标准 HTTP 状态码，并在 JSON 响应中说明错误原因。

收到 429 或 529 时，请使用指数退避重试，不要立即连续发送相同请求。使用 SDK 默认重试策略时，这些重试通常会由 SDK 自动处理。