ממשקי AI API מובנים: מה לעשות ומה לא לעשות

תאריך פרסום: 30 באפריל 2026

עם AI מובנה, האתר או אפליקציית האינטרנט שלכם יכולים לבצע משימות מבוססות-AI בלי שתצטרכו לפרוס, לנהל או לארח מודלים בעצמכם. יכול להיות שיהיה לכם קשה לעבור מהדגמה לתכונה שמוכנה לייצור. במסמך הזה מפורטים שיקולים טכניים ושיקולים שקשורים לחוויית המשתמש, כדי לעזור לכם להימנע מטעויות נפוצות.

רוב ההנחיות רלוונטיות לכל ממשקי ה-API המובנים של AI. החריגים מצוינים.

הכנת המודל בזמן סביר

מה כן לעשות: להפעיל את הסשן ברגע שברור שהמשתמש מתכוון להשתמש בתכונת ה-AI. למשל, כשהמשתמש נכנס לממשק רלוונטי של כלי AI, מעביר את העכבר מעל סביבת עבודה של AI או יוצר אינטראקציה עם ממשק המשתמש שמסביב לתכונה. הכנה מראש של הסשן מאפשרת למודל להיטען לזיכרון בשקט ברקע בזמן שהמשתמש מגדיר את המשימה שלו, וכך למנוע זמן אחזור מיותר של הפעלה קרה. נסו להיות צעד אחד קדימה ולהתחיל את משימת ה-AI הבאה הסבירה ביותר ברגע שאתם מתחילים לעבד את התוצאה הנוכחית, למשל, אם התכונה מיועדת לשימוש איטרטיבי.

מה לא לעשות: אלא אם זה הכרחי, אל תחכו שהמשתמש ילחץ על "יצירה" כדי להתחיל את הסשן. זה מוביל לעיכוב בהפעלה במצב התחלתי, כי קודם צריך לטעון את המודל לזיכרון ולהכין את צינור עיבוד הנתונים שלו.

הגדרת הנחיות ראשוניות במהלך היצירה

ההנחיות הבאות רלוונטיות ל-Prompt API.

מומלץ: לספק הוראות מערכת במהלך אתחול הסשן כדי לשפר את מהירות ההנחיה הראשונה.

מה לא לעשות: להתחיל סשן ריק ולשלוח הוראות מערכת כחלק מהקריאה הראשונה ל-prompt(). זה מאריך את זמן האחזור כי המודל נאלץ לעבד את ההוראות האלה ברגע האחרון.

// ✅ DO: Create the session as early as possible (warm 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.'
    }
  ]
});

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

שכפול סשנים למשימות שחוזרות על עצמן

ההנחיות הבאות רלוונטיות ל-Prompt API.

ב-Prompt API, כל סשן עוקב אחרי ההקשר של השיחה, ומביא בחשבון את כל האינטראקציות הקודמות. כשמשכפלים סשן, כל מה שקשור לסשן המקורי עובר בירושה, כולל ההנחיות הראשוניות וכל היסטוריית האינטראקציות עד לנקודת השכפול. לכן, כדאי לבנות את השימוש כך שיעבור בירושה בלבד מה שצריך.

מומלץ:

  • יצירת סשן בסיסי: כדי לטפל ביעילות במשימות לא קשורות, צרו סשן בסיסי שמכיל רק את ההוראות למערכת, בלי הקשר של שיחות קודמות.
  • שכפול הבסיס: משתמשים ב-clone() בסשן הבסיסי הזה למשימות חדשות כדי לחסוך את התקורה של ניתוח מחדש של הוראות המערכת. כך אפשר ליצור שיחות מקבילות או לאפס משימה למצב הבסיסי שלה.

מה אסור לעשות:

  • אל תשתמשו באותו סשן למשימות לא קשורות, ואל תשכפלו סשן שכבר מכיל היסטוריית אינטראקציות מיותרת. שני הדפוסים האלה יכולים לגרום להקשר קודם שלא קשור למשימה הנוכחית להפריע לה.
  • אל תשלחו ל-create() שוב ושוב את אותן הוראות מערכת. כדי לשפר את הביצועים, השתמשו בתבנית השכפול.
// ✅ 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...");

השמדת סשנים שלא בשימוש

מה כן לעשות: להפעיל באופן מפורש את destroy() בסשנים שכבר לא צריך, כדי לפנות זיכרון כשלא משתמשים יותר בתכונה. אם אתם משתמשים בתבנית שכפול, שמרו את הסשן הבסיסי והשמידו את השכפולים שאתם לא צריכים יותר.

