Jev AI API 教程：用 Choice、Score、Noul 构建第一个结构化决策

如果你已经在 Jev AI Playground 里体验过模型，下一步通常是把一个真实判断接入服务端：接收工单或用户消息，定义需要回答的问题，读取概率与置信度，再由代码决定路由、排队或人工复核。

Jev AI API 的核心不是一条“聊天式”请求，而是三个清晰的输入：State、Model、Questions。State 描述上下文，Questions 描述判断，响应则以问题 ID 返回类型化结果。这样可以把 AI 判断嵌入现有函数、队列和 Agent 工作流，而不是再增加一个聊天窗口。

本文是一份从零开始的 API 教程，覆盖请求结构、Choice/Score/Noul 的选择、最小 curl 示例、结果处理、错误边界和生产上线清单。

教程目标： 完成一个低风险的支持工单判断，并让服务端根据结果决定是否自动路由或请求人工处理。

目录

• 先理解 Jev API 的请求模型
• State：给问题提供上下文
• Questions：选择 Choice、Score 还是 Noul
• 调用第一个 Jev API 请求
• 如何读取和处理响应
• 把结果接回业务代码
• 生产环境上线清单
• 常见问题

先理解 Jev API 的请求模型

图：State 提供上下文，Questions 说明判断，结构化结果回到你的服务。

Jev API 的基本思路可以写成：

state + model + questions
            ↓
typed answers + probabilities + confidence
            ↓
your application logic

官网当前文档使用 POST https://thejevai.com/v1/systemone 作为生产请求入口。一个请求包含三项核心字段：

• state：字符串、JSON 对象或文本数组；
• model：当前使用的模型名称，例如 typesafe/jev-1.13；
• questions：按业务问题 ID 组织的类型化问题。

Jev 只负责对问题做判断，应用仍然负责鉴权、输入清洗、阈值、重试、日志和最终动作。想了解整体定位，可以先阅读 Jev AI 介绍文章。

State：给问题提供上下文

使用字符串处理简单场景

当所有判断都围绕一条消息展开时，字符串是最简单的 State：

{
  "state": "The customer has tried to connect Stripe for three days."
}

适合客服消息、告警内容、表单描述、用户反馈和短文本工单。

使用 JSON 对象保存结构化上下文

当一个判断需要同时读取工单、订单和政策信息时，可以把它们放在对象中：

{
  "ticket": {
    "text": "The customer has tried to connect Stripe for three days.",
    "channel": "email"
  },
  "customer": {
    "plan": "pro",
    "days_open": 3
  },
  "policy": {
    "same_day_escalation": true
  }
}

对象可以让问题共享更多事实，但不代表应该把所有系统数据都发送出去。只提供完成判断所需的最小上下文，并在服务端先移除密钥、支付信息和不必要的个人数据。

使用文本数组拼接相关信息

多条消息、检索片段或对话摘要可以作为文本数组输入。数组中的每一项都应该与当前判断直接相关，避免把无关材料混入 State 后再期待模型自动忽略。

当前官网文档明确说明，Jev 接受文本、JSON 对象和文本数组；图片、音频、视频暂不支持直接输入。如果你的业务需要处理多媒体，应先在应用侧完成转写、OCR 或分类。

Questions：选择 Choice、Score 还是 Noul

图：问题类型决定返回结果的形状，也决定它如何进入业务控制流。

问题类型	适用问题	主要结果	典型后续动作
Choice	从候选项中选一个	choice、probabilities、confidence	路由、分类、模型选择
Score	按有序标准打分	score、legend、probabilities、confidence	排序、优先级、SLA
Noul	判断一个陈述是否为真	noul（yes 概率）	拦截、确认、升级

Choice：分类和路由

当答案可以列出时使用 Choice。例如支持团队、内容分类、任务类型和模型等级。为未知情况保留 other 或 none-of-the-above，不要让系统被迫从不匹配的选项中选择。

Score：连续或有序评价

当问题是严重程度、满意度、紧急程度或风险等级时使用 Score。等级必须从低到高排列，并且每个等级有明确说明。不要只提供“低、中、高”三个模糊词，要描述每个等级会触发什么业务动作。

Noul：单一真假判断

当问题可以改写成“这个陈述是否成立？”时使用 Noul，例如“客户是否明确要求退款？”“这个工具调用是否需要人工确认？”Noul 返回 yes 概率，不应被误解为另一个 confidence 字段。

TypeSafe 官方文档强调，问题应该保持原子化。与其让一个问题同时判断部门、优先级和风险，不如拆成多个问题，再由代码组合。

调用第一个 Jev API 请求

图：先验证一个小而明确的请求，再逐步扩展到多个问题。

准备 API Key

API Key 必须保存在服务端环境变量中，例如：

export JEV_API_KEY="your-server-side-key"

不要把真实密钥粘贴到前端、客户端脚本、公开文章或 Git 仓库。线上创建和管理密钥时，参考 Jev AI API 文档。

最小化 Noul 请求

下面的请求示例采用官网文档当前给出的字段形状：

