jaredpalmer/kev 来源：https://github.com/jaredpalmer/kev

Kev：小型Jev风格决策模型，可自行训练与运行

Kev是一系列基于Qwen3.5构建的小型决策模型，其架构源于《Jev架构揭秘》(https://archerhume.com/posts/jevs-architecture-unmasked)所述的设计。您可以直接使用预训练权重，也可以训练自己的模型。其API与TypeSafe的System One (https://docs.typesafe.ai/api)兼容，因此您可以将他们的Python SDK指向本地服务器。

亮点

• 提供0.8B、4B和9B三种模型，附带训练代码与评估数据。
• 支持单次请求中混合提问是非题(noul)、选择题(choice)和评分题(score)。
• 各问题共享输入文本，但彼此隔离，无法相互读取。
• 可在CUDA、ROCm及Apple Silicon上运行。4B和9B模型在32GB Mac上支持bf16精度；具体性能参见服务性能。
• 提供网页交互界面，可输入自定义内容并观察选项顺序对答案的影响。也可直接在浏览器中体验Kev-4B和Kev-0.8B（huggingface.co/spaces/jaredpalmer/kev），无需安装。

Kev交互界面

快速开始

需要Python 3.12+及uv (https://docs.astral.sh/uv/)。

git clone https://github.com/jaredpalmer/kev.git && cd kev
uv sync --extra serve
KEV_DTYPE=bf16 uv run --extra serve python -m kev.serve --run jaredpalmer/kev-4b --port 8009

上述命令将在本地启动Kev-4B。首次运行时会下载适配器和基础模型。--run参数也支持指定本地检查点目录或Hub版本标识，例如上一代的jaredpalmer/kev-4b@qwen3。

在另一个终端中发送工单查询：

curl -s localhost:8009/v1/systemone -H 'content-type: application/json' -d '{
  "state": "鞋子延迟两周送达且尺码错误。此外我的信用卡被扣了两次款。",
  "model": "kev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "应由哪个团队处理此问题？",
      "criteria": {
        "returns": "换货、退款、商品错发或损坏",
        "shipping": "配送状态、延迟、包裹丢失",
        "billing": "扣款、账单、支付问题"
      }
    },
    "escalate": {
      "type": "noul",
      "instructions": "此问题是否需要紧急人工介入？"
    },
    "frustration": {
      "type": "score",
      "instructions": "客户的情绪沮丧程度如何？",
      "criteria": ["平静", "沮丧", "非常愤怒"]
    }
  }
}'

以下是Kev-4B在Apple M5上以bf16精度运行的示例响应：

{
  "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": "平静",
        "1": "沮丧",
        "2": "非常愤怒"
      },
      "probabilities": {
        "0": 0.00,
        "1": 0.56,
        "2": 0.44
      }
    }
  },
  "usage": {
    "input_tokens": 101,
    "output_tokens": 161
  },
  "latency_ms": 495
}

工单涉及退货、延迟交付和账单问题，各部门概率分布清晰体现了这一点。这正是返回概率分布而非单一标签的意义所在。

Python调用

TypeSafe SDK已包含在uv sync --extra serve中：

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="我被重复扣款，请尽快处理。",
    questions={
        "billing": Noul(instructions="此工单是否涉及账单问题？"),
        "tone": Choice(
            instructions="客户的语气如何？",
            criteria={"calm": None, "frustrated": None, "angry": None},
        ),
        "urgency": Score(
            instructions="此工单的紧急程度如何？",
            criteria=["可以等待", "本周内", "今日处理"],
        ),
    },
)

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

交互界面

保持服务运行，打开另一个终端。需要Node 20.9+：

cd playground
npm install
npm run dev -- -p 3001

