GSP125

概览

借助 Google Cloud Speech 流式传输 API，开发者可以实时将语音内容转换为文本。通过将该 API 与 JavaScript 的 Web Audio API 和 WebSocket 结合使用，Java Servlet 可以接受来自网页的流式传输语音，并提供相应的转写文稿，使任何网页都能将语音内容作为额外的界面使用。

本实验分为多个部分，每个部分介绍最终 Web 应用的一个组件。

您创建的 Web 应用会从客户端的麦克风获取音频，并将其流式传输到 Java Servlet。Java Servlet 将数据传递给 Cloud Speech API，后者会将检测到的任何语音的转写内容以流式传输方式返回给 Servlet。然后，Servlet 将转写结果传递给客户端，后者则会在网页上显示相应结果。

为此，您需要创建以下几种组件：

• Java Servlet，用于为网页提供静态 HTML、JavaScript 和 CSS。
• JavaScript、HTML 和 CSS，用于将网页连接到用户的麦克风、提取原始字节并通过 WebSocket 将其传输到 Servlet。
• Servlet WebSocket 处理程序，用于将从客户端接收的声音字节流式传输到 Cloud Speech API，并将 Cloud Speech API 生成的转写结果以流式传输方式返回给客户端。

您将执行的操作

• 创建虚拟机 (VM)
• 启动 HTTP Java Servlet
• 在网页上捕获音频
• 将音频转写为文本

前提条件

本实验假设您熟悉以下内容：

• Java 编程语言。
• Java Servlet（具体而言，是 Jetty Servlet 容器）。可以使用其他 Servlet 容器，但示例解决方案使用的是 Jetty，因此，使用其他容器的解决方案会更难进行验证。
• JavaScript 编程语言。网页的代码几乎都是用 JavaScript 编写的，有关网页的实验就很难避免使用它。
• Linux 命令行。本实验的大部分操作都是在 Linux 命令提示符下完成的，熟悉该环境的一些常用工具和文本编辑器可让您更轻松地完成实验。
• Maven 项目管理工具。原则上可以使用任何 Java 项目管理工具，但示例解决方案使用的是 Maven，因此，使用其他工具的解决方案会更难进行验证。

设置和要求

点击“开始实验”按钮前的注意事项

请阅读以下说明。实验是计时的，并且您无法暂停实验。计时器在您点击开始实验后即开始计时，显示 Google Cloud 资源可供您使用多长时间。

此实操实验可让您在真实的云环境中开展实验活动，免受模拟或演示环境的局限。为此，我们会向您提供新的临时凭据，您可以在该实验的规定时间内通过此凭据登录和访问 Google Cloud。

为完成此实验，您需要：

• 能够使用标准的互联网浏览器（建议使用 Chrome 浏览器）。

注意：请使用无痕模式（推荐）或无痕浏览器窗口运行此实验。这可以避免您的个人账号与学生账号之间发生冲突，这种冲突可能导致您的个人账号产生额外费用。

• 完成实验的时间 - 请注意，实验开始后无法暂停。

注意：请仅使用学生账号完成本实验。如果您使用其他 Google Cloud 账号，则可能会向该账号收取费用。

如何开始实验并登录 Google Cloud 控制台

1. 点击开始实验按钮。如果该实验需要付费，系统会打开一个对话框供您选择支付方式。左侧是“实验详细信息”窗格，其中包含以下各项：

   • “打开 Google Cloud 控制台”按钮
   • 剩余时间
   • 进行该实验时必须使用的临时凭据
   • 帮助您逐步完成本实验所需的其他信息（如果需要）

2. 点击打开 Google Cloud 控制台（如果您使用的是 Chrome 浏览器，请右键点击并选择在无痕式窗口中打开链接）。

   该实验会启动资源并打开另一个标签页，显示“登录”页面。

   提示：将这些标签页安排在不同的窗口中，并排显示。

   注意：如果您看见选择账号对话框，请点击使用其他账号。

3. 如有必要，请复制下方的用户名，然后将其粘贴到登录对话框中。

   {{{user_0.username | "<用户名>"}}}

   您也可以在“实验详细信息”窗格中找到“用户名”。

4. 点击下一步。

5. 复制下面的密码，然后将其粘贴到欢迎对话框中。

   {{{user_0.password | "<密码>"}}}

   您也可以在“实验详细信息”窗格中找到“密码”。

