企业官网建设流程全解析

Haystack 音频转写指南：深入解析 LocalWhisperTranscriber 与 RemoteWhisperTranscriber（Version 2.19）

【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack

本篇技术指南围绕 Haystack 2.19 音频 API 参考文档 audio_api.md 展开，系统讲解LocalWhisperTranscriber与RemoteWhisperTranscriber两个音频转写组件的完整 API：从初始化参数、warm_up、run/transcribe的调用方式，到to_dict/from_dict的序列化机制，以及它们在索引管道中的典型落地形态。读完本文，你将掌握如何在本地或云端把音频文件转写为 HaystackDocument，并理解两个组件在版本演进中的迁移去向。

组件定位：音频转写是索引管道的起点

在 Haystack 中，音频转写组件最典型的位置是索引管道的第一个组件（这一点在 localwhispertranscriber.mdx 与 remotewhispertranscriber.mdx 中均有明确标注）。它们把原始音频文件（MP3、WAV 等）转写成文本，输出为 Haystack 的Document，从而让后续的切分、向量化、检索等环节可以像处理普通文本一样处理语音内容，支撑语音问答、播客知识库、会议纪要等场景。

两个组件的核心差异在于推理位置：

run方法的必需入参均为sources：一个由文件路径（str/Path）或二进制流（ByteStream）组成的列表；输出均为documents：一个由Document组成的列表，每个文档对应一个输入音频文件。

本地转写：LocalWhisperTranscriber

适用场景与前提依赖

LocalWhisperTranscriber使用 OpenAI 的 Whisper 模型在本地完成转写，音频数据不会离开执行机器，适合对数据隐私敏感、离线环境或希望避免逐次计费的场景。在使用前需要先安装推理依赖（安装命令见 localwhispertranscriber.mdx）：

pip install 'transformers[torch]' pip install -U openai-whisper

初始化参数

根据 audio_api.md 中的构造函数签名：

def __init__(model: WhisperLocalModel = "large", device: Optional[ComponentDevice] = None, whisper_params: Optional[dict[str, Any]] = None)

• model：使用的 Whisper 模型名称，可选值为"tiny"、"base"、"small"、"medium"、"large"（默认）。模型越小推理越快、显存占用越低，但准确率相应下降；large准确率最高但对资源要求也最高。具体模型的参数规模与多语言支持差异可参考官方 Whisper 模型文档。
• device：模型加载的目标设备。传入None时组件自动选择默认设备（从源码设计看，Haystack 会优先利用 GPU）。若希望显式指定 CPU 或某块 GPU，可通过 Haystack 的设备管理机制传入对应设备。
• whisper_params：透传给 Whisper 转写过程的可选参数字典，用于控制语言、采样温度、解码选项等，在__init__与run中均可提供。

生命周期方法

• warm_up()：将模型加载进内存。由于本地模型体积较大，Haystack 组件约定在首次run前需要调用warm_up()完成模型加载（管道运行时会自动处理）。
• run(sources, whisper_params=None)：转写音频文件列表。sources接受list[Union[str, Path, ByteStream]]，whisper_params为可选的透传参数。方法声明了输出类型@component.output_types(documents=list[Document])，返回字典中documents是转写结果列表。
• transcribe(sources, **kwargs)：底层转写实现，返回list[Document]，每个输入文件对应一个文档。run内部即委托该方法完成核心逻辑。

输出文档的结构

run返回的每个Document中：

• content：转写出的文本内容；
• metadata：包含 Whisper 模型返回的额外信息，例如对齐数据（alignment data）以及本次转写使用的音频文件路径。

这意味着下游组件可以直接读取documents[0].content获得纯文本，也可以从metadata中获取时间戳对齐等细粒度信息用于字幕生成等场景。

独立使用示例

localwhispertranscriber.mdx 给出了完整可运行示例——先下载一段公开演讲音频，再本地转写：

import requests from haystack.components.audio import LocalWhisperTranscriber response = requests.get( "https://ia903102.us.archive.org/19/items/100-Best--Speeches/EK_19690725_64kb.mp3", ) with open("kennedy_speech.mp3", "wb") as file: file.write(response.content) transcriber = LocalWhisperTranscriber(model="tiny") transcriber.warm_up() transcription = transcriber.run(sources=["./kennedy_speech.mp3"]) print(transcription["documents"][0].content)

在管道中与 LinkContentFetcher 组合

典型的语音索引管道先用LinkContentFetcher抓取远程音频，再交给转写组件：

from haystack.components.audio import LocalWhisperTranscriber from haystack.components.fetchers import LinkContentFetcher from haystack import Pipeline pipe = Pipeline() pipe.add_component("fetcher", LinkContentFetcher()) pipe.add_component("transcriber", LocalWhisperTranscriber(model="tiny")) pipe.connect("fetcher", "transcriber") result = pipe.run( data={ "fetcher": { "urls": [ "https://ia903102.us.archive.org/19/items/100-Best--Speeches/EK_19690725_64kb.mp3", ], }, }, ) print(result["transcriber"]["documents"][0].content)

这里fetcher输出的streams会自动匹配transcriber的sources输入，实现"抓取即转写"的串联。

云端转写：RemoteWhisperTranscriber

适用场景与 API Key 配置

RemoteWhisperTranscriber通过调用 OpenAI Whisper API 完成转写，适合没有本地 GPU、希望使用托管推理服务的场景。组件需要 OpenAI API Key，配置方式有两种（见 remotewhispertranscriber.mdx）：

1. 通过初始化参数api_key传入，内部使用 Haystack 的Secret机制解析密钥；
2. 设置环境变量OPENAI_API_KEY，组件默认会读取该环境变量。

