Prompt API

Thomas Steiner

Alexandra Klepper

게시일: 2025년 5월 20일, 최종 업데이트: 2025년 9월 21일

설명하듯이	웹	확장 프로그램	Chrome 상태	의도
GitHub	Origin 체험판	Chrome 138	View	실험 의도
GitHub	샘플링 매개변수 Origin 체험판	Chrome 148	View	실험 의도

Prompt API를 사용하면 브라우저에서 Gemini Nano에 자연어 요청을 보낼 수 있습니다.

Prompt API를 사용하는 방법은 다양합니다. 예를 들어 다음을 빌드할 수 있습니다.

• AI 기반 검색: 웹페이지의 콘텐츠를 기반으로 질문에 답변합니다.
• 맞춤설정된 뉴스 피드: 카테고리로 기사를 동적으로 분류하고 사용자가 콘텐츠를 필터링할 수 있는 피드를 빌드합니다.
• 맞춤 콘텐츠 필터. 뉴스 기사를 분석하고 사용자 정의 주제를 기반으로 콘텐츠를 자동으로 흐리게 처리하거나 숨깁니다.
• 캘린더 일정 만들기. 사용자가 몇 단계만으로 캘린더 항목을 만들 수 있도록 웹페이지에서 이벤트 세부정보를 자동으로 추출하는 Chrome 확장 프로그램을 개발합니다.
• 원활한 연락처 추출. 웹사이트에서 연락처 정보를 추출하는 확장 프로그램을 빌드하여 사용자가 비즈니스에 더 쉽게 연락하거나 연락처 목록에 세부정보를 추가할 수 있도록 합니다.

이러한 가능성은 몇 가지에 불과하며, 개발자가 어떤 것을 만들지 기대됩니다.

중요: Gemini Nano는 생성형 AI 모델입니다. Gemini Nano를 사용하는 API로 빌드하기 전에 AI를 사용한 설계를 위한 권장사항, 방법, 예시를 알아보려면 People + AI 가이드북을 검토해야 합니다.

하드웨어 요구사항 검토

Chrome에서 이러한 API를 사용하여 기능을 운영하는 개발자와 사용자에게는 다음과 같은 요구사항이 있습니다. 브라우저마다 운영 요구사항이 다를 수 있습니다.

언어 감지기 및 번역기 API는 데스크톱의 Chrome에서 작동합니다. 이러한 API는 휴대기기에서 작동하지 않습니다.

Prompt API, Summarizer API, Writer API, Rewriter API, Proofreader API는 다음 조건을 충족하는 경우 Chrome에서 작동합니다.

• 운영체제: Windows 10 또는 11, macOS 13+ (Ventura 이상), Linux 또는 Chromebook Plus 기기의 ChromeOS (플랫폼 16389.0.0 이상) Gemini Nano를 사용하는 API는 아직 Chromebook Plus 기기가 아닌 기기의 Android용 Chrome, iOS, ChromeOS를 지원하지 않습니다.
• 저장용량: Chrome 프로필이 포함된 볼륨에 최소 22GB의 여유 공간
  기본 제공 모델은 훨씬 작아야 합니다. 정확한 크기는 업데이트에 따라 약간 다를 수 있습니다.
• GPU 또는 CPU: 기본 제공 모델은 GPU 또는 CPU로 실행할 수 있습니다.
  • GPU: VRAM이 4GB보다 엄격하게 많음
  • CPU: RAM 16GB 이상, CPU 코어 4개 이상
  • 참고: 오디오 입력이 있는 Prompt API에는 GPU가 필요합니다.
• 네트워크: 무제한 데이터 또는 데이터 전송량 제한이 없는 연결
  주요 용어: 데이터 전송량 제한이 있는 연결은 데이터가 제한된 인터넷 연결입니다. Wi-Fi 및 이더넷 연결은 기본적으로 데이터 전송량 제한이 없는 반면, 셀룰러 연결은 데이터 전송량 제한이 있는 경우가 많습니다.
  참고: 네트워크 요구사항은 모델의 초기 다운로드에만 적용됩니다. 모델을 이후에 사용하는 데는 네트워크 연결이 필요하지 않습니다. 모델을 사용할 때 Google 또는 서드 파티로 데이터가 전송되지 않습니다.

