프롬프트 API

2 weeks ago 18

Chrome에 내장된 Gemini Nano에 자연어 요청을 보내는 웹 API로, 질의응답·분류·콘텐츠 필터링·일정 추출·연락처 추출 같은 작업에 활용 가능함
사용 전에는 별도 모델 다운로드가 필요하며, 지원 OS·저장공간·GPU 또는 CPU 메모리 같은 실행 조건을 충족해야 동작함
세션은 LanguageModel.availability()로 사용 가능 여부를 확인한 뒤 create()로 준비하며, initialPrompts·append()·clone()으로 컨텍스트를 이어가거나 분기할 수 있음
입력은 text, image, audio를 받을 수 있고 출력은 현재 text만 지원하며, prompt()는 완성 응답을, promptStreaming()은 스트리밍 응답을 반환함
responseConstraint 기반 구조화 출력, 컨텍스트 창 관리, 권한 정책, 멀티모달 처리까지 포함해 브라우저 안에서 온디바이스 AI를 다루는 실행 모델을 제공함

개요

Chrome 내장 Gemini Nano에 자연어 요청을 보내는 API로 동작하며, 웹페이지 기반 질의응답·기사 분류·콘텐츠 필터링·일정 추출·연락처 추출 같은 활용이 가능함
모델은 Chrome에 API가 내장되어 있어도 별도 다운로드가 필요하며, 최초 사용 전에는 Google의 Generative AI Prohibited Uses Policy를 확인해야 함
생성형 AI 사용 전에는 People + AI Guidebook 참고가 권장됨
TypeScript 타이핑은 @types/dom-chromium-ai 패키지로 받을 수 있음
Chrome Extensions 개발자는 만료된 origin trial 권한인 aiLanguageModelOriginTrial 제거가 필요함

하드웨어 및 실행 조건

Prompt API·Summarizer API·Writer API·Rewriter API·Proofreader API는 Chrome에서 특정 조건을 충족해야 동작함
지원 운영체제는 Windows 10/11, macOS 13+, Linux, ChromeOS이며, ChromeOS는 Chromebook Plus 기기에서 Platform 16389.0.0 이상일 때 지원됨
Chrome for Android, iOS, non-Chromebook Plus 기기의 ChromeOS는 Gemini Nano 기반 API를 아직 지원하지 않음
저장공간은 Chrome 프로필이 있는 볼륨에 최소 22GB 여유 공간이 필요함
모델 실행은 GPU 또는 CPU로 가능함
- GPU는 4GB 초과 VRAM이 필요함
- CPU는 16GB 이상 RAM과 4개 이상 CPU 코어가 필요함
- 오디오 입력을 사용하는 Prompt API는 GPU가 필요함
네트워크는 초기 모델 다운로드 시에만 무제한 또는 종량제 아님 연결이 필요함
- 이후 모델 사용에는 네트워크 연결이 필요하지 않음
- 모델 사용 시 데이터는 Google이나 제3자에게 전송되지 않음
모델 크기는 브라우저 업데이트에 따라 달라질 수 있으며, 현재 크기는 chrome://on-device-internals에서 확인 가능함
다운로드 후 여유 저장공간이 10GB 미만으로 떨어지면 모델이 기기에서 제거되며, 다시 조건을 충족하면 재다운로드됨

사용 시작과 모델 준비

사용 가능 여부는 LanguageModel.availability()로 확인 가능함
availability()에는 이후 prompt() 또는 promptStreaming()에 넣을 것과 같은 옵션을 전달해야 함
- 일부 모델은 특정 모달리티나 언어를 지원하지 않을 수 있어 옵션 일치가 중요함
모델 다운로드와 세션 생성은 user activation 확인 뒤 create()로 시작함
다운로드 중이라면 진행률 이벤트를 받아 사용자에게 다운로드 상황을 알려야 함
localhost에서는 Chrome 플래그를 켜면 내장 AI API를 사용할 수 있음
- chrome://flags/#optimization-guide-on-device-model
- chrome://flags/#prompt-api-for-gemini-nano-multimodal-input
- 이후 Relaunch 또는 Chrome 재시작이 필요함
- 오류가 나면 localhost 문제 해결 참고가 가능함

세션 생성과 기본 설정

세션은 LanguageModel.create()로 생성됨
Chrome Extensions용 Prompt API에서는 세션별로 topK와 temperature를 옵션으로 조정할 수 있음
- 기본값과 최대값은 LanguageModel.params()로 확인 가능함
- 이 기능은 Chrome Extensions 또는 sampling parameters origin trial 사용 시에만 적용됨
params()는 defaultTopK, maxTopK, defaultTemperature, maxTemperature를 반환함
새 세션 초기화 시 topK와 temperature는 둘 다 지정하거나 둘 다 생략해야 함
create()는 signal 필드로 AbortSignal을 받아 세션을 중단할 수 있음

컨텍스트와 프롬프트 구성

