How to Use Transformers.js in a Chrome Extension

🖼️ 인포그래픽

How to Use Transformers.js in a Chrome Extension 내용을 설명하는 본문 이미지

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Manifest V3 크롬 확장 프로그램에서 모델 실행과 상태 관리는 백그라운드 서비스 워커에 집중하고, 사이드 패널과 콘텐츠 스크립트는 각각 사용자 인터페이스와 웹페이지 조작에 전념하도록 구성하는 Transformers.js 구현 안내서다.

📌 핵심 요약

확장 프로그램은 모델과 에이전트를 관리하는 백그라운드 서비스 워커, 채팅을 제공하는 사이드 패널, 웹페이지 내용을 추출하고 요소를 강조하는 콘텐츠 스크립트의 세 실행 영역으로 나뉜다.
텍스트 생성에는 양자화된 Gemma 4 E2B 모델을, 의미 유사도 검색에는 MiniLM 임베딩 모델을 사용하며, 모든 추론을 백그라운드에서 실행해 모델 중복 적재와 사용자 인터페이스 지연을 줄인다.
실행 영역 사이의 작업은 명시적으로 정의된 메시지 유형으로 전달하고, 백그라운드를 단일 조정자로 삼아 대화 상태, 모델 초기화, 도구 실행과 결과 배포를 일관되게 관리한다.
에이전트는 모델의 도구 호출 출력을 정규화하고 파싱한 뒤 실제 확장 프로그램 기능을 실행하며, 도구 결과를 다음 추론 입력으로 되돌려 도구 호출이 사라질 때까지 반복한다.
대화, 설정, 벡터 기록, 웹페이지 콘텐츠는 수명과 접근 방식에 따라 메모리, 크롬 로컬 저장소, IndexedDB, 백그라운드 캐시에 나누어 보관하고, 빌드 결과는 매니페스트의 진입점과 정확히 일치시킨다.

🧩 주요 포인트

확장 프로그램은 모델과 에이전트를 관리하는 백그라운드 서비스 워커, 채팅을 제공하는 사이드 패널, 웹페이지 내용을 추출하고 요소를 강조하는 콘텐츠 스크립트의 세 실행 영역으로 나뉜다.
텍스트 생성에는 양자화된 Gemma 4 E2B 모델을, 의미 유사도 검색에는 MiniLM 임베딩 모델을 사용하며, 모든 추론을 백그라운드에서 실행해 모델 중복 적재와 사용자 인터페이스 지연을 줄인다.
실행 영역 사이의 작업은 명시적으로 정의된 메시지 유형으로 전달하고, 백그라운드를 단일 조정자로 삼아 대화 상태, 모델 초기화, 도구 실행과 결과 배포를 일관되게 관리한다.
에이전트는 모델의 도구 호출 출력을 정규화하고 파싱한 뒤 실제 확장 프로그램 기능을 실행하며, 도구 결과를 다음 추론 입력으로 되돌려 도구 호출이 사라질 때까지 반복한다.
대화, 설정, 벡터 기록, 웹페이지 콘텐츠는 수명과 접근 방식에 따라 메모리, 크롬 로컬 저장소, IndexedDB, 백그라운드 캐시에 나누어 보관하고, 빌드 결과는 매니페스트의 진입점과 정확히 일치시킨다.

🧠 상세 정리

1. 구현 목표와 전체 구조

이 글은 Manifest V3 제약 아래에서 Transformers.js로 로컬 인공지능 기능을 실행하려는 크롬 확장 프로그램 개발자를 대상으로 한다. 구현 목표는 공개된 Gemma 4 Browser Assistant와 같은 구조를 재현하는 것으로, 백그라운드 서비스 워커가 모델을 호스팅하고 사이드 패널이 지속적인 채팅 화면을 제공하며 콘텐츠 스크립트가 웹페이지 수준의 작업을 맡는다. 설명의 초점은 React 화면 구성이나 Vite의 세부 설정이 아니라, 서로 다른 크롬 실행 영역에 어떤 책임을 배치하고 이들을 어떻게 조율할지에 맞춰져 있다. 최종적으로 무거운 모델 실행과 에이전트 제어는 백그라운드에 집중하고, 사용자 인터페이스와 문서 객체 모델 접근 영역은 필요한 기능만 수행하는 얇은 클라이언트로 유지하는 것이 핵심 원칙이다.

2. Manifest V3 실행 영역과 메시지 흐름

