企业官网建设流程全解析

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

该集成包含四个组件，分别覆盖"嵌入"与"生成"两条核心链路：

所有组件均通过统一的run()方法与 Haystack 管线（Pipeline）对接，并实现了to_dict()/from_dict()序列化接口，可无缝参与管线的 YAML/JSON 持久化。

二、环境准备与凭据配置

所有 watsonx 组件都必须提供两组 IBM Cloud 凭据：

• api_key：IBM Cloud API 密钥，可通过环境变量WATSONX_API_KEY设置；
• project_id：Watson 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(content="I love pizza!"), Document(content="Pasta is great too"), ] document_embedder = WatsonxDocumentEmbedder( model="ibm/slate-30m-english-rtrvr-v2", api_key=Secret.from_env_var("WATSONX_API_KEY"), api_base_url="https://us-south.ml.cloud.ibm.com", project_id=Secret.from_env_var("WATSONX_PROJECT_ID"), ) result = document_embedder.run(documents=documents) 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

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(content="some text", meta={"title": "relevant title", "page number": 18}) embedder = WatsonxDocumentEmbedder( api_key=Secret.from_env_var("WATSONX_API_KEY"), project_id=Secret.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( model="ibm/slate-30m-english-rtrvr-v2", api_key=Secret.from_env_var("WATSONX_API_KEY"), api_base_url="https://us-south.ml.cloud.ibm.com", project_id=Secret.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（因为它每次只处理一条文本）：

五、实战：用 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_function="cosine") documents = [ Document(content="My name is Wolfgang and I live in Berlin"), Document(content="I saw a black horse running"), Document(content="Germany has many big cities"), ] indexing_pipeline = Pipeline() indexing_pipeline.add_component("embedder", WatsonxDocumentEmbedder()) indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_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_store=document_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_function="cosine"）在文档向量空间中召回最相关的文档。若文档量超出内存容量，可将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_key=Secret.from_env_var("WATSONX_API_KEY"), model="ibm/granite-4-h-small", project_id=Secret.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=["What's in this image?", image_content])] # 使用多模态模型 client = WatsonxChatGenerator( api_key=Secret.from_env_var("WATSONX_API_KEY"), model="meta-llama/llama-3-2-11b-vision-instruct", project_id=Secret.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

6.5 generation_kwargs：控制生成行为

generation_kwargs中的参数会直接透传给 watsonx.ai 推理端点，支持的主要参数包括：

该参数既可在__init__中设置，也可在run()中按次传入并覆盖初始化时的值，适合对不同请求使用不同采样策略。

6.6 run 与 run_async

run()提供同步对话补全：

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="", flush=True) client = WatsonxChatGenerator( api_key=Secret.from_env_var("WATSONX_API_KEY"), model="ibm/granite-4-h-small", project_id=Secret.from_env_var("WATSONX_PROJECT_ID"), streaming_callback=my_streaming_callback, )

6.8 在管线中组合使用

WatsonxChatGenerator通常位于ChatPromptBuilder之后（完整示例见 docs-website/docs/pipeline-components/generators/watsonxchatgenerator.mdx）：

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_key=Secret.from_env_var("WATSONX_API_KEY"), project_id=Secret.from_env_var("WATSONX_PROJECT_ID"), model="ibm/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("What's 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_key=Secret.from_env_var("WATSONX_API_KEY"), model="ibm/granite-4-h-small", project_id=Secret.from_env_var("WATSONX_PROJECT_ID"), ) response = generator.run( prompt="Explain quantum computing in simple terms", system_prompt="You 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