크롬 프롬프트 API 완벽 가이드 — Gemini Nano로 브라우저 내 AI 개발하기

크롬 프롬프트 API 완벽 가이드 — Gemini Nano로 브라우저 내 AI 개발하기

크롬 프롬프트 API — 브라우저 내장 AI의 새로운 시대

크롬(Chrome) 브라우저에 Gemini Nano가 내장되었다. 별도의 API 키도, 서버 호출도, 데이터 전송도 없이, 브라우저 안에서 AI 모델이 작동한다. Google's Prompt API가 그 중심에 있다. 이번 글에서는 크롬 프롬프트 API의 동작 원리, 개발 방법, 실무 활용 사례를 살펴본다.

크롬 프롬프트 API란?

크롬 프롬프트 API(Prompt API)는 브라우저에 내장된 경량 LLM인 Gemini Nano를 JavaScript로 직접 호출할 수 있게 해주는 Web API다. 2025년 Google I/O에서 처음 발표되었으며, 현재 Chrome 127+ (Beta, Dev, Canary)에서 사용할 수 있다.

핵심 특징은 다음과 같다:

• 디바이스 내 실행(On-Device): Gemini Nano가 WebAssembly/WebGPU로 브라우저 내부에서 완전히 실행된다
• 데이터 전송 없음: 사용자 데이터가 Google 서버나 제3자로 전송되지 않는다
• 도메인 간 공유: 한 번 설치되면 해당 기기의 모든 웹페이지와 확장 프로그램이 모델을 공유한다
• 스트리밍/비스트리밍 지원: prompt()와 promptStreaming() 두 가지 방식 제공

내장 AI API 시리즈

크롬은 Prompt API 외에도 여러 내장 AI API를 제공하고 있다:

API	용도
Prompt API	범용 프롬프트 실행
Summarizer API	텍스트 요약
Writer API	글 작성 보조
Rewriter API	텍스트 재작성
Translator API	번역
Language Detector API	언어 감지

시스템 요구 사항

Prompt API를 사용하기 위해서는 다음 조건을 만족해야 한다.

지원 OS

• Windows 10/11
• macOS 13 (Ventura) 이상
• Linux
• ChromeOS (Platform 16389.0.0 이상, Chromebook Plus 기기)

Android, iOS, 일반 Chromebook은 현재 미지원이다.

하드웨어 요구 사항

항목	조건
디스크 여유 공간	Chrome 프로필이 있는 볼륨에 최소 22GB
GPU	4GB 이상의 VRAM
CPU	16GB RAM 이상, 4코어 이상
네트워크	초기 모델 다운로드 시에만 필요 (이후 오프라인 사용 가능)

마이크 활용 (오디오 입력)을 위해서는 GPU가 필수다.

개발 환경 설정

1단계: 크롬 채널 설치

Chrome Beta (버전 127 이상) 또는 Chrome Canary를 설치한다. https://www.google.com/chrome/beta/ 에서 받을 수 있다.

2단계: 플래그 활성화

크롬 주소창에 다음 주소를 입력하고 두 플래그를 Enabled로 설정한다.

chrome://flags/#optimization-guide-on-device-model

chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

설정 변경 후 Relaunch를 클릭하여 브라우저를 재시작한다.

3단계: 모델 확인

주소창에 chrome://components를 입력하고 On-Device Model 구성 요소가 최신 상태인지 확인한다. 없다면 수동으로 업데이트 버튼을 클릭한다.

4단계: 동작 확인

개발자 콘솔(F12)에서 다음 코드로 API 사용 가능 여부를 확인할 수 있다.

const availability = await LanguageModel.availability();

console.log(availability);
// "readily" → 즉시 사용 가능
// "downloading" → 다운로드 중
// "after-download" → 다운로드 후 사용 가능
// "no" → 사용할 수 없음

기본 사용법

세션 생성

// 세션 생성 (다운로드 프롬프트 표시)

const session = await LanguageModel.create({
monitor(m) {
m.addEventListener('downloadprogress', (e) => {
console.log(다운로드 ${e.loaded * 100}%);
});
}
});

기본 프롬프트 실행

// 비스트리밍 방식

const result = await session.prompt('한국의 수도는 어디인가요?');
console.log(result);
// "대한민국의 수도는 서울특별시입니다."

스트리밍 응답

// 스트리밍 방식

const stream = session.promptStreaming('AI의 미래에 대해 설명해 주세요');
for await (const chunk of stream) {
process.stdout.write(chunk);
}

시스템 프롬프트 설정

