Haystack Optimum 集成实战用 Optimum ONNX Runtime 打造高性能文本与文档嵌入组件【免费下载链接】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 官方 Optimum 集成optimum-haystack展开系统讲解OptimumTextEmbedder与OptimumDocumentEmbedder两个组件的安装、认证、参数配置、独立运行与 Pipeline 集成方式并深入剖析 Optimum 嵌入组件专属的池化Pooling、图优化Optimization与量化Quantization三大调优能力。读完本文你将掌握如何在 Haystack 索引管道与 RAG 查询管道中基于 Hugging Face Optimum 与 ONNX Runtime 搭建可本地加速、可序列化的向量化流水线。Optimum 集成是什么本地高性能嵌入的组件化封装Haystack 将 Hugging Face 生态中的 Optimum其中收录了 OpenAI、Azure、Cohere、SentenceTransformers 等全部官方嵌入组件OptimumTextEmbedder负责把单条文本如用户查询编码为向量输出embedding字段典型位置是 RAG/查询管道中位于嵌入检索器Embedding Retriever之前。OptimumDocumentEmbedder负责把一批Document编码为向量并把结果写回每个Document的embedding字段典型位置是索引管道中位于DocumentWriter之前。这两个组件的共同技术底座是使用 Hugging Face Optimum 库加载模型并借助 ONNX Runtime 完成高速推理。因此它们既保留了 Sentence-Transformer 等生态中丰富的开源嵌入模型又通过 ONNX 图优化、动态量化等手段获得比原生 PyTorch 推理更低的延迟与更小的显存/内存占用。默认模型为sentence-transformers/all-mpnet-base-v2无需额外指定即可开箱使用。组件第一次run()时会自动完成预热warm_up后续调用直接复用已加载的模型会话。安装与环境准备使用该集成需要单独安装官方集成包该集成的维护仓库为 deepset 的 haystack-core-integrations 中 integrations/optimum 目录其说明文档与组件页见 docs-website/versioned_docs/version-2.21/pipeline-components/embedders/optimumdocumentembedder.mdx 与 docs-website/versioned_docs/version-2.21/pipeline-components/embedders/optimumtextembedder.mdxpip install optimum-haystack安装后即可从haystack_integrations.components.embedders.optimum导入全部符号from haystack_integrations.components.embedders.optimum import ( OptimumTextEmbedder, OptimumDocumentEmbedder, OptimumEmbedderPooling, OptimumEmbedderOptimizationConfig, OptimumEmbedderOptimizationMode, OptimumEmbedderQuantizationConfig, OptimumEmbedderQuantizationMode, )需要说明的是OptimumTextEmbedder/OptimumDocumentEmbedder的完整 API 参考含全部构造参数与方法的签名可在 docs-website/reference_versioned_docs/version-2.21/integrations-api/optimum.md 中查阅后文参数表均以此为依据。认证配置何时需要 Hugging Face Token默认情况下组件从环境变量HF_API_TOKEN读取令牌初始化签名中token: Secret | None Secret.from_env_var(HF_API_TOKEN, strictFalse)即未设置时也不会报错。官方文档明确只有在通过 Serverless Inference API 或 Inference Endpoints 访问私有模型、gated受限模型时才需要 Hugging Face API Token 认证。也就是说直接下载并本地运行公开模型不需要任何密钥。认证有两种方式设置环境变量HF_API_TOKEN或HF_TOKEN初始化组件时显式传入token参数。若需要在程序内安全地管理密钥避免硬编码可参考 Haystack 的 Secret 管理与Secret.from_env_var用法见 docs-website/versioned_docs/version-2.21/concepts/secret-management.mdx。OptimumTextEmbedder查询侧文本嵌入完整构造签名OptimumTextEmbedder的构造签名如下来自 API 参考OptimumTextEmbedder( 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各参数含义与取值说明参数类型默认值说明modelstrsentence-transformers/all-mpnet-base-v2Hugging Face Hub 上的模型 ID支持所有可被 Optimum 导出为 ONNX 的嵌入模型tokenSecret \| NoneHF_API_TOKEN环境变量访问私有/受限模型时使用的 Hugging Face 令牌prefixstr拼接到每条待嵌入文本开头的字符串常用于注入指令/提示如 e5 系模型的query: 前缀suffixstr拼接到每条待嵌入文本结尾的字符串normalize_embeddingsboolTrue是否将嵌入向量归一化为单位长度便于用余弦相似度检索onnx_execution_providerstrCPUExecutionProviderONNX Runtime 执行提供程序如CUDAExecutionProvider、TensorrtExecutionProvider等pooling_modestr \| OptimumEmbedderPooling \| NoneNone池化模式为None时从模型配置自动推断model_kwargsdict \| NoneNone透传给底层模型的额外关键字参数与model/onnx_execution_provider/token重复时以本参数中的值为准覆盖初始化参数working_dirstr \| NoneNone模型优化/量化过程中生成中间文件的目录启用优化或量化时必填optimizer_settingsOptimumEmbedderOptimizationConfig \| NoneNone图优化配置为None时不应用额外优化quantizer_settingsOptimumEmbedderQuantizationConfig \| NoneNone量化配置为None时不应用量化独立使用示例from haystack_integrations.components.embedders.optimum import OptimumTextEmbedder text_to_embed I love pizza! text_embedder OptimumTextEmbedder(modelsentence-transformers/all-mpnet-base-v2) # 组件会在首次运行时自动预热也可显式调用 warm_up() print(text_embedder.run(text_to_embed)) # {embedding: [-0.07804739475250244, 0.1498992145061493, ...]}run(text: str)接受单个字符串返回dict[str, list[float]]即{embedding: [...]}若传入的不是字符串将抛出TypeError。在 Pipeline 中使用GPU 加速 图优化示例以下示例来自官方文档注意它需要 GPU 支持才能执行指定了CUDAExecutionProvider并对模型应用 O4 级 GPU 图优化from 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])注意示例中三个要点e5-base-v2这类模型通常配合normalize_embeddingsTrue使用GPU 优化模式需要for_gpuTrue启用优化必须提供working_dir存放中间文件。OptimumDocumentEmbedder索引侧文档批量嵌入完整构造签名OptimumDocumentEmbedder在文本版基础上增加了批量处理相关参数OptimumDocumentEmbedder( 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除与OptimumTextEmbedder相同的前面各参数外文档版专属参数为参数类型默认值说明batch_sizeint32每次编码的 Document 数量控制批量推理吞吐与显存占用progress_barboolTrue是否显示进度条meta_fields_to_embedlist[str] \| NoneNone需要连同正文一起参与嵌入的元数据字段列表如标题、作者、来源链接embedding_separatorstr\n拼接元数据字段与正文时使用的分隔符默认换行独立使用示例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) # 组件会在首次运行时自动预热也可显式调用 warm_up() result document_embedder.run([doc]) print(result[documents][0].embedding) # [0.017020374536514282, -0.023255806416273117, ...]run(documents: list[Document])接收 Document 列表返回dict[str, list[Document]]每个 Document 的embedding字段被就地写入若输入不是 Document 列表将抛出TypeError。在 Pipeline 中使用索引管道示例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][documents][0].embedding)在实际索引管道中该组件通常位于文本转换器/预处理器之后、DocumentWriter之前先由它把每篇文档向量化再由 Writer 连同向量一并写入文档存储。meta_fields_to_embed与embedding_separator可用于把文档的元数据如标题拼进向量内容从而让检索结果在语义上同时匹配正文与元数据。三大专属调优能力Pooling、Optimization、QuantizationOptimum 嵌入组件区别于普通 Embedder 的核心是官方文档中重点强调的、可通过模式配置控制的三个专属参数族。它们分别在 docs-website/reference_versioned_docs/version-2.21/integrations-api/optimum.md 的pooling、optimization、quantization三个模块中被定义。池化模式OptimumEmbedderPoolingOptimumEmbedderPooling是一个枚举类用于从变长句子编码生成定长的句向量。Transformer 编码器对每个 token 都会输出一个向量池化则是把这些 token 级向量聚合为单个定长向量例如取平均MEAN。其用法通过OptimumEmbedderPooling.MEAN等枚举值显式指定也支持字符串并提供了from_str(string: str) - OptimumEmbedderPooling类方法把字符串转换为枚举构造参数pooling_mode为None时组件会从模型配置自动推断池化方式因此大多数情况下无需手动指定。图优化模式OptimumEmbedderOptimizationMode 与 OptimumEmbedderOptimizationConfigONNX 图优化通过对计算图进行算子融合、常量折叠、冗余节点消除等变换来提升推理速度。OptimumEmbedderOptimizationMode枚举定义了可选的优化级别官方文档建议对照 Optimum 的 ONNX 优化使用指南选择合适级别OptimumEmbedderOptimizationConfig承载配置mode: OptimumEmbedderOptimizationMode优化模式for_gpu: bool是否针对 GPU 优化。GPU 与 CPU 的最优图变换集合不同需按实际部署硬件选择。配置对象提供以下方法config OptimumEmbedderOptimizationConfig( modeOptimumEmbedderOptimizationMode.O4, for_gpuTrue, ) # 转换为 Optimum 库的 OptimizationConfig供底层调用 optimum_config config.to_optimum_config() # 序列化/反序列化 data config.to_dict() # - dict[str, Any] config2 OptimumEmbedderOptimizationConfig.from_dict(data)其中to_optimum_config() - OptimizationConfig是连接 Haystack 配置与 Optimum 底层实现的桥梁to_dict/from_dict用于把配置对象安全地序列化为字典例如存入 YAML 管道定义再恢复。动态量化模式OptimumEmbedderQuantizationMode 与 OptimumEmbedderQuantizationConfig量化通过降低权重/激活的数值精度如 FP32 → INT8来降低计算与内存成本适用于对延迟和模型体积敏感、可接受轻微精度损失的场景。OptimumEmbedderQuantizationMode枚举定义了支持的动态量化模式官方文档建议对照 Optimum 的 ONNX 量化使用指南OptimumEmbedderQuantizationConfig承载配置mode: OptimumEmbedderQuantizationMode量化模式per_channel: bool是否启用逐通道per-channel量化逐通道量化通常精度损失更小。同样具备三个方法quant_config OptimumEmbedderQuantizationConfig( modeOptimumEmbedderQuantizationMode.INT8, # 以实际枚举成员为准 per_channelTrue, ) optimum_quant_config quant_config.to_optimum_config() # - QuantizationConfig data quant_config.to_dict() quant_config2 OptimumEmbedderQuantizationConfig.from_dict(data)to_optimum_config() - QuantizationConfig将其转换为 Optimum 的QuantizationConfigto_dict/from_dict负责序列化往返。使用前提working_dir 与 model_kwargs启用优化或量化时Optimum 需要把中间产物如优化后的图、量化校准数据写入磁盘因此working_dir在启用优化/量化时是必填参数例如官方示例中的working_dir/tmp/optimum。若需要向底层模型传递更细粒度的控制参数可统一放入model_kwargs且model_kwargs中的键值在发生重复时优先于model、onnx_execution_provider、token三个初始化参数这为高阶用户提供了覆盖默认行为的入口。执行提供程序从 CPU 到 GPU/TensorRTonnx_execution_provider决定 ONNX 模型由哪个后端执行默认CPUExecutionProvider开箱即用无需任何额外依赖。需要 GPU 加速时可切换为CUDAExecutionProvider官方 Pipeline 示例即使用该值。完整的提供程序列表以 ONNX Runtime 官方文档为准。官方文档对TensorRT 执行提供程序给出了专门的注意事项TensorRT 在正式推理前需要提前构建推理引擎构建过程包含模型优化与节点融合耗时较长为避免每次加载模型都重复构建ONNX Runtime 提供了trt_engine_cache_enable与trt_engine_cache_path两个选项把引擎缓存到磁盘。官方建议在使用 TensorRT 时通过model_kwargs的provider_options传入这两个选项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初始化签名中的onnx_execution_provider与model_kwargs参数完全相同。缓存的引擎在首次构建后即可复用显著缩短后续冷启动时间。生命周期与序列化warm_up / to_dict / from_dict两个组件都遵循 Haystack 组件的标准生命周期API 参考中定义了四个核心方法warm_up() - None初始化组件加载模型并如需执行优化/量化。官方文档的用法示例中说明组件会在首次run()时自动完成预热也可以显式调用warm_up()提前加载把模型加载耗时排除在首次推理之外这一点与仓库内其它嵌入组件一致——例如 haystack/components/embedders/openai_text_embedder.py 中的OpenAITextEmbedder同样在run内调用self.warm_up()实现惰性初始化。run(...)执行嵌入计算文本版输入str文档版输入list[Document]并在输入类型错误时抛出TypeError。to_dict() - dict[str, Any]把组件连同全部构造参数序列化为字典便于写入 YAML/JSON 管道定义。from_dict(data: dict[str, Any]) - OptimumTextEmbedder / OptimumDocumentEmbedder从字典反序列化重建组件。这意味着包含 Optimum 嵌入组件的管道可以像其它 Haystack 管道一样被Pipeline.dump()/Pipeline.load()持久化与恢复配置中的枚举、Secret 与嵌套的优化/量化配置对象都能被完整保存。小结如何组合这些能力综合全文搭建一套高性能的 Optimum 嵌入流水线的推荐路径是pip install optimum-haystack安装集成索引侧选用OptimumDocumentEmbedder配合batch_size控制吞吐、meta_fields_to_embed让元数据参与语义编码查询侧选用OptimumTextEmbedder用prefix/suffix按模型要求注入指令如 e5 系模型的 query 前缀按部署硬件选择onnx_execution_providerCPU 用默认值NVIDIA GPU 用CUDAExecutionProvider进一步加速可选用TensorrtExecutionProvider并开启引擎缓存追求更低延迟时启用图优化OptimumEmbedderOptimizationConfig 合适的mode/for_gpu追求更低内存占用时启用动态量化OptimumEmbedderQuantizationConfig两者都需提供working_dir通过to_dict/from_dict把配置固化进管道定义保证可复现。若想横向对比 Haystack 中的其它嵌入方案可参考 docs-website/versioned_docs/version-2.21/pipeline-components/embedders.mdx 中列出的全部 Embedder 组件清单按 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 Optimum 集成实战：用 Optimum + ONNX Runtime 打造高性能文本与文档嵌入组件
Haystack Optimum 集成实战用 Optimum ONNX Runtime 打造高性能文本与文档嵌入组件【免费下载链接】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 官方 Optimum 集成optimum-haystack展开系统讲解OptimumTextEmbedder与OptimumDocumentEmbedder两个组件的安装、认证、参数配置、独立运行与 Pipeline 集成方式并深入剖析 Optimum 嵌入组件专属的池化Pooling、图优化Optimization与量化Quantization三大调优能力。读完本文你将掌握如何在 Haystack 索引管道与 RAG 查询管道中基于 Hugging Face Optimum 与 ONNX Runtime 搭建可本地加速、可序列化的向量化流水线。Optimum 集成是什么本地高性能嵌入的组件化封装Haystack 将 Hugging Face 生态中的 Optimum其中收录了 OpenAI、Azure、Cohere、SentenceTransformers 等全部官方嵌入组件OptimumTextEmbedder负责把单条文本如用户查询编码为向量输出embedding字段典型位置是 RAG/查询管道中位于嵌入检索器Embedding Retriever之前。OptimumDocumentEmbedder负责把一批Document编码为向量并把结果写回每个Document的embedding字段典型位置是索引管道中位于DocumentWriter之前。这两个组件的共同技术底座是使用 Hugging Face Optimum 库加载模型并借助 ONNX Runtime 完成高速推理。因此它们既保留了 Sentence-Transformer 等生态中丰富的开源嵌入模型又通过 ONNX 图优化、动态量化等手段获得比原生 PyTorch 推理更低的延迟与更小的显存/内存占用。默认模型为sentence-transformers/all-mpnet-base-v2无需额外指定即可开箱使用。组件第一次run()时会自动完成预热warm_up后续调用直接复用已加载的模型会话。安装与环境准备使用该集成需要单独安装官方集成包该集成的维护仓库为 deepset 的 haystack-core-integrations 中 integrations/optimum 目录其说明文档与组件页见 docs-website/versioned_docs/version-2.21/pipeline-components/embedders/optimumdocumentembedder.mdx 与 docs-website/versioned_docs/version-2.21/pipeline-components/embedders/optimumtextembedder.mdxpip install optimum-haystack安装后即可从haystack_integrations.components.embedders.optimum导入全部符号from haystack_integrations.components.embedders.optimum import ( OptimumTextEmbedder, OptimumDocumentEmbedder, OptimumEmbedderPooling, OptimumEmbedderOptimizationConfig, OptimumEmbedderOptimizationMode, OptimumEmbedderQuantizationConfig, OptimumEmbedderQuantizationMode, )需要说明的是OptimumTextEmbedder/OptimumDocumentEmbedder的完整 API 参考含全部构造参数与方法的签名可在 docs-website/reference_versioned_docs/version-2.21/integrations-api/optimum.md 中查阅后文参数表均以此为依据。认证配置何时需要 Hugging Face Token默认情况下组件从环境变量HF_API_TOKEN读取令牌初始化签名中token: Secret | None Secret.from_env_var(HF_API_TOKEN, strictFalse)即未设置时也不会报错。官方文档明确只有在通过 Serverless Inference API 或 Inference Endpoints 访问私有模型、gated受限模型时才需要 Hugging Face API Token 认证。也就是说直接下载并本地运行公开模型不需要任何密钥。认证有两种方式设置环境变量HF_API_TOKEN或HF_TOKEN初始化组件时显式传入token参数。若需要在程序内安全地管理密钥避免硬编码可参考 Haystack 的 Secret 管理与Secret.from_env_var用法见 docs-website/versioned_docs/version-2.21/concepts/secret-management.mdx。OptimumTextEmbedder查询侧文本嵌入完整构造签名OptimumTextEmbedder的构造签名如下来自 API 参考OptimumTextEmbedder( 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各参数含义与取值说明参数类型默认值说明modelstrsentence-transformers/all-mpnet-base-v2Hugging Face Hub 上的模型 ID支持所有可被 Optimum 导出为 ONNX 的嵌入模型tokenSecret \| NoneHF_API_TOKEN环境变量访问私有/受限模型时使用的 Hugging Face 令牌prefixstr拼接到每条待嵌入文本开头的字符串常用于注入指令/提示如 e5 系模型的query: 前缀suffixstr拼接到每条待嵌入文本结尾的字符串normalize_embeddingsboolTrue是否将嵌入向量归一化为单位长度便于用余弦相似度检索onnx_execution_providerstrCPUExecutionProviderONNX Runtime 执行提供程序如CUDAExecutionProvider、TensorrtExecutionProvider等pooling_modestr \| OptimumEmbedderPooling \| NoneNone池化模式为None时从模型配置自动推断model_kwargsdict \| NoneNone透传给底层模型的额外关键字参数与model/onnx_execution_provider/token重复时以本参数中的值为准覆盖初始化参数working_dirstr \| NoneNone模型优化/量化过程中生成中间文件的目录启用优化或量化时必填optimizer_settingsOptimumEmbedderOptimizationConfig \| NoneNone图优化配置为None时不应用额外优化quantizer_settingsOptimumEmbedderQuantizationConfig \| NoneNone量化配置为None时不应用量化独立使用示例from haystack_integrations.components.embedders.optimum import OptimumTextEmbedder text_to_embed I love pizza! text_embedder OptimumTextEmbedder(modelsentence-transformers/all-mpnet-base-v2) # 组件会在首次运行时自动预热也可显式调用 warm_up() print(text_embedder.run(text_to_embed)) # {embedding: [-0.07804739475250244, 0.1498992145061493, ...]}run(text: str)接受单个字符串返回dict[str, list[float]]即{embedding: [...]}若传入的不是字符串将抛出TypeError。在 Pipeline 中使用GPU 加速 图优化示例以下示例来自官方文档注意它需要 GPU 支持才能执行指定了CUDAExecutionProvider并对模型应用 O4 级 GPU 图优化from 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])注意示例中三个要点e5-base-v2这类模型通常配合normalize_embeddingsTrue使用GPU 优化模式需要for_gpuTrue启用优化必须提供working_dir存放中间文件。OptimumDocumentEmbedder索引侧文档批量嵌入完整构造签名OptimumDocumentEmbedder在文本版基础上增加了批量处理相关参数OptimumDocumentEmbedder( 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除与OptimumTextEmbedder相同的前面各参数外文档版专属参数为参数类型默认值说明batch_sizeint32每次编码的 Document 数量控制批量推理吞吐与显存占用progress_barboolTrue是否显示进度条meta_fields_to_embedlist[str] \| NoneNone需要连同正文一起参与嵌入的元数据字段列表如标题、作者、来源链接embedding_separatorstr\n拼接元数据字段与正文时使用的分隔符默认换行独立使用示例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) # 组件会在首次运行时自动预热也可显式调用 warm_up() result document_embedder.run([doc]) print(result[documents][0].embedding) # [0.017020374536514282, -0.023255806416273117, ...]run(documents: list[Document])接收 Document 列表返回dict[str, list[Document]]每个 Document 的embedding字段被就地写入若输入不是 Document 列表将抛出TypeError。在 Pipeline 中使用索引管道示例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][documents][0].embedding)在实际索引管道中该组件通常位于文本转换器/预处理器之后、DocumentWriter之前先由它把每篇文档向量化再由 Writer 连同向量一并写入文档存储。meta_fields_to_embed与embedding_separator可用于把文档的元数据如标题拼进向量内容从而让检索结果在语义上同时匹配正文与元数据。三大专属调优能力Pooling、Optimization、QuantizationOptimum 嵌入组件区别于普通 Embedder 的核心是官方文档中重点强调的、可通过模式配置控制的三个专属参数族。它们分别在 docs-website/reference_versioned_docs/version-2.21/integrations-api/optimum.md 的pooling、optimization、quantization三个模块中被定义。池化模式OptimumEmbedderPoolingOptimumEmbedderPooling是一个枚举类用于从变长句子编码生成定长的句向量。Transformer 编码器对每个 token 都会输出一个向量池化则是把这些 token 级向量聚合为单个定长向量例如取平均MEAN。其用法通过OptimumEmbedderPooling.MEAN等枚举值显式指定也支持字符串并提供了from_str(string: str) - OptimumEmbedderPooling类方法把字符串转换为枚举构造参数pooling_mode为None时组件会从模型配置自动推断池化方式因此大多数情况下无需手动指定。图优化模式OptimumEmbedderOptimizationMode 与 OptimumEmbedderOptimizationConfigONNX 图优化通过对计算图进行算子融合、常量折叠、冗余节点消除等变换来提升推理速度。OptimumEmbedderOptimizationMode枚举定义了可选的优化级别官方文档建议对照 Optimum 的 ONNX 优化使用指南选择合适级别OptimumEmbedderOptimizationConfig承载配置mode: OptimumEmbedderOptimizationMode优化模式for_gpu: bool是否针对 GPU 优化。GPU 与 CPU 的最优图变换集合不同需按实际部署硬件选择。配置对象提供以下方法config OptimumEmbedderOptimizationConfig( modeOptimumEmbedderOptimizationMode.O4, for_gpuTrue, ) # 转换为 Optimum 库的 OptimizationConfig供底层调用 optimum_config config.to_optimum_config() # 序列化/反序列化 data config.to_dict() # - dict[str, Any] config2 OptimumEmbedderOptimizationConfig.from_dict(data)其中to_optimum_config() - OptimizationConfig是连接 Haystack 配置与 Optimum 底层实现的桥梁to_dict/from_dict用于把配置对象安全地序列化为字典例如存入 YAML 管道定义再恢复。动态量化模式OptimumEmbedderQuantizationMode 与 OptimumEmbedderQuantizationConfig量化通过降低权重/激活的数值精度如 FP32 → INT8来降低计算与内存成本适用于对延迟和模型体积敏感、可接受轻微精度损失的场景。OptimumEmbedderQuantizationMode枚举定义了支持的动态量化模式官方文档建议对照 Optimum 的 ONNX 量化使用指南OptimumEmbedderQuantizationConfig承载配置mode: OptimumEmbedderQuantizationMode量化模式per_channel: bool是否启用逐通道per-channel量化逐通道量化通常精度损失更小。同样具备三个方法quant_config OptimumEmbedderQuantizationConfig( modeOptimumEmbedderQuantizationMode.INT8, # 以实际枚举成员为准 per_channelTrue, ) optimum_quant_config quant_config.to_optimum_config() # - QuantizationConfig data quant_config.to_dict() quant_config2 OptimumEmbedderQuantizationConfig.from_dict(data)to_optimum_config() - QuantizationConfig将其转换为 Optimum 的QuantizationConfigto_dict/from_dict负责序列化往返。使用前提working_dir 与 model_kwargs启用优化或量化时Optimum 需要把中间产物如优化后的图、量化校准数据写入磁盘因此working_dir在启用优化/量化时是必填参数例如官方示例中的working_dir/tmp/optimum。若需要向底层模型传递更细粒度的控制参数可统一放入model_kwargs且model_kwargs中的键值在发生重复时优先于model、onnx_execution_provider、token三个初始化参数这为高阶用户提供了覆盖默认行为的入口。执行提供程序从 CPU 到 GPU/TensorRTonnx_execution_provider决定 ONNX 模型由哪个后端执行默认CPUExecutionProvider开箱即用无需任何额外依赖。需要 GPU 加速时可切换为CUDAExecutionProvider官方 Pipeline 示例即使用该值。完整的提供程序列表以 ONNX Runtime 官方文档为准。官方文档对TensorRT 执行提供程序给出了专门的注意事项TensorRT 在正式推理前需要提前构建推理引擎构建过程包含模型优化与节点融合耗时较长为避免每次加载模型都重复构建ONNX Runtime 提供了trt_engine_cache_enable与trt_engine_cache_path两个选项把引擎缓存到磁盘。官方建议在使用 TensorRT 时通过model_kwargs的provider_options传入这两个选项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初始化签名中的onnx_execution_provider与model_kwargs参数完全相同。缓存的引擎在首次构建后即可复用显著缩短后续冷启动时间。生命周期与序列化warm_up / to_dict / from_dict两个组件都遵循 Haystack 组件的标准生命周期API 参考中定义了四个核心方法warm_up() - None初始化组件加载模型并如需执行优化/量化。官方文档的用法示例中说明组件会在首次run()时自动完成预热也可以显式调用warm_up()提前加载把模型加载耗时排除在首次推理之外这一点与仓库内其它嵌入组件一致——例如 haystack/components/embedders/openai_text_embedder.py 中的OpenAITextEmbedder同样在run内调用self.warm_up()实现惰性初始化。run(...)执行嵌入计算文本版输入str文档版输入list[Document]并在输入类型错误时抛出TypeError。to_dict() - dict[str, Any]把组件连同全部构造参数序列化为字典便于写入 YAML/JSON 管道定义。from_dict(data: dict[str, Any]) - OptimumTextEmbedder / OptimumDocumentEmbedder从字典反序列化重建组件。这意味着包含 Optimum 嵌入组件的管道可以像其它 Haystack 管道一样被Pipeline.dump()/Pipeline.load()持久化与恢复配置中的枚举、Secret 与嵌套的优化/量化配置对象都能被完整保存。小结如何组合这些能力综合全文搭建一套高性能的 Optimum 嵌入流水线的推荐路径是pip install optimum-haystack安装集成索引侧选用OptimumDocumentEmbedder配合batch_size控制吞吐、meta_fields_to_embed让元数据参与语义编码查询侧选用OptimumTextEmbedder用prefix/suffix按模型要求注入指令如 e5 系模型的 query 前缀按部署硬件选择onnx_execution_providerCPU 用默认值NVIDIA GPU 用CUDAExecutionProvider进一步加速可选用TensorrtExecutionProvider并开启引擎缓存追求更低延迟时启用图优化OptimumEmbedderOptimizationConfig 合适的mode/for_gpu追求更低内存占用时启用动态量化OptimumEmbedderQuantizationConfig两者都需提供working_dir通过to_dict/from_dict把配置固化进管道定义保证可复现。若想横向对比 Haystack 中的其它嵌入方案可参考 docs-website/versioned_docs/version-2.21/pipeline-components/embedders.mdx 中列出的全部 Embedder 组件清单按 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），仅供参考
