다양한 지표에 걸친 transformers 리비전(revisions) 벤치마킹

이 글은 사람이 작성한, 에이전트(agent) 중심의 블로그 포스트입니다.

코딩 에이전트(Coding agents)는 점점 더 우리 대신 우리의 소프트웨어와 함께 작업합니다. 작업을 설명하면, 에이전트가 라이브러리를 선택하고, 호출(calls)을 작성하며, 이를 실행하고, 자신의 실수를 디버깅(debug)합니다. 라이브러리가 방해가 되면, 에이전트는 기꺼이 이를 우회하여 로직을 처음부터 다시 작성할 것입니다. 이는 라이브러리 개발에 있어 새로운 개념을 도입합니다. 코드는 단지 정확하고 빨라야 할 뿐만 아니라, 에이전트가 이를 효과적으로 제어할 수 있도록 설계되어야 합니다. 투박한 API나 오래된 문서는 우리 개발자들을 짜증 나게 하지만, 이제는 에이전트를 더 길고 비용이 많이 드는 경로로 빠지게 만듭니다.

대부분의 벤치마크(benchmarks)는 단지 최종 답변만을 확인합니다. 우리는 그 과정 전체를 원했습니다. 즉, 에이전트가 정답을 맞혔는지뿐만 아니라, 그곳에 도달하기 위해 얼마나 많은 작업이 필요했는지, 그리고 그것이 모델, 라이브러리 리비전(revisions), 그리고 작업(tasks)에 따라 어떻게 변하는지를 보고 싶었습니다. 우리는 transformers를 사례 연구(case study)로 사용하여 바로 그 점을 측정했습니다.

여기에서 우리는 답변이 어떻게 찾아졌는지에 초점을 맞춘 툴 전용 벤치마크를 소개하고, pi 코딩 에이전트(pi coding agent)에 의해 구동되는 오픈 모델(open models)로 완전히 실행되는 이러한 하네스(harness) 중 하나의 간단한 구현을 제공할 것입니다. 모든 실행이 동일한 하드웨어를 볼 수 있도록 모델 × 리비전 × 작업의 전체 범위를 Hugging Face Jobs에 펼쳐서 실행합니다.

하지만, 에이전트를 위해 소프트웨어를 어떻게 최적화할 것인가?

우리는 다음 두 가지 소프트웨어 원칙을 강력하게 믿습니다:

• 테스트되지 않았다면, 그것은 작동하지 않는 것이다
• 문서화되지 않았다면, 그것은 존재하지 않는 것이다

이는 에이전트 최적화 툴링(agentic-optimized tooling)의 영역에서도 동일하게 유지되며, 이번에는 이 두 가지가 서로 직접적으로 연결되어 있습니다.

당신은 에이전트가 당신의 툴을 사용할 수 있기를 원합니다. 즉, 발견 가능(discoverable)해야 합니다. API는 명확해야 하고 문서는 광범위해야 합니다. 에이전트가 유용한 파일과 예제에 빠르게 접근할 수 있는 방식으로 구조화되어야 합니다. 당신의 툴이 에이전트에게 제대로 작동하기를 원한다면, 에이전트 사용(agentic-use)을 위해 테스트해야 합니다.

우리는 transformers를 사용할 것입니다.

이 블로그 포스트 전반에 걸쳐 예시로 사용할 것입니다: 즉, transformers에 코드를 기여하는 것이 아니라, ML 작업(텍스트 분류, 이미지 캡셔닝, 오디오 전사)을 해결하기 위해 이를 사용하는 에이전트입니다. 비록 이 하네스(harness)는 명령줄(command line)에서 작동할 수 있는 모든 도구와 함께 작동하도록 설계되었지만 말입니다.

transformers에 대한 우리의 직관은 몇 가지 변화, 즉 CLI, 스킬(Skill), 그리고 독립적인 작업별 예제들을 통해 사용법을 획기적으로 단순화할 수 있다는 것이었습니다. 이는 최근 hf CLI에 적용된 것과 동일한 레시피로, 에이전트에 최적화되도록 재설계되어 에이전트가 사용하는 토큰을 1.3~1.8배(최대 6배) 줄였습니다. 우리는 이러한 종류의 이점이 일반화될 수 있는지, 그리고 transformers에도 유용할 수 있는지 알고 싶었습니다.

직관은 강력한 도구이지만, transformers와 같이 널리 사용되는 코드베이스에 수천 줄의 코드를 추가하는 PR(Pull Request)을 올리기 전에 더 많은 증거가 필요했습니다. 우리는 성공이 어떤 모습인지 측정하기로 했습니다.

