🍎 Apple SiliconのMacでJev風の判断APIを動かすdiffusiongemma-jev-macosの構造と使い方

diffusiongemma-jev-macos は、Apple Silicon の Mac 上で、コーディングエージェント向けの小さな判断を数値で返すローカル決定サーバーです。
この記事では、仕組み・データ形・構築手順・運用の目安を、手元で再現できる粒度で整理します。
数値と仕様は 2026-09-19 時点の main（コミット 5d89d73）と公開ドキュメントに基づきます。

この記事の全体像。以下、順に解説します。

diffusiongemma-jev-macos とは

Saik0s/diffusiongemma-jev-macos は、パッケージ名 diffusion-jev 0.1.0、CLI 名 jev-local の MIT ライセンスの OSS です。

• 呼び出し側は、証拠（state）と、許容する答え付きの質問（questions）を送ります。
• サーバーは Noul / Choice / Score という型付きの確率を返します。
• 応答の組み立てと次のアクションは、アプリケーションのコードが担当します。

着想元は TypeSafe の決定モデル Jev です。
実行モデルは Google の DiffusionGemma 26B-A4B-it です。
これを mlx-community の OptiQ 4-bit チェックポイントとして読み込みます。
読み出し方は vLLM の structured-read 提案（PR #57250）と同じ「短い canvas 上の許可ラベルを読む」方式です。

Jev との互換は API の基本形に合わせたサブセットです。
学習と校正は共有しません。

質問型は 3 つです。

1 リクエストの上限は、質問 32 問、プロンプト 8,192 トークン（既定）、本文 1 MiB です。
既定モード packed は複数の質問を同じ入力にまとめて読みます。
independent は質問ごとに別々に評価します。

公開パイロット（CodeSearchNet Python、50 クエリ）の結果は次のとおりです。

30 関数の再ランクは中央値 19.1 秒です。
M2 Ultra の小さな合成スイートでは、既定設定の中央値が 291 ms、256 トークン canvas の full 投影が 472 ms です。

特徴

• TypeSafe Jev の System One 契約（state と型付き質問 → 型付き確率）の基本形を、Apple Silicon の単一プロセスで提供します。
• 学習はしません。既存の DiffusionGemma チェックポイントをそのまま使います。
• Google の DiffusionGemma 本体は、256 トークン canvas でテキストを生成するモデルです。本実装はそのチェックポイントを、許可ラベルの 1-step 読み出しに使います。
• start はピン留めしたチェックポイントを取得または再利用して起動します。serve は既存ディレクトリだけを使います。
• Python からは DecisionClient で同じ契約を呼べます。
• CodeSearchNet Python の公開再ランクを benchmark-search で再現できます。
• 依存とモデルが揃えば --offline で起動できます。
• LM Studio の同名 OptiQ ディレクトリがあれば、それを先に使います。
• GET /health と GET /v1/models を返します。
• コミュニティ事例（Every、Jev Logs、Foreman、ProgressGate、fast-jev-compaction）の設計を、中身を確認できる教材デモにしています。
• Choice / Score の confidence は分布の集中度（エントロピー正規化）です。Noul は noul だけを返します。
• options.samples は 1〜8 回の独立ノイズ読み出しの平均です。各回は 1-step です。
• 役割分担は明確です。終了コードなどの確定事実は通常のコード、パッチ生成はコーディングモデル、可否の確定はテストとレビューが担います。本サーバーは「どこに手間を割くか」の数値を返します。

Jev は RLCD（校正された決定のための強化学習）で訓練されたモデルです。本実装はこの訓練を再現しません。

関連スタックとの比較

NVIDIA GPU 側には同系統の実装として mmastrac/djev-spark と razorback16/openjev があります。

公式 DiffusionGemma の generate() は、256 トークン canvas を反復的に un-mask して文章を生成します。
vLLM PR #57250 は、CUDA 上で seeded canvas と read-only step を使います。
本実装は同じ読み出し形を MLX と OptiQ で実装し直したものです。

