max_pixels는 위장된 토큰 예산입니다 — 적절한 제한 값은 찾고자 하는 대상의 크기에 따라 달라집니다

동일한 이미지를 서로 다른 런타임(runtime)에서 동일한 Qwen2.5-VL 모델로 실행하면, 선택한 추론 스택(inference stack)에 따라 8개에서 16,384개의 시각적 토큰 (visual tokens) — 즉, 2,000배의 차이 — 이 소모될 수 있습니다. 아무도 모델을 변경하지 않았습니다. 그들은 단지 하나의 설정 값인 max_pixels에 대해 의견이 다를 뿐입니다.

이 포스트는 세 가지 내용을 담고 있습니다: max_pixels를 이해하기 쉽게 만드는 한 줄의 정의, 최적의 제한 값은 찾으려는 대상의 크기에 따라 달라진다는 것을 보여주는 정확하게 측정된 정확도 대비 예산 곡선(accuracy-vs-budget curves), 그리고 모든 주요 런타임이 무엇을 기본값으로 사용하는지에 대한 조사입니다.

요약 (TL;DR) — max_pixels ÷ 28²이 당신의 이미지 토큰 예산입니다. 벤더(vendor)는 1,280개 이하의 토큰을 권장하지만, 대부분의 런타임은 조용히 16,384개를 제공합니다. 실제 4K 스크린샷으로 측정한 결과: 큰 대상(패널)은 1,280개에서 정점을 찍으며, 더 많은 토큰은 오히려 성능을 악화시킵니다. 작은 대상(아이콘)은 토큰이 늘어날수록 계속해서 성능이 향상됩니다. 제한 값을 당신이 사냥하려는 대상의 크기에 맞게 설정하세요.

max_pixels 해독하기: 한 줄의 수학

Qwen-VL 모델은 두 단계에 걸쳐 픽셀을 토큰으로 변환합니다. 비전 트랜스포머(vision transformer)는 이미지를 겹치지 않는 **14×14 px 패치 (patches)**로 나눕니다. 그런 다음 작은 MLP가 인접한 패치들의 모든 2×2 블록을 하나의 토큰으로 병합합니다. 이 두 과정을 조합하면 각 LLM 토큰은 이미지의 연속적인 28×28 px 사각형을 차지하게 됩니다:

factor = patch_size × merge_size          # Qwen2/2.5-VL의 경우 28, Qwen3-VL의 경우 32
tokens = (W × H) / factor²                # 면적 ÷ 토큰당 면적

이는 모든 설정이 제공하는 max_pixels 값이 큰 숫자의 탈을 쓴 토큰 제한(token cap)일 뿐임을 의미합니다:

max_pixels = max_tokens × factor²

Qwen2.5-VL 체크포인트의 기본값을 이를 통해 해독해 보겠습니다: max_pixels = 12,845,056 = 16,384 × 28². 이는 16,384-토큰의 이미지 예산입니다. 모델 카드(model card)에서 권장하는 범위는 256–1,280 토큰입니다. 출시된 기본값은 권장 상한선의 12.8배에 달합니다. 그리고 smart_resize는 오직 상한선(cap)에 맞춰 다운스케일링(downscale)만 수행하기 때문에, 충분히 큰 모든 이미지는 모델이 튜닝되지 않은 해상도로 조용히 실행됩니다.

(권장되는 토큰 예산은 전체 Qwen-VL 라인업에서 동일합니다. 모델마다 factor만 변경됩니다 — 28 대 32. 따라서 Qwen3-VL의 권장 픽셀 상한은 1,003,520이 아니라 1280 × 32² = 1,310,720입니다. 토큰 숫자는 이식 가능한(portable) 수치이지만, 픽셀 숫자는 그렇지 않습니다.)

그렇다면 적절한 상한선은 무엇인가? 잘못된 질문입니다 — 어떤 대상을 위한 것인가가 핵심입니다.

