Kev: 少規模 Jev 様の意思決定モデルファミリー

概要

少規模な「Jev（ジェーヴ）」様のような意思決定モデルを、ご自身で訓練・実行可能です。

• Kevは Qwen3.5 を基盤とし、「Jev のアーキテクチャの解明」に基づいた少規模な意思決定モデルファミリーです。
• 事前学習済みの重みを使用するか、ご自身で訓練することも可能です。
• API は TypeSafe の System One と互換性があり、Python SDK をローカルサーバーに指向して利用できます。

主な特徴

• 多種類のサイズ: 0.8B、4B、9B のモデルを用意し、訓練コードと評価データを提供します。
• 多様な質問タイプ対応: 一つのリクエスト内で以下のすべての質問タイプを扱います。
  • 是非判断（

    noul

    ）
  • 択一選択（

    choice

    ）
  • スコアリング（

    score

    ）
• 質問間の独立性: 複数の質問が共通の入力テキスト（ステート）を共有しますが、質問内容は互いに参照できません（相互影響はありません）。
• プラットフォーム対応:
  • CUDA、ROCm、Apple Silicon で動作します。
  • 4B および 9B のモデルは

    bf16

    モードで、32 GB メモリを持つ Mac に収まります。
  • サーバーサイド性能の詳細は「Serving Performance（サーバーサイド性能）」をご確認ください。
• 手軽なアクセス:
  • ウェブプレイグラウンドをインストール不要で利用可能です。
  • Hugging Face スペース

    huggingface.co/spaces/jaredpalmer/kev

    から、Kev-4B および Kev-0.8B をブラウザ上で試すことができます。

クイックスタート

1. 環境の準備

Python 3.12 以上と

uv

2. サーバー起動（ローカル環境での Kev-4B）

以下のコマンドを実行すると、Kev-4B がローカル環境で起動します。 初回実行時にはアダプタとベースモデルが自動的にダウンロードされます。

git clone https://github.com/jaredpalmer/kev.git && cd kev
uv sync --extra serve
# bf16 モードでの起動（Mac 推奨）
KEV_DTYPE=bf16 uv run --extra serve python -m kev.serve --run jaredpalmer/kev-4b --port 8009

オプション:

--run

• ローカルのチェックポイントディレクトリ
• Hub レビジョン（例：前世代の

  jaredpalmer/kev-4b@qwen3

  ）

3. API クライアントによるテスト

別のターミナルで、以下の「チケット（問い合わせ）」を System One エンドポイントに送信します。

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"]}
  }}'

4. サンプル回答（Kev-4B / Apple M5）

上記の入力に対する Kev-4B の回答例です。