Gemini Nano의 정확한 크기는 브라우저에서 모델을 업데이트할 때 다를 수 있습니다. 현재 크기를 확인하려면 chrome://on-device-internals를 방문하세요.

참고: 다운로드 후 사용 가능한 저장용량이 10GB 미만으로 떨어지면 모델이 기기에서 삭제됩니다. 요구사항이 충족되면 모델이 다시 다운로드됩니다.

Prompt API 사용

Prompt API는 Chrome에서 Gemini Nano 모델을 사용합니다. API는 Chrome에 기본 제공되지만, 모델은 Origin에서 API를 처음 사용할 때 별도로 다운로드됩니다. 이 API를 사용하기 전에 Google의 생성형 AI에 관한 금지된 사용 정책을 확인하세요.

도움말: @types/dom-chromium-ai npm 패키지를 사용하여 Prompt API 및 기타 기본 제공 AI API의 TypeScript 유형을 가져옵니다.

참고: 확장 프로그램 개발자는 만료된 Origin 체험판 권한( "permissions": ["aiLanguageModelOriginTrial"])을 삭제해야 합니다.

모델을 사용할 준비가 되었는지 확인하려면 LanguageModel.availability()를 호출합니다.

const availability = await LanguageModel.availability({
  // The same options in `prompt()` or `promptStreaming()`
});

주의: `prompt()` 또는 `promptStreaming()`에서 사용하는 것과 동일한 옵션을 항상 `availability()` 함수에 전달하세요.availability()prompt()promptStreaming() 일부 모델은 특정 형식 또는 언어를 지원하지 않을 수 있으므로 이 작업은 매우 중요합니다.

다운로드를 트리거하고 언어 모델을 인스턴스화하려면 사용자 활성화를 확인합니다. 그런 다음 create() 함수를 호출합니다.

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

availability()에 대한 응답이 downloading인 경우 다운로드 진행률을 수신 대기하고 사용자에게 알립니다. 다운로드에 시간이 걸릴 수 있습니다.

localhost에서 사용

모든 기본 제공 AI API는 Chrome의 localhost에서 사용할 수 있습니다. 다음 플래그를 사용 설정됨으로 설정합니다.

• chrome://flags/#optimization-guide-on-device-model
• chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

그런 다음 다시 시작 을 클릭하거나 Chrome을 다시 시작합니다. 오류가 발생하면 localhost 문제 해결을 참고하세요.

모델 매개변수

**주의:** 이 섹션의 매개변수는 Chrome 확장 프로그램용 Prompt API에만 적용되거나 Origin 체험판이 사용 설정된 Prompt API를 사용하는 경우에만 적용됩니다.

params() 함수는 언어 모델의 매개변수를 알려줍니다. 객체에는 다음 필드가 포함됩니다.

• defaultTopK: 기본 상위 K 값입니다.
• maxTopK: 최대 상위 K 값입니다.
• defaultTemperature: 기본 온도입니다.
• maxTemperature: 최대 온도입니다.

// Only available when using the Prompt API for Chrome Extensions.
await LanguageModel.params();
// {defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2}

세션 만들기

Prompt API를 실행할 수 있게 되면 create() 함수를 사용하여 세션을 만듭니다.

const session = await LanguageModel.create();

Chrome 확장 프로그램용 Prompt API로 세션 만들기

Chrome 확장 프로그램용 Prompt API를 사용하는 경우 선택적 옵션 객체를 사용하여 각 세션을 topK 및 temperature로 맞춤설정할 수 있습니다. 이러한 매개변수의 기본값은 LanguageModel.params()에서 반환됩니다.

