כדי לשלב את Google Assistant בפרויקט, פועלים לפי ההוראות בכל אחד מהקטעים שבהמשך.
קישורי gRPC
שירות Google Assistant מבוסס על gRPC, מסגרת RPC בעלת ביצועים גבוהים וקוד פתוח. ה-framework הזה מתאים מאוד לסטרימינג דו-כיווני של אודיו.
Python
אם אתם משתמשים ב-Python, התחילו בעזרת המדריך הזה.
C++
כדאי לעיין בדוגמה ל-C++ ב-GitHub.
Node.js
עיינו בדוגמת Node.js ב-GitHub.
Android Things
רוצה לראות מכשירים מוטמעים? אתם מוזמנים לעיין בדוגמה של Assistant SDK עבור Android Things.
שפות אחרות
- משכפלים את המאגר של googleapis כדי לקבל את ההגדרות של ממשק מאגר הנתונים הזמני של Google Assistant Service API.
- כדאי לפעול לפי התיעוד של gRPC כדי ליצור קישורי gRPC בשפה שבחרתם
- יש לפעול לפי השלבים שמפורטים בקטעים שבהמשך.
אישור ואימות של חשבון Google כדי לעבוד עם Assistant
בשלב הבא, צריך לתת הרשאה למכשיר לדבר עם Google Assistant באמצעות חשבון Google.
קבלת אסימוני OAuth באמצעות היקף ה-SDK של Assistant
Assistant SDK משתמשת באסימוני גישה מסוג OAuth 2.0 כדי לתת למכשיר שלך הרשאה להתחבר ל-Assistant.
במהלך יצירת אב טיפוס, תוכלו להשתמש בכלי ההרשאות כדי ליצור בקלות פרטי כניסה
של OAuth2.0 מקובץ client_secret_<client-id>.json
שנוצר במהלך רישום הדגם של המכשיר.
מבצעים את הפעולות הבאות כדי ליצור את פרטי הכניסה:
משתמשים בסביבה וירטואלית של Python כדי לבודד את כלי ההרשאה ואת יחסי התלות שלו מחבילות ה-Python של המערכת.
sudo apt-get update
sudo apt-get install python3-dev python3-venv # Use python3.4-venv if the package cannot be found.
python3 -m venv env
env/bin/python -m pip install --upgrade pip setuptools wheel
source env/bin/activate
התקנת כלי ההרשאות:
python -m pip install --upgrade google-auth-oauthlib[tool]
מפעילים את הכלי. מסירים את הדגל
--headless
אם מריצים אותו מטרמינל במכשיר (לא בסשן SSH):google-oauthlib-tool --client-secrets /path/to/client_secret_client-id.json --scope https://www.googleapis.com/auth/assistant-sdk-prototype --save --headless
כשתהיו מוכנים לשלב את ההרשאה כחלק ממנגנון ההקצאה של המכשיר, כדאי לקרוא את המדריכים שלנו בנושא שימוש ב-OAuth 2.0 לגישה ל-Google APIs כדי להבין איך לקבל אסימוני גישה מסוג OAuth, לשמור אותם ולהשתמש בהם כדי לאפשר למכשיר לתקשר עם Assistant API.
פעלו לפי הדברים הבאים במדריכים האלה:
- היקף OAuth: https://www.googleapis.com/auth/assistant-sdk-prototype
תהליכי OAuth נתמכים:
כדאי לקרוא את השיטות המומלצות לגבי פרטיות ואבטחה כדי לקבל המלצות לאבטחת המכשיר.
אימות החיבור ל-gRPC באמצעות אסימוני OAuth
לבסוף, מחברים את כל החלקים בעזרת הסבר על השימוש באימות מבוסס-אסימונים ב-Google כדי לאמת את חיבור ה-gRPC ל-Assistant API.
רישום המכשיר
רושמים את דגם המכשיר ואת המכונה באופן ידני או באמצעות כלי הרישום (זמין ב-Python).
הטמעת תיבת דו-שיח בסיסית של שיחה עם Assistant
- הטמעת לקוח gRPC לסטרימינג דו-כיווני עבור Google Assistant Service API.
- ממתינים עד שהמשתמש יפעיל בקשה חדשה (למשל, מחכים להפרעות ב-GPIO מלחיצה על לחצן).
שולחים הודעת
AssistRequest
עם שדהconfig
מוגדר (מידע נוסףAssistConfig
) צריך לוודא שהשדהconfig
כולל את הפרטים הבאים:- השדה
audio_in_config
, שמציין איך לעבד את נתוניaudio_in
שיסופקו בבקשות הבאות (מידע נוסףAudioInConfig
). - השדה
audio_out_config
, שמציין את הפורמט הרצוי לשימוש השרת כשהוא מחזיר הודעותaudio_out
(מידע נוסףAudioOutConfig
). - השדה
device_config
, שמזהה את המכשיר הרשום ל-Assistant (מידע נוסף זמין במאמרDeviceConfig
). - השדה
dialog_state_in
, שמכיל את ה-language_code
שמשויך לבקשה (מידע נוסף זמין בכתובתDialogStateIn
).
- השדה
מתחילים להקליט.
שליחת מספר הודעות
AssistRequest
עם נתוני אודיו מהשאילתה שנאמרת בקול בשדהaudio_in
.טיפול בהודעות נכנסות של
AssistResponse
.חלץ את המטא-נתונים של השיחות מההודעה
AssistResponse
. לדוגמה, מ-dialog_state_out
, מקבלים אתconversation_state
ו-volume_percentage
(מידע נוסף ב-DialogStateOut
).הפסקת ההקלטה עם קבלת
AssistResponse
עםevent_type
שלEND_OF_UTTERANCE
.השמעת אודיו מהתשובה של Assistant עם נתוני האודיו שמגיעים מהשדה
audio_out
.לוקחים את
conversation_state
שחילצתם קודם ומעתיקים אותו להודעהDialogStateIn
בAssistConfig
עבורAssistRequest
הבאה.
כך אתם אמורים להיות מוכנים לשלוח את הבקשות הראשונות ל-Google Assistant דרך המכשיר שלכם.
הרחבת תיבת דו-שיח של שיחה באמצעות 'פעולות במכשיר'
אתם יכולים להרחיב את תיבת הדו-שיח הבסיסית של השיחה שלמעלה כדי להפעיל את יכולות החומרה הייחודיות של המכשיר הספציפי שלכם:
- בהודעות הנכנסות
AssistResponse
, מחלצים את השדהdevice_action
(מידע נוסף ב-DeviceAction
). - ניתוח המטען הייעודי (payload) של ה-JSON בשדה
device_request_json
. בדף Device Traits אפשר למצוא רשימה של התכונות הנתמכות. בכל דף של סכימת trait מוצגת בקשת EXECUTE לדוגמה עם הפקודות במכשיר והפרמטרים שמוחזרים במטען הייעודי(payload) של JSON.
קבלת התמליל של הבקשה מהמשתמש
אם יש לכם מסך שמצורף למכשיר, אפשר להשתמש בו כדי להציג את הבקשה מהמשתמש. כדי לראות את התמליל הזה, צריך לנתח את השדה speech_results
בהודעות AssistResponse
. כשזיהוי הדיבור יסתיים, הרשימה תכיל פריט אחד שבו stability
מוגדר ל-1.0.
קבלת הרינדור הטקסט או הרינדור של התשובה של Assistant
אם יש לכם מסך שמחובר למכשיר, כדאי להשתמש בו כדי להציג את התשובה של Assistant בפורמט טקסט פשוט לבקשת המשתמש. הטקסט הזה ממוקם בשדה DialogStateOut.supplemental_display_text
.
ה-Assistant תומך בתשובות חזותיות של HTML5 לשאילתות מסוימות (מה מזג האוויר במאונטיין וויו? או מה השעה?). כדי להפעיל את האפשרות הזו, צריך להגדיר את השדה screen_out_config
ב-AssistConfig
.
ההודעה ScreenOutConfig
כוללת את השדה screen_mode
, שצריך להגדיר אותו ל-PLAYING
.
לאחר מכן, השדה screen_out
מוגדר בהודעות AssistResponse
. אפשר לחלץ את נתוני ה-HTML5 (אם קיימים) מהשדה data
.
שליחת שאילתות באמצעות קלט טקסט
אם למכשיר מצורף ממשק טקסט (למשל מקלדת),
צריך להגדיר את השדה text_query
בשדה config
(מידע נוסף ב-AssistConfig
).
אין להגדיר את השדה audio_in_config
.
פתרון בעיות
אם תיתקלו בבעיות, עיינו בדף פתרון בעיות.