Haystack × IBM watsonx.ai 集成实战Document/Text Embedder 与 Chat/Generator 四组件使用全指南【免费下载链接】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 仓库中 IBM watsonx.ai 集成watsonx-haystack的官方 API 参考文档系统讲解四个核心组件——WatsonxDocumentEmbedder、WatsonxTextEmbedder、WatsonxChatGenerator、WatsonxGenerator——的初始化参数、运行接口、序列化机制与实际 Pipeline 用法。读完本文你将能独立搭建一套以 watsonx.ai 为模型后端、涵盖索引嵌入与检索问答的完整 RAG 应用并掌握多模态对话、流式输出、工具调用等进阶能力。一、集成总览四个组件与它们的职责分工该集成参考文档位于 version-2.23 的 integrations-api/watsonx.md围绕 IBM watsonx.ai 平台封装了四个 Haystack 组件分别覆盖嵌入与生成两大能力面组件所属模块输入输出典型位置WatsonxDocumentEmbeddercomponents.embedders.watsonx.document_embedderlist[Document]带embedding的文档列表 meta索引 Pipeline 中DocumentWriter之前WatsonxTextEmbeddercomponents.embedders.watsonx.text_embedder单个strembedding向量 meta查询/RAG Pipeline 中嵌入 Retriever 之前WatsonxChatGeneratorcomponents.generators.watsonx.chat.chat_generatorlist[ChatMessage]或strreplieslist[ChatMessage]ChatPromptBuilder之后WatsonxGeneratorcomponents.generators.watsonx.generatorprompt: strrepliesmetaPromptBuilder之后已弃用其中WatsonxGenerator直接继承自WatsonxChatGeneratorBases: WatsonxChatGenerator只是把聊天消息接口包装成了纯文本 prompt接口。两个生成器共用同一套SUPPORTED_MODELS模型清单两个嵌入器共用同一默认模型ibm/slate-30m-english-rtrvr-v2。二、环境准备安装与 IBM Cloud 凭据所有组件都要求 IBM Cloud 凭据才能工作且使用同一个watsonx-haystack包pip install watsonx-haystack凭据有两条注入路径官方推荐使用环境变量WATSONX_API_KEYIBM Cloud API keyWATSONX_PROJECT_IDWatson Studio 项目 ID在初始化时也可以直接传入Secret对象Haystack 的 Secret 管理 API见 Secret 管理相关文档from haystack.utils import Secret embedder WatsonxDocumentEmbedder( api_keySecret.from_token(your-api-key), project_idSecret.from_token(your-project-id), )组件内部的默认行为从 API 参考的__init__签名可见是api_key: Secret Secret.from_env_var(WATSONX_API_KEY)、project_id: Secret Secret.from_env_var(WATSONX_PROJECT_ID)即不传参时自动读取环境变量。此外生成器组件还额外支持两个环境变量WATSONX_TIMEOUT覆盖默认请求超时默认 30 秒WATSONX_MAX_RETRIES覆盖默认重试次数默认 5 次所有组件默认的api_base_url为https://us-south.ml.cloud.ibm.com可按需通过api_base_url参数切换到其他地域端点。三、WatsonxDocumentEmbedder为文档批量生成向量WatsonxDocumentEmbedder用于为一批文档计算 embedding其向量是嵌入检索的前提——检索时用查询向量与文档向量做相似度比较找出最相关文档。3.1 完整参数说明__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各参数含义与取值建议model用于计算 embedding 的模型名默认ibm/slate-30m-english-rtrvr-v2。支持同类 slate 系列模型。api_key / api_base_url / project_id凭据与服务端点见上文环境准备。truncate_input_tokens输入文本最多使用的 token 数。为None默认时使用完整输入直到模型的最大 token 上限设置具体数值可强制截断超长文本。prefix / suffix分别在每段待嵌入文本的开头和末尾追加的字符串可用于注入任务指令或领域前缀改善检索效果。batch_size单次 API 调用中嵌入的文档数默认 1000控制吞吐与单请求负载。concurrency_limit并行请求数默认 5。批量文档会被拆成多个请求并发发送提升索引效率。timeout单次 API 请求超时秒。max_retries请求失败时的最大重试次数。meta_fields_to_embed需要一并嵌入的元数据字段名列表。文档的meta中这些字段的取值会被拼进待嵌入文本使检索能利用元数据语义。embedding_separator拼接元数据字段与正文内容时使用的分隔符默认换行符\n。3.2 基础用法示例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_fields_to_embed指定的字段会拼入文本参与嵌入但字段本身仍保留在meta中meta关于模型使用情况的信息。3.3 嵌入元数据让元数据参与语义检索文本常附带元数据标题、页码、标签等。如果这些元数据有区分度和语义价值把它们拼进嵌入文本可以显著提升检索相关性。设置meta_fields_to_embed即可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]此时嵌入的文本内容约等于relevant title\nsome text标题在前、正文在后用默认分隔符\n连接。四、WatsonxTextEmbedder为查询文本生成向量WatsonxTextEmbedder与文档嵌入器互补它嵌入单条字符串典型场景是用户查询供嵌入 Retriever 与文档向量做相似度匹配。查询管道中的标准用法是把它放在InMemoryEmbeddingRetriever之前并将输出embedding接到 Retriever 的query_embedding输入。4.1 完整参数说明__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四个批量/元数据参数——因为查询是单条文本。其余参数model、truncate_input_tokens、prefix、suffix、timeout、max_retries语义与文档嵌入器一致。4.2 用法示例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模型使用信息示例中可见model与实际truncated_input_tokens此处为 3说明输入的 3 个 token 全部被使用。五、组合实战一个完整的 RAG 索引 查询双 Pipeline把两个嵌入器串起来就能构建标准的语义检索应用。索引 Pipeline 负责文档 → 向量 → 写入文档库查询 Pipeline 负责查询 → 向量 → 检索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), ] # 索引 Pipeline嵌入并写入文档库 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}}) # 查询 Pipeline嵌入查询并检索最相似文档 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: ...)关键连接点索引侧embedder→writer传输文档 向量查询侧text_embedder.embedding→retriever.query_embedding把查询向量喂给检索器。文档库使用cosine相似度函数与嵌入检索天然匹配。六、WatsonxChatGenerator聊天补全与多模态对话WatsonxChatGenerator使用 watsonx.ai 基础模型完成聊天补全输入输出均为 Haystack 的ChatMessage格式见 chat_message.py并支持文本 图像的多模态输入图像载体见 image_content.py。6.1 支持的模型清单组件通过SUPPORTED_MODELS维护一份非穷举的模型白名单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, ]清单覆盖 IBM Granite 系列含代码、护栏模型、Meta Llama 系列含两个视觉模型与 Llama Guard 视觉护栏、Mistral 系列以及 OpenAI 开源模型 gpt-oss。名单为非穷举实际可用模型以 IBM 官方支持的模型文档为准组件内做白名单校验。6.2 完整参数说明__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_key / project_idIBM Cloud 凭据可用环境变量或直接传入。model模型 ID默认ibm/granite-4-h-small可用模型可在 IBM Cloud 账户中查看。api_base_urlAPI 端点默认https://us-south.ml.cloud.ibm.com。generation_kwargs直接透传给 watsonx.ai 推理端点的生成控制参数常见支持项temperature随机性控制越低越确定max_new_tokens/min_new_tokens生成 token 数的上下限top_p核采样概率阈值top_k考虑的最高概率 token 数repetition_penalty重复 token 惩罚length_penalty基于输出长度的惩罚stop_sequences命中即停止生成的序列列表random_seed随机种子用于可复现结果。timeout请求超时秒默认取环境变量WATSONX_TIMEOUT否则 30 秒。max_retries失败请求最大重试次数默认取WATSONX_MAX_RETRIES否则 5。verifySSL 校验设置取值可为True校验默认、False跳过校验不安全、或 CA 证书包路径自定义证书。streaming_callback流式回调函数每收到一个新 token 即被调用流式支持详见 choosing-the-right-generator.mdx。toolsTool和/或Toolset对象列表或单个Toolset供模型准备工具调用。6.3 基础对话示例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(messages..., generation_kwargsNone, streaming_callbackNone, toolsNone)返回字典键为replies生成回复的ChatMessage列表。run层参数有覆盖语义generation_kwargs会覆盖__init__中的同名配置streaming_callback、tools同理。messages也接受纯字符串会自动包装成一条 user 角色的ChatMessage。组件还提供run_async异步版本签名与覆盖语义与run完全一致适合在异步 Pipeline 中使用。6.4 多模态对话示例使用带视觉能力的模型如meta-llama/llama-3-2-11b-vision-instruct可同时输入文本与图片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)ImageContent.from_file_path(...)从本地文件加载图像与文本片段一起放进ChatMessage.from_user(content_parts[...])即可实现看图问答。6.5 在 Pipeline 中使用WatsonxChatGenerator通常跟在ChatPromptBuilder之后用模板变量渲染出系统消息与用户消息from 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)七、WatsonxGenerator文本补全已弃用迁移建议WatsonxGenerator继承自WatsonxChatGenerator提供面向纯文本 prompt 的标准 Generator 接口。需要说明的是仓库内组件文档watsonxgenerator.mdx已给出弃用警告——该组件将在未来版本移除官方建议改用WatsonxChatGenerator它本身也接受纯字符串输入。API 参考文档仍完整保留其接口以下参数说明适用于仍在使用旧组件的项目迁移参考。__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, system_prompt: str | None None, 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 ) - None与WatsonxChatGenerator相比差异点在于新增system_prompt初始化时可预设系统提示词run时若不传则使用该值无tools参数纯文本生成接口不涉及工具调用SUPPORTED_MODELS与父类完全一致。用法示例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)输出示例含 token 用量统计{ 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, }, } ], }run(prompt, system_promptNone, streaming_callbackNone, generation_kwargsNone)返回replies字符串列表与meta每次生成的元数据列表含模型名、finish reason、token 用量。同样提供run_async异步版本。八、序列化to_dict / from_dict 与 Pipeline 持久化四个组件均实现了标准序列化接口这是 Haystack Pipeline 能通过 YAML/JSON 持久化的基础序列化机制见 serialization.pyto_dict() - dict[str, Any]把组件序列化为字典包含组件类型与全部初始化参数。注意Secret类型参数在序列化时以占位符形式保存如环境变量名不会把真实密钥写入字典。from_dict(data: dict[str, Any]) - WatsonxDocumentEmbedder或对应组件类型从字典反序列化还原组件实例用于加载 Pipeline 定义。# 序列化 data embedder.to_dict() # {type: haystack_integrations.components.embedders.watsonx.document_embedder.WatsonxDocumentEmbedder, init_parameters: {...}} # 反序列化 restored WatsonxDocumentEmbedder.from_dict(data)借助这两个方法包含 watsonx 组件的 Pipeline 可以被序列化为配置文件在部署环境间迁移、复用且凭据始终保持在运行时从环境变量注入避免密钥泄露到配置文件。九、常见问题与调优要点凭据缺失四个组件都强制要求api_key与project_id请先确认WATSONX_API_KEY、WATSONX_PROJECT_ID已导出或初始化时显式传入Secret。地域端点api_base_url默认指向us-south如果你的 IBM Cloud 项目位于其他地域务必同步修改否则请求会 404 或鉴权失败。超长文本索引长文档时建议显式设置truncate_input_tokens避免超出模型上下文导致请求报错也可搭配DocumentSplitter先切分再嵌入。批量与并发WatsonxDocumentEmbedder的batch_size默认 1000与concurrency_limit默认 5决定索引吞吐。大批量索引时建议先小批量压测观察是否触发限流后再放大并发。可复现性在generation_kwargs中固定random_seed并降低temperature可获得更确定、可复现的生成结果。弃用迁移若仍在用WatsonxGenerator应尽快迁移到WatsonxChatGenerator——后者同样接受字符串输入且持续获得新能力工具调用、多模态等。十、深入阅读本文章的核心 API 参考version-2.23 integrations-api/watsonx.md组件实战文档含更多 Pipeline 示例WatsonxDocumentEmbedderWatsonxTextEmbedderWatsonxChatGeneratorWatsonxGenerator关联数据类ChatMessagechat_message.py、ImageContentimage_content.py配套检索组件InMemoryEmbeddingRetriever 与文档库 、DocumentWriter【免费下载链接】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），仅供参考