이전 기사에서는 이 상한선이 그라운딩(grounding)을 위한 핵심 전처리 변수임을 입증했습니다 (1,280으로 제한하는 것만으로도 고해상도 스크린샷에서의 평균 IoU가 0.54에서 0.74로 상승했습니다 — 해당 글의 Bug #5 참조). 이 포스트에서는 다음 질문을 던집니다: 1,280이 모든 상황에 적절한가?

저는 먼저 당연한 후속 조치로 — 예산을 훑으며(sweep) 변곡점(knee)을 찾는 실험을 진행했고 — 명확한 답을 얻었습니다. 하지만 단 하나의 변수, 즉 프레임 대비 대상의 크기를 통제하는 순간 그 답은 무너졌습니다. 그래서 여기, 유효한 실험 결과를 제시합니다.

설정(Setup). Apple Silicon (mlx-vlm) 환경에서 Qwen2.5-VL-7B-4bit를 사용하였으며, ScreenSpot-Pro (26개의 전문 앱)의 실제 ~4K 스크린샷을 대상으로 그라운딩을 수행했습니다. 0.1% 미만의 아이콘(ScreenSpot-Pro의 자체 휴먼 어노테이션 대상)부터 5% 이상의 패널 및 캔버스에 이르기까지 크기 스펙트럼을 아우르는 200개의 대상 요소를 포함했습니다. 예산은 256 / 1,280 / 4,096 / 16,384 토큰으로 설정하였으며, 지표는 참조 박스(reference box)에 대한 IoU입니다.

대형 대상 참조 데이터의 출처 (ScreenSpot-Pro에는 본질적으로 대형 대상 어노테이션이 거의 없습니다 — 가장 큰 것이 프레임의 4.7%입니다):

1. 모델은 각 화면에서 인식한 명명된 영역(named regions)을 **제안(proposes)**합니다.
2. 각 제안은 네이티브 해상도(native resolution)에서의 독립적인 줌인(zoom-in) 패스를 통해 **재위치 확인(re-localized)**됩니다.
3. 모든 요소는 **모호성 스크리닝(ambiguity screen)**을 통과해야 합니다. 만약 해당 요소의 설명이 동일한 화면 내의 다른 영역과도 일치하거나, 크롭(crop) 수준의 검증을 통과하지 못하면 제외됩니다.

이 스크리닝 과정에서 후보의 64%가 제거되었습니다.

이 스크리닝은 결벽증적인 절차가 아니라, 시스템을 지탱하는 핵심 요소입니다. 모호한 설명은 단순히 노이즈를 추가하는 것에 그치지 않고, 높은 예산(high-budget)에 대한 페널티를 _체계적으로 조작(systematically fakes)_합니다. 즉, 낮은 예산에서는 모델이 가장 두드러진 후보 하나를 선택하지만, 높은 예산에서는 갑자기 다른 일치 항목을 식별하여 대신 박싱(box)할 수 있게 됩니다. 오염된 하위 집합(contaminated subset)에서 높은 예산으로 인한 하락 폭은 -30%였습니다. 정제된 집합(cleaned set)에서는 -18%였습니다. 우리가 주장하는 수치는 정제된 수치입니다.

결과 — 대상의 크기가 작아질수록 피크(peaks)는 바로 이동합니다:

대상 크기	n	GT 출처	256	1,280	4,096	16,384	최적값 (optimum)
대형 (>프레임의 5%)	36	감사됨 (audited)	0.343	0.643	0.574	0.526	1,280
...
Four IoU-vs-token-budget curves, one per target-size bin; peaks shift right as targets shrink

두 가지 실패 방향이 존재하며, 이들은 서로 다른 크기 영역(size regimes)에 속합니다:

1. 대형 대상은 ~1,280 토큰 이상에서 성능이 저하됩니다 (-16k에서 IoU -18%, 감사됨 — 그리고 이 4K 이미지들에 대해 쿼리당 9.7초에서 62초로 증가, 즉 6배의 지연 시간(latency) 세금이 발생합니다). 실패 모드는 구체적입니다. 모델은 여전히 패널을 찾아내지만 (click-through-center는 0.86에서 0.75로 유지됨), 예측된 박스가 실제 경계를 벗어나 표류(drift)합니다. 토큰이 많아질수록 기하학적 구조(geometry)는 더 나빠집니다.
2. 미세한 대상은 성능 향상이 멈추지 않습니다. 이들의 곡선은 모델의 아키텍처 한계점(architectural ceiling)에서도 여전히 상승 중입니다. 4K 프레임에서 수십 픽셀 너비의 아이콘은 대형 대상 영역에서 정상이라고 간주될 법한 어떤 예산에서도 형체를 잃고 흩어져 버립니다.

왜 더 많은 디테일이 오히려 해질까요? 여기서 예산(budget)은 연산 제한(compute limit)이 아니라 분포 제한(distribution limit)입니다. 16,384 토큰은 모델이 튜닝된 범위를 12배나 초과한 수치이며, 위치 통계(position statistics)가 해당 범위를 벗어나 표류하기 시작할 때 가장 먼저 무너지는 것이 바로 장거리 박스 기하학(long-range box geometry)입니다.

따라서 모델 카드(model card)에 명시된 1,280이라는 수치는 보편적인 최적점(sweet spot)이 아닙니다. 이는 **대형 대상에 대한 최적값(large-target optimum)**이자, 두 체제(regimes)가 서로 자리를 바꾸는 교차점입니다. 만약 대상이 패널(panels)이라면 1,280이 정확히 맞습니다. 하지만 대상이 4K 화면 위의 아이콘이라면, 고정된 상한선(flat cap) 중 정답인 것은 없습니다. 이것이 바로 현재의 연구 흐름(아래에서 더 자세히 설명)이 해상도를 높이는 대신 줌(zoom)을 사용하는 이유입니다.

솔직한 범위(scope)에 대한 참고 사항: 하나의 모델 제품군, 하나의 작업 제품군(UI grounding)을 대상으로 하며, 대형 대상 참조값은 모델에 고정(model-anchored)되어 있습니다(검증은 되었으나 제3자 인간 라벨은 아닙니다. 대형 UI 영역에 대한 인간 라벨은 존재하지 않기 때문입니다. 작거나 아주 작은 행(rows)은 순수하게 인간의 GT(Ground Truth)를 따릅니다). 중간/작은 크기 범주(bins)는 표본이 적습니다(n=8/9). 그리고 방법론 자체에 대한 한 가지 발견이 있습니다: 요소(elements)를 제안하라는 요청을 받았을 때, 모델은 본질적으로 은 것들을 고유하게 명명할 수 없습니다. 모델이 제안한 148개 요소 중 단 2개만이 아주 작았습니다. 따라서 아주 작은 크기 범주는 ScreenSpot-Pro의 인간 주석(human annotations)에 의존합니다.

이것은 새로운 단위로 표현된 오래된 법칙입니다

“최적의 스케일(scale)은 대상의 크기에 따라 달라진다”는 말이 익숙하게 들린다면, 당연한 결과입니다. 다른 분야에서는 이미 수년 전에 이를 측정해 왔습니다. 객체 탐지(Object detection): SNIP (CVPR 2018)는 고해상도에서 큰 객체들이 “정확하게 분류되기에는 너무 커진다”는 것을 보여주었으며, HRDNet은 입력 해상도가 두 배로 증가할 때 대분류 AP(Average Precision)가 7.6포인트 하락하는 것을 측정했습니다. 항공 이미지(Aerial imagery): SAHI는 작은 객체를 위해 이미지를 타일링(tiling)하지만, 특히 큰 객체들을 복구하기 위해 전체 프레임 추론(full-frame inference)을 다시 추가해야만 합니다. 이 원리는 스케일 공간 이론(scale-space theory)의 “특성 스케일(characteristic scale)” (Lindeberg, IJCV 1998)과 일맥상통합니다. 즉, 모든 구조물은 가장 잘 탐지되는 하나의 스케일을 가지고 있습니다.

제가 찾은 바로는, 화면상의 대상 크기별로 분류된 VLM 토큰 예산(token-budget) 단위의 곡선은 지금까지 존재하지 않았습니다. 관련 연구들은 각각 별도로 발표되었습니다: Phi-Ground는 토큰 예산에 따른 절제 연구(ablation)를 측정했으나(약 2k 이후 정체, 크기별 분류 없음), AdaZoom-GUI는 무조건적인 줌(unconditional zoom)이 쉬운 대상에게 해를 끼친다는 것을 측정했습니다; Qwen의 자체 보고서(Table 7)는 업스케일링(upscaling) 측면에서의 분포 외(off-distribution) 메커니즘을 확인했습니다; 저는 mlx-vlm #1175에서 출시된 기본 설정값의 불일치를 보고했습니다. 이 포스트는 이들을 하나로 연결하는 크기별 분류 곡선을 추가합니다. 점들을 발견하는 것이 아니라, 점들을 연결하는 것입니다.

이는 또한 왜 2025–26년 GUI-그라운딩(GUI-grounding) 문헌들(ZoomClick, UI-Zoomer, MEGA-GUI, AdaZoom-GUI)이 ‘거친 패스 후 조건부 줌(coarse-pass-then-conditional-zoom)’ 방식으로 수렴했는지를 설명해 줍니다. 즉, 적절한 제한(cap) 내에서의 첫 번째 패스가 큰 대상에 대한 최적값이며 거칠게 위치를 파악(localize)하고, 줌 패스가 크롭(crop) 내부의 작은 대상들에게 높은 유효 해상도를 제공하는 방식입니다. 위 곡선은 사실상 이러한 정책들이 임시방편적인 탐색(ad-hoc sweep)을 통해 선택해 온 동작 지점(operating-point) 표라고 할 수 있습니다.

모든 런타임이 실제로 기본값으로 설정하는 것

모든 주요 스택은 동일한 리사이즈 알고리즘(HF의 smart_resize, 때로는 그대로 가져와 사용됨)을 구현하지만, 각기 다른 예산(budget)을 선택합니다:

동일한 모델, 동일한 알고리즘임에도 기본값이 세 자릿수(three orders of magnitude) 차이가 납니다. 만약 사용하는 서빙 스택(serving stacks)에 따라 Qwen-VL의 그라운딩(grounding) 정확도가 다르다면, 가중치(weights)를 의심하기 전에 이 값을 먼저 확인하십시오. 부풀려진 기본값은 오직 '큰' 입력값에서만 문제를 일으키기 때문에 위험합니다. 1080p 스크린샷으로 테스트하면 모든 것이 정상처럼 보이지만, 패널(panel)을 찾아야 하는 Retina 캡처 이미지를 입력하면 박스(boxes)들이 조용히 비대해집니다.

실제로 해야 할 일

• 자신의 크기 체계(size regime)를 파악한 후, 표를 참고하여 제한(cap)을 설정하십시오. 패널, 창, 레이아웃 영역: max_pixels = 1280 × factor² — 이제 측정된 근거가 있는 벤더 수치(vendor number)입니다. 일반적인 스크린샷의 버튼 및 필드: ~2–4k 토큰 정도의 여유 공간을 두십시오. 4K의 아이콘: 고정된 제한(flat cap)으로는 해결할 수 없습니다. 지연 시간(latency)이 허용하는 범위 내에서 예산을 설정하거나, 위 논문들처럼 '거칠게 탐색 후 확대(coarse-then-zoom)'하는 방식을 사용하십시오.
• 대상(targets)이 클 경우, 큰 이미지가 제한 없이 5k 이상의 영역으로 진입하게 두지 마십시오 — 곡선(curve)을 보면 정확도를 '잃는' 대가로 지연 시간이 6배 증가함을 알 수 있습니다.
• 런타임별 대응: transformers/vLLM/SGLang — 체크포인트 설정(checkpoint config)을 신뢰하기보다 max_pixels를 명시적으로 전달하십시오 (예: mm_processor_kwargs). llama.cpp — 경고 메시지에 명시된 대로 하한선(floor)을 높이십시오 (--image-min-tokens 1024). Ollama 및 현재의 mlx-swift-lm — 이미 큰 대상에 최적화되어 있습니다; 작은 대상 작업(small-target workloads)을 위해서는 의도적으로 높여주십시오.
• 모델 간에 픽셀 수(pixel numbers)를 그대로 복사하지 마십시오 — Qwen3의 factor는 32이므로, 동일한 토큰 예산이라도 max_pixels 값은 달라집니다.

출처 (Provenance)

이 프로젝트는 macOS의 Swift에서 Qwen2.5-VL grounding을 네이티브로 작동시키는 작업을 진행하던 초기 프로젝트에서 시작되었으며, 이 과정에서 픽셀 제한(pixel cap)이 전처리 과정의 핵심적인 변수임이 밝혀졌습니다. 기본값을 권장 예산(recommended budget)으로 변경하는 사항은 mlx-swift-lm #243에 업스트림(upstream)으로 병합되었습니다. 스윕 하네스(sweep harness), 감사 판정(audit verdicts)이 포함된 요소 세트, 그리고 테스트별 원시 결과는 재현 가능합니다. 예산 계산 방식은 모든 모델의 preprocessor_config.json에서 두 줄만 확인하면 검증할 수 있습니다.

만약 Qwen-VL 모델을 서빙하는 런타임을 유지하면서 기본값인 16,384를 그대로 사용하고 있다면, 해결 방법은 단 한 줄이며, 이를 통해 사용자의 큰 대상에 대한 grounding 성능이 향상되고 6배 더 빨라집니다.