NVIDIA 側の同系統実装 djev-spark のプレイグラウンド UI です。本実装は画像入力と UI を持ちません。

ユースケース別の選び方

構造

C4 モデルの 3 段階（システムコンテキスト、コンテナ、コンポーネント）で整理します。

システムコンテキスト図

コンテナ図

コンポーネント図

図の矢印の意味は、下の表の各要素の説明にまとめています。

データ

公開契約と、推論時の作業データを整理します。
属性と制限は schemas.py、canvas.py、engine.py、api.py、model_manifest.py に合わせています。

概念モデル

情報モデル

図には決定 API の背骨だけを載せています。
Usage の全フィールドは後の表に、HealthResponse・ModelList・Artifact は概念モデルの表に記載しています。

値の型と制約は次のとおりです。

答えと Usage の意味です。

canvas の足場は canvas.py で次のように定義されています。

head = "<|channel>thought\n<channel|>"
rows = "q{i}: {label}"
close = "<turn|>"

許可ラベルは「1 トークン」「位置を共有」「ID 重複なし」を満たす必要があります。
違反すると 422 になります。

推論時の読み出し（engine.py の _read）は次の流れです。

JSON state
→ tokenizer.apply_chat_template system_prompt + user
→ encode
→ compile_canvas
→ encoder 512 トークンずつ
→ canvas.seeded 答スロットのみ
→ decoder 1-step
→ projection:
    labels: hidden[:, positions] @ alias_embeddings.T
    full: embedding.as_linear(hidden) で語彙全体の logits
→ model._softcap
→ 許可ラベルを抽出して softmax
→ samples 平均
→ make_answer

内部ラベルは、Noul が yes / no、Choice と Score が A / B / C … です。
応答のキーと Choice の当選名は、make_answer が元の質問 ID と criteria キーへ戻します。

構築方法

前提条件

uname -s
uname -m
python3 --version
uv --version
git --version

Darwin
arm64
Python 3.13.9

CLI 入口とフラグ

CLI 名は jev-local、サブコマンドは start / serve / demo / benchmark-search です。
demo と benchmark-search は Darwin の検査より前に分岐し、起動済みサーバーへ HTTP で接続します。

環境変数

インストール方法

いちばん手軽なのは uvx です。

uvx --python 3.13 --from git+https://github.com/Saik0s/diffusiongemma-jev-macos jev-local start

• パッケージを入れ、モデルを用意し、HTTP サーバーを起動します。
• ログに Application startup complete が出たら受付開始です。
• 停止は Ctrl-C です。

リポジトリを clone して動かす方法もあります。

git clone https://github.com/Saik0s/diffusiongemma-jev-macos.git
cd diffusiongemma-jev-macos
uv run jev-local start

検索評価とテストには extra benchmark（pyarrow）が必要です。

uv sync --frozen --extra benchmark

ツールとして常設するなら uv tool install を使います。

git clone https://github.com/Saik0s/diffusiongemma-jev-macos.git
cd diffusiongemma-jev-macos
uv tool install --python 3.13 .
jev-local start

モデルの二重ロードを避けるため、同時に動かすプロセスは 1 つにします。

上の手順は main の先頭を取得します。
この記事と同じ版（コミット 5d89d73）で再現するときは、revision を固定します。

uvx --python 3.13 --from git+https://github.com/Saik0s/diffusiongemma-jev-macos@5d89d73fa1c6acad0e7e6b689a444a2740a71180 jev-local start

clone する場合は、git checkout 5d89d73fa1c6acad0e7e6b689a444a2740a71180 を実行してから起動します。

モデルの解決順

start は次の順でモデルのパスを決めます（provisioning.resolve_model）。

構造チェックで確認する必須ファイルです。

config.json
tokenizer.json
tokenizer_config.json
model.safetensors.index.json
optiq_metadata.json
weight_map が指す *.safetensors
optiq/optiq_vision.safetensors または optiq_vision.safetensors

既存モデルの serve とオフライン起動

