Transformers.js v4: Now Available on NPM!

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Transformers.js v4는 새 C++ 기반 WebGPU 런타임, 고성능 모델 실행 전략, 모노레포 구조, 확장된 모델 지원, 경량 빌드와 운영용 API를 도입해 브라우저와 서버 측 자바스크립트 전반의 로컬 AI 실행 기반을 강화한 대규모 업데이트다.

📌 핵심 요약

• 2025년 3월부터 약 1년간 개발된 Transformers.js v4가 NPM에 공개됐으며, 브라우저뿐 아니라 Node, Bun, Deno와 데스크톱 애플리케이션에서도 동일한 코드로 WebGPU 가속 모델을 실행할 수 있게 됐다.
• 새 WebGPU 런타임은 C++로 전면 재작성됐고, 약 200개의 지원 모델 아키텍처와 v4 전용 신규 아키텍처를 대상으로 검증됐다. 특화된 ONNX Runtime 연산자를 활용한 모델별 재구현으로 성능·정확도·지원 범위를 개선했으며, BERT 계열 임베딩 모델에서는 약 4배의 속도 향상을 달성했다.
• 저장소는 pnpm 워크스페이스 기반 모노레포로 개편됐고, 8천 줄이 넘던 단일 모델 파일은 역할별 모듈로 분리됐다. 예제 프로젝트도 별도 저장소로 이동했으며, 일관된 코드 스타일을 위해 Prettier 설정과 전체 파일 포맷이 정비됐다.
• GPT-OSS, Chatterbox, GraniteMoeHybrid, LFM2-MoE, Olmo3 등 새로운 모델과 Mamba, MLA, MoE 같은 고급 구조가 추가됐다. 빌드 도구는 Webpack에서 esbuild로 전환돼 빌드 시간이 2초에서 200밀리초로 단축됐고, 기본 웹 번들은 53% 작아졌다.
• ModelRegistry를 통해 필요한 파일, 다운로드 크기, 캐시 상태, 지원 정밀도를 로딩 전에 확인할 수 있으며, WASM 캐시·사용자 정의 fetch·로그 수준 설정도 추가됐다. 별도 패키지인 @huggingface/tokenizers와 동적 파이프라인 타입, 8B 초과 대형 모델 지원까지 포함해 실제 애플리케이션 운영과 개발 편의성을 함께 높였다.

🧩 주요 포인트

1. 2025년 3월부터 약 1년간 개발된 Transformers.js v4가 NPM에 공개됐으며, 브라우저뿐 아니라 Node, Bun, Deno와 데스크톱 애플리케이션에서도 동일한 코드로 WebGPU 가속 모델을 실행할 수 있게 됐다.
2. 새 WebGPU 런타임은 C++로 전면 재작성됐고, 약 200개의 지원 모델 아키텍처와 v4 전용 신규 아키텍처를 대상으로 검증됐다. 특화된 ONNX Runtime 연산자를 활용한 모델별 재구현으로 성능·정확도·지원 범위를 개선했으며, BERT 계열 임베딩 모델에서는 약 4배의 속도 향상을 달성했다.
3. 저장소는 pnpm 워크스페이스 기반 모노레포로 개편됐고, 8천 줄이 넘던 단일 모델 파일은 역할별 모듈로 분리됐다. 예제 프로젝트도 별도 저장소로 이동했으며, 일관된 코드 스타일을 위해 Prettier 설정과 전체 파일 포맷이 정비됐다.
4. GPT-OSS, Chatterbox, GraniteMoeHybrid, LFM2-MoE, Olmo3 등 새로운 모델과 Mamba, MLA, MoE 같은 고급 구조가 추가됐다. 빌드 도구는 Webpack에서 esbuild로 전환돼 빌드 시간이 2초에서 200밀리초로 단축됐고, 기본 웹 번들은 53% 작아졌다.
5. ModelRegistry를 통해 필요한 파일, 다운로드 크기, 캐시 상태, 지원 정밀도를 로딩 전에 확인할 수 있으며, WASM 캐시·사용자 정의 fetch·로그 수준 설정도 추가됐다. 별도 패키지인 @huggingface/tokenizers와 동적 파이프라인 타입, 8B 초과 대형 모델 지원까지 포함해 실제 애플리케이션 운영과 개발 편의성을 함께 높였다.

