第47篇：使用Speech-to-Text API快速构建语音应用（操作教程）

文章目录

• • 前言
  • 环境准备
  • 分步操作
  • • 步骤一：基础语音识别（同步）
    • 步骤二：处理长音频（异步）
    • 步骤三：实时语音识别（流式）
  • 完整代码与项目结构
  • 踩坑提示
  • 总结

前言

在做一个智能客服项目时，我需要处理大量的用户语音咨询。一开始尝试用开源模型自己搭，光是解决不同口音和背景噪音的问题就折腾了好几周，效果还不理想。后来我直接转向了云服务商提供的 Speech-to-Text (STT) API，开发效率瞬间提升了一个量级。今天这篇教程，我就以 Google Cloud 的 Speech-to-Text API 为例，带你从零开始，快速构建一个可用的语音转文字应用。你会发现，利用成熟的 API 服务，能让你绕过很多底层算法的"坑"，把精力集中在业务逻辑上。

环境准备

在开始敲代码之前，我们需要把"战场"布置好。这里主要分为两步：在云平台创建项目、获取认证凭证，以及在本地配置开发环境。

1. 创建 Google Cloud 项目并启用 API

• 访问 Google Cloud Console。
• 创建一个新项目（例如 my-speech-demo），或者选择一个现有项目。
• 在左侧导航栏找到 "API 和服务" > "库"。
• 搜索 "Cloud Speech-to-Text API" ，点击进入并 "启用" 该服务。

2. 创建服务账号密钥（关键步骤）

这是本地代码调用云端 API 的通行证，很多新手在这里会卡住。

• 在"API 和服务"中，进入 "凭据" 页面。
• 点击 "创建凭据" ，选择 "服务账号"。
• 填写服务账号名称和 ID，角色可以选择 "项目 > 所有者"（仅用于测试，生产环境应遵循最小权限原则）。
• 创建完成后，在服务账号列表中找到刚创建的账号，点击其邮箱进入详情页。
• 切换到 "密钥" 标签页，点击 "添加密钥" > "创建新密钥" ，密钥类型选择 JSON。
• 下载生成的 JSON 私钥文件，并妥善保存 。我将它重命名为 service-account-key.json，放在项目根目录下。

3. 本地 Python 环境配置

确保你的机器上安装了 Python 3.7+。我们创建一个干净的虚拟环境并安装必要的包。

# 创建并进入项目目录
mkdir speech-to-text-demo && cd speech-to-text-demo

# 创建虚拟环境（可选但推荐）
python3 -m venv venv
# 激活虚拟环境
# Windows: venv\Scripts\activate
# Mac/Linux: source venv/bin/activate

# 安装 Google Cloud 语音客户端库
pip install google-cloud-speech

分步操作

步骤一：基础语音识别（同步）

我们从最简单的同步识别开始。这种方式适用于短音频（小于1分钟），API会等待整个音频处理完毕后才返回结果。

首先，设置环境变量，指向你的密钥文件。这是让客户端库自动找到凭证的方法。

# 在终端中执行，注意替换为你的实际路径
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

# 在Windows PowerShell中，使用：
# $env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\service-account-key.json"

接下来，创建第一个识别脚本 sync_recognize.py：

# sync_recognize.py
import io
from google.cloud import speech

def transcribe_file(speech_file):
    """同步识别一个本地音频文件。"""
    # 实例化客户端
    client = speech.SpeechClient()

    # 读取音频文件到内存
    with io.open(speech_file, "rb") as audio_file:
        content = audio_file.read()

    # 构建音频对象，指定编码和采样率
    # 这里以单声道、16kHz采样的FLAC文件为例，这是API推荐的格式之一
    audio = speech.RecognitionAudio(content=content)
    
    # 配置识别参数
    config = speech.RecognitionConfig(
        encoding=speech.RecognitionConfig.AudioEncoding.FLAC,
        sample_rate_hertz=16000,
        language_code="zh-CN",  # 中文普通话
        # 可选：启用自动标点，使结果更可读
        enable_automatic_punctuation=True,
    )

    # 发起同步识别请求
    response = client.recognize(config=config, audio=audio)

    # 处理并打印结果
    for result in response.results:
        # result.alternatives 是一个列表，按置信度排序
        print(f"转录文本: {result.alternatives[0].transcript}")
        print(f"置信度: {result.alternatives[0].confidence:.2%}")

