Dil Modeli

Prompt API, geliştiricilerin Gemini Nano'yu kullanarak doğal dil işleme görevlerini doğrudan tarayıcıda çalıştırmasına olanak tanır. Bu yerleşik yapay zeka yaklaşımı, kullanıcı gizliliğini sağlar, sunucu maliyetlerini azaltır ve çevrimdışı işlevsellik sağlar.

1. Başlangıç ve Donanım Gereksinimleri

Prompt API şu anda Windows, macOS, Linux ve Chromebook Plus için Chrome'un 148 (Masaüstü) ve sonraki sürümlerinde kullanılabilir.

Donanım Ön Koşulları

• Depolama alanı: 22 GB boş alan (ilk profil ve model için).
• Bellek/CPU: 16 GB RAM ve 4+ CPU çekirdeği.
• GPU: 4 GB VRAM veya daha fazla (Ses girişi için gereklidir).
• Ağ: Yalnızca ilk model indirme işlemi için gereklidir.

API'yi başlatma

İndirme işlemini tetiklemeden önce modelin kullanılabilirliğini kontrol edin:

const availability = await LanguageModel.availability();

// Do not call create() when unavailable — the model cannot run on this device.
if (availability !== 'unavailable') {
    const session = await LanguageModel.create({
        monitor(m) {
            // Inform the user while the model downloads so the UI doesn't appear frozen.
            m.addEventListener('downloadprogress', (e) => {
                console.log(`Downloaded ${e.loaded * 100}%`);
            });
        },
    });
}

2. Temel İstem Özellikleri

Bu bölümdeki oturum örneklerinde, kısa olması için session.destroy() atlanmıştır. Cihaz belleğinde yer açmak için bir oturuma artık ihtiyaç duyulmadığında her zaman session.destroy() yöntemini çağırın (bkz. Bölüm 5).

Temel ve Akış Çıkışı

Kısa yanıtlar için prompt() kullanın. Daha uzun içerikler için promptStreaming() kullanarak daha duyarlı bir kullanıcı arayüzü sağlayın.

ZORUNLU: Model çıktısını hiçbir zaman innerHTML olarak atamayın. Model çıktısı güvenilir değildir ve eklenmiş işaretleme içerebilir. Her zaman textContent veya dezenfektan kullanın.

const session = await LanguageModel.create();

// prompt() accumulates the full response before resolving — use for short, one-shot output.
const result = await session.prompt('Write a haiku about coding.');
// textContent, not innerHTML — model output is untrusted and must not be parsed as markup.
outputEl.textContent = result;

// promptStreaming() yields independent chunks that must be concatenated;
// use for longer content so each chunk can be rendered progressively.
const stream = session.promptStreaming('Write a long story about a robot.');
let completeResult = '';
for await (const chunk of stream) {
    completeResult += chunk;
    outputEl.append(chunk);
}
console.log('Full story:', completeResult);

Çok formatlı giriş

Prompt API; metin, ses ve görsel girişleri (resimler, tuval, video kareleri) destekler.

const session = await LanguageModel.create({
    // Declaring expected input types lets the browser optimize model loading.
    expectedInputs: [{ type: 'text' }, { type: 'image' }],
    expectedOutputs: [{ type: 'text' }],
});

const response = await session.prompt([
    {
        role: 'user',
        content: [
            { type: 'text', value: 'What is in this image?' },
            { type: 'image', value: document.querySelector('canvas') },
        ],
    },
]);

3. Gelişmiş Oturum Yönetimi

Oturumlar, modelin birden fazla etkileşimde bağlamı korumasını sağlar.

Bağlam ve kota

Her oturumun maksimum jeton sınırı vardır. Kullanımı session.contextUsage ve session.contextWindow üzerinden izleyebilirsiniz. Pencere taşarsa en eski mesajlar (sistem istemi hariç) silinir.

Oturumları kopyalama

Klonlama, aynı başlangıç bağlamını (ör. "sistem" kişiliği) paylaşan paralel sohbetleri yeniden başlatmadan başlatmak için etkilidir.

const mainSession = await LanguageModel.create({
    initialPrompts: [{ role: 'system', content: 'You speak like a pirate.' }],
});

const branchA = await mainSession.clone();
const branchB = await mainSession.clone();
// Destroy the base after cloning — the clones own their own context from here.
mainSession.destroy();

