jaredpalmer/kev · 上手攻略

  • 仓库：jaredpalmer/kev
  • 链接：https://github.com/jaredpalmer/kev
  • 分类：AI决策模型 / 本地LLM应用
  • 作者：Tom
  • 更新：2026-09-21

是什么

Kev 是一个小尺寸的决策模型（Decision Model）家族，基于 Qwen3.5 基座构建，架构思路来自 Jev（见 Jev's Architecture Unmasked）。它用 LoRA adapter + pointer head 的方式，让你可以在自己的机器上训练和运行私有化决策模型，返回的不是自由文本，而是类型化的概率决策——支持二选一（noul）、多选一（choice）、打分（score）三种决策原语。

核心特点： - 提供 0.8B / 4B / 9B 三种规格，均可本地运行 - 所有决策共享输入文本，但各问题之间互相隔离（attention mask 控制） - 同时支持 CUDA（需装 flash-linear-attention）和 Apple Silicon（bf16，32GB Mac 可跑 4B/9B） - API 兼容 TypeSafe System One，可以用官方 Python SDK 直连本地服务 - 带一个 Web Playground，可以调试输入、测试选项顺序对答案的影响

解决什么问题

在工单路由、内容审核、游戏 AI、推荐评分等场景中，传统的做法是让 LLM 生成一段文字，再从文字里解析出结论。这有两个问题：输出不稳定（每次生成可能略有差异），以及成本高（每个问题都要跑一次完整的文本生成）。

Kev 的思路是把「决策」变成一个专门的小模型任务：给定一段文本 + 一组结构化问题，返回带概率的确定性答案。这让你： - 工单/客服场景：批量判断优先级、部门、情绪，一次调用搞定 - 游戏 AI：Chess 示例里，把棋盘状态输入，用 Choice 选合法走法、Score 评估局面 - 自定义评分：对产品评论、内容质量打 0-10 分，概率分布返回 - 本地优先：不需要把敏感数据发给第三方

快速安装

依赖：Python 3.12+ 和 uv。

git clone https://github.com/jaredpalmer/kev.git && cd kev
uv sync --extra serve

启动本地服务（以 4B 模型为例，首次运行自动下载基座+adapter）：

KEV_DTYPE=bf16 uv run --extra serve python -m kev.serve --run jaredpalmer/kev-4b --port 8009

注：--run 也接受本地路径或 Hub revision，如 jaredpalmer/kev-4b@qwen3 跑上一代（Qwen3）4B，速度更快（在 Mac 上约 174ms vs 779ms）。

CUDA 加速（Qwen3.5 模型建议安装）：

pip install flash-linear-attention

核心用法

curl 直接调用

curl -s localhost:8009/v1/systemone -H 'content-type: application/json' -d '{
  "state": "Shoes arrived two weeks late and in the wrong size. Also I see two charges on my card.",
  "model": "kev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "returns": "Exchanges, refunds, wrong or damaged items",
        "shipping": "Delivery status, delays, lost packages",
        "billing": "Charges, invoices, payment problems"
      }
    },
    "escalate": {
      "type": "noul",
      "instructions": "Does this need urgent human attention?"
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": ["Calm", "Frustrated", "Very angry"]
    }
  }
}'

返回示例：

{
  "model": "kev-latest",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "returns",
      "confidence": 0.21,
      "probabilities": { "returns": 0.47, "shipping": 0.28, "billing": 0.25 }
    },
    "escalate": { "type": "noul", "noul": 0.93 },
    "frustration": {
      "type": "score",
      "score": 1.44,
      "confidence": 0.78,
      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
      "probabilities": { "0": 0.00, "1": 0.56, "2": 0.44 }
    }
  },
  "usage": { "input_tokens": 101, "output_tokens": 161 },
  "latency_ms": 495
}

Python SDK（TypeSafe SDK）

# SDK 已含在 uv sync --extra serve 中
cd your_project
uv add typesafe-sdk  # 如在新项目中使用

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

client = TypeSafeClient(
    api_key="local",
    base_url="http://127.0.0.1:8009",
    model="kev-latest",
)

