Haystack Whisper 语音转写组件指南LocalWhisperTranscriber 与 RemoteWhisperTranscriber 的本地与云端方案实战【免费下载链接】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/haystackHaystack 的 Whisper 集成将 OpenAI 的语音转写Speech-to-Text能力封装为两个可直接接入索引管道的组件LocalWhisperTranscriber在本地执行 Whisper 模型完成转写RemoteWhisperTranscriber则通过 OpenAI 兼容 API 进行远程转写。本文基于 version-2.22 的 Whisper 集成 API 参考文档 展开完整覆盖两个组件的初始化参数、运行方式、序列化方法与管道集成实践读完即可在自己的 Haystack 项目中落地音频文件 → 可检索文本的完整流程。一、两个组件两种部署哲学Whisper 集成提供了一对互补的转写组件它们在 Haystack 管道中的典型位置是索引管道Indexing Pipeline的第一个组件——把音频转换成后续DocumentWriter等组件可消费的Document组件运行位置核心特征LocalWhisperTranscriber本地机器音频数据不出本机全部转写由执行机器完成不依赖任何第三方服务RemoteWhisperTranscriberOpenAI 兼容 API调用 OpenAI Whisper API需要 API Key轻量免本地算力两者的强制运行变量一致sources要转写的路径或二进制流列表输出变量一致documents每个音频对应一个文档。这种统一的设计让两个组件可以在管道中无缝替换具体选型取决于你是在数据主权优先的本地环境还是希望借助云端 GPU 算力。二、安装与环境准备本地组件依赖LocalWhisperTranscriber需要在本机安装 PyTorch 与 Whisper 本体。根据 version-2.22 的组件使用文档安装命令为pip install transformers[torch] pip install -U openai-whisper其中openai-whisper是 OpenAI 官方 Whisper 包本地转写与音频解码依赖它同时还需要系统具备ffmpeg以完成音频解码。远程组件则只需安装 Haystack 的 OpenAI 客户端依赖不要求本地 GPU。远程组件密钥RemoteWhisperTranscriber需要 OpenAI API Key官方推荐通过环境变量注入详见下文密钥管理小节。需要说明的是该组件工作在OpenAI 兼容客户端之上并不局限于 OpenAI 一家服务商——只要目标服务商提供了兼容的/v1/audio/transcriptions接口如 Groq 的语音转写服务均可通过api_base_url指向其端点接入。三、LocalWhisperTranscriber本地转写全解析LocalWhisperTranscriber位于haystack_integrations.components.audio.whisper.whisper_local将 OpenAI Whisper 模型加载到本机内存中完成转写。3.1 初始化参数__init__( model: WhisperLocalModel large, device: ComponentDevice | None None, whisper_params: dict[str, Any] | None None, ) - NonemodelWhisperLocalModel默认large指定使用的 Whisper 模型名可选值包括tiny、base、small、medium、large。五档模型按参数规模递增越大的模型转写准确率越高、多语言能力越强但对显存/内存与推理耗时的要求也越高。官方文档对每个模型的参数量、所需显存与支持语言有详细说明选型时应结合机器资源与目标语言权衡。注意该参数在早期版本中名为model_name后被统一改名为model见 releasenotes/notes/rename-model-param--transcribers-71dbe7cfb86950e0.yaml。deviceComponentDevice | None默认None模型加载设备。传None时由 Haystack 自动选择默认设备如 CUDA 可用则优先 GPU也可显式指定例如强制使用 CPU 或指定某块 GPU。whisper_paramsdict[str, Any] | None透传给 Whisper 转写调用的额外参数语言、解码选项等支持范围以 OpenAI Whisper 的 API 文档为准。3.2 warm_up预加载模型warm_up() - Nonewarm_up()负责把指定模型加载进内存。Haystack 组件的warm_up机制允许在管道正式运行前完成重量级资源此处为模型权重的加载从而避免首次run时的冷启动延迟。使用本地组件时这一步是必须调用的——不调用warm_up直接run会报错。3.3 run转写输入与输出run( sources: list[str | Path | ByteStream], whisper_params: dict[str, Any] | None None, ) - dict[str, Any]sources待转写的音频列表每个元素可以是本地路径字符串、pathlib.Path也可以是ByteStream二进制流对象。这意味着既可以直接喂文件路径也可以在内存中构造音频流。需要注意的是早期版本该输入参数名为audio_files后来为了与其他组件统一输入约定而改名为sources见 releasenotes/notes/change-localwhispertranscriber-run-3b0a818060867720.yaml。whisper_params可选的转写参数覆盖运行时传入会与初始化时的参数合并生效。返回值为一个字典包含唯一的键documents每个音频文件对应一个Document其中Document.content转写得到的文本Document.metaWhisper 模型返回的附加信息例如对齐数据alignment data以及本次转写所使用的音频文件路径等。3.4 独立使用示例以下示例改编自 version-2.22 的组件文档先下载一段公开演讲音频再使用tiny模型本地转写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(modeltiny) transcriber.warm_up() transcription transcriber.run(sources[./kennedy_speech.mp3]) print(transcription[documents][0].content)3.5 在管道中使用本地转写同样可以编排进管道。下面的管道用LinkContentFetcher从 URL 拉取音频交给LocalWhisperTranscriber转写最后输出文本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(modeltiny)) 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)LinkContentFetcher抓取的二进制内容与LocalWhisperTranscriber的sources支持ByteStream天然衔接这也是该组件被设计为支持ByteStream输入的原因。转写完成后documents可以继续流向DocumentCleaner、DocumentSplitter、DocumentWriter等下游组件构成完整的音频 → 文本 → 向量索引流水线。四、RemoteWhisperTranscriber云端转写全解析RemoteWhisperTranscriber位于haystack_integrations.components.audio.whisper.whisper_remote通过 OpenAI Whisper API 在云端完成转写本地无需加载任何模型。4.1 初始化参数__init__( api_key: Secret Secret.from_env_var(OPENAI_API_KEY), model: str whisper-1, api_base_url: str | None None, organization: str | None None, http_client_kwargs: dict[str, Any] | None None, **kwargs: Any ) - Noneapi_keySecretOpenAI API Key。两种设置方式通过环境变量OPENAI_API_KEY注入默认行为Haystack 的Secret.from_env_var会在组件初始化时解析该变量初始化时显式传入Secret对象。Haystack 的 Secret 管理机制支持环境变量、文件等多种解析来源密钥不会明文进入序列化配置。相关演进可见 releasenotes/notes/update-secret-handling-in-components-925d4f3c3c9530db.yaml。modelstr默认whisper-1当前 API 仅接受whisper-1。api_base_urlstr | None自定义 API 基础地址。默认指向 OpenAI 官方端点若使用其他 OpenAI 兼容的 Whisper 服务商则按该服务商的文档设置此参数。注意早期版本的默认值为https://api.openai.com/v1组件后续迁移到 OpenAI SDK 后默认值行为以当前版本为准见 releasenotes/notes/migrate-remote-whisper-transcriber-to-openai-sdk-980ae6f54ddfd7df.yaml。organizationstr | NoneOpenAI 组织 ID适用于多组织账号场景。http_client_kwargsdict[str, Any] | None用于配置自定义httpx.Client/httpx.AsyncClient的关键字参数字典可用来定制超时、代理、连接池等底层 HTTP 行为。**kwargs透传给 OpenAI 转写端点的其他可选参数常见的有language输入音频的语言使用 ISO-639-1 格式如en、zh、de。预先指定语言可显著提升转写准确率并降低延迟避免模型自动检测带来的开销。prompt可选的提示文本用于引导模型风格或衔接上一段音频内容提示语言应与音频语言一致。response_format转写输出格式。本组件只支持json传其他格式将不被接受。temperature采样温度取值范围 01。高值如 0.8使输出更随机多样低值如 0.2更聚焦、确定性更强若设为 0模型会使用对数概率自动升温直到命中特定阈值——这对忠实转写、减少幻觉很有帮助。4.2 run 与 run_asyncrun(sources: list[str | Path | ByteStream]) - dict[str, Any] run_async(sources: list[str | Path | ByteStream]) - dict[str, Any]run同步转写将输入列表中的每个文件转写为一个Documentcontent为转写文本。run_asyncrun的异步版本参数与返回值完全一致可用await在异步代码中调用适用于AsyncPipeline。根据 releasenotes/notes/add-run-async-whisper-image-generator-850fa600c24c0a96.yaml该组件持有同步与异步两套 OpenAI 客户端异步调用不会阻塞事件循环。4.3 独立使用示例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)由于api_key默认从OPENAI_API_KEY环境变量解析此例中无需显式传参。如需指定语言与温度可这样初始化transcriber RemoteWhisperTranscriber( modelwhisper-1, languageen, temperature0.2, )4.4 在管道中使用与本地版本一致远程组件也可与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 管道定义与 Python 对象之间往返to_dict() - dict[str, Any]将组件序列化为字典包含类路径与初始化参数可用于管道 YAML 导出与持久化。from_dict(data: dict[str, Any]) - LocalWhisperTranscriber/RemoteWhisperTranscriber从字典反序列化重建组件实例。这意味着两个组件都可以直接写入 Haystack 的 YAML 管道文件随管道一起版本化、复用与部署。值得注意的是序列化时会遵循 Haystack 的密钥处理约定Secret以引用形式而非明文保存避免 API Key 泄露到配置文件中。六、输入约定与格式边界两个组件共享统一的输入输出契约项目说明输入sourceslist[str \| Path \| ByteStream]支持文件路径与二进制流输出documents每个音频对应一个Documentcontent为转写文本本地版附加元数据meta中包含 Whisper 模型返回值对齐数据、音频路径等支持的音频格式与语言以 OpenAI Whisper 的官方文档为准需要留意的是远程版的response_format仅支持json且model目前仅接受whisper-1本地版则通过whisper_params透传 Whisper 原生解码选项灵活性更高。在数据合规要求严格的场景下本地版音频不出本机的特性是明显的优势而在需要大批量、低运维转写时远程版更省心。七、版本演进与迁移路线从仓库的 releasenotes/notes 目录可以梳理出这两个组件清晰的演进脉络参数统一model_name/model_name_or_path统一改名为model输入audio_files改名为sources并补充ByteStream支持与其他 Haystack 组件输入约定对齐。远程客户端升级RemoteWhisperTranscriber迁移到 OpenAI SDKpreview状态并新增run_async异步方法及配套的AsyncOpenAI客户端可原生运行于AsyncPipeline。独立成包两个组件在后续版本中被从 Haystack 核心库移出独立为whisper-haystack集成包。若在迁移后的版本中使用需要pip install whisper-haystack并将导入路径改为from haystack_integrations.components.audio.whisper import LocalWhisperTranscriber from haystack_integrations.components.audio.whisper import RemoteWhisperTranscriber这正是 version-2.22 的 API 参考文档 所使用的模块路径。另外本地版在独立成包后仍依赖openai-whisper及ffmpeg安装命令为pip install openai-whisper20231106。八、实战建议小结本地转写先warm_up()再run()模型从tiny起步验证流程再根据机器资源与语种上调至base/small/medium/largeCPU 环境优先选小模型并显式指定device。远程转写优先用OPENAI_API_KEY环境变量注入密钥多语言场景显式传language提升准确率对幻觉敏感的场景建议设temperature0接入第三方兼容服务时配置api_base_url。管道集成两个组件都适合放在索引管道首位配合LinkContentFetcher抓取网络音频或直接传入ByteStream处理内存中的音频数据下游接文本预处理与文档写入即可构建完整的音频 RAG 流程。版本适配确认当前 Haystack 版本中组件所在的包路径核心库还是whisper-haystack并据此选择本文对应的导入写法。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考