Contrastive-LM/CLM

Contrastive Language Models (CLMs) are a new class of System One model trained with a contrastive learning objective that connects states and actions.

Contrastive Language Models (CLM) – クイック概要

概要 – CLM-8B は、候補となるアクションがテキスト状態とどの程度一致するかをスコアリングすることで、高速かつ型付きの意思決定を行う System-One スタイルのモデルです。これは、凍結された大規模言語モデル (Qwen-3-8B) に、状態用とアクション用にそれぞれ 20 M パラメータの軽量な投影ヘッドを追加して構築されています。これら 2 つのヘッドは、数百万の質問と回答のペア、合成されたハードネガティブ、およびエージェントの軌跡を用いた対照 (InfoNCE) 損失関数でトレーニングされています。

重要性 – 状態とアクションの埋め込みを分離することで、CLM はアクションベクトルをキャッシュし、多くの状態で再利用できます。これにより推論コストが低く抑えられ、同等のエージェント（例: Jev）よりも最大 9 倍高速でありながら、コンピュータ操作、ゲーム、ツール呼び出しのベンチマークで同等以上の成功率を達成します。また、エージェントのコーディングベンチマークにおける検証器としても優れており、Terminal-Bench 2.1 (87.6 %) および DeepSWE (81.6 %) で新しい SOTA を記録しました。

はじめに

# クライアントライブラリのインストール
pip install contrastive-lm

サービスの実行

エンコーダー (Qwen-3-8B プーリングモデル) を vllm で起動します：

vllm serve Qwen/Qwen3-8B --served-model-name qwen3-8b \
     --runner pooling --max-model-len 2048 --port 8090 &

CLM の起動：
```
clm-serve   # http://127.0.0.1:8700 で API を提供
```
初回実行時に 75 MB の「ヘッド」チェックポイントが自動的にダウンロードされます。

Python での簡単な使用例

from clm import CLMClient, Noul, Choice, Score
client = CLMClient()
resp = client.system_one(
    state="Customer: my invoice was charged twice and nobody answers the phone!",
    questions={
        "urgency": Noul(instructions="Is this urgent?"),
        "department": Choice(
            instructions="Which team should handle this?",
            criteria={"billing": "Charges, invoices, refunds",
                      "technical": "Bugs and outages"}),
        "frustration": Score(
            instructions="How frustrated is the customer?",
            criteria=["Calm", "Frustrated", "Very angry"]),
    },
)
print(resp.answers["urgency"].noul)          # ステートメントが真である確率
print(resp.answers["department"].choice)   # 選択されたオプション
print(resp.answers["frustration"].score)   # 期待されるレベル (0-2)

同じ機能は、組み込みの playground UI (http://localhost:8700/) および標準の HTTP API (POST /v1/systemone) を通じて利用可能です。

主な機能

機能	説明
型付き意思決定 API	3 つの質問タイプをサポート – `Noul` (バイナリ確率)、`Choice` (ソフトマックス付きカテゴリ)、`Score` (順序付き評価)。
高速ランキング	`Engine.rank(state, candidates)` は、任意の候補リストをプロセス内でスコアリングし、Best-of-N 選択、ツール呼び出し、または検索の絞り込みに役立ちます。
キャッシュ対応	アクション埋め込みはキャッシュされ、繰り返される状態では同じベクトルが再利用されるため、トークン数とレイテンシが削減されます。
ゼロショット	タスク固有のプロンプトエンジニアリングは不要 – 状態テキストと候補アクションのセットを提供するだけです。
微調整	独自のデータセットで軽量な投影ヘッドを微調整可能 (`docs/FINETUNING.md` を参照)。
拡張可能なヘッド	`state_head`、`action_head`、`logit_scale`、および設定を含むチェックポイントは、`--ckpt` を介して提供可能です。

パフォーマンスのハイライト（リポジトリの報告に基づく）

レイテンシ：多数の候補アクションがあるタスク（例: WikiRacing）において、Jev よりも最大 9 倍低速。 |
エージェント検証：CLM-8B は Terminal-Bench 2.1 で 87.6 %、DeepSWE で 81.6 % に達し、H100 GPU 上で Jev よりも 4～6 倍高速です。 |
ゼロショット精度：コンピュータ操作、ゲーム、ツール呼び出しのベンチマーク全体で Jev と同等の成功率。 |

仕組み（概要）

状態エンコーダーとアクションエンコーダーは、凍結された LLM バックボーン (Qwen-3-8B) であり、小さなトレーニング可能な投影ヘッド（約 20 M パラメータ）を備えています。 |
対照学習 – 双方向の InfoNCE 損失関数が、一致する状態とアクションのペアを引き寄せ、他のすべてのペアを遠ざけます。 |
トレーニング中期では、合成されたハードネガティブを追加して、きめ細かい識別能力を研ぎ澄まします。 |
トレーニング後期では、1 M のエージェントの軌跡でトレーニングを行い、モデルを実際の意思決定シーケンスに合わせます。 |
推論 – 状態を埋め込み、各候補アクションを埋め込み、ドット積の類似度を計算し、温度スケーリングされたソフトマックスを適用して、分布を返します。 |

拡張 / 微調整

リポジトリには、エンコーダーを凍結して投影ヘッドのみを更新する train/finetune.py スクリプトが含まれています。README のコマンド例：

# DeepSWE 検証結果の再現
python evaluation/bon_eval.py \
    --hf-dataset Contrastive-LM/deepswe-clm-embeddings-8k \
    --checkpoint heads/deepswe/best_head.pt \
    --tasks-file heads/deepswe/heldout_tasks.json -n 4 --window 12

# カスタムの型付き意思決定データセットでの微調整
python train/finetune.py --task choice \
    --data LocalLLaMA/typed-decisions --workflow all \
    --init-ckpt "$(clm-download)" --out-dir runs/typed

docs/FINETUNING.md ガイドでは、データ準備、ハイパーパラメータ、およびチェックポイント管理について詳しく説明しています。

ライセンスと可用性

コード – Apache 2.0 ライセンス (LICENSE を参照)。 |
モデルの重み – Apache 2.0、Hugging Face でホスト：Contrastive-LM/CLM-v0.1-8B。 |
コミュニティ – ブログ、Discord、および Hugging Face ハブへのリンクは、上部のナビゲーションバーにあります。 |

クイックリファレンス – API エンドポイント

POST /v1/systemone – 型付き意思決定リクエスト（状態 + 質問）。 |
POST /v1/rank – 候補アクションの生のランキング。 |
GET / – オプションの Web プレイグラウンド UI。 |
GET /v1/models – 利用可能なヘッドのリスト。 |

TL;DR: CLM-8B は、エージェント向けに高速で型付きの意思決定を提供する、対照学習された状態-アクション埋め込みモデルです。単一の pip コマンドでインストールし、軽量サーバーを実行して、Python、curl、または組み込み UI から呼び出します。独自のデータで小さな投影ヘッドを微調整して、新しいドメインに適応させることができます。