허깅페이스, 'Transformers.js 크롬 확장' 가이드 공개… Gemma-4-E2B-it·MiniLM-L6-v2 ONNX로 로컬 추론 아키텍처 정리
허깅페이스(Hugging Face)가 Transformers.js를 활용해 Chrome 확장 프로그램에 로컬 AI 기능을 탑재하는 방법을 정리한 가이드를 블로그에 공개했다. 가이드는 'Transformers.js Gemma 4 Browser Assistant' 프로젝트의 아키텍처를 그대로 재현하는 형태로, 공개된 확장과 오픈소스 코드(github.com/nico-martin/gemma4-browser-extension)를 참고 구현체로 제시한다.
Manifest V3(MV3) 제약 아래 모델을 호스팅하는 백그라운드 서비스 워커, 사이드 패널 채팅 UI, 페이지 단위 액션을 처리하는 콘텐트 스크립트라는 3개 런타임 구조가 핵심이다. public/manifest.json의 진입점은 background.service_worker, side_panel.default_path, content_scripts(.js, document_idle 시점) 세 가지로 정의되며, 백그라운드 서비스 워커가 chrome.action.onClicked 이벤트로 사이드 패널을 연다.
설계의 핵심은 무거운 오케스트레이션을 모두 백그라운드에 두고 UI와 페이지 로직은 가볍게 유지하는 것이다. 백그라운드는 에이전트 라이프사이클·모델 초기화·툴 실행·피처 추출 같은 공유 서비스를 담당하는 컨트롤 플레인이고, 사이드 패널은 채팅 입출력과 스트리밍을 처리하는 상호작용 계층, 콘텐트 스크립트는 DOM 추출과 하이라이트를 처리하는 페이지 브릿지 역할을 한다.
이런 구조 덕에 대화 내역도 백그라운드의 Agent.chatMessages에 위치한다. UI는 AGENT_GENERATE_TEXT 같은 이벤트를 보내고 백그라운드가 메시지를 추가·추론한 뒤 MESSAGES_UPDATE를 사이드 패널에 다시 보낸다. 이를 통해 모델 중복 로드를 막고 UI 반응성을 유지하며 Chrome의 DOM 접근 보안 경계도 지킬 수 있다고 가이드는 설명한다.
모델은 두 가지 역할로 나뉜다. 텍스트 생성·추론은 onnx-community/gemma-4-E2B-it-ONNX(text-generation, q4f16) 모델이, 벡터 임베딩은 onnx-community/all-MiniLM-L6-v2-ONNX(feature-extraction, fp32) 모델이 각각 담당한다. Gemma 4가 추론과 툴 결정을 맡고, MiniLM은 ask_website·find_history 같은 시맨틱 유사도 검색에 쓸 임베딩을 생성한다.
모든 추론은 src/background/background.ts에서 실행된다. 텍스트 생성은 pipeline("text-generation", ...)으로, 임베딩은 pipeline("feature-extraction", ...)으로 처리되며, 새로 만든 DynamicCache 클래스를 통해 일관된 KV 캐싱이 활성화된다. 모델이 백그라운드 서비스 워커에서 로드되므로 아티팩트 캐시는 웹사이트 origin이 아닌 chrome-extension://<extension-id> origin에 묶여 확장 설치 단위로 단일 캐시를 공유한다.
모델 라이프사이클은 명시적으로 분리된다. CHECK_MODELS는 캐시 상태와 남은 다운로드 용량을 점검하고, INITIALIZE_MODELS는 모델 다운로드·초기화를 수행하며 DOWNLOAD_PROGRESS 이벤트를 UI에 전송한다. 생성 파이프라인은 src/background/agent/Agent.ts, 임베딩 파이프라인은 src/background/utils/FeatureExtractor.ts에 각각 장기 유지된다. MV3 서비스 워커는 일시 중지·재시작될 수 있어 런타임 상태는 복구 가능한 형태로 다뤄야 한다고 가이드는 강조한다.
권한 설계도 보안 경계의 일부로 다뤄진다. public/manifest.json은 sidePanel(사이드 패널 제어), storage(설정·툴 상태 영속화), scripting·tabs(탭 인지 툴과 페이지 액션), host_permissions http(s)://*/*(임의 사이트에서의 콘텐츠 추출·하이라이트)만 요구하며, 추론이 확장 런타임 내부에서 로컬로 수행됨을 사용자에게 분명히 알려야 한다고 권고한다.
툴 호출은 모델별 채팅 템플릿에 따라 형식이 달라진다. Gemma-4 계열 템플릿에서는 모델이 호출 결정 시 특수 툴 콜 토큰 블록을 출력하며, 가이드는 webMcp 정규화 레이어와 extractToolCalls 파서로 모델 출력을 결정성 있는 툴 실행으로 변환한다. 예시 코드에서는 @huggingface/transformers의 pipeline으로 텍스트 생성기를 초기화하고 device: "webgpu" 옵션과 함께 q4f16 dtype, 'getWeather' 같은 함수 도구 스키마를 전달한다.