uv run jev-local serve --model /path/to/model
uv run --offline jev-local start --offline
uv run jev-local start --cache-dir /Volumes/Models/huggingface --port 8018

• serve は既存ディレクトリだけを読み、ダウンロードしません。--cache-dir と --offline はありません。
• 2 行目の先頭の --offline は uv のパッケージ取得を止めます。後ろの --offline はモデルのダウンロードを止めます。
• 起動前に preflight_port でポートを bind できるか確認します。確認はモデル取得より先です。

起動確認とアンインストール

curl -s http://127.0.0.1:8017/health
curl -s http://127.0.0.1:8017/v1/models
uv tool uninstall diffusion-jev

{"status": "ok", "model": "diffusiongemma-local"}

アンインストールで指定するのはパッケージ名 diffusion-jev です。
モデルファイルは Python ツールとは別の場所に残ります。

利用方法

リクエストのパラメータ

値は schemas.py、api.py、client.py に基づきます。

HTTP エンドポイント

自然言語の文章は返しません。
会話の永続化、認証ヘッダ、chat-completions エンドポイントもありません。

curl で POST /v1/systemone を呼ぶ

curl -s http://127.0.0.1:8017/v1/systemone \
  -H 'Content-Type: application/json' \
  -d '{
    "state": "pytest cannot collect tests: ModuleNotFoundError: No module named yaml",
    "questions": {
      "next_step": {
        "type": "choice",
        "instructions": "Which investigation best fits this failure?",
        "criteria": {
          "environment": "Inspect missing dependencies and the Python environment.",
          "assertion": "Inspect an assertion that compared the wrong values.",
          "network": "Inspect a remote request that timed out."
        }
      }
    }
  }'

• 選ばれたキーは answers.next_step.choice に入ります。
• 各候補の確率は answers.next_step.probabilities に入ります。
• この例で想定する答えは environment です。実際の数値はモデルが実行ごとに出します。
• サーバー自身はコマンド実行、ファイル編集、別エージェントの起動をしません。

DecisionClient で呼ぶ

from diffusion_jev.client import DecisionClient, DecisionClientError
from diffusion_jev.schemas import DecisionRequest, NoulAnswer, NoulQuestion

request = DecisionRequest(
    state={
        "function": "def parse_count(text):\n"
        "    try: return int(text)\n"
        "    except ValueError: return 0",
    },
    questions={
        "hides_error": NoulQuestion(
            type="noul",
            instructions="Does this function catch an exception without reporting it?",
        ),
    },
)

try:
    with DecisionClient() as client:
        answer = client.decide(request).answers.get("hides_error")
    if isinstance(answer, NoulAnswer):
        print(f"Probability of yes: {answer.noul:.3f}")
except DecisionClientError:
    print("The request failed. Keep the function available for manual review.")

別ポートのサーバーへ向けるときは base_url を渡します。

from diffusion_jev.client import DecisionClient
from diffusion_jev.schemas import DecisionRequest, NoulQuestion

request = DecisionRequest(
    model="diffusiongemma-local",
    state="ok",
    questions={"q": NoulQuestion(type="noul", instructions="Is the service ready?")},
)
with DecisionClient(base_url="http://127.0.0.1:8018") as client:
    print(client.decide(request).model)

1 リクエストで 3 つの型を聞く

{
  "model": "diffusiongemma-local",
  "state": {
    "test_result": "Login rejects every user with HTTP 500.",
    "workaround": "None known."
  },
  "questions": {
    "investigate": {
      "type": "noul",
      "instructions": "Does login fail for users?"
    },
    "next_file": {
      "type": "choice",
      "instructions": "Which supplied file should be inspected first?",
      "criteria": {
        "auth": "src/auth.py handles login requests.",
        "styles": "static/theme.css controls colors.",
        "other": "Neither file matches the problem."
      }
    },
    "severity": {
      "type": "score",
      "instructions": "How disruptive is the reported issue?",
      "criteria": [
        "Cosmetic issue; functionality works.",
        "A feature fails, with a working alternative.",
        "A feature is blocked without a known workaround."
      ]
    }
  }
}

