YEYETILCraftsPostsAbout

[TIL] Transformers.js + WebGPU

2026. 05. 26.Yeji Kim
AIFrontend

1. Transformers.js?

Hugging Face가 만든 JS 라이브러리이다. 모델 가중치를 사용자 디바이스로 받아서, 추론을 브라우저 안에서 직접 수행한다.

요약하면, OpenAI API 부르는 대신 모델을 브라우저에 다운받아서 그냥 돌리는 방식이다. 텍스트 생성뿐 아니라 임베딩, 분류, 음성 인식, 이미지·비전 모델까지 같은 인터페이스(pipeline)로 다룬다.

2. WebGPU 덕에 실용 영역으로

원래는 WASM(CPU)으로만 돌아서 조금만 무거워도 느렸다. WebGPU가 들어오면서 브라우저가 GPU를 직접 쓰는 길이 열렸고, SLM도 실사용 가능한 속도가 나오기 시작했다고 한다.

text
이전: 브라우저 + WASM(CPU)   → 작은 모델만 그나마
지금: 브라우저 + WebGPU(GPU) → SLM도 수십 tok/s

체감상 GPU 백엔드와 CPU 백엔드의 토큰 생성 속도 차이가 한 자리 수 배수 이상 난다. 데모용에서 진짜 제품 안에 넣어볼까? 정도로 넘어가게 한 변화에 가깝다.

3. 어떻게 돌리나 - ONNX + 양자화

내부 구조를 한 겹만 들춰보면 이렇다.

  • 모델은 PyTorch 원본 그대로가 아니라, ONNX 포맷으로 변환된 버전을 받는다
  • 브라우저에서 실제 실행 엔진은 ONNX Runtime Web
  • 백엔드(GPU/CPU)는 ONNX Runtime Web이 알아서 선택 - Transformers.js는 옵션만 넘김
  • 모델은 보통 양자화(quantized) 버전 (q4, q8, fp16 등)으로 미리 잘게 만들어져 있어, 다운로드/메모리/속도가 줄어듦
text
[모델 원본 PyTorch]
       ↓ ONNX 변환 + 양자화
[onnx-community/... q4 / q8 / fp16 ...]
       ↓ 브라우저가 다운로드 (캐시: IndexedDB)
[ONNX Runtime Web]
       ↓ WebGPU backend (가능하면) / WASM backend (fallback)
[실행]

그래서 사용자가 보는 건 한 줄짜리 pipeline이지만, 그 한 줄 뒤에 포맷 변환 → 양자화 → 런타임 → 백엔드 선택의 과정이 있다.

4. 예제

ts
import { pipeline } from "@huggingface/transformers";
 
const generator = await pipeline(
  "text-generation",
  "onnx-community/Llama-3.2-1B-Instruct",
  {
    device: "webgpu",
    dtype: "q4",   // 양자화 정도: q4(가벼움) ~ fp16(정확)
  },
);
 
const out = await generator("프론트엔드란?", { max_new_tokens: 64 });
console.log(out[0].generated_text);

세 줄로 브라우저에서 1B 모델이 돈다. 첫 호출 때만 모델 다운로드, 이후엔 IndexedDB 캐시라 오프라인에서도 동작한다. dtype을 바꿔가며 같은 모델의 메모리·속도·품질 트레이드오프를 직접 체감할 수 있다.

5. 한계

  • 첫 다운로드 비용 - 1B 모델 양자화본도 보통 ~500MB 이상. 캐시 전 첫 진입은 무겁다
  • WebGPU 호환성 - Chrome/Edge는 안정적, Safari/Firefox는 점진적 지원 중. fallback 시나리오가 필요
  • 모델 풀이 좁다 - 누군가 ONNX로 변환·업로드해둔 모델만 곧장 쓸 수 있다 (대부분 onnx-community/, Xenova/ 네임스페이스)
  • 장기 추론은 부적합 - RAM 점유와 발열이 누적된다. 짧고 빠른 태스크가 적합

6. 어디에 쓸만한가

  • 프라이버시 - 사용자 입력이 서버로 안 나감 (의료·금융·사내 데이터 친화)
  • 비용 0 - API 콜 비용 없음, 추론 자원은 사용자 디바이스 (대신 사용자의 비용은...)
  • 빠른 프로토타이핑 - 백엔드 없이 데모/실험 가능
  • 에디터 도메인 - 인라인 제안, 분류, 임베딩 기반 검색처럼 짧고 반복적인 태스크에 잘 맞음
  • 하이브리드 - 평소엔 브라우저 SLM, 복잡한 질의는 서버 LLM으로 fallback (SLM 글에서 다룬 패턴 그대로)

참고