Yerleşik yapay zeka API'leri: Yapılması ve yapılmaması gerekenler

Maud Nalpas

Yayınlanma tarihi: 30 Nisan 2026

Yerleşik yapay zeka sayesinde web siteniz veya web uygulamanız, modelleri dağıtma, yönetme ya da kendi kendine barındırma ihtiyacı olmadan yapay zeka destekli görevler gerçekleştirebilir. Demodan üretime hazır bir özelliğe geçmek zor olabilir. Bu belgede, sık karşılaşılan sorunlardan kaçınmanıza yardımcı olacak teknik ve kullanıcı deneyimiyle ilgili hususlar ele alınmaktadır.

Modeli erken hazırlayın

Geçerli olduğu kullanıcılar: Tüm API'ler (ör.Summarizer, Translator ve Writer)

Yapılacaklar: Kullanıcı niyetini anladığınız anda oturumu başlatın. Oturum başlatmak için kullanıcı etkinleştirme gerektiğinden, yapay zeka destekli özellik sunan sayfada herhangi bir yeri tıklama gibi etkileşimleri kullanabilirsiniz. Bu işlem, kullanıcı arayüzüyle etkileşimde bulunurken modeli ve çalışma zamanını hazırlar. İlgili olduğunda, sonucu oluşturmaya başlar başlamaz en olası bir sonraki yapay zeka görevini başlatın.

Yapmayın: Oturumu başlatmak için kullanıcının "Oluştur"u tıklamasını bekleyin. Modelin önce belleğe yüklenmesi ve yürütme hattını hazırlaması gerektiğinden bu durum, birkaç saniyelik bir baştan başlatma gecikmesine neden olur.

Oluşturma sırasında ilk istemleri ayarlama

Geçerli olduğu API: Prompt API.

Yapılacaklar: İlk istemin hızını artırmak için oturum başlatma sırasında sistem talimatları sağlayın.

Yapmayın: Boş bir oturumla başlayıp ilk prompt() çağrısının bir parçası olarak sistem talimatları göndermeyin. Bu durum, modeli talimatları son anda işlemeye zorladığı için gecikmeyi artırır.

// ✅ DO: Create the session as early as possible (tip on warming up the model early) and use initialPrompts for system instructions in the create call
const session = await LanguageModel.create({
  initialPrompts: [
    { role: 'system', content: 'You are a helpful assistant specialized in code reviews.' }
  ]
});

// A few moments later, when the user triggers the AI feature
const review = await session.prompt(`Review the following code:\n\n${code}`);

// ❌ DON'T: Send instructions using prompt() after creation
// const slowerSession = await LanguageModel.create();
// await slowerSession.prompt(`You are a helpful assistant specialized in code reviews.\n\nReview the following code:\n\n${code}`); // Higher latency

Tekrarlanan görevler için oturumları klonlama

Geçerli olduğu API: Prompt API.

İstem API'sinde her oturum, konuşmanın bağlamını izler ve önceki tüm etkileşimleri dikkate alır. Klon, başlangıç istemleri ve klonlama noktasına kadar olan tüm etkileşim geçmişi dahil olmak üzere her şeyi üst oturumundan devraldığı için kullanımınızı yalnızca ihtiyacınız olanları devralacak şekilde yapılandırın.

Yapılması gerekenler:

• Temel oturum oluşturma: Birbiriyle alakasız görevleri verimli bir şekilde yönetmek için yalnızca sistem talimatlarınızı içeren ve önceki sohbet bağlamını içermeyen bir temel oturum oluşturun.
• Temeli klonlayın: Ağır sistem talimatlarını yeniden ayrıştırma yükünü azaltmak için yeni görevlerde bu temel oturumda clone() simgesini kullanın. Bu sayede paralel sohbetler oluşturabilir veya bir görevi temel haline sıfırlayabilirsiniz.

Yapılmaması gerekenler:

• Alakasız görevler için aynı oturumu tekrar kullanmayın ve gereksiz etkileşim geçmişi içeren oturumları klonlamayın. Her iki kalıp da alakasız önceki bağlamın mevcut görevinize müdahale etmesine neden olabilir.
• create()'ı aynı ve ağır sistem talimatlarıyla tekrar tekrar çağırmayın. Performansı optimize etmek için bunun yerine klonlama kalıbını kullanın.

