Transformers.js 소개 및 설치 완벽 가이드

브라우저와 Node.js에서 머신러닝 모델을 실행할 수 있는 Transformers.js의 개념부터 설치, 첫 예제 실행까지 초급 개발자를 위해 쉽게 설명합니다.

---

목차

1. Transformers.js란_무엇인가
2. Hugging_Face와의_관계
3. 브라우저_vs_Node.js_환경
4. npm_yarn으로_설치하기
5. CDN으로_바로_사용하기
6. 첫_번째_예제_실행하기

---

1. Transformers.js란 무엇인가

어느 날 김개발 씨는 회사에서 흥미로운 요청을 받았습니다. "우리 웹사이트에 AI 기능을 넣어볼 수 있을까요?

서버 비용은 최소화하면서요." 서버 없이 브라우저에서 AI를 돌린다고요? 처음엔 불가능하다고 생각했습니다.

Transformers.js는 웹 브라우저와 Node.js 환경에서 최신 머신러닝 모델을 직접 실행할 수 있게 해주는 JavaScript 라이브러리입니다. 마치 스마트폰에 번역 앱을 설치하면 인터넷 없이도 번역이 되는 것처럼, 사용자의 기기에서 바로 AI가 동작합니다.

Python 없이 JavaScript만으로 텍스트 분석, 이미지 인식, 음성 처리 등을 구현할 수 있습니다.

다음 코드를 살펴봅시다.

// Transformers.js 기본 사용 예시
import { pipeline } from '@xenova/transformers';

// 감정 분석 파이프라인 생성
const classifier = await pipeline('sentiment-analysis');

// 텍스트의 감정을 분석합니다
const result = await classifier('I love programming!');

// 결과: [{ label: 'POSITIVE', score: 0.9998 }]
console.log(result);

김개발 씨는 입사 2년 차 프론트엔드 개발자입니다. 어느 날 기획팀에서 특별한 요청이 들어왔습니다.

고객 리뷰의 감정을 실시간으로 분석해서 보여주는 기능을 만들어 달라는 것이었습니다. "AI 기능이요?

그러면 Python으로 서버를 만들고, API를 연동하고..." 김개발 씨가 복잡한 아키텍처를 떠올리며 한숨을 쉬었습니다. 서버 비용도 만만치 않고, 응답 속도도 느려질 텐데 말입니다.

그때 선배 박시니어 씨가 다가왔습니다. "Transformers.js 써본 적 있어요?

브라우저에서 바로 AI 모델을 돌릴 수 있어요." 그렇다면 Transformers.js란 정확히 무엇일까요? 쉽게 비유하자면, Transformers.js는 마치 휴대용 통역기와 같습니다.

예전에는 통역이 필요하면 통역사를 불러야 했습니다. 하지만 요즘은 손안의 작은 기기가 실시간으로 번역해줍니다.

Transformers.js도 마찬가지입니다. 거대한 AI 서버 없이도 사용자의 브라우저에서 직접 머신러닝이 동작합니다.

Transformers.js가 등장하기 전에는 어땠을까요? 웹에서 AI 기능을 구현하려면 반드시 서버가 필요했습니다.

사용자가 텍스트를 입력하면 서버로 보내고, 서버에서 Python으로 처리한 뒤 결과를 다시 받아와야 했습니다. 네트워크 지연이 발생하고, 서버 비용이 들고, 동시 접속자가 많아지면 서버가 터지기도 했습니다.

바로 이런 문제를 해결하기 위해 Transformers.js가 등장했습니다. 이 라이브러리를 사용하면 서버 비용이 들지 않습니다.

모든 처리가 사용자의 기기에서 일어나기 때문입니다. 또한 네트워크 지연이 없어 빠른 응답이 가능합니다.

무엇보다 개인정보 보호 측면에서 큰 장점이 있습니다. 사용자의 데이터가 서버로 전송되지 않으니까요.

위의 코드를 살펴보겠습니다. pipeline 함수는 특정 작업을 수행하는 AI 모델을 불러옵니다.

sentiment-analysis를 지정하면 감정 분석용 모델이 로드됩니다. 그 다음 classifier에 텍스트를 전달하면 긍정인지 부정인지 분석 결과가 반환됩니다.