// Only available when using the Prompt API for Chrome Extensions.
const params = await LanguageModel.params();
// Initializing a new session must either specify both `topK` and
// `temperature` or neither of them.
// Only available when using the Prompt API for Chrome Extensions.
const slightlyHighTemperatureSession = await LanguageModel.create({
  temperature: Math.max(params.defaultTemperature * 1.2, 2.0),
  topK: params.defaultTopK,
});

create() 함수의 선택적 옵션 객체는 세션을 삭제하기 위해 AbortSignal을 전달할 수 있는 signal 필드도 사용합니다.

const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const session = await LanguageModel.create({
  signal: controller.signal,
});

초기 프롬프트로 컨텍스트 추가

초기 프롬프트를 사용하면 언어 모델에 이전 상호작용에 관한 컨텍스트를 제공할 수 있습니다. 예를 들어 사용자가 브라우저를 다시 시작한 후 저장된 세션을 재개할 수 있도록 합니다.

const session = await LanguageModel.create({
  initialPrompts: [
    { role: 'system', content: 'You are a helpful and friendly assistant.' },
    { role: 'user', content: 'What is the capital of Italy?' },
    { role: 'assistant', content: 'The capital of Italy is Rome.' },
    { role: 'user', content: 'What language is spoken there?' },
    {
      role: 'assistant',
      content: 'The official language of Italy is Italian. [...]',
    },
  ],
});

접두사로 응답 제한

이전 역할 외에 "assistant" 역할을 추가하여 모델의 이전 응답을 자세히 설명할 수 있습니다. 예를 들면 다음과 같습니다.

const followup = await session.prompt([
  {
    role: "user",
    content: "I'm nervous about my presentation tomorrow"
  },
  {
    role: "assistant",
    content: "Presentations are tough!"
  }
]);

경우에 따라 새 응답을 요청하는 대신 "assistant" 역할 응답 메시지의 일부를 미리 입력할 수 있습니다. 이는 언어 모델이 특정 응답 형식을 사용하도록 안내하는 데 유용할 수 있습니다. 이렇게 하려면 후행 "assistant" 역할 메시지에 prefix: true를 추가합니다. 예를 들면 다음과 같습니다.

const characterSheet = await session.prompt([
  {
    role: 'user',
    content: 'Create a TOML character sheet for a gnome barbarian',
  },
  {
    role: 'assistant',
    content: '```toml\n',
    prefix: true,
  },
]);

예상 입력 및 출력 추가

Prompt API에는 멀티모달 기능이 있으며 여러 언어를 지원합니다. 세션을 만들 때 expectedInputs 및 expectedOutputs 형식과 언어를 설정합니다.

• type: 예상되는 형식입니다.
  • expectedInputs의 경우 text, image 또는 audio일 수 있습니다.
  • expectedOutputs의 경우 Prompt API는 text만 허용합니다.
• languages: 예상되는 언어를 설정하는 배열입니다. Prompt API는 "en", "ja", "es"를 허용합니다. 추가 언어 지원은 개발 중입니다.
  • expectedInputs의 경우 시스템 프롬프트 언어와 하나 이상의 예상 사용자 프롬프트 언어를 설정합니다.
  • 하나 이상의 expectedOutputs 언어를 설정합니다.

const session = await LanguageModel.create({
  expectedInputs: [
    { type: "text", languages: ["en" /* system prompt */, "ja" /* user prompt */] }
  ],
  expectedOutputs: [
    { type: "text", languages: ["ja"] }
  ]
});

모델에서 지원되지 않는 입력 또는 출력이 발생하면 "NotSupportedError" DOMException이 수신될 수 있습니다.

멀티모달 기능

이러한 기능을 사용하면 다음을 할 수 있습니다.

• 사용자가 채팅 애플리케이션에서 전송된 오디오 메시지를 트랜스크립션할 수 있도록 허용합니다.
• 캡션 또는 대체 텍스트에 사용할 웹사이트에 업로드된 이미지를 설명합니다.

