Cloudflare Clairic · Clairic-flash 오픈웨이트 아키텍처 해부: Parallel Slot 자기회귀·Clair 분포 헤드와 PDF/이미지 4장·과금 경계 점검하기
2026년 11월 18일 Cloudflare Workers AI Superintelligence 팀이 Apache-2.0 오픈웨이트로 공개한 System One 추출 모델 Clairic(27B)과 Clairic-flash(9B)의 내부 아키텍처와 제약 경계를 분석한다. 프리뷰의 단일 순전파에서 Parallel Slot 자기회귀(xgrammar) + 전용 Clair 분포 헤드(256 bins, p_null·p10~p90) 2계통 구조로의 전환, 이미지·PDF 페이지 합산 4장 제한과 RGBA 알파 합성 처리, 2026년 12월 1일 프로모션 종료 후 입력 토큰 단일 과금($0.24/M vs $0.10/M) 및 로컬 Python 스키마·계약 검증 스크립트를 정리한다.
Cloudflare Clairic 추상 표지 아트워크: 비정형 문서·이미지 입력이 System One 추출 코어를 거쳐 병렬 슬롯 구조화 필드와 확률 분포로 변환되는 개념 그래픽
Cloudflare의 Workers AI Superintelligence 팀이 2026년 11월 18일 공식 발표한 Clairic · Clairic-flash 오픈웨이트 릴리스는 비정형 텍스트·이미지·PDF에서 정형 값(텍스트·숫자·날짜·목록)을 추출하고 수치 추정(estimate)·시계열 예측(forecast)까지 수행하는 System One 추출 모델 패밀리다. 10월 프리뷰 당시 9B 모델 단일 엔드포인트(@cf/cloudflare/clairic)로 출발했던 구성을 이번에 27B 모델(Clairic, Qwen/Qwen3.8-27B 기반)과 신규 9B 경량 모델(Clairic-flash, Qwen/Qwen3.5-9B 기반)의 2종으로 분리하고, 가중치·프로세서·런타임 코드 전체를 Apache-2.0 라이선스로 Hugging Face에 공개했다.
핵심 아키텍처 판단 기준을 먼저 요약하면, 이번 정식 오픈웨이트 버전의 Clairic은 프리뷰 시절의 '순수 단일 순전파(Single Forward Pass)' 구조를 버리고 'Parallel Slot 자기회귀(xgrammar JSON Schema 로짓 제약) + 전용 Clair 분포 헤드(clair_head.safetensors)'의 듀얼 트랙 구조로 재설계됐다. 일반 텍스트·숫자·불리언·열거형·객체 행(list[object]) 필드는 각 필드가 독립 슬롯으로 분리되어 서빙 배치 안에서 동시에 다음 토큰을 생성·종료하고, 계산(compute)·날짜·시간·기간·추정(estimate)·예측(forecast)은 256개 빈(bin)과 라우팅 헤드(route_width=1024)를 갖춘 전용 헤드가 직접 확률 분포(p10~p90)와 독립 p_null 점수를 계산한다. Workers AI에서는 내부적으로 출력 토큰을 생성함에도 여전히 '입력 토큰 단일 과금(출력 토큰 $0)' 원칙을 유지하지만, 이미지와 렌더링된 PDF 페이지가 합산 최대 4장 슬롯과 개별 4 MiB·합산 8 MiB 한도를 공유하고, object 행 속성에는 date나 source_only를 중첩할 수 없으며, 2026년 12월 1일 프로모션 종료 후 27B Clairic 단가가 $0.10/M에서 $0.24/M으로 인상되는 경계를 도입 전 반드시 점검해야 한다. 이 글은 2026년 11월 20일 기준 Cloudflare 공식 블로그, Workers AI 모델 문서, 그리고 Hugging Face Cloudflare/clairic · Cloudflare/clairic-flash 저장소의 README.md, clair_head_config.json, clairic_model.py, clairic_runtime/ 소스 코드를 교차 검증해 정리한 내용이며, 자체 GPU 실측 벤치마크 대신 Cloudflare 공식 보고 지연 시간·정확도 지표와 로컬 Python 스키마·경계 검증 스크립트를 기준으로 설명한다.
1. 듀얼 트랙 실행 아키텍처: Parallel Slot 자기회귀와 전용 Clair 헤드
프리뷰 공개 이후 영수증 이미지·고객지원 티켓·다중 페이지 문서에서 복합 표(table)와 리스트 추출 정확도를 끌어올리기 위해, Cloudflare는 단일 순전파 일괄 디코딩을 2계통 하이브리드 구조로 교체했다.
Cloudflare Clairic · Clairic-flash 듀얼 트랙 아키텍처: 4장 공유 멀티모달 입력 제한, Qwen3.8-27B/Qwen3.5-9B 백본, Parallel Slot 자기회귀(xgrammar)와 전용 Clair 분포 헤드 분기 및 입력 토큰 단일 과금 구조
1.1 Parallel Slot 자기회귀 + xgrammar 제약 디코딩 (Track A)
- 필드 단위 슬롯 병렬 전진:
text,number,boolean,enum,object, 그리고 텍스트·객체 리스트(list)는clairic_runtime/ar.py및contracts.py경로를 탄다. 요청에 선언된 각 필드가 고유 슬롯으로 할당되며, 각 슬롯은 자신이 이미 출력한 토큰 시퀀스만 참조해 다음 토큰을 선택하고 자신의 종료 마커에 도달하면 즉시 멈춘다. 모든 슬롯이 서빙 배치 안에서 함께 전진하므로 일반 LLM처럼 전체 JSON 문자열을 직렬로 생성할 때보다 지연 시간이 크게 줄고, 인보이스 품목 행(list[object])처럼 여러 필드가 맞물리는 표 구조에서도 필드 간 간섭이 억제된다.
xgrammar로짓 프로세서와source_only: 생성 단계에는xgrammar기반 JSON Schema 제약이 로짓 레벨에서 적용되어minLength·maxLength·pattern·minimum·maximum·enum·nullable규칙을 강제한다. 숫자 정규화(normalize_number)는Decimal기반ROUND_HALF_UP반올림으로 지정 소수점 자리수(decimals)를 보정하며, 텍스트가 원문state에 유일하게 매칭될 때는 문자 오프셋(spans)까지 함께 반환한다.
1.2 전용 Clair 분포·연산 헤드 (Track B: clair_head.safetensors)
- 256-Bin 분포 예측과
compute헤드:compute,date,time,datetime,duration,estimate,forecast및 숫자·날짜 리스트는 별도 학습된 Clair 헤드(clair_head_config.json기준bins=256,pointer_width=256,route_width=1024,route_layers=2,route_heads=8,slot_rank=32)가 처리한다.Clairic(27B)는hidden_size=5120,Clairic-flash(9B)는hidden_size=4096으로 백본 차원만 다르며 헤드 라우팅 구조는 동일하다.
- 환각 대신
p_null과 80% 예측 구간(p10~p90) 반환: 모든 스칼라 답변은 전체 시퀀스confidence와 별개로 '입력 데이터가 해당 값을 결정하지 못할 확률'인p_null을 독립 계산한다.estimate는 선언된[min, max]범위(linear또는log스케일, 격자 최대1,000,000스텝) 위에서 중앙값과p10~p90구간(옵션include_quantiles: true시 99개 분위수)을 산출하며,forecast는 최대64스텝(step·minute·hour·day·week·month·quarter·year)까지 미래 시계열 분포를 펼쳐 응답한다.
2. 혼동하기 쉬운 6가지 기술·운영 경계와 모델 비교표
공식 블로그와 clairic_runtime 소스 코드(embedded.py, documents.py, contracts.py, clair_schema.py, clairic_model.py)를 교차 점검할 때 실무 개발자가 가장 자주 오해하는 경계는 다음 6가지다.
- 1) 이미지와 PDF 페이지가 '합산 4장' 슬롯을 공유한다:
documents.py의ClairDocument.render()는pypdfium2로 PDF 각 페이지를 이미지로 래스터화(scale = min(2.0, sqrt(4_000_000 / (width * height))))한 뒤 이미지 배열과 합쳐MAX_IMAGES = 4한도를 검사한다. 즉 이미지 1장과 4페이지 PDF를 함께 보내면 총 5장이 되어 즉시 거부된다. 또한 개별 파일(이미지·PDF 각각)은 디코딩 기준4 MiB, 전체 합산은8 MiB, 단일 이미지 해상도는16,000,000픽셀을 넘을 수 없으며, 원격 미디어 URL과 암호화된 PDF는 지원하지 않는다.
- 2) 투명 PNG(RGBA)의 흰 배경 합성 및 회전 규칙:
ClairImage.to_pil()은 알파 채널이 있는 이미지를 곧바로 RGB로 변환하지 않고 흰색("white") 캔버스에 알파 마스크로 합성한다. 투명 배경 위 검정 텍스트가 RGBA→RGB 직접 변환 시 검은 배경에 묻혀 사라지는 문제를 막기 위한 장치다. 회전은 EXIF 정렬 후0·90·180·270도 시계 방향만 허용되며, 명시하지 않으면orient_document()가 자동 방향 보정을 수행한다.
- 3)
object행 속성과source_only옵션의 비대칭 제약:contracts.py기준으로object(또는list[object]) 내부properties에는text,number,boolean,enum4종만 들어갈 수 있다. 따라서 영수증 품목 행 안에date나estimate를 중첩하면 검증 오류로 거부된다. 또한 원문 그대로 복사하도록 강제하는source_only: true는 스칼라number·date·time·datetime과date/number리스트에서만 동작하며,object행 속성·null_threshold·knowledge: true와는 함께 쓸 수 없다.
- 4) 컨텍스트 65,536 토큰 초과 시 에러가 아니라 조용한 절단(
truncated): Workers AI 스펙은65,536토큰(로컬load_release_model기본값max_length=65,273)이지만, 이를 넘겨도 요청이 실패하지 않고 입력 상태 텍스트가 잘린 채 추론이 실행된다. 운영 파이프라인에서는 반드시 응답의truncated플래그와 개별 필드의valid·complete·p_null을 함께 검사해야 누락 추출을 막을 수 있다.
- 5) 셀프호스팅 로컬
load_release_model()의 기본 동시성 1 제한: Hugging Face 저장소의clairic_model.py를 그대로 로드하면RuntimeSettings(..., max_concurrency=1)로 초기화된다. 따라서 FastAPI/비동기 워커에서 동시에 2개 이상 요청을predict_async()로 밀어 넣으면queue-full예외가 발생하므로, 프로덕션 셀프호스팅 시에는 서빙 큐잉이나 워커 풀 분리가 필수다.
- 6) 2026년 12월 1일
@cf/cloudflare/clairic엔드포인트 자동 승격 및 단가 인상: 기존 프리뷰 당시@cf/cloudflare/clairic에 연결돼 있던 9B 모델은@cf/cloudflare/clairic-flash($0.10/1M 입력 토큰)로 이동했고,@cf/cloudflare/clairic는 27B 모델로 제자리 업그레이드됐다. Cloudflare는 2026년 12월 1일까지 27B 모델도 $0.10/1M 프로모션 가격으로 제공하지만, 12월 1일 이후에는 $0.24/1M 입력 토큰으로 전환되므로 지연 시간·비용 민감 워크로드는 사전에clairic-flash로 엔드포인트를 분리해야 한다.
| 비교 항목 | Clairic (27B · 정식 오픈웨이트) | Clairic-flash (9B · 신규 경량) | Clairic-preview (10월 프리뷰) |
| 기반 모델 · 히든 크기 | Qwen/Qwen3.8-27B (hidden_size=5120) | Qwen/Qwen3.5-9B (hidden_size=4096) | 9B 프리뷰 변형 (비공개 가중치) |
| 실행 아키텍처 | Parallel Slot AR( xgrammar) + Clair 분포 헤드 | Parallel Slot AR( xgrammar) + Clair 분포 헤드 | 단일 순전파 (Single Forward Pass) |
| Workers AI 엔드포인트 · 과금 | @cf/cloudflare/clairic12/1까지 $0.10/M → 이후 $0.24/M 입력 (출력 $0) | @cf/cloudflare/clairic-flash상시 $0.10/M 입력 토큰 (출력 $0) | 구 @cf/cloudflare/clairic (대체됨)$0.10/M 입력 토큰 |
| 자체 벤치마크 정확도 (합성 영수증 · 고객 어설션) | 영수증 576/576 (0오류) · 어설션 1,263/1,263 혼합 입력 221/226 · 텍스트 335/336 | 영수증 576/576 (0오류) · 어설션 1,263/1,263 혼합 입력 213/226 · 텍스트 328/336 | 영수증 369/576 (207오류) · 어설션 1,033/1,263 혼합 입력 207/226 · 텍스트 295/336 |
| 자체 측정 지연 시간 (p50 / p95) | 텍스트 358 / 736 ms · 이미지 453 / 976 ms 상업용 리스 691/803ms · 대출 395/407ms | 텍스트 155 / 328 ms · 이미지 305 / 605 ms 상업용 리스 379/519ms · 대출 188/192ms | 단일 패스 초저지연 (복합 표·리스트 정확도 한계) |
| 멀티모달 · 라이선스 | 텍스트 + 이미지·PDF 합산 4장 · Apache-2.0 | 텍스트 + 이미지·PDF 합산 4장 · Apache-2.0 | 텍스트 + 이미지 (PDF 미지원 · 클로즈드) |
3. 실전 Workers AI 연동과 로컬 Python 계약 사전 검증 스크립트
3.1 Workers AI 바인딩 및 Hugging Face 로컬 추론 흐름
Cloudflare Workers에서는 env.AI.run()으로 기존 스키마 그대로 호출할 수 있고, 온프레미스·GPU 서버에서는 snapshot_download()와 systemone() 헬퍼로 동일한 페이로드를 실행할 수 있다.
3.2 Python 표준 라이브러리 기반 Clairic 스키마·멀티모달·과금 사전 검증기
실제 GPU 서버나 Workers AI에 요청을 보내기 전에, 필드 계약(contracts.py·clair_schema.py), 이미지+PDF 4장 공유 슬롯 및 4 MiB/8 MiB 바이트 한도, 듀얼 트랙 실행 경로 분기, 로컬 동시성 1 제한, 그리고 2026년 12월 1일 프로모션 전후 과금을 로컬에서 사전 점검하는 Python 스크립트(verify_cloudflare_clairic.py)다.
로컬 Python 3 실행 결과, 듀얼 트랙(Parallel Slot AR vs Clair Head) 라우팅 분기, 2026년 12월 1일 프로모션 전후 입력 토큰 단가($0.10/M → $0.24/M), 65,273 토큰 초과 절단·이미지/PDF 5장 초과·8 MiB 초과·암호화 PDF·로컬 동시성 초과·object 내 date 중첩·source_only 충돌 등 15가지 위반 탐지, 그리고 정상 인보이스+3페이지 PDF 복합 스펙의 무오류 통과(ALL CHECKS PASSED)를 모두 확인했다.
4. 실무 도입 및 운영 점검 체크리스트
워크로드별 모델 및 엔드포인트 분리: 지연 시간과 비용이 민감한 대량 텍스트·영수증 추출은 @cf/cloudflare/clairic-flash(9B, 상시 $0.10/M)로 고정하고, 복합 다중 페이지 표·고난도 추론 추출만 @cf/cloudflare/clairic(27B)를 사용한다. 2026년 12월 1일 프로모션 종료 후 27B 단가가 $0.24/M으로 전환됨에 유의한다.
이미지·PDF 4장 슬롯과 용량 사전 분할: 입력 이미지와 PDF 페이지 총합이 4장을 넘지 않도록 업로드 단계에서 페이지를 분할·선별하고, 개별 파일 4 MiB·합산 8 MiB·암호화 여부를 검사해 원격 URL이 아닌 base64 data URI로 전달한다.
p_null·confidence·truncated 3중 게이트 적용: answers[field]의 값만 읽지 말고 truncated == false 여부와 p_null 임곗값(예: 0.2 이하), confidence 하한을 애플리케이션 수용 기준으로 강제해 절단·결측 오류를 걸러낸다.
스키마 계약 준수 및 source_only 구분: object 행 속성은 text·number·boolean·enum만 허용되므로 날짜·계산 필드는 최상위 스키마로 분리하고, 계산이 필요한 합계는 compute를, 원문 숫자/날짜 그대로의 추출은 source_only: true를 지정한다.
셀프호스팅 시 동시성 및 pypdfium2·xgrammar 런타임 준비: Hugging Face 가중치(Apache-2.0)를 직접 서빙할 때는 Python 3.11+ 환경에 xgrammar와 pypdfium2를 포함하고, load_release_model()의 기본 max_concurrency=1 제약을 고려해 배치 큐 또는 다중 워커 프로세스로 감싼다.
5. 참고 자료 및 공식 출처 (2026-11-20 확인)
확인 기준일: November 20, 2026