Haystack 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本文基于 Haystack 仓库中 v2.19 版本的 Optimum 集成 API 参考文档integrations-api/optimum.md系统讲解haystack_integrations.components.embedders.optimum模块下的两个核心组件OptimumDocumentEmbedder与OptimumTextEmbedder以及配套的 Pooling、Optimization、Quantization 三类模式配置。读完后你可以掌握如何在 Haystack 管道中使用 Hugging Face Optimum ONNX Runtime 计算文本/文档向量如何配置执行提供者CPU/CUDA/TensorRT、图优化与动态量化以及如何通过to_dict/from_dict完成组件的序列化与反序列化。集成定位与安装前提Optimum 集成属于 Haystack 的外部集成组件integrations核心特征是模型由 Hugging Face Optimum 库加载底层依赖 ONNX Runtime 做高速推理。需要说明的是当前仓库Haystack 核心库中不包含该集成的 Python 源码实现——在haystack/目录下搜索不到 optimum 相关模块该实现由独立的haystack-core-integrations工程维护仓库文档页面中也标注了这一点本仓库提供的是配套的 API 参考文档与组件使用说明。安装方式来自同版本的组件使用文档 optimumdocumentembedder.mdxpip install optimum-haystack两个组件在管道中的典型位置同样来自上述使用文档OptimumDocumentEmbedder常见于索引管道位于DocumentWriter之前负责为待写入的文档批量计算向量OptimumTextEmbedder常见于查询/RAG 管道位于嵌入式 Retriever 之前负责把用户查询文本编码为向量。两者的默认模型都是sentence-transformers/all-mpnet-base-v2且都支持通过prefix/suffix参数给每条文本添加指令式前后缀。OptimumDocumentEmbedder文档向量嵌入组件OptimumDocumentEmbedder用于计算Document对象的嵌入。每个文档的向量写入该Document的embedding字段。完整构造函数签名如下引自 v2.19 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各参数说明参数类型 / 默认值说明modelstr默认sentence-transformers/all-mpnet-base-v2Hugging Face Hub 上的模型 idtokenSecret \| None默认从HF_API_TOKEN环境变量读取strictFalse即允许为空访问私有/受限模型所需的 HF tokenprefix/suffixstr默认拼接在每条文本开头/结尾的字符串用于注入指令normalize_embeddingsbool默认True是否将向量归一化到单位长度onnx_execution_providerstr默认CPUExecutionProviderONNX 模型使用的执行提供者CPU/CUDA/TensorRT 等pooling_modestr \| OptimumEmbedderPooling \| None默认None池化模式为None时从模型配置自动推断model_kwargsdict[str, Any] \| None透传给模型的额外 kwargs重复时优先于model、onnx_execution_provider、token参数working_dirstr \| None优化/量化过程中间文件的存放目录使用优化或量化时必填optimizer_settingsOptimumEmbedderOptimizationConfig \| None图优化配置None表示不做额外优化quantizer_settingsOptimumEmbedderQuantizationConfig \| None量化配置None表示不做量化batch_sizeint默认32一次编码的 Document 数量progress_barbool默认True是否显示进度条meta_fields_to_embedlist[str] \| None需要与正文一起参与嵌入的 metadata 字段名列表embedding_separatorstr默认\n拼接 meta 字段与正文的分隔符核心方法与行为warm_up()初始化组件加载模型。文档同时注明“Components warm up automatically on first run”即组件在管道中首次运行时会自动预热也可以显式调用warm_up()run(documents: list[Document]) - dict[str, list[Document]]输入必须是Document列表否则抛出TypeError返回带embedding字段的更新后文档列表to_dict()/from_dict(data)组件序列化/反序列化保证该组件可以被持久化进管道定义如 YAML 配置文件后再还原。独立使用示例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) # Components warm up automatically on first run. result document_embedder.run([doc]) print(result[documents][0].embedding) # [0.017020374536514282, -0.023255806416273117, ...]OptimumTextEmbedder文本向量嵌入组件OptimumTextEmbedder面向单一字符串输入。其构造函数签名与文档版基本一致但不包含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, ) - Nonerun(text: str) - dict[str, list[float]]接收字符串返回{embedding: [...]}形式的向量输入非字符串时抛出TypeError。同样提供warm_up()、to_dict()、from_dict(data)方法。独立使用示例from haystack_integrations.components.embedders.optimum import OptimumTextEmbedder text_to_embed I love pizza! text_embedder OptimumTextEmbedder(modelsentence-transformers/all-mpnet-base-v2) # Components warm up automatically on first run. print(text_embedder.run(text_to_embed)) # {embedding: [-0.07804739475250244, 0.1498992145061493, ...]}三类模式配置Pooling、Optimization、QuantizationOptimum 嵌入组件相比其他嵌入器的差异化能力集中体现在三组带from_str工厂方法的枚举与两个配置类上。PoolingOptimumEmbedderPooling继承自Enum表示 Optimum 嵌入器支持的池化模式——把变长的句子级嵌入聚合为固定长度的向量。通过OptimumEmbedderPooling.from_str(string)可以从字符串构造池化模式pooling_mode参数接受str或枚举值传None时从模型配置推断。使用文档optimumdocumentembedder.mdx中出现的实际取值为OptimumEmbedderPooling.MEAN。OptimizationOptimumEmbedderOptimizationMode 与 OptimumEmbedderOptimizationConfigOptimumEmbedderOptimizationMode继承自Enum表示 ONNX 图优化模式可用from_str从字符串构造OptimumEmbedderOptimizationConfig包含两个字段modeOptimumEmbedderOptimizationMode——优化模式for_gpubool——是否为 GPU 优化。配置类提供三个方法to_optimum_config() - OptimizationConfig转换为 Optimum 库原生配置对象内部对接 Optimum ONNX Runtime 的图优化能力用于提升推理速度to_dict() - dict[str, Any]序列化为字典from_dict(data)从字典还原配置。使用文档中的实际取值为OptimumEmbedderOptimizationMode.O4GPU 场景下的最高级别优化。QuantizationOptimumEmbedderQuantizationMode 与 OptimumEmbedderQuantizationConfigOptimumEmbedderQuantizationMode继承自Enum表示动态量化模式OptimumEmbedderQuantizationConfig字段为modeOptimumEmbedderQuantizationMode——量化模式per_channelbool——是否启用逐通道量化。同样提供to_optimum_config() - QuantizationConfig、to_dict()、from_dict(data)三个方法。量化的目标是降低计算与内存开销。注意配置对象在warm_up阶段生效且启用优化或量化时必须通过working_dir指定中间文件目录文档明确要求“Required for optimization and quantization”。执行提供者与 model_kwargsTensorRT 引擎缓存实战onnx_execution_provider决定了 ONNX 模型在哪里执行默认 CPU。当使用TensorRT 执行提供者时有个重要的性能细节API 文档原文强调TensorRT 需要在推理前构建推理引擎涉及模型优化与节点融合耗时较长。为避免每次加载模型都重新构建引擎ONNX Runtime 提供了trt_engine_cache_enable和trt_engine_cache_path两个 provider options文档推荐通过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, } }, )另外按文档说明model_kwargs在参数冲突时具有最高优先级会覆盖model、onnx_execution_provider、token三个初始化参数。管道中的完整用法下面两个示例来自同版本的组件使用文档OptimumTextEmbedder、OptimumDocumentEmbedder展示了“GPU 执行 O4 图优化 MEAN 池化”的完整组合查询侧文本嵌入注意该示例需要 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, ..., }, }, ) print(results[embedder][embedding])索引侧文档嵌入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)认证与 Secret 管理两个组件的token参数默认为Secret.from_env_var(HF_API_TOKEN, strictFalse)即默认从HF_API_TOKEN环境变量读取 tokenstrictFalse表示该环境变量可以缺失公共模型场景不需要 token。组件使用文档补充说明仅当需要通过 Inference API / Inference Endpoints 访问私有或受限gated模型时才必须提供 HF API Token且组件也接受HF_TOKEN环境变量或直接在初始化时传入 token。Haystack 核心仓库中对应的机制说明见 Secret Management 概念页。小结与证据边界Optimum 集成的两个嵌入组件均以sentence-transformers/all-mpnet-base-v2为默认模型、CPUExecutionProvider为默认执行提供者默认开启向量归一化其独有能力是通过pooling_mode、optimizer_settings、quantizer_settings三个参数暴露的 ONNX 池化/图优化/动态量化三类模式配置类统一提供to_optimum_config/to_dict/from_dict接口启用优化或量化时必须设置working_dirTensorRT 场景建议通过model_kwargs开启引擎缓存本文所有签名、参数默认值、行为描述均来自仓库内 v2.19 参考文档 与 v2.19 组件使用文档由于当前仓库不含该集成的 Python 源码枚举成员完整取值如全部优化级别、池化模式清单请以optimum-haystack包的实际 API 为准本文仅引用文档中出现过的实际取值O4、MEAN等。【免费下载链接】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），仅供参考