브라우저에서 WebGPU로 LLM 실행하기

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

WebLLM은 WebGPU와 WebAssembly를 이용해 서버 없이 브라우저에서 LLM 추론을 실행하는 고성능 inference engine이다. OpenAI API 형식의 chat completions를 기반으로 스트리밍, JSON mode, seed 기반 재현성을 제공하고, Llama 3·Phi 3·Gemma·Mistral·Qwen 계열 모델과 MLC 형식의 custom model을 지원한다. 모델은 첫 실행 때 브라우저에 다운로드하고 Cache API, IndexedDB, OPFS 등의 backend에 저장하며, Web Worker나 Service Worker로 추론 작업과 모델 수명주기를 분리할 수 있다. 모델 파일에는 SRI 해시를 지정해 config, WASM, tokenizer의 무결성을 검증할 수 있지만, 첫 다운로드 시간과 브라우저별 WebGPU·저장소 지원 여부는 구현 과정에서 고려해야 한다.

섹션별 상세

WebLLM은 모델 추론을 서버에 보내지 않고 브라우저 내부에서 수행하도록 설계된 inference engine이다. WebGPU가 GPU 연산을 가속하고 WebAssembly 기반 라이브러리가 모델 계산을 실행하므로, 웹 애플리케이션이 로컬 환경에서 LLM을 호출하는 구조를 만든다. 이 방식은 서버 지원 없이 브라우저 기반 AI assistant와 개인정보 보호형 애플리케이션을 구축하는 기반이 된다.

WebLLM은 Llama 3, Llama 2, Phi 3, Phi 2, Gemma-2B, Mistral-7B 계열, Qwen2 0.5B·1.5B·7B 등을 prebuilt model로 제공한다. 각 모델은 weight와 metadata를 담은 model URL, 계산용 WebAssembly library를 가리키는 model_lib로 구성되며, 사용자는 MLC 형식의 custom model과 weight variant를 별도로 연결할 수 있다. 따라서 기본 목록에 없는 모델도 MLC LLM의 컴파일·배포 절차를 거쳐 WebLLM에 등록할 수 있다.

패키지는 NPM, Yarn, pnpm 또는 CDN으로 설치하며 CreateMLCEngine이 엔진 생성과 모델 로딩을 한 번에 처리한다. 첫 호출에서는 모델 파일을 다운로드하므로 시간이 오래 걸릴 수 있고, initProgressCallback으로 진행 상태를 전달할 수 있다. MLCEngine을 먼저 동기적으로 만든 뒤 engine.reload(selectedModel)을 비동기 호출하는 방식으로 두 단계를 분리하는 것도 가능하다.

typescript

import { CreateMLCEngine } from "@mlc-ai/web-llm";

// Callback function to update model loading progress
const initProgressCallback = (initProgress) => {
  console.log(initProgress);
};

const selectedModel = "Llama-3.1-8B-Instruct-q4f32_1-MLC";

const engine = await CreateMLCEngine(
  selectedModel,
  { initProgressCallback: initProgressCallback },
  // engineConfig
);

선택한 모델을 비동기적으로 내려받고 MLCEngine을 생성하면서 로딩 진행률을 콜백으로 전달합니다.

엔진의 chat.completions.create 인터페이스는 OpenAI API와 같은 메시지 형식을 받아 응답을 생성한다. stream을 true로 설정하면 결과를 AsyncGenerator 청크로 순차 수신하고, JSON mode는 지정한 구조의 출력을 만들며, seed는 재현 가능한 생성을 지원한다. function-calling은 tools와 tool_choice를 이용한 preliminary support가 제공되는 단계로 표시되어 있다.

모델 캐시는 Cache API를 기본값으로 사용하며 IndexedDB, OPFS, experimental Chrome Cross-Origin Storage API backend도 선택할 수 있다. OPFS는 환경 지원 여부와 access mode에 따라 동작이 달라지고, cross-origin backend는 호환 확장 프로그램 설치가 필요하며 tensor-cache 삭제는 확장 프로그램이 관리한다. 캐시 정책을 조정하면 반복 방문 때 모델을 다시 내려받는 부담을 줄일 수 있지만, backend별 제약을 애플리케이션에서 처리해야 한다.

typescript

const messages = [
  { role: "system", content: "You are a helpful AI assistant." },
  { role: "user", content: "Hello!" },
];

const reply = await engine.chat.completions.create({
  messages,
});

console.log(reply.choices[0].message);
console.log(reply.usage);

초기화한 엔진에 OpenAI API 형식의 메시지를 보내고 응답과 사용량 정보를 받습니다.

