在 Haystack 中使用 Whisper 转录音频：LocalWhisperTranscriber 与 RemoteWhisperTranscriber 完整指南

在 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/haystack本指南系统讲解 Haystack 开源 AI 编排框架中的 Whisper 音频转写集成覆盖本地推理组件LocalWhisperTranscriber与云端 API 组件RemoteWhisperTranscriber的安装、初始化参数、run调用、序列化与管线集成方式。读完本文你将掌握如何把任意音频文件转写为 HaystackDocument并将其作为索引管线的第一步构建音频 → 文本 → RAG的完整链路。背景Whisper 集成在 Haystack 中的定位Whisper 是 OpenAI 开源的通用语音识别模型Haystack 通过两个音频组件将其接入组件化管线体系LocalWhisperTranscriber在本机加载 Whisper 模型完成转写音频数据不出本机RemoteWhisperTranscriber调用 OpenAI 兼容的 Whisper API如 OpenAI、Groq 等完成转写。在版本 2.18 中这两个组件的完整 API 参考记录于 whisper.md 与 audio_api.md对应的用户指南位于 localwhispertranscriber.mdx 和 remotewhispertranscriber.mdx。从 MIGRATION.md 的迁移表可以看到这两个组件后续被迁移至独立的whisper-haystack集成包导入路径从haystack.components.audio变为haystack_integrations.components.audio.whisper。迁移说明记录在 deprecate-whisper-components-95822a86cd87fdc0.yamlLocalWhisperTranscriber和RemoteWhisperTranscriber已被弃用将在 Haystack 3.0 中移除。它们将迁移至whisper-haystack包。要继续使用请用pip install whisper-haystack安装并更新导入语句。因此本指南中的示例同时给出两种导入路径Haystack 2.18 内置组件使用haystack.components.audio迁移后的集成包使用haystack_integrations.components.audio.whisper二者 API 形态保持一致。LocalWhisperTranscriber本地 Whisper 转写组件概览LocalWhisperTranscriber在本地机器上使用 OpenAI 的 Whisper 模型转写音频文件。它适用于对数据隐私敏感、无网络依赖或需要离线批量处理的场景——所有转写都在执行机器上完成音频永远不会发送给第三方服务商。在管线中的典型位置与输入输出约定见 localwhispertranscriber.mdx项目说明管线中最常见位置索引管线的第一个组件必需的 run 变量sources要转写的路径或二进制流列表输出变量documentsDocument 列表安装依赖本地转写依赖 torch 与 Whisper 本体按以下命令安装pip install transformers[torch] pip install -U openai-whisper若使用迁移后的whisper-haystack包则改为pip install whisper-haystack pip install -U openai-whisper初始化参数def __init__( model: WhisperLocalModel large, device: ComponentDevice | None None, whisper_params: dict[str, Any] | None None, ) - NonemodelWhisperLocalModel默认large要使用的模型名可选tiny、base、small、medium、large。模型规模越大识别准确率越高、速度越慢、显存占用越大请根据机器算力权衡选择。deviceComponentDevice | None默认None模型加载设备。为None时自动选择默认设备。whisper_paramsdict[str, Any] | None透传给 Whisper 转写调用的附加参数例如语言、时间戳等。关于设备参数发布说明 whisper-loc-new-devices-0665a24cd92ee4b6.yaml 记录了 Haystack 设备管理的演进早期版本直接传字符串devicecuda:0新版本改为框架无关的ComponentDevice# 旧用法 from haystack.components.audio import LocalWhisperTranscriber transcriber LocalWhisperTranscriber(devicecuda:0) # 新用法 from haystack.utils.device import ComponentDevice, Device device ComponentDevice.from_single(Device.gpu(id0)) # 或 # device ComponentDevice.from_str(cuda:0) transcriber LocalWhisperTranscriber(devicedevice)方法清单方法签名说明warm_up()warm_up() - None将模型加载到内存中首次调用前必须先执行run(sources, whisper_params)run(sources: list[str \| Path \| ByteStream], whisper_params: dict[str, Any] \| None None) - dict[str, Any]转写一组音频文件为 Document 列表to_dict()to_dict() - dict[str, Any]序列化组件为字典from_dict(data)from_dict(data: dict[str, Any]) - LocalWhisperTranscriber从字典反序列化组件其中run的返回字典包含键documents每个音频文件对应一个DocumentDocument.content为转写文本Document.metadata携带 Whisper 模型返回的额外信息如对齐数据 alignment data、转写所用的音频文件路径。值得注意组件底层还有一个transcribe(sources, **kwargs) - list[Document]方法负责把输入文件逐一转为Document见 audio_api.mdrun是对它的组件化封装。独立使用以下示例先下载一段肯尼迪演讲 MP3再用tiny模型在本机转写示例源自 localwhispertranscriber.mdximport 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)关键步骤有三构造组件 →warm_up()加载模型 →run(sources[...])转写。使用迁移包时把导入语句换成from haystack_integrations.components.audio.whisper import LocalWhisperTranscriber即可其余代码不变迁移后不再强制要求显式warm_up()但显式调用依然安全。接入管线LocalWhisperTranscriber最常见的定位是索引管线的第一个组件。下面的管线用LinkContentFetcher抓取音频 URL再用转写器转成文本示例源自 localwhispertranscriber.mdxfrom 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输出的二进制流与transcriber的sources输入天然衔接转写结果documents可直接继续连接到后续的文档切分、向量化组件形成完整的音频抓取 → 转写 → 索引管线。RemoteWhisperTranscriberAPI 转写组件概览RemoteWhisperTranscriber调用 OpenAI 的 Whisper API 完成转写本机无需安装模型与 torch只依赖网络请求。该组件兼容任何 OpenAI 兼容的客户端不限于 OpenAI 官方服务——例如 Groq 就提供了可直接替换的 Whisper 兼容端点。它适合对延迟敏感、算力有限或希望按量付费的场景。在管线中的约定见 remotewhispertranscriber.mdx项目说明管线中最常见位置索引管线的第一个组件必需的 init 变量api_keyOpenAI API 密钥可通过环境变量OPENAI_API_KEY提供必需的 run 变量sources要转写的路径或二进制流列表输出变量documentsDocument 列表安装与密钥配置安装迁移后的集成包pip install whisper-haystackRemoteWhisperTranscriber需要 OpenAI API 密钥参考 whisper.md 中的 API 文档说明可通过两种方式设置通过api_key初始化参数传入密钥由 Haystack 的 Secret API 机制解析设置环境变量OPENAI_API_KEY组件默认从该变量读取。from haystack_integrations.components.audio.whisper import RemoteWhisperTranscriber transcriber RemoteWhisperTranscriber()初始化参数def __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, ) - None各参数说明如下api_keySecretOpenAI API 密钥。默认从环境变量OPENAI_API_KEY解析也可以在初始化时显式传入。modelstr默认whisper-1使用的模型名目前仅接受whisper-1。api_base_urlstr | NoneAPI 基地址默认https://api.openai.com/v1。如果使用 OpenAI 之外的其他 Whisper 服务商如 Groq按该服务商文档配置此参数。organizationstr | NoneOpenAI 组织 ID适用于多组织账号场景。http_client_kwargsdict[str, Any] | None用于配置自定义httpx.Client或httpx.AsyncClient的关键字参数字典可自定义超时、代理、重试等行为。kwargs其他直接透传给 OpenAI 端点的模型可选参数主要包括language输入音频的语言使用 ISO-639-1 格式如zh、en提前指定可提升转写准确率并降低延迟prompt可选的引导文本用于指定输出风格或衔接上一段音频提示语言应与音频语言一致response_format转写输出格式本组件仅支持jsontemperature采样温度取值 01。较高值如 0.8使输出更随机较低值如 0.2更聚焦和确定设为 0 时模型会利用对数概率自动升温直到命中特定阈值。版本 2.18 的RemoteWhisperTranscriber已基于 OpenAI SDK 实现见 migrate-remote-whisper-transcriber-to-openai-sdk-980ae6f54ddfd7df.yaml并支持通过http_client_kwargs定制底层 HTTP 客户端。方法清单方法签名说明run(sources)run(sources: list[str \| Path \| ByteStream]) - dict[str, Any]同步转写音频文件列表为 Document 列表run_async(sources)run_async(sources: list[str \| Path \| ByteStream]) - dict[str, Any]run的异步版本可在异步代码中用await调用参数与返回值一致to_dict()to_dict() - dict[str, Any]序列化组件为字典from_dict(data)from_dict(data: dict[str, Any]) - RemoteWhisperTranscriber从字典反序列化组件返回字典的documents键中每个输入文件对应一个Document其content为转写文本。RemoteWhisperTranscriber无需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)也可以在初始化时用Secret.from_token直接传入密钥from haystack.components.audio import RemoteWhisperTranscriber from haystack.utils import Secret whisper RemoteWhisperTranscriber(api_keySecret.from_token(your-api-key), modeltiny) transcription whisper.run(sources[path/to/audio/file])接入管线与本地版本对称远程版同样可与LinkContentFetcher串联示例源自 remotewhispertranscriber.mdxfrom 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)若换成 Groq 等兼容服务商只需按厂商文档设置api_base_url与api_key组件代码无需其他改动。本地与远程如何选择维度LocalWhisperTranscriberRemoteWhisperTranscriber运行位置本机CPU/GPUOpenAI 兼容 API 服务端音频数据流向不出本机上传至服务端前置依赖torch、openai-whisper、模型权重OPENAI_API_KEY或等效密钥是否需要warm_up()需要首次运行前加载模型不需要适用场景隐私敏感、离线批处理、无 API 预算无本地算力、要求低延迟、按量付费可选模型tiny / base / small / medium / largewhisper-1OpenAI 托管选择建议数据不出域、算力充足选本地追求省心与弹性、能接受数据上云选远程。两者输出结构一致documents列表因此可以在索引管线中无缝互换。序列化与版本迁移序列化支持两个组件都实现了标准的 Haystack 组件序列化协议to_dict()将组件及其初始化参数序列化为字典便于持久化到 YAML/JSON 或存入管线描述文件from_dict(data)从字典还原组件实例保证管线可完整导出与恢复。这与其他 Haystack 组件一致是组件可组合、可复用、可版本化管理的基础。从 Haystack 2.18 到 whisper-haystack 的迁移两个组件在后续版本被移入whisper-haystack独立包迁移步骤见 MIGRATION.md 与 deprecate-whisper-components-95822a86cd87fdc0.yaml安装新包pip install whisper-haystack更新导入语句迁移前Haystack 2.18迁移后whisper-haystackfrom haystack.components.audio import LocalWhisperTranscriberfrom haystack_integrations.components.audio.whisper import LocalWhisperTranscriberfrom haystack.components.audio import RemoteWhisperTranscriberfrom haystack_integrations.components.audio.whisper import RemoteWhisperTranscriber迁移后组件继续以haystack_integrations命名空间提供初始化与run调用方式保持一致。进一步探索音频组件总览audio.mdx用户指南localwhispertranscriber.mdx、remotewhispertranscriber.mdxAPI 参考integrations-api/whisper.md、haystack-api/audio_api.md相关发布说明deprecate-whisper-components-95822a86cd87fdc0.yaml、whisper-loc-new-devices-0665a24cd92ee4b6.yaml组件迁移对照表MIGRATION.md基于这两个转写组件可以进一步组合文档切分器、Embedder 与 Document Store搭建播客 / 会议录音 → 转写文本 → 向量索引 → 多语言 RAG的完整生产级应用。【免费下载链接】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），仅供参考