Model Bahasa

Fitur web: LanguageModel

Prompt API memungkinkan developer menjalankan tugas natural language processing langsung di browser menggunakan Gemini Nano. Pendekatan AI bawaan ini memastikan privasi pengguna, mengurangi biaya server, dan memungkinkan fungsi offline.

1. Persiapan dan Persyaratan Hardware

Prompt API saat ini tersedia di Chrome mulai versi 148 (Desktop) untuk Windows, macOS, Linux, dan Chromebook Plus.

Prasyarat Hardware

  • Penyimpanan: Ruang kosong 22 GB (untuk profil dan model awal).
  • Memori/CPU: RAM 16 GB dan 4+ core CPU.
  • GPU: VRAM 4 GB atau lebih (Diperlukan untuk input audio).
  • Jaringan: Hanya diperlukan untuk download model awal.

Melakukan inisialisasi API

Periksa ketersediaan model sebelum memicu download:

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. Kemampuan Prompting Inti

Contoh sesi di bagian ini menghilangkan session.destroy() agar lebih singkat. Selalu panggil session.destroy() saat sesi tidak lagi diperlukan untuk mengosongkan memori perangkat (lihat Bagian 5).

Output Dasar dan Streaming

Untuk respons singkat, gunakan prompt(). Untuk konten yang lebih panjang, gunakan promptStreaming() untuk memberikan UI yang lebih responsif.

WAJIB: Jangan pernah menetapkan output model ke innerHTML. Output model tidak tepercaya dan dapat berisi markup yang diinjeksikan. Selalu gunakan textContent atau pembersih.

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

Input Multimodal

Prompt API mendukung input teks, audio, dan visual (gambar, kanvas, frame video).

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. Pengelolaan Sesi Lanjutan

Sesi memungkinkan model mempertahankan konteks di beberapa interaksi.

Konteks dan Kuota

Setiap sesi memiliki batas token maksimum. Anda dapat memantau penggunaan melalui session.contextUsage dan session.contextWindow. Jika jendela melebihi batas, pesan terlama (kecuali perintah sistem) akan dihapus.

Sesi Cloning

Meng-clone efisien untuk memulai percakapan paralel yang memiliki konteks awal yang sama (seperti kepribadian "sistem") tanpa melakukan inisialisasi ulang.

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();

Memulihkan Sesi Sebelumnya

Meskipun fitur "pemulihan" native sedang dalam pengembangan, Anda dapat membuat ulang sesi dengan memasukkan histori sebelumnya ke initialPrompts.

Catatan: localStorage tidak dienkripsi dan bersifat persisten. Histori percakapan yang disimpan mungkin menyertakan PII pengguna — pertimbangkan implikasi privasi sebelum mempertahankan histori chat.

// || '[]' 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. Output Terstruktur dengan Skema JSON

Untuk mencegah model menambahkan "basa-basi" (misalnya, "Tentu, ini JSON Anda:"), gunakan Skema JSON melalui kolom responseConstraint. Hal ini memastikan output-nya adalah JSON yang valid dan dapat langsung diuraikan.

Contoh: Klasifikasi Sentimen

// 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

Batasan dan Awalan

Anda dapat memandu model lebih lanjut dengan mengisi otomatis respons asisten menggunakan prefix: true.

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

5. Praktik Terbaik dan Keamanan

  • Pembersihan Resource: Selalu panggil session.destroy() saat percakapan selesai untuk mengosongkan memori.
  • Keamanan Output: Output model tidak tepercaya. Selalu tulis hasil ke textContent, bukan innerHTML, untuk mencegah injeksi XSS dari output model berbahaya.
  • Gunakan pembersih seperti Sanitizer API native atau DOMPurify jika Anda perlu mengizinkan HTML terbatas.
  • Membatalkan Tugas: Gunakan AbortController untuk memungkinkan pengguna menghentikan pembuatan yang berjalan lama. Teruskan signal ke prompt() atau promptStreaming(), bukan ke LanguageModel.create().
  • Keamanan: Gunakan Kebijakan Izin untuk mengontrol akses di iframe: <iframe src="..." allow="language-model"></iframe>.
  • Desain: Tinjau Panduan People + AI untuk memastikan penerapan AI yang bertanggung jawab.

Dengan menggabungkan output terstruktur dengan pengelolaan sesi yang andal, developer dapat membangun aplikasi AI stateful yang kompleks dan berjalan sepenuhnya di perangkat pengguna.

Anjuran dan Larangan

Untuk mengetahui daftar lengkap hal yang boleh dan tidak boleh dilakukan, lihat https://developer.chrome.com/docs/ai/built-in-ai-dos-donts.md.txt. Berikut adalah intinya:

Menyiapkan model pada waktu yang tepat

Berlaku untuk: semua API, misalnya, Summarizer, Translator, dan Writer.

Lakukan: Lakukan inisialisasi sesi segera setelah Anda menetapkan dengan jelas niat pengguna untuk menggunakan fitur AI, misalnya, saat pengguna membuka platform alat AI yang relevan, mengarahkan kursor ke ruang kerja AI, atau berinteraksi dengan UI di sekitar fitur. Dengan melakukan pra-pemanasan sesi, model dapat dimuat ke dalam memori secara diam-diam di latar belakang saat pengguna menyiapkan tugasnya, sehingga menghilangkan latensi cold-start yang dapat dihindari. Cobalah untuk selangkah lebih maju dengan memulai tugas AI berikutnya yang paling mungkin segera setelah Anda mulai merender hasil saat ini, misalnya, jika fitur tersebut dirancang untuk penggunaan berulang.

Jangan: Kecuali jika diperlukan, jangan menunggu pengguna mengklik "Buat" untuk melakukan inisialisasi sesi. Hal ini menyebabkan penundaan cold start, karena model harus dimuat terlebih dahulu ke dalam memori dan menyiapkan pipeline eksekusinya.

Menetapkan perintah awal selama pembuatan

Berlaku untuk: Prompt API.

Lakukan: Berikan petunjuk sistem selama inisialisasi sesi untuk meningkatkan kecepatan perintah pertama.

Jangan: Memulai dengan sesi kosong dan mengirim petunjuk sistem sebagai bagian dari panggilan prompt() pertama. Hal ini meningkatkan latensi karena memaksa model untuk memproses petunjuk tersebut pada saat-saat terakhir.

Meng-clone sesi untuk tugas berulang

Berlaku untuk: Prompt API.

Untuk Prompt API, setiap sesi melacak konteks percakapan, dengan mempertimbangkan semua interaksi sebelumnya. Karena clone mewarisi semuanya dari sesi induknya, termasuk perintah awal dan semua histori interaksi hingga titik cloning, susun penggunaan Anda untuk mewarisi hanya yang Anda butuhkan.

Lakukan:

  • Buat sesi dasar: Untuk menangani tugas yang tidak terkait secara efisien, buat sesi dasar yang hanya berisi petunjuk sistem Anda dan tidak berisi konteks percakapan sebelumnya.
  • Buat clone dasar pengukuran: Gunakan clone() pada sesi dasar tersebut untuk tugas baru guna menghemat overhead penguraian ulang petunjuk sistem. Dengan begitu, Anda dapat membuat percakapan paralel atau mereset tugas ke dasar pengukurannya.

Larangan:

  • Jangan menggunakan kembali sesi yang sama untuk tugas yang tidak terkait, dan hindari meng-clone sesi apa pun yang sudah berisi histori interaksi yang tidak diperlukan. Kedua pola ini dapat menyebabkan konteks sebelumnya yang tidak terkait mengganggu tugas Anda saat ini.
  • Jangan panggil create() berulang kali dengan petunjuk sistem yang sama. Gunakan pola cloning untuk mengoptimalkan performa.

Menghancurkan sesi yang tidak digunakan

Berlaku untuk: Semua API.

Lakukan: Panggil destroy() secara eksplisit pada sesi yang tidak lagi Anda perlukan, untuk mengosongkan memori saat fitur tidak lagi digunakan. Jika Anda menggunakan pola cloning, pertahankan sesi dasar dan hancurkan clone yang tidak lagi Anda perlukan.

Jangan: Membiarkan beberapa sesi besar tetap aktif. Setiap sesi menggunakan memori, yang menyebabkan penggunaan resource yang tidak perlu dan dapat menjadi masalah. Sesi akan otomatis dibersihkan oleh pembersih sampah memori, tetapi memanggil destroy() akan mengosongkan memori lebih cepat.

Merender respons streaming dengan aman dan efisien

Berlaku untuk: Semua API dengan dukungan streaming (Prompt, Summarizer, Writer, Rewriter, dan Translator).

Lakukan: Perlakukan semua output LLM sebagai konten yang tidak tepercaya. Bersihkan output gabungan secara penuh, bukan hanya sebagian, karena kode berbahaya dapat dibagi di seluruh update. Sebelum merender, gunakan Sanitizer API jika didukung. Untuk menghindari penurunan performa, gunakan parser Markdown streaming seperti streaming-markdown.

Jangan: Menetapkan innerHTML secara langsung pada setiap update potongan. Proses ini lambat, terutama dengan pemformatan yang kompleks seperti penyorotan sintaksis, dan rentan terhadap injeksi.

Mengoptimalkan input untuk kecepatan

Berlaku untuk: Semua API.

Lakukan: Hanya teruskan ke model apa yang benar-benar diperlukan. Hapus semua hal yang tidak relevan dengan tugas yang ada. Untuk set data besar, berikan ringkasan singkat dan pilihan kecil item yang relevan.

Jangan: Mengirim teks mentah yang belum diproses, metadata yang tidak perlu, tag HTML, atau daftar besar yang tidak difilter ke API. Latensi meningkat secara signifikan seiring dengan ukuran input, yang dapat membuat fitur AI tampak rusak di banyak perangkat.

Menggunakan output terstruktur untuk hasil yang dapat diprediksi

Berlaku untuk: Prompt API.

Lakukan: Jika Anda memerlukan model untuk menampilkan data dalam format tertentu, gunakan output terstruktur dengan memberikan kolom responseConstraint untuk menyediakan Skema JSON. Hal ini memastikan output dapat diprediksi dan mencegah Anda memerlukan pascapemrosesan yang kompleks atau penguraian manual.

Jangan: Hanya mengandalkan petunjuk bahasa alami (seperti "output only JSON"). Model mungkin menyertakan pengisi percakapan yang merusak parser Anda.

Memisahkan pembuatan dari batasan panjang

Berlaku untuk: Prompt API, karena ini adalah satu-satunya API yang mendukung skema output terstruktur.

Lakukan: Biarkan model menghasilkan responsnya secara alami, lalu gunakan logika sisi klien untuk memotong teks agar sesuai dengan UI Anda.

Jangan: Menerapkan batas karakter yang ketat seperti maxLength: 125 menggunakan skema output terstruktur. Jika respons model lebih panjang dari batas yang Anda tetapkan, model mungkin akan beralih ke token dengan kepadatan tinggi seperti bahasa asing atau emoji untuk memadatkan makna, sehingga menghasilkan output yang tidak masuk akal.

Selalu memberi tahu pengguna

Berlaku untuk: Semua API.

Lakukan: Bergantung pada kompleksitas dan perkiraan durasi tugas, gunakan animasi, isyarat visual, dan indikator progres untuk terus memberi tahu pengguna. Pendekatan yang optimal bergantung pada kasus penggunaan Anda dan panjang output API yang diharapkan. Beberapa ide yang bisa diterapkan:

  • Streaming untuk konten panjang: Untuk ringkasan atau chat, streaming membuat efek mesin ketik per token secara default. Hal ini dapat terasa alami dan memberikan masukan langsung.
  • Non-streaming untuk tugas singkat (atau tugas asinkron panjang): Untuk output singkat, misalnya, teks alternatif, non-streaming dapat membuat UI yang lebih rapi. Hal ini juga memberikan waktu untuk menyiapkan tugas AI berikutnya secara spekulatif saat tugas saat ini dirender. Pendekatan ini juga berfungsi untuk tugas asinkron atau latar belakang yang lebih lama. Jika pengguna tidak terhalang untuk melanjutkan perjalanannya karena output, tidak ada kebutuhan mendesak untuk menghasilkan output saat itu juga. Memberikan sinyal bahwa proses sedang berlangsung di UI.
  • Transisi visual untuk pembaruan: Saat menerjemahkan atau menulis ulang teks, gunakan animasi, misalnya, perubahan kata.

