Haystack 集成 Amazon SageMaker：使用 SagemakerGenerator 调用 SageMaker Inference Endpoint 完成 LLM 文本生成-开发者社区

Haystack 集成 Amazon SageMaker：使用 SagemakerGenerator 调用 SageMaker Inference Endpoint 完成 LLM 文本生成

【免费下载链接】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

Amazon SageMaker 是 AWS 托管的机器学习平台，可将大语言模型（LLM）部署为托管式 Inference Endpoint。Haystack 通过独立的集成包amazon-sagemaker-haystack提供SagemakerGenerator组件，让开发者可以在 Haystack Pipeline 中直接调用部署在 SageMaker 上的模型完成文本生成。本文以 docs-website/reference_versioned_docs/version-2.18/integrations-api/amazon_sagemaker.md 与当前仓库中 SagemakerGenerator 使用文档为主体，系统讲解该组件的初始化参数、run()调用方式、串行化机制以及在实际 RAG Pipeline 中的集成方法，帮助你快速在 Haystack 应用中接入 AWS SageMaker 托管的 LLM。

SagemakerGenerator 是什么

SagemakerGenerator是 Haystack 生态中负责文本生成的 Generator 组件，其核心能力是调用部署在 SageMaker Inference Endpoint 上的大语言模型完成文本生成。

从文档定位看，它在 Pipeline 中最常见的位置是PromptBuilder之后——即由 PromptBuilder 依据模板组装好 prompt，再交给SagemakerGenerator调用 SageMaker 端点获得模型回复。

组件的基本信息如下：

项目	说明
组件名称	`SagemakerGenerator`
导入路径	`haystack_integrations.components.generators.amazon_sagemaker`
所属集成包	`amazon-sagemaker-haystack`
Pipeline 中常见位置	`PromptBuilder`之后
必备初始化参数	`model`（SageMaker Model Endpoint 名称）；AWS 凭据（可通过环境变量提供）
必备 run 参数	`prompt`（传给 LLM 的字符串提示词）
输出变量	`replies`（LLM 生成的回复字符串列表）；`meta`（每个回复关联的元数据字典列表，如 token 数、finish reason 等）
API 参考	docs-website/reference/integrations-api/amazon_sagemaker.md

在生成器总览文档中，SagemakerGenerator被归类为"Enables text generation using LLMs deployed on Amazon Sagemaker"，即专门面向 AWS 托管推理场景的生成器。如果你的模型托管在 SageMaker 而非 OpenAI、Hugging Face 等平台，它是把生成能力接入 Haystack Pipeline 的标准途径。

说明：SagemakerGenerator属于haystack-core-integrations生态，其源码不在此仓库内（当前仓库只包含 API 参考文档与使用指南），以下参数与行为说明均以 API 参考文档和使用指南为准。

前置条件：部署模型并配置 AWS 凭据

使用SagemakerGenerator前需要完成两件事：在 SageMaker 上部署一个模型端点，以及配置好 AWS 凭据。

部署模型到 SageMaker

SagemakerGenerator支持托管在 SageMaker Inference Endpoint 上的大语言模型。官方文档建议参考 SageMaker JumpStart foundation models documentation 完成模型部署。SageMaker JumpStart 提供大量预训练基础模型的即用部署方式，例如本文示例中使用的 Falcon 7B（jumpstart-dft-hf-llm-falcon-7b-bf16或jumpstart-dft-hf-llm-falcon-7b-instruct-bf16）与 Llama-2 系列。

配置 AWS 凭据

组件需要 AWS 凭据才能与 SageMaker 服务建立会话。你可以通过两种标准方式提供：

环境变量：SagemakerGenerator初始化时默认从以下环境变量读取凭据（strict=False表示环境变量缺失时不会抛错，会继续尝试其他凭据来源）：
- AWS_ACCESS_KEY_ID→aws_access_key_id
- AWS_SECRET_ACCESS_KEY→aws_secret_access_key
- AWS_SESSION_TOKEN→aws_session_token
- AWS_DEFAULT_REGION→aws_region_name
- AWS_PROFILE→aws_profile_name
共享凭据文件（shared credentials file）：AWS CLI 常规的~/.aws/credentials与~/.aws/config配置。