오디오 입력으로 Prompt API를 사용하는 Mediarecorder 오디오 프롬프트 데모와 이미지 입력으로 Prompt API를 사용하는 Canvas 이미지 프롬프트 데모 를 살펴보세요.

Prompt API는 다음 입력 유형을 지원합니다.

• 오디오:
  • AudioBuffer
  • ArrayBufferView
  • ArrayBuffer
  • Blob
• 시각적 요소:
  • HTMLImageElement
  • SVGImageElement
  • HTMLVideoElement (현재 동영상 위치의 동영상 프레임을 사용함)
  • HTMLCanvasElement
  • ImageBitmap
  • OffscreenCanvas
  • VideoFrame
  • Blob
  • ImageData

이 스니펫은 먼저 두 개의 시각적 요소 (이미지 Blob 하나와 HTMLCanvasElement 하나)를 처리하고 AI가 이를 비교하는 멀티모달 세션을 보여줍니다. 두 번째로 사용자가 오디오 녹음 (AudioBuffer로)으로 응답할 수 있도록 합니다.

const session = await LanguageModel.create({
  expectedInputs: [
    { type: "text", languages: ["en"] },
    { type: "audio" },
    { type: "image" },
  ],
  expectedOutputs: [{ type: "text", languages: ["en"] }],
});

const referenceImage = await (await fetch("reference-image.jpeg")).blob();
const userDrawnImage = document.querySelector("canvas");

const response1 = await session.prompt([
  {
    role: "user",
    content: [
      {
        type: "text",
        value:
          "Give a helpful artistic critique of how well the second image matches the first:",
      },
      { type: "image", value: referenceImage },
      { type: "image", value: userDrawnImage },
    ],
  },
]);
console.log(response1);

const audioBuffer = await captureMicrophoneInput({ seconds: 10 });

const response2 = await session.prompt([
  {
    role: "user",
    content: [
      { type: "text", value: "My response to your critique:" },
      { type: "audio", value: audioBuffer },
    ],
  },
]);
console.log(response2);

메시지 추가

특히 멀티모달 입력으로 프롬프트를 작성할 때는 추론에 시간이 걸릴 수 있습니다. 모델이 처리를 시작할 수 있도록 미리 결정된 프롬프트를 미리 보내 세션을 채우는 것이 유용할 수 있습니다.

initialPrompts는 세션을 만들 때 유용하지만, 세션이 생성된 후 추가 컨텍스트 프롬프트를 제공하기 위해 prompt() 또는 promptStreaming() 메서드 외에 append() 메서드를 사용할 수 있습니다.

예를 들면 다음과 같습니다.

const session = await LanguageModel.create({
  initialPrompts: [
    {
      role: 'system',
      content:
        'You are a skilled analyst who correlates patterns across multiple images.',
    },
  ],
  expectedInputs: [{ type: 'image' }],
});

fileUpload.onchange = async () => {
  await session.append([
    {
      role: 'user',
      content: [
        {
          type: 'text',
          value: `Here's one image. Notes: ${fileNotesInput.value}`,
        },
        { type: 'image', value: fileUpload.files[0] },
      ],
    },
  ]);
};

analyzeButton.onclick = async (e) => {
  analysisResult.textContent = await session.prompt(userQuestionInput.value);
};

append()에서 반환된 Promise는 프롬프트가 검증되고 처리되어 세션에 추가되면 이행됩니다. 프롬프트를 추가할 수 없는 경우 Promise가 거부됩니다.

JSON 스키마 전달

responseConstraint 필드를 prompt() 또는 promptStreaming() 메서드에 추가하여 JSON 스키마를 값으로 전달합니다. 그런 다음 구조화된 출력을 Prompt API와 함께 사용할 수 있습니다.

다음 예에서 JSON 스키마는 모델이 주어진 메시지가 도자기에 관한 것인지 분류하기 위해 true 또는 false로 응답하도록 합니다.