확장 프로그램의 진입점은 public/manifest.json에서 정의되며, background.js는 백그라운드 서비스 워커로, sidebar.html은 사이드 패널로, content.js는 일반 웹사이트에서 document_idle 시점에 실행되는 콘텐츠 스크립트로 연결된다. 백그라운드는 확장 프로그램 아이콘 클릭도 처리해 현재 탭에 사이드 패널을 열고, 사이드 패널은 채팅 입력과 출력, 스트리밍 갱신, 모델 설정 화면을 담당하며, 콘텐츠 스크립트는 페이지 데이터 추출과 요소 강조를 처리한다. 실행 영역 사이에서는 CHECK_MODELS, INITIALIZE_MODELS, AGENT_GENERATE_TEXT, MESSAGES_UPDATE, EXTRACT_PAGE_DATA, HIGHLIGHT_ELEMENTS처럼 역할이 명시된 메시지를 사용한다. 예를 들어 사이드 패널이 텍스트 생성을 요청하면 백그라운드가 대화 기록에 메시지를 추가하고 추론과 도구 실행을 수행한 뒤, 갱신된 메시지 목록을 다시 보내 화면을 다시 그리게 한다. 이 구조에서 백그라운드는 유일한 조정자이고, 사이드 패널과 콘텐츠 스크립트는 전문화된 요청자이자 결과 표현 계층으로 동작한다.

3. 모델 역할 분리와 백그라운드 추론

확장 프로그램은 텍스트 생성과 벡터 임베딩을 서로 다른 모델에 맡긴다. 텍스트 생성에는 q4f16 형식의 onnx-community/gemma-4-E2B-it-ONNX를 사용해 추론과 도구 선택을 처리하고, 의미 검색에는 fp32 형식의 onnx-community/all-MiniLM-L6-v2-ONNX를 사용해 ask_website와 find_history에 필요한 정규화 벡터를 생성한다. 두 파이프라인은 모두 백그라운드에서 실행되므로 여러 화면이나 탭이 각자 모델을 적재하지 않아도 되고, 사이드 패널은 무거운 추론 작업에서 분리되어 반응성을 유지할 수 있다. 모델 파일도 개별 웹사이트의 출처가 아니라 확장 프로그램 출처 아래에 캐시되기 때문에 설치된 확장 프로그램 전체가 하나의 캐시를 공유한다. 다만 Manifest V3 서비스 워커는 중지되었다가 다시 시작될 수 있으므로, 실행 중인 모델 상태를 영구적인 것으로 간주하지 않고 필요할 때 복구하고 재초기화할 수 있게 설계해야 한다.

4. 모델 다운로드와 권한·개인정보 설계

모델 수명 주기는 명시적인 메시지와 사용자 인터페이스 상태로 관리된다. CHECK_MODELS는 캐시에 이미 존재하는 파일을 조사하고 남은 다운로드 크기를 추정하며, INITIALIZE_MODELS는 실제 다운로드와 초기화를 수행하면서 DOWNLOAD_PROGRESS 메시지로 진행 상황을 사이드 패널에 전달한다. 초기 설정이 끝난 뒤에는 Agent의 생성 파이프라인과 FeatureExtractor의 임베딩 파이프라인을 장기 인스턴스로 재사용하되, 서비스 워커 재시작에 대비한 복구 경로를 유지한다. 매니페스트는 사이드 패널 제어를 위한 sidePanel, 설정 보존을 위한 storage, 탭 인식 및 페이지 작업을 위한 tabs와 scripting, 임의의 웹사이트에서 추출과 강조를 수행하기 위한 웹 주소 권한을 요청한다. 권한은 기능 구현의 부속 사항이 아니라 사용자 신뢰와 크롬 웹 스토어 심사 위험에 직접 연결되므로, 실제 기능에 필요한 범위만 요청하고 데이터가 확장 프로그램 내부에서 로컬로 처리된다는 점을 분명히 설명해야 한다.

5. 모델의 도구 호출과 실행 인터페이스

에이전트형 동작을 만들려면 대화 메시지와 함께 도구의 이름, 설명, 매개변수 구조를 모델에 전달해야 한다. Transformers.js는 해당 입력을 모델별 채팅 템플릿에 맞게 구성하며, Gemma 4 계열 템플릿에서는 모델이 도구를 사용하기로 결정했을 때 특별한 도구 호출 토큰 블록을 출력할 수 있다. 이 출력은 곧바로 확장 프로그램 기능을 실행할 수 있는 일반 함수 호출이 아니므로, webMcp 계층이 도구를 이름·설명·입력 스키마·실행 함수 형태로 정규화하고 extractToolCalls가 모델 출력을 결정 가능한 호출 정보로 파싱한다. 제공되는 도구에는 열린 탭 조회, 탭 이동, 주소 열기, 탭 닫기, 방문 기록 검색, 현재 웹사이트 질의, 웹페이지 요소 강조 등이 포함된다. 즉 모델은 어떤 기능과 인수를 사용할지 선택하지만, 실제 실행은 백그라운드가 검증 가능한 인터페이스를 통해 담당하며 모델 고유의 출력 형식과 크롬 기능 사이를 별도의 계층이 연결한다.

