Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

프롬프트 API의 실험용 폴리필

Thomas Steiner

게시일: 2026년 5월 14일

Chrome의 Prompt API를 사용하면 고급 브라우저 API를 사용하여 window.LanguageModel에서 LLM과 상호작용할 수 있습니다. 하지만 아직 지원이 제한적이며 구현은 복잡한 프로세스입니다.

브라우저	지원되는 OS	지원되지 않는 OS	위치
Chrome	Windows, macOS, Linux, ChromeOS (Chromebook Plus)	Android, iOS	✅ 지원됨
Edge	Windows, macOS	Android, iOS	✅ 지원됨
Safari	—	—	📋 위치 결정됨
Firefox	—	—	📋 위치 결정됨

동시에 사전 체험판 프로그램의 개발자들은 Prompt API에 대한 열정을 공유했습니다. API의 가용성은 예측 가능한 미래에 호환성 문제를 야기합니다.

솔루션

따라서 구성 가능한 클라우드 백엔드 제공업체와 Transformers.js 형식의 로컬 백엔드 제공업체 모두에서 Prompt API를 정확하게 구현하는 실험용 사양 준수 Prompt API 폴리필 (GitHub에서 소스 코드 확인)을 출시합니다.

폴리필 사용

폴리필을 사용하려면 다음을 실행합니다.

npm에서 폴리필을 다운로드합니다.
```
npm install prompt-api-polyfill
```
클라우드 백엔드 프로바이더 또는 로컬 백엔드 프로바이더를 사용할지 선택합니다.
- 클라우드 백엔드 제공업체: 사용자 데이터는 원격 처리를 위해 클라우드로 전송되지만 로컬 모델이 제공될 때까지 기다릴 필요가 없습니다. 클라우드 제공업체의 가격 책정 정보에 따라 발생하는 비용은 사용자가 부담합니다.
- 로컬 백엔드 제공업체: 사용자 데이터는 브라우저에 유지되고 로컬에서 처리되지만 실제 Prompt API와 달리 여러 출처에서 공유할 수 없는 모델을 다운로드해야 합니다. 로컬 처리에는 비용이 들지 않습니다.

클라우드 백엔드

클라우드 백엔드 중에서 선택하고 백엔드 제공업체의 API 키 (및 추가 사용자 인증 정보)를 가져옵니다.

API 키가 있으면 구성 파일 .env.json에 세부정보를 입력합니다. modelName을 지정하지 않으면 폴리필은 각 백엔드의 기본 모델을 사용하지만 지정하면 각 백엔드의 지원되는 모델 중 하나를 선택할 수 있습니다.

{
  "apiKey": "y0ur-Api-k3Y",
  "modelName": "model-name"
}

로컬 백엔드

Transformers.js를 기반으로 하는 로컬 백엔드 제공업체를 사용하기로 결정한 경우 더미 API 키만 있으면 됩니다. 하지만 Transformers.js에서 사용할 기기를 구성할 수 있습니다. 최대 성능을 위해 "webgpu"를 선택하고 최대 호환성을 위해 "wasm"를 선택합니다. 선택적으로 기본 설정을 변경할 수 있습니다. 호환되는 모델의 Hugging Face 카탈로그에서 다른 모델을 선택합니다. 일부 모델의 경우 dtype 매개변수를 사용하여 다양한 양자화 중에서 선택할 수 있습니다.

{
  "apiKey": "dummy",
  "device": "webgpu",
  "dtype": "q4f16",
  "modelName": "onnx-community/gemma-3-1b-it-ONNX-GQA"
};

폴리필 구성

구성 파일이 준비되면 이제 앱에서 폴리필을 사용할 수 있습니다.

구성 파일을 가져와서 적절한 이름의 전역 변수에 할당합니다. 여기서 $BACKEND는 선택한 백엔드입니다. window.$BACKEND_CONFIG
기본 브라우저에서 폴리필을 지원하지 않는 경우에만 동적 가져오기를 사용하여 폴리필을 로드합니다.
Prompt API 함수를 호출합니다.