실제 현업에서는 어떻게 활용할까요? 쇼핑몰의 리뷰 시스템을 생각해봅시다.

고객이 리뷰를 작성하면 실시간으로 감정을 분석해서 이모티콘을 추천해줄 수 있습니다. 고객센터 챗봇에서는 사용자의 메시지 톤을 파악해서 급한 문의에 우선 대응할 수 있습니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 설명을 들은 김개발 씨는 눈이 반짝였습니다.

"서버 없이 브라우저에서요? 완전 신세계네요!"

실전 팁

💡 - Transformers.js는 WebGL과 WebAssembly를 활용해 브라우저에서 빠르게 동작합니다

• 첫 로딩 시 모델 다운로드가 필요하므로 로딩 인디케이터를 표시해주세요

---

2. Hugging Face와의 관계

김개발 씨가 Transformers.js를 검색하다 보니 자꾸 Hugging Face라는 이름이 등장했습니다. 귀여운 이모티콘 로고가 인상적인데, 도대체 이 회사와 Transformers.js는 무슨 관계일까요?

Hugging Face는 AI 모델의 GitHub라고 불리는 플랫폼입니다. 전 세계 개발자들이 학습시킨 수십만 개의 AI 모델이 이곳에 공개되어 있습니다.

Transformers.js는 바로 이 Hugging Face의 모델들을 JavaScript로 실행할 수 있게 변환한 라이브러리입니다. 덕분에 우리는 직접 AI를 학습시키지 않아도 뛰어난 성능의 모델을 바로 사용할 수 있습니다.

다음 코드를 살펴봅시다.

// Hugging Face 모델 허브에서 모델 불러오기
import { pipeline } from '@xenova/transformers';

// 'Xenova/distilbert-base-uncased-finetuned-sst-2-english'
// 위 모델은 Hugging Face Hub에 공개된 모델입니다
const classifier = await pipeline(
  'sentiment-analysis',
  'Xenova/distilbert-base-uncased-finetuned-sst-2-english'
);

// 특정 모델을 지정하여 사용
const result = await classifier('This product is amazing!');
console.log(result);

김개발 씨는 Transformers.js를 본격적으로 공부하기로 마음먹었습니다. 그런데 공식 문서를 읽다 보니 계속해서 Hugging Face라는 단어가 등장합니다.

이게 대체 뭐길래 이렇게 자주 나오는 걸까요? 박시니어 씨에게 물어보니 이렇게 설명해주었습니다.

"Hugging Face는 AI 세계의 GitHub라고 생각하면 돼요." 개발자들이 코드를 GitHub에 공유하듯이, AI 연구자들은 자신이 학습시킨 모델을 Hugging Face에 공유합니다. 텍스트 번역, 이미지 인식, 음성 합성 등 수십만 개의 모델이 이 플랫폼에 올라와 있습니다.

그리고 대부분 무료로 사용할 수 있습니다. 그렇다면 Transformers라는 이름은 어디서 온 걸까요?

Transformers는 원래 Hugging Face가 만든 Python 라이브러리 이름입니다. 이 라이브러리 덕분에 개발자들이 최신 AI 모델을 쉽게 사용할 수 있게 되었습니다.

Transformers.js는 이 Python 라이브러리의 JavaScript 버전인 셈입니다. 재미있는 점은 Transformers.js가 Hugging Face 공식 프로젝트가 아니라는 것입니다.

Xenova라는 개발자가 개인 프로젝트로 시작했습니다. 하지만 그 가치를 인정받아 현재는 Hugging Face에서 공식적으로 지원하고 있습니다.

위의 코드에서 Xenova라는 이름이 보이시나요? 이것이 바로 그 개발자의 Hugging Face 계정명입니다.

모델 이름 앞에 계정명이 붙는 것은 GitHub의 저장소 주소와 비슷한 방식입니다. 실무에서 이 관계를 어떻게 활용할 수 있을까요?

Hugging Face Hub에 가면 용도별로 정리된 수많은 모델을 찾아볼 수 있습니다. 번역이 필요하면 translation 모델을, 요약이 필요하면 summarization 모델을 검색하면 됩니다.