6. 点击下一步。

   重要提示：您必须使用实验提供的凭据。请勿使用您的 Google Cloud 账号凭据。 注意：在本实验中使用您自己的 Google Cloud 账号可能会产生额外费用。

7. 继续在后续页面中点击以完成相应操作：

   • 接受条款及条件。
   • 由于这是临时账号，请勿添加账号恢复选项或双重验证。
   • 请勿注册免费试用。

片刻之后，系统会在此标签页中打开 Google Cloud 控制台。

注意：如需访问 Google Cloud 产品和服务，请点击导航菜单，或在搜索字段中输入服务或产品的名称。

任务 1. 创建虚拟机

Compute Engine 是一项服务，可用于在 Google 基础设施上启动虚拟机。在本实验中，您将创建虚拟机，并通过它来运行用 Java 8 编写的 Servlet；该 Servlet 托管网站并使用 Cloud Speech API 向客户端提供动态转写服务。在本实验中，您还将使用虚拟机运行代码。

1. 创建新的虚拟机，方法是依次点击导航菜单 () > Compute Engine > 虚拟机实例。

2. 创建新实例，方法是点击创建实例。

3. 在机器配置中，

   • 将新实例命名为 speaking-with-a-webpage。

   • 选择一个可用区作为 。

   • 将其他值保留为默认值。

4. 点击操作系统和存储空间。

   • 点击更改开始配置启动磁盘，并选择以下各项的值：

     • 对于操作系统，选择 Debian。

     • 对于版本，选择 Debian GNU/Linux 12 (bookworm)。

     • 将启动磁盘类型保留为默认设置。

     • 在窗口底部，点击选择。

5. 点击网络。

   • 对于防火墙，选中允许 HTTP 流量和允许 HTTPS 流量复选框。

6. 点击安全。

   • 对于身份和 API 访问权限 > 服务账号，保留默认设置。

   • 对于访问权限范围，选择授予对所有 Cloud API 的完整访问权限。

7. 点击创建。

几分钟后，您的虚拟机会启动并正常运行！在虚拟机实例列表中查看您的虚拟机及其详细信息。请注意 SSH 按钮（将在下一步中使用）和外部 IP（将在本实验的后续步骤中使用）。

8. 点击实例右侧的 SSH 按钮与之连接。如果看到提示，请点击授权。

系统会打开一个新窗口，将您连接到这个虚拟机，同时提供命令提示符。您会在本实验的其余部分使用此界面。

验证您已完成的任务

点击检查我的进度，验证您已完成的任务。

创建虚拟机

相关文档

如需详细了解 Compute Engine 及其各种功能，请参阅 Compute Engine 参考文档。

任务 2. 下载并设置实际示例

1. 在 SSH 会话中，安装 Git、Java 17 和 Maven 项目管理工具，以编译并运行示例代码：

sudo apt update && sudo apt install git -y sudo apt install -y maven openjdk-17-jdk 注意：此命令可能需要几分钟时间才能执行完毕。

2. 将实际示例克隆到您的虚拟机：

git clone https://github.com/googlecodelabs/speaking-with-a-webpage.git

这会创建目录 speaking-with-a-webpage，其中包含与以下各部分对应的子目录。每个子目录都基于前一个子目录构建，逐步添加新功能：

• 01-hello-https - 包含一个带有静态文件的最小 Jetty Servlet，以及一个通过 HTTPS 传送的处理程序
• 02-webaudio - 完善客户端 JavaScript 代码，用于从客户端麦克风录制音频，并显示可视化效果以确认其正常运行
• 03-websockets - 修改客户端和服务器，以便通过 WebSocket 相互通信
• 04-speech - 修改服务器，从而将音频发送到 Cloud Speech API，并将后续转写内容发送到 JavaScript 客户端

出于开发目的，本实验所用的示例不使用常规 HTTPS 端口，而是非特权端口 8443。

3. 若要从网络浏览器访问此端口，使用以下 gcloud 命令打开虚拟机的防火墙：

gcloud compute firewall-rules create dev-ports \ --allow=tcp:8443 \ --source-ranges=0.0.0.0/0 注意：您可以比较各个步骤之间的变化。

如果需要比较一个部分与下一个部分之间的变化，可以使用以下命令：

cd ~/speaking-with-a-webpage

git diff --no-index 01-hello-https/ 02-webaudio/