curl -X POST https://thejevai.com/v1/systemone \
  -H "Authorization: Bearer $JEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-1.13",
    "state": "A customer has tried to connect Stripe for three days.",
    "questions": {
      "urgent": {
        "type": "noul",
        "instructions": "Does this message express urgency?"
      }
    }
  }'

从 Playground 复制请求形状

如果你还不确定 Choice 或 Score 的完整 JSON 字段，最稳妥的流程是：先在 Playground 定义一个问题，运行结果，再使用页面提供的 API request preview 查看请求形状。这样可以避免根据旧示例猜测字段名。

如何读取和处理响应

图：结果先经过结构校验和阈值判断，再进入自动化或人工路径。

按问题 ID 读取答案

响应中的 answers 使用你发送的问题 ID。概念上可以理解为：

{
  "answers": {
    "urgent": {
      "noul": 0.87
    }
  },
  "usage": {
    "input_tokens": 42,
    "output_tokens": 0
  },
  "elapsedMs": 214
}

上面的响应是结构示意，不是完整 API Schema。请以 官方 API reference 为准处理字段、错误和版本变化。

把概率当作信号，而不是结论

可以根据风险设置不同阈值：

• 低风险工单：urgent > 0.8 可以进入自动队列；
• 中风险动作：0.6–0.8 进入抽样或二次判断；
• 高风险动作：即使概率很高，也先经过权限、规则和人工确认。

阈值不是 Jev API 的默认答案，而是你自己的业务策略。要用真实历史数据和反例集校准它。

处理错误和超时

生产客户端至少需要处理：HTTP 非 2xx、请求超时、响应字段缺失、未知选项、模型版本变化和重复提交。重试需要幂等策略，不要因为一次网络失败就重复执行付款、删除或权限修改。

把结果接回业务代码

示例：工单优先级流程

result = jev.system_one(
    model="typesafe/jev-1.13",
    state=ticket,
    questions={
        "needs_human": {
            "type": "noul",
            "instructions": "Does this ticket require a human review?"
        }
    },
)

if result.answers["needs_human"].noul >= 0.85:
    queue_for_review(ticket)
else:
    route_automatically(ticket)

示例展示的是控制流思想。具体 Python SDK、JavaScript SDK 或 REST 字段，请使用当前官方文档和 Playground 导出的请求作为事实来源。

多问题请求的设计原则

同一份 State 可以支持多个问题，例如：

• department：使用 Choice 选择处理团队；
• urgency：使用 Score 评估优先级；
• needs_human：使用 Noul 判断是否需要人工。

每个问题只描述一个判断，业务动作再由代码组合。这样当部门路由规则变化时，不必同时修改紧急程度和人工复核问题。

生产环境上线清单

上线前逐项确认：

1. API Key 只存在于服务端环境变量或密钥管理器；
2. State 已做长度限制、敏感信息处理和权限检查；
3. 每个问题都有明确 ID、答案空间和说明；
4. 响应会校验 HTTP 状态和字段结构；
5. 概率阈值按风险级别配置，而不是写死一个全局数字；
6. 高风险动作保留硬规则、授权校验和人工复核；
7. 记录模型版本、问题定义、输入摘要和最终动作；
8. 有超时、重试、降级和人工接管路径；
9. 使用真实数据集测试中文、专业术语和边界案例；
10. 以 Jev AI 价格页 和最新 API 文档核对用量与方案。

如果你还在进行技术选型，可以阅读 Jev AI vs LLM 对比；如果要把 API 放进 Agent，则可以继续看 Jev AI Agent 安全实践。

常见问题

Jev AI API 是聊天接口吗？

不是。它接收 State 和类型化问题，返回应用可以读取的结构化答案。它可以成为聊天系统或 Agent 内部的决策节点，但本身不是为了生成聊天段落。

一次请求可以问多个问题吗？

可以。官网和 TypeSafe 文档都强调，多个问题可以围绕同一份 State 评估。问题应保持独立、清晰，并使用稳定的 ID。

Noul 的值是不是 confidence？

不是。Noul 表示“答案为 yes 的概率”；Choice 和 Score 才会返回相应的 probability 与 confidence 字段。具体响应字段要以当前 API 文档为准。

Jev API 支持图片吗？

当前官网文档列出的 State 输入是文本、JSON 对象和文本数组，图片、音频和视频不支持直接输入。可以先在应用侧做 OCR、转写或其他预处理。

如何判断 API 是否适合我的产品？

从一个低风险、可衡量、答案空间清晰的判断开始。先在 Playground 验证，再做服务端集成和历史数据评估。

结语

Jev AI API 的关键不是调用一次模型，而是把“状态、问题、结果、动作”四个部分拆清楚。State 负责事实，Choice/Score/Noul 负责判断，概率和置信度负责暴露不确定性，业务代码负责最终行动。

当这条链路被清晰地记录、测试和监控之后，Jev AI 才真正从 Playground 里的演示变成你产品中的可维护决策组件。

资料核验日期： 2026-09-20

主要资料： Jev AI 官网、Jev AI Docs、Jev AI Playground、TypeSafe 官方介绍