마음에 드는 모델을 찾았다면 그 이름을 pipeline 함수에 전달하기만 하면 됩니다. 주의할 점도 있습니다.

모든 Hugging Face 모델이 Transformers.js에서 동작하는 것은 아닙니다. ONNX 형식으로 변환된 모델만 사용할 수 있습니다.

다행히 Xenova 계정에는 이미 변환된 수백 개의 인기 모델이 준비되어 있습니다. 김개발 씨는 Hugging Face 웹사이트를 둘러보며 감탄했습니다.

"와, 이렇게 많은 모델이 무료라고요? AI 민주화가 이런 거구나!"

실전 팁

💡 - huggingface.co에서 ONNX 태그가 붙은 모델을 찾으면 Transformers.js에서 바로 사용 가능합니다

• Xenova 계정의 모델들은 웹 환경에 최적화되어 있어 크기가 작고 빠릅니다

---

3. 브라우저 vs Node.js 환경

김개발 씨가 Transformers.js 예제 코드를 실행해보려는데 문득 의문이 들었습니다. "이거 브라우저에서 돌리는 거야, 아니면 Node.js에서 돌리는 거야?" 답은 둘 다입니다.

Transformers.js는 브라우저와 Node.js 두 환경 모두에서 동작합니다. 브라우저에서는 WebGPU나 WebAssembly를 활용하고, Node.js에서는 ONNX Runtime을 사용합니다.

같은 코드가 두 환경에서 모두 작동하므로, 개발할 때 환경을 크게 신경 쓰지 않아도 됩니다.

다음 코드를 살펴봅시다.

// 브라우저 환경 - 클라이언트 사이드
// HTML 파일에서 직접 사용 가능
import { pipeline } from '@xenova/transformers';

// Node.js 환경 - 서버 사이드
// 동일한 코드가 그대로 동작합니다
const translator = await pipeline('translation', 'Xenova/nllb-200-distilled-600M');

// 환경에 관계없이 동일한 API
const result = await translator('Hello, how are you?', {
  src_lang: 'eng_Latn',
  tgt_lang: 'kor_Hang'
});
console.log(result); // 한국어 번역 결과

김개발 씨는 회사에서 두 가지 프로젝트를 진행하고 있습니다. 하나는 React로 만든 웹 애플리케이션이고, 다른 하나는 Node.js 기반의 백엔드 서비스입니다.

두 프로젝트 모두에 AI 기능을 넣고 싶은데, 라이브러리를 따로 배워야 할까요? 박시니어 씨가 반가운 소식을 전해주었습니다.

"Transformers.js 하나면 둘 다 해결돼요." 브라우저 환경에서 Transformers.js가 동작하는 원리를 알아봅시다. 브라우저에는 GPU를 직접 제어할 수 있는 WebGPU라는 최신 기술이 있습니다.

아직 모든 브라우저가 지원하지는 않지만, 지원되는 경우 굉장히 빠른 속도를 낼 수 있습니다. WebGPU를 사용할 수 없는 환경에서는 WebAssembly가 대신 동작합니다.

그렇다면 Node.js 환경에서는 어떨까요? Node.js에서는 ONNX Runtime이라는 마이크로소프트의 추론 엔진을 사용합니다.

이 엔진은 CPU와 GPU 모두 활용할 수 있어서 서버 환경에서도 뛰어난 성능을 보여줍니다. 가장 멋진 점은 API가 동일하다는 것입니다.

위의 코드를 보세요. 이 코드는 브라우저에서도 Node.js에서도 똑같이 동작합니다.

import 문 하나, pipeline 함수 하나로 어느 환경에서든 AI 기능을 사용할 수 있습니다. 그럼 언제 브라우저를 쓰고, 언제 Node.js를 써야 할까요?

브라우저 환경이 적합한 경우가 있습니다. 실시간 상호작용이 필요할 때, 사용자 개인정보를 서버로 보내지 않아야 할 때, 서버 비용을 절약하고 싶을 때입니다.

반면 Node.js 환경이 적합한 경우도 있습니다. 대용량 데이터를 일괄 처리할 때, 더 강력한 하드웨어가 필요할 때, 여러 클라이언트가 같은 결과를 공유할 때입니다.

실제로 두 환경을 함께 사용하는 하이브리드 방식도 있습니다. 간단한 작업은 브라우저에서 처리하고, 복잡한 작업은 서버로 보내는 것입니다.

Transformers.js 덕분에 두 환경의 코드를 거의 동일하게 유지할 수 있습니다. 김개발 씨는 안도의 한숨을 내쉬었습니다.

"휴, 라이브러리 두 개 배울 필요 없겠네요."

실전 팁

💡 - 브라우저에서 WebGPU 지원 여부는 navigator.gpu 객체로 확인할 수 있습니다

• Node.js 18 이상 버전을 권장하며, GPU 가속을 위해서는 별도 설정이 필요합니다

---

4. npm yarn으로 설치하기

이제 본격적으로 Transformers.js를 설치해볼 시간입니다. 김개발 씨는 터미널을 열고 익숙한 npm 명령어를 입력할 준비를 합니다.

React나 Vue처럼 간단히 설치할 수 있을까요?

Transformers.js는 npm과 yarn을 통해 쉽게 설치할 수 있습니다. 패키지 이름은 @xenova/transformers입니다.

설치 후 바로 import하여 사용할 수 있으며, 번들러와의 호환성도 뛰어납니다. Webpack, Vite, Next.js 등 대부분의 프레임워크에서 문제없이 동작합니다.

다음 코드를 살펴봅시다.

// npm으로 설치
// 터미널에서 실행
npm install @xenova/transformers

// 또는 yarn으로 설치
yarn add @xenova/transformers

// 설치 후 프로젝트에서 사용
import { pipeline, env } from '@xenova/transformers';

// 모델 캐시 경로 설정 (선택사항)
env.cacheDir = './models';

// 로컬 모델만 사용하도록 설정 (오프라인 환경)
env.allowLocalModels = true;

김개발 씨는 새 프로젝트 폴더를 만들고 터미널을 열었습니다. 수많은 npm 패키지를 설치해본 경험이 있지만, AI 관련 라이브러리는 처음이라 약간 긴장됩니다.

하지만 걱정할 필요가 없었습니다. Transformers.js 설치는 다른 라이브러리와 다를 바 없이 간단합니다.

터미널에 npm install @xenova/transformers를 입력하면 끝입니다. yarn을 선호한다면 yarn add @xenova/transformers를 사용하면 됩니다.

설치에는 보통 몇 초에서 몇십 초 정도 걸립니다. 패키지 이름에 @xenova가 붙어있는 것이 보이시나요?

이것은 npm의 스코프 기능입니다. Transformers.js를 만든 Xenova 개발자의 네임스페이스 아래에 패키지가 등록되어 있습니다.

설치가 완료되면 바로 사용할 수 있습니다. 위의 코드처럼 import 문으로 필요한 함수를 불러오면 됩니다.

pipeline은 AI 작업을 수행하는 핵심 함수이고, env는 라이브러리 설정을 담당하는 객체입니다. env 객체로 할 수 있는 설정 중 중요한 것이 캐시 경로입니다.

Transformers.js는 처음 모델을 사용할 때 인터넷에서 다운로드합니다. 이 모델 파일들이 저장되는 위치를 지정할 수 있습니다.

기본값은 브라우저의 경우 IndexedDB, Node.js의 경우 홈 디렉토리입니다. 오프라인 환경에서 작업해야 한다면 allowLocalModels 옵션이 유용합니다.

미리 다운로드해둔 모델만 사용하도록 설정할 수 있습니다. 보안이 중요한 기업 환경에서 자주 사용되는 옵션입니다.

번들러 호환성에 대해서도 알아봅시다. Webpack, Vite, Rollup 등 대부분의 번들러에서 잘 동작합니다.

다만 Next.js나 Nuxt 같은 SSR 프레임워크에서는 클라이언트 사이드에서만 실행되도록 주의해야 합니다. 서버 사이드 렌더링 중에 브라우저 전용 API를 호출하면 에러가 발생할 수 있기 때문입니다.

김개발 씨는 설치 명령어를 실행하고 초록색 성공 메시지를 확인했습니다. "생각보다 너무 쉬운데요?"

