פעולות ופרמטרים

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

איפה אפשר למצוא את הנתונים האלה

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

1. עוברים אל מסוף Dialogflow ES.
2. בוחרים נציג תמיכה.
3. בתפריט הצדדי הימני, בוחרים באפשרות כוונות.
4. בוחרים כוונה.
5. גוללים למטה לקטע Action and parameters (פעולה ופרמטרים).

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

פעולות

השדה action הוא שדה נוח ופשוט שעוזר להפעיל לוגיקה בשירות.

כשיוצרים סוכן, אפשר להגדיר בשדה הזה כל טקסט שרוצים.

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

פרמטרים

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

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

ברשימה הבאה מוצגים השדות של הגדרת פרמטר. מוצגות דוגמאות לביטוי האימון 'book a room on Tuesday' (תזמין חדר ליום שלישי), כאשר 'Tuesday' (יום שלישי) מסומן בהערה.

• חובה: מסמנים את התיבה הזו אם הפרמטר נדרש כדי שהכוונה תהיה שלמה. מידע נוסף מופיע בקטע מילוי משבצות עם פרמטרים נדרשים בהמשך.
• שם הפרמטר: שם שמזהה את הפרמטר. דוגמה: date.
• ‫Entity: סוג הישות שמשויך לפרמטר. דוגמה: @sys.date.
• ערך: ברוב המקרים, הערך הזה מוגדר כהפניה לפרמטר כמו $parameter-name, שמשמש כפלייסולדר לערך שחולץ בזמן הריצה. עם זאת, אפשר להשתמש בשדה הזה גם כדי לבחור ערכים חלופיים. עיינו בקטע ערכי פרמטרים והפניות לפרמטרים בהמשך. דוגמה: $date.
• Is List: מסמנים את התיבה הזו אם רוצים שהערכים יוחזרו כרשימה. בהמשך מופיע הקטע רשימת פרמטרים.
• הנחיות: שאלות שהסוכן ישאל את משתמש הקצה אם הפרמטר הזה לא סופק. השדה הזה משמש רק אם מסומנת התיבה חובה. מידע נוסף מופיע בקטע מילוי משבצות עם פרמטרים נדרשים בהמשך.
• ערך ברירת מחדל: זהו ערך ברירת המחדל של הפרמטר אם משתמש הקצה לא מספק ערך. כדי לשנות את ערך ברירת המחדל באמצעות המסוף, צריך להעביר את העכבר מעל שורת הפרמטר וללחוץ על התפריט בצד שמאל.

כשמזהים כוונה בזמן הריצה,‏ Dialogflow מספק נתוני פרמטרים לבקשת ה-webhook של מילוי הבקשה או לתשובת האינטראקציה עם ה-API. הם מסופקים כמיפוי משמות של פרמטרים לערכים של פרמטרים.

כשמפתחים סוכן, התשובות יכולות לכלול ערכי פרמטרים. בהמשך המאמר מוסבר על ערכי פרמטרים והפניות לפרמטרים.

פרמטרים של רשימות

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

• ‫"I want apples" (אני רוצה תפוחים)
• ‫"I want apples and oranges" (אני רוצה תפוחים ותפוזים)
• ‫"I want apples, oranges, and bananas" (אני רוצה תפוחים, תפוזים ובננות)

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

אחרי שמבצעים הערה לפחות לשתי מילים או לביטויים עם אותו פרמטר במשפט אימון יחיד, האפשרות Is List מופעלת באופן אוטומטי. אם משביתים את האפשרות הזו אבל משאירים את אותה הערה, התיבה Is List תסומן שוב באופן אוטומטי כשפותחים את הדף עם ההערה הזו.

בסוכנים רב-לשוניים, האפשרות Is List לא ספציפית לשפה.

ערכי פרמטרים והפניות לפרמטרים

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

לדוגמה, אפשר להשתמש ב-$parameter-name בתשובה של כוונת משתמש. כש-Dialogflow מגיב למשתמש, הוא מחליף את ההפניה לפרמטר בערך הפרמטר שחולץ בזמן הריצה. התכונה הזו שימושית לסיכום מידע שסופק על ידי משתמש הקצה. לדוגמה, תשובה להבעת כוונה יכולה להיראות כך: ‫"Okay, I booked a room for you on $date".

הפניה בסיסית לפרמטרים

כדי להפנות לערך פרמטר שחולץ על ידי הישות המשויכת, צריך להשתמש בפורמט הבא:

$parameter-name

לדוגמה, אם שם הפרמטר הוא date, אפשר להפנות אליו כאל $date.

הפניה לפרמטר של ערך מקורי

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

$parameter-name.original

לדוגמה, אם שם הפרמטר הוא date, אפשר להתייחס לערך המקורי כאל $date.original.

הפניה לפרמטר של תאריכים לא חד-משמעיים

כשפרמטר משויך לישות המערכת @sys.date, והמשתמש מספק תאריך חלקי (לא מציין חודש, יום ושנה), Dialogflow יתאים לתאריך הקרוב ביותר בעתיד. אבל אפשר גם לאחזר וריאציות של התאריך הזה.

אפשר לאחזר את ההתאמה החלקית המדויקת, שבה Dialogflow מחליף את החלק הלא ידוע ב-Us, באמצעות הפורמט הבא:

$parameter-name.partial

אפשר לאחזר את התאריך הקרוב ביותר בעבר באמצעות הפורמט הבא:

$parameter-name.recent

לדוגמה, אם התאריך של היום הוא 11 באוגוסט 2021, שם הפרמטר הוא date, והמשתמש אומר "13 באוגוסט":

הפניה לפרמטר	ערך שנקבע
‫$date	2021-08-13
$date.partial	UUUU-08-13
$date.recent	2020-08-13

הפניה לפרמטר של ישות מורכבת

ישויות מורכבות הן ישויות שמכילות ישויות משנה אחרות. כדי להפנות לערך של ישות משנה של פרמטר, משתמשים בפורמט הבא:

$parameter-name.sub-entity-name

לדוגמה, אם שם הפרמטר הוא move ושם ישות המשנה הוא direction, אפשר להפנות לערך של ישות המשנה בתור $move.direction.

חומרי עזר לפרמטרים של הקשר פעיל

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

#context-name.parameter-name

לדוגמה, אם שם הפרמטר הוא room ו-reservation הוא הקשר הפעיל, אפשר להפנות לערך הפרמטר כ-#reservation.room.

הפניה לפרמטר של אירוע

כדי להפנות לפרמטר של אירוע, משתמשים בפורמט הבא:

#event-name.parameter-name

לדוגמה, אם שם הפרמטר הוא duration ושם האירוע הוא alarm, אפשר להתייחס לפרמטר של אירוע כאל #alarm.duration.

השדה 'ערך הפרמטר'

להפניות לפרמטרים בשדה ערך של הפרמטר יש משמעות מיוחדת. התוכן בשדה הזה קובע את הערך שמתקבל עבור$parameter-name בתגובות לכוונות ובהנחיות לפרמטרים. מערכת Dialogflow מעבדת נתוני פרמטרים בסדר הבא:

1. מחפשים את ערך הפרמטר בביטוי של משתמש הקצה באמצעות הישות המשויכת.
2. מזינים תוכן בשדה הפרמטר ערך.
3. מגדירים את $parameter-name לתוכן שנפתר של הפרמטר Value. אם השדה Value לא מוגדר ל-$parameter-name, הערך של $parameter-name יאופס למשהו אחר.
4. לפתור תוכן לתשובות של כוונות ולהנחיות של פרמטרים.

הנה כמה דוגמאות שממחישות את ההשפעות של הסדר הזה על ביטוי של משתמש קצה כמו "אני רוצה לקנות חולצה קטנה".

מיקום ההפניה לפרמטר	תוכן שהוגדר	תוכן שנפתרה לגביו בעיה
השדה ערך של הפרמטר	$size	S
תגובה בהתאם לכוונה	בחרת בגודל: $size	בחרת מידה: S

מיקום ההפניה לפרמטר	תוכן שהוגדר	תוכן שנפתרה לגביו בעיה
השדה ערך של הפרמטר	$size.original	קטן
תגובה בהתאם לכוונה	בחרת בגודל: $size	בחרת בגודל: קטן

מיקום ההפניה לפרמטר	תוכן שהוגדר	תוכן שנפתרה לגביו בעיה
השדה ערך של הפרמטר	$size	S
תגובה בהתאם לכוונה	בחרת בגודל: $size.original	בחרת מידה: קטנה

מילוי משבצות עם פרמטרים נדרשים

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

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

‫Dialogflow לא שולח בקשת webhook לביצוע פעולה עד שהוא אוסף את כל הנתונים הנדרשים ממשתמש הקצה, אלא אם מופעלת האפשרות webhook למילוי משבצות.

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

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

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

• סוג הביגוד
• quantity
• size
• color

השלמת כוונה יכולה להיראות כך:

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

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

פרמטרים של הזמנה

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

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

הפניות לפרמטרים בהנחיות

כשמפתחים סוכן, אפשר להשתמש בהפניות לפרמטרים בהנחיות, אבל רק לפרמטרים נדרשים לפני ההנחיה. לדוגמה, אם הפרמטר color מופיע לפני הפרמטר quantity, אפשר להשתמש בהנחיה הבאה לפרמטר quantity: How many $color t-shirts would you like to buy?

ביטול מילוי משבצת

כשמשתמש הקצה אומר ביטוי יציאה כמו "ביטול", "תפסיק", "זה מספיק" וכו', הנציג משיב "בסדר, בוטל" ומנקה את ההקשרים של מילוי המשבצות.

אם אתם משתמשים ב-API, השדה DetectIntentResponse.queryResult.cancelsSlotFilling מוגדר לערך true כשביטול מילוי המשבצת מתבצע. מידע נוסף זמין במאמרי העזרה בנושא detectIntent של סוג Sessions.