import config from './.env.json' with { type: 'json' };

// Set $BACKEND_CONFIG to select a backend
window.$BACKEND_CONFIG = config;

if (!('LanguageModel' in window)) {
  await import('prompt-api-polyfill');
}

const session = await LanguageModel.create({
  expectedInputs: [{type: 'text', languages: ['en']}],
  expectedOutputs: [{type: 'text', languages: ['en']}],
});
await session.prompt('Tell me a joke!');

폴리필은 구조화된 출력을 지원하고 (Transformers.js 백엔드 제외) 멀티모달 입력을 처리하며 (오디오와 이미지를 함께 지원하지 않고 별도로만 지원하는 OpenAI 백엔드 제외) 전체 웹 플랫폼 테스트 모음으로 테스트됩니다.LanguageModel

배경 및 자세한 사용 정보와 소스 코드는 GitHub 저장소의 README 파일을 참고하세요.

브라우저 Prompt API와의 차이점

폴리필이 클라우드 모델로 지원되는 경우 클라이언트 측 실행의 일부 이점이 더 이상 적용되지 않습니다. 즉, 백엔드 제공업체의 개인정보처리방침은 여전히 적용되지만 더 이상 민감한 정보의 로컬 처리를 보장할 수 없습니다. 또한 사용자가 오프라인 상태일 때 앱에서 더 이상 AI를 사용할 수 없습니다. 온라인 상태인지 오프라인 상태인지 확인하려면 상응하는 이벤트를 수신 대기하면 됩니다.

window.addEventListener("offline", (e) => {
  console.log("offline");
});

window.addEventListener("online", (e) => {
  console.log("online");
});

AI 추론이 클라우드의 모델에 대해 실행되는 경우 다운로드할 로컬 모델이 없습니다. 폴리필은 downloadprogress 이벤트를 가장하므로 앱에는 기본 모델이 이미 다운로드된 것처럼 표시됩니다. 즉, 사양에 필요한 대로 loaded 값이 0인 이벤트와 1인 이벤트가 두 개 있습니다.

클라우드 기반 추론은 기기 내 추론과 달리 선택한 백엔드 제공업체에서 API를 호출할 때 비용이 발생할 수 있습니다. Gemini API와 같은 가격 책정 정보를 확인하세요. 토큰당 비용을 알고 있는 경우 Prompt API의 contextUsage 정보를 사용하여 비용을 계산할 수 있습니다.

const COST_PER_TOKEN = 123;
const COST_LIMIT = 456;

let costSoFar = 0;

const session = await LanguageModel.create(options);

/…/

if (costSoFar < COST_LIMIT) {
  await session.prompt('Tell me a joke.');
  costSoFar = session.contextUsage * COST_PER_TOKEN;
} else {
  // Show premium AI plan promo.
}

모바일 또는 웹 앱에서 직접 클라우드 API (예: 생성형 AI 모델에 대한 액세스를 허용하는 API)를 호출하면 API 키가 승인되지 않은 클라이언트에 의해 악용될 수 있습니다. 이러한 API를 보호하려면 Firebase AI Logic Hybrid SDK를 사용하는 경우 Firebase 앱 체크를 사용하여 모든 수신 API 호출이 실제 앱에서 이루어지는지 확인해야 합니다. Google과 같은 일부 클라우드 제공업체의 경우 엄격한 출처 검사를 적용하여 허용된 웹사이트만 API를 사용할 수 있도록 할 수도 있습니다.

예를 들어 세션의 contextWindow와 관련된 Prompt API의 제한사항이 아니라 백엔드 제공업체의 제한사항이 적용됩니다. contextWindow의 경우 이러한 제한사항은 일반적으로 기기 내보다 훨씬 높으며 클라우드에서 더 많은 양의 데이터를 처리할 수 있으므로 차이점을 알고 있어야 하지만 실제로 이로 인해 문제가 발생하지 않을 수 있습니다.

자체 백엔드 만들기