// ✅ DO: Create a baseline session and clone it for each new task
const baseSession = await LanguageModel.create({
  initialPrompts: [{
    role: 'system',
    content: 'You are a technical editor...',
  }],
});

// Clone the base session once for the first task
const task1 = await baseSession.clone();
const response1 = await task1.prompt("Review this first draft...");
// ... Repeat the cloning pattern for subsequent independent tasks
// Each task starts fresh from the baseline system instructions

// ❌ DON'T:
// Bad performance pattern: repeated create() calls for identical tasks.
// This forces the model to re-parse instructions every time, increasing latency.
// const sessionA = await LanguageModel.create({ initialPrompts: [...] });
// await sessionA.prompt("Task 1...");
// const sessionB = await LanguageModel.create({ initialPrompts: [...] });
// await sessionB.prompt("Task 2...");
// Bad quality pattern: reusing the same session for unrelated tasks.
// const session = await LanguageModel.create();
// await session.prompt("Analyze this financial report...");
// Unrelated task in the same session:
// await session.prompt("Now write a children's story...");

Kullanılmayan oturumları silme

Geçerlilik kapsamı: Tüm API'ler.

Yapılacaklar: Artık ihtiyacınız olmayan oturumlarda �destroy() işlevini açıkça çağırarak bir özellik kullanılmadığında belleği boşaltın. Klonlama kalıbı kullanıyorsanız temel oturumu koruyun ve artık ihtiyacınız olmayan klonları silin.

Yapılmaması gerekenler: Birden fazla büyük oturumu etkin tutmayın. Her oturumda bellek tüketilir. Bu durum, gereksiz kaynak kullanımına neden olur ve sorun teşkil edebilir. Oturumlar çöp toplayıcı tarafından doğal olarak temizlenir ancak destroy() çağrıldığında bellek daha hızlı boşaltılır.

// ✅ DO: Use the clone and destroy it immediately after
const clone = await baseSession.clone();
const response = await clone.prompt("Quick task...");
// Free memory right away: destry the clone, keep the baseSession
clone.destroy();

Yayın yanıtlarını güvenli ve verimli bir şekilde oluşturma

Geçerli olduğu API'ler: Akış desteği sunan tüm API'ler (Prompt, Summarizer, Writer, Rewriter ve Translator).

Yapılması gerekenler: Tüm LLM çıkışlarını güvenilmeyen içerik olarak değerlendirin. Kötü amaçlı kod güncellemeler arasında bölünebileceğinden, yalnızca parçalar değil, birleştirilmiş çıktının tamamı temizlenmelidir. Oluşturmadan önce, desteklenen yerlerde Sanitizer API'yi kullanın. Performansın düşmesini önlemek için streaming-markdown gibi bir akış Markdown ayrıştırıcısı kullanın.

Yapmayın: innerHTML değerini her parça güncellemesinde doğrudan ayarlamayın. Bu yöntem, özellikle söz dizimi vurgulama gibi karmaşık biçimlendirmelerde yavaştır ve ekleme saldırılarına karşı savunmasızdır.

import * as smd from "streaming-markdown";
// Set up virtual buffer and Sanitizer API
const sanitizer = new Sanitizer({
  allowElements: ['figure', 'figcaption', 'p', 'br', 'strong', 'em', 'img', 'a'],
  allowAttributes: {
    'loading': ['img'], 'decoding': ['img'], 'src': ['img'], 'href': ['a']
  }
});

// Create an off-screen fragment so the parser doesn't cause flicker
// or trigger XSS in the live DOM during the building process.
const buffer = new DocumentFragment();
const parser = smd.parser_new(buffer);

// Use sanitizer as a gatekeeper / cleaner function so we can combine it with the streaming Markdown parser
function syncSanitized(target, sourceFragment) {
  // .sanitize() returns a fresh, clean DocumentFragment
  const cleanFragment = sanitizer.sanitize(sourceFragment);
  // replaceChildren is the modern high-performance way to swap DOM content
  target.replaceChildren(cleanFragment);
}

// Streaming Logic
// `chunks` keeps track of the raw string (useful for logs/debug)
chunks += chunk;
// Let the parser build the DOM incrementally in the buffer.
// This is high-performance because the buffer is not live
smd.parser_write(parser, chunk);
// Use the Sanitizer API to port the content safely to the container.
syncSanitized(container, buffer);

Girişi hız için optimize etme

Geçerlilik kapsamı: Tüm API'ler.