두 에이전트 모두 감성 분류(sentiment-classification) 작업에 대해 올바른 라벨을 생성할 수 있지만, 한 에이전트는:

• 40줄짜리 Python 스크립트를 작성하고, transformers를 임포트(import)하며, 형상 오류(shape error)를 디버깅하고, 두 번 재실행한 끝에 마침내 정답을 출력합니다.

반면 다른 에이전트는:

• transformers classify --model ... --text "..."를 입력하고 단 한 번의 호출로 끝냅니다.

둘 다 POSITIVE (0.9999)에 도달하며, 다음은 에이전트가 이 정확한 작업에서 실제로 취한 두 가지 경로입니다:

# Task: "I absolutely loved the movie, it was fantastic!"의 감성을 분류하세요.
- # 한 에이전트: 스크립트를 python으로 파이프(pipe)하고 출력을 파싱합니다.
- python - <<'PY'
...

두 방법 모두 동일한 결과에 도달합니다. 하지만 이들은 비용(cost), 지연 시간(latency), 토큰 사용량(token usage), 그리고 실패(failures) 측면에서 매우 다른 프로필을 가집니다.

만약 당신의 평가가 최종 문자열만 확인한다면, 이러한 요소들은 물론, 당신이 라이브러리에 배포한 변경 사항(CLI 개선, 더 나은 에러 메시지, 스킬 등)이 실제로 에이전트에게 도움이 되었는지 여부도 알 수 없습니다.

이 하네스의 목표는 에이전트가 주어진 작업을 수행하기 위해 얼마나 많은 작업을 해야 하는지, 그리고 라이브러리의 변경 사항이 성능을 향상시키는지 평가하는 것입니다.

여기서 에이전트를 어떻게 평가할지에 대해 몇 가지 말씀드리겠습니다.

우리는 모든 작업을 세 가지 변형(또는 "티어(tiers)") 하에서 실행합니다. 이는 에이전트가 transformers에 접근하는 세 가지 서로 다른 방식입니다:

- bare pip install transformers, 그리고 그 외 아무것도 없음
- 전체 transformers 소스 코드를 클론(clone)하여 작업 디렉토리에 체크아웃함
- 패키징된 스킬(Skill) 활용: CLI 문서 + 작업 예시가 컨텍스트(context)에 로드됨

이들은 중첩된 구조가 아닙니다: skill은 clone을 포함하지 않으며 (소스 트리가 아닌 큐레이션된 문서를 제공함), 또한 어느 쪽도 다른 쪽을 엄격하게 포함하지 않습니다. 각각은 에이전트에게 서로 다른 종류의 도움을 제공합니다. 앞으로 살펴보겠지만, 모델에 따라 때로는 skill보다 clone에서 더 나은 성능을 보일 수도 있습니다.

몇 가지 추가적인 선택 사항:

• 현재로서는 실험을 위한 매우 좋은 기준(ground)을 제공하는, 정확한 일치(exact match)를 제공할 수 있는 결정론적(deterministic) 작업에만 집중합니다. 모델 기반 평가(Model-as-a-judge) 및 기타 방식은 다른 작업들을 위한 명백한 다음 단계입니다.
• 모든 실행은 각각 독립적인 Hugging Face Job으로 처리됩니다: (모델 × 리비전 × 작업)당 하나씩 할당되므로, 전체 스윕(sweep)이 동일한 하드웨어에서 병렬로 실행되어 대규모 환경에서도 비교의 공정성을 유지합니다.
• 결과와 트레이스(traces)는 Hugging Face Bucket에 저장됩니다: 빠르고, 버전 관리가 필요 없으며, 매우 높은 쓰기 동시성(write concurrency)을 처리할 수 있습니다.

에이전트를 구동하는 모든 모델이 동일한 것은 아니며, 모델 간의 차이는 실행 시 무엇을 살펴봐야 하는지를 변화시킵니다.

대규모 오픈 모델 (Large open models)

한쪽 끝에는 가장 크고 유능한 오픈 모델들이 있습니다. 상당히 일반적인 작업의 경우, 이들은 결국 정답을 찾아낼 것입니다. 이러한 모델들의 경우, 작업 완료율이 100% 근처에서 포화 상태에 이르러 도구(tool)에 대해 많은 정보를 알려주지 못합니다. 이들에게 더 관련성 있는 벤치마크는 에이전트가 그곳에 도달하기 위해 들인 노력입니다: 몇 번의 턴(turns), 토큰(tokens), 초(seconds)가 소요되었는지, 그리고 깨끗한 경로를 따라갔는지 아니면 권장되지 않는(deprecated) API를 사용했는지 여부입니다.

