Haystack 音频转写指南深入解析 LocalWhisperTranscriber 与 RemoteWhisperTranscriberVersion 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从而让后续的切分、向量化、检索等环节可以像处理普通文本一样处理语音内容支撑语音问答、播客知识库、会议纪要等场景。两个组件的核心差异在于推理位置维度LocalWhisperTranscriberRemoteWhisperTranscriber推理位置本地机器执行组件所在环境OpenAI Whisper API云端是否发送音频到第三方否完全本地完成是通过 API 发送必需配置安装 torch 与 openai-whisperOpenAI API Key默认模型largewhisper-1run方法的必需入参均为sources一个由文件路径str/Path或二进制流ByteStream组成的列表输出均为documents一个由Document组成的列表每个文档对应一个输入音频文件。本地转写LocalWhisperTranscriber适用场景与前提依赖LocalWhisperTranscriber使用 OpenAI 的 Whisper 模型在本地完成转写音频数据不会离开执行机器适合对数据隐私敏感、离线环境或希望避免逐次计费的场景。在使用前需要先安装推理依赖安装命令见 localwhispertranscriber.mdxpip 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_paramsNone)转写音频文件列表。sources接受list[Union[str, Path, ByteStream]]whisper_params为可选的透传参数。方法声明了输出类型component.output_types(documentslist[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(modeltiny) 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(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)这里fetcher输出的streams会自动匹配transcriber的sources输入实现抓取即转写的串联。云端转写RemoteWhisperTranscriber适用场景与 API Key 配置RemoteWhisperTranscriber通过调用 OpenAI Whisper API 完成转写适合没有本地 GPU、希望使用托管推理服务的场景。组件需要 OpenAI API Key配置方式有两种见 remotewhispertranscriber.mdx通过初始化参数api_key传入内部使用 Haystack 的Secret机制解析密钥设置环境变量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)参数说明api_keyOpenAI API Key默认从环境变量OPENAI_API_KEY读取也可在初始化时显式传入Secretmodel使用的模型名当前仅支持whisper-1默认api_base_urlOpenAI 兼容 API 的 Base URL默认指向 OpenAI 官方地址使用其他兼容提供商时按其文档配置organizationOpenAI 组织 IDOrganization ID按需传入http_client_kwargs用于配置自定义httpx.Client或httpx.AsyncClient的关键字参数字典可控制超时、代理、重试策略等**kwargs透传给 OpenAI 转写端点的其他可选参数透传参数kwargs重点说明详见 audio_api.mdlanguage输入音频的语言使用 ISO-639-1 格式如en、zh显式指定可提升转写准确率并降低延迟prompt可选的提示文本用于引导模型的输出风格或衔接前一段音频提示语言应与音频语言一致response_format转写结果格式本组件仅支持jsontemperature采样温度取值 0 到 1。较高的值如 0.8使输出更随机较低的值如 0.2更聚焦、确定性更强设为 0 时模型会自动按对数概率逐步升温直到命中阈值。兼容 OpenAI 兼容客户端从 remotewhispertranscriber.mdx 可以看到该组件基于 OpenAI 兼容协议工作并不局限于 OpenAI 一家提供商——例如 Groq 等提供 Whisper 语音转写服务的平台可作为即插即用的替代此时通过api_base_url指向对方端点、api_key使用对方密钥即可。run 方法与输出component.output_types(documentslist[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-whisper20231106。完整的导入路径对照表可在 MIGRATION.md 中查到。因此如果项目基于 Haystack 2.19 使用from haystack.components.audio import ...的写法请留意升级到 3.x 时需同步调整导入路径如果从零开始新项目建议直接使用whisper-haystack集成包。实践要点小结选型数据不出本机、离线环境、有 GPU →LocalWhisperTranscriber无本地算力、追求托管便利 →RemoteWhisperTranscriber使用非 OpenAI 的兼容提供商 → 远程版 自定义api_base_url。输入输出两者输入均为sources路径或ByteStream输出均为documentsDocument列表可直接接入 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Haystack 音频转写指南：深入解析 LocalWhisperTranscriber 与 RemoteWhisperTranscriber（Version 2.19）
Haystack 音频转写指南深入解析 LocalWhisperTranscriber 与 RemoteWhisperTranscriberVersion 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从而让后续的切分、向量化、检索等环节可以像处理普通文本一样处理语音内容支撑语音问答、播客知识库、会议纪要等场景。两个组件的核心差异在于推理位置维度LocalWhisperTranscriberRemoteWhisperTranscriber推理位置本地机器执行组件所在环境OpenAI Whisper API云端是否发送音频到第三方否完全本地完成是通过 API 发送必需配置安装 torch 与 openai-whisperOpenAI API Key默认模型largewhisper-1run方法的必需入参均为sources一个由文件路径str/Path或二进制流ByteStream组成的列表输出均为documents一个由Document组成的列表每个文档对应一个输入音频文件。本地转写LocalWhisperTranscriber适用场景与前提依赖LocalWhisperTranscriber使用 OpenAI 的 Whisper 模型在本地完成转写音频数据不会离开执行机器适合对数据隐私敏感、离线环境或希望避免逐次计费的场景。在使用前需要先安装推理依赖安装命令见 localwhispertranscriber.mdxpip 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_paramsNone)转写音频文件列表。sources接受list[Union[str, Path, ByteStream]]whisper_params为可选的透传参数。方法声明了输出类型component.output_types(documentslist[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(modeltiny) 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(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)这里fetcher输出的streams会自动匹配transcriber的sources输入实现抓取即转写的串联。云端转写RemoteWhisperTranscriber适用场景与 API Key 配置RemoteWhisperTranscriber通过调用 OpenAI Whisper API 完成转写适合没有本地 GPU、希望使用托管推理服务的场景。组件需要 OpenAI API Key配置方式有两种见 remotewhispertranscriber.mdx通过初始化参数api_key传入内部使用 Haystack 的Secret机制解析密钥设置环境变量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)参数说明api_keyOpenAI API Key默认从环境变量OPENAI_API_KEY读取也可在初始化时显式传入Secretmodel使用的模型名当前仅支持whisper-1默认api_base_urlOpenAI 兼容 API 的 Base URL默认指向 OpenAI 官方地址使用其他兼容提供商时按其文档配置organizationOpenAI 组织 IDOrganization ID按需传入http_client_kwargs用于配置自定义httpx.Client或httpx.AsyncClient的关键字参数字典可控制超时、代理、重试策略等**kwargs透传给 OpenAI 转写端点的其他可选参数透传参数kwargs重点说明详见 audio_api.mdlanguage输入音频的语言使用 ISO-639-1 格式如en、zh显式指定可提升转写准确率并降低延迟prompt可选的提示文本用于引导模型的输出风格或衔接前一段音频提示语言应与音频语言一致response_format转写结果格式本组件仅支持jsontemperature采样温度取值 0 到 1。较高的值如 0.8使输出更随机较低的值如 0.2更聚焦、确定性更强设为 0 时模型会自动按对数概率逐步升温直到命中阈值。兼容 OpenAI 兼容客户端从 remotewhispertranscriber.mdx 可以看到该组件基于 OpenAI 兼容协议工作并不局限于 OpenAI 一家提供商——例如 Groq 等提供 Whisper 语音转写服务的平台可作为即插即用的替代此时通过api_base_url指向对方端点、api_key使用对方密钥即可。run 方法与输出component.output_types(documentslist[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-whisper20231106。完整的导入路径对照表可在 MIGRATION.md 中查到。因此如果项目基于 Haystack 2.19 使用from haystack.components.audio import ...的写法请留意升级到 3.x 时需同步调整导入路径如果从零开始新项目建议直接使用whisper-haystack集成包。实践要点小结选型数据不出本机、离线环境、有 GPU →LocalWhisperTranscriber无本地算力、追求托管便利 →RemoteWhisperTranscriber使用非 OpenAI 的兼容提供商 → 远程版 自定义api_base_url。输入输出两者输入均为sources路径或ByteStream输出均为documentsDocument列表可直接接入 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