オプションを指定する

from diffusion_jev.schemas import DecisionOptions, DecisionRequest, NoulQuestion

request = DecisionRequest(
    model="diffusiongemma-local",
    state={"note": "tiny evidence"},
    questions={
        "ok": NoulQuestion(type="noul", instructions="Is the evidence sufficient to continue?"),
    },
    options=DecisionOptions(
        seed=0,
        samples=1,
        mode="packed",
        projection="labels",
        canvas_length=None,
    ),
)

エラー応答

curl -s -o /tmp/jev-400.txt -w "%{http_code}\n" \
  http://127.0.0.1:8017/v1/systemone \
  -H 'Content-Type: application/json' \
  -d '{"model":"other","state":null,"questions":{"q":{"type":"noul","instructions":"Check"}}}'

422 は入力を本文に含めません。
{"secret":"PRIVATE"} を送っても、応答は {"detail":"Invalid request"} です。

demo と教材スクリプト

uv run jev-local demo search
uv run jev-local demo logs
uv run jev-local demo completion
uv run jev-local demo progress
uv run jev-local demo all --url http://127.0.0.1:8018
uv run python examples/context_compaction.py
uv run python examples/failure_triage.py
uv run python examples/file_selection.py
uv run python examples/patch_review.py

benchmark-search とローカル検査

uv run --extra benchmark jev-local benchmark-search \
  --limit 50 \
  --batch-size 5 \
  --seed 0 \
  --base-url http://127.0.0.1:8017 \
  --output retrieval-results.local.json

uv sync --frozen --extra benchmark
uv run pytest -q
uv run ruff check src tests examples
uv run mypy

速度ベンチマークは、HTTP サーバーを止めてからエンジンを直接呼びます。

uv run python -m diffusion_jev.benchmark --repeats 3 --output benchmark-results.local.json

extra benchmark が無い状態で benchmark-search を実行すると、終了コード 1 で Install the optional data reader with: uv sync --extra benchmark が出ます。

運用

起動完了を判定する

• 受付開始の合図は uvicorn の Application startup complete です。
• その直前に Model loaded in {秒}. Starting the local API. が出ます。
• モデルのロードは起動処理（lifespan）の中で行われ、完了するまで通常は接続自体ができません。
• 503（Model is not ready）は、エンジン未設定のままリクエストが届いた場合の防御的な応答です。
• 検証機（M2 Ultra / 64 GiB / Python 3.13.9）でのロード時間は 12.68 秒です。

Model loaded in 12.7s. Starting the local API.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8017

ヘルスチェック

• GET /health は推論キューと独立して応答します。
• 32 問のリクエストを処理中でも応答時間は 2.03 ms でした。
• キューが満杯でも 200 を返します。

curl -s http://127.0.0.1:8017/health

停止と 1 プロセス制約

• 停止はフォアグラウンドでの Ctrl-C です。
• lifespan の終了処理で ThreadPoolExecutor.shutdown(wait=True, cancel_futures=True) が走ります。
• 2 つ目のプロセスを起動すると、重みがもう 1 セット載ります。

lsof -nP -iTCP:8017 -sTCP:LISTEN

受付キューとバックプレッシャー

• 定数は MAX_ADMITTED_REQUESTS = 9（実行中 1 + 待ち 8）です。
• ワーカーは ThreadPoolExecutor(max_workers=1) です。
• 10 件目は 503（Inference queue is full）です。
• クライアントが切断しても枠は減りません。GPU 作業が終わるまで保持します。
• DecisionClient のタイムアウトは 120 秒です。キュー待ち時間は usage.total_ms に含まれません。

future = loop.run_in_executor(executor, engine.decide, request)
return await asyncio.shield(future)

usage メトリクスの読み方

次の JSON は、公開ベンチマークの既定設定の中央値を 1 リクエストの形に並べた合成例です。
単一リクエストの生ログではありません。
questions: 3 は形を示すための値です。

