第一次使用：从离线演示到真实判断

这一章的完成标准很小：你知道自己运行的是离线演示还是真实请求，能找到一个问题对应的返回值，并能解释输入里哪句话支持这个判断。先不要批量处理文件，也不要把结果接入会自动执行动作的业务系统。

第一步：运行不需要账号的案例

下载并解压本书配套代码，打开终端，进入包含 examples 文件夹的项目根目录。下面的 path/to/hello-jev 是占位路径，请换成你实际解压的位置。

macOS 或 Linux：

cd path/to/hello-jev
python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m examples.hello_jev tickets --mode offline

本书以 Python 3.10 或更新版本为基线。虚拟环境激活后，后文的 python 指向这个环境。本地示例使用标准库，因此此时没有 pip install 步骤。

Windows PowerShell 可以直接使用虚拟环境里的解释器：

cd path\to\hello-jev
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m examples.hello_jev tickets --mode offline

这样不需要先调整脚本执行策略。后文若使用 Windows，就把 python 换成这条解释器路径。

打开命令报告的输出文件，确认结果标记为 offline_fixture，再找一条工单的原文与队列建议。离线模式重放预先编写的返回数据，并检查它是否与当前输入和问题匹配；改动导致指纹不一致时会报错。它不会替你重新进行语义判断，适合检查代码流程，不能用来观察 Jev 对措辞变化的反应。

第二步：在 Playground 做一条真实判断

官方快速上手提供了 Playground 入口。登录后确认自己的账号可以使用服务；界面若要求开通访问或配置计费，先按控制台提示处理。本书不预设每个账号都有相同额度或权限。官方快速上手

把下面这条合成客户消息放进 state：

I need a copy of the invoice for my September subscription.
Please send it before our bookkeeping closes on Friday.

它只有一个业务诉求，适合作为第一次判断。添加一个 Noul 问题，意思是：“客户原文是否明确说出了处理期限？”如果界面支持粘贴问题 JSON，可以使用：

{
  "has_deadline": {
    "type": "noul",
    "instructions": "Does the message explicitly name a deadline?"
  }
}

点击运行后保存输入、问题和实际结果。此处不预先给出“应该返回 0.99”之类的数字：书稿没有执行这次调用，你的账号、模型版本和当前输入才决定真实返回。人工参考判断是“存在明确期限”，因为 Friday 是原文中的证据。

现在只改消息，不改问题。把第二句改成 “There is no rush.”，再运行一次。然后改成 “Please help when possible.”。比较三次结果，记录是否与人工标注一致。不要同时改输入、问题和阈值，否则发生变化时很难确定原因。

第三步：认识你正在读的数值

Noul 的值表示命题得到“是”的概率，接近 0.5 表示两种答案的概率接近。它不是时间压力的强度，也没有独立 confidence 字段。Noul 文档

后两项将在置信度与评测中展开。现在只需保留原始值，不急着把它转成不可修改的自动决策。

第四步：在终端发出相同请求

从 TypeSafe 控制台取得可用的 API Key，把它放进当前终端的环境变量。以下输入方式不把 Key 写进命令本身：运行第一行后粘贴 Key，按回车；输入时没有可见字符属于正常现象。

read -r -s TYPESAFE_API_KEY
export TYPESAFE_API_KEY

Windows PowerShell：

$secureKey = Read-Host "TypeSafe API key" -AsSecureString
$credential = [System.Net.NetworkCredential]::new("", $secureKey)
$env:TYPESAFE_API_KEY = $credential.Password

这些变量只用于当前会话及其启动的程序。不要把 Key 填进样例数据、问题文字、截图或可分享的结果文件。你也不需要把 Key 发给编程助手。

在编辑器中创建 request.json，内容如下。实际保存时，JSON 字符串不能直接换行：

{
  "model": "jev-latest",
  "state": "Please send my invoice before Friday.",
  "questions": {
    "has_deadline": {
      "type": "noul",
      "instructions": "Does the message explicitly name a deadline?"
    }
  }
}

macOS 或 Linux 运行：

curl --silent --show-error --fail-with-body \
  https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output quickstart-response.json
python -m json.tool quickstart-response.json

这是 POST /v1/systemone 的真实请求，可能产生实际用量。接口使用 state、model 和 questions，结果在 answers 下；它不是 messages 格式的聊天请求。API 文档

Windows 读者可用下一章的 Python 程序完成同样的 HTTP 调用，也可以直接运行配套案例：

.\.venv\Scripts\python.exe -m examples.hello_jev tickets --mode live

案例会处理其样例集，范围大于本节的一条请求。切换 live 前先阅读对应案例的输入说明。macOS/Linux 的同一命令为 python -m examples.hello_jev tickets --mode live。

第五步：确认真正成功到了哪一步

打开 quickstart-response.json，寻找 answers.has_deadline.type 与 answers.has_deadline.noul，同时保留顶层 model 和 usage。不要把本地耗时或手写数字补成服务器用量。jev-latest 是别名，保存响应中的模型标识有助于后来比较版本。模型文档

如果第一条真实请求失败，保留 HTTP 状态和脱敏错误内容，按故障排查处理。重复点击不会修复缺失的 Key，随意改问题也不会修复认证失败。

保留一份可以重做的记录

本章的小作业是一张三行记录表：有期限、明确不着急、措辞模糊。填上人工预期和真实返回；没有账号时，把真实返回留空。不要只保存最后一个截图，也不要把三次运行都覆盖在同一个文件里。

每一行旁边保留完整消息、完整问题、运行日期、输入语言和实际模型标识。人工标签里要写清“Friday 提供期限”，而不只是写“应该是 1”。前者可以与他人讨论，后者把概率预测和业务判断混在了一起。若两位标注者对 “when possible” 是否算期限意见不同，先把这个分歧写入标准，再增加新样例。

重新运行时使用相同材料，是为了看同一任务的结果；改写材料时另起一个记录，是为了观察边界变化。两类试验需要不同的比较方式。不要因为某个新句子更容易判断，就把它替换进原记录，然后宣布系统已经改进。

离线工单的默认结果位于 examples/hello_jev/output/tickets.json。你也可以在 CLI 后加 --output first-offline.json 保存副本；扩展名应为 .json。真实结果另存一个文件，并确认其证据标记和用量字段。即使两份文件结构相似，它们证明的事情也不同。

做到这里，你已经有了第一份可以讨论、可以重新执行的材料。下一次遇到“怎么这回结果不同”，先对照这些记录，再决定要检查输入、问题还是版本。

下一章：把判断接进 Python 项目。