initialPrompts로 이전 대화 맥락을 넣어 브라우저 재시작 뒤 저장된 세션을 이어갈 수 있음
프롬프트 배열에는 system, user, assistant 역할을 함께 넣을 수 있음
마지막 assistant 메시지에 prefix: true를 주면 응답 일부를 미리 채워 넣어 특정 출력 형식을 유도할 수 있음
- 예시로 TOML 코드블록 시작 문자열을 미리 넣어 출력 형식을 고정함
세션 생성 뒤에는 append()로 추가 컨텍스트를 미리 넣을 수 있음
- initialPrompts와 달리 세션 생성 후에도 컨텍스트를 누적할 수 있음
- append()는 프롬프트가 검증·처리·추가된 뒤 이행됨
- 추가할 수 없는 프롬프트면 promise가 거부됨

입력·출력 모달리티와 다국어

세션 생성 시 expectedInputs와 expectedOutputs로 예상 입력/출력 형식과 언어를 설정할 수 있음
expectedInputs의 type은 text, image, audio를 지원함
expectedOutputs의 type은 현재 text만 허용됨
언어는 languages 배열로 설정하며, Prompt API는 "en", "ja", "es"를 받음
- 추가 언어 지원은 개발 중임
- 입력 쪽에는 system prompt 언어와 하나 이상의 user prompt 언어를 넣을 수 있음
- 출력 쪽에는 하나 이상의 출력 언어를 넣을 수 있음
지원하지 않는 입력이나 출력을 만나면 "NotSupportedError" DOMException이 발생할 수 있음

멀티모달 입력

오디오 전사나 이미지 설명·캡션·alt text 생성 같은 작업에 활용 가능함
관련 데모
- Mediarecorder Audio Prompt
- Canvas Image Prompt
오디오 입력은 다음 타입을 지원함
시각 입력은 다음 타입을 지원함
예시에서는 이미지 Blob과 HTMLCanvasElement를 함께 넣어 두 시각 자료를 비교하게 하고, 이어서 AudioBuffer로 사용자의 음성 응답을 받게 만듦

구조화 출력과 제약

prompt() 또는 promptStreaming()의 responseConstraint에 JSON Schema를 넣어 구조화 출력을 사용할 수 있음
관련 기능은 structured output에서 확인 가능함
예시에서는 boolean 스키마를 넣어 게시물이 도예 관련인지 true 또는 false로만 답하게 만듦
구현 시 JSON Schema나 정규식을 메시지 일부로 함께 넣을 수도 있으며, 이 경우 context window의 일부를 사용하게 됨
session.measureContextUsage()에 responseConstraint 옵션을 전달하면 제약 조건이 컨텍스트를 얼마나 쓰는지 측정 가능함
omitResponseConstraintInput 옵션을 쓰면 이 동작을 피할 수 있음
- 이 경우 프롬프트 안에 원하는 출력 형식에 대한 안내를 함께 넣는 편이 권장됨

프롬프트 실행 방식

짧은 응답이 예상되면 prompt()를 사용해 완성된 결과를 한 번에 받을 수 있음
긴 응답이 예상되면 promptStreaming()을 사용해 부분 결과를 스트리밍으로 받을 수 있음
promptStreaming()은 ReadableStream을 반환함
prompt()와 promptStreaming() 모두 두 번째 인자로 signal을 받아 실행 중 프롬프트를 중단할 수 있음

세션 관리

각 세션은 대화의 컨텍스트를 유지하며, 이전 상호작용이 이후 응답에 반영됨
각 세션에는 처리 가능한 최대 토큰 수가 있으며, session.contextUsage와 session.contextWindow로 현재 사용량과 한도를 확인할 수 있음
새 프롬프트로 컨텍스트 창이 넘치면, 시스템 프롬프트를 제외한 대화 앞부분이 질문-응답 쌍 단위로 제거되어 공간을 확보함
이런 상황은 세션의 contextoverflow 이벤트로 감지할 수 있음
대화 기록을 지워도 충분한 토큰을 확보할 수 없으면 prompt() 또는 promptStreaming()이 QuotaExceededError로 실패하며, 아무것도 제거되지 않음
- requested: 입력이 차지한 토큰 수
- contextWindow: 사용 가능했던 토큰 수
자세한 내용은 session management 참고가 가능함

세션 복제와 종료

clone()으로 기존 세션을 복사해 대화 분기를 만들 수 있음
복제된 세션은 기존 컨텍스트와 초기 프롬프트를 유지함
clone()도 signal 필드로 AbortSignal을 받을 수 있음
더 이상 세션이 필요 없으면 destroy()로 리소스를 해제할 수 있음
세션이 파괴되면 더 이상 사용할 수 없고, 진행 중인 실행도 중단됨
세션 생성에는 시간이 걸릴 수 있어 자주 프롬프트를 보낼 예정이면 세션을 유지하는 편이 나을 수 있음

권한 정책과 실행 환경 제약

기본적으로 Prompt API는 최상위 window와 같은 origin의 iframe에서만 사용 가능함
cross-origin iframe에는 Permission Policy의 allow="language-model" 속성으로 접근 권한을 위임할 수 있음
현재 Prompt API는 Web Workers에서 사용할 수 없음
- 각 worker마다 permissions policy 상태를 확인할 책임 문서를 정하는 일이 복잡하기 때문임