if __name__ == "__main__":
    # 准备一个测试音频文件，例如 record.flac
    transcribe_file("record.flac")

运行它： 将一个短音频文件（FLAC格式，16kHz采样）命名为 record.flac 放在同目录，然后执行 python sync_recognize.py。你应该能看到转写出的文字和置信度。

步骤二：处理长音频（异步）

如果音频超过1分钟，必须使用异步识别。API会立即返回一个操作名（operation name），你需要用这个操作名去轮询获取结果。

创建 async_recognize.py：

# async_recognize.py
from google.cloud import speech
import time

def transcribe_long_file(gcs_uri):
    """异步识别一个存储在Google Cloud Storage中的长音频文件。"""
    client = speech.SpeechClient()

    # 配置参数，与同步类似
    config = speech.RecognitionConfig(
        encoding=speech.RecognitionConfig.AudioEncoding.FLAC,
        sample_rate_hertz=16000,
        language_code="zh-CN",
        enable_automatic_punctuation=True,
    )

    # 注意：这里 audio 的 source 是 Google Cloud Storage 的 URI
    audio = speech.RecognitionAudio(uri=gcs_uri)

    # 发起异步请求，返回的是一个 Operation 对象
    operation = client.long_running_recognize(config=config, audio=audio)

    print("正在处理长音频，请等待...")
    # 等待操作完成，这是一个阻塞调用
    response = operation.result(timeout=90)  # 设置超时时间，单位秒

    # 将结果写入文件
    with open("long_transcript.txt", "w", encoding="utf-8") as f:
        for result in response.results:
            transcript = result.alternatives[0].transcript
            f.write(transcript + "\n")
            print(f"片段转录: {transcript}")

    print("完整转录已保存至 'long_transcript.txt'")

if __name__ == "__main__":
    # 你需要先将长音频文件上传到 Google Cloud Storage
    # 格式：gs://你的存储桶名/音频文件路径.flac
    uri = "gs://my-speech-bucket/long-audio.flac"
    transcribe_long_file(uri)

关键点： 异步识别要求音频文件必须放在 Google Cloud Storage (GCS) 上，不能使用本地文件。你需要先创建一个GCS存储桶并上传文件。

步骤三：实时语音识别（流式）

这是最酷的部分，可以实现像语音助手那样的实时转写。它基于 gRPC 流，能够一边接收音频流，一边返回中间和最终结果。

创建 streaming_recognize.py：

# streaming_recognize.py
import pyaudio  # 需要安装：pip install pyaudio
from six.moves import queue
from google.cloud import speech

class MicrophoneStream:
    """开一个线程从麦克风读取音频数据到缓冲区。"""
    def __init__(self, rate, chunk):
        self._rate = rate
        self._chunk = chunk
        self._buff = queue.Queue()
        self.closed = True

    def __enter__(self):
        self._audio_interface = pyaudio.PyAudio()
        self._audio_stream = self._audio_interface.open(
            format=pyaudio.paInt16,
            channels=1,  # 单声道
            rate=self._rate,
            input=True,
            frames_per_buffer=self._chunk,
            stream_callback=self._fill_buffer,
        )
        self.closed = False
        return self

    def __exit__(self, type, value, traceback):
        self._audio_stream.stop_stream()
        self._audio_stream.close()
        self.closed = True
        self._buff.put(None)  # 发送结束信号
        self._audio_interface.terminate()

    def _fill_buffer(self, in_data, frame_count, time_info, status_flags):
        """回调函数，将麦克风数据放入队列。"""
        self._buff.put(in_data)
        return None, pyaudio.paContinue

    def generator(self):
        """生成音频数据块的生成器。"""
        while not self.closed:
            chunk = self._buff.get()
            if chunk is None:
                return
            data = [chunk]
            while True:
                try:
                    chunk = self._buff.get(block=False)
                    if chunk is None:
                        return
                    data.append(chunk)
                except queue.Empty:
                    break
            yield b''.join(data)

def listen_print_loop(responses):
    """迭代流式响应并打印结果。"""
    for response in responses:
        if not response.results:
            continue
        result = response.results[0]
        if not result.alternatives:
            continue

        transcript = result.alternatives[0].transcript
        # 检查是否是临时结果（is_final=False）
        if result.is_final:
            print(f"\n最终结果: {transcript}")
            # 这里可以加入业务逻辑，例如触发命令
            if "停止" in transcript:
                print("检测到停止指令，退出。")
                break
        else:
            # 临时结果，可以显示在UI上作为实时反馈
            print(f"正在聆听: {transcript}", end='\r')

