第 9 课 · 遇到问题排查指南、FAQ 与资源导航
🎯 学完这一课，你将能够
- 对照系统排查表，在 1 分钟内快速定位并解决常见报错
- 掌握 17 个高频实际问题的人话解答，扫清关于 Jev 的全部认知迷雾
- 熟悉官方文档、控制台与社区技术导航资源
快速定位排查表
如果在实操或接入过程中卡住，请先看这张排查表：
| 遇到的卡点症状 | 核心排查方向与秒级解决对策 |
|---|---|
| 申请 Waitlist 一直不过 | 申请描述太泛泛。重新提交申请，详细说明具体的工具项目、每日工单量与分流落地场景。 |
| 找不到聊天输入框 | 正常现象！Jev 不是对话聊天模型，请在左侧点击 Playground 或直接调 API。 |
| 试卷 Questions 不会写 | 先拿草稿纸写三句人话，不要一开始就写 JSON。人话想清楚了，再对应标成 Noul、Choice、Score。 |
| 中文分类不准确 | 拿同一批样本，将题目和 criteria 换成英文进行双跑对照；如果是行业黑话，将其解释写进 criteria。 |
| Confidence 很高但选错了 | 0.92 只代表概率集中度，不等于业务正确率。拿 30 条旧数据重新校准你的放行阈值。 |
| API 调用报错 401 | API Key 未正确注入。检查生产环境变量、检查 Authorization 请求头格式是否为 Bearer ts_...。 |
| 类型参数报错（Validation Error） | 检查 type 是否拼写正确（只能是小写 noul、choice、score）；检查 Choice 的 criteria 是否为对象，Score 是否为数组。 |
| 所有材料都被分到了“其他” | 前几个业务选项的边界描述写得太窄太苛刻。把具体选项的定义放宽，补充常见同义词。 |
| 所有材料都被分到了同一个部门 | 现场材料 State 太短，信息量不足；或者某一个部门的 criteria 解释过于宽泛，吞并了其他部门。 |
| 同一条材料两次跑出的结果会跳 | 检查两次请求的 Questions 是否发生过微调；如果题目没变，看置信度是否原本就处于低把握区间。 |
| 感觉响应比大模型还要慢 | 检查代码链路：是否在 Jev 做出判断后，又把整个请求丢回大模型让它重新完整推理了一遍。 |
新手高频 FAQ（17 问人话精解）
Q1：Jev 是 ChatGPT 的平替吗？ 答：完全不是。它根本不聊天。它接替的是你业务里“本来就只是让模型返回一个选项”的那一层。
Q2：小白必须会写代码才能玩吗？ 答：第一天完全不需要。控制台自带强大的 Playground，贴材料、写题目、看结果，点点鼠标就能全部搞定。要接进公司系统才需要写那二十行代码。
Q3：必须精通英语吗？ 答：界面虽然是英文，但对照教程标注图很容易认清。题干和选项可以用中文，遇到纠结时抽测一下英文即可。
Q4：在哪里充值与绑卡？ 答：在控制台导航点击 Usage / Billing，找到 Add Funds 按钮即可充值。
Q5：API Key 存在哪里最安全？ 答：存放在服务器环境变量或云原生密钥管理器中。严禁写进前端页面、严禁提交进 Git、严禁截图发群。
Q6：生产调用的模型名称写什么？
答：当前调试可写 jev-latest；正式锁定生产环境时，建议根据当时官方文档写死具体版本号（如 jev-1.13.0）。
Q7：中文支持到底怎么样？ 答：完全能跑。但英文理解更为稳定。涉及重要业务，务必拿你自己的真实中文样本验证。
Q8：Jev 能不能直接看图识物？ 答：目前不行。图片中的信息（如发票金额、报错截图文字）必须先由 OCR 或 Vision 模型转为文字，才能喂进 State。
Q9：置信度 0.9 可以直接全自动退款吗？ 答：上线第一周绝对不要。资金操作前期务必人工确认，放行线要用旧数据严密校准。
Q10：一次调用最多可以问多少道题？ 答：可以在同一套 Questions 里同时定义多道题。只要围绕的是同一份 State 材料，强烈建议一次全部问完，成本最低、速度最快。
Q11：Criteria 描述写得越长越好吗？ 答：不是。讲清核心边界即可。把整篇小说贴进 Criteria，只会白白增加输入 Token 成本，判断并不一定会更准。
Q12：Jev 的返回结果能直接发给客户看吗？
答：不能。它返回的是选项代号（如 billing）和数字。给客户看的温馨答复，应该由你系统里预置好的短信模板或者由大模型根据选项来起草。
Q13：Agent 安装了 TypeSafe Skill 却不调用怎么办？ 答：在给 Agent 的 Prompt 里明确加上一句：“遇到选择与分类问题，请务必使用 TypeSafe skill”，并检查 Agent 能否读取到环境变量。
Q14：Jev 能取代整个 Agent 框架吗？ 答：不能。它取代的是工作流节点中负责做选择题、做动作分流的那个判断元件。
Q15：我们公司今天该不该 All in Jev？ 答：先盘点一下你们现有业务：有没有哪次大模型调用，其实最终只用到它返回的一个选项？如果一个都没有，继续观察；如果有好几个，立刻着手做 30 条旧数据盲测表。
Q16：产品经理学到哪里就可以停了？ 答：看到 30 条旧数据盲测表即可。你能独立把表格理清、把自动放行线画好，就已经具备了推动研发团队落地的全部核心输入。
Q17：工程师的最小闭环是什么？ 答：配置好环境变量、写一段 fetch 请求、定义三道题目、把 answers 打进日志、用 30 条旧数据回放一遍。不要一开始就做复杂中台，先跑通最小闭环。
官方与社区核心资源导航
- 官方申请入口：typesafe.ai
- 控制台工作台：console.typesafe.ai
- 官方技术文档：docs.typesafe.ai
- 大白话介绍页：whatisjev.com/zh-tw
- 社区前沿演示汇编：jev-hub (mizzlelover.github.io/jev-hub)
📌 结语与核心认知
申请只是拿到了一张门票。门票不是作品；你的真正作品，是那份 30 条真实业务盲测表，以及表上那条你敢于签字放行的安全基准线。
学完后记得保存进度
完成标记保存在当前浏览器；登录后，会记住上次阅读的章节与位置。