Geçmiş oturumlar geri yükleniyor

Yerel bir "geri yükleme" özelliği geliştirme aşamasındadır. Bu özellik kullanıma sunulana kadar, önceki geçmişi initialPrompts uygulamasına besleyerek bir oturumu yeniden oluşturabilirsiniz.

Not: localStorage şifrelenmez ve kalıcıdır. Saklanan sohbet geçmişi, kullanıcıların kimliği tanımlayabilecek bilgilerini içerebilir. Sohbet geçmişini saklamadan önce gizlilikle ilgili sonuçları göz önünde bulundurun.

// || '[]' ensures JSON.parse never receives null when the key doesn't exist yet.
const history = JSON.parse(localStorage.getItem('chat_history') || '[]');
const session = await LanguageModel.create({
    initialPrompts: history, // Array of {role, content} objects
});

4. JSON şemasıyla yapılandırılmış çıkış

Modelin "gevezelik" (ör. "Elbette, JSON'unuz burada:") eklemesini önlemek için responseConstraint alanı üzerinden bir JSON şeması kullanın. Bu sayede, çıkışın hemen ayrıştırılabilen geçerli bir JSON olması sağlanır.

Örnek: Duygu Sınıflandırması

// Pass the schema as a plain object — do not JSON.stringify() it first.
const schema = {
    type: 'object',
    properties: {
        rating: { type: 'number', minimum: 1, maximum: 5 },
        is_positive: { type: 'boolean' },
    },
    required: ['rating', 'is_positive'],
};

const result = await session.prompt(
    "Rate the following feedback: 'The food was great!'",
    { responseConstraint: schema },
);

const data = JSON.parse(result);
console.log(data.rating); // 5

Kısıtlamalar ve Önekler

prefix: true kullanarak asistanın yanıtını önceden doldurarak modeli daha fazla yönlendirebilirsiniz.

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

5. En İyi Uygulamalar ve Güvenlik

• Kaynak Temizleme: Bellekte yer açmak için bir görüşme bittiğinde her zaman session.destroy() yöntemini çağırın.
• Çıkış güvenliği: Model çıktısı güvenilir değil. Kötü amaçlı model çıktısından XSS yerleştirmesini önlemek için sonuçları her zaman innerHTML yerine textContent içine yazın.
• Sınırlı HTML'ye izin vermeniz gerekiyorsa yerel Sanitizer API veya DOMPurify gibi bir temizleyici kullanın.
• Görevleri iptal etme: Kullanıcıların uzun süren oluşturma işlemlerini durdurmasına olanak tanımak için AbortController kullanın. signal'i LanguageModel.create()'e değil, prompt() veya promptStreaming()'a geçirin.
• Güvenlik: iframe'lerde erişimi kontrol etmek için izin politikalarını kullanın: <iframe src="..." allow="language-model"></iframe>.
• Tasarım: Sorumlu yapay zeka uygulamasını sağlamak için People + AI Guidebook'u inceleyin.

Geliştiriciler, yapılandırılmış çıkışları güçlü oturum yönetimiyle birleştirerek tamamen kullanıcının cihazında çalışan karmaşık, durum bilgisi olan yapay zeka uygulamaları oluşturabilir.

Yapılması ve yapılmaması gerekenler

Yapılması ve yapılmaması gerekenlerin ayrıntılı listesi için https://developer.chrome.com/docs/ai/built-in-ai-dos-donts.md.txt adresini ziyaret edin. Özetle:

Modeli makul bir sürede hazırlama

Geçerli olduğu API'ler: Özetleyici, Çevirmen ve Yazar gibi tüm API'ler.

Doğru: Kullanıcının yapay zeka özelliğini kullanma niyetini net bir şekilde belirlediğiniz anda oturumu başlatın. Örneğin, kullanıcı ilgili yapay zeka araçları yüzeyine gittiğinde, yapay zeka çalışma alanının üzerine geldiğinde veya özelliğin çevresindeki kullanıcı arayüzüyle etkileşime geçtiğinde. Oturumu önceden ısıtmak, modelin arka planda sessizce belleğe yüklenmesini sağlar. Böylece, kullanıcı görevini ayarlarken önlenebilir soğuk başlatma gecikmesi ortadan kalkar. Ö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 ardışık düzenini hazırlaması gerektiğinden bu durum, baştan başlatma gecikmesine neden olur.

