Haystack 与 NVIDIA NIM 集成指南Embedder、ChatGenerator 与 Ranker 组件实战解析【免费下载链接】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.18 参考文档 docs-website/reference_versioned_docs/version-2.18/integrations-api/nvidia.md中定义的 NVIDIA 集成 API系统讲解nvidia-haystack集成包中的四大组件文档/文本向量化NvidiaDocumentEmbedder、NvidiaTextEmbedder、对话生成NvidiaChatGenerator与重排序NvidiaRanker。你将掌握这些组件的全部初始化参数、运行契约、截断模式、串行化机制以及如何将它们接入索引管道和 RAG 查询管道构建基于 NVIDIA API Catalog 或自托管 NIM 的生产级 LLM 应用。集成概览一个包覆盖 Embedding / Generation / RerankingNVIDIA 集成是 Haystack 生态中把 NVIDIA 的推理能力接入管道Pipeline的标准方式。它通过nvidia-haystack包提供覆盖 LLM 应用中三个核心环节组件模块路径职责管道中的典型位置NvidiaDocumentEmbedderhaystack_integrations.components.embedders.nvidia为一组 Document 计算向量并写回每个文档的embedding字段索引管道中DocumentWriter之前NvidiaTextEmbedderhaystack_integrations.components.embedders.nvidia将单个字符串如查询编码为向量查询/RAG 管道中向量检索器之前NvidiaChatGeneratorhaystack_integrations.components.generators.nvidia基于 NVIDIA 生成式模型完成对话补全ChatPromptBuilder之后NvidiaRankerhaystack_integrations.components.rankers.nvidia依据查询对文档做语义相关性排序查询管道中检索器之后这些组件既支持 NVIDIA 托管的API Catalog默认接入https://integrate.api.nvidia.com/v1也支持自托管 NVIDIA NIMapi_url指向本地地址即可。官方使用指南见 NvidiaDocumentEmbedder、NvidiaTextEmbedder、NvidiaChatGenerator、NvidiaRanker与其一一对应可配合参考文档交叉阅读。环境准备与密钥配置安装集成包pip install nvidia-haystack组件默认通过环境变量读取配置支持的变量如下环境变量作用默认行为NVIDIA_API_KEYNVIDIA NIM / API Catalog 的 API 密钥各组件默认以Secret.from_env_var(NVIDIA_API_KEY)读取NVIDIA_API_URL自定义 API 地址各组件默认取该变量值未设置时使用内置的DEFAULT_API_URL托管 API 为https://integrate.api.nvidia.com/v1NVIDIA_TIMEOUT请求超时时间秒未设置时timeout参数默认为 60NVIDIA_MAX_RETRIES内部错误后的最大重试次数仅 Chat Generator未设置时默认重试 5 次密钥除了走环境变量还可以通过 Haystack 的Secret机制显式传入。Secret的完整实现见 haystack/utils/auth.py它支持从环境变量Secret.from_env_var(...)或明文令牌Secret.from_token(...)构造且不会在序列化时泄露明文值。例如from haystack.utils import Secret api_key Secret.from_env_var(NVIDIA_API_KEY) # 推荐从环境变量读取 api_key Secret.from_token(your-api-key) # 显式令牌NvidiaDocumentEmbedder为文档批量生成向量NvidiaDocumentEmbedder负责为一批Document计算语义向量并把结果写入每个文档的embedding字段。它通常出现在索引管道中、位于DocumentWriter之前保证入库的文档自带可检索向量。初始化参数__init__( model: str | None None, api_key: Secret | None Secret.from_env_var(NVIDIA_API_KEY), api_url: str os.getenv(NVIDIA_API_URL, DEFAULT_API_URL), prefix: str , suffix: str , batch_size: int 32, progress_bar: bool True, meta_fields_to_embed: list[str] | None None, embedding_separator: str \n, truncate: EmbeddingTruncateMode | str | None None, timeout: float | None None, ) - None参数类型说明modelstr \| None使用的嵌入模型。若同时未指定模型且api_url指向本地 NIM组件会调用/modelsAPI 自动探测并选用可用模型api_keySecret \| NoneNVIDIA NIM 的 API 密钥默认从NVIDIA_API_KEY环境变量读取api_urlstr自定义 API 地址格式为http://host:port托管服务默认https://integrate.api.nvidia.com/v1prefixstr拼接到每段文本开头的字符串suffixstr拼接到每段文本末尾的字符串batch_sizeint一次编码的 Document 数量默认 32不能超过 50progress_barbool是否显示进度条默认Truemeta_fields_to_embedlist[str] \| None需要随正文一起参与向量化的元数据字段名列表embedding_separatorstr拼接元数据字段与正文时使用的分隔符默认换行符\ntruncateEmbeddingTruncateMode \| str \| None超长输入的处理策略None时行为由模型决定timeoutfloat \| None请求超时未设置时读取NVIDIA_TIMEOUT再缺省为 60 秒运行契约run(documents: list[Document]) - dict[str, list[Document] | dict[str, Any]]入参documents必须是一个Document列表否则抛出TypeError。返回值字典包含两个键——documents处理完成、已带embedding的文档列表Document数据类定义见 haystack/dataclasses/document.pymeta用量统计等元信息。使用示例方式一使用 NVIDIA API Catalog托管模型from haystack import Document from haystack.utils.auth import Secret from haystack_integrations.components.embedders.nvidia import NvidiaDocumentEmbedder documents [ Document(contentA transformer is a deep learning architecture), Document(contentLarge language models use transformer architectures), ] embedder NvidiaDocumentEmbedder( modelnvidia/nv-embedqa-e5-v5, api_urlhttps://integrate.api.nvidia.com/v1, api_keySecret.from_token(your-api-key), ) result embedder.run(documentsdocuments) print(result[documents]) print(result[meta])方式二对接本地自托管 NIM将api_url指向本地服务并把api_key设为Nonefrom haystack import Document from haystack_integrations.components.embedders.nvidia import NvidiaDocumentEmbedder documents [ Document(contentA transformer is a deep learning architecture), Document(contentLarge language models use transformer architectures), ] embedder NvidiaDocumentEmbedder( modelnvidia/nv-embedqa-e5-v5, api_urlhttp://localhost:9999/v1, api_keyNone, # 本地 NIM 无需密钥 ) result embedder.run(documentsdocuments) print(result[documents]) print(result[meta])方法与属性class_name() - str返回序列化用的类名标识。default_model() - None在本地 NIM 模式下设置默认模型借助/modelsAPI 探测可用模型。available_models - list[Model]列出与NvidiaDocumentEmbedder兼容的可用模型。warm_up() - None初始化组件。与文档中示例注释一致组件会在首次运行时自动 warm up无需显式调用。close() - None关闭后端并释放资源。to_dict() - dict[str, Any]/from_dict(data) - NvidiaDocumentEmbedder将组件序列化为字典、或从字典反序列化用于管道持久化与 YAML/JSON 配置加载。NvidiaTextEmbedder为查询字符串生成向量NvidiaTextEmbedder将单个字符串编码为向量适用于查询侧query embedding。对于区分 query 与 document 输入的模型本组件会按query语义编码输入。初始化参数__init__( model: str | None None, api_key: Secret | None Secret.from_env_var(NVIDIA_API_KEY), api_url: str os.getenv(NVIDIA_API_URL, DEFAULT_API_URL), prefix: str , suffix: str , truncate: EmbeddingTruncateMode | str | None None, timeout: float | None None, ) - None参数含义与NvidiaDocumentEmbedder同名参数一致model、api_key、api_url、prefix、suffix、truncate、timeout区别在于它没有batch_size、progress_bar、meta_fields_to_embed、embedding_separator——因为它的输入就是单一字符串。运行契约run(text: str) - dict[str, list[float] | dict[str, Any]]入参text必须是字符串否则抛出TypeError空字符串抛出ValueError。返回值字典包含两个键——embedding文本对应的向量list[float]meta用量统计等元信息。使用示例from haystack.utils.auth import Secret from haystack_integrations.components.embedders.nvidia import NvidiaTextEmbedder embedder NvidiaTextEmbedder( modelnvidia/nv-embedqa-e5-v5, api_urlhttps://integrate.api.nvidia.com/v1, api_keySecret.from_token(your-api-key), ) result embedder.run(A transformer is a deep learning architecture) print(result[embedding]) print(result[meta])本地 NIM 场景同样只需将api_url指向http://localhost:9999/v1并把api_key设为None。其生命周期方法class_name、default_model、warm_up、close、to_dict、from_dict与available_models属性与文档嵌入器保持一致。截断模式EmbeddingTruncateModeEmbeddingTruncateMode是继承自Enum的枚举用于指定输入超出模型最大 token 长度时的处理策略取值行为START从输入开头开始截断END从输入末尾开始截断NONE不截断输入过长时直接返回错误from haystack_integrations.components.embedders.nvidia.truncate import EmbeddingTruncateMode mode EmbeddingTruncateMode.from_str(END) # 从字符串创建截断模式from_str(string: str) - EmbeddingTruncateMode接受START、END、NONE等字符串并返回对应枚举。这就是NvidiaDocumentEmbedder与NvidiaTextEmbedder的truncate参数可直接传字符串的原因。NvidiaChatGenerator基于 NVIDIA 模型的对话生成NvidiaChatGenerator基于OpenAIChatGenerator实现用于调用 NVIDIA 生成式模型完成对话补全。它采用 Haystack 的ChatMessage格式组织输入输出ChatMessage数据类实现见 haystack/dataclasses/chat_message.py确保对话上下文连贯。任何 NVIDIA Chat Completion API 支持的生成参数都可以通过__init__或run中的generation_kwargs直接透传。初始化参数__init__( *, api_key: Secret Secret.from_env_var(NVIDIA_API_KEY), model: str nvidia/nemotron-3.5-lightning-30b-a3b, streaming_callback: StreamingCallbackT | None None, api_base_url: str | None os.getenv(NVIDIA_API_URL, DEFAULT_API_URL), generation_kwargs: dict[str, Any] | None None, tools: ToolsType | None None, timeout: float | None None, max_retries: int | None None, http_client_kwargs: dict[str, Any] | None None, ) - None参数类型说明api_keySecretNVIDIA API 密钥默认读取NVIDIA_API_KEYmodelstr对话补全模型名。2.18 参考文档默认值为nvidia/nemotron-3.5-lightning-30b-a3b新版用户指南NvidiaChatGenerator中的默认模型为meta/llama-3.1-8b-instruct使用时请以对应版本的文档为准streaming_callbackStreamingCallbackT \| None流式回调函数每收到一个新 tokenStreamingChunk即被调用api_base_urlstr \| NoneNVIDIA API 基础地址默认取NVIDIA_API_URL缺省为托管地址generation_kwargsdict \| None直接透传给 NVIDIA 端点的生成参数详见下文toolsToolsType \| None供模型准备调用的工具可传Tool列表或Toolset实例timeoutfloat \| NoneNVIDIA API 调用超时max_retriesint \| None内部错误后的最大重试次数默认读NVIDIA_MAX_RETRIES缺省为 5http_client_kwargsdict \| None用于配置自定义httpx.Client/httpx.AsyncClient的关键字参数generation_kwargs 深度解析这些参数会原样发送到 NVIDIA API 端点常用的包括max_tokens输出文本的最大 token 数。temperature采样温度。越高越有创造性需要确定答案时设为0argmax 采样创意型应用可尝试0.9。top_p核采样nucleus sampling概率阈值。例如0.1表示只考虑概率质量最高的前 10% 的 token。stream是否流式返回部分进度若开启token 会以 server-sent events 形式陆续返回并以data: [DONE]结束。response_formatNIM 服务器支持有限。基础 JSON 模式{type: json_object}可用于兼容模型输出合法 JSON需要结构化 JSON 输出时使用json_schema例如generation_kwargs{ response_format: { type: json_schema, json_schema: { name: my_schema, schema: json_schema, # 你的 JSON Schema 定义 }, } }工具调用Function Callingtools参数支持三种灵活的组合方式详见 NvidiaChatGenerator 用户指南Tool 对象列表逐个传入独立工具单个 Toolset直接传入整个工具集混合组合在同一个列表中混用多个 Toolset 与独立 Tool。from haystack.tools import Tool, Toolset from haystack_integrations.components.generators.nvidia import NvidiaChatGenerator weather_tool Tool( nameweather, descriptionGet weather info, parameters..., function... ) news_tool Tool( namenews, descriptionGet latest news, parameters..., function... ) math_toolset Toolset([add_tool, subtract_tool, multiply_tool]) generator NvidiaChatGenerator( tools[math_toolset, weather_tool, news_tool] # Toolset 与 Tool 混合 )使用示例基础对话from haystack.dataclasses import ChatMessage from haystack.utils import Secret from haystack_integrations.components.generators.nvidia import NvidiaChatGenerator generator NvidiaChatGenerator( modelmeta/llama-3.1-8b-instruct, api_keySecret.from_env_var(NVIDIA_API_KEY), ) messages [ChatMessage.from_user(Whats Natural Language Processing? Be brief.)] result generator.run(messages) print(result[replies])多模态输入视觉模型from haystack.dataclasses import ChatMessage, ImageContent from haystack.utils import Secret from haystack_integrations.components.generators.nvidia import NvidiaChatGenerator llm NvidiaChatGenerator( modelmeta/llama-3.2-11b-vision-instruct, api_keySecret.from_env_var(NVIDIA_API_KEY), ) image ImageContent.from_file_path(apple.jpg) user_message ChatMessage.from_user( content_parts[ What does the image show? Max 5 words., image, ], ) response llm.run([user_message])[replies][0].text print(response) # Red apple on straw.接入管道配合 ChatPromptBuilderfrom haystack import Pipeline from haystack.components.builders import ChatPromptBuilder from haystack.dataclasses import ChatMessage from haystack.utils import Secret from haystack_integrations.components.generators.nvidia import NvidiaChatGenerator pipe Pipeline() pipe.add_component(prompt_builder, ChatPromptBuilder()) pipe.add_component( llm, NvidiaChatGenerator( modelmeta/llama-3.1-8b-instruct, api_keySecret.from_env_var(NVIDIA_API_KEY), ), ) pipe.connect(prompt_builder, llm) country Germany system_message ChatMessage.from_system( You are an assistant giving out valuable information to language learners., ) messages [ system_message, ChatMessage.from_user(Whats the official language of {{ country }}?), ] res pipe.run( data{ prompt_builder: { template_variables: {country: country}, template: messages, }, }, ) print(res)序列化to_dict() - dict[str, Any]将组件序列化为字典YAML/JSON 管道配置即依赖此能力供管道持久化与再加载使用。NvidiaRanker语义重排序组件NvidiaRanker基于查询对一组Document做语义相关性排序通常位于查询管道中检索器之后例如 BM25 粗排之后做精排。文档示例中的模型为nvidia/llama-nemotron-rerank-vl-1b-v2按用户指南NvidiaRanker说明若未设置model参数托管端默认使用nv-rerank-qa-mistral-4b:1。初始化参数__init__( model: str | None None, truncate: RankerTruncateMode | str | None None, api_url: str os.getenv(NVIDIA_API_URL, DEFAULT_API_URL), api_key: Secret | None Secret.from_env_var(NVIDIA_API_KEY), top_k: int 5, query_prefix: str , document_prefix: str , meta_fields_to_embed: list[str] | None None, embedding_separator: str \n, timeout: float | None None, ) - None参数类型说明modelstr \| None排序模型不设置时使用 NIM 默认模型truncateRankerTruncateMode \| str \| None截断策略可为NONE、END或RankerTruncateMode默认跟随 NIM 默认值api_keySecret \| NoneNVIDIA NIM API 密钥api_urlstr自定义 API 地址格式http://host:porttop_kint返回的文档数量默认 5初始化时若top_k 0抛出ValueErrorquery_prefixstr排序前拼接到查询文本开头的字符串可用于按bge等重排序模型的要求注入指令document_prefixstr排序前拼接到每个文档开头的字符串同样用于模型指令meta_fields_to_embedlist[str] \| None参与排序的文档元数据字段列表embedding_separatorstr拼接元数据字段与文档内容的分隔符默认\ntimeoutfloat \| None请求超时未设置时读取NVIDIA_TIMEOUT缺省 60 秒运行契约run( query: str, documents: list[Document], top_k: int | None None ) - dict[str, list[Document]]入参query查询字符串、documents待排序文档列表、top_k返回数量可覆盖初始化值。返回值字典中的documents键对应按相关性降序排列的文档列表。异常参数类型错误抛出TypeErrortop_k 0抛出ValueError。使用示例单独使用from haystack_integrations.components.rankers.nvidia import NvidiaRanker from haystack import Document from haystack.utils import Secret ranker NvidiaRanker( modelnvidia/llama-nemotron-rerank-vl-1b-v2, api_keySecret.from_env_var(NVIDIA_API_KEY), ) # 组件会在首次运行时自动 warm up query What is the capital of Germany? documents [ Document(contentBerlin is the capital of Germany.), Document(contentThe capital of Germany is Berlin.), Document(contentGermanys capital is Berlin.), ] result ranker.run(query, documents, top_k2) print(result[documents])管道中使用BM25 召回 NVIDIA 精排from haystack import Document, Pipeline from haystack.components.retrievers.in_memory import InMemoryBM25Retriever from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack_integrations.components.rankers.nvidia import NvidiaRanker docs [ Document(contentParis is in France), Document(contentBerlin is in Germany), Document(contentLyon is in France), ] document_store InMemoryDocumentStore() document_store.write_documents(docs) retriever InMemoryBM25Retriever(document_storedocument_store) ranker NvidiaRanker() document_ranker_pipeline Pipeline() document_ranker_pipeline.add_component(instanceretriever, nameretriever) document_ranker_pipeline.add_component(instanceranker, nameranker) document_ranker_pipeline.connect(retriever.documents, ranker.documents) query Cities in France res document_ranker_pipeline.run( data{ retriever: {query: query, top_k: 3}, ranker: {query: query, top_k: 2}, }, )关于top_k的实践提示上述示例中 Retriever 与 Ranker 的top_k含义不同——Retriever 的top_k决定召回多少文档Ranker 的top_k决定最终返回/向下游传递多少文档。当 Ranker 是管道末组件时管道输出即 Rankertop_k数量的结果。合理调小 Retriever 的top_k可减少 Ranker 处理量、加快整体管道速度。方法与生命周期class_name() - str序列化类名标识。to_dict() - dict[str, Any]/from_dict(data) - NvidiaRanker序列化与反序列化。warm_up() - None初始化排序器若使用 NVIDIA 托管 NIM 而缺少 API 密钥抛出ValueError。close() - None关闭后端并释放资源。重排序截断模式RankerTruncateModeRankerTruncateMode继承自str和Enum用于指定排序器输入超长时的处理策略取值行为NONE不截断输入过长时直接返回错误END从输入末尾开始截断from haystack_integrations.components.rankers.nvidia.truncate import RankerTruncateMode mode RankerTruncateMode.from_str(END) # 从字符串创建from_str(string: str) - RankerTruncateMode将字符串转换为对应枚举因此NvidiaRanker的truncate参数可以直接传NONE或END。组件生命周期与序列化机制四个 NVIDIA 组件遵循 Haystack 组件规范具备一致的运行模型自动 warm up组件在首次run时自动初始化后端无需手动预热也可显式调用warm_up()。资源释放调用close()关闭后端并释放连接等资源。可序列化to_dict()将组件转换为纯字典含class_name标识from_dict()从字典还原组件。这意味着包含 NVIDIA 组件的管道可以完整导出为 YAML/JSON 并在其他环境中重建实现配置化部署。深入阅读关联 API 参考版本 2.18docs-website/reference_versioned_docs/version-2.18/integrations-api/nvidia.md用户指南NvidiaDocumentEmbedder、NvidiaTextEmbedder、NvidiaChatGenerator、NvidiaRanker相关数据类与基础设施ChatMessage、Document、Secret管道核心haystack/core/pipeline【免费下载链接】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），仅供参考