자체 백엔드 프로바이더를 추가하려면 다음 단계를 따르세요.

기본 백엔드 클래스 확장

backends/ 디렉터리에 새 파일(예: backends/custom-backend.js)을 만듭니다. PolyfillBackend 클래스를 확장하고 예상 인터페이스를 충족하는 핵심 메서드를 구현해야 합니다.

import PolyfillBackend from './base.js';
import { DEFAULT_MODELS } from './defaults.js';

export default class CustomBackend extends PolyfillBackend {
  constructor(config) {
    // config typically comes from a window global (e.g., window.CUSTOM_CONFIG)
    super(config.modelName || DEFAULT_MODELS.custom.modelName);
  }

  // Check if the backend is configured (e.g., API key is present), if given
  // combinations of modelName and options are supported, or, for local model,
  // if the model is available.
  static availability(options) {
    return window.CUSTOM_CONFIG?.apiKey ? 'available' : 'unavailable';
  }

  // Initialize the underlying SDK or API client. With local models, use
  // monitorTarget to report model download progress to the polyfill.
  createSession(options, sessionParams, monitorTarget) {
    // Return the initialized session or client instance
  }

  // Non-streaming prompt execution
  async generateContent(contents) {
    // contents: Array of { role: 'user'|'model', parts: [{ text: string }] }
    // Return: { text: string, usage: number }
  }

  // Streaming prompt execution
  async generateContentStream(contents) {
    // Return: AsyncIterable yielding chunks
  }

  // Token counting for quota/usage tracking
  async countTokens(contents) {
    // Return: total token count (number)
  }
}

백엔드 등록

폴리필은 전역 구성을 기반으로 '첫 번째 일치 우선순위' 전략을 사용합니다. 정적 #backends 배열에 추가하여 prompt-api-polyfill.js 파일에 백엔드를 등록해야 합니다.

// prompt-api-polyfill.js
static #backends = [
  // ... existing backends
  {
    config: 'CUSTOM_CONFIG', // The global object to look for on `window`
    path: './backends/custom-backend.js',
  },
];

기본 모델 설정

backends/defaults.js에서 대체 모델 ID를 정의합니다. 이는 사용자가 특정 modelName을 지정하지 않고 세션을 초기화할 때 사용됩니다.

// backends/defaults.js
export const DEFAULT_MODELS = {
  // ...
  custom: 'custom-model-pro-v1',
};

로컬 개발 및 테스트 사용 설정

이 프로젝트는 검색 스크립트 (scripts/list-backends.js)를 사용하여 테스트 매트릭스를 생성합니다. 테스트 실행기에 새 백엔드를 포함하려면 루트 디렉터리에 .env-[name].json 파일 (예: .env-custom.json)을 만듭니다.

{
  "apiKey": "your-api-key-here",
  "modelName": "custom-model-pro-v1"
}

웹 플랫폼 테스트 (WPT)로 확인

마지막 단계는 규정 준수를 보장하는 것입니다. 폴리필은 사양 기반이므로 모든 새 백엔드는 공식 (또는 잠정) 웹 플랫폼 테스트를 통과해야 합니다.

npm run test:wpt

이 확인 단계를 통해 백엔드가 Prompt API 사양에서 예상하는 대로 AbortSignal, 시스템 프롬프트, 기록 형식 지정과 같은 작업을 처리할 수 있습니다.

결론

폴리필을 사용하면 모든 플랫폼과 기기에서 Prompt API를 사용할 수 있습니다. Prompt API의 잘 정의된 API에 대해 코딩하면 클라우드 제공업체로부터 더 독립적이고 플랫폼에 최대한 가까이 유지할 수 있습니다.

Prompt API를 지원하는 지원되는 기기에서는 폴리필이 로드되지도 않으므로 사용자가 실행하지 않을 코드를 다운로드하지 않아도 됩니다. 의견이 있거나 버그가 발생하면 GitHub에서 문제를 엽니다. 즐겁게 프롬프트를 작성해 보시기를 바랍니다.