Haystack 集成 FunASR：使用 FunASRTranscriber 构建本地离线语音转文本（ASR）流水线-育师

Haystack 集成 FunASR：使用 FunASRTranscriber 构建本地离线语音转文本（ASR）流水线

【免费下载链接】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.22 参考文档中的FunASRTranscriber集成组件展开，讲解如何将阿里达摩院开源语音识别工具包 FunASR 接入 Haystack，把 WAV、MP3 等音频文件批量转写为结构化Document对象。读完本文你将掌握该组件的完整参数体系、独立使用与流水线接入方式、说话人分离与标点恢复等进阶配置，并理解其与 Haystack 核心数据模型（Document、ByteStream）及设备管理（ComponentDevice）之间的底层协作关系。

组件概览：本地化、免 API Key 的语音识别

FunASRTranscriber是 Haystack 官方集成（位于haystack_integrations.components.audio.funasr.transcriber模块）中负责语音转文本的组件。它基于 FunASR 与对应 API 参考文档）：

完全本地运行：推理在本机完成，无需任何 API Key，不依赖云端服务；
多语言支持：默认模型iic/SenseVoiceSmall支持 50+ 种语言，官方资料称其速度约为 Whisper 的 5–10 倍；
模型自动管理：首次使用时从 ModelScope 自动下载模型，并缓存在本地~/.cache/modelscope目录，之后离线复用；
零手动加载：模型在组件首次运行时自动载入内存，也可通过warm_up()主动预热。

在 Haystack 的音频组件家族中（见 docs-website/docs/pipeline-components/audio.mdx），FunASRTranscriber与LocalWhisperTranscriber、RemoteWhisperTranscriber并列，但它是唯一一个「本地运行 + 免 API Key」的选择，最适合对数据隐私、网络隔离或成本敏感的场景。

快速上手：独立使用

FunASRTranscriber最常见的定位是索引流水线（indexing pipeline）中的第一个组件。最简用法如下：

from haystack_integrations.components.audio.funasr import FunASRTranscriber transcriber = FunASRTranscriber() result = transcriber.run(sources=["speech.wav", "interview.mp3"]) documents = result["documents"]

要点说明：

sources接受音频文件路径列表（str或Path），也接受ByteStream二进制流对象；
支持的音频格式包括 WAV、MP3、FLAC、OGG、M4A、AAC，以及 FunASR 底层音频后端（soundfile/ffmpeg）能够解码的任何格式；
返回结果是一个字典，键"documents"对应一个Document列表，每个音频源生成一个Document，完整转写文本存放在其content字段中；
若想直接打印结果，可使用print(result["documents"][0].content)。

Document是 Haystack 的核心数据类，其定义见 haystack/dataclasses/document.py：content字段保存文本内容，meta字段保存可 JSON 序列化的自定义元数据——FunASR 转写产生的说话人信息等正是写入meta。

构造参数全解析

FunASRTranscriber的构造函数签名（来自 API 参考文档）如下：

__init__( *, model: str = "iic/SenseVoiceSmall", vad_model: str | None = "fsmn-vad", punc_model: str | None = "ct-punc", spk_model: str | None = None, device: ComponentDevice | None = None, batch_size_s: int = 300, store_full_path: bool = False, generation_kwargs: dict[str, Any] | None = None ) -> None

所有参数均为仅关键字参数（keyword-only）。各参数含义如下：

