Jev 常见错误：从报错到修复

“跑不起来”和“判断不对”是两类问题。前者需要确认环境与请求链路，后者需要检查材料、问题与业务政策。把两类问题混在一起，最容易出现一边改提示词、一边实际连 API 都没有成功的情况。

用最短路径确定故障层

先运行一个离线案例，确认 Python 能导入项目、读取样例并写出结果。然后只做一次小的真实请求，确认账号、网络和请求格式。最后才使用完整批量输入。每增加一层，都保留上一层已经成功的样本。

python -m examples.hello_jev tickets --mode offline

运行位置应该是解压后的项目根目录，其中能看到 examples/。如果错误是找不到模块，检查当前目录和 Python 命令指向的环境，而不是先安装一个名称相似的第三方包。

如果同一台电脑有多个 Python，先使用创建虚拟环境时的解释器，再激活虚拟环境。终端显示的环境名称并不能替代实际的解释器路径检查。

认证失败时，不需要修改问题

真实模式需要有访问权限的账号和有效的 API Key。环境变量只对当前进程及其子进程生效；在一个终端配置，不代表另一个已经打开的终端或编辑器能读取它。

可以用以下代码检查是否设置，但不要打印变量内容：

import os

print("Key configured:", bool(os.environ.get("TYPESAFE_API_KEY")))

.env.example 只是配置模板。Python 标准库不会因为目录里存在 .env 就自动加载它。本书的命令读取进程环境，请按运行说明设置变量。不要把密钥写进教程、截图、公开代码仓库或错误工单。

HTTP 状态码对应不同的处理动作

官方 API 文档列出了以下常见状态。接口与服务状态可能更新，处理前仍应阅读响应与当前 API 文档。

401 和 422 一般需要修正配置或内容。对相同错误请求立即重试多次，通常不会改变结果。429 和 529 属于可能恢复的服务条件，也不应无限重试：设置次数上限，尊重服务提供的等待时间，并把最终失败返回给调用方。

直调 HTTP 与使用官方 SDK 的默认重试行为可能不同。阅读实际客户端的代码和文档，避免一层 SDK 重试外面再套一层未受限的业务重试。超时代表客户端没有及时得到完整响应，不足以判断服务端是否已经执行或计费。

请求格式：先还原成一个问题

遇到 422，保留一段短文本，只提交一个 Noul 问题。成功后再逐个加回 Choice、Score 和其他字段。这样可以确定是哪个改动引入问题。

检查 questions 是对象，每个问题有合法类型与完整说明；Choice 的 criteria 是命名选项到说明的映射，Score 的 criteria 是有序等级列表。业务字段放在 state 中，不要把另一家聊天接口的 messages 结构直接搬过来。

本书代码对收到的响应也做校验。服务返回内容与预期不符时，程序应显示错误并进入复核，而不是把缺失字段填成零后继续执行。零在 Noul 中是有效的否定判断，和“没有收到结果”完全不同。

接口成功，但业务判断不对

按以下次序缩小问题，每次只修改一项：

1. 检查输入：是否把真正需要的事实传进去了，是否混入无关历史。
2. 检查指向：问题明确指定要判断哪段内容，还是依赖变量名暗示。
3. 检查标准：选项是否重叠，等级是否有可观察差异。
4. 检查组合：程序是否正确解释真假方向、评分范围和待复核条件。
5. 检查期望：人工参考答案是否真有一致规则支持。

例如，文章明明缺少操作步骤却通过，先看你的问题是否仅问“是否有编号列表”。编号列表可以列观点，也可以列步骤；缺陷可能出在标准，而不是输出解析。将标准改为“是否至少包含两个读者可以依次执行的动作”，再在开发样本上验证。

如果问题让模型推断未提供的订单归属，就需要改变系统设计。正确做法是让程序从可信身份与订单记录检查权限。重新写一段更强硬的模型指令不能代替权限数据。

修改离线输入后，为什么被要求重新配置？

离线模式读取固定的教学响应。它不理解新输入，也不会自动为新增样本生成判断。配套程序会核对输入与问题的指纹，发现材料被修改后就拒绝回放旧响应，避免让旧数字看起来像对新材料的判断。

新增一条离线测试时，需要同时定义期望行为、对应的响应情境和匹配指纹。恢复原始样例即可再次运行既有演示；希望观察模型面对新材料的真实反应，则切换到有权限的 live 模式。离线与真实两条路径应始终在报告中明确区分。

保存一个足够小的复现包

一个有用的报错记录包含：Python 版本、运行命令、样例编号、模型请求名、错误类型或状态码、期望行为，以及删去敏感内容后的最小输入。不要直接转发完整环境变量、认证头或大量真实客户数据。

先确认最小样例可以稳定复现，再提交给项目维护者或官方支持。修复完成后，把这条最小样例留在测试中。下次同类问题出现，你会更早知道它来自环境、接口变化还是自己的改动。