실전 팁

💡 - package.json의 type을 module로 설정하면 ES 모듈 방식으로 import할 수 있습니다

• Next.js에서는 dynamic import와 ssr: false 옵션을 함께 사용하세요

---

5. CDN으로 바로 사용하기

김개발 씨가 간단한 프로토타입을 만들려고 합니다. 빌드 설정 없이 HTML 파일 하나로 빠르게 테스트해보고 싶은데, npm 설치 없이도 Transformers.js를 사용할 수 있을까요?

CDN을 통해 별도의 설치 없이 Transformers.js를 바로 사용할 수 있습니다. HTML 파일에 script 태그 한 줄만 추가하면 됩니다.

빠른 프로토타이핑이나 학습 목적으로 적합하며, 번들러 설정 없이 순수 HTML에서 AI 기능을 테스트할 수 있습니다.

다음 코드를 살펴봅시다.

<!DOCTYPE html>
<html>
<head>
  <title>Transformers.js CDN 예제</title>
</head>
<body>
  <script type="module">
    // CDN에서 직접 import
    import { pipeline } from 'https://cdn.jsdelivr.net/npm/@xenova/transformers';

    // 텍스트 분류 모델 로드
    const classifier = await pipeline('sentiment-analysis');

    // 분석 실행
    const result = await classifier('I absolutely love this!');
    console.log(result);
    // 결과가 콘솔에 출력됩니다
  </script>
</body>
</html>

가끔은 복잡한 빌드 설정 없이 빠르게 무언가를 테스트해보고 싶을 때가 있습니다. 김개발 씨도 마찬가지였습니다.

상사에게 Transformers.js의 가능성을 보여주고 싶은데, 프로젝트 전체를 세팅할 시간은 없었습니다. 이럴 때 CDN 방식이 유용합니다.

Content Delivery Network의 약자인 CDN은 전 세계에 분산된 서버에서 파일을 제공하는 서비스입니다. npm 패키지들도 CDN을 통해 바로 사용할 수 있습니다.

위의 코드를 보세요. HTML 파일 하나만 있으면 됩니다.

script 태그에 **type="module"**을 지정하고, import 문에서 CDN URL을 직접 사용합니다. 그게 전부입니다.

CDN 주소는 jsdelivr를 사용했습니다. 이 외에도 unpkg, skypack 등 다양한 CDN 서비스가 있습니다.

jsdelivr가 가장 널리 사용되고 안정적입니다. CDN 방식의 장점은 명확합니다.

첫째, 설치가 필요 없습니다. 인터넷만 연결되어 있으면 어디서든 바로 실행할 수 있습니다.

둘째, 빌드 과정이 없습니다. Webpack이나 Vite 같은 도구를 설정할 필요가 없습니다.

셋째, 공유가 쉽습니다. HTML 파일 하나만 보내면 누구든 실행해볼 수 있습니다.

물론 단점도 있습니다. 프로덕션 환경에서는 권장하지 않습니다.

매번 CDN에서 파일을 받아오므로 초기 로딩이 느릴 수 있습니다. 또한 CDN 서비스에 장애가 생기면 여러분의 애플리케이션도 영향을 받습니다.

실제 서비스에는 npm으로 설치하고 번들링하는 것이 좋습니다. 하지만 학습이나 데모 목적으로는 CDN 방식이 최고입니다.

CodePen, JSFiddle 같은 온라인 코드 에디터에서도 이 방식으로 Transformers.js를 사용할 수 있습니다. 김개발 씨는 HTML 파일을 만들어 브라우저에서 열었습니다.

콘솔에 분석 결과가 나타나는 것을 보며 상사에게 보여줄 데모 준비를 마쳤습니다.

실전 팁

💡 - jsdelivr CDN은 npm 패키지를 https://cdn.jsdelivr.net/npm/패키지명 형식으로 제공합니다

• 버전을 고정하려면 @xenova/transformers@2.17.0 처럼 버전을 명시하세요

---

6. 첫 번째 예제 실행하기

드디어 실습 시간입니다. 김개발 씨는 설치를 마치고 첫 번째 AI 프로그램을 작성해보려 합니다.

