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 参数投影头。这两个投影头通过对比 (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	支持三种问题类型 – `Noul`（二进制概率）、`Choice`（带 softmax 的分类）和 `Score`（有序评分）。
快速排序	`Engine.rank(state, candidates)` 可在进程内对任意候选列表进行评分，适用于 Best-of-N 选择、工具调用或检索排序。
缓存感知	动作嵌入会被缓存；重复的状态会重用相同的向量，从而减少 token 数量和延迟。
零样本	无需特定任务的提示工程 – 只需提供状态文本和候选动作集。
微调	可在您自己的数据集上对轻量级投影头进行微调（参见 `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 条智能体轨迹上进行训练，使模型与真实的决策序列对齐。 |
推理 – 嵌入状态，嵌入每个候选动作，计算点积相似度，应用温度缩放的 softmax，并返回分布。 |

扩展/微调

该仓库包含一个 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 调用它。在您自己的数据上微调微小的投影头，以使其适应新领域。