def main():
    # 音频流参数
    RATE = 16000
    CHUNK = int(RATE / 10)  # 100ms 的块

    # 流式识别配置
    client = speech.SpeechClient()
    config = speech.RecognitionConfig(
        encoding=speech.RecognitionConfig.AudioEncoding.LINEAR16,
        sample_rate_hertz=RATE,
        language_code="zh-CN",
        enable_automatic_punctuation=True,
        # 流式识别建议使用增强模型
        model="command_and_search",  # 适用于短命令，对"打开灯光"这类短语优化
        use_enhanced=True,
    )
    streaming_config = speech.StreamingRecognitionConfig(
        config=config,
        interim_results=True,  # 关键！设置为True以获取中间结果
    )

    with MicrophoneStream(RATE, CHUNK) as stream:
        audio_generator = stream.generator()
        requests = (
            speech.StreamingRecognizeRequest(audio_content=content)
            for content in audio_generator
        )
        responses = client.streaming_recognize(streaming_config, requests)
        # 开始监听和打印
        listen_print_loop(responses)

if __name__ == "__main__":
    main()

运行这个脚本，对着麦克风说话，你会看到实时的转写文字在终端上滚动，说完后约半秒会输出最终结果。这是构建语音交互应用的基石。

完整代码与项目结构

一个典型的语音应用项目结构可能如下：

speech-app/
├── service-account-key.json  # 密钥文件（.gitignore 忽略！）
├── requirements.txt
├── src/
│   ├── __init__.py
│   ├── sync_recognizer.py    # 封装同步识别
│   ├── async_recognizer.py   # 封装异步识别
│   ├── stream_recognizer.py  # 封装流式识别
│   └── utils/
│       └── audio_utils.py    # 音频格式转换、预处理
└── examples/
    ├── transcribe_short.py   # 示例：处理短录音
    ├── transcribe_podcast.py # 示例：处理长音频（播客）
    └── live_caption.py       # 示例：实时字幕生成

requirements.txt 内容：

google-cloud-speech>=2.0.0
pyaudio>=0.2.11

踩坑提示

根据我的实战经验，以下几个坑你大概率会遇到：

1. 认证失败 ：google.auth.exceptions.DefaultCredentialsError。这是头号杀手。请务必检查：

   • 环境变量 GOOGLE_APPLICATION_CREDENTIALS 的路径是否正确、文件名是否拼写错误。
   • 密钥文件对应的服务账号是否已启用，且所在项目是否已启用 Speech-to-Text API。
   • 有时在 IDE 中运行，环境变量可能未加载，尝试在终端直接激活环境后运行脚本。

2. 音频格式问题：API 对音频编码、采样率、声道数有要求。常见的错误是采样率不匹配。

   • 最佳实践 ：上传前，使用 ffmpeg 统一将音频转换为单声道、16kHz 采样率的 FLAC 或 LINEAR16 (WAV) 格式。

   ffmpeg -i input.mp3 -ar 16000 -ac 1 output.flac

3. 流式识别延迟或中断：在开发流式应用时，网络不稳定或音频块大小不合适会导致连接断开或延迟高。

   • 调整 CHUNK 大小：示例中的 100ms (RATE/10) 是个不错的起点，可以根据网络情况微调。
   • 处理网络重连 ：生产环境需要在 responses 迭代中加入异常捕获和重连逻辑。

4. 费用控制：API 按处理时长收费。在开发和测试阶段，注意：

   • 使用较短的音频文件。
   • 设置预算提醒（在 GCP 控制台"预算和提醒"中设置）。
   • 本地可以先做简单的 VAD（语音活动检测），只上传有声音的片段。

总结

通过这篇教程，我们走完了使用 Speech-to-Text API 构建语音应用的完整路径：从环境配置、同步/异步识别到最复杂的流式识别。云服务 API 的强大之处在于，它把顶尖的语音识别能力封装成了简单的函数调用，让我们能快速实现产品原型并验证想法。

记住，同步用于短音频，异步用于长文件，流式用于实时交互。选择哪种方式，完全取决于你的应用场景。下一步，你可以尝试将识别结果接入到 NLP 模型（如意图识别）或 TTS（文本转语音）模块，构建一个完整的语音对话系统。

如有问题欢迎评论区交流，持续更新中...