Haystack 与 Optimum 集成指南：基于 ONNX Runtime 的 OptimumTextEmbedder 与 OptimumDocumentEmbedder

Haystack 与 Optimum 集成指南基于 ONNX Runtime 的 OptimumTextEmbedder 与 OptimumDocumentEmbedder【免费下载链接】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 仓库 version-2.20 的 Optimum 集成 API 参考文档 为核心系统讲解如何通过 HuggingFace Optimum 库加载模型、借助 ONNX Runtime 完成高性能的文本与文档向量化。你将掌握OptimumDocumentEmbedder、OptimumTextEmbedder的全部初始化参数与运行机制理解 Pooling池化、Optimization图优化、Quantization量化三种加速手段的配置方式并能在 Haystack 索引管道与查询/RAG 管道中直接落地使用。Optimum 集成概览为 Haystack 带来 ONNX Runtime 级推理速度在 Haystack 的 Embedder 组件家族中参见 Embedders 总览OptimumTextEmbedder与OptimumDocumentEmbedder是一对以HuggingFace Optimum库加载模型、以ONNX Runtime执行推理的向量化组件OptimumDocumentEmbedder接收一批Document对象计算每个文档的 embedding 并写回其embedding字段通常位于索引管道中DocumentWriter之前OptimumTextEmbedder接收单条文本字符串如用户查询返回一个浮点向量embedding通常位于查询/RAG 管道中 embedding Retriever 之前。两个组件共享同一套初始化参数体系默认模型均为sentence-transformers/all-mpnet-base-v2。相比纯 PyTorch 推理ONNX Runtime 通过图优化、算子融合与多执行提供方Execution Provider调度能显著提升推理吞吐、降低内存占用。安装该集成作为独立扩展包发布使用前需要安装pip install optimum-haystack安装完成后即可从haystack_integrations.components.embedders.optimum导入全部类包括两个 Embedder、Pooling 枚举、Optimization/Quantization 的 Mode 与 Config。组件无需显式预热文档指出 Components warm up automatically on first run即首次run()调用时会自动完成模型加载与预热当然在管道中显式调用warm_up()也是官方推荐做法可避免首次运行延迟。OptimumDocumentEmbedder文档批量向量化OptimumDocumentEmbedder面向文档批量场景核心职责是输入 Documents输出携带 embedding 的 Documents。初始化参数详解构造函数签名如下来自 API 参考文档__init__( model: str sentence-transformers/all-mpnet-base-v2, token: Secret | None Secret.from_env_var(HF_API_TOKEN, strictFalse), prefix: str , suffix: str , normalize_embeddings: bool True, onnx_execution_provider: str CPUExecutionProvider, pooling_mode: str | OptimumEmbedderPooling | None None, model_kwargs: dict[str, Any] | None None, working_dir: str | None None, optimizer_settings: OptimumEmbedderOptimizationConfig | None None, quantizer_settings: OptimumEmbedderQuantizationConfig | None None, batch_size: int 32, progress_bar: bool True, meta_fields_to_embed: list[str] | None None, embedding_separator: str \n, ) - None参数类型默认值说明modelstrsentence-transformers/all-mpnet-base-v2HuggingFace Hub 上的模型 IDtokenSecret \| None读取HF_API_TOKEN非严格用于 HTTP Bearer 认证的 HuggingFace Token仅访问私有/受限gated模型时需要prefix/suffixstr拼接到每段文本开头/结尾的字符串常用于注入指令式前缀normalize_embeddingsboolTrue是否将 embedding 归一化为单位长度便于余弦相似度计算onnx_execution_providerstrCPUExecutionProviderONNX Runtime 执行提供方如 CUDA、TensorRT、OpenVINO 等pooling_modestr \| OptimumEmbedderPooling \| NoneNone池化模式为None时从模型配置自动推断model_kwargsdict \| NoneNone透传给底层模型的额外参数与model、onnx_execution_provider、token冲突时覆盖这三者working_dirstr \| NoneNone优化/量化过程中中间文件的存放目录启用优化或量化时必须设置optimizer_settingsOptimumEmbedderOptimizationConfig \| NoneNone优化配置为None时不应用额外优化quantizer_settingsOptimumEmbedderQuantizationConfig \| NoneNone量化配置为None时不应用量化batch_sizeint32一次编码的 Document 数量progress_barboolTrue是否显示进度条meta_fields_to_embedlist[str] \| NoneNone需要与文档文本一起参与编码的 meta 字段列表embedding_separatorstr\n拼接 meta 字段与文档文本时使用的分隔符单独使用from haystack.dataclasses import Document from haystack_integrations.components.embedders.optimum import OptimumDocumentEmbedder doc Document(contentI love pizza!) document_embedder OptimumDocumentEmbedder(modelsentence-transformers/all-mpnet-base-v2) document_embedder.warm_up() result document_embedder.run([doc]) print(result[documents][0].embedding) # [0.017020374536514282, -0.023255806416273117, ...]生成的向量写入Document.embedding字段——这与 Haystack 的 Document 数据类 定义一致embedding: list[float] | None以 Python 列表形式保存稠密向量可直接用于后续检索与相似度计算。在管道中使用GPU 优化示例from haystack import Pipeline from haystack import Document from haystack_integrations.components.embedders.optimum import ( OptimumDocumentEmbedder, OptimumEmbedderPooling, OptimumEmbedderOptimizationConfig, OptimumEmbedderOptimizationMode, ) documents [ Document(contentMy name is Wolfgang and I live in Berlin), Document(contentI saw a black horse running), Document(contentGermany has many big cities), ] embedder OptimumDocumentEmbedder( modelintfloat/e5-base-v2, normalize_embeddingsTrue, onnx_execution_providerCUDAExecutionProvider, optimizer_settingsOptimumEmbedderOptimizationConfig( modeOptimumEmbedderOptimizationMode.O4, for_gpuTrue, ), working_dir/tmp/optimum, pooling_modeOptimumEmbedderPooling.MEAN, ) pipeline Pipeline() pipeline.add_component(embedder, embedder) results pipeline.run({embedder: {documents: documents}}) print(results[embedder][embedding])该示例同时展示了三个关键点使用 CUDA 执行提供方、通过OptimumEmbedderOptimizationConfig(modeO4, for_gpuTrue)启用面向 GPU 的 O4 级图优化、以working_dir/tmp/optimum指定优化中间文件目录启用优化时必须设置否则会报错。方法契约方法签名行为warm_up()- None初始化组件加载并预热模型run(documents)- dict[str, list[Document]]对 Documents 列表编码返回{documents: [...]}输入非list[Document]时抛出TypeErrorto_dict()- dict[str, Any]序列化为可 JSON 化的字典from_dict(data)- OptimumDocumentEmbedder从字典反序列化重建组件OptimumTextEmbedder单条文本实时编码OptimumTextEmbedder面向查询侧的单条文本输入构造参数与 Document 版本完全同构无batch_size、progress_bar、meta_fields_to_embed、embedding_separator四项文档专属参数__init__( model: str sentence-transformers/all-mpnet-base-v2, token: Secret | None Secret.from_env_var(HF_API_TOKEN, strictFalse), prefix: str , suffix: str , normalize_embeddings: bool True, onnx_execution_provider: str CPUExecutionProvider, pooling_mode: str | OptimumEmbedderPooling | None None, model_kwargs: dict[str, Any] | None None, working_dir: str | None None, optimizer_settings: OptimumEmbedderOptimizationConfig | None None, quantizer_settings: OptimumEmbedderQuantizationConfig | None None, ) - None单独使用CPU 默认配置from haystack_integrations.components.embedders.optimum import OptimumTextEmbedder text_to_embed I love pizza! text_embedder OptimumTextEmbedder(modelsentence-transformers/all-mpnet-base-v2) text_embedder.warm_up() print(text_embedder.run(text_to_embed)) # {embedding: [-0.07804739475250244, 0.1498992145061493, ...]}注意输出结构与 Document 版本不同Text 版本返回{embedding: [...]}直接给出向量本身而非包裹在 Documents 中。在查询管道中使用需 GPUfrom haystack import Pipeline from haystack_integrations.components.embedders.optimum import ( OptimumTextEmbedder, OptimumEmbedderPooling, OptimumEmbedderOptimizationConfig, OptimumEmbedderOptimizationMode, ) pipeline Pipeline() embedder OptimumTextEmbedder( modelintfloat/e5-base-v2, normalize_embeddingsTrue, onnx_execution_providerCUDAExecutionProvider, optimizer_settingsOptimumEmbedderOptimizationConfig( modeOptimumEmbedderOptimizationMode.O4, for_gpuTrue, ), working_dir/tmp/optimum, pooling_modeOptimumEmbedderPooling.MEAN, ) pipeline.add_component(embedder, embedder) results pipeline.run( { embedder: { text: Ex profunditate antique doctrinae, Ad caelos supra semper, Hoc incantamentum evoco, draco apparet, Incantamentum iam transactum est, }, }, ) print(results[embedder][embedding])方法契约方法签名行为warm_up()- None初始化组件run(text)- dict[str, list[float]]编码单条字符串返回{embedding: [...]}输入非str时抛出TypeErrorto_dict()/from_dict()序列化 / 反序列化与 Document 版本一致三大加速/调优机制Pooling、Optimization、QuantizationOptimum Embedder 的独特价值在于通过pooling_mode、optimizer_settings、quantizer_settings三个参数把 Optimum 库的能力直接暴露给 Haystack 开发者。Pooling从变长 token 到定长句向量OptimumEmbedderPooling定义于haystack_integrations.components.embedders.optimum.pooling继承自Enum负责把模型输出的变长token 级向量聚合为定长句向量例如官方示例中使用的OptimumEmbedderPooling.MEAN均值池化。它提供类方法from_str(string: str) - OptimumEmbedderPooling将字符串如mean转换为对应的池化枚举值。当pooling_modeNone时组件会从模型配置中自动推断合适的池化方式因此大多数场景无需显式指定。Optimization图优化提升推理速度OptimumEmbedderOptimizationModeoptimization模块继承自Enum声明了 Optimum Embedder 支持的 ONNX 图优化模式其语义对应 Optimum 官方 ONNX Runtime 优化指南中的优化级别。同样提供from_str(string) - OptimumEmbedderOptimizationMode类方法。从官方管道示例可以看到实际存在的枚举成员O4——即OptimumEmbedderOptimizationMode.O4属于较高等级、对 GPU 友好的优化档位。OptimumEmbedderOptimizationConfig则是对应配置类仅含两个字段字段类型说明modeOptimumEmbedderOptimizationMode采用的优化模式for_gpubool是否为 GPU 场景优化GPU 与 CPU 的最优图优化策略不同配置类提供三个方法to_optimum_config() - OptimizationConfig转换为 Optimum 库原生的OptimizationConfig对象to_dict() - dict[str, Any]序列化为字典from_dict(data) - OptimumEmbedderOptimizationConfig从字典重建配置。Quantization降低计算与内存成本OptimumEmbedderQuantizationModequantization模块继承自Enum声明支持的动态量化模式语义对应 Optimum 官方 ONNX 量化指南。from_str(string) - OptimumEmbedderQuantizationMode可将字符串转为枚举值具体可用模式名由 Optimum 库定义配置时以该库支持的量化模式为准。OptimumEmbedderQuantizationConfig字段如下字段类型说明modeOptimumEmbedderQuantizationMode采用的量化模式per_channelbool是否按通道per-channel粒度执行量化同样提供to_optimum_config() - QuantizationConfig、to_dict()、from_dict()三个方法分别完成到 Optimum 原生配置的转换与序列化往返。使用约束无论启用 Optimization 还是 Quantization都必须同时设置working_dir参数用于存放优化/量化过程中产生的中间文件如官方示例中的/tmp/optimum。TensorRT 执行提供方与引擎缓存当使用 TensorRT 执行提供方时需特别注意TensorRT 要求在推理前预先构建推理引擎该过程涉及模型优化与节点融合耗时较长。为避免每次加载模型都重建引擎ONNX Runtime 提供了trt_engine_cache_enable与trt_engine_cache_path两个 provider 选项来保存引擎。官方推荐通过model_kwargs传入embedder OptimumDocumentEmbedder( modelsentence-transformers/all-mpnet-base-v2, onnx_execution_providerTensorrtExecutionProvider, model_kwargs{ provider_options: { trt_engine_cache_enable: True, trt_engine_cache_path: tmp/trt_cache, } }, )该写法同样适用于OptimumTextEmbedder。从源码语义看model_kwargs会被透传给底层 Optimum 模型且在键冲突时优先于model、onnx_execution_provider、token三个初始化参数——因此上述代码中的执行提供方实际由provider_options生效。序列化与反序列化配置随管道一起保存两个 Embedder 都实现了to_dict()/from_dict()。to_dict()把组件包括model、normalize_embeddings、onnx_execution_provider、pooling_mode、optimizer_settings、quantizer_settings等全部初始化状态转换为 JSON 兼容字典便于与 Haystack 管道的 YAML/JSON 序列化体系集成from_dict()则从字典还原组件实例保证配置可以持久化存储、版本化并跨进程复用。与之配套OptimumEmbedderOptimizationConfig与OptimumEmbedderQuantizationConfig也都实现了各自的to_dict()/from_dict()确保优化/量化设置能随组件完整序列化。认证与 Secret 管理组件初始化时默认读取HF_API_TOKEN环境变量Secret.from_env_var(HF_API_TOKEN, strictFalse)非严格模式。认证仅在与HuggingFace API Token相关的场景访问私有或 gated 模型才必需公开模型无需任何凭据。Haystack 的 Secret 工具类 提供了统一的密钥封装机制Secret.from_env_var(HF_API_TOKEN, strictFalse)从环境变量读取strictFalse表示变量未设置时不抛异常Secret.from_token(...)直接传入 Token该方式不可序列化Secret.resolve_value()在真正需要时惰性解析密钥值避免密钥明文落盘。总结Optimum 集成为 Haystack 提供了本地模型 ONNX Runtime的高性能向量化方案OptimumDocumentEmbedder负责索引侧的文档批量编码OptimumTextEmbedder负责查询侧的实时编码两者共享默认模型sentence-transformers/all-mpnet-base-v2并通过 Pooling、Optimization、Quantization 三组配置实现对推理速度与资源占用的精细调控。结合onnx_execution_provider可在 CPU、CUDA、TensorRT 等执行提供方之间灵活切换配合working_dir与model_kwargs完成引擎缓存等进阶调优。若需进一步查阅类与方法的完整签名可参阅 version-2.20 Optimum API 参考以及配套的 OptimumDocumentEmbedder 与 OptimumTextEmbedder 使用指南。【免费下载链接】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），仅供参考