这会显示 02-https 和 03-webaudio 目录/步骤之间的差异。

使用箭头键、PgUp/PgDn 进行导航，按 q 退出。

验证您已完成的任务

点击检查我的进度，验证您已完成的任务。

安装必要的软件并创建防火墙规则

任务 3. 启动 HTTPS Java Servlet

Java Servlet 是支持此 Web 应用的支柱，因为它提供所需的客户端 HTML、CSS 和 JavaScript 代码，并连接到 Cloud Speech API 以提供转写功能。

当从网页访问用户的麦克风时，浏览器要求网页通过安全信道进行通信，以防止窃听。因此，请将 Servlet 设置为通过 HTTPS 传送网页。由于配置和传送安全网页本身就是一个独立的主题，因此在本实验中，请使用所提供示例解决方案中的自签名证书和 Jetty 配置文件，这足以满足开发环境的需求。

对于本部分，只需通读并运行 01-hello-https 中提供的 Maven 项目即可。请特别注意 src/ 目录中的文件，因为它们是后续步骤中进行构建所用的主要文件：

• src/main/webapp 中的文件包括由 Jetty 静态传送的 JavaScript、CSS 和 HTML 文件
• TranscribeServlet.java 定义的 Servlet 用于处理对路径 /transcribe 的请求

运行示例解决方案

在提供的 speaking-with-a-webpage 代码库中，01-hello-https 子目录包含一个针对 HTTPS 配置的 Maven Servlet 项目。此 Servlet 使用 Jetty Servlet 框架传送静态文件和动态端点。它还使用上述博文中的内容，通过 Key Tool 命令生成自签名证书，并添加 Jetty 配置以支持 HTTPS。

1. 启动 Servlet。前往 01-hello-https。

cd ~/speaking-with-a-webpage/01-hello-https

2. 运行代码：

mvn clean jetty:run

3. 通过网络浏览器访问此网址：https://<your-external-ip>:8443

注意：您可以在 Cloud 控制台的“虚拟机实例”页面上找到外部 IP 地址。

由于示例 Servlet 正在监听非标准端口，因此直接点击外部 IP 链接并不能引导您访问正在运行的 Servlet。您必须添加相关端口（如上所示），才能访问 Servlet。

当您首次通过 HTTPS 网址访问该 Web 应用时，浏览器可能会发出警告：该连接不是私密连接。这是因为示例应用在开发时使用了自签名 SSL 证书。在生产环境中，您需要使用由证书授权机构签名的 SSL 证书，但就本实验而言，自签名 SSL 证书就已够用。请务必注意，不要在网页上透露任何机密信息。😁

验证您已完成的任务

点击检查我的进度，验证您已完成的任务。

运行示例解决方案 (hello-https)

任务 4. 在网页上捕获音频

Web Audio API 允许网页在征得用户同意的情况下从用户的麦克风捕获音频数据。Cloud Speech API 需要这些原始数据以特定格式提供，并且需要知道其采样率。

示例解决方案

在提供的 speaking-with-a-webpage 代码库中，02-webaudio 子目录基于 01-hello-https 示例代码构建：通过添加 Web Audio getUserMedia 函数，将用户的麦克风连接到音频的可视化效果。然后，它会向音频流水线添加 ScriptProcessorNode，以检索原始音频字节，为将其发送到服务器做准备。由于 Cloud Speech API 最终也需要 sampleRate，因此也会一并检索。按如下方式启动 02-webaudio 应用：

1. 按 CTRL+C 以停止服务器。

2. 前往包含 02-webaudio 的目录：

cd ~/speaking-with-a-webpage/02-webaudio

3. 运行应用：

mvn clean jetty:run

4. 访问正在运行的 Web 应用，方法是在 Cloud 控制台的“虚拟机实例”页面中查找外部 IP 地址，然后通过浏览器访问如下网址：https://<your-external-ip>:8443

注意：您可以运行以下命令，查看上一部分 (01-hello-https) 与当前部分 (02-webaudio) 之间的变化：

cd ~/speaking-with-a-webpage git diff --no-index 01-hello-https/ 02-webaudio/

验证您已完成的任务

点击检查我的进度，验证您已完成的任务。

运行示例解决方案，在网页上捕获音频

5. 按 CTRL+C 以停止服务器。

任务 5. 将音频从客户端流式传输到服务器

