أنشئ نصًا لاجتماعات العمل باستخدام "مستندات Google" التعلم الآلي

1. نظرة عامة

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية إرسال ملف صوتي من خلال Google Cloud Speech to Text API، ثم إخراج نص المحادثة إلى مستند Google. تتميّز واجهة برمجة التطبيقات Speech to Text API بسهولة الاستخدام، وتطبّق شبكات عصبونية قوية تتيح للمطوّرين تحويل الصوت إلى نص. بالإضافة إلى ذلك، تستند هذه الميزة إلى تكنولوجيات تعلُّم الآلة.

ستستخدم Google Docs API لإنشاء مستند جديد والكتابة فيه. ستنشئ تطبيقًا مستندًا إلى سطر الأوامر بلغة Java، وستنفّذ الرمز باستخدام نظام التصميم Gradle، ثم ستستخدم واجهة برمجة التطبيقات Docs API لعرض النتائج.

أهداف الدورة التعليمية

• كيفية استخدام Google Cloud Speech to Text API
• كيفية استخدام Google Docs API لإنشاء مستند جديد
• كيفية استخدام Docs API للكتابة في مستند

المتطلبات

• تثبيت Java (الإصدار 7 أو إصدار أحدث)
• تثبيت Gradle (الإصدار 5 أو إصدار أحدث)
• إمكانية الوصول إلى الإنترنت ومتصفّح ويب
• حساب Google
• مشروع Google Cloud Platform

2. إعداد مشروعك

إنشاء مشروعك على السحابة الإلكترونية

1. سجِّل الدخول إلى Cloud Console وأنشِئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. (إذا لم يكن لديك حساب Gmail أو Workspace، عليك إنشاء حساب).

ملاحظة: يمكنك الوصول بسهولة إلى Cloud Console من خلال تذكُّر عنوان URL الخاص بها، وهو console.cloud.google.com.

تذكَّر رقم تعريف المشروع، وهو اسم فريد في جميع مشاريع Google Cloud (الاسم أعلاه مستخدَم حاليًا ولن يكون متاحًا لك، نأسف لذلك). سيتم الإشارة إليه لاحقًا في هذا الدرس التطبيقي حول الترميز باسم PROJECT_ID.

ملاحظة: إذا كنت تستخدم حساب Gmail، يمكنك ترك الموقع الجغرافي التلقائي مضبوطًا على بدون مؤسسة. في حال كنت تستخدم حسابًا على Workspace، اختَر موقعًا جغرافيًا مناسبًا لمؤسستك.

2. بعد ذلك، عليك تفعيل الفوترة في Cloud Console من أجل استخدام موارد Google Cloud.

لن تكلفك تجربة هذا الدرس البرمجي الكثير من المال، إن وُجدت تكلفة على الإطلاق. احرص على اتّباع أي تعليمات في قسم "التنظيف" الذي ينصحك بكيفية إيقاف الموارد حتى لا يتم تحصيل رسوم منك بعد هذا البرنامج التعليمي. يمكن لمستخدمي Google Cloud الجدد الاستفادة من برنامج الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.

الحصول على مفتاح حساب خدمة لواجهة Cloud Speech-to-Text API

1. انتقِل إلى وحدة تحكّم Google Cloud Platform وابحث عن مشروعك الجديد.
2. إنشاء حساب خدمة
3. تنزيل مفتاح حساب خدمة بتنسيق JSON
4. اضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS على مسار ملف JSON الذي يحتوي على مفتاح حساب الخدمة. إذا أعدت تشغيل جلسة shell، عليك ضبط المتغيّر مرة أخرى.

$ export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

على سبيل المثال:

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

الحصول على بيانات اعتماد لواجهة Docs API

1. في وحدة تحكّم Google Cloud Platform، انتقِل إلى بيانات الاعتماد.
2. إنشاء مفتاح OAuth 2.0 وتنزيله بتنسيق JSON
3. أعِد تسمية الملف credentials.json وتأكَّد من أنّه في الدليل src/main/resources/ الخاص برمزك