参数	类型	默认值	作用与取值建议
`model`	`str`	`"iic/SenseVoiceSmall"`	FunASR 模型名称或本地模型路径。默认值为多语言模型`iic/SenseVoiceSmall`（支持 50+ 语言、速度快于 Whisper）；中文场景可选`"paraformer-zh"`，英文场景可选`"paraformer-en"`。可浏览 ModelScope 模型库按需挑选
`vad_model`	`str \\| None`	`"fsmn-vad"`	语音活动检测（Voice Activity Detection）模型，用于把长音频切分成语音片段。设为`None`则将整段音频作为单一流处理，不做切分
`punc_model`	`str \\| None`	`"ct-punc"`	标点恢复（punctuation restoration）模型。设为`None`则关闭标点功能
`spk_model`	`str \\| None`	`None`	说话人分离（speaker diarization）模型，例如`"cam++"`。启用后会在生成的`Document`元数据中加入`"speakers"`键。默认`None`表示关闭分离
`device`	`ComponentDevice \\| None`	`None`	推理设备。`None`时自动选择默认设备；GPU 推理使用`ComponentDevice.from_str("cuda")`显式指定
`batch_size_s`	`int`	`300`	VAD 切分后音频的批处理时长（秒）。值越大吞吐越高，但内存占用也越大
`store_full_path`	`bool`	`False`	是否在`Document`元数据中保存音频文件的完整路径。`True`存完整路径，`False`（默认）只存文件名
`generation_kwargs`	`dict[str, Any] \\| None`	`None`	透传给`AutoModel.generate()`的额外关键字参数，用于模型专属选项，详见下文

进阶配置一：说话人分离 + 标点恢复

对于会议纪要、访谈整理等多说话人场景，可以同时启用 VAD 切分、标点恢复和说话人分离：

from haystack.utils import ComponentDevice transcriber = FunASRTranscriber( model="paraformer-zh", vad_model="fsmn-vad", punc_model="ct-punc", spk_model="cam++", device=ComponentDevice.from_str("cuda"), )

此配置下，run()产出的每个Document的meta中会包含"speakers"键，记录各语音片段对应的说话人标识，从而支持在转写文本基础上做按说话人归类的后处理。

进阶配置二：SenseVoice 反文本规范化（ITN）

SenseVoice 模型可通过generation_kwargs开启反文本规范化（Inverse Text Normalisation），把口语数字、日期、金额等转写为规范化书面形式，并启用 VAD 合并与语种自动识别：

transcriber = FunASRTranscriber( model="iic/SenseVoiceSmall", generation_kwargs={"use_itn": True, "merge_vad": True, "language": "auto"}, )

generation_kwargs直接透传给底层AutoModel.generate()，因此它同时承担着模型专属能力开关的职责：

SenseVoice 系列：use_itn=True开启反文本规范化，merge_vad=True合并 VAD 片段，language="auto"自动识别语种；
上下文热词：可通过hotword="..."传入热词列表，实现特定人名、专有名词的上下文识别纠偏。

在流水线中使用

FunASRTranscriber可无缝嵌入 HaystackPipeline。例如与LinkContentFetcher组合，实现「抓取网页音频链接 → 转写」的链路：

from haystack import Pipeline from haystack.components.fetchers import LinkContentFetcher from haystack_integrations.components.audio.funasr import FunASRTranscriber pipe = Pipeline() pipe.add_component("fetcher", LinkContentFetcher()) pipe.add_component("transcriber", FunASRTranscriber()) pipe.connect("fetcher", "transcriber") result = pipe.run( data={ "fetcher": { "urls": ["https://example.com/interview.wav"], }, }, ) print(result["transcriber"]["documents"][0].content)

