İstem API'si için deneysel bir polyfill

Thomas Steiner

Yayınlanma tarihi: 14 Mayıs 2026

Chrome'daki Prompt API ile window.LanguageModel üzerinde üst düzey bir tarayıcı API'si kullanarak bir LLM ile etkileşimde bulunabilirsiniz. Ancak bu özellik için destek sınırlıdır ve uygulama karmaşık bir süreçtir.

Aynı zamanda, erken önizleme programındaki geliştiriciler de Prompt API'ye olan ilgilerini dile getirdi. API'nin kullanılabilirliği, öngörülebilir gelecekte uyumluluk açısından sorun yaratacaktır.

Çözüm

Bu nedenle, yapılandırılabilir bulut arka uç sağlayıcılarının yanı sıra Transformers.js biçiminde bir yerel arka uç sağlayıcının üzerinde Prompt API'yi doğru şekilde uygulayan deneysel bir spec uyumlu Prompt API polyfill yayınlıyoruz (GitHub'daki kaynak koduna bakın).

Polyfill'i kullanma

Polyfill'i kullanmak için aşağıdakileri yapın:

1. npm'den polyfill'i indirin:

   npm install prompt-api-polyfill
   

2. Bulut arka uç sağlayıcısı mı yoksa yerel arka uç sağlayıcısı mı kullanmak istediğinizi seçin:

   • Bulut arka uç sağlayıcı: Kullanıcı verileri, uzaktan işleme için buluta gönderilir ancak yerel modelin kullanılabilir olmasını beklemeniz gerekmez. Bulut sağlayıcınızın fiyatlandırma bilgilerine göre oluşan tüm maliyetlerden siz sorumlusunuz.
   • Yerel arka uç sağlayıcı: Kullanıcı verileri tarayıcıda kalır ve yerel olarak işlenir ancak bir model indirmeniz gerekir. Bu model, gerçek İstem API'sinin aksine farklı kaynaklar arasında paylaşılamaz. Yerel işleme için herhangi bir ücret alınmaz.

Bulut arka ucu

Bulut arka uçlarından birini seçin ve arka uç sağlayıcınız için bir API anahtarı (ve ek kimlik bilgileri) alın.

API anahtarınızı aldıktan sonra ayrıntıları yapılandırma dosyanıza girin .env.json. modelName belirtmezseniz polyfill, her arka ucun varsayılan modelini kullanır. Belirtirseniz her arka ucun desteklenen modellerinden birini seçebilirsiniz.

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

Yerel arka uç

Transformers.js tabanlı yerel bir arka uç sağlayıcı kullanmaya karar verirseniz yalnızca sahte bir API anahtarına ihtiyacınız olur. Ancak Transformers.js'nin hangi cihazı kullanacağını yapılandırabilirsiniz. Maksimum performans için "webgpu", maksimum uyumluluk için "wasm" seçeneğini belirleyin. İsteğe bağlı olarak varsayılan ayarları değiştirebilirsiniz. Uyumlu modellerin Hugging Face kataloğundan başka bir model seçin. Bazı modellerde, dtype parametresini kullanarak farklı nicemlemeler arasından seçim yapabilirsiniz.

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

Polyfill'inizi yapılandırma

Yapılandırma dosyası hazır olduğunda artık uygulamanızda polyfill'i kullanmaya başlayabilirsiniz.

1. Yapılandırma dosyasını içe aktarın ve uygun şekilde adlandırılmış bir genel değişkene atayın. Burada $BACKEND, seçtiğiniz arka uçtur: window.$BACKEND_CONFIG.
2. Altta yatan tarayıcı desteklemediğinde yalnızca polyfill'i yüklemek için dinamik içe aktarma kullanın.
3. Prompt API işlevlerini çağırın.

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!');

Polyfill, yapılandırılmış çıkışı (Transformers.js arka ucu hariç) destekler, çok formatlı girişle (ses ve görüntüyü birlikte değil, yalnızca ayrı ayrı destekleyen OpenAI arka ucu hariç) ilgilenir ve LanguageModel için Web Platform Tests paketinin tamamına karşı test edilir.

Daha fazla arka plan bilgisi, ayrıntılı kullanım bilgileri ve kaynak kodu için GitHub deposundaki README dosyasına bakın.

Tarayıcı istemi API'sinden farkı

Polyfill, bulut modelleri tarafından destekleniyorsa istemci tarafında çalıştırmanın bazı avantajları artık geçerli değildir. Yani, arka uç sağlayıcınızın gizlilik politikaları geçerliliğini korusa da artık hassas verilerin yerel olarak işlenmesini garanti edemezsiniz. Uygulamanız, kullanıcı çevrimdışı olduğunda da artık yapay zekayı kullanamaz. Çevrimiçi veya çevrimdışı olup olmadığınızı öğrenmek için ilgili etkinlikleri dinleyebilirsiniz.

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

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

