开发者指南

Jev SDK 开发者指南

要在本站接入？请先看托管 API 指南与预付定价。本页解释 Choice / Score / Noul 与背景接入选项——不是创建 jv_live_ 密钥的主路径。

本页是概念层：原语、定价背景与实现注意。针对本站计量接口的可复制示例，见入门指南与托管 API 文档。

如何获取访问

本站最快路径：登录 → 购买预付包 → 创建 jv_live_ 密钥 → POST /api/v1/decide。上游 TypeSafe 密钥留在服务器。官方候补与第三方网关仅在你需要原始 TypeSafe 凭证时使用。

接入选项

本站托管（推荐快速上手）：定价 + 账户 — 预付 token 与 jv_live_ 密钥，用于 /api/v1/decide 与工具。
官方 / 网关备选：typesafe.ai 候补，以及 OpenRouter、Vercel AI Gateway、Cloudflare AI（若你已在这些平台计费）。

重要限制：没有可下载模型文件，无法本地自托管。推理均在云端（本站、TypeSafe 或网关）。

定价说明

输入 token 价格为 每百万 token 0.042 美元。输出 token 完全免费。 按 TypeSafe 公布的价目表，Jev 决策输出不会额外计费。

网关可能在基础模型价之上加收 markup 或使用不同计费单位。估算生产成本前请查阅网关定价页。另见定价常见问题。

Jev 的三个核心原语

Jev 请求由三类原语问题构成。每次请求发送 state（输入上下文或程序数据）以及一组 typed 问题。Jev 返回结构化 typed 结果与校准概率。

Choice: 从预定义选项中择一，常用于 Agent 路由与分类。
Score: 在既定量表或 rubric 上返回数值位置，常用于风险打分与严重度评级。
Noul: 返回是/否判断的概率，常用于审核闸门与简单布尔过滤。

简短定义亦见术语表。

安装与依赖

仅发请求并不强制安装某个官方 npm/pip 包。最小路径是对 System One 端点发起 HTTP POST。Node.js 18+ 可使用内置 fetch。Python 可安装常用的 requests：

终端

pip install requests

若通过 OpenRouter 调用 Jev，请使用该网关文档中的 Decisions API 及其密钥。不要臆造或硬编码包名，例如虚构的 @typesafe/jev-sdk。

env.sh

# Store keys outside source control
export JEV_API_KEY="YOUR_API_KEY"
# Or, when calling through OpenRouter:
# export OPENROUTER_API_KEY="YOUR_OPENROUTER_KEY"

完整最小 API 请求 JSON

下文示例使用的端点：POST https://jevtypesafe.org/api/v1/decide。上线前请对照 TypeSafe 文档确认最新路径与字段名。

request.json

{
  "state": "Customer message: my order has not arrived",
  "questions": {
    "ticket_routing": {
      "type": "choice",
      "options": ["support", "logistics", "billing"]
    },
    "is_urgent": {
      "type": "noul"
    },
    "severity_level": {
      "type": "score",
      "criteria": ["calm", "frustrated", "angry"]
    }
  }
}

可复制 API 示例

以下为使用原生 HTTP 的社区最小示例，并非官方 SDK 封装。请将环境变量替换为候补或网关提供的真实密钥。

Node.js

call-jev.mjs

// Minimal raw API call — hosted decide on this site
// Replace with a jv_live_ key from Account
async function callJev() {
  const apiKey = process.env.JEV_API_KEY;

  const payload = {
    state: "Customer message: my order has not arrived",
    questions: {
      ticket_routing: {
        type: "choice",
        instructions: "Route this ticket",
        criteria: { support: "product help", logistics: "shipping", billing: "payment" },
      },
    },
  };

  const res = await fetch("https://jevtypesafe.org/api/v1/decide", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  if (!res.ok) {
    throw new Error(`Jev request failed: ${res.status}`);
  }

  return res.json();
}

Python

call_jev.py

# Minimal raw API call — hosted decide on this site
# Requires: pip install requests
# Replace with a jv_live_ key from Account
import os
import requests

def call_jev():
    api_key = os.environ["JEV_API_KEY"]
    payload = {
        "state": "Customer message: my order has not arrived",
        "questions": {
            "ticket_routing": {
                "type": "choice",
                "instructions": "Route this ticket",
                "criteria": {"support": "product help", "logistics": "shipping", "billing": "payment"},
            }
        },
    }
    response = requests.post(
        "https://jevtypesafe.org/api/v1/decide",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

SDK 最佳实践

API 密钥放在环境变量中，切勿暴露在前端代码。
对重复决策任务做请求缓存，降低调用次数与成本。
为 transient 网络故障添加重试逻辑。
发送前校验全部输入 schema。
需要自动化时优先使用 Choice / Score / Noul，而非自由文本 prompt。

实现笔记

按决策身份缓存，而非原始 prompt 文本

对问题集与规范化 state 字段做哈希。若两次请求代表同一路由决策，复用先前结果。对审核打分、工具选择等热路径尤其有用。

schema 不匹配时 fail closed

若响应不符合预期决策 schema，不要静默 coerce 到默认分支。记录事件、返回安全回退路由并告警。

生成式 LLM 放在决策门之后

先调用 Jev，路由确定后再调用聊天式模型。示例见生产用例。

来源参考:

TypeSafe AI 官方公告博文