로컬 (Local)

로컬 모델은 크기가 매우 다양하며, 그 능력 또한 다양합니다. **"일치율(match %)"**과 같은 지표는 대규모 모델의 경우보다 로컬 모델에서 더 관련성이 높습니다. 모델의 크기와 능력이 귀하의 특정 도구에 대한 결과에 어떤 영향을 미치는지 확인할 수 있기 때문입니다.

이 하네스 (harness)는 라이브러리 유지 관리자들에게 에이전트 상호작용을 위해 리포지토리를 어떻게 개선할지에 대한 가이드를 제공할 뿐만 아니라, 사용자가 중요하게 생각하는 작업에 대해 서로 다른 에이전트와 모델이 어떻게 성능을 내는지 평가하는 데에도 도움을 줍니다.

이 하네스는 모든 실행을 여러 축(axes)에 따라 점수화하므로, 각 모델 범주에 대해 실제로 무엇이 중요한지 질문할 수 있습니다:

일치율 (match %): 최종 답변에 예상된 결과가 포함되었는가 (태스크별, 대소문자 구분 없는 부분 문자열 / 정규 표현식 (regex) / 정확히 일치 여부, 모두 보고서에 명시됨);
중앙값 시간 (median time) 및 중앙값 토큰 (median tokens) (신규 vs 캐시됨 vs 생성됨);
오류 발생 실행 비율 (runs with error %): 아무것도 생성하지 않은(출력 토큰 0개, 도구 호출 없음, 답변 없음) 실행을 표시하는 가드 (guard)를 포함하여, 침묵하는 실패 (silent failures)가 "0"으로 위장하는 것을 방지합니다;
마커 채택 (marker adoption): 도구로 정의된 동작 마커 (marker). 이것이 무엇인지에 대한 설명은 아래를 참조하세요.

이 모든 정보는 직접 검토할 수 있는 보고서에 담깁니다:

실시간 보고서: 개요, 커버리지(Coverage), 결과, 모두 클라이언트 측에서 실행됩니다.
(로드되지 않나요? 새 탭에서 여세요.)

또한 모든 실행의 네이티브 에이전트 트레이스 (agent trace)를 캡처하기 때문에, 수치는 시작일 뿐입니다. 에이전트가 명령 단위로 정확히 무엇을 했는지 읽을 수 있습니다. 트레이스는 Hub의 에이전트 트레이스 뷰어 (agent-traces viewer)를 통해 공유할 수 있습니다:

Hub의 에이전트 트레이스 뷰어에서 렌더링된 실행 결과: answer-question 태스크에서의 MiniMax-M2.7.

Hub에서 이 트레이스 열기 ↗

결과를 보기 전에, 설정에 대해 빠르게 요약하겠습니다. 각 실행은 네 가지 요소가 달라집니다: 에이전트를 구동하는 모델 (model), 실행되는 transformers 버전 (transformers revision), 태스크 (task), 그리고 티어 (tier) (bare / clone / skill).
앞서 논의한 바와 같이, 두 가지 서로 다른 모델 범주에 대해 서로 다른 지표를 살펴봅니다. 대규모 오픈 모델은 보통 올바른 결과에 도달하기 때문에, 실제로 측정하는 것은 그 결과에 도달하기 위해 들인 노력입니다. 열 번의 턴이 걸렸나요, 아니면 한 번인가요? 오래된 문서를 신뢰하여 폐기된 API 경로를 따랐나요? 예상하지 못한 오류를 만났나요?

자연스러운 실험 방법은 하나의 강력한 모델을 고정하고, 테스트 대상인 툴의 개정(revisions) 버전을 변화시키는 것입니다. 즉, v5.8.0이나 v5.9.0과 같은 릴리스 태그부터 CLI와 Skill이 도입된 특정 커밋에 이르기까지, transformers의 연속적인 git 버전을 변화시키며 테스트합니다. 우리는 에이전트가 짊어지는 부하가 증가하는지 혹은 감소하는지를 관찰하고자 합니다. 우리는 전용 CLI와 Skill을 추가하는 것이 실제로 에이전트의 작업량을 경감시키는지 확인하기 위해 transformers에 하네스 (harness)를 사용했습니다.

테스트에 사용된 세 가지 대규모 모델의 경우, 모든 작업에 소요된 평균 시간은 Skill 커밋이 작업에 소요되는 시간을 줄여준다는 것을 나타냅니다.

계층별 개정당 중앙값 시간: Skill 커밋(녹색 점)이 가장 빠릅니다.

