Cloudflare Clef를 내 PC에서 실행하려면? 27B·9B 선택과 SystemOne 사용법

결제 오류로 고객이 도움을 요청했다고 해 볼게요. 문의 내용이나 JSON 주문 기록을 state에 넣고, 긴급 여부와 담당 부서를 묻는 questions를 함께 보내면 Clef가 선택 결과와 선택지별 확률을 돌려줘요. 애플리케이션은 그 결과로 티켓을 분류하거나 사람 검토 대기열에 보낼 수 있어요.

Cloudflare의 Clef와 Clef-Flash는 자유형 문장을 계속 생성하는 챗봇이 아니라 typed question에 답하는 decision model이에요. noul은 참일 확률, choice는 정해 둔 이름 중 선택, score는 순서가 있는 수준 평가를 돌려줘요. 결과를 받아 다음 동작을 하는 부분은 호출하는 코드가 맡아요.

두 모델 모두 텍스트, JSON, 이미지, 비디오를 상태로 받을 수 있고 Jev/SystemOne API와 호환돼요. 문서 작성이나 상담 답변처럼 긴 문장을 새로 써야 하면 생성형 LLM⁵을 연결하고, 어떤 경로로 보낼지 판단하는 단계를 Clef에 맡기는 구성이 맞아요.

Clef는 Qwen3.8-27B 기반 27B 모델이고 Clef-Flash는 Qwen3.5-9B 기반 9B 모델이에요. Cloudflare는 더 정밀한 선택이 필요한 작업에는 Clef를, 지연을 줄여야 하는 작업에는 Clef-Flash를 제안해요. 두 모델은 이미지와 비디오 입력도 지원해요.

개인용 Apple Silicon Mac에서는 oMLX의 MLX 체크포인트로 시작할 수 있어요. Jundot/clef-oQ4e는 27B 모델로 파일 크기가 약 17GB이고, Jundot/clef-flash-oQ4e는 9B 모델로 약 6.28GB예요. 입력 이미지와 작업 메모리까지 쓸 여유를 남겨 모델을 골라요. 두 체크포인트는 Apache-2.0 라이선스로 배포돼요.

Cloudflare의 원본 모델 카드는 torch 2.11, transformers 5.10.2, 단일 H200에서 검증한 SGLang 예제를 제공해요. 이 카드는 서버 실행의 기준이고, Mac 경로는 oMLX 0.7.1.dev1이 decision 모델을 자동 감지하는 별도 실행 방법이에요.

oMLX 0.7.1.dev1은 Apple Silicon과 macOS 15 이상을 지원해요. 공식 릴리스에서 현재 macOS에 맞는 DMG를 내려받아 Applications에 설치한 뒤 앱을 열어요. 환영 화면에서 모델 폴더와 서버를 설정해요.

앱 대시보드의 Model Downloader에서 Jundot/clef-flash-oQ4e 또는 Jundot/clef-oQ4e를 검색해 내려받아요. Clef-Flash는 약 6.28GB, Clef는 약 17GB예요. 대시보드에 모델을 내려받으면 oMLX가 설정 폴더의 모델을 스캔해 decision 유형으로 자동 감지해요. 모델 폴더에 기존 파일을 수동 복사했다면 서버를 재시작해 새 모델을 인식시켜요.

기본 서버 주소는 http://127.0.0.1:8000이에요. 브라우저에서 /admin을 열고 서버 설정의 API 키를 저장해요. 같은 키를 뒤의 curl 요청에 넣으면 로컬 서버 인증을 확인할 수 있어요.

서버가 실행되면 브라우저에서 http://127.0.0.1:8000/admin을 열어 모델이 표시되는지 확인해요. oMLX 앱은 메뉴 막대에서 서버를 시작하고 상태를 볼 수 있어요.

터미널에서 별도 서버를 직접 시작하려면 DMG 앱이 설치한 CLI⁶ shim을 사용해요. 먼저 앱 관리 서버를 중지하고, --model-dir에는 Welcome 화면에서 선택한 것과 같은 모델 폴더를 지정해요. CLI를 따로 설치할 필요는 없어요.