const session = await LanguageModel.create();

const schema = {
  "type": "boolean"
};

const post = "Mugs and ramen bowls, both a bit smaller than intended, but that
happens with reclaim. Glaze crawled the first time around, but pretty happy
with it after refiring.";

const result = await session.prompt(
  `Is this post about pottery?\n\n${post}`,
  {
    responseConstraint: schema,
  }
);
console.log(JSON.parse(result));
// true

구현에는 모델로 전송되는 메시지의 일부로 JSON 스키마 또는 정규 표현식이 포함될 수 있습니다. 이는 컨텍스트 윈도우의 일부를 사용합니다. 컨텍스트 윈도우. responseConstraint 옵션을 session.measureContextUsage()에 전달하여 사용할 컨텍스트 윈도우의 양을 측정할 수 있습니다.

omitResponseConstraintInput 옵션을 사용하면 이 동작을 방지할 수 있습니다. 이렇게 하는 경우 프롬프트에 몇 가지 안내를 포함하는 것이 좋습니다.

const result = await session.prompt(`
  Summarize this feedback into a rating between 0-5. Only output a JSON
  object { rating }, with a single property whose value is a number:
  The food was delicious, service was excellent, will recommend.
`, { responseConstraint: schema, omitResponseConstraintInput: true });

모델에 프롬프트 작성

prompt() 또는 promptStreaming() 함수를 사용하여 모델에 프롬프트를 작성할 수 있습니다.

요청 기반 출력

짧은 결과를 예상하는 경우 응답이 제공되면 반환하는 prompt() 함수를 사용할 수 있습니다.

// Start by checking if it's possible to create a session based on the
// availability of the model, and the characteristics of the device.
const available = await LanguageModel.availability({
  expectedInputs: [{type: 'text', languages: ['en']}],
  expectedOutputs: [{type: 'text', languages: ['en']}],
});

if (available !== 'unavailable') {
  const session = await LanguageModel.create();

  // Prompt the model and wait for the whole result to come back.
  const result = await session.prompt('Write me a poem!');
  console.log(result);
}

스트리밍된 출력

더 긴 응답을 예상하는 경우 모델에서 수신되는 대로 부분 결과를 표시할 수 있는 promptStreaming() 함수를 사용해야 합니다. promptStreaming() 함수는 ReadableStream을 반환합니다.

const available = await LanguageModel.availability({
  expectedInputs: [{type: 'text', languages: ['en']}],
  expectedOutputs: [{type: 'text', languages: ['en']}],
});
if (available !== 'unavailable') {
  const session = await LanguageModel.create();

  // Prompt the model and stream the result:
  const stream = session.promptStreaming('Write me an extra-long poem!');
  for await (const chunk of stream) {
    console.log(chunk);
  }
}

프롬프트 작성 중지

prompt()와 promptStreaming() 모두 프롬프트 실행을 중지할 수 있는 signal 필드가 있는 선택적 두 번째 매개변수를 허용합니다.

const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const result = await session.prompt('Write me a poem!', {
  signal: controller.signal,
});

세션 관리

각 세션은 대화의 컨텍스트를 추적합니다. 세션의 컨텍스트 윈도우가 가득 찰 때까지 이전 상호작용이 향후 상호작용에 고려됩니다.

각 세션에는 처리할 수 있는 최대 토큰 수가 있습니다. 다음으로 이 한도에 대한 진행 상황을 확인하세요.

console.log(`${session.contextUsage}/${session.contextWindow}`);

컨텍스트 윈도우가 오버플로되는 프롬프트를 보낼 수 있습니다. 이러한 경우 새 프롬프트를 처리할 수 있는 충분한 토큰이 제공될 때까지 언어 모델과의 대화의 초기 부분이 한 번에 하나의 프롬프트 및 응답 쌍으로 삭제됩니다. 예외는 시스템 프롬프트로, 삭제되지 않습니다.