🧠 상세 정리

1. 약 1년간 개발된 v4의 NPM 공개

Transformers.js v4는 2025년 3월부터 약 1년 동안 개발된 뒤 2026년 2월 9일 NPM에 공개됐다. 사용자는 npm i @huggingface/transformers 명령으로 새 버전을 설치할 수 있으며, 이번 릴리스는 단순한 기능 추가가 아니라 런타임·모델 내보내기·저장소·빌드·운영 API를 함께 재설계한 메이저 업데이트다. 프로젝트가 이미 브라우저에서 최신 AI 모델을 완전히 로컬로 실행할 수 있음을 보여준 만큼, v4의 중심 과제는 제한된 자원에서도 모델이 최대한 빠르게 동작하도록 성능과 실행 환경의 범위를 넓히는 것이었다. 이를 위해 ONNX Runtime 팀과 협력해 기존에 지원하던 약 200개 모델 아키텍처뿐 아니라 v4에서 새로 추가된 아키텍처까지 폭넓게 시험했다.

2. C++ 기반 WebGPU 런타임과 실행 환경 확대

가장 큰 변화는 C++로 완전히 다시 작성된 새 WebGPU 런타임의 도입이다. 새 런타임은 연산자 지원을 확장해 성능과 정확도, 모델 적용 범위를 개선하는 동시에 동일한 Transformers.js 코드를 여러 자바스크립트 환경에서 재사용할 수 있도록 설계됐다. 이에 따라 브라우저와 데스크톱 애플리케이션은 물론 Node, Bun, Deno 같은 서버 측 런타임에서도 WebGPU로 가속된 모델을 직접 실행할 수 있다. 실행 장소에 따라 별도의 모델 코드를 유지하기보다 공통 자바스크립트 인터페이스를 활용할 수 있다는 점이 핵심이며, 하드웨어 가속을 브라우저 전용 기능에 머물지 않게 했다. 이 변화는 로컬 추론의 적용 범위를 웹 페이지에서 서버 및 데스크톱 애플리케이션으로 확장한다.

3. 모델별 내보내기 전략과 특화 연산자 최적화

개발팀은 특히 대규모 언어 모델의 성능을 높이기 위해 기존 내보내기 전략을 전면적으로 다시 검토했다. 새 모델을 일반적인 변환 절차에만 맡기지 않고 연산 단위로 다시 구현하면서 com.microsoft.GroupQueryAttention, com.microsoft.MatMulNBits, com.microsoft.QMoE 같은 ONNX Runtime Contrib 연산자를 적극적으로 사용했다. 이러한 특화 연산자는 모델 구조에 맞는 계산을 효율적으로 처리해 실행 속도뿐 아니라 정확도와 아키텍처 지원 범위를 함께 개선하는 기반이 됐다. 실제로 BERT 계열 임베딩 모델에 com.microsoft.MultiHeadAttention 연산자를 적용한 결과 약 4배의 속도 향상을 기록했다. 따라서 v4의 성능 개선은 런타임 교체에만 의존한 것이 아니라 각 모델의 핵심 연산을 세밀하게 재구성한 결과다.

4. 모노레포 전환과 모델 코드 모듈화

기존에는 GitHub 저장소 자체가 하나의 NPM 패키지 역할을 했지만, 핵심 라이브러리에 의존하는 하위 패키지와 특정 용도의 유틸리티를 제공하기에는 구조적 제약이 있었다. v4에서는 저장소를 pnpm 워크스페이스 기반 모노레포로 전환해 별도 저장소를 계속 만들지 않고도 @huggingface/transformers에 의존하는 작은 패키지를 함께 배포할 수 있게 했다. v3에서 모든 모델 정의를 담아 8천 줄을 넘겼던 models.js도 유틸리티, 핵심 로직, 모델별 구현을 구분한 작은 모듈들로 분리했다. 이 구조는 개발자가 수천 줄의 무관한 코드를 탐색하지 않고 필요한 모델 구현에 집중하도록 하며, 새 모델을 추가하는 과정도 단순화한다. 예제 프로젝트는 전용 저장소로 옮겨 핵심 코드베이스를 정돈했고, Prettier 설정과 전체 파일 포맷을 갱신해 향후 기여 코드의 스타일도 자동으로 통일했다.

