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)을 기반으로 하며, 상태와 작업을 위해 각각 20M 파라미터의 경량 프로젝션 헤드를 추가하여 구축되었습니다. 이 두 헤드는 수백만 개의 질문-답변 쌍, 합성된 하드 네거티브, 그리고 에이전트 궤적을 사용하여 대조(InfoNCE) 손실 함수로 학습되었습니다.

중요성 – 상태와 작업 임베딩을 분리함으로써 CLM은 작업 벡터를 캐시하고 여러 상태에서 재사용할 수 있습니다. 이를 통해 추론 비용이 저렴해지며, 동급 에이전트(예: Jev)보다 최대 9배 빠르면서도 컴퓨터 사용, 게임, 도구 호출 벤치마크에서 비슷하거나 더 나은 성공률을 달성합니다. 또한 에이전트 코딩 벤치마크에서 검증기로서 탁월한 성능을 발휘하여 Terminal-Bench 2.1(87.6%) 및 DeepSWE(81.6%)에서 새로운 SOTA를 기록했습니다.

시작하기

# 클라이언트 라이브러리 설치
pip install contrastive-lm

서비스 실행

vllm을 사용하여 인코더(Qwen-3-8B 풀링 모델)를 시작합니다:

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 서비스 제공
```
첫 실행 시 75MB의 "헤드" 체크포인트가 자동으로 다운로드됩니다.

간단한 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`(소프트맥스 포함 범주), `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)이며, 학습 가능한 작은 프로젝션 헤드(약 20M 파라미터)를 갖추고 있습니다. |
대조 학습 – 양방향 InfoNCE 손실 함수가 일치하는 상태-작업 쌍을 서로 가깝게 만들고 다른 모든 쌍을 멀어지게 합니다. |
학습 중기에는 합성된 하드 네거티브를 추가하여 세밀한 식별 능력을 강화합니다. |
학습 후기에는 1M 개의 에이전트 궤적을 사용하여 모델을 실제 의사결정 시퀀스에 맞춥니다. |
추론 – 상태를 임베딩하고, 각 후보 작업을 임베딩하고, 내적 유사도를 계산하고, 온도 스케일링된 소프트맥스를 적용하여 분포를 반환합니다. |

확장 / 미세 조정

저장소에는 인코더를 고정하고 프로젝션 헤드만 업데이트하는 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 / – 선택적 웹 플레이그라운드 UI. |
GET /v1/models – 사용 가능한 헤드 목록. |

TL;DR: CLM-8B는 에이전트를 위한 빠르고 유형화된 의사결정을 제공하는 대조 학습된 상태-작업 임베딩 모델입니다. 단일 pip 명령으로 설치하고, 경량 서버를 실행한 다음, Python, curl 또는 내장 UI에서 호출하세요. 자체 데이터로 작은 프로젝션 헤드를 미세 조정하여 새로운 도메인에 적응시킬 수 있습니다.