2026-09-21_Jev本地部署手册

Jev 本地部署手册（TypeSafe System One）

用 TypeSafe 的 Jev 给 Agent 外挂一个"只做判断、不写文章"的模型：批量分类、意图路由、评分、是非判断，以及从技能库里挑该加载哪个 skill。
环境：WSL2 (Ubuntu) + Python 3，无需 GPU（模型跑在云端，本地只放调用封装）。
状态：✅ 已部署并验证通过（实测单次调用 1.9 秒；技能选择两段式 1.4–2.2 秒）。

关联概念： [[概念/编程]] | [[概念/Agent]] | [[概念/开源]]

---

1. 背景：为什么需要一个"只会判断"的模型

1.1 问题的起点——工具库越大，选择越难

Agent 的技能库（skill / tool 列表）是以索引形式到达模型的：一行一个，描述被截断。

Hermes 这个 harness 默认把描述截到 60 字符。在这个宽度下：

"编辑 .pptx 文件的技能"和"创作 .pptx 文件的技能"读起来几乎一样。

于是出现两类错误：

1. 用户要一份 pitch deck，Agent 加载了"编辑 pptx"那个；
2. 这一轮根本不需要任何技能（比如用户只是在吐槽亏钱了），Agent 也会加载一个——因为一列名字本身就在邀请它猜。

这不是模型不够聪明，是信息不够：描述被砍到 60 字符，判断依据就没了。

1.2 为什么不直接让大模型做这个判断

让主模型自己选也行，但代价是：

• 它要生成一段文本/JSON（几十到几百 token 的输出），然后你还要解析；
• 每次判断都要走一遍完整推理，慢且贵；
• 在一轮对话里做 5 次小判断，就是 5 次大模型调用。

而这些判断的共同特征是：次数多、选项有限、不需要生成任何东西。这类活不该由生成模型干。

1.3 Jev 的定位

Jev（TypeSafe System One）不生成文本，只做判断：给它一段 state + 一批候选选项，它回概率分布 + 置信度。

它替代的是"让大模型生成一段 JSON 再解析"这个动作，不是替代大模型本身。

---

2. 它是什么：三种原语

类型	用途	返回
Choice	答案是一个无序选项集里的一个	choice + probabilities + confidence
Score	答案落在一条有序等级上	score + legend + probabilities + confidence
Noul	干净的是非问题	noul（0–1），无 confidence

关键特性：多问题一次调用。 一个请求里可以塞进任意多个问题（还能混用三种类型），它们在服务端并行且相互隔离地评估——加问题几乎不增加耗时。这是它相对大模型最核心的优势。

成本与限流（官方口径）：

• 输入 $42/Btok（$0.042/MTok），输出 token 免费；
• 限流 250,000 tokens/秒、1,200 请求/分钟，官方注明正在动态调整；
• 上下文：state + 最长问题 ≤ 32k tokens，总计 ≤ 64k；
• 只接受文本。

---

3. 什么时候用 / 不用

三条同时满足才划算：判断次数多 · 选项有限 · 不需要生成文本。

✅ 用	❌ 不用
批量分类（材料归目录、评论分派别、视频定主题）	写内容/写代码/写分析（它不生成文本）
意图路由（该走确定性逻辑、大模型、还是给人）	只做一两次判断（自己想更快，省不了时间）
评分/严重度（证据强度、紧急程度、可信度）	需要读图/音视频（只吃文本，先转文本）
干净的是非判断（是否含个人信息、是否要求退款）	判断标准说不清（选项/等级必须由你给全）
从技能库里挑该加载哪个 skill（见第 6 节）	需要解释理由（它不给理由，只给概率）

---

4. 架构

┌─ 本机（WSL / Linux / macOS）───────────────────┐
│  jev.py              通用调用封装              │
│   ├─ noul / choice / score  单问题             │
│   ├─ ask   多问题一次调用                      │
│   └─ batch 批量（逐行 spec）                   │
│  jev_skill_suggest.py  技能选择器（两段式）     │
│   ├─ Call 1：扫全部技能 → 候选                 │
│   └─ Call 2：精读前 3 → 定选                   │
│  ~/.hermes/.env  →  TYPESAFE_API_KEY          │
└───────────────────┬───────────────────────────┘
                    │ HTTPS  POST /v1/systemone
                    ▼
        ┌─ api.typesafe.ai ─────────────┐
        │  Jev (jev-1.13.0)             │
        │  只判断，不生成文本            │
        └───────────────────────────────┘

"本地部署"的准确含义：Jev 是闭源 API 模型，TypeSafe 没有放权重，模型本体不能跑在你的显卡上。所谓本地部署 = 在本机装好调用封装 + skill，让 Agent 能随时调它。