5. 새 모델과 고급 아키텍처의 WebGPU 지원

새로운 내보내기 전략과 ONNX Runtime의 사용자 정의 연산자 지원 확대를 바탕으로 v4에는 다수의 신규 모델과 아키텍처가 추가됐다. 지원 목록에는 GPT-OSS, Chatterbox, GraniteMoeHybrid, LFM2-MoE, HunYuanDenseV1, Apertus, Olmo3, FalconH1, Youtu-LLM 등이 포함된다. 이 모델들을 지원하는 과정에서 상태 공간 모델인 Mamba, 다중 헤드 잠재 어텐션인 MLA, 전문가 혼합 구조인 MoE와 같은 고급 패턴도 구현됐다. 중요한 점은 이 모델들이 모두 WebGPU와 호환돼 브라우저뿐 아니라 서버 측 자바스크립트 환경에서도 하드웨어 가속으로 실행될 수 있다는 것이다. 개발팀은 이미 여러 Transformers.js v4 데모를 공개했으며 앞으로도 데모를 계속 추가할 계획이라고 밝혔다.

6. esbuild 전환으로 빨라진 빌드와 작아진 번들

빌드 시스템은 Webpack에서 esbuild로 교체됐으며, 개발 반복 속도와 사용자 다운로드 비용 모두에서 구체적인 개선이 나타났다. 기존에 약 2초 걸리던 빌드는 약 200밀리초로 줄어 10배 빨라졌고, 전체 빌드의 번들 크기도 평균 약 10% 감소했다. 특히 기본 내보내기 파일인 transformers.web.js는 이전보다 53% 작아져 웹 애플리케이션에서 다운로드와 초기 시작에 필요한 부담을 크게 낮췄다. 이 결과는 개발자가 변경 사항을 더 빠르게 확인할 수 있게 하는 동시에, 최종 사용자가 라이브러리를 내려받고 실행을 시작하는 시간도 단축한다. 즉, 새 빌드 체계는 내부 개발 생산성과 실제 배포 결과물의 효율을 동시에 개선했다.

7. ModelRegistry를 통한 로딩 전 자산 관리

새 ModelRegistry API는 모델을 실제로 불러오기 전에 파이프라인에 필요한 자산을 명시적으로 파악할 수 있도록 만들어졌다. get_pipeline_files로 필수 파일 목록을 가져오고 get_file_metadata로 각 파일의 크기 등 메타데이터를 조회하면, 애플리케이션이 전체 다운로드 용량을 사전에 계산할 수 있다. is_pipeline_cached와 clear_pipeline_cache를 사용하면 파이프라인의 캐시 여부를 확인하거나 관련 아티팩트를 제거할 수 있으며, get_available_dtypes로 모델이 제공하는 fp32, fp16, q4, q4f16 등의 정밀도 유형도 조회할 수 있다. 이 API를 기반으로 progress_callback에는 전체 로딩 진행률을 전달하는 progress_total 이벤트가 추가됐다. 따라서 파일별 진행 상황을 애플리케이션이 직접 합산하지 않아도 종단 간 로딩 상태를 표시할 수 있어, 다운로드와 캐시를 관리해야 하는 운영 환경에 적합한 기반을 제공한다.

8. 오프라인 캐시, 사용자 정의 요청과 로그 제어