提示：当前仓库中的 RAG 示例（sagemakergenerator.mdx）注释强调"Make sure your AWS credentials are set up correctly. You can use environment variables or a shared credentials file"（确保 AWS 凭据配置正确，可以使用环境变量或共享凭据文件），与 API 参考文档的说明一致。

初始化参数详解

SagemakerGenerator的构造函数签名如下（来自 API 参考文档）：

__init__( model: str, aws_access_key_id: Secret | None = Secret.from_env_var( ["AWS_ACCESS_KEY_ID"], strict=False ), aws_secret_access_key: Secret | None = Secret.from_env_var( ["AWS_SECRET_ACCESS_KEY"], strict=False ), aws_session_token: Secret | None = Secret.from_env_var( ["AWS_SESSION_TOKEN"], strict=False ), aws_region_name: Secret | None = Secret.from_env_var( ["AWS_DEFAULT_REGION"], strict=False ), aws_profile_name: Secret | None = Secret.from_env_var( ["AWS_PROFILE"], strict=False ), aws_custom_attributes: dict[str, Any] | None = None, generation_kwargs: dict[str, Any] | None = None, ) -> None

各参数含义与要点：

参数	类型	默认值	说明
`model`	`str`	必填	SageMaker Model Endpoint 名称。注意传入的是端点名而非模型名，例如`jumpstart-dft-hf-llm-falcon-7b-bf16`。
`aws_access_key_id`	`Secret \\| None`	环境变量`AWS_ACCESS_KEY_ID`	AWS 访问密钥 ID。
`aws_secret_access_key`	`Secret \\| None`	环境变量`AWS_SECRET_ACCESS_KEY`	AWS 秘密访问密钥。
`aws_session_token`	`Secret \\| None`	环境变量`AWS_SESSION_TOKEN`	AWS 会话令牌（使用临时凭据时需要）。
`aws_region_name`	`Secret \\| None`	环境变量`AWS_DEFAULT_REGION`	AWS 区域名；未提供时使用默认区域。
`aws_profile_name`	`Secret \\| None`	环境变量`AWS_PROFILE`	AWS 配置文件名；未提供时使用默认 profile。
`aws_custom_attributes`	`dict[str, Any] \\| None`	`None`	传递给 SageMaker 的自定义属性字典。例如 Llama-2 系列模型需要传`{"accept_eula": True}`。
`generation_kwargs`	`dict[str, Any] \\| None`	`None`	文本生成所需的额外关键字参数，具体支持的参数以你的模型文档为准。

关于 Secret 类型的凭据封装

注意所有 AWS 凭据参数的类型都是Secret | None，且默认通过Secret.from_env_var([...], strict=False)从环境变量解析。这是 Haystack 组件规范化的凭据处理方式：Secret封装敏感信息，避免在代码或序列化文件中明文暴露；strict=False表示对应环境变量未设置时不会立即报错，而是回退到 boto3 默认的凭据链（如共享凭据文件、IAM 角色等）。因此你可以在初始化时不显式传入任何凭据参数，只要运行环境（环境变量或~/.aws/credentials）配置正确即可。

model 参数：传入的是 Endpoint 名称

文档特别强调model参数是"The name for SageMaker Model Endpoint"（SageMaker 模型端点的名称）。也就是说，你传入的必须是部署完成后生成的端点名（endpoint name），例如jumpstart-dft-hf-llm-falcon-7b-instruct-bf16。这与直接调用模型 ID 的本地推理组件有本质区别：SagemakerGenerator不加载模型权重，而是通过 HTTP 调用托管端点进行远程推理。

aws_custom_attributes：处理需要特殊请求属性的模型

某些 SageMaker 模型在推理时需要携带自定义请求属性。一个典型例子是Llama-2 模型族，其推理必须显式接受 EULA（终端用户许可协议），因此需要在初始化时传入：

generator = SagemakerGenerator( model="jumpstart-dft-meta-textgenerationneuron-llama-2-7b", aws_custom_attributes={"accept_eula": True}, )

generation_kwargs：模型相关的生成参数

generation_kwargs用于传递模型特定的文本生成参数。由于不同模型的推理负载（inference payload）格式不同，具体支持哪些参数需要查阅你所部署模型的技术文档。以 Hugging Face 模型为例，可参考 Hugging Face 官方博客中关于 SageMaker 托管 LLM 推理负载参数的说明。

文档特别以Llama-2 模型为例列出了其支持的推理负载参数：

参数	类型约束	说明
`max_new_tokens`	正整数	模型生成文本直到输出长度（不含输入上下文长度）达到该值。
`temperature`	正浮点数	控制输出随机性。温度越高，输出越倾向低概率词；`temperature=0`时退化为贪心解码（greedy decoding）。
`top_p`	0 到 1 之间的浮点数	每一步生成时，从累积概率达到`top_p`的最小词集合中采样（核采样）。
`return_full_text`	布尔值	为`True`时输入文本会包含在输出文本中。默认值为`False`。

例如，初始化时传入生成参数：

generator = SagemakerGenerator( model="jumpstart-dft-meta-textgenerationneuron-llama-2-7b", aws_custom_attributes={"accept_eula": True}, generation_kwargs={ "max_new_tokens": 200, "temperature": 0.7, "top_p": 0.9, "return_full_text": False, }, )

run()：调用推理端点

run()是触发文本生成推理的入口方法：

run( prompt: str, generation_kwargs: dict[str, Any] | None = None ) -> dict[str, list[str] | list[dict[str, Any]]]

参数

prompt（str）：用于文本生成的字符串提示词，必填。
generation_kwargs（dict[str, Any] | None）：额外的文本生成关键字参数。合并规则：这些参数与初始化时传入的generation_kwargs按 key 合并——run()中提供的 key 优先级更高（会覆盖初始化值），而只在初始化时设置过的 key 会被保留。

也就是说，你可以在初始化时设置一组"全局默认"生成参数，再在每次调用时按需覆盖或追加，无需重复构造组件。

返回值

返回一个字典，包含两个 key：

replies（list[str]）：模型生成的回复字符串列表。通常列表中只有一个元素，即模型对本次 prompt 的回复。
meta（list[dict[str, Any]]）：每个回复关联的元数据字典列表，例如 token 使用量、finish reason 等（具体字段取决于端点返回内容）。

异常

run()可能抛出以下异常：

异常	触发场景
`ValueError`	模型响应类型既不是字典列表也不是单个字典时。
`SagemakerNotReadyError`	SageMaker 模型尚未就绪、无法接受请求时（例如端点仍在创建或扩容中）。
`SagemakerInferenceError`	SageMaker 推理过程返回错误时。

基础使用示例

安装集成包

SagemakerGenerator属于独立集成包，需要先安装：

pip install amazon-sagemaker-haystack

独立使用

配置好 AWS 凭据（环境变量或共享凭据文件）后，最小可用示例：

from haystack_integrations.components.generators.amazon_sagemaker import ( SagemakerGenerator, ) generator = SagemakerGenerator(model="jumpstart-dft-hf-llm-falcon-7b-bf16") response = generator.run("What's Natural Language Processing? Be brief.") print(response)

API 参考文档给出的输出示例为：

>>> {'replies': ['Natural Language Processing (NLP) is a branch of artificial intelligence that focuses on >>> the interaction between computers and human language. It involves enabling computers to understand, interpret, >>> and respond to natural human language in a way that is both meaningful and useful.'], 'meta': [{}]}

使用指南中则使用 instruct 变体端点并展示了类似输出。可以看到：replies中保存模型生成的完整回答，meta中保存每条回复的元数据（示例中为空字典）。

你也可以在调用时覆盖生成参数：

response = generator.run( "Summarize the key ideas of this article.", generation_kwargs={"max_new_tokens": 150, "temperature": 0.3}, )

在 RAG Pipeline 中集成