Yapılması gerekenler: Yalnızca kesinlikle gerekli olan bilgileri modele iletin. O anki görevle alakasız her şeyi çıkar. Büyük veri kümeleri için kısa bir genel bakış ve ilgili öğelerden küçük bir seçim sunun.

Yapmayın: API'lere işlenmemiş ham metin, gereksiz meta veriler, HTML etiketleri veya büyük filtrelenmemiş listeler göndermeyin. Gecikme, giriş boyutuyla birlikte önemli ölçüde artar. Bu durum, yapay zeka özelliğinin birçok cihazda bozuk görünmesine neden olabilir.

// ✅ DO: Send only relevant text
const cleanText = document.querySelector('#article').innerText;
const summary = await Summarizer.summarize(cleanText);

// ❌ DON'T: Send the entire DOM structure
// const dirtyText = document.querySelector('#article').innerHTML;

Tahmin edilebilir sonuçlar için yapılandırılmış çıkış kullanma

Geçerli olduğu API: Prompt API.

Yapılacaklar: Modelin verileri belirli bir biçimde döndürmesini istediğinizde, JSON şeması sağlamak için responseConstraint alanı belirterek yapılandırılmış çıkış kullanın. Bu sayede, çıkışın tahmin edilebilir olması sağlanır ve karmaşık bir son işlem veya manuel ayrıştırma yapmanız gerekmez.

Yapmayın: Yalnızca doğal dil talimatlarına (ör. "yalnızca JSON çıkışı yap") güvenin. Modeller, ayrıştırıcınızı bozan sohbet dolgusu içerebilir.

// ✅ DO: Use a JSON Schema for predictable results
const schema = {
  type: "object",
  properties: {
    isTopicCats: { type: "boolean" }
  }
};

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

Üretimi uzunluk kısıtlamalarından ayırma

Şu API için geçerlidir: Yapılandırılmış çıkış şemalarını destekleyen tek API olan Prompt API.

Yapılacaklar: Modelin yanıtını doğal bir şekilde oluşturmasına izin verin ve ardından metni kullanıcı arayüzünüze uyacak şekilde kesmek için istemci tarafı mantığını kullanın.

Yapmayın: Yapılandırılmış çıkış şemaları kullanarak maxLength: 125 gibi katı karakter sınırları uygulayın. Bir modelin yanıtı, belirlediğiniz sınırdan uzun olduğunda anlamı sıkıştırmak için yabancı diller veya emoji gibi yüksek yoğunluklu jetonlara geçebilir. Bu da anlamsız bir çıkışa neden olur.

/*  DO: Handle overflow using CSS */
.result {
  overflow: hidden;
  white-space: nowrap;
  text-overflow: ellipsis; /* Displays '…' */
}

// ❌ DON'T: Force length in the prompt
const result = await session.prompt("Write a bio in exactly 50 characters.");

Kullanıcının sabrını yönetme

Geçerlilik kapsamı: Tüm API'ler.

Yapılması gerekenler: Kullanıcının sabrını yönetmek için animasyonlar ve kullanıcı arayüzü teknikleri kullanın. En iyi yaklaşım, kullanım alanınıza ve API çıkışının beklenen uzunluğuna bağlıdır. Bazı fikirler:

• Uzun içeriklerde akış: Özetler veya sohbet için akış, varsayılan olarak jeton başına daktilo efekti oluşturur. Bu yöntem doğal bir deneyim sunar ve anında geri bildirim sağlar.
• Kısa görevler (veya uzun eş zamansız görevler) için akışsız: Kısa çıktılar (ör. alternatif metin) için akışsız yöntemle daha iyi bir kullanıcı arayüzü oluşturulabilir. Ayrıca, mevcut görev oluşturulurken bir sonraki yapay zeka görevini spekülatif olarak hazırlamak için zaman tanır. Bu yaklaşım, daha uzun süren eşzamansız veya arka plan görevleri için de geçerlidir. Kullanıcının yolculuğuna devam etmesi için çıkışta engellenmemesi durumunda, çıkışın anında üretilmesi acil bir ihtiyaç değildir. Kullanıcı arayüzünde işlemin devam ettiğini belirtin.
• Güncellemeler için görsel geçişler: Metni çevirirken veya yeniden yazarken animasyonlar (ör. kelime dönüştürme) kullanın.