تفعيل واجهات برمجة التطبيقات

1. انقر على علامة التبويب لوحة البيانات، ثم على الزر تفعيل واجهات برمجة التطبيقات والخدمات، وفعِّل واجهتَي برمجة التطبيقات التاليتَين:
2. تحويل الكلام إلى نص
3. مستندات Google

أنت الآن جاهز للمتابعة وبدء العمل على الرمز.

3- إعداد الرمز

الحصول على الرمز النموذجي

للحصول على رمز نموذجي، يمكنك إما تنزيل ملف ZIP على جهاز الكمبيوتر...

تنزيل ملف Zip

...أو استنسِخ مستودع GitHub من سطر الأوامر.

$ git clone [e-mail]: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" وإدارتها. إذا كان الرمز يتطلّب تفويضًا يتجاوز هذا الوصول أو يختلف عنه، احرص على تعديل هذا المتغيّر وفقًا لذلك استنادًا إلى نطاقات Google API في OAuth 2.0.

على سبيل المثال، إذا لم تكن تكتب في "مستند Google"، يمكنك تغيير النطاق إلى DOCUMENTS_READONLY. إنّ المتغيّر SCOPES ضروري ليس فقط لكي يحصل تطبيقك على أذونات الوصول المناسبة، ولكن أيضًا للحفاظ على الشفافية مع المستخدمين. يتم عرض النطاقات المحدّدة التي تطلبها للمستخدم في صفحة تأكيد OAuth حيث يجب أن يوافق على استخدام التطبيق.

إعادة تسمية المتغيّرات

تأكَّد من تحديد المتغيّرات أعلاه بشكلٍ صحيح لمشروعك.

1. تأكَّد من ضبط AUDIO_FILENAME على اسم ملف العرض التوضيحي الذي ترسله إلى Speech-to-Text API. في ملف CreateTranscript.java، من المفترض أن يظهر لك الإعداد بشكل صحيح.
2. أعِد تسمية CREDENTIALS_FILE_PATH إلى اسم ملف بيانات الاعتماد الذي تم تنزيله (يجب أن يكون ‎/credentials.json'). تأكَّد من أنّ هذا الملف موجود داخل دليل src/main/resources في مجلدك، لذا احرص على إنشاء هذا الدليل إذا لم يتم ذلك عند استنساخ GitHub.

يمكنك الآن البدء في تنفيذ الرمز.

4. إعداد برنامج "مستندات Google"

في ملف 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 (متغير). تمثّل الخدمة عميلاً معتمَدًا لواجهة برمجة التطبيقات، وهي تحتفظ ببيانات الاعتماد الخاصة بك، وفي هذه الحالة، تحتفظ بمصادقة المستخدم النهائي.

في الرمز البرمجي، يجب أن تستخدم أي دالة تُجري طلبًا إلى Docs API المتغيّر service من أجل تنفيذ المهام ذات الصلة بـ "مستندات Google".

5- إنشاء مستند Google

سيتم إنشاء مستند Google جديد بعنوان محدّد. لذا، لننسخ الرمز أدناه في الدالة createDocument.

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

تعرض هذه الدالة معرّف ملف Google Drive الخاص بمستند Google، ويمكن العثور على هذا المعرّف نفسه ضمن عنوان 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() إذا كان ملف الصوت بلغة أخرى غير الإنجليزية مثلاً، وتغيير setSampleRateHertz() إذا كان ملف الصوت يتضمّن معدّل عيّنات مختلفًا بالهرتز (1600 هو المعدّل الأمثل).

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. وبالتالي، يحتوي كل عنصر على جزأين: نسخة نصية ونتيجة الثقة المقابلة لواجهة برمجة التطبيقات.

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. لإجراء أي تعديلات على مستند، عليك استخدام طريقة BatchUpdate. BatchUpdate هي حاوية لأنواع مختلفة من طلبات الكتابة، وستستخدم هنا InsertTextRequest.

‫EndOfSegmentLocation هي مَعلمة مهمة تحدّد المكان الذي تريد طباعة النص فيه في مستند Google. في رمز المصدر، أنت تُدرج نصًا في نص مستندك.

لنُدرج الرمز أدناه في الدالة لمعرفة كيف يمكن أن تسمح لنا نتائج Speech-to-Text API المقترنة بطلبات إلى Docs API بإدراج نص ملف صوتي في مستند Google:

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

إنشاء الطلب

عند تقديم طلب BatchUpdate، عليك ضبط مواصفات مهمة جدًا، وهي: ما تريد طباعته (.setText())، والمكان الذي تريد طباعته فيه في مستندك (.setIndex(1)).

لقد أدرجت الآن نص ملفك الصوتي في مستند Google الذي أنشأته.

8. تنفيذ الرمز البرمجي

بعد أن أصبح لديك كل الرموز اللازمة للحصول على ملف صوتي، والحصول على نصّه، وطباعة النص في مستند Google تم إنشاؤه حديثًا، لنبدأ العمل!

بما أنّك ستشغّل رمز Java باستخدام نظام التصميم Gradle، عليك إخبار ملف build.gradle بما يجب إنشاؤه وتشغيله بالضبط. في هذا المشروع والمشاريع الأخرى، احرص على أن يكون mainClassName متوافقًا مع فئة Java التي تريد تشغيلها.

رائع! أنت الآن جاهز لتشغيل الرمز. لإجراء ذلك، اكتب ما يلي في سطر الأوامر:

$ gradle run

مصادقة المستخدم النهائي

في المرة الأولى التي تنفّذ فيها هذا الرمز، سيظهر لك عنوان URL مطبوع في نافذة الأوامر، وسيُطلب منك تسجيل الدخول إلى حساب الخدمة ومنح الإذن بالوصول إلى مستندات Google الخاصة به. بعد السماح بالوصول، ستلاحظ ملفًا جديدًا مخزّنًا في دليلك.

داخل دليل العمل، سيظهر لك مجلد تم إنشاؤه حديثًا بعنوان tokens، ويحتوي على ملف StoredCredential. هذا هو رمز المصادقة الذي قدّمته للتو، والذي طلبه عميلك من خادم مصادقة Google، وتم استخراجه من الردّ، وسيتم إرساله الآن إلى أي واجهة برمجة تطبيقات تستخدمها.

الحل

إذا لم يكن الرمز يعمل، ألقِ نظرة على ملف CreateTranscript.java داخل مجلد finish. يحتوي هذا الملف على جميع الرموز البرمجية بالطريقة التي يجب أن تكون عليها لكي يتم تشغيلها بنجاح.

لنلقِ نظرة الآن على النتيجة.

9. عرض نتائجك

لقد أنشأت للتو مستند Google جديدًا يحتوي على نص ملفك الصوتي، لذا لنلقِ نظرة عليه.

تم إنشاء مستند Google هذا من خلال الحساب الذي منح المستخدم النهائي الإذن باستخدامه. أحد التوسّعات المحتملة هو أنّه يمكنك مشاركة هذا المستند تلقائيًا مع الآخرين باستخدام Drive API.

باستخدام الرمز المصدر وملف الصوت المقدَّم، إليك ما يجب أن يظهر لك:

10. تهانينا!

لقد تعلّمت الآن كيفية إنشاء مستند Google وإجراء طلب إلى Speech-to-Text API وإخراج نص ملفك الصوتي إلى المستند الذي أنشأته.

التحسينات المحتملة

في ما يلي بعض الأفكار حول كيفية إنشاء عملية دمج أكثر إقناعًا:

• إعداد الرمز البرمجي للاستماع إلى وقت إضافة ملف صوتي إلى حزمة Google Cloud Storage في Drive، وتفعيل Google Cloud Function لتنفيذ هذا الرمز
• جرِّب إدراج نص في مستند Google غير فارغ

مزيد من المعلومات

• قراءة مستندات مطوّري برامج Google Docs API
• طرح الأسئلة والعثور على إجابات على Stack Overflow ضمن العلامة google-docs-api