Transformers.js v4 프리뷰: 이제 NPM에서 사용 가능!
Source: Hugging Face Blog
Table of Contents
- Performance & Runtime Improvements
- Repository Restructuring
- PNPM Workspaces
- Modular Class Structure
- Examples Repository
- Prettier
- Formatting and Consistency
- New Models and Architectures
- New Build System
- Standalone
Tokenizers.jsLibrary - Miscellaneous Improvements
- Acknowledgements
우리는 Transformers.js v4 (preview) 가 이제 npm에서 사용 가능하게 되었다는 소식을 전하게 되어 매우 기쁩니다! 거의 1년 동안 개발에 매진한 뒤(2025년 3월에 시작했어요 🤯), 드디어 여러분이 직접 테스트해볼 수 있게 되었습니다. 이전에는 사용자가 GitHub에서 소스를 직접 설치해야 했지만, 이제는 한 줄의 명령어만으로 간단히 설치할 수 있습니다:
npm i @huggingface/transformers@next전체 정식 릴리스가 나올 때까지 npm에서는 next 태그 아래에 v4 릴리스를 계속해서 배포할 예정이니, 정기적인 업데이트를 기대해 주세요!
성능 및 런타임 개선
가장 큰 변화는 WebGPU 런타임을 새롭게 도입한 것으로, C++로 완전히 재작성되었습니다. 우리는 ONNX Runtime 팀과 긴밀히 협력하여 약 200개의 지원되는 모델 아키텍처와 새로운 v4 전용 아키텍처 전반에 걸쳐 이 런타임을 테스트했습니다.
성능, 정확도 및 커버리지를 위한 연산자 지원이 개선될 뿐만 아니라, 새로운 WebGPU 런타임은 동일한 transformers.js 코드를 브라우저, 서버‑사이드 런타임, 데스크톱 애플리케이션 등 다양한 JavaScript 환경에서 실행할 수 있게 합니다. 이제 Node, Bun, Deno에서도 WebGPU 가속 모델을 직접 실행할 수 있습니다!
우리는 최신 AI 모델을 브라우저에서 100 % 로컬로 실행할 수 있음을 입증했습니다. 이제는 성능에 집중하고 있습니다: 자원 제한이 있는 환경에서도 가능한 한 빠르게 모델을 실행하도록 하는 것이 목표입니다. 이를 위해 특히 대형 언어 모델에 대한 내보내기 전략을 재고해야 했습니다. 우리는 새로운 모델을 연산자별로 재구현하고, 다음과 같은 특수 ONNX Runtime Contrib Operators를 활용함으로써 이를 달성했습니다:
com.microsoft.GroupQueryAttentioncom.microsoft.MatMulNBitscom.microsoft.QMoE
이 연산자들은 성능을 극대화합니다. 예를 들어 com.microsoft.MultiHeadAttention 연산자를 채택함으로써 BERT 기반 임베딩 모델에서 약 4배의 속도 향상을 얻었습니다.
이번 업데이트는 또한 브라우저에 WASM 파일을 로컬에 캐시하여 완전한 오프라인 지원을 가능하게 합니다. 초기 다운로드 후에는 인터넷 연결 없이도 Transformers.js 애플리케이션을 실행할 수 있습니다.
Repository Restructuring
새로운 주요 버전을 개발하면서 코드베이스에 투자하고 오래도록 미뤄졌던 리팩토링 작업을 수행할 기회를 얻었습니다.
PNPM Workspaces
지금까지 GitHub 저장소는 우리의 npm 패키지 역할을 해왔습니다. 저장소가 단일 라이브러리만 제공할 때는 잘 작동했지만, 앞으로 Transformers.js 코어에 크게 의존하는 서브‑패키지(예: 라이브러리‑특정 구현이나 작은 유틸리티)를 위해 보다 유연한 구조가 필요했습니다.
따라서 우리는 저장소를 pnpm workspaces를 이용한 모노레포로 전환했습니다. 이를 통해 별도 저장소를 유지 관리하는 부담 없이 @huggingface/transformers에 의존하는 작은 패키지들을 배포할 수 있게 되었습니다.
Modular Class Structure
Another major refactor targeted the ever‑growing models.js file. In v3, all available models were defined in a single file spanning over 8 000 lines, making maintenance difficult. For v4 we split this into smaller, focused modules with a clear distinction between:
- Utility functions
- Core logic
- Model‑specific implementations
The new structure improves readability and makes it much easier to add new models. Developers can now focus on model‑specific logic without navigating through thousands of unrelated lines of code.
Examples Repository
v3에서는 많은 Transformers.js 예제 프로젝트가 메인 저장소에 직접 포함되어 있었습니다. v4에서는 이를 전용 저장소: 로 옮겼습니다. 이렇게 하면 핵심 라이브러리를 깔끔하게 유지하고, 사용자가 메인 코드베이스를 뒤적이지 않고도 예제를 찾고 기여하기가 쉬워집니다.
Prettier
우리는 Prettier 구성을 업데이트하고 모든 파일을 일관된 스타일을 따르도록 재포맷했습니다. (이 섹션의 나머지는 전체 기사에서 계속됩니다.)
포맷팅 및 일관성
현재 저장소의 모든 파일은 이제 단일 공유 Prettier 설정을 사용합니다. 이는 코드베이스 전반에 걸쳐 일관된 포맷팅을 보장하며, 향후 모든 PR이 자동으로 동일한 스타일을 따르게 합니다. 포맷팅에 대한 논쟁은 이제 끝—Prettier가 모든 것을 처리해 코드가 모두에게 깨끗하고 읽기 쉬운 상태를 유지합니다.
새로운 모델 및 아키텍처
우리 새로운 export 전략과 ONNX Runtime의 커스텀 연산자 지원 확대 덕분에 Transformers.js v4에 많은 새로운 모델과 아키텍처를 추가했습니다. 여기에는 다음과 같은 인기 모델이 포함됩니다:
- GPT‑OSS
- Chatterbox
- GraniteMoeHybrid
- LFM2‑MoE
- HunYuanDenseV1
- Apertus
- Olmo3
- FalconH1
- Youtu‑LLM
이들 중 다수는 다음과 같은 고급 아키텍처 패턴에 대한 지원 구현을 필요로 했습니다:
- Mamba (state‑space models)
- Multi‑head Latent Attention (MLA)
- Mixture of Experts (MoE)
이러한 모든 모델은 WebGPU와 호환되어, 사용자가 브라우저 또는 서버‑사이드 JavaScript 환경에서 하드웨어 가속을 통해 직접 실행할 수 있습니다.
새로운 빌드 시스템
우리는 빌드 시스템을 Webpack에서 esbuild로 이전했으며, 그 결과는 놀라웠습니다:
- Build time: 약 2 초에서 ~200 ms로 단축되었습니다 (≈10배 빠름)
- Bundle size: 모든 빌드에서 평균 약 10 % 감소했습니다
- transformers.web.js: 이제 53 % 작아져 다운로드 속도가 빨라지고 사용자의 시작 시간이 단축되었습니다
스탠드얼론 Tokenizers.js 라이브러리
사용자들의 빈번한 요청은 토큰화 로직을 별도 라이브러리로 분리하는 것이었습니다. v4에서는 바로 그 작업을 수행했습니다.
@huggingface/tokenizers는 토큰화 로직을 완전히 리팩터링한 것으로, 브라우저와 서버‑사이드 런타임 모두에서 원활하게 작동하도록 설계되었습니다. 8.8 kB(gzipped) 크기에 의존성이 전혀 없으며, 매우 가볍지만 완전한 타입‑안전성을 유지합니다.
예시
import { Tokenizer } from "@huggingface/tokenizers";
// Load from Hugging Face Hub
const modelId = "HuggingFaceTB/SmolLM3-3B";
const tokenizerJson = await fetch(
`https://huggingface.co/${modelId}/resolve/main/tokenizer.json`
).then(res => res.json());
const tokenizerConfig = await fetch(
`https://huggingface.co/${modelId}/resolve/main/tokenizer_config.json`
).then(res => res.json());
// Create tokenizer
const tokenizer = new Tokenizer(tokenizerJson, tokenizerConfig);
// Tokenize text
const tokens = tokenizer.tokenize("Hello World");
// ['Hello', 'ĠWorld']
const encoded = tokenizer.encode("Hello World");
// { ids: [9906, 4435], tokens: ['Hello', 'ĠWorld'], ... }이 분리를 통해 Transformers.js의 핵심은 집중되고 간결하게 유지되며, 어떤 WebML 프로젝트에서도 독립적으로 사용할 수 있는 다재다능한 스탠드얼론 도구를 제공합니다.
기타 개선 사항
우리는 라이브러리 전반에 걸쳐 여러 품질‑향상 개선을 적용했습니다:
-
동적 파이프라인 유형은 입력에 따라 자동으로 적응하여 개발자 경험과 타입 안전성을 향상시킵니다.
-
향상된 로깅으로 모델 실행 중에 더 많은 제어와 명확한 피드백을 제공합니다.
-
대형 모델 지원으로 8 B 파라미터를 초과하는 모델을 사용할 수 있습니다. 테스트에서는 GPT‑OSS 20B (q4f16) 를 M4 Pro Max에서 초당 약 60 토큰 속도로 실행했습니다.
감사의 글
이번 주요 릴리스에 기여해 주신 모든 분들께 특히 깊은 감사를 전하고 싶습니다.
- ONNX Runtime 팀은 새로운 WebGPU 런타임에 대한 놀라운 작업과 개발 전반에 걸친 지원에 감사드립니다.
- 모든 외부 기여자와 초기 테스터 여러분.