Yapay zeka çıkarımı buluttaki bir modele karşı çalıştırılıyorsa indirilecek yerel bir model yoktur. Polyfill, downloadprogress etkinliklerini taklit eder. Bu nedenle, uygulamanızda yerleşik model zaten indirilmiş gibi görünür. Bu da bir etkinlikte loaded değeri 0, diğerinde ise 1 olacağı anlamına gelir. Bu, spesifikasyonun gerektirdiği durumdur.

Cihaz üzerinde çıkarımın aksine, bulut tabanlı çıkarımda, tercih ettiğiniz arka uç sağlayıcının API'lerini çağırırken maliyet söz konusu olabilir. Gemini API'deki gibi fiyatlandırma bilgilerini kontrol edin. Jeton başına maliyeti biliyorsanız maliyeti hesaplamak için Prompt API'nin contextUsage bilgilerini kullanabilirsiniz.

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.
}

Bir bulut API'sini doğrudan bir mobil veya web uygulamasından çağırdığınızda (ör. üretken yapay zeka modellerine erişime izin veren API'ler) API anahtarı, yetkisiz istemciler tarafından kötüye kullanıma açık hâle gelir. Bu API'leri korumaya yardımcı olmak için Firebase AI Logic Hybrid SDK'yı kullanıyorsanız gelen tüm API çağrılarının gerçek uygulamanızdan geldiğini doğrulamak üzere Firebase Uygulama Kontrolü'nü kullanmanız gerekir. Google gibi bazı bulut sağlayıcılarla, yalnızca izin verilen web sitelerinin API'yi kullanabildiğinden emin olmak için katı kaynak kontrolleri de uygulayabilirsiniz.

Örneğin, oturumun contextWindow ile ilgili olarak Prompt API'nin sınırları yerine arka uç sağlayıcının sınırları geçerlidir. contextWindow için bu sınırlar genellikle cihaz üzerinde olanlardan çok daha yüksektir ve bulutta daha büyük miktarda veri işleyebilirsiniz. Bu nedenle, farkın bilincinde olmanız gerekse de uygulamada bu konuda sorun yaşamanız olası değildir.

Kendi arka ucunuzu oluşturma

Kendi arka uç sağlayıcınızı eklemek için aşağıdaki adımları uygulayın:

Temel arka uç sınıfını genişletme

backends/ dizininde yeni bir dosya oluşturun (örneğin, backends/custom-backend.js). PolyfillBackend sınıfını genişletmeniz ve beklenen arayüzü karşılayan temel yöntemleri uygulamanız gerekir.

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)
  }
}

Arka uçunuzu kaydetme

Polyfill, genel yapılandırmaya dayalı bir "ilk eşleşmeye öncelik" stratejisi kullanır. Arka uçunuzu, statik #backends dizisine ekleyerek prompt-api-polyfill.js dosyasında kaydetmeniz gerekir:

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

Varsayılan model ayarlama

Yedek model kimliğini backends/defaults.js içinde tanımlayın. Bu, bir kullanıcı belirli bir modelName belirtmeden oturum başlattığında kullanılır.

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

Yerel geliştirme ve testi etkinleştirme

Proje, test matrisleri oluşturmak için bir keşif komut dosyası (scripts/list-backends.js) kullanır. Yeni arka uçunuzu test çalıştırıcıya dahil etmek için kök dizinde bir .env-[name].json dosyası (örneğin, .env-custom.json) oluşturun:

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

Web Platform Testleri (WPT) ile doğrulama

Son adım, uygunluğu sağlamaktır. Polyfill, spesifikasyona dayalı olduğundan tüm yeni arka uçlar resmi (veya geçici) Web Platform Testleri'ni geçmelidir:

npm run test:wpt

Bu doğrulama adımı, arka uçunuzun AbortSignal, sistem istemleri ve geçmiş biçimlendirme gibi işlemleri Prompt API spesifikasyonunun beklediği şekilde gerçekleştirmesini sağlar.

Sonuç

Polyfill, istem API'sini tüm platformlarda ve cihazlarda kullanmanıza yardımcı olur. Prompt API'nin iyi tanımlanmış API'sine göre kodlama yaparak kendinizi bulut sağlayıcılardan daha bağımsız hale getirir ve platforma mümkün olduğunca yakın kalırsınız.

Prompt API'yi destekleyen uygun cihazlarda polyfill yüklenmez bile. Böylece kullanıcılarınız, çalıştırmayacakları kodu indirmekten kurtulur. Geri bildiriminiz varsa veya bir hatayla karşılaşırsanız GitHub'da sorun kaydı açın. Başarılı istemler yazmanız dileğiyle.