이러한 오버플로는 세션에서 contextoverflow 이벤트를 수신 대기하여 감지할 수 있습니다.

session.addEventListener("contextoverflow", () => {
  console.log("We've gone past the context window, and some inputs will be dropped!");
});

새 프롬프트를 처리하기 위해 대화 기록에서 충분한 토큰을 삭제할 수 없는 경우 prompt() 또는 promptStreaming() 호출이 QuotaExceededError 예외로 실패하고 아무것도 삭제되지 않습니다. QuotaExceededError에는 다음과 같은 속성이 있습니다.

• requested: 입력이 구성되는 토큰 수
• contextWindow: 사용 가능한 토큰 수

세션 관리에 대해 자세히 알아보세요.

세션 클론

리소스를 보존하려면 clone() 함수를 사용하여 기존 세션을 복사할 수 있습니다. 이렇게 하면 컨텍스트와 초기 프롬프트가 보존되는 대화 포크가 생성됩니다.

clone() 함수는 클론된 세션을 삭제하기 위해 AbortSignal을 전달할 수 있는 signal 필드가 있는 선택적 옵션 객체를 사용합니다.

const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const clonedSession = await session.clone({
  signal: controller.signal,
});

세션 종료

세션이 더 이상 필요하지 않은 경우 destroy()를 호출하여 리소스를 확보합니다. 세션이 삭제되면 더 이상 사용할 수 없으며 진행 중인 실행이 중단됩니다. 세션을 만드는 데 시간이 걸릴 수 있으므로 모델에 자주 프롬프트를 작성하려는 경우 세션을 유지하는 것이 좋습니다.

await session.prompt(
  "You are a friendly, helpful assistant specialized in clothing choices."
);

session.destroy();

// The promise is rejected with an error explaining that
// the session is destroyed.
await session.prompt(
  "What should I wear today? It is sunny, and I am choosing between a t-shirt
  and a polo."
);

데모

Prompt API의 다양한 사용 사례를 살펴보기 위해 여러 데모를 빌드했습니다. 다음 데모는 웹 애플리케이션입니다.

• Prompt API 플레이그라운드
• Mediarecorder 오디오 프롬프트
• Canvas 이미지 프롬프트

Chrome 확장 프로그램에서 Prompt API를 테스트하려면 데모 확장 프로그램을 설치하세요. 확장 프로그램 소스 코드는 GitHub에서 제공됩니다.

실적 전략

웹용 Prompt API는 아직 개발 중입니다. 이 API를 빌드하는 동안 세션 관리에 관한 권장사항을 참고하여 최적의 성능을 얻으세요.

권한 정책, iframe, 웹 워커

기본적으로 Prompt API는 최상위 창과 동일한 Origin iframe에서만 사용할 수 있습니다. 권한 정책 allow="" 속성을 사용하여 API에 대한 액세스 권한을 교차 Origin iframe 에 위임할 수 있습니다.

<!--
  The hosting site at https://main.example.com can grant a cross-origin iframe
  at https://cross-origin.example.com/ access to the Prompt API by
  setting the `allow="language-model"` attribute.
-->
<iframe src="https://cross-origin.example.com/" allow="language-model"></iframe>

권한 정책 상태를 확인하기 위해 각 워커에 책임 있는 문서를 설정하는 것이 복잡하므로 Prompt API는 현재 웹 워커에서 사용할 수 없습니다.

참여 및 의견 공유

개발자의 의견은 이 API와 모든 기본 제공 AI API의 향후 버전을 빌드하고 구현하는 방식에 직접적인 영향을 미칠 수 있습니다.

• Chrome의 구현에 관한 의견은 버그 신고 또는 기능 요청을 제출하세요.
• 기존 문제를 댓글로 달거나 Prompt API GitHub 저장소에서 새 문제를 열어 API 형태에 관한 의견을 공유하세요.
• 조기 미리보기 프로그램에 참여하세요.