from haystack.components.audio import RemoteWhisperTranscriber transcriber = RemoteWhisperTranscriber() # 使用 OPENAI_API_KEY 环境变量

初始化参数详解

构造函数签名如下：

def __init__(api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"), model: str = "whisper-1", api_base_url: Optional[str] = None, organization: Optional[str] = None, http_client_kwargs: Optional[dict[str, Any]] = None, **kwargs)

透传参数（kwargs）重点说明（详见 audio_api.md）：

• language：输入音频的语言，使用 ISO-639-1 格式（如"en"、"zh"），显式指定可提升转写准确率并降低延迟；
• prompt：可选的提示文本，用于引导模型的输出风格或衔接前一段音频，提示语言应与音频语言一致；
• response_format：转写结果格式，本组件仅支持json；
• temperature：采样温度，取值 0 到 1。较高的值（如 0.8）使输出更随机，较低的值（如 0.2）更聚焦、确定性更强；设为 0 时模型会自动按对数概率逐步升温直到命中阈值。

兼容 OpenAI 兼容客户端

从 remotewhispertranscriber.mdx 可以看到，该组件基于 OpenAI 兼容协议工作，并不局限于 OpenAI 一家提供商——例如 Groq 等提供 Whisper 语音转写服务的平台可作为即插即用的替代（此时通过api_base_url指向对方端点、api_key使用对方密钥即可）。

run 方法与输出

@component.output_types(documents=list[Document]) def run(sources: list[Union[str, Path, ByteStream]])

• sources：待转写的文件路径或ByteStream对象列表；
• 返回值：字典，键documents对应一个列表，每个输入文件一个文档，Document.content即为转写文本。

与本地版不同，远程版在初始化时不需要warm_up()——模型由服务端托管，组件开箱即用。

独立使用示例

import requests from haystack.components.audio import RemoteWhisperTranscriber response = requests.get( "https://ia903102.us.archive.org/19/items/100-Best--Speeches/EK_19690725_64kb.mp3", ) with open("kennedy_speech.mp3", "wb") as file: file.write(response.content) transcriber = RemoteWhisperTranscriber() transcription = transcriber.run(sources=["./kennedy_speech.mp3"]) print(transcription["documents"][0].content)

在管道中与 LinkContentFetcher 组合

from haystack.components.audio import RemoteWhisperTranscriber from haystack.components.fetchers import LinkContentFetcher from haystack import Pipeline pipe = Pipeline() pipe.add_component("fetcher", LinkContentFetcher()) pipe.add_component("transcriber", RemoteWhisperTranscriber()) pipe.connect("fetcher", "transcriber") result = pipe.run( data={ "fetcher": { "urls": [ "https://ia903102.us.archive.org/19/items/100-Best--Speeches/EK_19690725_64kb.mp3", ], }, }, ) print(result["transcriber"]["documents"][0].content)

序列化支持：to_dict 与 from_dict

两个组件均实现了 Haystack 标准的序列化协议，便于组件被保存为 YAML/JSON 管道描述并在反序列化时还原：

• to_dict() -> dict[str, Any]：将组件序列化为字典，包含类名、初始化参数（含模型名、设备、API Key 引用方式等）等可重建信息；
• from_dict(data: dict[str, Any])（类方法）：从字典反序列化出组件实例，data为to_dict产生的字典。

这一机制使包含转写组件的管道可以无缝走 Haystack 的 marshal 序列化 流程，实现管道描述的持久化与跨环境复用。

版本演进：组件迁移至 whisper-haystack

需要特别说明的是，这两个组件在 Haystack 后续版本中经历了从核心库迁出的演进。从 releasenotes/notes/deprecate-whisper-components-95822a86cd87fdc0.yaml 可见，LocalWhisperTranscriber与RemoteWhisperTranscriber被标记为弃用并计划在 3.0 移除，迁移目标为独立的whisper-haystack集成包；releasenotes/notes/remove-whisper-components-30108535da20e41f.yaml 则记录了最终迁移动作：安装pip install whisper-haystack后将导入路径更新为：

from haystack_integrations.components.audio.whisper import LocalWhisperTranscriber from haystack_integrations.components.audio.whisper import RemoteWhisperTranscriber

此外，迁移后LocalWhisperTranscriber仍需单独安装openai-whisper（以及ffmpeg），安装命令为pip install "openai-whisper>=20231106"。完整的导入路径对照表可在 MIGRATION.md 中查到。

因此，如果项目基于 Haystack 2.19 使用from haystack.components.audio import ...的写法，请留意升级到 3.x 时需同步调整导入路径；如果从零开始新项目，建议直接使用whisper-haystack集成包。

实践要点小结

• 选型：数据不出本机、离线环境、有 GPU →LocalWhisperTranscriber；无本地算力、追求托管便利 →RemoteWhisperTranscriber；使用非 OpenAI 的兼容提供商 → 远程版 + 自定义api_base_url。
• 输入输出：两者输入均为sources（路径或ByteStream），输出均为documents（Document列表），可直接接入 Haystack 的切分、嵌入、检索组件。
• 本地版记得warm_up()：模型按需加载到内存，独立使用组件时需手动调用；管道运行时会自动完成。
• 远程版用足透传参数：language提升准确率与速度，temperature控制随机性，prompt引导风格，注意response_format仅支持json。
• 密钥管理：推荐优先使用OPENAI_API_KEY环境变量，组件通过 HaystackSecret机制统一解析。
• 版本兼容：2.19 的haystack.components.audio导入路径已在后续版本迁移至whisper-haystack集成包，升级前对照 MIGRATION.md 更新导入。

完整的类方法签名、参数说明与返回值定义，可随时查阅 version-2.19 音频 API 参考 及其组件使用文档（本地版、远程版）。

【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack