مدل زبانی

‫Prompt API به توسعه‌دهندگان امکان می‌دهد تا بااستفاده از Gemini Nano، تکالیف پردازش زبان طبیعی را مستقیماً در مرورگر اجرا کنند. این رویکرد هوش مصنوعی داخلی حریم خصوصی کاربر را تضمین می‌کند، هزینه‌های سرور را کاهش می‌دهد، و عملکرد آفلاین را ممکن می‌سازد.

۱. شروع به کار و الزامات سخت‌افزاری

Prompt API درحال‌حاضر در Chrome از نسخه ۱۴۸ (رایانه) برای Windows،‏ macOS،‏ Linux، و Chromebook Plus دردسترس است.

پیش‌نیازهای سخت‌افزاری

• فضای ذخیره‌سازی: ۲۲ گیگابایت فضای خالی (برای نمایه و مدل اولیه).
• حافظه/واحد پردازش مرکزی: ۱۶ گیگابایت حافظه دسترسی تصادفی و ۴+ هسته واحد پردازش مرکزی.
• واحد پردازش گرافیکی: ۴ گیگابایت VRAM یا بیشتر (برای ورودی صوتی لازم است).
• شبکه: فقط برای بارگیری اولیه مدل لازم است.

مقداردهی اولیه میانای برنامه‌سازی کاربردی