response = client.system_one(
    state="I was charged twice. Please fix this ASAP.",
    questions={
        "billing": Noul(instructions="Is this ticket about billing?"),
        "tone": Choice(
            instructions="What is the customer's tone?",
            criteria={"calm": None, "frustrated": None, "angry": None},
        ),
        "urgency": Score(
            instructions="How urgent is this ticket?",
            criteria=["can wait", "this week", "today"],
        ),
    },
)

print(response.nouls["billing"].noul)        # 0.93
print(response.choices["tone"].choice)       # "frustrated"
print(response.scores["urgency"].score)     # 1.44

Web Playground

cd playground
npm install
npm run dev -- -p 3001
# 打开 http://localhost:3001

Playground 支持：自定义输入/问题、对比合并提问 vs 单独提问、测试选项顺序影响（Permute）。另有 Chess 演示，棋盘作为 state，合法走法作为 Choice 选项，局面评分作为 Score。

模型规格选择

模型 基座 新来源准确率（测试集） Brier（越低越好） Mac bf16 推理时间
Kev-0.8B Qwen3.5-0.8B-Base 0.668 0.473 ~329ms
Kev-4B Qwen3.5-4B-Base 0.832 0.266 ~779ms
Kev-9B Qwen3.5-9B-Base 0.837 0.243 ~2s

Mac 上追求低延迟优先选 Qwen3 版本（--run jaredpalmer/kev-4b@qwen3，约 174ms）。

典型适用场景

  • 客服工单分类：一次传入工单内容，同时问「哪个部门处理」「是否紧急」「客户情绪评分」，批量跑，成本极低
  • 游戏 AI：Chess 示例展示的思路可迁移到其他棋类或策略游戏
  • 内容审核/过滤：noul 类型天然适合「是否违规」的二分类，带概率可做置信度门控
  • 本地隐私场景：不想把数据发给第三方，但需要 AI 辅助决策
  • 规则 + AI 混合系统：用 Jev 做策略判断，规则引擎做执行，pointer head 保证输出格式稳定

坑与注意

  1. Apple Silicon 速度：Qwen3.5 混合了 Gated DeltaNet 层，Mac 上没有快速 kernel，PyTorch 跑参考实现，9B 模型约 2 秒/次。如追求低延迟先用 Qwen3 版本（@qwen3 revision）。

  2. Confidence 不是准确率：README 明确说明，Confidence 是 (p_max − 1/K) / (1 − 1/K) 的数学变换，不是有多少比例答对了。不要把它当成「这个答案 80% 可靠」来用。

  3. Mac bf16 精度：README 披露 bf16 概率与 fp32 最大偏差 0.017，属于「小样本检查，非全面保证」。高精度场景建议用 CUDA 或确认偏差可接受。

  4. 无认证：服务绑定 127.0.0.1，无内置认证。需要放在本地使用，或自行在前面加一层认证层。

  5. fine-tune 建议：如果你的问题类型与预训练数据差异大（自己的路由类目、特殊语言），用几百条标注数据微调效果通常好过改 prompt。

与同类对比

方案 决策类型 本地运行 概率输出 训练成本 适用场景
Kev Choice/Score/Noul ✅（0.8B-9B） ✅ 完整概率 LoRA ~1h（H100） 私有化决策、工单路由、游戏
TypeSafe Jev（托管） Choice/Score/Noul ❌ ✅ 完整概率 无（云） 快速接入、不想运维
通用 LLM + prompt 自由文本 ✅（本地模型） ⚠️ 需解析 无 通用，但输出不稳定
Rule-based 确定规则 ✅ ❌ 无 规则清晰的场景，但无法泛化

Kev 的优势在于本地私有、输出类型稳定、概率完整；劣势是预训练数据偏向英文工单/客服场景，其他语言或领域可能需要微调。

一句话推荐结论

如果你需要在本地跑一个输出稳定、带概率、专门做决策的小模型（而不是生成文本），Kev 是目前最直接的开源方案——0.8B 到 9B 多个规格，API 兼容 TypeSafe，训练和推理都有完整代码。