{
  "usage": {
    "prompt_tokens": 193,
    "questions": 3,
    "decoder_passes": 1,
    "canvas_tokens": 32,
    "prefill_ms": 210.6,
    "decode_ms": 79.5,
    "total_ms": 291.0,
    "peak_memory_gb": 18.30
  }
}

peak_memory_gb は mx.get_peak_memory() / 1e9 で計算します。
リクエストの先頭で mx.reset_peak_memory() を呼びます。

アクセスログとプロンプトの非保存

uvicorn.run(create_app(load_engine), host=args.host, port=args.port, access_log=False)

• サーバーはプロンプトと答えを保存しません。
• 422 は入力をエコーしません。
• ダウンロード中は huggingface_hub / httpx / httpcore の通信ログを抑え、Xet を無効にします。

レイテンシの目安（M2 Ultra）

数値は 1 台・1 回の計測です。
8,192 トークン上限付近や同時クライアント負荷は含みません。

オフライン推論とポート変更

uv run --offline jev-local start --offline
uv run jev-local start --port 8018
curl -s http://127.0.0.1:8018/health
uv run jev-local demo search --url http://127.0.0.1:8018

/docs の UI 資産は CDN から読み込みます。
オフラインでは /openapi.json を使います。

HTTP エラーへの対応

更新とランタイムのピン留め

• 推論ランタイムは mlx-optiq 0.5.12、MLX 0.32.2、huggingface-hub 1.32.0 に固定されています。
• エンジンは内部のデコーダインタフェースを使います。ランタイムを更新したら実モデルで再計測します。

uv sync --frozen --extra benchmark
uv run pytest -q

ベストプラクティス

packed と independent を使い分ける

• 既定の packed は、複数の質問で同じプロンプトと canvas を共有します。
• packed はプリフィルを節約します。小スイートでは 659 ms → 291 ms でした。
• 質問の追加・削除・並べ替えで、他の質問の確率が変わることがあります。
• independent は質問ごとに入力を作り直します。Choice / Score の候補はどちらのモードでも同時に評価します。

{"options": {"mode": "independent", "seed": 0, "samples": 1}}

canvas 幅は自動のままにする

• canvas_length: null が既定です。足場が収まる最小の 16 の倍数を選びます。
• 明示する場合は 16〜256 の 16 の倍数です。足場より狭いと 422 です。
• 小スイートでの主な高速化は、256 → 最短 canvas への縮小です（472 ms → 295 ms）。labels 投影の上乗せは約 1.6% です。

{"options": {"canvas_length": null, "projection": "labels"}}

samples は安定性の観測に使う

• samples は 1〜8、既定 1 です。
• 各 sample は新しいシードのノイズで読み直します。段階的な denoising ではありません。
• 結果の一致は読み出しの安定性を示します。真偽の校正ではありません。
• seed は入力ノイズを再現します。ハードウェア間のビット一致は保証しません。

{"options": {"seed": 0, "samples": 4}}

閾値は自分のデータで決める

• 例の 0.5 / 0.65 / 0.8 は教材の分岐です。信頼性の保証ではありません。
• セキュリティ境界、削除の保証、認可ルールには使いません。
• 本番の閾値は、自分のワークフローのラベル付き事例で決めます。

証拠は state にすべて入れる

• サーバーは、判断対象としてホスト上のファイルやリポジトリを自動では読みません。リクエストをまたぐ会話も持ちません。
• 判断に必要な要件・制約・直前の結果・テスト出力は、すべて state に入れます。
• 上限（1 MiB、既定 8,192 トークン）を超えると拒否します。切り詰めはしません。

{
  "state": {
    "requirement": "Reject retry counts <= 0 with ValueError.",
    "patch": "if retries <= 0: raise ValueError('retries')",
    "tests": ["test_positive_count"],
    "test_run": "1 passed"
  }
}

確定事実はコードで、制御は呼び出し側で持つ

