【AI】Jev API 接入实战：用 Python 调用 TypeSafe Jev 做结构化判断

上一篇讲了 Jev 是什么（System One 快速判断模型入门），这篇直接动手：从申请 Key 到写出一个可用的置信度路由，完整走一遍。

一、准备：拿到 API Key

打开 console.typesafe.ai 注册；
在控制台创建 API Key，存进环境变量（不要硬编码进代码）：

bash 复制代码

export TYPESAFE_API_KEY="你的key"

二、最小可运行示例（curl）

一条 curl 就能跑通。这里用 Noul 题型问一个"是/否"判断：

bash 复制代码

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "I was charged twice for my subscription this month. Please refund the extra charge.",
    "questions": {
      "billing": {
        "type": "noul",
        "instructions": "Is this message about billing?"
      }
    }
  }'

json 复制代码

{
  "model": "jev-latest",
  "answers": {
    "billing": { "type": "noul", "noul": 0.98 }
  },
  "usage": { "input_tokens": 120, "output_tokens": 12 }
}

0.98 就是模型认为"是计费问题"的概率------代码可以直接用这个数字做阈值判断，不需要解析任何文本。

三、Python SDK 调用

bash 复制代码

pip install typesafe-sdk

python 复制代码

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

with TypeSafeClient() as client:   # 自动读取 TYPESAFE_API_KEY
    resp = client.system_one(
        state="My running shoes arrived in the wrong size. Can I swap them for a size 10?",
        questions={
            # 1) Choice：从固定选项里选
            "department": Choice(
                instructions="Which team should handle this?",
                criteria={
                    "returns": "Exchanges, wrong or damaged items",
                    "shipping": "Delivery status, delays, lost packages",
                    "billing": "Charges, invoices, payment problems",
                },
            ),
            # 2) Score：按评分档位打分
            "urgency": Score(
                instructions="How urgent is this message?",
                criteria=["Can wait", "Needs attention this week", "Needs attention today"],
            ),
            # 3) Noul：是/否判断
            "wants_refund": Noul(
                instructions="Does the customer ask for a refund?",
            ),
        },
    )

    for name, ans in resp.answers.items():
        print(name, "=>", ans)

三种题型一次请求全部返回，每个答案都是结构化的对象（不是文本）。

四、响应结构详解

Choice（选择）

json 复制代码

{
  "type": "choice",
  "choice": "calm",
  "confidence": 0.7,
  "probabilities": { "angry": 0.15, "calm": 0.8, "excited": 0.05 }
}

choice：选中的选项
probabilities：每个选项的概率（不是只有最高分）
confidence：置信度（与概率是两回事，见下文）

Score（评分）

json 复制代码

{
  "type": "score",
  "score": 1.7,
  "confidence": 0.55,
  "legend": { "0": "Can wait", "1": "Needs attention this week", "2": "Needs attention today" },
  "probabilities": { "0": 0.1, "1": 0.1, "2": 0.8 }
}

score：连续值（落在档位之间，例如 1.7）
legend：档位含义，方便代码映射

Noul（是/否）

json 复制代码

{ "type": "noul", "noul": 0.95 }

返回"陈述为真"的概率（0--1）

usage（计费）

json 复制代码

{ "usage": { "input_tokens": 120, "output_tokens": 12 } }

注意：Jev 按输入 token 计费，输出免费------所以一次请求里塞多个问题，成本几乎不随问题数增加（官方称打包多问题比逐个调用便宜约 12 倍、快约 10 倍）。

五、实战模式：置信度路由

Jev 最有价值的用法，是用 confidence 决定"要不要相信这个判断"：

python 复制代码

from typesafe_sdk import Choice, TypeSafeClient

def route_ticket(text: str):
    with TypeSafeClient() as client:
        resp = client.system_one(
            state=text,
            questions={
                "team": Choice(
                    instructions="Which team should handle this?",
                    criteria={
                        "billing": "Charges, invoices, payment problems",
                        "technical": "Bugs, errors, product not working",
                        "account": "Login, password, account settings",
                    },
                ),
            },
        )

    ans = resp.answers["team"]

    # 置信度低 → 转人工；高 → 自动分发
    if ans.confidence >= 0.8:
        return f"自动派给 {ans.choice} 团队"
    else:
        return f"转人工（模型倾向 {ans.choice}，置信度 {ans.confidence:.2f}）"

这个模式叫 Confidence-gated routing：答案告诉你"是什么"，置信度告诉你"能不能据此行动"。

六、和 LLM 组合使用

两者是互补关系，常见组合：

环节	用什么	理由
用户消息分诊	Jev（Choice）	快、结构化、可路由
生成回复文案	LLM	需要自然语言
回复前安全检查	Jev（Noul/Score）	低延迟、可设阈值
工具调用参数提取	Jev（Choice/Score）	闭集参数、带置信度

一个实用的"守卫"流程：LLM 生成回复 → Jev 用 Noul 判断"是否包含敏感承诺" → 命中就拦截或转人工。

七、成本与限制注意事项

项	说明
计费	只算输入 token（ $42/Btok \approx$ 0.042/M）；输出免费
上下文	默认 64k/请求、32k/问题；超长文本需开长上下文 Header（上限 262k）
输入类型	仅文本（字符串 / JSON / 文本数组）；图片音频暂不支持
模型名	用 `jev-latest` 别名自动跟随最新版；固定版本可用 `jev-1.14.0`
限流与错误	返回 4xx 时看错误体；请求体可压缩（zstd）、支持 HTTP/2

八、常见坑

忘记 model 字段 ：请求体必须带 model（如 jev-latest）；
把 Jev 当 LLM 用：让它"写文案"会失败------它只回答题型定义的问题；
问题 id 是自己起的 ：questions 的 key 任意命名，答案按同名返回，模型看不到 id；
只看最高概率、忽略置信度 ：概率高不代表可信，务必结合 confidence；
一次塞太多问题超过上下文：注意 32k/问题的限制，长文本先裁剪或分片。

结语

Jev 的接入成本很低（一个 endpoint + 三种题型），真正的价值在于把"AI 判断"变成业务代码可以直接 if 的结构化信号。如果你在做一个需要"分诊、审核、路由、打分"的系统，值得花半小时试一下。

📦 AI工具库查看 100+ 个 AI 工具与分类对比，大模型 API 平台见开放平台分类。