工程化 / Jev

2. 准备环境并完成第一次Jev调用

本篇目录 · 15 节

来源：Jev

预计阅读时间：30～40 分钟
本篇目标：在 Playground 中完成一次判断，随后用 Python SDK 发起真实 API 请求，并通过代码确认返回值的类型和范围正确。

上一篇把 Jev 理解成一个“能做模糊语义判断的函数”。这一篇不继续讲概念，我们直接把这个函数调用起来。

你会先使用 Playground，确认自己的账号已经获得访问权限；然后建立一个干净的 Python 项目，安全地配置 API Key，运行 first_call.py。完成后，电脑里会留下后续 Decision Inbox 可以直接使用的项目目录。

本文核对日期为 2026 年 9 月 23 日。Jev 刚刚发布不久，账号开放范围、控制台界面和 SDK 可能继续变化。遇到差异时，以 TypeSafe Quick Start 和 Python SDK 文档为准。

一、开始前准备什么

本篇需要：

一个可以登录 TypeSafe 控制台的账号；
一枚 TypeSafe API Key；
可以访问 api.typesafe.ai 的网络；
Python 3.10 或更高版本；
一个代码编辑器和终端。

先检查 Python。

macOS 或 Linux：

python3 --version

Windows PowerShell：

py --version

看到 Python 3.10 或更高版本即可继续。如果系统提示找不到命令，先从 Python 官网安装当前受支持版本。Windows 安装时注意勾选将 Python 加入 PATH；如果 python 指向 Microsoft Store，但 py 可以正常显示版本，后面使用 py 即可。

二、先在 Playground 里验证账号

先用网页验证有两个好处：不需要区分操作系统，也能把“账号没有访问权限”和“本地代码写错了”分开。

打开 TypeSafe Playground。
登录账号。
在页面中找到用于填写 state 的区域。
输入下面这段状态：

I was charged twice for the same monthly subscription. Please help me check it today.

新增一个 Noul 问题，问题内容填写：

Does this message express urgency?

运行判断。

你应该看到一个 0 到 1 之间的结果。数值越接近 1，表示模型越倾向于判断“这条消息表达了紧迫性”。具体数字可能随模型版本变化，不要把教程截图里的某个小数当作固定答案。

这一步的成功标准只有三个：

页面确实返回了结果，而不是登录或权限错误；
返回值是一个概率，不是一段聊天回复；
你能在页面上分清 state 与问题。

如果控制台没有创建 API Key 的入口，或账号提示尚无访问权限，就暂时无法完成真实 API 调用。可以先阅读后续结构，但不要伪造调用结果。账号开放方式和控制台入口可能继续调整，以官方页面为准。

三、创建课程项目目录

不要把练习脚本随手放进桌面，也不要安装到系统 Python。我们建立一个独立目录和虚拟环境。

macOS 或 Linux：

mkdir -p ~/jev-course/decision-inbox
cd ~/jev-course/decision-inbox
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install typesafe-sdk

Windows PowerShell：

New-Item -ItemType Directory -Force "$HOME\jev-course\decision-inbox"
Set-Location "$HOME\jev-course\decision-inbox"
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install typesafe-sdk

Windows 示例故意不要求激活虚拟环境，而是直接调用 .venv 中的 Python。这样即使 PowerShell 的脚本执行策略阻止 Activate.ps1，你也能继续学习。

安装完成后验证 SDK。

macOS 或 Linux：

python -c "import typesafe_sdk; print('typesafe-sdk ready')"

Windows PowerShell：

.\.venv\Scripts\python.exe -c "import typesafe_sdk; print('typesafe-sdk ready')"

期望看到：

typesafe-sdk ready

如果出现 ModuleNotFoundError，通常不是包名错了，而是运行脚本的 Python 与安装 SDK 的 Python 不是同一个。重新执行上面的显式路径命令，不要急着在系统环境里反复安装。

四、创建并保管 API Key

在 TypeSafe 控制台中进入 API Key 或开发者凭据区域，创建一枚用于课程练习的 Key。控制台的具体导航名称可能变化，但它应与 Playground 位于同一账号空间。