{
  "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 の使い方

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="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)
print(response.choices["tone"].choice)
print(response.scores["urgency"].score)

プレイグラウンド（Web 版）

サーバー起動状態で別のターミナルを開き、Node 20.9+ を使用してプレイグラウンドを起動します。

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

localhost:3001

• プリセット: テキストや質問内容を編集可能。
• Packed vs separate: 全質問を一度に処理するか、個別に処理するかを比較できます。
• Permute: 選択肢の順序を変えた

  choice

  質問の実行テスト。
• 独立性テスト: 質問の独立性や仮の区切りトークンの挙動確認。

チェスのデモ: 盤面を入力し、合法的な手番を選択肢として回答させます。Score 質問で局面評価も行えます。Kev と対戦や、自身同士での対局も可能です（ゲーム履歴は

localStorage

モデルについて

まずは Kev-4B からお試しください。

• Kev-9B: 記憶容量よりも精度や較正（calibration）を重視する場合に使用してください。
• Kev-0.8B: 最も軽量なモデルが必要な場合に使用してください。

いずれも同じ訓練データと設定で Qwen3.5 ベースに構築されています。

注: 「学習済みソース」は訓練データセットから保持したサンプル、「新しいソース」は訓練していないデータセットやポリシールールを指します。Brier スコアが低いほど良い値です。

Kev-9B と Jev の比較

• Kev-9B は新しいソースの開発データセットにおいて、Jev より 3.5 ポイント劣ります（0.822 vs 0.857）。
• テストデータセットでは Kev-9B が 0.852 ですが、Jev は評価されていません。
• Jev の訓練データセットが不明なため、厳密な比較ではありません。

モデルの更新と較正（Calibration）

すべてのモデルは 2026 年 9 月 21 日 に更新され、再調整済みです（短縮された第 2 の訓練パス）。

• Kev-9B: テストデータセット上の精度が 0.837 から 0.852 に向上。
• Kev-4B: 0.832 から 0.837 に、Kev-0.8B: 0.668 から 0.684 に改善。
• 較正: 確率はデフォルトで較正されています（温度約 2.1〜2.4）。回答自体は変更されませんが、新しいソースでは較正誤差が大幅に改善しています。
  • Kev-9B: 較正誤差 0.106 → 0.042
  • 確実な誤り（高確率の不正回答）：8.7% → 4.0%（Jev は 3.7%、精度同等）

生のログ几率を取得するには

KEV_TEMPERATURE=1.0

日付算術 (

KEV_DATE_FACTS=1

)

オプションでステート内の絶対日付の差を計算して追加できます（例：「2026 年 7 月 4 日は...」）。

• Kev は日付の引き算自体は確実に行えませんが、明示された日数を使用することで対応可能です。
• デッドラインポリシー質問において、Kev-9B は 0.80 から 0.90 に向上しました（Jev: 0.93）。
• 表の数値はこの設定を使用していない場合の結果です。

リソースとコスト

すべての重みは Kev コレクションと GitHub リリースに含まれており、tarball ファイルと SHA-256 チェックサムも提供されます。詳細はモデルカードおよび PLAN.md を参照してください。

前世代（Qwen3）およびプロトタイプ

最初の Kev ファミリーは Qwen3 ベース で訓練されました。

• Mac での実行速度: Qwen3 モデルの方が高速です（Serving Performance を参照）。
• 開発状況: 現在は Qwen3.5 ベースの開発が主流で、Qwen3 の重みは公開されていますが新機能の追加はありません。

jaredpalmer/kev-0.6b

jaredpalmer/kev-4b@qwen3

jaredpalmer/kev-8b

注: ベースモデルのみが変更されています。テストデータセット上では、Kev-9B は Kev-8B に比べ 7.3 ポイント優れており（Brier スコアは 0.08 低いです）。Kev-4B と Kev-0.8B もそれぞれ前世代に対し向上しています。

API

エンドポイント:

POST /v1/systemone

state

• Choice で選択肢数 $K > 1$ の場合、信頼度は $(p_{\text{max}} - 1/K) / (1 - 1/K)$ です。単一選択の場合、信頼度は 1 です。
• Score の信頼度は分布が最も可能性の高いレベルに近い度合いを測ります。
• オブジェクトと配列はラベル付きテキストに変換されます。
• 無効なリクエストには 422 が返されます。

API メソッド一覧

/v1/models

/v1/systemone/permute

/v1/systemone/separate

注: サーバーは

127.0.0.1

仕組みについて

各チェックポイントは、Qwen ベースモデルに対するランク 16 の LoRA アダプタと小型のポインタヘッドから構成されています。

• ベース（Qwen3）: ステートと質問を一つのトークンシーケンスに統合し、アテンションマスクにより各質問を独立して処理します。位置 ID はステート直後にリセットされます。
• Qwen3.5: アテンション層と再帰的かつアテンションマスクを無視する Gated DeltaNet 層が混在しています。各行ごとにステートにその質問が続く形で実行され、隔離（isolation）は完全です。
• ポインタヘッド: 各選択肢の

  </opt>

  を

  <decide>

  とスコアリングし、softmax で確率に変換します。

訓練:

• 正解に対するクロスエントロピーを使用。
• アダプタとヘッドが同時に訓練され、ベースモデルの重みは固定されます。
• 訓練サンプルと API リクエストは同じテキスト形式を使用します。

サーバーサイド性能（Serving Performance）

環境ごとの推奨設定

• CUDA / ROCm: Qwen3.5 モデルに

  flash-linear-attention

  をインストールしてください。H100 や MI300X では 5 質問のリクエストが数十ミリ秒で完了します。
• Apple Silicon: DeltaNet 層用の高速カーネルがないため、PyTorch が参照コードを実行します。

Apple M5 (bf16 モード) の中間値（Median model time）

ステート（約 230 トークン）、各質問に選択肢 3 つの場合、5 質問での所要時間：

低レイテンシが必要な場合:現時点では Qwen3 モデルをお使いください（MLX バックエンドの予定変更中）。

• キャッシュ: ステートプレフィックスをキャッシュします（デフォルトは各状態が少なくとも 384 トークン）。772 トークンのステートを繰り返すと、Kev-4B (Qwen3) は 861ms から 242ms に短縮されます。
• オプション設定の無効化:

  KEV_MERGE=0

  、

  KEV_ATTN=eager

  、

  KEV_SHAPE_BUCKET=1

  、

  KEV_PREFIX_CACHE=0

  を使用します。

精度の違いについて

• bf16 の新しいソースの 24 レコードで、確率は fp32 と最大 0.017 の差がありましたが、最高確率の回答には影響ありませんでした（小さい検証）。
• アテンション単独のモデルでは、サーバーは fp32 で LoRA 重みをマージしてからキャストし、Apple GPU で SDPA アテンションを使用します。

訓練（Training）

リリースされたモデルは

decision-v7

• 公開データセット 10 つからの 10,000 サンプル
• 生成ポリシー例 896 サンプル
• 生成ルール構造 60 の 1,680 サンプル

すべて 2 エポック でランク 16 の LoRA とクロスエントロピーで訓練されます。

サンチチェック（Sanity Check）

uv run python -m kev.train --n_per_source 40 --accum 4 --out runs/smoke

Kev-0.8B の訓練（H100 一台、約 20 分）

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 の訓練（H100 一台、約 1 時間）

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

ご自身のデータでのファインチューニング（Fine-tuning）

リリースされたモデルは公開データセットと生成ポリシー例で訓練されています。質問のスタイルが異なる場合（独自のカテゴリ、ルール、言語など）、数百ラベル付きサンプルでの短いファインチューニングがプロンプト変更よりも効果的であることが多いです。

データ準備

サンプルを JSONL ファイルに置き、各行を一つのリクエストとして作成します。API リクエストと同じ形状で、各質問にラベルを追加します。

{"state": {"subject": "Charged twice", "body": "I see two charges for order #4411. Please refund one."},
 "questions": {
   "team":     {"type": "choice", "instructions": "Which team should handle this ticket?",
                "criteria": {"billing": "Payments and refunds", "shipping": "Delivery problems", "access": "Login and account access"}, "label": "billing"},
   "angry":    {"type": "noul",   "instructions": "Is the customer angry?", "label": false},
   "priority": {"type": "score",  "instructions": "How urgent is this ticket?", "criteria": ["low", "normal", "high"], "label": 1}}}

• choice

  ではラベルが選択肢名、

  noul

  では

  true/false

  、

  score

  ではレベルの位置（0 から開始）となります。
• ファイルの 10〜20% を評価用に別途保存してください。

訓練コマンド（リリースモデルからの開始）

uv run python -m kev.train --data train.jsonl --base Qwen/Qwen3.5-4B-Base \
    --init_from jaredpalmer/kev-4b --epochs 2 --lr 2e-5 --batch 1 --accum 8 \
    --dtype bf16 --checkpointing 1 --device cuda --out runs/mine

uv run python -m kev.benchmark --run runs/mine --data heldout.jsonl --out runs/mine-eval
KEV_DTYPE=bf16 uv run --extra serve python -m kev.serve --run runs/mine --port 8009

注意点:

• --init_from

  は訓練前にリリースモデルのアダプタとポインタヘッドをロードするため、Kev が既に知っている知識を残しつつドメインを追加できます。
• ベースモデルから始める（ゼロショット）場合、ファインチューニング版は Kev 独自評価セットで 0.33 という低いスコアになり、リリースモデルの 0.84 と対照的です。一方

  --init_from

  を使用した場合は評価セットで 0.83 を維持しつつ新ドメインで 0.88 に到達しました。
• より小さい学習率（2e-5）を使用し、ゼロショット学習レシピ（from-scratch）よりも推奨されます。

Mac 環境では一度に一つの訓練ジョブを実行してください。並列実行は大幅に遅くなります。長時間の作業には Modal を使用します。

コーディングエージェントとの連携:

kev-finetune

npx skills add jaredpalmer/kev@kev-finetune

Modal を使った訓練

各トライアルには独自の H100 が割り当てられ、接続を切っても学習は継続します。

uv run modal token new                                    # トークン生成（ブラウザ開示）
KEV_GPU=T4 uv run modal run modal_app.py::smoke           # エンドツーエンドチェック（GPU 約 1 分）

uv run modal deploy modal_app.py                          # アプリデプロイ（接続切れ耐性あり）
uv run modal run modal_app.py::study \
    --suite evals/v7/decision-v7 --plan experiments/v7-final.json \
    --name my-study --transfer evals/v4/transfer-v4 --budget 30 --timeout 7200

uv run modal run modal_app.py::pull --name my-study       # 結果の取得（runs/my-study）

研究計画には訓練設定がリストされ、各トライアルは設定、コードハッシュ、データセットハッシュ、および結果を保存します。開発結果（非固定テスト）を用いてモデルを選択し、最終候補を選んだ後、一度だけテスト結果を読み出せます：

uv run modal run modal_app.py::locked_test --trial my-study/00-trial-0 --name my-candidate

評価（Evaluation）

evals/

ドメイン外評価例

uv run python -m kev.benchmark --run jaredpalmer/kev-4b --suite evals/v4/transfer-v4 --out runs/my-eval
uv run python -m kev.benchmark --run jaredpalmer/kev-4b --suite evals/v9/transfer-v9 --out runs/my-eval-v9   # MMLU-Pro 追加等
uv run python -m kev.benchmark --run jaredpalmer/kev-4b --suite evals/v7/decision-v7 --out runs/my-eval-id   # 分布内（in distribution）

ベンチマークでは以下の指標が報告されます。

• 精度、Brier スコア、較正誤差
• 自動化可能な判断の割合（5% の誤り予算で）
• 選択肢順序変化の影響、質問独立性

transfer-v9

外部テストセットの変換データや Jev との比較結果も利用可能です：

• SemIf: 144 件の著者判断（Kev-9B:0.917, Jev:0.965）
• scientoon: 900 件のサポートチケット（ルーティング：Kev-9B:0.952 vs Jev:0.897、トーン：Kev-9B:0.911 vs Jev:0.914）

kev.jev

kev.compare

制限事項（Limitations）

• 較正: 分布内で適合された単一の温度に基づいています。新しいソースにおいて誤答に少なくとも 0.9 の確率を与える頻度は 4.0%（Jev は 3.7%）あります。5% の誤り予算での自動化可能な判断割合は Jev に劣ります。確率閾値を選ぶ前にご自身のデータでテストしてください。
• ファインチューニングの影響: ベースモデルの個別タスク性能が低下する可能性があります（例：日付算術）。知識系質問のギャップはベースモデルによって設定されるため解消されません。
• Apple Silicon での低速: Serving Performance の表を参照してください。
• 選択肢の順序: 変更すると回答が変化します。質問独立性でもこれを完全に防止できません。
• トークン長:
  • ステート最大 384 トークン、ステートプラス一つの質問で 1,024 トークンまで処理可能。
  • サーバーは最大 8,192 トークンを許可しますが、長文脈は訓練対象外です。
• バッチ処理: サーバーは一リクエストずつ処理します。ステートテキストのキャッシュは行いますが、異なる呼び出し元からのバッチ処理は行いません。

開発（Development）

ユニットテストや API テストを実行可能です。

# 重みなし、サーバーなし；CI で実行
uv run --extra serve python -m pytest tests/test_unit.py tests/test_research.py -q 

# 動作中のサーバーへの API テスト
KEV_BASE_URL=http://127.0.0.1:8009 uv run --extra serve python -m pytest tests/test_api.py -q 

# プレイグラウンドの型チェック
cd playground && npm run lint && npx next typegen && npx tsc --noEmit -p .

トラブルシューティング

• MPS でメモリ不足: 一つのジョブのみを実行しているか確認してください。

  output_hidden_states

  の有効化や

  peft

  のトークン追加は避けてください。
• プレイグラウンドでボタン不具合:

  localhost:3001

  を使用してください（Next.js の開発ホスト名検証のため）。他ホストの場合は

  playground/next.config.ts

  に

  allowedDevOrigins

  を追加する必要があります。
• 「Dataset scripts are no longer supported」エラー:

  legacy-datasets/banking77

  を使用してください。

著者・ライセンス

• 著者: Jared Palmer (@jaredpalmer)
• 開発: Devin を用いて構築。アーキテクチャ解説（Archer Hume）、API デザイン（TypeSafe）、ベースモデル（Qwen）に感謝します。日付算術の失敗場所を指摘した 3x3xX3N0N、

  --init_from

  に Radexito に感謝します。
• 関連研究: Hydragen, DeFT, FIRST。
• ライセンス: Apache-2.0。Qwen3 および Qwen3.5 のベースモデルも同様に Apache-2.0 です。訓練データセットは独自のライセンスを持っており、モデルカードをご参照ください。