---

5. 部署步骤

5.1 拿 API key（唯一需要人工的一步）

1. 打开 https://console.typesafe.ai/keys —— 会自动跳登录页；
2. 登录只有两种方式（没有密码注册）：Continue with Google 或 Email me a code instead（邮箱验证码）；
3. 登录后在 /keys 创建 key 并复制（形如 apikey_…_…，108 字符）；
4. 写进环境文件：

echo 'TYPESAFE_API_KEY=你的key' >> ~/.hermes/.env
chmod 600 ~/.hermes/.env   # 别让同机其它用户读到

⚠️ 不要把 key 贴在聊天里。若已贴过，去 console 吊销重发；新 key 直接写文件，代码不用改。

5.2 装两个脚本

文件	作用
jev.py	通用调用：noul / choice / score / ask / batch / --selftest
jev_skill_suggest.py	技能选择器（两段式实现）

重写时别丢的设计约束：

• key 只从环境变量或 ~/.hermes/.env 读，永不打印；
• 无 key → 退出码 2 + 明确提示（不静默失败、不卡住）；
• 429 按 retry-after 重试一次；其它错误退出码 3；
• 默认输出给人看的一行摘要，--json 给原始响应。

5.3 建技能清单

python3 jev_skill_suggest.py --build-roster
# → ~/.hermes/cache/jev_skill_roster.json（本机 202 个技能，含 name/desc/excerpt/path）

技能库变动后需要重建。

5.4 三步验证（必须全过）

# 1) 连通性 + key 位置（不打印 key）
python3 jev.py --selftest
#    期望：key 来源 ~/.hermes/.env | 模型: jev-1.13.0 | noul=0.9xx

# 2) 单次判断
python3 jev.py choice "一个讲 Qt 与 KDE 互相成就的开源历史视频" \
    "该归到哪个目录" "阅读资讯" "开发" "ai"
#    期望：choice=开发  conf=0.99  开发:0.99 阅读资讯:0.01 …

# 3) 技能选择（两段式）
python3 jev_skill_suggest.py "帮我把这个B站视频整理进库"
#    期望：✅ 建议加载: bilibili-video-organization

---

6. 场景一：从技能库里挑该加载哪个 skill

这是最值得用的场景，也是官方 cookbook 直接拿 Hermes 当案例的那个。

6.1 官方实测数据

488 次请求，claude-haiku-4-5，Hermes 技能库：

	加载了错的 skill	什么都不该加载时却加载了
agent 只有技能清单	16.8%	9.8%
agent + Jev 建议	7.3%	4.0%
agent 直接被告知正确答案	2.5%	1.2%

第三行是天花板：就算直接告诉它答案，它也不总是照着做。所以目标不是 0%，而是把两类错误各砍掉一半以上。

6.2 实现（两段式）

Call 1（skim 全部技能）
  state     = 技能索引（每行一条，描述长度自适应截断）+ 用户这一轮的话
  questions = 1 个 Choice（选哪个 skill）
            + 4 个 Noul（要不要技能 / 是否要动用户的东西 / 是否该按步骤走 / 是否只是闲聊）
  gate      = 四个 Noul 的均值；< 0.30 → 直接建议"不加载任何 skill"

Call 2（只精读前 3）
  state     = 用户这一轮的话
  criteria  = 每个候选的 SKILL.md 真实节选（700 字）
  questions = 1 个 Choice（三选一）+ 每个候选一个 Noul（它真的能做这事吗）
  fit < 0.30 → 建议"不加载"

输出：最多一个 skill 名 → 写进 system prompt 的一行

可调阈值：SHORTLIST=3 · EXCERPT_CHARS=700 · GATE_THRESHOLD=0.30 · FITS_THRESHOLD=0.30。

6.3 本机实测

用户这一轮	Jev 的判定	对不对
帮我把这个B站视频整理进库	Call1 bilibili-video-organization 0.99 → Call2 fit 0.72 → 建议加载	✅
我股票亏了心里很烦，不想看了	gate=0.263 < 0.30 → 建议不加载任何 skill（候选 trade-journal 0.43 被门控拦住）	✅
帮我看看兴森科技现在的筹码分布	Call1 chip-distribution 1.00 → fit 0.84 → 建议加载	✅

第二条最能说明价值：用户情绪低落时，正确的行为是给结论并让他关软件休息，而不是加载一个日志类技能去分析——而只有技能清单的 Agent 很容易"看到 trade-journal 就加载"（它在候选里确实排第一，0.43）。门控把它拦住了。

---

7. 场景二：批量分类 / 意图路由