מה לא לעשות: להשאיר כמה פגישות גדולות פעילות. כל סשן צורך זיכרון, מה שיוצר שימוש מיותר במשאבים ועלול להפוך לבעיה. הסשנים ינוקו באופן טבעי על ידי אוסף האשפה, אבל קריאה ל-destroy() מפנה זיכרון מהר יותר.

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

עיבוד תשובות בסטרימינג בצורה בטוחה ויעילה

ההנחיות האלה רלוונטיות לממשקי API עם תמיכה בסטרימינג (Prompt,‏ Summarizer,‏ Writer,‏ Rewriter ו-Translator).

מה כדאי לעשות: להתייחס לכל פלט של LLM כתוכן לא מהימן. חשוב להסיר תוכן זדוני או רגיש מהפלט המשולב המלא, ולא רק מחלקים ממנו, כי קוד זדוני יכול להיות מפוצל בין עדכונים. לפני העיבוד, משתמשים ב-Sanitizer API אם הוא נתמך. כדי למנוע ירידה בביצועים, השתמשו במנתח Markdown בסטרימינג כמו streaming-markdown.

לא מומלץ: להגדיר את innerHTML ישירות בכל עדכון של מקטע. התהליך הזה איטי, במיוחד עם עיצוב מורכב כמו הדגשת תחביר, והוא חשוף להזרקה.

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

אופטימיזציה של הקלט למהירות

מה כדאי לעשות: להעביר למודל רק את מה שבאמת נחוץ. הסירו כל מה שלא רלוונטי למשימה. אם יש לכם קבוצות נתונים גדולות, תנו סקירה כללית קצרה ומבחר קטן של פריטים רלוונטיים.

מה לא לעשות: לשלוח לממשקי ה-API טקסט גולמי שלא עבר עיבוד, מטא-נתונים מיותרים, תגי HTML או רשימות גדולות שלא עברו סינון. זמן האחזור גדל באופן משמעותי ככל שגודל הקלט גדל, מה שעלול לגרום לתכונת ה-AI להיראות לא תקינה במכשירים רבים.

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

שימוש בפלט מובנה כדי לקבל תוצאות צפויות

ההנחיות הבאות רלוונטיות ל-Prompt API.

מה כן לעשות: אם אתם צריכים שהמודל יחזיר נתונים בפורמט ספציפי, השתמשו בפלט מובנה על ידי הוספת שדה responseConstraint כדי לספק סכימת JSON. כך הפלט יהיה צפוי ולא תצטרכו לבצע עיבוד מורכב או ניתוח ידני.

מה לא לעשות: להסתמך רק על הוראות בשפה טבעית (כמו "פלט רק ב-JSON"). המודלים עשויים לכלול מילות קישור שמשבשות את המנתח.

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

הפרדה בין יצירת התוכן לבין מגבלות האורך

ההנחיות הבאות רלוונטיות ל-Prompt API.

מה כן לעשות: מאפשרים למודל ליצור את התשובה באופן טבעי, ואז משתמשים בלוגיקה בצד הלקוח כדי לחתוך את הטקסט כך שיתאים לממשק המשתמש.

מה לא לעשות: לאכוף מגבלות תווים מחמירות כמו maxLength: 125 באמצעות סכימות פלט מובנות. אם התשובה של המודל ארוכה מהמגבלה שהגדרתם, יכול להיות שהמודל יעבור לטוקנים בצפיפות גבוהה, כמו שפות זרות או אמוג'י, כדי לדחוס את המשמעות, וכתוצאה מכך הפלט יהיה חסר משמעות.

