# Jev API：判断模型的接入方式、问题设计、场景示例与常见报错

Source: https://ofox.ai/zh/docs/develop/models/jev

TypeSafe Jev 是一个**判断模型**，不生成文本，只回答预先定义的问题。请求中提供待判断的内容和一组问题，模型为每个问题返回结构化答案及其概率，程序可直接依据结果执行分支逻辑。

- [快速开始](#quickstart) — 准备接入信息，完成第一次调用。
- [问题设计](https://ofox.ai/zh/docs/develop/models/jev/writing) — 选项设计与返回结果说明，避免常见误判。
- [上线准备](https://ofox.ai/zh/docs/develop/models/jev/production) — 置信度阈值、成本与输入限制。
- [场景示例](https://ofox.ai/zh/docs/develop/models/jev/scenarios) — 工单分流、内容审核、RAG 筛选、结构化判断。
- [项目接入](https://ofox.ai/zh/docs/develop/models/jev/assistant) — 通过编程助手接入，或从 TypeSafe 迁移。
- [常见报错](#errors) — 报错信息与结果异常的原因及处理方法。

## 适用场景

**要点**:需要程序依据判断结果执行不同逻辑时，使用 Jev；需要生成供人阅读的文本时，使用对话大模型。

**适用于**：

- 分类与分流：工单归属的处理团队、用户意图类别。
- 是非判断：是否包含个人信息、是否为退款申请、是否为提示词注入。
- 评分与排序：紧急程度、相关度、情绪强度，以及检索结果筛选。
- 大模型输出质检：回答是否切题、是否违规。

**不适用于**：

- 生成文本、摘要、翻译或代码。
- 图片判断（Jev 仅支持文本和 JSON 输入，图片判断请使用 [GPT-6 Luna](https://ofox.ai/zh/docs/develop/models/gpt-6-luna)）。
- 答案无法预先列为选项或级别的开放式问题。

与「对话大模型 + JSON 输出」的对比：

| | Jev | 对话大模型 + JSON 输出 |
|---|---|---|
| 返回内容 | 仅限预先给定的选项或级别 | 可能返回选项以外的值，需要额外校验 |
| 不确定性 | 每个答案附带概率，choice 与 score 另附置信度 | 通常不提供可用的概率 |
| 多个问题 | 单次请求同时回答，共享同一份输入 | 需合并到同一提示词，或分多次调用 |
| 计费 | 只按输入 token 计费，输出不计费 | 输入、输出都按对话模型价格计费 |

## 快速开始
**1. 准备接入信息**：在 [OfoxAI 控制台](https://app.ofox.ai/manage/api-keys)创建 API Key，并使用以下信息：

**接入信息**

- Base URL: `https://api.ofox.ai/v1`
- 模型 ID: `typesafe/jev-latest` — 也可写作 jev-latest
- 接口路径: `/v1/decisions` — POST；不适用 /v1/chat/completions

**2. 安装 SDK**：使用 OpenAI 官方 Python SDK 调用时，需安装包含 `client.decisions` 的版本：

```bash filename="Terminal"
pip install -U openai
```

**注意**:如运行时出现 `AttributeError: 'OpenAI' object has no attribute 'decisions'`，表示 SDK 版本过旧，执行上述命令升级即可（实测 `openai` 3.31.0 可用）。不使用 SDK 时，也可通过下方 cURL 调用。

**3. 发起调用**：

**Python**

```python filename="quickstart.py"
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.ofox.ai/v1", api_key=os.environ["OFOX_API_KEY"])

r = client.decisions.create(
    model="typesafe/jev-latest",
    input="客户留言：我被重复扣款了，两封邮件都没人回，今天必须退款。",
    questions=[{"type": "predicate", "name": "is_frustrated", "instructions": "客户是否不满？"}],
)
print(r.answers[0].probability)  # 0.98
```

**cURL**

```bash filename="Terminal"
curl https://api.ofox.ai/v1/decisions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-latest",
    "input": "客户留言：我被重复扣款了，两封邮件都没人回，今天必须退款。",
    "questions": [
      { "type": "predicate", "name": "is_frustrated", "instructions": "客户是否不满？" }
    ]
  }'
```

响应示例：

```json
{
  "model": "typesafe/jev-latest",
  "answers": [{ "type": "predicate", "name": "is_frustrated", "probability": 0.98 }],
  "usage": { "prompt_tokens": 302, "completion_tokens": 23, "total_tokens": 325 }
}
```

`probability` 表示答案为「是」的概率，0.98 即模型判断客户不满的可能性极高。将 `input` 替换为实际内容、`questions` 替换为实际问题，即可用于自己的业务场景。

## 问题类型
根据所需的结果形式选择问题类型：

| 所需结果 | 问题类型 | 需提供的字段 | 返回字段 |
|---|---|---|---|
| 是或否 | `predicate` | 问题；可选 `criteria` 说明「是」「否」各指什么 | `probability`：为「是」的概率 |
| 在多个选项中选择一个 | `choice` | `choices`：2–255 个选项 | `choice`、每个选项的概率、`confidence` |
| 程度高低 | `score` | `levels`：2–10 个从低到高的级别 | `score`、每级概率、`confidence` |

示例：「是否为退款申请」使用 predicate；「应由哪个团队处理」使用 choice；「紧急程度如何」使用 score。三个问题可放在同一请求中，一次返回全部答案。

确定问题类型后，请参照[问题设计](https://ofox.ai/zh/docs/develop/models/jev/writing)检查问题与选项。

## 常见报错
| 现象 | 原因 | 处理方法 |
|---|---|---|
| `AttributeError: 'OpenAI' object has no attribute 'decisions'` | OpenAI SDK 版本过旧 | 执行 `pip install -U openai` 后重试 |
| 400 `endpoint_not_supported`，提示 `Please use /v1/decisions instead` | 将 Jev 作为对话模型调用了 `/v1/chat/completions` | 改为调用 `/v1/decisions` |
| 400 `Invalid request payload` | 在 `/v1/decisions` 上使用了 TypeSafe 原生格式（`state`、对象形式的 `questions`） | 改用 `input` 与数组形式的 `questions`，或改为调用 `/typesafe/v1/systemone` |
| 400 `questions are required for decision` | `questions` 为空 | 至少提供一个问题 |
| 400 `question "a" has kind choice and requires criteria options` | choice 问题缺少 `choices` | 补充选项 |
| 400 `Too many score levels. Must have at most 10 levels.` | score 超过 10 级 | 合并级别 |
| 400 `max_tokens_exceeded` | 输入超过 64K token | 拆分长文档，或仅传入相关部分 |
| 400，报错信息包含 `input_image` 与 `Typesafe cannot read` | 向 Jev 传入了图片 | 移除图片，或改用支持图片的模型 |
| 404 `model_not_found` | 模型 ID 有误 | 使用 `typesafe/jev-latest` |
| 请求成功，但答案明显错误且置信度较高 | choice 的选项未覆盖实际情况 | 增加「以上都不是」选项并补充选项描述，参见[问题设计](https://ofox.ai/zh/docs/develop/models/jev/writing) |
| 答案中缺少 `name`，无法与问题对应 | 问题未设置 `name` | 为每个问题设置 `name` |

完整报错列表见 [Decisions API · 常见报错](https://ofox.ai/zh/docs/api/decisions#errors)。

## 官方文档
- [TypeSafe · 文档](https://docs.typesafe.ai/)
- [TypeSafe · 使用场景示例](https://docs.typesafe.ai/cookbooks)

## 常见问题

**Jev 和用大模型输出 JSON 有什么区别？**

Jev 仅在给定的选项和级别内作答，不会返回范围外的值；每个答案附带概率，choice 与 score 另附置信度，可直接用于设置阈值。大模型输出 JSON 需要额外校验，通常也不提供可用的概率。

**/v1/decisions 和 /typesafe/v1/systemone 该用哪个？**

新项目建议使用 /v1/decisions，可直接通过 OpenAI SDK 调用。已使用 TypeSafe SDK 或其官方示例代码的项目，可使用 /typesafe/v1/systemone，仅需修改 base URL。

**Jev 如何计费？**

仅按输入 token 计费，输出不计费，单价见模型页。同一请求中的多个问题共享同一份输入，因此将问题合并到一次请求中可降低成本。

**置信度高是否意味着答案一定正确？**

不一定。选项未覆盖实际情况时，模型仍会从已有选项中选择一个，且置信度可能较高。因此 choice 问题应设置「以上都不是」等兜底选项，并使用人工标注样本进行验证。

**score 返回 1.43 表示什么？**

score 是按各级概率加权计算的值，级别从 0 开始编号。1.43 表示介于第 1 级与第 2 级之间、更接近第 1 级；各级的具体概率见 probabilities。

**是否支持中文内容？**

支持。内容与问题均可使用中文，也可内容使用中文、问题使用英文。

**Jev 是否支持图片？**

不支持，Jev 仅接受文本和 JSON。需要对图片进行判断时，可改用支持图片输入的 GPT-6 Luna（openai/gpt-6-luna），请求格式相同。