감정 분석 모델을 사용해서 텍스트가 긍정인지 부정인지 판단하는 간단한 예제를 만들어봅시다.

첫 번째 예제로 감정 분석(Sentiment Analysis) 모델을 실행해봅니다. 이 모델은 주어진 텍스트가 긍정적인지 부정적인지를 판단합니다.

pipeline 함수로 모델을 로드하고, 텍스트를 전달하면 분석 결과가 반환됩니다. 첫 실행 시 모델 다운로드로 시간이 걸릴 수 있습니다.

다음 코드를 살펴봅시다.

import { pipeline } from '@xenova/transformers';

// 감정 분석 파이프라인 생성
// 첫 실행 시 모델 다운로드가 진행됩니다 (약 60MB)
console.log('모델을 불러오는 중...');
const classifier = await pipeline('sentiment-analysis');
console.log('모델 로드 완료!');

// 여러 텍스트 분석하기
const texts = [
  'I love this product! It works perfectly.',
  'This is the worst purchase I ever made.',
  'The quality is okay, nothing special.'
];

// 각 텍스트의 감정 분석
for (const text of texts) {
  const result = await classifier(text);
  console.log(`"${text}"`);
  console.log(`=> ${result[0].label} (${(result[0].score * 100).toFixed(1)}%)\n`);
}

김개발 씨는 코드 에디터를 열고 첫 번째 Transformers.js 프로그램을 작성하기 시작했습니다. 두근거리는 마음으로 한 줄 한 줄 입력합니다.

먼저 pipeline 함수를 import합니다. 이 함수가 Transformers.js의 핵심입니다.

원하는 작업 유형을 문자열로 전달하면 해당 작업을 수행할 수 있는 AI 모델이 준비됩니다. pipeline 함수에 sentiment-analysis를 전달했습니다.

이것은 감정 분석을 의미합니다. Transformers.js는 이 외에도 text-classification, translation, summarization, question-answering 등 다양한 작업 유형을 지원합니다.

첫 실행에서 한 가지 주의할 점이 있습니다. 모델 다운로드에 시간이 걸립니다.

감정 분석에 사용되는 기본 모델은 약 60MB 정도입니다. 인터넷 속도에 따라 몇 초에서 몇 분까지 걸릴 수 있습니다.

하지만 한 번 다운로드되면 캐시에 저장되어 다음부터는 빠르게 로드됩니다. 위의 코드에서는 세 개의 텍스트를 분석합니다.

첫 번째는 명확하게 긍정적인 문장, 두 번째는 부정적인 문장, 세 번째는 중립적인 문장입니다. 분석 결과는 어떻게 나올까요?

label 속성에는 POSITIVE 또는 NEGATIVE가 들어있습니다. score 속성에는 0과 1 사이의 신뢰도 점수가 들어있습니다.

1에 가까울수록 모델이 확신하고 있다는 뜻입니다. 실행 결과를 보면 첫 번째 문장은 POSITIVE 99.9%, 두 번째 문장은 NEGATIVE 99.8%로 나옵니다.

세 번째 중립적인 문장은 POSITIVE나 NEGATIVE 중 하나로 분류되지만 신뢰도가 상대적으로 낮습니다. 이 모델은 이진 분류만 하기 때문입니다.

실무에서는 이 결과를 어떻게 활용할 수 있을까요? 쇼핑몰 리뷰를 자동으로 분류하거나, 고객 문의의 긴급도를 파악하거나, SNS 반응을 모니터링하는 데 사용할 수 있습니다.

김개발 씨는 코드를 실행하고 콘솔에 출력되는 결과를 바라보았습니다. 몇 줄의 코드만으로 AI가 동작한다는 사실이 아직도 신기합니다.

"이제 시작이구나!" 박시니어 씨가 어깨를 두드리며 말했습니다. "잘했어요.

이제 다양한 모델을 탐험해보세요. 번역, 요약, 질문 답변...

가능성이 무궁무진해요."

실전 팁

💡 - 첫 로딩 시간을 줄이려면 더 작은 모델을 선택하거나 모델을 미리 다운로드해두세요

• 한국어 감정 분석이 필요하면 한국어로 학습된 모델을 Hugging Face에서 찾아보세요

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!