ליצור תמליל של הפגישות העסקיות באמצעות Google Docs & למידת מכונה

1. סקירה כללית

ב-codelab הזה נלמד איך לשלוח קובץ אודיו דרך Google Cloud Speech to Text API, ואז להפיק את התמליל כפלט למסמך Google. קל להשתמש ב-Speech to Text API, והוא משתמש ברשתות נוירונים מתקדמות כדי לאפשר למפתחים להמיר אודיו לטקסט. בנוסף, הוא מבוסס על למידת מכונה.

תשתמשו ב-Google Docs API כדי ליצור מסמך חדש ולכתוב בו. תצרו אפליקציית שורת פקודה ב-Java ותריצו את הקוד באמצעות מערכת ה-build של Gradle, ואז תשתמשו ב-Docs API כדי לראות את התוצאות.

מה תלמדו

איך משתמשים ב-Google Cloud Speech to Text API
איך משתמשים ב-Google Docs API כדי ליצור מסמך חדש
איך משתמשים ב-Docs API כדי לכתוב למסמך

הדרישות

‫Java מותקנת (גרסה 7 ואילך)
‫Gradle מותקן (גרסה 5 ומעלה)
גישה לאינטרנט ולדפדפן אינטרנט
חשבון Google
פרויקט ב-Google Cloud Platform

2. הגדרת הפרויקט

יצירת פרויקט בענן

נכנסים אל Cloud Console ויוצרים פרויקט חדש או משתמשים בפרויקט קיים. (אם אין לכם חשבון Gmail או חשבון Workspace, אתם צריכים ליצור חשבון).

dMbN6g9RawQj_VXCSYpdYncY-DbaRzr2GbnwoV7jFf1u3avxJtmGPmKpMYgiaMH-qu80a_NJ9p2IIXFppYk8x3wyymZXavjglNLJJhuXieCem56H30hwXtd8PvXGpXJO9gEUDu3cZw

ci9Oe6PgnbNuSYlMyvbXF1JdQyiHoEgnhl4PlV_MFagm2ppzhueRkqX4eLjJllZco_2zCp0V0bpTupUSKji9KkQyWqj11pqit1K1faS1V6aFxLGQdkuzGp4rsQTan7F01iePL5DtqQ

8-tA_Lheyo8SscAVKrGii2coplQp2_D1Iosb2ViABY0UUO1A8cimXUu6Wf1R9zJIRExL5OB2j946aIiFtyKTzxDcNnuznmR45vZ2HMoK3o67jxuoUJCAnqvEX6NgPGFjCVNgASc-lg

חשוב לזכור את מזהה הפרויקט, שהוא שם ייחודי בכל הפרויקטים ב-Google Cloud (השם שלמעלה כבר תפוס ולא יתאים לכם, מצטערים!). בהמשך ה-codelab הזה נתייחס אליו כאל PROJECT_ID.

לאחר מכן, תצטרכו להפעיל את החיוב ב-Cloud Console כדי להשתמש במשאבים של Google Cloud.

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

טעינת מפתח לחשבון שירות עבור Cloud Speech-to-Text API

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

$ export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

לדוגמה:

$ export GOOGLE_APPLICATION_CREDENTIALS="/home/usr/downloads/ServiceAccount.json"

קבלת פרטי כניסה ל-Docs API

חוזרים אל מסוף GCP ועוברים אל Credentials.
יצירת מפתח OAuth 2.0 והורדה שלו כ-JSON
משנים את השם של הקובץ credentials.json ומוודאים שהוא נמצא בספרייה src/main/resources/ של הקוד.

הפעלת ממשקי ה-API

בוחרים בכרטיסייה Dashboard, לוחצים על הלחצן Enable APIs and Services ומפעילים את שני ממשקי ה-API הבאים:
המרת דיבור לטקסט (STT)
Google Docs

עכשיו אפשר להתחיל לעבוד עם הקוד.

3. הגדרת הקוד

קבלת קוד לדוגמה

כדי לקבל את קוד הדוגמה, אפשר להוריד את קובץ ה-ZIP למחשב…

…או משכפלים את המאגר ב-GitHub משורת הפקודה.

$ git clone git@github.com:googleworkspace/docs-transcript-codelab.git

תעבדו בקובץ CreateTranscript.java שבספרייה start. אין לשנות את קובצי ה-gradle.

בספרייה, עוברים לתיקייה start ופותחים את הקובץ CreateTranscript.java. גוללים למטה עד שמגיעים להצהרת המחלקה CreateTranscript.

public class CreateTranscript {
  private static final String CREDENTIALS_FILE_PATH = "/credentials.json";
  
  // Specify audio file name below.
  private static final String AUDIO_FILENAME = "audioFile.wav";
  private static final String TOKENS_DIRECTORY_PATH = "tokens";
  private static final JsonFactory JSON_FACTORY = JacksonFactory.getDefaultInstance();
  private static final String APPLICATION_NAME = "CreateTranscript";
  private static final List<String> SCOPES = Collections.singletonList(DocsScopes.DOCUMENTS);

במשתנה SCOPES ציינת שהקוד יוכל להציג ולנהל את המסמכים של המשתמש ב-Google Docs. אם הקוד שלכם דורש הרשאה מעבר לגישה הזו או שונה ממנה, הקפידו לשנות את המשתנה הזה בהתאם להיקפי ההרשאות של OAuth 2.0 ל-Google APIs.

לדוגמה, אם לא כתבתם במסמך Google Docs, תוכלו לשנות את ההיקף ל-DOCUMENTS_READONLY. המשתנה SCOPES נחוץ לא רק כדי שהאפליקציה תקבל הרשאות גישה מתאימות, אלא גם כדי לשמור על שקיפות מול המשתמשים. המשתמש רואה את היקפי ההרשאות הספציפיים שביקשתם בדף האימות של OAuth, שבו הוא צריך להביע הסכמה לשימוש באפליקציה.

שינוי השם של משתנים

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

מוודאים שהערך של AUDIO_FILENAME מוגדר לשם של קובץ ההדגמה שאתם שולחים ל-Speech to Text API. בקובץ CreateTranscript.java, ההגדרה הזו כבר אמורה להיות מוגדרת בצורה נכונה.
משנים את השם של CREDENTIALS_FILE_PATH לשם של קובץ פרטי הכניסה שהורדתם (השם צריך להיות'/credentials.json'). מוודאים שהקובץ הזה נמצא בספרייה src/main/resources של התיקייה שלכם. אם לא, צריך ליצור את הספרייה הזו.

עכשיו אפשר להתחיל להריץ את הקוד.

4. אתחול של לקוח Docs

בקובץ CreateTranscript.java, מאתרים את הצהרת השיטה הראשית ומציצים לראות מה יש בתוכה:

final NetHttpTransport HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
Docs service = new Docs.Builder(HTTP_TRANSPORT, JSON_FACTORY,
    getCredentials(HTTP_TRANSPORT))
          .setApplicationName(APPLICATION_NAME)
          .build();

הרשאה להפעלת פונקציה

המשימה הראשונה שאתם מבצעים כאן היא יצירה של Docs service (משתנה). השירות מייצג לקוח API מורשה, שמחזיק בפרטי הכניסה שלכם ובאימות משתמש הקצה שלכם במקרה הזה.

בקוד, כל פונקציה שמבצעת קריאה ל-Docs API תצטרך להשתמש במשתנה service הזה כדי לבצע משימות שקשורות ל-Docs.

5. יצירת מסמך Google

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

Document doc = new Document().setTitle("Transcript for " +
    AUDIO_FILENAME);
doc = service.documents().create(doc).execute();
String documentId = doc.getDocumentId();
return documentId;

הפונקציה הזו מחזירה את מזהה הקובץ ב-Drive של מסמך Google Docs. אותו מזהה מופיע בכתובת ה-URL של המסמך.

בשלב הבא, מאתחלים את לקוח Speech-to-Text.

6. קריאה ל-Speech to Text API

המשימה הבאה שרוצים לבצע בקוד היא קבלת התמליל הכתוב של קובץ האודיו. בתוך CreateTranscript.java, מחפשים את הפונקציה getTranscript().

קודם כל, צריך לקבל את הנתיב של קובץ האודיו ואת בייטי האודיו:

SpeechClient speech = SpeechClient.create();
Path path = Paths.get(AUDIO_FILENAME);
byte[] data = Files.readAllBytes(path);
ByteString audioBytes = ByteString.copyFrom(data);

הגדרת זיהוי דיבור

בשלב הבא, צריך לאתחל את המשתנה RecognitionConfig בצורה נכונה.

במקרה הזה, config מספק מידע על האופן שבו מנגנון זיהוי הדיבור צריך לעבד את הבקשה. לדוגמה, אם קובץ האודיו שלכם הוא בשפה אחרת מאנגלית, תצטרכו לערוך את setLanguageCode(). אם קובץ האודיו שלכם כולל קצב דגימה שונה בהרץ (1,600 הוא קצב הדגימה האופטימלי), תצטרכו לשנות את setSampleRateHertz().

RecognitionConfig config =
    RecognitionConfig.newBuilder()
        .setEncoding(AudioEncoding.LINEAR16)
        .setLanguageCode("en-US")
        .setSampleRateHertz(8000)
        .build();
RecognitionAudio audio =
    RecognitionAudio.newBuilder().setContent(audioBytes).build();
RecognizeResponse response = speech.recognize(config, audio);
List<SpeechRecognitionResult> results = response.getResultsList();

הכנת הטקסט

לבסוף, מטפלים במשתנה result של תמלול קובץ האודיו ומכינים אותו להוספה למסמך.

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

List<Request> requests = new ArrayList<>();
for (SpeechRecognitionResult result : results) {
     // Using the first + most likely alternative transcript
     SpeechRecognitionAlternative alternative =
         result.getAlternativesList().get(0);
     String toInsert = alternative.getTranscript();

     // Add requests array list to return.
     requests.add(
         new Request()
             .setInsertText(
                 new InsertTextRequest()
                     .setText(toInsert)
                     .setEndOfSegmentLocation(new
     EndOfSegmentLocation().setSegmentId(""))));
}
return requests;

7. הוספת טקסט למסמך

עכשיו מוסיפים את הטקסט של התמליל למסמך Google Docs. כדי לבצע שינויים במסמך, צריך להשתמש בשיטה BatchUpdate. ‫BatchUpdate הוא מאגר לבקשות כתיבה מסוגים שונים, ובמקרה הזה תשתמשו ב- InsertTextRequest.

‫EndOfSegmentLocation הוא פרמטר חשוב שמציין איפה במסמך רוצים להדפיס את הטקסט. בקוד המקור, אתם מוסיפים טקסט לגוף המסמך ב-Docs.

נניח שנוסיף את הקוד הבא לפונקציה כדי לראות איך תוצאות של המרת דיבור לטקסט (STT) API בשילוב עם קריאות ל-Docs API מאפשרות לנו להוסיף תמליל של קובץ אודיו למסמך ב-Google Docs:

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest();
service.documents().batchUpdate(docId,
    body.setRequests(insertRequests)).execute();

יצירת הבקשה

כשמבצעים את הבקשה BatchUpdate, מגדירים שתי הגדרות חשובות מאוד: מה רוצים להדפיס (.setText()) ואיפה במסמך רוצים לעשות את זה (.setIndex(1)).

התמליל של קובץ האודיו נוסף למסמך שיצרתם.

8. הרצת הקוד

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

מכיוון שאתם הולכים להריץ את קוד ה-Java באמצעות מערכת ה-build של Gradle, אתם צריכים לציין בקובץ build.gradle מה בדיוק לבנות ולהריץ. בפרויקט הזה ובפרויקטים אחרים, חשוב לוודא שהערך של mainClassName תואם למחלקת ה-Java שרוצים להריץ.

מצוין! עכשיו אפשר להריץ את הקוד. כדי לעשות זאת, מקלידים את הפקודה הבאה בשורת הפקודה:

$ gradle run

אימות משתמשי קצה

בפעם הראשונה שמריצים את הקוד הזה, כתובת URL מודפסת במסוף. צריך להתחבר לחשבון השירות ולאשר גישה ל-Google Docs שלו. אחרי שתאשרו את הגישה, תראו קובץ חדש שיישמר בספרייה שלכם.

בספריית העבודה תופיע תיקייה חדשה בשם tokens, שמכילה את הקובץ StoredCredential. זהו טוקן האימות שסיפקתם עכשיו. הלקוח שלכם ביקש אותו משרת האימות של Google, חילץ אותו מהתשובה שלו ועכשיו ישלח אותו לכל API שתפעילו.

פתרון

אם הקוד לא פועל, כדאי לעיין בקובץ CreateTranscript.java בתיקייה finish. הקובץ הזה מכיל את כל הקוד בדיוק כמו שהוא צריך להיות כדי לפעול בהצלחה.

עכשיו נסתכל על התוצאה.

9. צפייה בתוצאות

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

מסמך ה-Doc הזה נוצר דרך החשבון שהמשתמש הקצה לו הרשאה. אפשרות אחת היא לשתף את המסמך הזה באופן אוטומטי עם אחרים באמצעות Drive API.

בהתבסס על קוד המקור וקובץ האודיו שסיפקת, הנה מה שצריך לראות:

10. מעולה!

למדתם איך ליצור מסמך Google Docs, לבצע קריאה ל-Speech-to-Text API ולייצא את התמליל של קובץ האודיו למסמך שיצרתם.

שיפורים אפשריים

הנה כמה רעיונות לשילוב מוצלח יותר:

הגדרת הקוד כך שיאזין לרגע שבו קובץ אודיו נוסף לקטגוריה של Google Cloud Storage ב-Drive, ויפעיל Google Cloud Function כדי להריץ את הקוד הזה
הוספת טקסט למסמך לא ריק ב-Google Docs

מידע נוסף

מומלץ לקרוא את מסמכי התיעוד למפתחים של Google Docs API
פרסום שאלות ומציאת תשובות ב-Stack Overflow באמצעות התג google-docs-api