6. 에이전트 반복 실행과 대화 기록 분리

Agent.runAgent의 중요한 설계는 모델 추론용 내부 기록과 사용자에게 보여 주는 대화 기록을 분리하는 것이다. 내부 messages에는 시스템, 사용자, 도구, 어시스턴트 발화가 모델 입력에 필요한 순서로 저장되고, chatMessages에는 스트리밍되는 답변과 도구 실행 정보, 성능 지표처럼 화면에 표시할 데이터가 저장된다. 사용자가 입력하면 백그라운드는 chatMessages에 사용자 메시지와 빈 어시스턴트 메시지를 추가한 뒤 토큰을 스트리밍하고, 최종 또는 중간 출력을 파싱해 일반 답변과 도구 호출을 분리한다. 사용자에게는 읽기 쉬운 텍스트를 유지하면서 도구 호출은 백그라운드에서 실행하고, 실행 결과는 화면용 도구 메타데이터에 기록하는 동시에 다음 모델 입력에 포함한다. 모델이 더 이상 도구를 요청하지 않을 때까지 이 과정을 반복한 후 최종 답변과 성능 지표를 확정하므로, 화면의 대화는 깔끔하게 유지하면서도 내부에서는 재현 가능한 도구 실행 순서를 보존할 수 있다.

7. 상태의 수명에 따른 저장 위치 분리

Manifest V3에서는 상태를 어디에 둘지가 실행 구조만큼 중요하며, 이 구현은 데이터의 수명과 접근 방식에 따라 저장 위치를 구분한다. 빠른 대화 조율에 필요한 Agent.chatMessages는 백그라운드 메모리에 두어 사이드 패널이 갱신되더라도 하나의 기준 상태를 사용하고, 세션을 넘어 유지되어야 하는 도구 설정과 사용자 선택은 chrome.storage.local에 저장한다. 의미 검색을 위한 벡터 기록은 데이터 규모가 더 크므로 VectorHistoryDB라는 IndexedDB 저장소에 보관하고, 웹페이지에서 추출한 콘텐츠는 WebsiteContentManager가 활성 주소를 키로 삼아 백그라운드 캐시에 유지한다. 이 배치는 모든 데이터를 한 저장소에 넣는 대신 짧게 유지되는 상태, 영속 설정, 대용량 검색 데이터, 현재 페이지 기반 임시 데이터를 각각 적합한 수단에 맡긴다. 결과적으로 사용자 인터페이스는 상태의 원본을 직접 소유하지 않고 백그라운드의 기준 상태를 구독하며, 재실행이 가능한 데이터와 지속되어야 하는 데이터를 구별할 수 있다.

8. 빌드 산출물과 확장 가능한 사용자 인터페이스

빌드는 src/sidebar/index.html, src/background/background.ts, src/content/content.ts를 각각 진입점으로 삼고, 결과 파일을 매니페스트가 기대하는 sidebar.html, background.js, content.js 경로와 이름에 맞춰야 한다. 특히 콘텐츠 스크립트는 실행 중 추가 청크를 불러오는 문제를 피하도록 독립적인 단일 산출물로 만드는 것이 중요하며, 각 크롬 실행 영역마다 예측 가능한 파일 하나를 제공하는 것이 기본 목표다. 같은 백그라운드 중심 구조는 사이드 패널에만 한정되지 않아, 짧은 작업용 팝업, 장시간 대화를 위한 사이드 패널, 탭별 맥락을 가진 에이전트, 팝업·사이드 패널·설정 화면을 함께 쓰는 혼합 구성에도 적용할 수 있다. 전역 상태가 필요한지, tabId별 상태가 필요한지, 사이트별 상태가 필요한지를 먼저 결정한 뒤 그 상태와 모델 추론을 백그라운드에 배치하면 된다. 여러 사용자 인터페이스 진입점은 동일한 메시지 계약과 백그라운드 조정자를 재사용하고, 콘텐츠 스크립트는 보안 경계상 필요한 웹페이지 접근만 담당하도록 유지한다.

🧾 핵심 주장 / 시사점

모델을 백그라운드에 한 번만 적재하고 모든 사용자 인터페이스가 같은 조정자와 메시지 계약을 사용하게 하면 메모리 중복을 줄이면서 대화 상태와 도구 실행 순서를 일관되게 유지할 수 있다.
Manifest V3 서비스 워커는 중지와 재시작이 가능하므로, 모델 인스턴스와 메모리 대화 상태는 복구 가능한 실행 상태로 취급하고 영속 설정과 검색 데이터는 별도의 저장소에 분리해야 한다.
도구 호출 모델의 출력은 모델별 채팅 템플릿에 의존하므로, 출력 파싱과 도구 정규화 계층을 모델 추론과 실제 크롬 기능 사이에 두는 것이 결정적인 실행 흐름을 만드는 핵심이다.