/*  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.");

עדכון המשתמשים

מה כן לעשות: בהתאם למורכבות ולמשך הזמן הצפוי של המשימה, כדאי להשתמש באנימציות, בסימנים חזותיים ובאינדיקטורים של התקדמות כדי לעדכן את המשתמש. הגישה האופטימלית תלויה בתרחיש לדוגמה ובאורך הצפוי של הפלט מה-API. הנה כמה רעיונות:

  • סטרימינג של תוכן ארוך: בסיכומים או בשיחות, הסטרימינג יוצר אפקט של מכונת כתיבה לכל אסימון כברירת מחדל. זה יכול להרגיש טבעי ולספק משוב מיידי.
  • בלי סטרימינג למשימות קצרות (או למשימות אסינכרוניות ארוכות): בפלט קצר, כמו טקסט חלופי, אפשר ליצור ממשק משתמש מלוטש יותר בלי סטרימינג. הוא גם נותן זמן להכין באופן ספקולטיבי את משימת ה-AI הבאה בזמן שהמשימה הנוכחית עוברת רינדור. הגישה הזו מתאימה גם למשימות אסינכרוניות או למשימות ברקע שנמשכות זמן רב יותר. אם המשתמש לא חסום בפלט כדי להמשיך בתהליך, אין צורך דחוף להפיק את הפלט בזמן אמת. מציינים בממשק המשתמש שהתהליך מתבצע.
  • מעברים חזותיים לעדכונים: כשמתרגמים או משכתבים טקסט, משתמשים באנימציות, למשל שינוי צורה של מילים.

מה לא לעשות: לעדכן את ממשק המשתמש בלי רמזים חזותיים.

התאמה למודל המנטלי של המשתמש לגבי זמן ועבודה

מומלץ: אם התשובה מתקבלת כמעט באופן מיידי, כדאי להוסיף השהיה מלאכותית של שנייה או שתיים. באופן פרדוקסלי, יכול להיות שהמשתמשים יתפסו את התוצאות כאמינות יותר אם תהליך היצירה יתאים לרמת הקושי שהם מייחסים למשימה. השתמשו באנימציות כדי לסמן שהתרחש עיבוד באמצעות AI.

מה לא לעשות: להפתיע את המשתמשים עם החלפות מיידיות של ממשק המשתמש.

המשתמשים יכולים לנווט במהירות ולבטל עריכות שבוצעו באמצעות AI

מה כדאי לעשות: הוסיפו לממשק המשתמש שלכם רכיב של שלבים או היסטוריית ניווט שמאפשרים למשתמשים לבחון תוצאות שונות בביטחון, ולבטל במהירות עריכות של ה-AI. כך אפשר להבטיח שגרסאות שונות עדיין יהיו זמינות.

מה לא לעשות: אל תחליפו את הטיוטה הקודמת של המשתמש או תוצאה של AI שהוא אהב בלי לתת לו אפשרות לחזור אחורה, לבטל את הפעולה או להשוות בין הגרסאות.

רכיב בממשק המשתמש של Stepper שמציג את היסטוריית הניווט.
תבנית ממשק משתמש: דחייה או קבלה של הצעה (Google Docs)
כפתור לביטול כל השינויים של הסוכן בממשק המשתמש של Google Antigravity.
תבנית ממשק משתמש: ביטול כל העריכות של הסוכן (Google Antigravity)
כפתורי דחייה או קבלה של הצעה ב-Google Docs.
תבנית ממשק משתמש: Stepper (הדגמה של טקסט חלופי)

המשתמשים יכולים לשלוט בהגדרות ולשנות אותן

מה כן לעשות: המשתמש צריך להיות העורך הסופי של כל התוכן שנוצר. לספק אפשרויות אינטואיטיביות לשינוי הפלט, כדי שהמשתמשים יוכלו לשלוט באופן מלא בתוצאה הסופית. יכול להיות שהתוצאות של ממשקי ה-API לא יהיו מדויקות.

מה לא לעשות: לאלץ תוצאה שנוצרה על ידי AI כאפשרות היחידה.

שמירת תוצאות במטמון למשימות חוזרות

מה כדאי לעשות: להטמיע מטמון של תוצאות מקומיות (לדוגמה, באמצעות sessionStorage או IndexedDB) לקלטים או לשאילתות שחוזרים על עצמם. כדי להגדיל את מספר המציאות במטמון, כדאי לנרמל את הקלט על ידי חיתוך רווחים לבנים והמרה לאותיות קטנות. בקלט כבד, כמו תמונות, צריך ליצור גיבוב (hash) שישמש כמפתח מטמון. הגדירו זמן חיים (TTL) שמרני למטמון (או הציגו תוצאות מהמטמון בזמן שאתם מעדכנים אותן ברקע). אם התוצאה לא מספקת, תנו למשתמשים להפעיל הסקה חדשה.

מה לא לעשות: להריץ מחדש את אותה הסקת מסקנות בשאילתת חיפוש חוזרת או בקלט נתונים זהה, במקרים שבהם לא רוצים שיהיה שינוי. לדוגמה, כשמשתמש עובר קדימה ואחורה בין תוצאות החיפוש. כך אפשר לשפר את הרספונסיביות ולהשתמש ביעילות במשאבי המחשוב המקומיים.

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