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

1. نظرة عامة

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

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

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

كيفية استخدام واجهة برمجة التطبيقات "تحويل الكلام إلى نص" في Google Cloud
كيفية استخدام 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 (الاسم أعلاه مستخدَم حاليًا ولن يكون متاحًا لك، نأسف لذلك). سيتم الإشارة إليه لاحقًا في هذا الدرس العملي باسم PROJECT_ID.

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

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

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

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

$ export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

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

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

الحصول على بيانات اعتماد لواجهة برمجة تطبيقات "مستندات Google"

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

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

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

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

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

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

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

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

تأكَّد من ضبط قيمة AUDIO_FILENAME على اسم ملف العرض التوضيحي الذي ترسله إلى Speech-to-Text API. في ملف CreateTranscript.java، من المفترض أن يظهر لك الإعداد بشكل صحيح.
أعِد تسمية 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 (متغير). تمثّل الخدمة عميل API معتمَدًا، وتحتوي على بيانات الاعتماد، وفي هذه الحالة، على مصادقة المستخدم النهائي.

في الرمز البرمجي، يجب أن تستخدم أي دالة تُجري طلبًا إلى 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