• 終了コード、HTTP 状態、ファイルの有無は通常のコードで確定します。
• パッチ生成と説明はコーディングモデルに任せます。
• 無効な応答、ID の欠落、リクエスト失敗のときは元の証拠を残し、自動で先へ進めません。

from diffusion_jev.client import DecisionClient, DecisionClientError

try:
    with DecisionClient() as client:
        response = client.decide(request)
except DecisionClientError:
    keep_original_evidence()

チェックサム検証の範囲を把握する

• Hugging Face のピン留め snapshot は、起動のたびにサイズと SHA-256 を検証します。
• ユーザー管理のディレクトリ（明示パス、LM Studio）は構造チェックだけです。
• 明示パスが不正ならエラーになります。別 revision へは切り替えません。

待受は 127.0.0.1 のままにする

• 既定ホストは 127.0.0.1（ループバック限定）です。
• --host 0.0.0.0 にすると、認証・TLS・API キーが無いまま、そのネットワークに公開されます。

uv run jev-local start --host 127.0.0.1 --port 8017
curl -s http://127.0.0.1:8017/openapi.json > /tmp/jev-openapi.json

比較実験では設定を固定する

• seed、samples、mode、projection、canvas、質問の順、候補の順を固定します。
• 検索の --batch-size を変えたら別の評価として扱います。
• 速度ベンチと検索ベンチを同時に走らせません。

注意点

ドキュメントと実装の乖離

資料間の食い違い

2026-09-19 時点の未確認事項

トラブルシューティング

• 起動の失敗はモデル取得の前に止まります。先にポートとプラットフォームを確認します。
• リクエストの拒否は入力をエコーしません。ステータスコードと detail で切り分けます。
• /health が 200 でも推論は 1 ワーカーです。遅いときはキュー待ちと usage.total_ms を分けて見ます。

起動とロード

リクエストの拒否

切り分けコマンド

curl -s -o /dev/null -w '%{http_code} %{time_total}\n' http://127.0.0.1:8017/health
lsof -nP -iTCP:8017 -sTCP:LISTEN
curl -s http://127.0.0.1:8017/v1/models

まとめ

• diffusiongemma-jev-macos は、Jev の POST /v1/systemone 契約の基本形を、Apple Silicon の Mac 上で DiffusionGemma を使って提供するローカル決定サーバーです。
• 1-step の structured read で、Noul / Choice / Score の確率を数百ミリ秒で返します。
• uvx 1 行で起動でき、モデルはピン留め revision をチェックサム付きで取得します。
• 推論ワーカーは 1 本で、受付上限は 9 件です。待受は既定でループバック限定です。
• API の基本形は Jev に合わせていますが、入力制約と Usage が異なるサブセット互換です。学習・校正・品質も再現しません。閾値は自分のデータで決めます。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

公式リポジトリ

• Saik0s/diffusiongemma-jev-macos
• README.md
• LICENSE
• main コミット 5d89d73

構造 / データ / 実装

• docs/research.md
• docs/api.md
• docs/concepts.md
• src/diffusion_jev/schemas.py
• src/diffusion_jev/api.py
• src/diffusion_jev/engine.py
• src/diffusion_jev/canvas.py
• src/diffusion_jev/cli.py
• src/diffusion_jev/provisioning.py
• src/diffusion_jev/model_manifest.py

構築 / 利用 / 運用

• docs/setup.md
• docs/examples.md
• docs/community.md
• docs/benchmarks.md
• docs/retrieval-benchmark.md
• uv インストール
• Hugging Face Hub download guide

モデルと関連スタック

• mlx-community/diffusiongemma-26B-A4B-it-OptiQ-4bit
• ピン留め revision のファイル一覧
• Google DiffusionGemma overview
• TypeSafe Primitives
• TypeSafe Noul
• TypeSafe Choice
• TypeSafe Score
• TypeSafe Confidence
• TypeSafe State
• vLLM PR #57250
• mmastrac/djev-spark
• razorback16/openjev
• anessbelbati/jev-rerank-bench