~/.omlx/bin/omlx serve --model-dir "/PATH/TO/SELECTED_MODEL_DIRECTORY" --api-key "YOUR_OMLX_API_KEY" --host 127.0.0.1 --port 8000

먼저 API 키로 /v1/models를 조회하고 응답의 data[].id 값을 복사해요. 모델 폴더나 별칭 설정에 따라 ID 표기는 달라질 수 있어요.

curl http://127.0.0.1:8000/v1/models -H 'Authorization: Bearer YOUR_OMLX_API_KEY'

복사한 값을 YOUR_DECISION_MODEL_ID에 넣어 SystemOne 요청을 보내요. API 키도 앞에서 설정한 값으로 바꿔요.

curl http://127.0.0.1:8000/v1/systemone -H 'Authorization: Bearer YOUR_OMLX_API_KEY' -H 'Content-Type: application/json' -d '{
  "model": "YOUR_DECISION_MODEL_ID",
  "state": "결제가 한 시간째 실패해 모든 고객의 주문이 막혔습니다.",
  "questions": {
    "urgent": {"type": "noul", "instructions": "이 요청은 긴급한가요?"},
    "team": {"type": "choice", "instructions": "어느 팀이 처리해야 하나요?", "criteria": {"billing": "결제와 환불", "technical": "장애와 오류", "sales": "요금제와 업그레이드"}}
  }
}'

성공하면 answers.urgent에 긴급 여부의 확률이, answers.team에 선택한 팀과 선택지별 확률이 표시돼요. 27B 모델을 쓸 때는 /v1/models 응답에서 그 모델의 실제 data[].id를 복사해 YOUR_DECISION_MODEL_ID에 넣어요. 티켓을 자동 분류할 기준과 사람이 다시 볼 확률은 연결한 앱에서 정해요.

데이터센터용 H200에서 원본 체크포인트를 서버로 실행하려면 Cloudflare 모델 카드의 SGLang 예제를 쓸 수 있어요. Docker에 NVIDIA GPU⁷ 접근이 설정된 Linux에서 실행하고, 모델 파일은 Hugging Face에서 처음 내려받아요.

docker run --gpus all --shm-size 32g -p 127.0.0.1:30000:30000 -v ~/.cache/huggingface:/root/.cache/huggingface --ipc=host lmsysorg/sglang:dev-clef sglang serve --model-path Cloudflare/clef --host 0.0.0.0 --port 30000

Clef-Flash를 띄우려면 명령의 --model-path Cloudflare/clef를 --model-path Cloudflare/clef-flash로 바꿔요. 이 경로는 모델 카드가 시험한 단일 H200 환경을 기준으로 하며, 호스트 포트는 localhost에만 바인딩해요. 개인용 Mac의 기본 경로는 앞 절의 oMLX예요.

oMLX가 모델을 목록에 표시하지 않으면 Model Downloader에서 저장소 ID를 다시 검색해요. 수동으로 파일을 옮겼다면 파일이 설정한 모델 디렉터리 안에 있는지 확인한 뒤 서버를 재시작해요.

401 응답이 나오면 앱에서는 /admin에 저장한 API 키, CLI에서는 --api-key 값을 요청의 Authorization: Bearer 값과 비교해요. 모델 파일을 찾지 못한다는 오류가 나면 Hugging Face에서 선택한 저장소 ID와 로컬 모델 폴더를 확인해요. Clef 체크포인트의 joint_head.safetensors와 joint_head_config.json도 가중치와 함께 있어야 해요.

서버가 켜져도 요청 오류가 나면 주소가 /v1/systemone인지, model에 /v1/models에서 확인한 ID를 넣었는지, questions 안에 typed question이 있는지 확인해요. 이미지·비디오 요청은 먼저 텍스트 요청이 성공한 뒤 추가해요.