Web Worker와 Service Worker용 엔진은 모델 계산을 별도 실행 맥락으로 옮긴다. WebWorkerMLCEngine은 기존 MLCEngineInterface를 유지하면서 UI 스레드와 추론 작업을 분리하고, ServiceWorkerMLCEngine은 여러 페이지 방문에서 모델을 다시 로드하지 않도록 지원한다. 다만 Service Worker는 브라우저가 언제든 종료할 수 있으므로 heartbeat와 오류 처리를 함께 구성해야 한다.

typescript

const messages = [
  { role: "system", content: "You are a helpful AI assistant." },
  { role: "user", content: "Hello!" },
];

// Chunks is an AsyncGenerator object
const chunks = await engine.chat.completions.create({
  messages,
  temperature: 1,
  stream: true,

stream 옵션을 true로 설정해 생성 결과를 청크 단위로 실시간 수신합니다.

WebLLM은 Chrome extension 예제를 제공하며, Service Worker와 WebGPU를 결합한 persistent background 실행 방식도 지원한다. 확장 프로그램은 브라우저 기능에 로컬 LLM을 연결하고 WebLLM Assistant 같은 별도 프로젝트로 확장할 수 있다. 이 구조는 웹 페이지 안의 chatbot뿐 아니라 브라우저 상주형 assistant를 구현할 때 활용된다.

typescript

import { CreateWebWorkerMLCEngine } from "@mlc-ai/web-llm";

async function main() {
  // Use a WebWorkerMLCEngine instead of MLCEngine here
  const engine = await CreateWebWorkerMLCEngine(
    new Worker(new URL("./worker.ts", import.meta.url), { type: "module" }),
    selectedModel,
    { initProgressCallback },
    // engineConfig
  );
  // everything else remains the same
}

Web Worker에서 엔진을 실행해 메인 스레드의 UI 작업과 모델 추론을 분리합니다.

모델 아티팩트에는 SRI 해시를 지정해 무결성 검사를 적용할 수 있다. config, model_lib, tokenizer 파일별 SHA-256·SHA-384·SHA-512 해시를 비교하고, 불일치 시 IntegrityError를 발생시키거나 onFailure를 warn으로 설정해 경고 후 계속 진행한다. integrity 필드를 생략하면 기존처럼 검증 없이 동작하므로 배포 환경의 파일 신뢰성을 별도로 결정해야 한다.

용어 해설

WebGPU: — 브라우저에서 GPU 기능을 직접 활용하도록 제공하는 웹 표준 API입니다. WebLLM은 WebGPU를 통해 모델 연산을 하드웨어 가속하고, 서버로 입력과 출력을 보내지 않은 채 브라우저 내부에서 LLM 추론을 수행합니다. 브라우저 기반 AI 애플리케이션의 처리 속도와 개인정보 보호에 영향을 주는 핵심 실행 계층입니다.
WebAssembly: — C와 C++ 같은 언어로 작성한 코드를 웹 브라우저에서 빠르게 실행할 수 있는 바이너리 형식입니다. WebLLM은 모델 계산을 가속하는 WASM 라이브러리를 모델 아티팩트와 함께 로드하며, JSON 구조화 생성 같은 기능도 WebAssembly 영역에서 처리합니다. 브라우저 내 추론의 실행 기반으로 사용됩니다.
OpenAI API 호환성(OpenAI API Compatibility): — OpenAI API와 같은 요청 구조와 호출 방식을 다른 모델 실행 환경에서도 사용할 수 있게 만드는 호환 계층입니다. WebLLM은 동일한 chat completions 인터페이스로 스트리밍, JSON mode, seed 기반 재현성을 제공하며, 모델 이름은 엔진 생성 또는 reload 단계에서 지정합니다. 기존 애플리케이션의 로컬 모델 전환을 단순화합니다.
Subresource Integrity: — 브라우저가 내려받은 파일의 해시를 비교해 지정된 원본과 일치하는지 검증하는 보안 방식입니다. WebLLM은 모델 설정, WASM 라이브러리, tokenizer 파일에 SHA-256·SHA-384·SHA-512 해시를 지정할 수 있으며, 불일치 시 오류를 발생시키거나 경고만 남깁니다. 모델 아티팩트 변조를 감지하는 데 사용됩니다.
Web Worker: — 브라우저의 주 실행 스레드와 분리된 작업 스레드에서 JavaScript를 실행하는 기능입니다. WebLLM은 동일한 MLCEngine 인터페이스를 구현하는 WebWorkerMLCEngine을 제공해 모델 계산을 별도 스레드로 옮깁니다. 그 결과 추론 중 사용자 인터페이스의 응답성을 유지할 수 있습니다.