常规 HTTP 连接并不适合将音频实时流式传输到服务器，同时接收可用转写内容。在本部分中，您将创建从客户端到服务器的 WebSocket 连接，并使用该连接将音频元数据（即采样率）和数据发送到服务器，同时监听响应（即数据的转写内容）。

流式传输音频字节

提供的示例将 TranscribeServlet 更改为从 WebSocketServlet 扩展，以便注册 WebSocketAdapter。它定义的 WebSocketAdapter 仅接收消息并将其发送回客户端。

在客户端，该示例将上一步中的 scriptNode 替换为用于将数据发送到稍后要定义的套接字的节点。然后，它会创建与服务器的安全 WebSocket 连接。服务器和麦克风都连接后，它会开始监听来自服务器的消息，然后将采样率发送给服务器。当服务器回传采样率时，客户端会使用更持久的转写处理程序替换监听器，并连接 scriptNode，开始向服务器流式传输音频字节。

1. 前往包含 03-websockets 的目录：

cd ~/speaking-with-a-webpage/03-websockets

2. 运行应用：

mvn clean jetty:run

3. 访问正在运行的 Web 应用，方法是在 Cloud 控制台的“虚拟机实例”页面中查找外部 IP 地址，然后通过浏览器访问如下网址：https://<your-external-ip>:8443

4. 按 CTRL+C 以停止服务器。

任务 6. 将音频转写为文本

借助 Google Cloud Speech 流式传输 API，您可以实时向该 API 发送音频字节，并异步接收其检测到的任何语音的转写内容。该 API 希望音频字节采用特定格式，具体由在请求开头发送的配置决定。对于此 Web 应用，您需要向该 API 发送 LINEAR16 格式的原始音频样本，即每个样本都是一个 16 位有符号整数，并以客户端获取的采样率发送。

示例解决方案

在提供的 speaking-with-a-webpage 代码库中，04-speech 子目录会填充 03-websockets 步骤中的服务器代码。它包含了上述 StreamingRecognizeClient 示例代码中的代码，用于连接 Cloud Speech API、向其传递音频字节，并从其接收转写内容。它异步接收到转写内容后，会使用与 JavaScript 客户端的连接传递这些内容。JavaScript 客户端只需将其输出到网页上。

1. 启动该应用：

cd ~/speaking-with-a-webpage/04-speech mvn clean jetty:run

2. 访问正在运行的 Web 应用，方法是在 Cloud 控制台的“虚拟机实例”页面中查找外部 IP 地址，然后通过浏览器访问如下网址：https://<your-external-ip>:8443

任务 7. 检验您的掌握情况

下面的选择题可加强您对本实验所涉概念的理解。请尽您所能回答。

恭喜！

您已了解如何使用 gcloud 创建虚拟机并启动 Java Servlet，以便在网页上捕获音频并转写为文本！

后续步骤/了解详情

思考一下可以对软件进行哪些改进：

• 该客户端应用目前仅能输出文本，但它可用于多种用途；可以把它看作是另一个界面。关键字可以调用某些操作，您可以将文本与对话引擎集成，也可以直接将其用于字幕。
• 将转写内容与 Cloud Natural Language API 集成，后者可以从原本非结构化的文本中提取结构。
• Cloud Speech API 支持 80 多种语言，您可以通过简单的配置参数选择相应语言。快用您会说的另一种语言或正在学习的语言试试吧！
• 当前项目设置主要适用于开发目的，在部署到生产环境时应进行更改。例如，您可以在一个实例组中使用多个 Compute Engine 实例，并使用 SSL 负载均衡器在客户端和服务器之间提供安全通信。

Google Cloud 培训和认证

…可帮助您充分利用 Google Cloud 技术。我们的课程会讲解各项技能与最佳实践，可帮助您迅速上手使用并继续学习更深入的知识。我们提供从基础到高级的全方位培训，并有点播、直播和虚拟三种方式选择，让您可以按照自己的日程安排学习时间。各项认证可以帮助您核实并证明您在 Google Cloud 技术方面的技能与专业知识。

本手册的最后更新时间：2025 年 9 月 15 日

本手册的最后测试时间：2025 年 9 月 15 日

版权所有 2025 Google LLC 保留所有权利。Google 和 Google 徽标是 Google LLC 的商标。其他所有公司名和产品名可能是其各自相关公司的商标。