Yapılmaması gerekenler: Kullanıcı arayüzünü görsel ipuçları olmadan güncelleme.

Kullanıcının zaman ve iş hakkındaki zihinsel modeliyle uyumlu olma

Geçerlilik kapsamı: Tüm API'ler.

Yapılacaklar: Yanıt neredeyse anında geliyorsa bir veya iki saniyelik yapay bir gecikme ekleyin. Paradoksal olarak, kullanıcılar, görev zorluğu algılarıyla uyumlu bir oluşturma süreci algıladıklarında sonuçları daha güvenilir bulabilir. Yapay zeka sürecinin gerçekleştiğini belirtmek için animasyonlar kullanın.

Yapılmaması gerekenler: Kullanıcıları anlık kullanıcı arayüzü değişiklikleriyle şaşırtmayın.

Kullanıcıların yapay zeka düzenlemelerinde hızlıca gezinmesine ve bu düzenlemeleri geri almasına izin verin.

Geçerlilik kapsamı: Tüm API'ler.

Yapılması gerekenler: Kullanıcıların farklı sonuçları güvenle keşfetmesine olanak tanıyan bir adım sayacı veya gezinme geçmişiyle kullanıcı arayüzünüzü donatın ve yapay zeka düzenlemelerini hızlıca geri almalarına izin verin. Bu sayede farklı sürümler kolayca kullanılabilir olmaya devam eder.

Yapmayın: Kullanıcının önceki taslağının veya beğendiği yapay zeka sonucunun üzerine, geri dönme, eski haline getirme veya sürümleri karşılaştırma olanağı sunmadan yazmayın.

Kullanıcı kontrolünü ve geçersiz kılmaları etkinleştirme

Geçerlilik kapsamı: Tüm API'ler.

Yapılması gerekenler: Her zaman son sözü kullanıcıya bırakın. Önerileri manuel olarak geçersiz kılma olanağı sunma. API'ler yanlış sonuçlar üretebilir.

Yapılmaması gerekenler: Yapay zekayla üretilen sonucu tek seçenek olarak sunmayın.

Tekrarlanan görevlerin sonuçlarını önbelleğe alma

Geçerlilik kapsamı: Tüm API'ler.

Yapılması gerekenler: Tekrarlanan girişler veya sorgular için yerel bir sonuç önbelleği uygulayın (örneğin, sessionStorage veya IndexedDB kullanarak). Önbellek isabetlerini artırmak için girişi boşlukları kırparak ve küçük harfe dönüştürerek normalleştirin. For heavy inputs, for example, images, generate a hash to use as a cache key. Önbelleğiniz için muhafazakar bir geçerlilik süresi (TTL) ayarlayın (veya arka planda güncellerken önbelleğe alınmış sonuçlar sunun). Sonuç tatmin edici değilse kullanıcının yeni bir çıkarım tetiklemesine izin verin.

Yapılmaması gerekenler: Tekrarlanan bir arama sorgusu veya aynı veri girişi için aynı çıkarımı yeniden çalıştırmayın. Örneğin, kullanıcı arama sonuçları arasında ileri geri gezinirken bu işlemi yapmayın. Cihaz üzerinde çıkarım, bulut maliyetleri açısından ücretsiz olsa da kullanıcı zamanı ve pil ömrü açısından maliyetlidir.

// ✅ DO: Check a local cache before running inference
async function getAiResponse(userInput, forceRefresh = false) {
  // Normalize the query to increase cache hits
  const query = userInput.trim().toLowerCase();
  const cacheKey = `ai_results_${query}`;
  const TTL_MS = 3600000; // 1 hour conservative TTL

  if (!forceRefresh) {
    const itemStr = localStorage.getItem(cacheKey);
    if (itemStr) {
      const item = JSON.parse(itemStr);
      const now = Date.now();

      // Check if the item has expired
      if (now < item.expiry) {
        // Lightweight safety check before rendering
        if (isValid(item.value)) return item.value;
      } else {
        // Delete the stale entry if the TTL has passed
        localStorage.removeItem(cacheKey);
      }
    }
  }

  // Fallback: Run inference if no valid cache exists
  const session = await LanguageModel.create();
  const response = await session.prompt(userInput);

  // Store the result for future use (with an expiration)
  const cacheData = {
    value: response,
    expiry: Date.now() + TTL_MS
  };
  localStorage.setItem(cacheKey, JSON.stringify(cacheData));

  return response;
}