Haystack 接入 IBM watsonx.ai嵌入器与生成器组件完整实战指南【免费下载链接】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.20 版本参考文档docs-website/reference_versioned_docs/version-2.20/integrations-api/watsonx.md为主体系统讲解watsonx-haystack集成包中的四个核心组件——WatsonxDocumentEmbedder、WatsonxTextEmbedder、WatsonxChatGenerator与WatsonxGenerator。读完本文你将掌握如何在 Haystack 管线中调用 IBM watsonx.ai 的基础模型完成文档向量化、语义检索、对话生成与多模态问答并能正确配置凭据、生成参数、流式回调与异步执行。一、集成概览一个包、四个组件IBM watsonx.ai 是 IBM Cloud 上的企业级 AI 平台提供 Granite、Llama、Mistral 等基础模型的托管推理服务。Haystack 通过watsonx-haystack集成包将其能力封装为标准的 Haystack 组件安装方式如下pip install watsonx-haystack该集成包含四个组件分别覆盖嵌入与生成两条核心链路组件所属模块核心职责WatsonxDocumentEmbedderhaystack_integrations.components.embedders.watsonx.document_embedder批量计算文档内容的嵌入向量用于索引管线WatsonxTextEmbedderhaystack_integrations.components.embedders.watsonx.text_embedder将单个字符串如查询编码为向量用于查询管线WatsonxChatGeneratorhaystack_integrations.components.generators.watsonx.chat.chat_generator基于ChatMessage完成对话补全支持多模态与工具调用WatsonxGeneratorhaystack_integrations.components.generators.watsonx.generator基于普通 prompt 字符串的文本补全继承自WatsonxChatGenerator已标记弃用所有组件均通过统一的run()方法与 Haystack 管线Pipeline对接并实现了to_dict()/from_dict()序列化接口可无缝参与管线的 YAML/JSON 持久化。二、环境准备与凭据配置所有 watsonx 组件都必须提供两组 IBM Cloud 凭据api_keyIBM Cloud API 密钥可通过环境变量WATSONX_API_KEY设置project_idWatson Studio 项目 ID可通过环境变量WATSONX_PROJECT_ID设置。官方文档推荐优先使用环境变量方式参考 docs-website/docs/pipeline-components/embedders/watsonxtextembedder.mdx也可以在组件初始化时通过 Haystack 的Secret机制显式传入。Secret类位于本仓库 haystack/utils/auth.py支持从环境变量、Token 或字符串构建凭据并保证密钥不会被意外序列化进明文配置from haystack.utils import Secret # 方式一从环境变量读取推荐 api_key Secret.from_env_var(WATSONX_API_KEY) project_id Secret.from_env_var(WATSONX_PROJECT_ID) # 方式二直接传入 Token api_key Secret.from_token(your-api-key) project_id Secret.from_token(your-project-id)此外WatsonxChatGenerator与WatsonxGenerator还支持两个可选环境变量用于覆盖网络行为WATSONX_TIMEOUT覆盖默认请求超时时间WATSONX_MAX_RETRIES覆盖默认失败重试次数。所有组件的默认 API 服务地址为https://us-south.ml.cloud.ibm.com美国南部区域可通过api_base_url参数切换为其他区域或自定义网关。三、WatsonxDocumentEmbedder文档批量向量化WatsonxDocumentEmbedder使用 IBM watsonx.ai 嵌入模型为一批文档计算向量输出结果可直接交给DocumentWriter写入文档存储是索引管线的核心前置组件。其典型应用位置在DocumentWriter之前。3.1 基本用法from haystack import Document from haystack_integrations.components.embedders.watsonx.document_embedder import WatsonxDocumentEmbedder documents [ Document(contentI love pizza!), Document(contentPasta is great too), ] document_embedder WatsonxDocumentEmbedder( modelibm/slate-30m-english-rtrvr-v2, api_keySecret.from_env_var(WATSONX_API_KEY), api_base_urlhttps://us-south.ml.cloud.ibm.com, project_idSecret.from_env_var(WATSONX_PROJECT_ID), ) result document_embedder.run(documentsdocuments) print(result[documents][0].embedding) # [0.017020374536514282, -0.023255806416273117, ...]run()的入参为documents: list[Document]返回字典包含两个键documents已填充embedding字段的文档列表meta模型使用信息如模型名、截断 token 数。默认嵌入模型为ibm/slate-30m-english-rtrvr-v2可参考 IBM 官方嵌入模型列表选择其他模型。3.2 构造参数详解__init__( *, model: str ibm/slate-30m-english-rtrvr-v2, api_key: Secret Secret.from_env_var(WATSONX_API_KEY), api_base_url: str https://us-south.ml.cloud.ibm.com, project_id: Secret Secret.from_env_var(WATSONX_PROJECT_ID), truncate_input_tokens: int | None None, prefix: str , suffix: str , batch_size: int 1000, concurrency_limit: int 5, timeout: float | None None, max_retries: int | None None, meta_fields_to_embed: list[str] | None None, embedding_separator: str \n ) - None参数类型默认值说明modelstribm/slate-30m-english-rtrvr-v2用于计算嵌入的模型名api_keySecret环境变量WATSONX_API_KEYIBM Cloud API 密钥api_base_urlstrhttps://us-south.ml.cloud.ibm.comwatsonx.ai 服务地址project_idSecret环境变量WATSONX_PROJECT_IDWatson Studio 项目 IDtruncate_input_tokensint \| NoneNone输入文本最多使用的 token 数为None时使用完整文本不超过模型上限prefixstr拼接在每个待嵌入文本开头的字符串suffixstr拼接在每个待嵌入文本末尾的字符串batch_sizeint1000单次 API 调用嵌入的文档数量concurrency_limitint5并行请求数上限timeoutfloat \| NoneNoneAPI 请求超时秒max_retriesint \| NoneNoneAPI 请求最大重试次数meta_fields_to_embedlist[str] \| NoneNone需要随正文一起嵌入的元数据字段名列表embedding_separatorstr\n正文与元数据拼接时使用的分隔符3.3 嵌入元数据以提升检索质量当文档带有语义上有区分度的元数据如标题、页码时将其与正文一起嵌入能显著改善检索效果。此时需配合embedding_separator控制拼接格式from haystack import Document from haystack_integrations.components.embedders.watsonx.document_embedder import ( WatsonxDocumentEmbedder, ) from haystack.utils import Secret doc Document(contentsome text, meta{title: relevant title, page number: 18}) embedder WatsonxDocumentEmbedder( api_keySecret.from_env_var(WATSONX_API_KEY), project_idSecret.from_env_var(WATSONX_PROJECT_ID), meta_fields_to_embed[title], ) docs_w_embeddings embedder.run(documents[doc])[documents]上例中title字段会被拼入待嵌入文本而page number字段不会这种细粒度控制有利于只注入对检索有增益的元数据。四、WatsonxTextEmbedder查询向量化WatsonxTextEmbedder用于将单个字符串通常是用户查询编码为向量供嵌入检索器Embedding Retriever与文档向量做相似度比对。它与WatsonxDocumentEmbedder的职责划分是后者处理文档列表前者处理单条文本。4.1 基本用法from haystack_integrations.components.embedders.watsonx.text_embedder import WatsonxTextEmbedder text_to_embed I love pizza! text_embedder WatsonxTextEmbedder( modelibm/slate-30m-english-rtrvr-v2, api_keySecret.from_env_var(WATSONX_API_KEY), api_base_urlhttps://us-south.ml.cloud.ibm.com, project_idSecret.from_env_var(WATSONX_PROJECT_ID), ) print(text_embedder.run(text_to_embed)) # {embedding: [0.017020374536514282, -0.023255806416273117, ...], # meta: {model: ibm/slate-30m-english-rtrvr-v2, # truncated_input_tokens: 3}}run(text: str)返回字典包含两个键embedding输入文本的向量list[float]与meta模型使用信息。上例中meta.truncated_input_tokens表示实际用于嵌入的 token 数可用于观测模型截断行为。4.2 构造参数详解__init__( *, model: str ibm/slate-30m-english-rtrvr-v2, api_key: Secret Secret.from_env_var(WATSONX_API_KEY), api_base_url: str https://us-south.ml.cloud.ibm.com, project_id: Secret Secret.from_env_var(WATSONX_PROJECT_ID), truncate_input_tokens: int | None None, prefix: str , suffix: str , timeout: float | None None, max_retries: int | None None ) - None文本嵌入器参数与文档嵌入器基本一致差异在于没有batch_size、concurrency_limit、meta_fields_to_embed与embedding_separator因为它每次只处理一条文本参数类型默认值说明modelstribm/slate-30m-english-rtrvr-v2用于计算嵌入的模型名api_keySecret环境变量WATSONX_API_KEYIBM Cloud API 密钥api_base_urlstrhttps://us-south.ml.cloud.ibm.comwatsonx.ai 服务地址project_idSecret环境变量WATSONX_PROJECT_IDWatson Studio 项目 IDtruncate_input_tokensint \| NoneNone输入文本最多使用的 token 数为None时使用完整文本prefixstr添加在待嵌入文本开头的字符串suffixstr添加在待嵌入文本末尾的字符串timeoutfloat \| NoneNoneAPI 请求超时秒max_retriesint \| NoneNoneAPI 请求最大重试次数五、实战用 watsonx 搭建语义检索RAG管线将上述两个嵌入器组合即可搭建一套完整的索引 查询双管线 RAG 架构。完整的管线示例见 docs-website/docs/pipeline-components/embedders/watsonxdocumentembedder.mdx 与 docs-website/docs/pipeline-components/embedders/watsonxtextembedder.mdx。5.1 索引管线文档 → 向量 → 存储from haystack import Document, Pipeline from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.components.writers import DocumentWriter from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever from haystack_integrations.components.embedders.watsonx.document_embedder import ( WatsonxDocumentEmbedder, ) from haystack_integrations.components.embedders.watsonx.text_embedder import ( WatsonxTextEmbedder, ) document_store InMemoryDocumentStore(embedding_similarity_functioncosine) documents [ Document(contentMy name is Wolfgang and I live in Berlin), Document(contentI saw a black horse running), Document(contentGermany has many big cities), ] indexing_pipeline Pipeline() indexing_pipeline.add_component(embedder, WatsonxDocumentEmbedder()) indexing_pipeline.add_component(writer, DocumentWriter(document_storedocument_store)) indexing_pipeline.connect(embedder, writer) indexing_pipeline.run({embedder: {documents: documents}})5.2 查询管线文本 → 向量 → 检索query_pipeline Pipeline() query_pipeline.add_component(text_embedder, WatsonxTextEmbedder()) query_pipeline.add_component( retriever, InMemoryEmbeddingRetriever(document_storedocument_store), ) query_pipeline.connect(text_embedder.embedding, retriever.query_embedding) query Who lives in Berlin? result query_pipeline.run({text_embedder: {text: query}}) print(result[retriever][documents][0]) # Document(id..., content: My name is Wolfgang and I live in Berlin, score: ...)关键连接点是text_embedder.embedding输出与retriever.query_embedding输入的接线查询文本先被WatsonxTextEmbedder编码再由InMemoryEmbeddingRetriever基于余弦相似度embedding_similarity_functioncosine在文档向量空间中召回最相关的文档。若文档量超出内存容量可将InMemoryDocumentStore替换为 Haystack 支持的其他文档存储实现见 haystack/document_stores。六、WatsonxChatGenerator对话生成与多模态WatsonxChatGenerator是集成中最强大的生成组件它使用 IBM watsonx.ai 基础模型完成对话补全输入输出均基于 Haystack 的ChatMessage数据类定义见 haystack/dataclasses/chat_message.py并支持文本 图片的多模态输入。6.1 基本用法from haystack_integrations.components.generators.watsonx.chat.chat_generator import WatsonxChatGenerator from haystack.dataclasses import ChatMessage from haystack.utils import Secret messages [ChatMessage.from_user(Explain quantum computing in simple terms)] client WatsonxChatGenerator( api_keySecret.from_env_var(WATSONX_API_KEY), modelibm/granite-4-h-small, project_idSecret.from_env_var(WATSONX_PROJECT_ID), ) response client.run(messages) print(response)run()返回字典中的replies键包含一组ChatMessage实例即为模型生成的回复。messages参数也支持直接传入字符串组件会自动将其包装为一条user角色的ChatMessage。6.2 多模态输入借助 Haystack 的ImageContent数据类定义见 haystack/dataclasses/image_content.py可以为视觉模型同时传入文本与图片from haystack.dataclasses import ChatMessage, ImageContent # 从文件路径或 base64 创建图片内容 image_content ImageContent.from_file_path(path/to/your/image.jpg) # 构造同时包含文本与图片的多模态消息 messages [ChatMessage.from_user(content_parts[Whats in this image?, image_content])] # 使用多模态模型 client WatsonxChatGenerator( api_keySecret.from_env_var(WATSONX_API_KEY), modelmeta-llama/llama-3-2-11b-vision-instruct, project_idSecret.from_env_var(WATSONX_PROJECT_ID), ) response client.run(messages) print(response)ChatMessage.from_user(content_parts[...])允许以列表形式混合文本与ImageContent对象ImageContent.from_file_path()负责从本地文件加载图片从而实现看图问答等视觉场景。6.3 支持的模型列表组件内置SUPPORTED_MODELS常量非穷尽列表完整的模型 ID 需查阅 IBM 官方支持文档SUPPORTED_MODELS: list[str] [ ibm/granite-3-1-8b-base, ibm/granite-3-8b-instruct, ibm/granite-4-h-small, ibm/granite-8b-code-instruct, ibm/granite-guardian-3-8b, meta-llama/llama-3-1-70b-gptq, meta-llama/llama-3-1-8b, meta-llama/llama-3-2-11b-vision-instruct, meta-llama/llama-3-2-90b-vision-instruct, meta-llama/llama-3-3-70b-instruct, meta-llama/llama-3-405b-instruct, meta-llama/llama-4-maverick-17b-128e-instruct-fp8, meta-llama/llama-guard-3-11b-vision, mistral-large-2512, mistralai/mistral-medium-2505, mistralai/mistral-small-3-1-24b-instruct-2503, openai/gpt-oss-120b, ]其中meta-llama/llama-3-2-11b-vision-instruct、meta-llama/llama-3-2-90b-vision-instruct与meta-llama/llama-guard-3-11b-vision为视觉多模态模型其余为纯文本模型。ibm/granite-guardian-3-8b可用于安全护栏类任务。6.4 构造参数详解__init__( *, api_key: Secret Secret.from_env_var(WATSONX_API_KEY), model: str ibm/granite-4-h-small, project_id: Secret Secret.from_env_var(WATSONX_PROJECT_ID), api_base_url: str https://us-south.ml.cloud.ibm.com, generation_kwargs: dict[str, Any] | None None, timeout: float | None None, max_retries: int | None None, verify: bool | str | None None, streaming_callback: StreamingCallbackT | None None, tools: ToolsType | None None ) - None参数类型默认值说明api_keySecret环境变量WATSONX_API_KEYIBM Cloud API 密钥modelstribm/granite-4-h-small用于补全的模型 IDproject_idSecret环境变量WATSONX_PROJECT_IDIBM Cloud 项目 IDapi_base_urlstrhttps://us-south.ml.cloud.ibm.comAPI 端点自定义地址generation_kwargsdict[str, Any] \| NoneNone透传给 watsonx.ai 推理端点的生成参数timeoutfloat \| NoneWATSONX_TIMEOUT或 30 秒请求超时秒max_retriesint \| NoneWATSONX_MAX_RETRIES或 5失败请求最大重试次数verifybool \| str \| NoneTrueSSL 校验True校验、False跳过不安全、字符串为自定义 CA 证书路径streaming_callbackStreamingCallbackT \| NoneNone流式输出回调函数toolsToolsType \| NoneNone模型可调用工具列表Tool/Toolset6.5 generation_kwargs控制生成行为generation_kwargs中的参数会直接透传给 watsonx.ai 推理端点支持的主要参数包括参数作用temperature控制随机性值越低越确定max_new_tokens生成的最大新 token 数min_new_tokens生成的最小新 token 数top_p核采样nucleus sampling概率阈值top_k候选的最高概率 token 数量repetition_penalty重复 token 惩罚length_penalty基于输出长度的惩罚stop_sequences停止生成的序列列表random_seed随机种子用于复现结果该参数既可在__init__中设置也可在run()中按次传入并覆盖初始化时的值适合对不同请求使用不同采样策略。6.6 run 与 run_asyncrun()提供同步对话补全run( *, messages: list[ChatMessage] | str, generation_kwargs: dict[str, Any] | None None, streaming_callback: StreamingCallbackT | None None, tools: ToolsType | None None ) - dict[str, list[ChatMessage]]run_async()提供对应的异步版本签名与run()完全一致可在asyncio环境下调用以提升吞吐。两者的generation_kwargs、streaming_callback、tools参数都会覆盖初始化时设置的同名参数。返回字典统一包含replies键list[ChatMessage]。6.7 流式输出组件支持将 LLM 生成的 token 实时流式返回。只需向streaming_callback传入一个回调函数即可逐 token 接收内容适用于打字机效果或边生成边处理的应用场景def my_streaming_callback(chunk) - None: print(chunk.content, end, flushTrue) client WatsonxChatGenerator( api_keySecret.from_env_var(WATSONX_API_KEY), modelibm/granite-4-h-small, project_idSecret.from_env_var(WATSONX_PROJECT_ID), streaming_callbackmy_streaming_callback, )6.8 在管线中组合使用WatsonxChatGenerator通常位于ChatPromptBuilder之后完整示例见 docs-website/docs/pipeline-components/generators/watsonxchatgenerator.mdxfrom haystack import Pipeline from haystack.components.builders import ChatPromptBuilder from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.watsonx.chat.chat_generator import ( WatsonxChatGenerator, ) from haystack.utils import Secret pipe Pipeline() pipe.add_component(prompt_builder, ChatPromptBuilder()) pipe.add_component( llm, WatsonxChatGenerator( api_keySecret.from_env_var(WATSONX_API_KEY), project_idSecret.from_env_var(WATSONX_PROJECT_ID), modelibm/granite-4-h-small, ), ) 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)ChatPromptBuilder支持在ChatMessage模板中使用 Jinja 变量如{{ country }}通过template_variables注入运行时数据再由管线将构建好的消息列表传递给WatsonxChatGenerator。七、WatsonxGenerator文本补全已弃用WatsonxGenerator继承自WatsonxChatGenerator提供面向普通 prompt 字符串的标准生成器接口。需要注意的是该组件已标记弃用官方建议改用同样支持字符串输入的WatsonxChatGenerator见 docs-website/docs/pipeline-components/generators/watsonxgenerator.mdx。from haystack_integrations.components.generators.watsonx.generator import WatsonxGenerator from haystack.utils import Secret generator WatsonxGenerator( api_keySecret.from_env_var(WATSONX_API_KEY), modelibm/granite-4-h-small, project_idSecret.from_env_var(WATSONX_PROJECT_ID), ) response generator.run( promptExplain quantum computing in simple terms, system_promptYou are a helpful physics teacher., ) print(response)输出结构示例{ replies: [Quantum computing uses quantum-mechanical phenomena like....], meta: [ { model: ibm/granite-4-h-small, project_id: your-project-id, usage: { prompt_tokens: 12, completion_tokens: 45, total_tokens: 57, }, } ], }replies为字符串列表meta为每次生成的元数据字典列表包含模型名、项目 ID 与 token 用量统计prompt_tokens、completion_tokens、total_tokens可直接用于成本核算与用量监控。与WatsonxChatGenerator相比其构造参数增加了一个system_prompt: str | None None可在初始化或run()时指定系统提示但不包含tools参数SUPPORTED_MODELS与生成参数透传机制则完全一致。八、序列化与管线持久化所有四个组件都实现了标准的 Haystack 序列化协议to_dict() - dict[str, Any]将组件序列化为字典便于保存为 YAML/JSON 管线描述from_dict(data: dict[str, Any])从字典反序列化恢复组件实例。这保证了包含 watsonx 组件的管线可以像其他 Haystack 管线一样被持久化、版本化管理与远程分发Secret的封装机制则确保密钥不会明文落入序列化产物。九、小结通过watsonx-haystack集成包Haystack 开发者可以无缝复用 IBM watsonx.ai 的企业级基础模型嵌入链路WatsonxDocumentEmbedder文档批量向量化支持元数据嵌入、批处理与并发控制WatsonxTextEmbedder查询向量化配合InMemoryEmbeddingRetriever即可搭建语义检索/RAG 双管线生成链路WatsonxChatGenerator对话补全支持多模态、流式、工具调用与异步是主力组件WatsonxGenerator文本补全已弃用建议迁移运维要点凭据优先使用WATSONX_API_KEY/WATSONX_PROJECT_ID环境变量生成行为通过generation_kwargs透传控制超时与重试可通过WATSONX_TIMEOUT/WATSONX_MAX_RETRIES环境变量或构造参数调优。从源码结构看本仓库haystack承载了组件所依赖的核心数据类ChatMessage、ImageContent、Secret与管线基础设施而 watsonx 组件本身的实现随watsonx-haystack包分发。参考本文的示例即可在自己的 Haystack 2.20 应用中完成 watsonx 的接入与调优。【免费下载链接】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），仅供参考