Key 放入当前终端环境后，会被其启动的子进程继承。以下交互输入避免把真实值写入命令历史；不要将 Key 粘到 Agent 对话。

macOS 或 Linux：

# bash/zsh 均可；输入不回显
printf 'API Key: '
stty -echo
IFS= read -r TYPESAFE_API_KEY
stty echo
printf '\n'
export TYPESAFE_API_KEY

Windows PowerShell：

$secret = Read-Host "输入 API Key" -AsSecureString
$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secret)
try { $env:TYPESAFE_API_KEY = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr) }
finally { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr); Remove-Variable secret,ptr }

这两种设置在关闭终端后都会失效，适合第一次练习。不要把真实 Key 写进 first_call.py、README、截图或 Git 仓库。

检查变量是否存在时，不要完整打印 Key。macOS 或 Linux 可以看字符数量：

python -c "import os; print('key loaded:', bool(os.getenv('TYPESAFE_API_KEY')))"

Windows PowerShell：

.\.venv\Scripts\python.exe -c "import os; print('key loaded:', bool(os.getenv('TYPESAFE_API_KEY')))"

期望看到：

key loaded: True

它只能证明环境变量存在，不能证明 Key 有效。真正的认证验证要靠下一步 API 调用。

五、写下第一段调用代码

在 decision-inbox 目录中新建 first_call.py，写入下面的内容：

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient


state = {
    "message": (
        "I was charged twice for the same monthly subscription. "
        "Please help me check it today."
    )
}

questions = {
    "category": Choice(
        instructions="What is the main topic of `message`?",
        criteria={
            "billing": "Charges, invoices, payments, or refunds.",
            "technical": "A product feature is broken or unavailable.",
            "account": "Login, profile, or account access.",
            "other": "None of the other options fits.",
        },
    ),
    "urgency": Score(
        instructions="How urgent is the situation described in `message`?",
        criteria=[
            "No time pressure is expressed.",
            "The user would like a reasonably prompt response.",
            "The user describes immediate harm or a strict deadline.",
        ],
    ),
    "refund_requested": Noul(
        instructions="Does `message` explicitly request a refund?",
    ),
}

with TypeSafeClient() as client:
    response = client.system_one(
        state=state,
        questions=questions,
    )

category = response.answers["category"]
urgency = response.answers["urgency"]
refund_requested = response.answers["refund_requested"]

print("category:", category.choice)
print("category probabilities:", category.probabilities)
print("category confidence:", category.confidence)
print("urgency score:", urgency.score)
print("urgency confidence:", urgency.confidence)
print("refund requested probability:", refund_requested.noul)

# 这些断言检查返回值能否被程序安全消费，
# 不负责断言模型对这条消息的语义判断一定正确。
assert category.choice in {"billing", "technical", "account", "other"}
assert 0 <= urgency.score <= 2
assert 0 <= refund_requested.noul <= 1

print("response shape verified")

这段代码做了三件不同的事：

Choice 从四个类别里选择一个；
Score 在三个有顺序的紧急程度等级之间评分；
Noul 判断留言是否明确要求退款。

所有问题都看见同一份 state，但分别独立判断。代码随后读取结构化字段，而不是解析一段模型生成的 JSON 字符串。

代码没有显式写模型名称。按当前官方 Quick Start，Python SDK 默认使用 jev-latest。别把教程写作时对应的具体版本号硬编码进第一次练习；如果以后需要稳定复现，再根据当时的官方 Models 文档决定是否固定版本。

六、运行并读懂结果

macOS 或 Linux：

python first_call.py

Windows PowerShell：

.\.venv\Scripts\python.exe first_call.py

实际数字会变化，输出形状大致如下：

category: billing
category probabilities: {'billing': ..., 'technical': ..., 'account': ..., 'other': ...}
category confidence: ...
urgency score: ...
urgency confidence: ...
refund requested probability: ...
response shape verified

不要只看 category: billing。至少观察三件事：

probabilities 是否包含你定义的全部类别；
urgency.score 是否落在 0 到 2 的范围内；
“请帮我核对”是否真的等于“明确要求退款”。

