第 34-36 章先看这一张图#

三章各自只负责一个边界。不要把三个接口都当成“一个语音模型”：

公共环境变量集中在 .env.example。先复制为 .env，再只填写本章实际需要的项。

本章在课程中的位置#

第 33 章的输入是图片：

1
图片 -> image content block -> 视觉模型 -> 文字

本章把音频先转换成文本：

1
音频文件 -> STT/ASR 接口 -> transcript 文本 -> 现有文本模型、RAG 或 Agent

本章产物：

• 最小示例：app/multimodal_stt_demo.py
• 当前讲义：本文件

官方依据与版本边界#

本章示例按 OpenRouter 当前官方音频接口编写：

• OpenRouter Speech-to-Text 指南：使用 /api/v1/audio/transcriptions，音频以 Base64 放入 input_audio，返回带 text 的 JSON。
• OpenRouter transcription API reference：列出 model、input_audio、language 和响应字段。
• OpenRouter 多模态总览：说明 STT 是独立端点，不等同于把音频放进普通文本消息。

模型名称、价格、支持格式和语言能力会变化。以模型页面和接口返回为准；本章不要求背某个具体模型名称。

第一关：先建立心智模型#

1
音频 bytes -> Base64 字符串 -> JSON input_audio.data

第二关：先看真实代码形状#

打开 app/multimodal_stt_demo.py，先只看主链路：

1
audio_bytes = Path(audio_path).read_bytes()
2
encoded_audio = base64.b64encode(audio_bytes).decode("ascii")
3

4
payload = {
5
    "model": model,
6
    "input_audio": {
7
        "data": encoded_audio,
8
        "format": "wav",
9
    },
10
}
11

12
response = client.post(
13
    f"{OPENROUTER_BASE_URL}/audio/transcriptions",
14
    headers={"Authorization": f"Bearer {api_key}"},
15
    json=payload,
16
)
17
response.raise_for_status()
18
transcript = response.json()["text"]

逐步追踪：

1. read_bytes() 把文件读成 bytes，此时还不是文本。
2. b64encode() 把字节编码成 Base64 字节串。
3. decode("ascii") 把 Base64 字节串变成 Python str，这样才能放进 JSON。
4. input_audio.data 是音频数据，input_audio.format 告诉服务端如何解释数据。
5. client.post(..., json=payload) 发出 HTTP JSON 请求。
6. raise_for_status() 检查 HTTP 状态码，4xx/5xx 时抛出异常。
7. response.json() 把响应 JSON 解析成 Python 对象。
8. result["text"] 是转录文本，它可以继续进入已有的 RAG 或 Agent。

完整数据流：

1
Path
2
  -> bytes
3
  -> Base64 str
4
  -> payload: dict
5
  -> HTTP POST
6
  -> response JSON
7
  -> transcript: str

第三关：STT 接口和普通聊天接口有什么区别#

普通聊天通常是：

1
messages -> /chat/completions -> assistant message

本章的 STT 是：

1
input_audio -> /audio/transcriptions -> {"text": "..."}

STT 返回的是结构化转录结果，不是 AIMessage。因此它通常先作为一个“输入转换步骤”，之后再交给文本模型：

1
transcript = transcribe_audio("voice.wav")
2
answer = text_agent.invoke({"messages": [
3
    {"role": "user", "content": transcript}
4
]})

这里的关键不是“音频模型替代 Agent”，而是：

STT 把一种输入模态转换为文本，后面的文本 RAG/Agent 可以继续复用。

第四关：配置并运行#

在 .env 中配置：

1
OPENROUTER_API_KEY=你的密钥
2
STT_MODEL=你的STT模型标识
3
STT_LANGUAGE=zh
4
STT_AUDIO_PATH=samples/voice.wav

模型标识从 OpenRouter 的 STT 模型列表确认，也可以查询：

1
curl "https://openrouter.ai/api/v1/models?output_modalities=transcription"

运行：

1
poetry run python -m app.multimodal_stt_demo

成功时打印：

1
这是音频里的转录内容。

第五关：把转录文本接入已有能力#

本章不重新实现 RAG。接入位置是 STT 返回之后：

1
transcript = transcribe_audio(audio_path)
2

3
# 这里可以换成你已经学过的 RAG 或 Agent 调用。
4
answer = await ask_existing_rag(transcript)

服务端真实边界应当是：

1
上传文件
2
  -> 校验用户权限、扩展名、MIME、大小和时长
3
  -> STT
4
  -> transcript
5
  -> RAG/Agent
6
  -> 文本回答

不要把未经限制的用户文件直接转发给外部模型。音频可能包含隐私，日志中不要保存原始音频、完整 Base64 或 API Key。

第六关：三遍主动练习#

1
print(f"转录长度：{len(transcript)}")

1
def transcribe_for_rag(audio_path: str) -> str:
2
    """把音频转成可交给 RAG 的问题文本。"""

常见坑#

本章压缩回顾#

1
音频 bytes
2
  -> Base64
3
  -> input_audio JSON
4
  -> STT endpoint
5
  -> response.json()["text"]
6
  -> 文本 RAG / Agent

本章完成后，你要能区分：

• 音频数据和转录文本不是同一种数据。
• Base64 是传输编码，不是安全保护。
• STT 是输入转换步骤，不是完整 Agent。
• 语音转文字成功后，已有文本 RAG/Agent 可以继续使用。

本章通过标准#

• 能解释 STT、ASR、transcript 和 Base64。
• 能读懂 bytes -> Base64 -> JSON -> text 的数据流。
• 能独立调用一次 STT 接口并拿到 str。
• 能说明 STT 与聊天模型、RAG、Agent 的职责边界。
• 能为音频输入增加大小、格式和隐私校验。

下一章学习反方向：把文本转换为音频，也就是 TTS。