这条链路的可行性有核心源码支撑：在 haystack/components/fetchers/link_content.py 中，LinkContentFetcher为audio/*MIME 类型注册了二进制内容处理器_binary_content_handler，因此抓取到的音频流会以ByteStream形式输出，恰好与FunASRTranscriber.run()的sources入参类型（str | Path | ByteStream）衔接。转写后的Document可继续连接到DocumentWriter写入文档存储，构成完整的音频索引流水线。

输入输出契约：run 方法详解

run( sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None = None, ) -> dict[str, list[Document]]

参数说明

sources（必填）：音频文件路径（str或Path）或ByteStream对象的列表。支持的格式包含 WAV、MP3、FLAC、OGG、M4A、AAC 等 FunASR 底层后端可解码的一切格式；
meta（可选）：附加到产出Document上的元数据。传入单个字典时，同一份元数据应用于所有Document；传入与sources等长的字典列表时，元数据按位置与各Document一一对应。

返回值

返回字典以"documents"为键，值为Document列表：每个输入源对应一个Document，其content保存完整转写文本。这符合 Haystack 组件「输出统一为Document结构」的设计惯例，便于下游检索、存储与评估组件直接消费。

生命周期方法：warm_up / to_dict / from_dict

warm_up()

warm_up() -> None

将 FunASR 模型加载进内存。模型在首次调用时从 ModelScope 下载并缓存到本地；该方法具备幂等性（idempotent），重复调用是安全的，可放心用于流水线预热阶段以缩短首次run的延迟。

to_dict() 与 from_dict()

to_dict() -> dict[str, Any] from_dict(data: dict[str, Any]) -> FunASRTranscriber

to_dict()将组件序列化为字典，便于将组件配置持久化为 YAML/JSON 或存入版本控制；
from_dict(data)从字典反序列化重建组件实例，返回FunASRTranscriber。

二者配合即可实现 Haystack 标准的组件序列化往返（round-trip），例如将「SenseVoice + VAD + 标点 + GPU」的完整配置导出后，在其他环境或进程中原样还原。

底层机制与源码佐证

设备抽象：ComponentDevice

device参数的类型ComponentDevice定义于 haystack/utils/device.py。它是对单设备（Device）或多设备映射（DeviceMap）的统一封装，常用构造方式包括：

ComponentDevice.from_str("cuda")：从设备字符串创建单设备表示；
ComponentDevice.from_single(device)：从Device对象创建；
ComponentDevice.from_multiple(device_map)：从设备映射创建（多卡场景）。

内部还提供to_torch()/to_torch_str()等转换方法（见 haystack/utils/device.py），供组件在载入模型时将统一的设备抽象转换为具体深度学习框架（如 PyTorch）所需的设备格式。需要说明的是，设备映射不支持转换为单设备格式，多卡并行需使用专门的设备映射路径。

数据载体：ByteStream

ByteStream定义于 haystack/dataclasses/byte_stream.py，是 Haystack 中表示二进制对象的基础数据类，承载data（二进制内容）、meta（元数据）与mime_type三个字段。因此FunASRTranscriber可以直接消费内存中的音频字节流，而不必先把数据落盘成临时文件——这在上述「网页抓取 → 转写」以及「API 上传音频 → 转写」的实时链路中尤为实用。ByteStream还提供了to_file()与from_file_path()等工具方法（见 haystack/dataclasses/byte_stream.py），用于与文件系统互相转换。

输出模型：Document

转写结果统一封装为Document（haystack/dataclasses/document.py）：content存放转写全文，meta存放可 JSON 序列化的附加信息（如说话人"speakers"、音频文件名或完整路径）。这意味着转写结果无需任何适配即可进入 Haystack 的文档存储、嵌入与检索环节。

实践建议与注意事项

模型缓存与离线：首次运行会从 ModelScope 下载模型并缓存至~/.cache/modelscope。对完全离线的生产环境，可提前在联网机器上预热warm_up()并整体拷贝缓存目录；
长音频处理：默认开启的fsmn-vad会先把长音频切分为语音片段，再由batch_size_s（默认 300 秒）控制批处理粒度——吞吐与内存之间的权衡可通过该参数调节；若音频本身很短，也可将vad_model设为None以单一流处理；
说话人分离：需要按说话人区分转写内容时，务必设置spk_model="cam++"并在下游读取meta["speakers"]；
中文场景：默认的 SenseVoice 模型已覆盖中文，追求中文效果更佳时可显式选用paraformer-zh，并配合ct-punc标点恢复与use_itn=True规范化；
设备指定：有 GPU 时建议显式传入ComponentDevice.from_str("cuda")以获得最佳推理性能；不传则自动选择默认设备。