SagemakerGenerator的典型用法是作为 RAG（检索增强生成）管线的生成环节：检索器召回相关文档，PromptBuilder把文档与问题组装成模板化 prompt，最后由SagemakerGenerator调用 SageMaker 端点生成答案。

使用指南给出了完整的 RAG 示例：

from haystack_integrations.components.generators.amazon_sagemaker import ( SagemakerGenerator, ) from haystack import Pipeline from haystack.components.retrievers.in_memory import InMemoryBM25Retriever from haystack.components.builders import PromptBuilder template = """ Given the following information, answer the question. Context: {% for document in documents %} {{ document.content }} {% endfor %} Question: What's the official language of {{ country }}? """ pipe = Pipeline() pipe.add_component("retriever", InMemoryBM25Retriever(document_store=docstore)) pipe.add_component("prompt_builder", PromptBuilder(template=template)) pipe.add_component( "llm", SagemakerGenerator(model="jumpstart-dft-hf-llm-falcon-7b-instruct-bf16"), ) pipe.connect("retriever", "prompt_builder.documents") pipe.connect("prompt_builder", "llm") pipe.run({"prompt_builder": {"country": "France"}})

这段代码演示了三条关键集成要点：

组件即插即用：SagemakerGenerator与 Haystack 的其他标准组件（InMemoryBM25Retriever、PromptBuilder）一样，通过pipe.add_component()注册，通过pipe.connect()连接。
接线方式：检索器输出documents接入prompt_builder.documents；prompt_builder的输出接入llm。PromptBuilder 的 Jinja 模板渲染出完整 prompt 后作为SagemakerGenerator.run()的输入。
运行参数：pipe.run()只需传入模板所需变量（示例中为country），Pipeline 会自动完成文档检索、prompt 组装与模型调用。

把示例中的docstore换成你自己写入文档的InMemoryDocumentStore，将model换成你实际部署的 SageMaker 端点名，即可得到一个可运行的、基于 AWS 托管 LLM 的 RAG 应用。

序列化与反序列化

作为 Haystack 组件，SagemakerGenerator支持通过字典完成序列化与反序列化，便于 Pipeline 的保存、加载与配置管理。

to_dict()

to_dict() -> dict[str, Any]

将组件序列化为字典。返回值为包含序列化数据的字典。序列化时会保留model、aws_custom_attributes、generation_kwargs等配置；而 AWS 凭据等Secret类型字段会以引用环境变量的形式序列化（而不是明文写入），从而避免敏感信息泄露。

from_dict()

from_dict(data: dict[str, Any]) -> SagemakerGenerator

从字典反序列化出SagemakerGenerator实例。

参数：

data（dict[str, Any]）：要反序列化的字典。

返回值：

SagemakerGenerator：反序列化后的组件实例。

配合 Haystack 的 YAML/JSON 序列化机制，你可以把包含SagemakerGenerator的完整 Pipeline 保存为配置文件，在部署时通过Pipeline.loads()等 API 恢复，实现 Pipeline 即代码（Pipeline-as-Code）。

补充说明与限制

远程托管推理：SagemakerGenerator不做本地模型加载，所有推理均发生在 AWS SageMaker 端点，因此使用前必须确保端点已成功部署并处于 InService 状态，否则run()会抛出SagemakerNotReadyError。
端点名即model：初始化时传入的model参数是 SageMaker 端点名（endpoint name），务必与 AWS 控制台中的端点名称一致。
凭据优先级：显式传入的Secret参数优先于环境变量，环境变量优先于共享凭据文件，最终遵循 boto3 标准凭据链解析。
生成参数因模型而异：generation_kwargs支持的 key 由模型决定。文档明确列出的max_new_tokens、temperature、top_p、return_full_text是 Llama-2 家族（及多数 Hugging Face LLM 部署）的通用负载参数，其他模型请查阅对应推理负载文档。
可选组件：在生成器总览的对比表中，SagemakerGenerator标注为非默认包含的集成组件，使用前需通过pip install amazon-sagemaker-haystack单独安装。

Haystack 集成 Amazon SageMaker：使用 SagemakerGenerator 调用 SageMaker Inference Endpoint 完成 LLM 文本生成