שילוב של Assistant בפרויקט (בשפות אחרות)

כדי לשלב את 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 שנוצר במהלך רישום הדגם של המכשיר.

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

  1. משתמשים בסביבה וירטואלית של 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

  2. התקנת כלי ההרשאות:

    python -m pip install --upgrade google-auth-oauthlib[tool]

  3. מפעילים את הכלי. מסירים את הדגל --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.

פעלו לפי הדברים הבאים במדריכים האלה:

כדאי לקרוא את השיטות המומלצות לגבי פרטיות ואבטחה כדי לקבל המלצות לאבטחת המכשיר.

אימות החיבור ל-gRPC באמצעות אסימוני OAuth

לבסוף, מחברים את כל החלקים בעזרת הסבר על השימוש באימות מבוסס-אסימונים ב-Google כדי לאמת את חיבור ה-gRPC ל-Assistant API.

רישום המכשיר

רושמים את דגם המכשיר ואת המכונה באופן ידני או באמצעות כלי הרישום (זמין ב-Python).

הטמעת תיבת דו-שיח בסיסית של שיחה עם Assistant

  1. הטמעת לקוח gRPC לסטרימינג דו-כיווני עבור Google Assistant Service API.
  2. ממתינים עד שהמשתמש יפעיל בקשה חדשה (למשל, מחכים להפרעות ב-GPIO מלחיצה על לחצן).

  3. שולחים הודעת 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).

  4. מתחילים להקליט.

  5. שליחת מספר הודעות AssistRequest עם נתוני אודיו מהשאילתה שנאמרת בקול בשדה audio_in.

  6. טיפול בהודעות נכנסות של AssistResponse.

  7. חלץ את המטא-נתונים של השיחות מההודעה AssistResponse. לדוגמה, מ-dialog_state_out, מקבלים את conversation_state ו-volume_percentage (מידע נוסף ב-DialogStateOut).

  8. הפסקת ההקלטה עם קבלת AssistResponse עם event_type של END_OF_UTTERANCE.

  9. השמעת אודיו מהתשובה של Assistant עם נתוני האודיו שמגיעים מהשדה audio_out.

  10. לוקחים את conversation_state שחילצתם קודם ומעתיקים אותו להודעה DialogStateIn בAssistConfig עבור AssistRequest הבאה.

כך אתם אמורים להיות מוכנים לשלוח את הבקשות הראשונות ל-Google Assistant דרך המכשיר שלכם.

הרחבת תיבת דו-שיח של שיחה באמצעות 'פעולות במכשיר'

אתם יכולים להרחיב את תיבת הדו-שיח הבסיסית של השיחה שלמעלה כדי להפעיל את יכולות החומרה הייחודיות של המכשיר הספציפי שלכם:

  1. בהודעות הנכנסות AssistResponse, מחלצים את השדה device_action (מידע נוסף ב-DeviceAction).
  2. ניתוח המטען הייעודי (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.

פתרון בעיות

אם תיתקלו בבעיות, עיינו בדף פתרון בעיות.