第三点没有唯一标准答案，它提醒我们：模型返回概率后，业务代码仍然需要决定多大概率才算“明确”，以及判断不清时是不是应该追问。

最后的 response shape verified 是一次独立的程序检查。它不能证明语义判断正确，但证明了返回值满足我们准备让代码消费的基本范围。

七、做一次对照实验

把 state 中的留言改成：

state = {
    "message": "Please refund the duplicate charge today."
}

再次运行脚本，比较 refund_requested.noul。我们期望它比“请帮我核对”的版本更接近肯定判断。

接着换成中文：

state = {
    "message": "同一份月度会员被扣了两次，请今天退回重复扣款。"
}

记录结果，但不要用这一个例子宣布“中文表现很好”或“中文不能用”。官方当前的 Models 文档说明英语是主要训练语言，也是准确率最好的语言，其他语言需要用自己的内容验证。一个样本只能帮助你确认接口接受中文；第七篇会用多条人工标注数据评估实际表现。

八、最常见的几个失败

`TYPESAFE_API_KEY` 未设置

如果提示缺少凭据，先重新运行本篇第四节的布尔检查。注意：在一个终端里设置的变量，不会自动出现在另一个已经打开的终端窗口中。

401 或 403

这通常表示 Key 无效、已撤销，或账号尚未获得对应访问权限。回到控制台检查，不要通过反复改代码绕过认证错误。

`ModuleNotFoundError: typesafe_sdk`

确认安装命令与运行命令使用同一个虚拟环境。Windows 优先使用 .venv\Scripts\python.exe 的完整相对路径；macOS 和 Linux 确认命令行前面是否出现 (.venv)。

网络超时或无法连接

先用 Playground 判断是不是本地网络问题。如果网页可用而 Python 不可用，再检查代理、公司网络策略和本机证书。不要把代理账号或证书内容复制进公开求助信息。

示例属性不存在

Jev 和 SDK 仍然很新。如果官方 SDK 更新导致 response.answers[...] 等访问方式变化，先查看当前 Python SDK 文档和安装版本，而不是同时尝试多个社区示例。可以查看当前安装版本：

python -m pip show typesafe-sdk

Windows 将 python 替换成 .\.venv\Scripts\python.exe。

九、结束练习后的 Key 处理

如果暂时不继续下一篇，可以清除当前终端中的环境变量。

macOS 或 Linux：

unset TYPESAFE_API_KEY

Windows PowerShell：

Remove-Item Env:TYPESAFE_API_KEY

后续练习仍可以在每次打开终端后临时设置环境变量。真实项目若改用系统密钥链、部署平台的 Secret 或本地 .env，原则也不变：Key 不进入源码，不写入教程数据，也不提交到 Git。

本篇验收

完成本篇后，项目目录里至少应该有：

decision-inbox/
├── .venv/
└── first_call.py

同时确认：

Playground 可以返回一次真实判断；
SDK 已安装在项目虚拟环境中；
API Key 从环境变量读取；
first_call.py 可以运行到 response shape verified；
你知道“返回结构正确”不等于“语义判断正确”；
真实 Key 没有写进脚本。

下一篇会专门拆开 Choice、Score 和 Noul。我们不只看它们返回什么，还要学习怎样设计互不重叠的选项、可解释的等级和真正清楚的是非问题。

unset TYPESAFE_API_KEY／移除 env 变量只清理当前进程环境，不会清除历史，也无法撤回已被子进程读取的值。若此前直接写入过真实 Key，应按控制台流程撤销并重新创建。

一、开始前准备什么

二、先在 Playground 里验证账号

三、创建课程项目目录

四、创建并保管 API Key

五、写下第一段调用代码

六、运行并读懂结果

七、做一次对照实验

八、最常见的几个失败

TYPESAFE_API_KEY 未设置

401 或 403

ModuleNotFoundError: typesafe_sdk

网络超时或无法连接

示例属性不存在

九、结束练习后的 Key 处理

本篇验收

`TYPESAFE_API_KEY` 未设置

`ModuleNotFoundError: typesafe_sdk`