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ğıtmanız, yönetmeniz ya da kendi kendine barındırmanız gerekmeden yapay zeka destekli görevler gerçekleştirebilir. Demodan üretime hazır bir özelliğe geçiş yapmak zor olabilir. Bu belgede, sık karşılaşılan hatalardan kaçınmanıza yardımcı olacak teknik ve kullanıcı deneyimiyle ilgili hususlar ele alınmaktadır.

Modeli makul bir zamanda hazırlayın

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

Yapılacaklar: Kullanıcının yapay zeka özelliğini kullanma niyetini net bir şekilde belirlediğiniz anda (ör. kullanıcı ilgili bir yapay zeka aracı yüzeyine gittiğinde, yapay zeka çalışma alanının üzerine geldiğinde veya özelliğin etrafındaki kullanıcı arayüzüyle etkileşime girdiğinde) oturumu başlatın. Oturumun önceden ısıtılması, kullanıcı görevini ayarlarken modelin arka planda sessizce belleğe yüklenmesini sağlayarak gereksiz soğuk başlatma gecikmesini ortadan kaldırır. Örneğin, özellik yinelemeli kullanım için tasarlanmışsa mevcut sonucu oluşturmaya başlar başlamaz bir sonraki en olası yapay zeka görevini başlatarak bir adım önde olmaya çalışın.

Yapmayın: Gerekli olmadığı sürece oturumu başlatmak için kullanıcının "Oluştur"u tıklamasını beklemeyin. Modelin önce belleğe yüklenmesi ve yürütme hattını hazırlaması gerektiğinden bu durum, soğuk başlatma gecikmesine yol açar.

Oluşturma sırasında ilk istemleri ayarlama

Geçerli olduğu kullanıcılar: 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 bu 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 kullanıcılar: 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 ele almak 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: 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ı sistem talimatlarıyla tekrar tekrar aramayı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ı yok etme

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

Yapılması gerekenler: Artık ihtiyacınız olmayan oturumlarda destroy() işlevini açıkça çağırarak bir özellik artık 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.

Yapmayın: 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ılacaklar: 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ılacaklar: Modele yalnızca kesinlikle gerekli olan bilgileri 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.

Yapılmaması gerekenler: API'lere işlenmemiş ham metin, gereksiz meta veriler, HTML etiketleri veya büyük filtrelenmemiş listeler göndermeyin. Giriş boyutuyla birlikte gecikme ö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 kullanıcılar: Prompt API.

Yapılacaklar: Modelin verileri belirli bir biçimde döndürmesini istediğinizde, JSON şeması sağlamak için responseConstraint alanı ekleyerek 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 kısaltmak için istemci tarafı mantığını kullanın.

Yapılmaması gerekenler: Yapılandırılmış çıkış şemaları kullanarak maxLength: 125 gibi katı karakter sınırları uygulamayı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ıyı bilgilendirin

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

Yapılması gerekenler: Görevin karmaşıklığına ve beklenen süresine bağlı olarak, kullanıcıyı bilgilendirmek için animasyonlar, görsel ipuçları ve ilerleme göstergeleri 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ış: Özet 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 çıktının engellenmemesi durumunda, çıktının anında üretilmesi gerekmez. 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 olun.

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ğunun kendi algıladıkları zorlukla 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.

Yapmayın: 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 ve yapay zeka düzenlemelerini hızlıca geri almasına olanak tanıyan bir adım sayacı veya gezinme geçmişiyle kullanıcı arayüzünüzü donatın. 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 yazmayın. Kullanıcı, sürümleri geri alma, eski haline getirme veya karşılaştırma seçeneği olmadan bu taslağı ya da sonucu kaybeder.

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

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

Yapılacaklar: Kullanıcıyı, oluşturulan tüm içeriklerin son düzenleyicisi yapın. Kullanıcının nihai çıktı üzerinde tam sahipliğini koruyabilmesi için sezgisel geçersiz kılmalar sunun. API'ler yanlış sonuçlar üretebilir.

Yapmayın: Yapay zeka tarafından oluşturulan sonucu tek seçenek olarak sunmayın.

Tekrarlanan görevler için sonuçları önbelleğe alma

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

Yapılması gerekenler: Tekrarlanan girişler veya sorgular için yerel sonuç önbelleği uygulayın (örneğin, sessionStorage veya IndexedDB kullanarak). Önbellek isabetlerini artırmak için girişleri boşlukları kırparak ve küçük harfe dönüştürerek normalleştirin. Örneğin resimler gibi yoğun girişler için önbellek anahtarı olarak kullanılacak bir karma oluşturun. Ö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: Değişkenliğin istenmediği durumlarda (ör. kullanıcı arama sonuçları arasında ileri geri gezinirken) aynı çıkarımı tekrarlanan bir arama sorgusu veya aynı veri girişi için yeniden çalıştırmayın. Bu, yanıt hızını ve yerel bilgi işlem kaynaklarının verimli kullanımını optimize eder.

// ✅ 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;
}