Oluşturma sırasında ilk istemleri ayarlama

Geçerli olduğu API: Prompt API.

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

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

Tekrarlanan görevler için oturumları kopyalama

Geçerli olduğu API: Prompt API.

Prompt API'de her oturum, önceki tüm etkileşimleri dikkate alarak sohbetin bağlamını takip eder. Klon, ilk istemler ve klonlama noktasına kadar olan tüm etkileşim geçmişi dahil olmak üzere üst oturumundaki her şeyi devralır. Bu nedenle, kullanımınızı yalnızca ihtiyacınız olanı devralacak şekilde yapılandırın.

Yapılması gerekenler:

• Temel oturum oluşturma: 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 klonlama: Sistem talimatlarını yeniden ayrıştırma zahmetinden kurtulmak için yeni görevlerde bu temel oturumda clone() kullanın. Bu sayede paralel sohbetler oluşturabilir veya bir görevi başlangıç durumuna sıfırlayabilirsiniz.

Yapılmaması gerekenler:

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

Kullanılmayan oturumları sonlandırma

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

Doğru: Bir özellik artık kullanılmadığında bellekten yer açmak için artık ihtiyacınız olmayan oturumlarda destroy() yöntemini açıkça çağırın. Klonlama kalıbı kullanıyorsanız temel oturumu saklayın ve artık ihtiyacınız olmayan klonları silin.

Yapmayın: Birden fazla büyük oturumu etkin tutmayın. Her oturum bellek tüketir. Bu da gereksiz kaynak kullanımına yol açar ve sorun oluşturabilir. Oturumlar, çöp toplayıcı tarafından doğal olarak temizlenir ancak destroy() yöntemini çağırmak, belleği daha hızlı boşaltır.

Akış 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).

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

Yapmayın: Her parça güncellemesinde innerHTML değerini 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.

Girişi hız için optimize etme

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

Doğru: Modele yalnızca kesinlikle gerekli olan bilgileri iletin. Elinizdeki görevle ilgisi olmayan her şeyi çıkarın. Büyük veri kümeleri için kısa bir genel bakış ve alakalı öğelerden oluşan küçük bir seçki sunun.

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

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

Geçerli olduğu API: Prompt API.

Do: Modelin verileri belirli bir biçimde döndürmesi gerektiğinde JSON şeması sağlamak için responseConstraint alanını kullanarak yapılandırılmış çıkış kullanın. Bu sayede, çıktının tahmin edilebilir olması sağlanır ve karmaşık işlem sonrası işlemlere veya manuel ayrıştırmaya gerek kalmaz.

Yapmayın: Yalnızca doğal dildeki talimatlara (ör. "yalnızca JSON çıkışı ver") güvenmeyin. Modeller, ayrıştırıcınızı bozan konuşma dolguları içerebilir.

Uzunluk kısıtlamalarından bağımsız olarak içerik üretme

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

Doğru yaklaşım: Modelin yanıtını doğal bir şekilde oluşturmasına izin verin ve ardından metni kullanıcı arayüzünüze sığacak şekilde kısaltmak için istemci tarafı mantığını kullanın.

Yapmayın: Yapılandırılmış çıkış şemalarını kullanarak maxLength: 125 gibi katı karakter sınırlamaları uygulamayın. Modelin yanıtı, belirlediğiniz sınırdan uzun olduğunda model, anlamı sıkıştırmak için yabancı diller veya emojiler gibi yüksek yoğunluklu jetonlara geçebilir ve bu da anlamsız bir çıkışa neden olabilir.

Kullanıcıyı bilgilendirme

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

Doğru: 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 uygun yaklaşım, kullanım alanınıza ve API çıkışının beklenen uzunluğuna bağlıdır. Birkaç fikir:

• Uzun içerikler için akış: Özetler veya sohbetler için akış, varsayılan olarak jeton başına daktilo efekti oluşturur. Bu yöntem doğal bir his verebilir ve anında geri bildirim sağlayabilir.
• Kısa görevler (veya uzun eş zamansız görevler) için akışsız: Alternatif metin gibi kısa çıkışlar için akışsız, daha şık bir kullanıcı arayüzü oluşturabilir. Ayrıca, mevcut görev oluşturulurken bir sonraki yapay zeka görevini tahmini olarak hazırlamak için zaman kazandırır. Bu yaklaşım, daha uzun süren eşzamansız veya arka plan görevleri için de kullanılabilir. Kullanıcının yolculuğuna devam etmesi için çıktının hemen üretilmesi gerekmiyorsa çıktıyı anında üretmeye gerek yoktur. Kullanıcı arayüzünde işlemin devam ettiğini gösterin.
• Güncellemeler için görsel geçişler: Metinleri ç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üncellemek.

Kullanıcının zaman ve çalışma ile ilgili zihinsel modeliyle uyumlu olma

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

Doğru: Yanıt neredeyse anında veriliyorsa bir veya iki saniyelik yapay bir gecikme ekleyin. Çelişkili bir şekilde, kullanıcılar, görevin zorluk derecesine uygun bir üretim süreci algıladıklarında sonuçları daha güvenilir bulabilirler. Yapay zeka işleminin gerçekleştiğini belirtmek için animasyonlar kullanın.

Yapmayın: Kullanıcı arayüzünü aniden değiştirerek kullanıcıları şaşırtmayın.

Kullanıcıların yapay zeka düzenlemelerinde hızlıca gezinmesine ve bunları geri almasına izin ver

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

Doğru: Kullanıcı arayüzünüzü, kullanıcıların farklı sonuçları güvenle keşfetmesine olanak tanıyan bir adım adım ilerleme aracı veya gezinme geçmişiyle donatın ve yapay zeka düzenlemelerini hızlıca geri almalarına izin verin. Bu sayede farklı sürümler her zaman kullanıma hazır olur.

Yapmayın: Kullanıcının önceki taslağının veya beğendiği bir yapay zeka sonucunun üzerine yazmayın. Geri dönme, geri alma veya sürümleri karşılaştırma imkanı sunun.

Kullanıcı kontrolünü ve geçersiz kılma işlemlerini destekleme

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

Doğru: Oluşturulan tüm içeriklerin son düzenleyicisi kullanıcı olmalıdır. Kullanıcının nihai çıktının tam sahipliğini koruması için sezgisel geçersiz kılma seçenekleri sunun. API'ler yanlış sonuçlar üretebilir.

Yapmayın: Yapay zeka tarafından üretilen bir sonucu tek seçenek olarak sunmayın.

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

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

Doğru: Tekrarlanan girişler veya sorgular için yerel bir sonuç önbelleği (ör. sessionStorage veya IndexedDB kullanarak) uygulayın. Önbellek isabetlerini artırmak için boşlukları kırparak ve küçük harf kullanarak girişi normalleştirin. Görseller gibi büyük girişler için önbellek anahtarı olarak kullanılacak bir karma oluşturun. Önbelleğiniz için ihtiyatlı bir geçerlilik süresi (TTL) ayarlayın (veya önbelleğe alınmış sonuçları arka planda güncellerken sunun). Sonuç tatmin edici değilse kullanıcının yeni bir çıkarım tetiklemesine izin verin.

Yapmayın: Tekrarlanan bir arama sorgusu veya değişkenliğin istenmediği aynı veri girişi için aynı çıkarımı yeniden çalıştırmayın (ör. bir kullanıcı arama sonuçları arasında ileri geri gittiğinde). Bu sayede yanıt hızı ve yerel işlem gücünün verimli kullanımı optimize edilir.

6. Yedek stratejiler

Kullanmadan önce LanguageModel nesnesinin genel kapsamda olup olmadığını kontrol edin:

if ('LanguageModel' in self) {
  // The Prompt API is supported.
} else {
  // Execute fallback strategy
}

Prompt API desteklenmiyorsa veya kullanılabilirlik kontrolleri "kullanılamıyor" değerini döndürüyorsa kontrollü bir şekilde yedekleme yapmanız gerekir:

• Uzak API yedekleme: Algılama isteğini bir sunucu uç noktasına veya bulut API'sine (ör. Vertex AI Gemini API) yönlendirin.
• Yerel API yedek çözümü: Algılama isteğini yerel bir uç noktaya yönlendirin (ör. Transformers.js kullanarak).