# 单问题
python3 jev.py noul   "<一段文本>" "这条内容含个人信息吗"
python3 jev.py score  "<一段文本>" "证据强度" "个人观察无数据" "有单一来源" "多来源可交叉验证"
python3 jev.py choice "<一段文本>" "该归到哪个目录" "阅读资讯" "开发" "ai" "交易"

# 多问题一次调用（推荐）
python3 jev.py ask /tmp/spec.json

spec.json 形状：

{
  "state": "客户说鞋码不对，而且退款三天没到账",
  "model": "jev-latest",
  "questions": {
    "department": {"type": "choice", "instructions": "Which team should handle this",
                   "criteria": {"billing": "付款或订阅问题", "technical": "Bug 或集成问题", "sales": "报价或账号问题"}},
    "frustration": {"type": "score", "instructions": "客户有多愤怒",
                    "criteria": ["平静陈述", "不满但克制", "非常愤怒"]},
    "is_urgent":  {"type": "noul", "instructions": "这条消息传达了紧迫性"}
  }
}

实测返回（一次请求，4 个问题混用三种类型）：

is_about_model    noul=0.960
has_perf_claim    noul=0.990
evidence_strength score=0.96  conf=0.94
topic             choice=ai   conf=0.99  ai:0.99 开发:0.01 交易:0.00 阅读资讯:0.00

设计要点（来自官方 intent-routing / speculative fan-out 模式）

1. 一个判断一个问题，不要问"综合评估一下"——拆成原子判断，权重在代码里合；
2. 选项要写全，覆盖不全时加一个 other / none of the above；
3. 确定性规则留在代码里，只把"模糊但边界清楚"的判断交给它；
4. 执行与验证留在代码里：它说"该退款"，真正调退款接口前仍要检查金额/权限/幂等。

---

8. 踩坑记录（官方文档没写清的地方）

坑	现象	正确做法
choice.criteria 必须是字典	传列表 → 422 dict_type … loc:[…,"criteria"]	写 {"选项": "说明"}；脚本已自动把裸选项转成 {选项: 选项}
score.criteria 必须是列表（与 choice 相反）	传字典会报错	按等级顺序 ["等级0","等级1"]
请求体必须带 model	缺字段 → 422 missing body.model	统一走 build_body() 自动补 model: jev-latest
32k 预算	state + 最长问题 ≤ 32k tokens，总计 64k	大 state（技能索引）要截断——脚本自适应 150→120→100→80→60→40 字
只吃文本	图/音/视频不支持	先转文本再送
Noul 没有 confidence	0.5 容易被误读成"中等水平"	0.5 = 是非等概率；要测程度用 Score

---

9. 置信度怎么用（confidence-gated routing）

• confidence 高 → 代码自动走；低 → 升级给人或大模型；
• 别只看 choice，要看 probabilities：0.51/0.49 和 0.98/0.02 的 choice 一样，含义完全不同；
• 它的校准目标是"说 80% 的事真有约 80% 发生"——但这是官方自测口径，用之前自己在几个已知答案的样本上验一遍。

失败回退（必须做，否则会卡住）

情况	动作
退出码 2（无 key）	不要卡住：自己判断，并说明"Jev 未配置"
429	按 retry-after 重试一次；仍失败则回退
超时/其它错	回退自己判断，如实说明
结果明显不合理	回退自己判断；不要因为"模型说的"就照做

---

10. 边界

• 只吃文本：图/音/视频必须先转文本；
• 32k 预算：state + 最长问题 ≤ 32k tokens，总计 64k；
• 它不给理由：只要概率，需要解释的场合仍用大模型；
• 选项质量决定结果质量：选项/等级写得含糊，概率就没法解释；
• 不要用它生成任何文本——那是它做不到的事。

---

11. 参考资料

• 官方文档索引：https://docs.typesafe.ai/llms.txt（每页加 .md 取 Markdown，比爬 HTML 快）
• 官方 cookbook「Skill suggestion」：https://docs.typesafe.ai/cookbooks/skill_suggestion.md（Hermes 就是它的案例）
• 官方 API 参考：https://docs.typesafe.ai/api.md
• 官方 agent skill 源码：https://github.com/typesafe-ai/skills（面向"写集成"，与本文"运行时当工具用"不同）

---

12. 未核实 / 待确认

• 是否有免费额度、是否需要绑卡：官方文档没有定价页（typesafe.ai/pricing 返回 404），需登录 console 自行查看；
• 开源替代品 Laya：有报道称其"推理速度快 Jev 近 8 倍、零成本替代专有 API"，但同时指出它"需微调适配、基础模型在特定基准测试中接近随机水平"。未验证，不要当成等价替代。