打开localhost:3001 (http://localhost:3001)，加载预设并编辑文本和问题，按⌘↵运行。“批量 vs 分离“模式对比一次性提问与逐个提问的效果。“排列模式“会使用六种不同选项顺序运行选择题。还提供测试问题隔离性和伪造分隔符token的预设。

内置国际象棋演示（http://localhost:3001/chess），棋盘作为输入，合法走法作为选择题选项，评分题评估局面优劣。您可以与Kev对弈或观其自弈，对局记录保存在localStorage中。

Kev国际象棋

模型列表

建议从Kev-4B开始使用。若对准确率和校准精度要求高于内存占用，可选用Kev-9B。如需最小模型则选Kev-0.8B。三者均基于Qwen3.5基础模型，采用相同训练数据与设置。

表格格式为 开发集 / 测试集。“训练数据源“指用于训练Kev的数据集中的留出样本。“新数据源“指Kev未训练过的数据集与策略规则类型。所有模型均使用相同开发集（decision-v7、transfer-v4）和测试集进行评估，测试集在模型选定后每个发布检查点仅读取一次。布里尔分数越低越好。

Kev-9B在新数据源开发集上比Jev低3.5个百分点（0.822 vs 0.857），测试集得分0.852（Jev未在此测试集运行）。由于Jev训练数据集未公开，这并非两种架构的严格对照实验。

所有模型已于2026年9月21日更新，通过生成样本进行短期二次训练：包含明确天数的政策案例，以及被移除关键证据、被训练为均匀回答的案例。测试集上Kev-9B从0.837提升至0.852（95%置信区间+0.8至+2.9），Kev-4B从0.832至0.837，Kev-0.8B从0.668至0.684。早期权重保存于版本v7-base。详细信息与成本参见模型卡片及PLAN.md。

概率默认经过校准。每个检查点存储在其分布内开发集上拟合的温度参数（约2.1–2.4），指针头在模型加载时应用该参数。这不会改变答案：在新数据源上，Kev-9B的校准误差从0.106降至0.042，高置信错误（概率≥0.9的错误答案）从8.7%降至4.0%，接近Jev的3.7%，且准确率保持不变。设置KEV_TEMPERATURE=1.0可获取原始logits。无论是否校准，表格中的准确率数字相同；布里尔分数基于原始logits计算。

可选设置KEV_DATE_FACTS=1会在状态中任意两个绝对日期之间追加天数差（如“2026年6月26日是2026年7月4日前8天“）。Kev无法可靠计算日期差，但可利用已说明的天数：在截止日策略问题上，Kev-9B准确率从0.80升至0.90（Jev为0.93）。上表未启用此功能。

Kev与Jev各数据源准确率对比

所有权重位于Kev合集(https://huggingface.co/collections/jaredpalmer/kev-6aad9d0ea49f2589665e07cd)及GitHub发布页(https://github.com/jaredpalmer/kev/releases/tag/kev-family)，包含压缩包与SHA-256校验和。

上一代（Qwen3）与原型

首代Kev系列基于Qwen3基础模型，采用相同数据与设置。这些权重仍公开发布，在Mac上运行速度更快（参见服务性能），但已停止开发。

由于仅基础模型变更，两代产品构成严格对照。开发集准确率提升在噪声范围内；测试集上Kev-9B比Kev-8B高7.3个百分点（95%置信区间+2.8至+11.7），布里尔分数低0.08；Kev-4B比前代高2.9个百分点（-0.9至+6.4）；Kev-0.8B比Kev-0.6B高4.8个百分点（+0.2至+9.3）。研究日志包含完整实验记录，包括预先设定的标准及结果达标情况。原始Kev-0.5B (https://huggingface.co/jaredpalmer/kev-0.5b)基于Qwen2.5-0.5B，作为参考保留；详见其模型卡片。

API文档

POST /v1/systemone

state为待评估文本。每个问题包含指令，必要时需提供选项列表。

{
  "state": "...", // 字符串 | 对象 | 数组 - 待评估内容
  "model": "kev-latest",
  "questions": {
    "": { // 由您定义ID，模型不可见
      "type": "noul" | "choice" | "score",
      "instructions": "...", // 字符串 | 对象 | 数组
      "criteria": ... // noul: {true?, false?}  choice: {选项: 描述|null}  score: [层级, ...]
    }
  }
}

对于选项数K > 1的选择题，置信度计算公式为(p_max − 1/K) / (1 − 1/K)。单一选项置信度为1。评分置信度衡量分布接近其最可能层级的程度，这是对TypeSafe公式的近似（其公式未公开）。这两个字段均非实测准确率。

对象和数组将转换为带标签文本。用户输入中的类分隔符字符串在分词前转义。无效请求返回422错误。usage.output_tokens统计序列化答案的token数，非生成token数。

服务器默认绑定127.0.0.1且无认证。除非自行添加认证，否则仅限本地访问。

工作原理

每个检查点包含Qwen基础模型上的rank-16 LoRA适配器和小型指针头。在纯注意力基础模型（Qwen3）上，状态与问题输入同一token序列：

...状态... 指令 选项1 选项2 ... 指令 选项1 选项2 ...

注意力掩码允许token读取状态及其所属问题，但无法读取其他问题或未来token。每个问题的位置ID在状态后重新开始，使模型能一次处理状态并独立回答各问题。

Qwen3.5混合注意力层与Gated DeltaNet层（后者为循环结构，忽略注意力掩码）。此类模型中，每个问题单独处理：状态后接该问题，使用相同位置编码。各行独立，隔离性精确，服务器计算状态一次后为各行重用其缓存。纯注意力模型下两种形式产生相同概率（tests/test_model.py）。

指针头将每个选项的隐藏状态与问题的隐藏状态进行评分，softmax将分数转化为概率。由于``位于最后，可关注完整选项列表。训练使用正确答案的交叉熵损失。适配器与指针头联合训练，基础模型其余权重保持固定。

训练样本与API请求使用相同文本格式。未使用Jev输出进行训练。合并提问或分步提问产生的概率在fp32测试中差异小于4e-6。这不代表选项顺序无关：同一问题内的选项仍可能相互影响。详见模型代码和一致性测试。

服务性能

在CUDA和ROCm上，建议为Qwen3.5模型安装flash-linear-attention（Modal镜像已包含）；在H100和MI300X上，五问题请求耗时数十毫秒。

Apple Silicon缺少DeltaNet层的快速内核，故PyTorch运行参考代码。M5芯片bf16精度下，五个三选项问题（约230 token状态）的模型中位耗时：

若需在Mac上低延迟服务，建议暂时使用Qwen3模型。Qwen3.5模型的MLX后端为下一阶段计划。

纯注意力模型服务器在转换前以fp32合并LoRA权重，Apple GPU使用SDPA注意力，MPS输入填充至64 token桶，并为重复请求缓存状态前缀（默认缓存至少384 token的四个状态）。对于772 token的重复状态，Kev-4B (Qwen3)响应时间从861毫秒降至242毫秒。可通过KEV_MERGE=0、KEV_ATTN=eager、KEV_SHAPE_BUCKET=1和KEV_PREFIX_CACHE=0禁用这些优化。

在24条新数据源记录上，bf16概率与fp32差异最大0.017，最高概率答案无变化。此为小规模检验，不保证所有输入均适用。

训练细节

已发布模型使用decision-v7数据集：来自十个公开数据集的10,000个样本，896个生成策略样本，以及来自60个生成规则结构的1,680个样本。所有模型训练2个epoch，LoRA rank 16，使用交叉熵损失。学习率：0.8B模型1e-4，4B/9B模型5e-5。对于Qwen3.5基础模型，适配器还覆盖DeltaNet投影层；kev.train从模型配置中自动选择正确目标。

# 简易测试，约1分钟
uv run python -m kev.train --n_per_source 40 --accum 4 --out runs/smoke

# Kev-0.8B（单H100约20分钟；Mac路径可行但对Qwen3.5基础模型较慢）
uv run python -m kev.train \
  --suite evals/v7/decision-v7 \
  --base Qwen/Qwen3.5-0.8B-Base \
  --base_revision dc7cdfe2ee4154fa7e30f5b51ca41bfa40174e68 \
  --epochs 2 --lr 1e-4 --batch 8 --dtype bf16 --p_none_pair 0.25 --device cuda \
  --out runs/kev-0.8b

# Kev-4B方案（通过Modal使用单H100，约1小时；见下文说明。使用Qwen/Qwen3-4B-Base可训练上一代模型）
uv run python -m kev.train \
  --suite evals/v7/decision-v7 \
  --base Qwen/Qwen3.5-4B-Base \
  --base_revision 1001bb4d826a52d1f399e183466143f4da7b741b \
  --epochs 2 --lr 5e-5 --batch 4 --accum 2 --dtype bf16 --checkpointing 1 \
  --p_none_pair 0.25 --device cuda --out runs/kev-4b

基于自有数据微调

已发布模型使用公开数据集和生成策略样本训练。若您的问题形态不同（自定义路由类别、升级规则、其他语言），在数百个标注样本上进行简短微调通常比调整提示词更有效。请将样本置于data/目录。