v4는 실제 애플리케이션의 모델 로딩 방식을 세밀하게 제어할 수 있도록 새로운 환경 설정을 추가했다. env.useWasmCache를 활성화하면 캐시 저장소를 사용할 수 있는 환경에서 WASM 런타임 파일을 보관하므로, 최초 로딩 이후에는 애플리케이션을 완전히 오프라인으로 동작시킬 수 있다. env.fetch에는 사용자 정의 fetch 구현을 지정할 수 있어 인증이 필요한 모델 접근, 사용자 정의 헤더 추가, 중단 가능한 요청 같은 요구를 처리할 수 있다. 로깅 정책도 개선돼 ONNX Runtime WebGPU 경고는 기본적으로 숨겨지며, Transformers.js와 ONNX Runtime 각각에 명시적인 로그 상세 수준을 설정할 수 있다. 이는 커뮤니티 피드백을 반영한 변경으로, 실제 배포 환경의 콘솔에서 가치가 낮은 반복 메시지를 줄이고 조치 가능한 신호에 집중하도록 돕는다.

9. 독립 Tokenizers.js와 대형 모델 지원

사용자들이 반복적으로 요청했던 토큰화 로직 분리는 @huggingface/tokenizers라는 독립 라이브러리로 구현됐다. 이 패키지는 브라우저와 서버 측 런타임에서 모두 작동하도록 토큰화 코드를 전면 재구성했으며, 압축 기준 8.8킬로바이트에 의존성이 없고 전체 타입 안전성을 제공한다. 사용자는 허깅페이스 허브에서 tokenizer.json과 tokenizer_config.json을 받아 Tokenizer 객체를 만든 뒤, 텍스트 토큰화와 인코딩을 Transformers.js 전체 패키지 없이 수행할 수 있다. 이 분리는 Transformers.js 핵심을 더 간결하게 유지하면서 다른 WebML 프로젝트에도 독립적으로 사용할 수 있는 도구를 제공한다. 이와 함께 입력에 따라 달라지는 동적 파이프라인 타입이 추가됐고 8B 매개변수를 넘는 모델도 지원하며, 개발팀의 시험에서는 M4 Pro Max에서 GPT-OSS 20B의 q4f16 버전을 초당 약 60토큰으로 실행했다.

🧾 핵심 주장 / 시사점

• v4의 핵심 변화는 WebGPU를 브라우저 전용 가속 수단으로 다루지 않고 Node, Bun, Deno와 데스크톱까지 포괄하는 공통 자바스크립트 실행 기반으로 확장한 데 있다.
• 성능 향상은 단순한 런타임 교체가 아니라 모델을 연산 단위로 다시 구현하고 구조별 ONNX Runtime 특화 연산자를 적용한 결과이며, BERT 계열의 약 4배 향상이 이를 구체적으로 보여준다.
• ModelRegistry, WASM 캐시, 사용자 정의 fetch, 로그 수준, 독립 토크나이저는 v4가 모델 실행 기능뿐 아니라 다운로드·캐시·인증·오프라인 동작·배포 관리까지 실제 운영 흐름을 다루도록 범위를 넓혔음을 보여준다.

✅ 액션 아이템

• Transformers.js v4 NPM 공개 기능을 활용해 브라우저·Node·Bun·Deno·데스크톱 대상의 동일 코드 실행 범위를 우선 정리한다.
• C++ 기반 WebGPU 런타임과 ONNX Runtime 특화 연산자, 200개 이상 아키텍처 검증치를 기준으로 기존 실행 경로의 교체 우선순위를 정한다.
• 모노레포 분해·esbuild 전환·웹 번들 53% 축소와 빌드 2초→200밀리초 기록을 반영해 운영 빌드 파이프라인 성능 점검한다.

❓ 열린 질문

• 브라우저·데스크톱 간 동일 코드 실행이 실제 서비스 환경에서 모델별 성능과 안정성을 모두 유지하는지 어떻게 판단할 것인가?
• BERT 계열에서 본 약 4배 속도 향상이 GPT-OSS, Chatterbox, GraniteMoeHybrid 등 추가 모델군에도 유지되는지 어떻게 확인할 것인가?
• ModelRegistry의 다운로드 크기·캐시 상태·지원 정밀도 정보를 바탕으로 8B 초과 모델 운영 시 메모리와 대역폭 정책을 어떤 기준으로 조정할 것인가?