רווחים:
- יכול לתאר את המבנה הבסיסי של בקשת API של LLM (נקודת קצה, מודל, הודעות, max_tokens)
- מבין את ההבדל בין תפקידי מערכת, משתמש ועוזר והיסטוריית שיחות חסרת מצב
- יכול לקרוא ולפרש שדות (חסימות תוכן, סיבה_עצירה, שימוש) של התגובה שהוחזרה
במודולים קודמים, השתמשנו בבינה מלאכותית מחלון צ'אט. אבל אם אתה רוצה להטמיע בינה מלאכותית במוצר, אוטומציה או זרימת עבודה משלך, ממשק צ'אט לא יחתוך את זה; אתה צריך להתחבר למודל באופן פרוגרמטי, כלומר עם קוד או כלי אוטומציה. שמו של הגשר הזה הוא API (ממשק תכנות יישומים, החוזה שמאפשר לשתי תוכנות לדבר עם כללים מסוימים). כשתסיים יחידה זו, תדע מה מהווה בקשת API של LLM (Large Language Model), מה עושים תפקידי הודעה וכיצד לקרוא את התגובה. זהו הבסיס עליו ייבנה שאר המודול.
איך עובד ה-API?
הזרימה הבסיסית ב-API היא כזו: אתה שולח בקשה בפורמט מסוים; השרת מחזיר תגובה בפורמט מסוים. ב-LLM, זו בדרך כלל קריאת HTTP (HTTP: פרוטוקול סטנדרטי להעברת בקשה-תגובה באינטרנט) לכתובת בודדת (נקודת קצה, הכתובת הקבועה בשרת שמטפלת בבקשה שלך). לדוגמה, ב-API להעברת הודעות, כל הבקשות עוברות לכתובת בודדת ומועברות בגוף כ-JSON (סימון אובייקט JavaScript - פורמט טקסט המורכב מזוגות מפתח/ערך שניתן לקרוא גם על ידי בני אדם וגם על ידי מכונות).
בבקשה, אתה מציין לפחות את שלושת הדברים הבאים:
- דגם: באיזה דגם תשתמשו (למשל דגם מהיר וזול או דגם חזק).
- max_tokens: המספר המרבי של אסימונים (היחידה הקטנה ביותר בה מעובד הטקסט, שיעובדו בפירוט ביחידה הבאה) שהדגם יכול לייצר; כלומר מגבלת תפוקה.
- הודעות: רשימת ההודעות המרכיבות את השיחה.
שלב אחר שלב: כיצד להגדיר בקשה
- הכן את נקודת הקצה ואת האישורים. אתה מוסיף את מפתח ה-API שלך (המחרוזת הסודית שמוכיחה את זהותך) לבקשה בכותרת. לעולם לא תטמיע את המפתח בקוד; אנו נכסה אחסון בטוח ביחידה 9.
- בחר את הדגם ואת מגבלת הפלט. דגם קל משקל + max_tokens קטנים למשימה פשוטה; דגם חזק + מגבלה גדולה יותר למשימה מורכבת.
- הגדר את רשימת ההודעות. List the system instruction, user message, and past rounds (if any).
- שלח את הבקשה ונתח את התגובה. קרא את תוכן הטקסט, עצור סיבה ושימוש באסימונים מה-JSON שהוחזר.
תפקידי הודעה: מערכת, משתמש, עוזר
שיחה מורכבת מהודעות המסודרות ברצף, ולכל הודעה יש תפקיד. התפקיד קובע כיצד המודל מתייחס לטקסט הזה.
תפקיד
מי כותב
מטרה
מערכת
מפתח/מפעיל
הנחיות, אישיות וחוקים קבועים החלים לאורך כל השיחה
משתמש
משתמש קצה
השאלה או הקלט הנוכחיים של המשתמש
עוזר
דגם
תגובה שהופקה על ידי המודל (ותגובות קודמות)
תפקיד המערכת זמין כשדה מערכת נפרד בגוף הבקשה ברוב הספקים; המשתמש והעוזר מופיעים ברצף ברשימת ההודעות. Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.
{ "model": "claude-opus-4-8", "max_tokens": 1024, "system": "אתה עוזר תמיכה ארגוני. תן תגובה קצרה, רשמית ומאומתת. אל תמציא מידע שאינך בטוח לגביו.", "messages": [ { "role": "user", "content": "איך אני מתחיל את תהליך ההחזרה שלי?" } ]}
הדיבור הוא חסר מדינה
הנה התפיסה השגויה הנפוצה ביותר: קריאות LLM API הן חסרות מדינה - השרת לא שומר זיכרון בין שתי בקשות. הדגם לא זוכר את הבקשה הקודמת שלך. אם אתה מגדיר צ'אט מרובה סיבובים, תצטרך לשלוח שוב סיבובים קודמים עם כל בקשה חדשה. ה"זיכרון" של הדגם מורכב מרשימת הודעות ששלחת.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "שלום, שמי דניז." }, { "role": "assistant", "content": "שלום דניז, איך אני יכול לעזור לך?" }, { "role": "user", "content": "אמרתי עכשיו את השם שלי, אתה זוכר?" } ]}
תשובה נכונה להודעה השלישית תלויה בכך שתשלח את שתי ההודעות הקודמות. אם לא תשלח אותו, הדוגמנית לא תדע "ים" ויענה לא נכון. זה גם משפיע ישירות על העלות: ככל שהשיחה ארוכה יותר, הרשימה גדולה יותר, כל בקשה צורכת יותר אסימונים.
טיפ: בשיחות ארוכות, סיכום והעברה של סבבים ישנים (סיכום + סבבים אחרונים) במקום שליחת ההיסטוריה כולה מוזיל עלויות ומשמר את חלון ההקשר. נעמיק זאת ביחידות 6 ו-11.
קרא את התשובה
כאשר המודל מחזיר תגובה, אתה מקבל אובייקט מובנה, לא טקסט רגיל. אזורים אופייניים:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "כדי ליזום החזרה, עבור לדף 'ההזמנות שלי' בחשבונך..." } ], "stop_reason", "stop_reason": "inage_tokens": "inage_tokens 47, "output_tokens": 88 }}
- תוכן: התגובה עצמה; זוהי רשימה של בלוקים של תוכן. שדה הטקסט של בלוק הטקסט הוא התשובה בפועל.
- stop_reason: מדוע הדגם נעצר. end_turn = סוף טבעי; max_tokens = תקוע במגבלת הפלט (ייתכן שהתגובה לא מלאה); סירוב = סירב מטעמי ביטחון. הקוד שלך צריך תמיד להסתכל קודם כל על stop_reason.
- שימוש: קלט ופלט מספרי אסימון. זה הבסיס למעקב אחר עלות ומגבלה.
שימו לב: אם stop_reason הוא max_tokens, התגובה לא הושלמה. התייחסות לכך כאל "תגובה מוצלחת" והצגת חצי טקסט למשתמש היא אחת הטעויות הנפוצות ביותר בייצור. או הגדל את max_tokens או השתמש בסטרימינג.
הנחיה חלשה / הנחיה חזקה
אותה משימה עם שתי הנחיות מערכת שונות:
# חלש אתה עוזר. ענה על השאלות.
# STRONG אתה עוזר תמיכה ארגוני. כללים:- הסתמכו אך ורק על המידע במסמך הפוליסה שסופק; אם זה לא במסמך, אמור "אין לי את המידע הזה, אני מפנה אותו ליחידה הרלוונטית". - התשובות לא יעלו על 3 משפטים, יהיו רשמיות וברורות. - אל תבקש מידע אישי (מספר תעודת זהות TC, מספר כרטיס) ואל תחזור. - אל תנחש כשאתה לא בטוח.
גרסה חזקה; הוא מגדיר היקף, צורה, מרווח בטיחות והתנהגות באי ודאות. העקביות של פלט הדגם מגיעה ישירות מהבהירות הזו.
שלושה מיני מארזים
מקרה 1 - בוט תמיכה (מלכודת חוסר מדינה). צוות מסחר אלקטרוני לקח את הבוט בשידור חי; כשהמשתמש אמר "בטל את ההזמנה הקודמת", הבוט "שכח" את מספר ההזמנה. סיבה: הם שלחו כל בקשה עם ההודעה האחרונה בלבד. פתרון: הם הוסיפו את 6 הסיבובים האחרונים לרשימת ההודעות. תוצאה: ההקשר נשמר, אך הקלט לכל בקשה גדל מ-40 אסימונים ל-~600 אסימונים - אנו נסקור את שיעור העלות ביחידה 2.
מקרה 2 - סיכום חוזה לא שלם. לצוות משפטי היו חוזים בני 10 עמודים. max_tokens: 300 נשארו נמוך, הסיכומים קטעו את אמצע המשפט. stop_reason היה max_tokens בכל פעם אבל אף אחד לא הסתכל. הגדיל את max_tokens ל-1500 והוסיף בדיקת stop_reason; שיעור הסיכום הקטוע ירד מ-18% ל-0%.
מקרה 3 - ערבוב תפקידים. צוות שיווק כתב את כל ההוראות בהודעת המשתמש, והשאיר את המערכת ריקה. כאשר קלט משתמש מעורבב עם הוראה, המודל היה מציית לפעמים לפקודה של המשתמש "לשכוח את הכללים הקודמים". הם העבירו חוקים קבועים למערכת; על ידי הפרדת קלט המשתמש מההוראה, הפרות הכללים פחתו באופן משמעותי.
טעויות נפוצות
- שוכחים לשלוח את העבר: הדגם נחשב "לא זוכר"; ואילו הוא חסר אזרחות. אתה נושא את ההקשר.
- לא מסתכל על `stop_reason`: התגובה שהופסקה עם max_tokens נחשבת להשלמת.
- הטמעת ההוראה ב'משתמש': כללים קבועים במערכת; קלט מיידי עובר למשתמש. ערבוב יוצר פרצות אבטחה.
- טעות ב'תוכן' כמחרוזת פשוטה: התשובה היא רשימה של בלוקים; קרא את שדה הטקסט של בלוק הטקסט הראשון, ודא את סוגו לפני קבלת תוכן[0] עם אינדקס עיוור.
- הטמעת המפתח בקוד: השתמש במשתנה סביבה (יחידה 9).
עמוק יותר: חסימות תוכן ותשובות מרובות חלקים
ההבנה מדוע שדה התוכן בתגובה הוא רשימה היא בסיסית לתכונות המתקדמות שתיתקל בהן מאוחר יותר. לפעמים המודל מחזיר לא גוש טקסט אחד, אלא מספר קוביות: גוש חשיבה ואחריו גוש טקסט; או בלוק טקסט ואחריו בלוק לשימוש בכלי. לכן ספירה עיוורת של תוכן[0] כ"תשובה" היא שבירה. הגישה הנכונה היא לעבור על הרשימה ולמיין אותה לפי סוג: אתה אוסף את תוכן הטקסט של בלוקים ששדה הסוג שלהם הוא טקסט, ומתייחס לסוגים אחרים (חשיבה, כלי) בנפרד.
מה שההבחנה הזו עושה בפועל הוא שאתה יכול לרשום את ההיגיון של המודל (אם בכלל) מבלי לחשוף אותו למשתמש, להפנות את קריאות הכלים ללוגיקה נפרדת, ולהדפיס רק את התשובה בפועל על המסך. ככל שהמודול מתקדם (במיוחד ביחידות 4 ו-11) תראה עד כמה מבנה הבלוק הזה שימושי לאימות והכוונת פלט.
נקודה מעשית נוספת: אתה יכול לגשת לאותו דגם מפלטפורמות ספקיות שונות (API ישיר, דרך ספק ענן). למרות שכתובת נקודת הקצה ופורמט האימות עשויים להשתנות, מושגים בסיסיים כגון תפקידי הודעה, חוסר מצב ומבנה תגובה נשארים זהים. אז היסודות ביחידה זו חלים לא משנה באיזו פלטפורמה אתה משתמש.
לסיכום
בקשת API של LLM מורכבת מהדגם, מגבלת הפלט ורשימת ההודעות; תפקידים (מערכת, משתמש, עוזר) קובעים את התנהגות המודל. שיחות הן חסרות אזרחות: אתה נושא את ההקשר עם כל בקשה. התגובה היא אובייקט מובנה; קריאה ופירוש של שדות התוכן, הסבת_סיבה ושימוש היא הבסיס לעמידות בייצור.
משימת יישום
בחר משימה מהמקצוע שלך (למשל מיון דואר אלקטרוני נכנס, יצירת סיכומים קצרים). על פיסת נייר: (1) כתוב את הודעת המערכת עם 4-5 כללים, (2) הגדר הודעת משתמש לדוגמה והיסטוריה של 2 סיבובים אם יש, (3) קבע ערך סביר עבור max_tokens וכתוב את ההצדקה, (4) רשום באילו ערכי stop_reason תטפל בתגובה המוחזרת וכיצד.
רשימת בדיקה
- [ ] אני יכול לספור את שלושת חלקי החובה של בקשה (מודל, max_tokens, הודעות).
- [ ] אני יכול להסביר את ההבדל בין תפקידי מערכת, משתמש ועוזר.
- [ ] אני יודע ששיחות הן חסרות אזרחות ושאני צריך לשאת את העבר.
- אני יכול לקרוא ולהגיב על [ ] תוכן, סיבת_עצירה ושדות שימוש.
- [ ] עם max_tokens אני יכול להבחין ולטפל בתגובה הקטומה.