반면, 저장소를 클론(clone)하여 진행한 실험에서는 잠시 후 살펴보겠지만, CLI와 예제들을 도입한 커밋으로 인해 토큰 소비량이 크게 증가하는 것을 볼 수 있습니다.

계층별 개정당 새로운 토큰 중앙값: 클론 변형(clone variant)은 리포지토리에 CLI가 도입되면서 급증합니다.

클론 변형의 트레이스 (traces)를 읽어보면 그 이유를 알 수 있습니다. 해당 커밋은 명령어를 추가할 뿐만 아니라, CLI의 구현체와 cli/agentic/*.py 사용 예제 세트를 리포지토리에 직접 포함시킵니다.

clone 변형의 경우 에이전트 앞에 transformers 전체 체크아웃 (checkout) 상태가 놓이게 되며, 실행의 약 3분의 1은 CLI를 호출하기 전에 인터페이스를 학습하기 위해 새로운 표면 (surface, 즉 /cli/ 트리와 예제 스크립트)을 읽는 데 사용됩니다. 이로 인해 중앙값 입력 토큰이 약 4k에서 약 6.4k로 증가합니다.

결과적으로 두 차트는 하나의 트레이드오프 (tradeoff)의 양면을 보여줍니다. 해당 커밋은 대규모 모델이 Python 디버깅 대신 CLI를 사용하게 함으로써 작업 시간을 단축해주지만, 그 대가로 더 많은 토큰을 소비하게 합니다 (CLI를 가르쳐준 코드를 읽어야 하기 때문입니다). 이는 PR을 머지(merge)하기 전에 반드시 알아두어야 할 트레이드오프입니다.

하지만 아직 벤치마크에 포함되지 않은, CLI에 유리하게 작용하는 주의사항(caveat)이 하나 있습니다. 바로 이를 읽는 데 드는 비용이 연속적인 실행을 통해 분할 상환(amortized)된다는 점입니다. 우리의 설정은 일회성 실험을 위해 구축되었습니다. 각 실행은 CLI를 처음부터 다시 발견하는 새로운 에이전트이므로, 매번 발견 비용을 지불합니다. 실제 사용 환경에서 에이전트는 인터페이스를 한 번 학습하면 동일한 세션 내에서 작업(task)을 차례로 해결하며, 이를 통해 많은 요청에 걸쳐 해당 비용을 분할 상환합니다. 여기서 우리가 측정한 토큰 증가량은 사용자가 일상적으로 겪게 될 상황보다는 최악의 경우(worst case)에 더 가깝습니다.

오픈 모델(Open models)은 여기서 가장 중요한 변수들, 즉 크기(size), 설정(configuration), 양자화(quantization), 제공자(provider), 학습(training), 그리고 모델마다 달라질 수 있는 모든 요소에 대해 세밀한 제어(fine-grained control)를 제공합니다. 또한 오픈 모델은 좋은 도구 인터페이스(tool surface)가 가장 중요하게 작용하는 영역이기도 합니다. bare 환경에서 "transformers를 사용하여 X를 수행하라"는 요청을 받은 작은 모델은 몇 개 릴리스 전에 변경된 API를 추측하거나, 불필요한 도구 호출(tool calls)을 수행하거나, 잘못된 답을 내놓을 수 있습니다.

따라서 여기서의 실험은 위와 반대입니다. 리비전(revision)은 고정하고 모델을 스윕(sweep)합니다. 이를 통해 단순히 토큰 수나 시간뿐만 아니라, 어떤 모델이 실제로 작업을 수행하는지, 그리고 어떤 모델이 도구 호출을 안정적으로 처리하지 못하는지까지 확인할 수 있습니다. 우리의 직관은 모델이 작을수록 도구 사용과 작업 모두 어려워진다는 것이며, 이를 정확히 테스트하기 위해 다양한 모델 크기에 걸쳐 하네스(harness)를 실행했습니다.

계층별 모델 간 일치율(%): 기술 계층(skill tier)은 더 큰 모델의 성능을 높이지만, 더 작은 모델의 성능은 떨어뜨립니다.

이는 또한 입력되는 토큰 수와 상관관계가 있는 것으로 보입니다.

계층별 모델 간 새로운 토큰의 중앙값.

공정한 비교에 관한 참고 사항: 커버리지(coverage)가 불균등할 때 단순히 작업 전체를 평균 내는 것은 오해의 소지가 있습니다 (빠른 작업만 완료한 모델은 빠르게 보일 수 있기 때문입니다). 이 보고서에는...