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），僅供參考