使用 Google 文档和创建商务会议的转写内容；机器学习

1. 概览

在此 Codelab 中，您将学习如何通过 Google Cloud Speech to Text API 发送音频文件，然后将转写内容输出到 Google 文档。Speech to Text API 易于使用，并且可以应用强大的神经网络，使开发者能够将音频转文字！此外，它依托于机器学习技术。

您将使用 Google 文档 API 创建新文档以及向新文档写入内容。您将创建一个 Java 命令行应用，并使用 Gradle 构建系统运行代码，然后使用 Google 文档 API 查看您的结果。

学习内容

• 如何使用 Google Cloud Speech to Text API
• 如何使用 Google 文档 API 创建新文档
• 如何使用 Google 文档 API 向文档写入内容

所需条件

• 已安装 Java（版本 7 或更高版本）
• 已安装 Gradle（版本 5 或更高版本）
• 访问互联网和网络浏览器
• Google 账号
• Google Cloud Platform 项目

2. 设置项目

创建云项目

1. 登录 Cloud 控制台，然后创建一个新项目或重复使用现有项目。 （如果您还没有 Gmail 或 Workspace 账号，则必须创建一个）。

注意：通过记住 Cloud Console 的网址 (console.cloud.google.com)，您可以轻松访问 Cloud Console。

请记住项目 ID，它在所有 Google Cloud 项目中都是唯一的名称（上述名称已被占用，您无法使用，抱歉！）。它稍后将在此 Codelab 中被称为 PROJECT_ID。

注意：如果您使用的是 Gmail 账号，可以将默认位置设置为无组织。如果您使用的是 Workspace 账号，请选择对贵组织来说合理的位置。

2. 接下来，您需要在 Cloud 控制台中启用结算功能，才能使用 Google Cloud 资源。

运行此 Codelab 应该不会产生太多的费用（如果有费用的话）。请务必按照“清理”部分部分，其中会指导您如何关停资源，以免产生超出本教程范围的结算费用。Google Cloud 的新用户符合参与 $300 USD 免费试用计划的条件。

获取 Cloud Speech-to-Text API 的服务账号密钥

1. 前往 GCP 控制台，找到您的新项目
2. 创建服务账号
3. 以 JSON 格式下载服务账号密钥
4. 将环境变量 GOOGLE_APPLICATION_CREDENTIALS 设置为包含服务账号密钥的 JSON 文件的文件路径。如果您重启 shell 会话，则必须重新设置该变量。

$ export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

例如：

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

获取 Google 文档 API 的凭据

1. 返回 GCP 控制台，转到凭据
2. 创建一个 OAuth 2.0 密钥并以 JSON 格式下载
3. 重命名 credentials.json 文件，并确保它位于代码的 src/main/resources/ 目录中

启用 API

1. 选择信息中心标签页，点击启用 API 和服务按钮，然后启用以下 2 个 API：
2. 语音转文字
3. Google 文档

现在，您可以继续操作并开始使用代码了。

3. 设置代码

获取示例代码

如需获取示例代码，请将 ZIP 文件下载到您的计算机上...

下载 ZIP 文件

...或者从命令行克隆 GitHub 代码库。

$ git clone [e-mail]:googleworkspace/docs-transcript-codelab.git

您将处理 start 目录下的 CreateTranscript.java 文件。请勿修改 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 文档文档。如果您的代码需要的授权超出此访问权限范围或不同于此访问权限，请务必根据 OAuth 2.0 Google API 作用域相应地调整此变量。

例如，如果您没有写入 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（变量）。该服务代表授权的 API 客户端，其中保存了您的凭据和（在本例中为最终用户身份验证）文件。

在您的代码中，任何调用 Google 文档 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 文档的云端硬盘文件 ID。同一 ID 可以在文档网址中找到。

接下来，您将初始化 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()；如果音频文件的采样率与赫兹不同（1600 是最佳选择），则需要更改 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 文档。要对文档进行任何修改，您需要使用 BatchUpdate 方法。BatchUpdate 是存放不同类型的写入请求的容器，在这里，您将使用 InsertTextRequest。

EndOfSegmentLocation 是一个重要参数，用于指定要在文档中打印文本的位置。在源代码中，您要在文档的正文中插入文本。

让我们将以下代码插入到您的函数中，看看您的 Speech-to-Text API 结果以及对 Google 文档 API 的调用如何能够让我们在 Google 文档中插入音频文件的转写内容：

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

创建请求

在发出 BatchUpdate 请求时，您需要设置两个非常重要的规范：要打印的内容 (.setText())，以及要在文档中的什么位置执行该操作 (.setIndex(1))。

现在，您已将音频文件的转写内容插入到创建的文档中。

8. 运行代码

现在，您已经拥有获取音频文件、获取其转录内容并将其转录为新建的 Google 文档所需的全部代码，接下来我们就开始操作吧！

由于您将使用 Gradle 构建系统运行 Java 代码，因此必须告知 build.gradle 文件究竟要构建和运行哪些内容。在此项目及其他项目中，请确保让 mainClassName 与要运行的 Java 类保持一致。

太棒了！现在，您可以运行代码了。为此，请在命令行中输入以下内容：

$ gradle run

最终用户身份验证

首次运行此代码时，您将看到终端中会输出一个网址，要求您登录服务账号并授予对其 Google 文档的访问权限。授予访问权限后，您会发现目录中存储了一个新文件。

在工作目录中，您会看到一个名为 tokens 的新建文件夹，其中包含文件 StoredCredential。这是您刚才提供的身份验证令牌，您的客户端从 Google Auth 服务器请求此令牌（从其响应中提取）。现在，该令牌将发送至您调用的任何 API。

解决方案

如果您的代码没有正常运行，请查看 CreateTranscript.java 文件夹内的 CreateTranscript.java 文件。此文件包含正常运行所需的全部代码。

现在，我们来看看结果。

9. 查看结果

您刚刚创建了一个包含音频文件转写文稿的新 Google 文档，我们来看一下。

此文档是通过最终用户授权时所用的账号创建的。您可以使用 Drive API 自动与他人共享此文档。

根据您的源代码和提供的音频文件，您应该会看到以下内容：

10. 恭喜！

现在，您已经学会了如何创建 Google 文档、调用 Speech-to-Text API，以及将音频文件的转写内容输出到创建的 Google 文档中。

可能的改进措施

以下是一些有关如何进行更具吸引力的集成的建议：

• 设置代码以监听将音频文件添加到 Google Cloud Storage 存储分区云端硬盘的时间，并触发 Google Cloud Functions 函数来执行此代码
• 尝试在非空 Google 文档中插入文本

了解详情

• 阅读 Google 文档 API 开发者文档
• 在 Stack Overflow 上使用 google-docs-api 标签发布问题并寻找答案