Jangan: Mengupdate UI tanpa isyarat visual.

Selaraskan dengan model mental pengguna tentang waktu dan pekerjaan

Berlaku untuk: Semua API.

Lakukan: Pertimbangkan penundaan buatan selama satu atau dua detik jika responsnya hampir instan. Paradoksnya, pengguna mungkin menganggap hasil lebih dapat dipercaya jika mereka melihat proses pembuatan yang sesuai dengan tingkat kesulitan tugas yang mereka rasakan. Gunakan animasi untuk memberi sinyal bahwa pemrosesan AI telah terjadi.

Jangan: Membuat pengguna terkejut dengan penggantian UI instan.

Memungkinkan pengguna menavigasi dan mengurungkan pengeditan AI dengan cepat

Berlaku untuk: Semua API.

Lakukan: Lengkapi UI Anda dengan stepper atau histori navigasi yang memungkinkan pengguna menjelajahi berbagai hasil dengan percaya diri, dan memungkinkan mereka mengurungkan pengeditan AI dengan cepat. Hal ini memastikan bahwa berbagai versi masih tersedia.

Jangan: Menimpa draf pengguna sebelumnya, atau hasil AI yang mungkin mereka sukai tanpa cara untuk kembali, mengurungkan, atau membandingkan versi.

Memberikan kontrol dan penggantian kepada pengguna

Berlaku untuk: Semua API.

Lakukan: Jadikan pengguna sebagai editor akhir dari semua konten yang dihasilkan. Berikan penggantian yang intuitif sehingga pengguna tetap memiliki kepemilikan penuh atas output akhir. API mungkin memberikan hasil yang salah.

Jangan: Memaksakan hasil buatan AI sebagai satu-satunya opsi.

Menyimpan hasil dalam cache untuk tugas berulang

Berlaku untuk: Semua API.

Lakukan: Terapkan cache hasil lokal (misalnya, menggunakan sessionStorage atau IndexedDB) untuk input atau kueri berulang. Normalisasi input dengan memangkas spasi kosong dan mengubahnya menjadi huruf kecil untuk meningkatkan cache ditemukan. Untuk input yang berat, misalnya, gambar, buat hash untuk digunakan sebagai kunci cache. Tetapkan time to live (TTL) yang konservatif untuk cache Anda (atau sajikan hasil yang di-cache sambil memperbaruinya di latar belakang). Izinkan pengguna memicu inferensi baru jika hasilnya tidak memuaskan.

Jangan: Jalankan ulang inferensi yang sama untuk kueri penelusuran berulang atau input data yang identik jika variabilitas tidak diinginkan, misalnya saat pengguna berpindah-pindah antara hasil penelusuran. Hal ini mengoptimalkan responsivitas dan penggunaan komputasi lokal yang efisien.

6. Strategi penggantian

Sebelum digunakan, periksa apakah objek LanguageModel tersedia dalam cakupan global:

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

Jika Prompt API tidak didukung atau pemeriksaan ketersediaan menampilkan 'unavailable', Anda harus melakukan penggantian dengan baik:

  • Pengalihan ke API Jarak Jauh: Alihkan permintaan deteksi ke endpoint server atau API cloud (seperti Vertex AI Gemini API).
  • Penggantian API Lokal: Alihkan permintaan deteksi ke endpoint lokal, misalnya, menggunakan Transformers.js.