قبل‌از شروع بارگیری، دردسترس بودن مدل را بررسی کنید:

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}%`);
            });
        },
    });
}

۲. قابلیت‌های اصلی پیام‌واره

نمونه‌های جلسه در این بخش برای اختصار session.destroy() را حذف می‌کنند. وقتی دیگر به جلسه نیازی نیست، همیشه session.destroy() را فراخوانی کنید تا حافظه دستگاه آزاد شود (بخش ۵ را ببینید).

خروجی پایه و جاری‌سازی‌شده

برای پاسخ‌های کوتاه، از prompt() استفاده کنید. برای محتوای طولانی‌تر، از promptStreaming() استفاده کنید تا واسط کاربر واکنش‌گراتری ارائه دهید.

اجباری: هرگز برونداد مدل را به innerHTML اختصاص ندهید. برونداد مدل غیرقابل‌اعتماد است و می‌تواند حاوی نشانه‌گذاری تزریق‌شده باشد. همیشه از textContent یا ضدعفونی‌کننده استفاده کنید.

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

ورودی چندحالته

‫Prompt API از ورودی‌های نوشتاری، صوتی، و تصویری (تصاویر، بوم، فریم‌های ویدیو) پشتیبانی می‌کند.

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') },
        ],
    },
]);

۳. مدیریت پیشرفته جلسه

جلسه‌ها به مدل اجازه می‌دهند تا بافت را در چندین تعامل حفظ کند.

بافت و سهمیه

هر جلسه حداکثر محدودیت توکن دارد. می‌توانید میزان استفاده را ازطریق session.contextUsage و session.contextWindow پایش کنید. اگر پنجره سرریز شود، قدیمی‌ترین پیام‌ها (به‌جز پیام‌واره سیستم) حذف می‌شوند.

جلسه‌های همسان‌سازی

کلون‌سازی برای شروع مکالمه‌های موازی که بافت اولیه یکسانی دارند (مثل شخصیت «سیستم») بدون راه‌اندازی مجدد کارآمد است.

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

درحال بازیابی جلسه‌های گذشته

درحالی‌که ویژگی «بازیابی» بومی درحال توسعه است، می‌توانید با وارد کردن سابقه قبلی در initialPrompts، جلسه را دوباره ایجاد کنید.

توجه: localStorage رمزگذاری‌نشده و پایدار است. سابقه مکالمه ذخیره‌شده ممکن است شامل اطلاعات شناساننده شخصی کاربر باشد — قبل‌از حفظ سابقه گپ، پیامدهای حریم خصوصی را درنظر بگیرید.

// || '[]' 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
});

۴. خروجی ساختاریافته با طرح JSON

برای جلوگیری از افزودن «پرگویی» توسط مدل (مثلاً «حتماً، این JSON شما است»)، از طرح JSON ازطریق فیلد responseConstraint استفاده کنید. این کار تضمین می‌کند که برونداد یک JSON معتبر است که می‌تواند بلافاصله تجزیه شود.

مثال: طبقه‌بندی احساسات

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

محدودیت‌ها و پیشوندها

با پیش‌پر کردن پاسخ دستیار بااستفاده از prefix: true می‌توانید مدل را بیشتر راهنمایی کنید.

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

۵. روال‌های مطلوب و ایمنی

• پاک‌سازی منابع: همیشه وقتی مکالمه‌ای تمام می‌شود، session.destroy() را فراخوانی کنید تا حافظه آزاد شود.
• ایمنی برونداد: برونداد مدل غیرقابل‌اعتماد است. همیشه نتایج را در textContent بنویسید، نه innerHTML، تا از تزریق XSS از برونداد مدل مخرب جلوگیری شود.
• اگر لازم است HTML محدود را مجاز کنید، از یک پاک‌کننده مانند Sanitizer API بومی یا DOMPurify استفاده کنید.
• لغو کردن Tasks: از AbortController استفاده کنید تا به کاربران اجازه دهید تولیدهای طولانی‌مدت را متوقف کنند. ‫signal را به prompt() یا promptStreaming() بدهید، نه به LanguageModel.create().
• امنیت: از «خط‌مشی‌های اجازه» برای کنترل دسترسی در iframe استفاده کنید: <iframe src="..." allow="language-model"></iframe>.
• طراحی: People + AI Guidebook را مرور کنید تا از پیاده‌سازی مسئولانه هوش مصنوعی مطمئن شوید.

با ترکیب خروجی‌های ساختاریافته با مدیریت قوی جلسه، توسعه‌دهندگان می‌توانند برنامه‌های هوش مصنوعی پیچیده و باحفظ وضعیت بسازند که کاملاً در دستگاه کاربر اجرا می‌شوند.

بایدها و نبایدها

برای مشاهده فهرست کامل و دقیق بایدها و نبایدها، به https://developer.chrome.com/docs/ai/built-in-ai-dos-donts.md.txt مراجعه کنید. اصل مطلب در زیر آمده است:

مدل را در زمان مناسبی آماده کنید

برای همه میاناهای برنامه‌سازی کاربردی، مثلاً «خلاصه‌ساز»، «مترجم»، و «نویسنده» اعمال می‌شود.

باید: به‌محض اینکه قصد کاربر برای استفاده از ویژگی هوش مصنوعی به‌وضوح مشخص شد، جلسه را مقداردهی اولیه کنید، برای مثال، وقتی کاربر به سطح ابزارهای هوش مصنوعی مربوطه می‌رود، روی فضای کاری هوش مصنوعی نگه می‌دارد، یا با میانای کاربری اطراف ویژگی تعامل برقرار می‌کند. پیش‌گرم کردن جلسه به مدل اجازه می‌دهد تا درحین اینکه کاربر درحال راه‌اندازی تکلیف خود است، به‌آرامی در پس‌زمینه در حافظه بار شود و تأخیر اجتناب‌پذیر شروع سرد را ازبین ببرد. سعی کنید یک قدم جلوتر باشید و به‌محض شروع رندر کردن نتیجه فعلی، تکلیف هوش مصنوعی بعدی را که احتمالاً انجام خواهد شد شروع کنید، مثلاً اگر ویژگی برای استفاده تکراری طراحی شده است.

نباید: مگر در موارد ضروری، برای مقداردهی اولیه جلسه منتظر نمانید تا کاربر روی «تولید» کلیک کند. این امر منجر به تأخیر در شروع سرد می‌شود، زیرا مدل ابتدا باید در حافظه بار شود و خط لوله اجرایی خود را آماده کند.

تنظیم پیام‌واره‌های اولیه درطول ساختن

قابل‌اعمال برای: Prompt API.

بایدها: دستورالعمل‌های سیستم را درطول مقداردهی اولیه جلسه ارائه دهید تا سرعت اولین پیام‌واره بهبود یابد.

نباید: با جلسه خالی شروع کنید و دستورالعمل‌های سیستم را به‌عنوان بخشی از اولین تماس prompt() ارسال کنید. این کار تأخیر را افزایش می‌دهد زیرا مدل را مجبور می‌کند آن دستورالعمل‌ها را در آخرین لحظه پردازش کند.

کلون کردن جلسه‌ها برای تکالیف تکراری

قابل‌اعمال برای: Prompt API.

برای Prompt API، هر جلسه زمینه مکالمه را ردیابی می‌کند و همه تعاملات قبلی را درنظر می‌گیرد. چون کلون همه چیز را از جلسه اصلی خود به ارث می‌برد، ازجمله پیام‌واره‌های اولیه و کل سابقه تعامل تا زمان کلون‌سازی، استفاده خود را به‌گونه‌ای ساختاردهی کنید که فقط آنچه را نیاز دارید به ارث ببرد.

بایدها:

• ایجاد جلسه پایه: برای رسیدگی کارآمد به تکالیف غیرمرتبط، جلسه پایه‌ای ایجاد کنید که فقط حاوی دستورالعمل‌های سیستم شما باشد و هیچ بافت مکالمه قبلی نداشته باشد.
• شبیه‌سازی خط مبنا: برای کارهای جدید از clone() در آن جلسه پایه استفاده کنید تا از سربار تجزیه مجدد دستورالعمل‌های سیستم جلوگیری شود. این کار به شما امکان می‌دهد مکالمه‌های موازی ایجاد کنید یا تکلیف را به حالت پایه آن بازنشانی کنید.

کارهایی که نباید انجام دهید:

• از یک جلسه برای کارهای نامرتبط استفاده نکنید و از شبیه‌سازی جلسه‌ای که قبلاً حاوی سابقه تعامل غیرضروری است خودداری کنید. هر دو الگو می‌توانند باعث شوند بافت قبلی نامرتبط با تکلیف فعلی شما تداخل پیدا کند.
• create() را به‌طور مکرر با دستورالعمل‌های سیستم یکسان فراخوانی نکنید. برای بهینه‌سازی عملکرد، از الگوی شبیه‌سازی استفاده کنید.

ازبین بردن جلسه‌های استفاده‌نشده

اعمال می‌شود بر: همه میاناهای برنامه‌سازی کاربردی.

باید: destroy() را به‌طور صریح در جلسه‌هایی که دیگر به آن‌ها نیاز ندارید فراخوانی کنید تا وقتی ویژگی دیگر درحال استفاده نیست، حافظه آزاد شود. اگر از الگوی شبیه‌سازی استفاده می‌کنید، جلسه پایه را نگه دارید و شبیه‌سازی‌هایی را که دیگر نیاز ندارید ازبین ببرید.

نباید: چندین جلسه بزرگ را فعال نگه دارید. هر جلسه حافظه مصرف می‌کند، که باعث استفاده غیرضروری از منابع می‌شود و ممکن است مشکل‌ساز شود. جلسه‌ها به‌طور طبیعی توسط زباله‌روب پاک‌سازی می‌شوند، اما فراخوانی destroy() حافظه را سریع‌تر آزاد می‌کند.

ارائه پاسخ‌های جاری‌سازی به‌صورت ایمن و کارآمد

قابل‌اعمال برای: همه میاناهای برنامه‌سازی کاربردی با پشتیبانی از جاری‌سازی (Prompt،‏ Summarizer،‏ Writer،‏ Rewriter، و Translator).

باید: با همه بروندادهای «مدل زبانی بزرگ» به‌عنوان محتوای غیرقابل‌اعتماد رفتار کنید. کل خروجی ترکیبی را پاک‌سازی کنید، نه فقط بخش‌هایی از آن را، زیرا کد مخرب ممکن است در به‌روزرسانی‌های مختلف تقسیم شده باشد. قبل‌از رندر کردن، از Sanitizer API در جایی که پشتیبانی می‌شود استفاده کنید. برای جلوگیری از کاهش عملکرد، از تجزیه‌کننده Markdown جاری‌سازی مثل streaming-markdown استفاده کنید.

نباید: innerHTML را مستقیماً در هر به‌روزرسانی تکه تنظیم کنید. این روش کند است، به‌ویژه با قالب‌بندی‌های پیچیده مانند برجسته‌سازی نحو، و دربرابر تزریق آسیب‌پذیر است.

بهینه‌سازی ورودی برای سرعت

اعمال می‌شود بر: همه میاناهای برنامه‌سازی کاربردی.

باید: فقط آنچه را که کاملاً ضروری است به مدل منتقل کنید. هر چیزی را که به تکلیف موردنظر مربوط نیست حذف کنید. برای مجموعه داده‌های بزرگ، نمای کلی کوتاهی ارائه دهید و انتخاب کوچکی از موارد مربوط را ارائه دهید.

نباید: نوشتار خام پردازش‌نشده، فراداده غیرضروری، برچسب‌های HTML، یا فهرست‌های بزرگ فیلترنشده را به میاناهای برنامه‌سازی کاربردی ارسال کنید. تأخیر با اندازه ورودی به‌طور قابل‌توجهی افزایش می‌یابد، که می‌تواند باعث شود ویژگی هوش مصنوعی در بسیاری از دستگاه‌ها خراب به‌نظر برسد.

استفاده کردن از برونداد ساختاریافته برای نتایج قابل‌پیش‌بینی

قابل‌اعمال برای: Prompt API.

بایدها: وقتی لازم است مدل داده‌ها را در قالب خاصی برگرداند، از برونداد ساختاریافته استفاده کنید و با ارائه فیلد responseConstraint، «طرح JSON» را ارائه دهید. این کار باعث می‌شود خروجی قابل‌پیش‌بینی باشد و شما را از نیاز به پس‌پردازش پیچیده یا تجزیه دستی بی‌نیاز می‌کند.

نباید: فقط به دستورالعمل‌های زبان طبیعی (مثل «فقط JSON برونداد شود») اتکا کنید. مدل‌ها ممکن است شامل پرکننده‌های مکالمه‌ای باشند که تجزیه‌کننده شما را خراب می‌کند.

جدا کردن تولید از محدودیت‌های طول

برای: Prompt API اعمال می‌شود، زیرا تنها میانای برنامه‌سازی کاربردی است که از طرح‌واره‌های خروجی ساختاریافته پشتیبانی می‌کند.

باید: اجازه دهید مدل پاسخ خود را به‌طور طبیعی تولید کند، و سپس از منطق سمت کارخواه برای کوتاه کردن نوشتار استفاده کنید تا با واسط کاربر شما مطابقت داشته باشد.

نباید: محدودیت‌های سخت‌گیرانه برای تعداد نویسه‌ها اعمال کنید، مثلاً بااستفاده از maxLength: 125 طرح‌واره‌های برونداد ساختاریافته. وقتی پاسخ مدل طولانی‌تر از حدی باشد که تنظیم کرده‌اید، مدل ممکن است برای فشرده‌سازی معنی به نشانه‌های با تراکم بالا مثل زبان‌های خارجی یا اموجی تغییر کند که این امر منجر به خروجی بی‌معنی می‌شود.

مطلع نگه داشتن کاربر

اعمال می‌شود بر: همه میاناهای برنامه‌سازی کاربردی.

انجام دهید: بسته به پیچیدگی و مدت‌زمان موردانتظار برای تکمیل تکلیف، از پویانمایی، نشانه‌های دیداری، و نشانگرهای پیشرفت استفاده کنید تا کاربر را مطلع نگه دارید. رویکرد بهینه به مورد استفاده شما و طول موردانتظار خروجی میانای برنامه‌سازی کاربردی بستگی دارد. چند ایده:

• جاری‌سازی برای محتوای طولانی: برای خلاصه‌ها یا گپ، جاری‌سازی به‌طور پیش‌فرض جلوه ماشین‌تحریر را برای هر نمانه ایجاد می‌کند. این کار می‌تواند طبیعی به‌نظر برسد و بازخورد فوری ارائه دهد.
• غیرجاری‌سازی برای تکالیف کوتاه (یا تکالیف ناهمگام طولانی): برای بروندادهای کوتاه، مثلاً نوشتار جایگزین، غیرجاری‌سازی می‌تواند واسط کاربری صیقل‌خورده‌تری ایجاد کند. همچنین زمان لازم را برای آماده‌سازی احتمالی تکلیف هوش مصنوعی بعدی درحین رندر شدن تکلیف فعلی فراهم می‌کند. این رویکرد برای کارهای پس‌زمینه یا ناهمگام طولانی‌تر نیز کار می‌کند. اگر کاربر برای ادامه سفر خود در خروجی مسدود نشده باشد، نیازی فوری به تولید خروجی در همان لحظه وجود ندارد. در واسط کاربر نشان دهید که فرایند درحال انجام است.
• گذار دیداری برای به‌روزرسانی‌ها: هنگام ترجمه یا بازنویسی نوشتار، از پویانمایی استفاده کنید، مثلاً دگرگونی واژه.

نباید: واسط کاربر را بدون نشانه‌های دیداری به‌روز کنید.

با مدل ذهنی کاربر از زمان و کار همسو باشد

اعمال می‌شود بر: همه میاناهای برنامه‌سازی کاربردی.

بایدها: اگر پاسخ تقریباً فوری است، تأخیر مصنوعی یک یا دو ثانیه‌ای را درنظر بگیرید. به‌طور متناقض، کاربران ممکن است نتایج را زمانی قابل‌اعتمادتر بدانند که فرایند تولید را با دشواری درک‌شده از تکلیف همسو ببینند. از پویانمایی‌ها برای نشان دادن اینکه فرایند هوش مصنوعی رخ داده است استفاده کنید.

نباید: کاربران را با جایگزینی فوری میانای کاربر غافلگیر کنید.

به کاربران اجازه می‌دهد به‌سرعت پیمایش کنند و ویرایش‌های هوش مصنوعی را واگرد کنند

اعمال می‌شود بر: همه میاناهای برنامه‌سازی کاربردی.

باید: واسط کاربر را به یک گام‌شمار یا سابقه پیمایش مجهز کنید تا کاربران بتوانند با اطمینان نتایج مختلف را کاوش کنند و به آن‌ها اجازه دهید ویرایش‌های هوش مصنوعی را به‌سرعت واگرد کنند. این کار تضمین می‌کند که نسخه‌های مختلف همچنان به‌راحتی دردسترس باشند.

نباید: پیش‌نویس قبلی کاربر یا نتیجه هوش مصنوعی را که ممکن است کاربر پسندیده باشد بدون ارائه راهی برای برگشتن، واگرداندن، یا مقایسه نسخه‌ها رونویسی کنید.

تقویت کنترل و لغو تنظیمات توسط کاربر

اعمال می‌شود بر: همه میاناهای برنامه‌سازی کاربردی.

باید: کاربر را ویرایشگر نهایی همه محتواهای تولیدشده قرار دهید. امکان لغو کردن بصری را فراهم کنید تا کاربر مالکیت کامل خروجی نهایی را حفظ کند. ممکن است میاناهای برنامه‌سازی کاربردی نتایج نادرستی تولید کنند.

نباید: نتیجه تولیدشده با هوش مصنوعی را به‌عنوان تنها گزینه تحمیل کنید.

نتایج حافظه پنهان برای تکالیف تکراری

اعمال می‌شود بر: همه میاناهای برنامه‌سازی کاربردی.

باید: برای ورودی‌ها یا پُرسمان‌های تکراری، حافظه نهان نتایج محلی (مثلاً بااستفاده از sessionStorage یا IndexedDB) پیاده‌سازی کنید. با حذف کردن فاصله سفید و تبدیل کردن به حروف کوچک، ورودی را نرمال‌سازی کنید تا بازدیدهای حافظه پنهان افزایش یابد. برای ورودی‌های سنگین، مثلاً تصاویر، درهم‌سازی تولید کنید تا به‌عنوان کلید حافظه نهان استفاده شود. زمان بقای (TTL) محافظه‌کارانه‌ای برای حافظه نهان خود تنظیم کنید (یا نتایج ذخیره‌شده در حافظه نهان را هنگام به‌روزرسانی در پس‌زمینه ارائه دهید). اگر نتیجه رضایت‌بخش نبود، به کاربر اجازه دهید استنتاج جدیدی را راه‌اندازی کند.

نباید: برای پُرسمان جستجوی تکراری یا ورودی داده یکسان که تغییرپذیری در آن مطلوب نیست، همان استنتاج را دوباره اجرا کنید، مثلاً وقتی کاربر بین نتایج جستجو عقب و جلو می‌رود. این کار باعث بهینه‌سازی پاسخ‌گویی و استفاده کارآمد از محاسبات محلی می‌شود.

‫۶. راهبردهای جایگزین

قبل‌از استفاده، بررسی کنید که آیا شیء LanguageModel در دامنه سراسری دردسترس است یا نه:

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

اگر Prompt API پشتیبانی نمی‌شود یا بررسی‌های دردسترس بودن نتیجه «unavailable» (دردسترس نیست) را برمی‌گرداند، باید به‌طور مناسب به حالت قبلی برگردید:

• جایگزین میانای برنامه‌سازی کاربردی ازراه‌دور: درخواست تشخیص را به نقطه پایانی سرور یا میانای برنامه‌سازی کاربردی ابری (مانند Vertex AI Gemini API) هدایت کنید.
• جایگزین API محلی: درخواست تشخیص را به نقطه پایانی محلی هدایت کنید، برای مثال، بااستفاده از Transformers.js.