const session = await LanguageModel.create({

initialPrompts: [
{ role: 'system', content: '당신은 친절한 기술 컨설턴트입니다.' },
{ role: 'user', content: '프롬프트 API란?' },
{ role: 'assistant', content: '프롬프트 API는...' }
]
});

실전 활용 사례

1. AI-powered 검색

페이지 내용을 기반으로 사용자의 질문에 직접 답변하는 검색 기능을 만들 수 있다.

async function answerFromPage(question) {

const session = await LanguageModel.create({
initialPrompts: [
{ role: 'system', content: '다음 페이지 내용을 바탕으로 질문에 답변해줘. 답을 모르면 "모른다"고 해.' },
{ role: 'user', content: 페이지 내용: ${document.body.innerText} }
]
});
return session.prompt(질문: ${question});
}

2. 자동 캘린더 이벤트 생성

웹페이지에서 일정 정보를 자동으로 추출하여 캘린더 이벤트를 생성하는 확장 프로그램 예시다.

document.querySelector('.event-card').addEventListener('click', async () => {

const eventText = document.querySelector('.event-card').innerText;
const session = await LanguageModel.create();
const structured = await session.prompt(
다음 텍스트에서 일정을 추출해서 JSON으로 반환해줘.  +
형식: {"title": "제목", "date": "날짜", "time": "시간", "location": "장소"}  +
텍스트: ${eventText}
);
const event = JSON.parse(structured);
// 캘린더 API 호출...
});

3. 이미지 설명 생성 (멀티모달)

이미지 입력을 활용한 예시로, 사용자가 업로드한 이미지의 설명을 생성할 수 있다.

const session = await LanguageModel.create({

expectedInputs: [{ type: 'image' }]
});
const imgElement = document.querySelector('#uploaded-image');
const result = await session.prompt([
{ role: 'user', content: [
{ type: 'image', value: imgElement },
{ type: 'text', value: '이 이미지에 대한 설명을 2문장으로 작성해줘.' }
]}
]);

매개변수 조절

TopK와 Temperature

응답의 창의성과 다양성을 조절할 수 있다.

// Chrome 확장 프로그램에서만 사용 가능

const params = await LanguageModel.params();
// { defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2 }

const creativeSession = await LanguageModel.create({
temperature: 1.8,
topK: 64
});

응답 프리픽스 지정

응답의 형식을 사전 지정하여 모델의 출력 포맷을 제어할 수 있다.

const result = await session.prompt([

{ role: 'user', content: 'Create a TOML character sheet for a gnome barbarian' },
{ role: 'assistant', content: '`toml\n', prefix: true }
]);

주의사항과 제한 사항

사실 정확성에 대한 한계

Gemini Nano는 사실 정확한 정보 검색보다는 요약, 분류, 재작성 작업에 최적화된 모델이다. 정확한 사실 기반 질의에는 클라우드 기반 모델을 병행 사용하는 것이 좋다.

컨텍스트 창 제한

Gemini Nano의 컨텍스트 창 크기는 제한적이다. 대용량 문서 처리가 필요한 경우 Chunked Augmented Generation (CAG) 방식으로 프롬프트를 분할 처리해야 한다.

한국어 지원 현황

현재 Prompt API의 멀티모달 입력에서 지원되는 언어는 영어(en), 일본어(ja), 스페인어(es) 가 공식 지원 목록에 있다. 한국어의 경우 텍스트 입력은 가능하나, 최적의 결과를 위해서는 영어 시스템 프롬프트와 병행 사용하는 것을 권장한다.

보안 고려사항

로컬에서 모델이 실행되지만, 추론 컨텍스트가 Chrome 내부에서 처리된다는 점에 대한 신뢰가 필요하다. 민감한 데이터 처리 시에는 이 점을 고려하여 추가적인 보안 처리를 검토해야 한다.

정리

크롬 프롬프트 API는 브라우저 기반 AI 응용의 새로운 지평을 연다. API 키 관리 부담 없이, 서버 비용 없이, 네트워크 지연 없이 브라우저 안에서 AI 기능을 구현할 수 있다.

지금 가장 먼저 해볼 수 있는 것은 간단하다. Chrome Canary를 설치하고, 플래그를 활성화한 뒤, 개발자 콘솔에서 window.ai 객체를 확인해 보는 것이다. 그리고 간단한 코드 한 줄로 브라우저 안에서 Gemini Nano가 작동하기 시작하는 것을 직접 체험해 볼 수 있다.

향후 Chrome 138+에서 오리진 트라이얼을 통한 더 광범위한 지원, 그리고 다중 탭 동시 쿼리 기능 등이 예정되어 있다. 지금부터 익혀두면, 이러한 업데이트가 출시될 때 가장 빠르게 활용할 수 있을 것이다.