Haystack 集成 Amazon SageMakerSagemakerGenerator 文本生成组件实战指南【免费下载链接】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 官方集成的SagemakerGenerator组件展开讲解如何让 Haystack Pipeline 直接调用部署在 Amazon SageMaker Inference Endpoint 上的大语言模型LLM完成文本生成。读完本文你将掌握该组件的安装方式、全部初始化参数、推理参数generation_kwargs的合并规则、异常处理机制以及如何把它接入一个完整的 RAG 检索增强生成流水线。组件定位SageMaker 端点与 Haystack 之间的生成桥梁SagemakerGenerator是 Haystack 生成器Generator家族的一员其作用是启用基于 Amazon SageMaker 的文本生成Enables text generation using Amazon Sagemaker。与调用 OpenAI、HuggingFace 等托管 API 的生成器不同它针对的是已经部署在 SageMaker Inference Endpoint 上的 LLM你只需要把端点的名称告诉组件Haystack 就会通过 AWS SDK 向该端点发起推理请求。在 Haystack 的生成器生态总览表生成器索引中它与 Amazon Bedrock、Vertex AI、OpenAI 等生成器并列服务于云上模型 本地编排的场景。参考文档特别提示关于如何在 SageMaker 上部署模型可参阅 AWS 官方的 SageMaker JumpStart 基础模型文档本文不再展开 AWS 侧的部署细节仅聚焦 Haystack 集成侧的使用。前置条件与安装使用SagemakerGenerator需要两个前提一个已部署并处于 InService 状态的 SageMaker 推理端点例如通过 SageMaker JumpStart 部署的 Falcon、Llama-2 等模型有效的 AWS 凭证组件才能代表你调用端点。组件位于独立的集成包amazon-sagemaker-haystack中安装命令pip install amazon-sagemaker-haystack安装后从如下路径导入from haystack_integrations.components.generators.amazon_sagemaker import SagemakerGenerator注意该集成包托管在 haystack-core-integrations 仓库中因此本仓库内不包含其实现源码其 API 契约以版本化 API 参考文档为准。AWS 凭证配置五种 Secret 注入方式SagemakerGenerator需要 AWS 凭证才能工作。最简单的方式是设置环境变量AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY组件在初始化时会自动读取。从__init__的签名可以看到凭证类参数全部是Secret | None类型且默认值均通过Secret.from_env_var(..., strictFalse)从环境变量读取——strictFalse意味着如果环境变量不存在也不抛错即这些参数全部可选__init__( model: str, aws_access_key_id: Secret | None Secret.from_env_var( [AWS_ACCESS_KEY_ID], strictFalse ), aws_secret_access_key: Secret | None Secret.from_env_var( [AWS_SECRET_ACCESS_KEY], strictFalse ), aws_session_token: Secret | None Secret.from_env_var( [AWS_SESSION_TOKEN], strictFalse ), aws_region_name: Secret | None Secret.from_env_var( [AWS_DEFAULT_REGION], strictFalse ), aws_profile_name: Secret | None Secret.from_env_var( [AWS_PROFILE], strictFalse ), aws_custom_attributes: dict[str, Any] | None None, generation_kwargs: dict[str, Any] | None None, ) - None各参数的作用如下表参数类型默认环境变量说明modelstr无必填SageMaker 推理端点的名称aws_access_key_idSecret \| NoneAWS_ACCESS_KEY_IDAWS 访问密钥 IDaws_secret_access_keySecret \| NoneAWS_SECRET_ACCESS_KEYAWS 访问密钥aws_session_tokenSecret \| NoneAWS_SESSION_TOKENAWS 会话令牌临时凭证场景aws_region_nameSecret \| NoneAWS_DEFAULT_REGION区域名不提供时使用默认区域aws_profile_nameSecret \| NoneAWS_PROFILEAWS 配置文件profile名不提供时使用默认 profileaws_custom_attributesdict[str, Any] \| None—透传给 SageMaker 的自定义属性generation_kwargsdict[str, Any] \| None—文本生成的附加关键字参数这意味着除了环境变量你还可以直接传入Secret对象例如从密钥管理系统读取后构造或者利用aws_profile_name走共享凭证文件~/.aws/credentials中的某个 profile——参考文档的示例注释也印证了这一点Make sure your AWS credentials are set up correctly. You can use environment variables or a shared credentials file.快速上手独立使用 SagemakerGenerator凭证就绪后最小用法只需要指定model参数即端点名然后调用run()from haystack_integrations.components.generators.amazon_sagemaker import SagemakerGenerator generator SagemakerGenerator(modeljumpstart-dft-hf-llm-falcon-7b-bf16) response generator.run(Whats Natural Language Processing? Be brief.) print(response) {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: [{}]}从使用指南组件页面可以看到完整的独立用法还支持显式调用warm_up()预热连接from haystack_integrations.components.generators.amazon_sagemaker import SagemakerGenerator client SagemakerGenerator(modeljumpstart-dft-hf-llm-falcon-7b-instruct-bf16) client.warm_up() response client.run(Briefly explain what NLP is in one sentence.) print(response) {replies: [Natural Language Processing (NLP) is a subfield of artificial intelligence and computational linguistics that focuses on the interaction between computers and human languages...], meta: [{}]}run()的返回值是一个字典固定包含两个键replieslist[str]模型生成的全部回复文本metalist[dict[str, Any]]每条回复对应的元数据如 token 数、结束原因等具体内容取决于模型端点返回的 payload。在 RAG Pipeline 中使用SagemakerGenerator最常见的 Pipeline 位置是紧跟PromptBuilder之后见组件页面的速览表即检索 → 构造提示词 → 生成的标准 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: Whats the official language of {{ country }}? pipe Pipeline() pipe.add_component(retriever, InMemoryBM25Retriever(document_storedocstore)) pipe.add_component(prompt_builder, PromptBuilder(templatetemplate)) pipe.add_component( llm, SagemakerGenerator(modeljumpstart-dft-hf-llm-falcon-7b-instruct-bf16), ) pipe.connect(retriever, prompt_builder.documents) pipe.connect(prompt_builder, llm) pipe.run({prompt_builder: {country: France}})这个示例中的两个配合组件都可以在本仓库中找到实现源码便于你深入理解调用链PromptBuilder基于 Jinja2 模板把检索到的文档渲染成提示词其documents输入槽与template渲染逻辑决定了发给SagemakerGenerator的prompt内容InMemoryBM25Retriever在内存文档库上做 BM25 检索负责把documents喂给PromptBuilder。Pipeline 的执行流是InMemoryBM25Retriever检索出相关文档 →PromptBuilder用模板拼装提示词 → 提示词作为prompt传入SagemakerGenerator.run()→ 生成结果经llm输出槽返回。model参数指定的是你自己的 SageMaker 端点名请将示例中的jumpstart-dft-*端点名替换为实际部署的端点。generation_kwargs推理参数详解与合并规则文本生成的附加参数通过generation_kwargs传递它既可以在初始化时设置也可以在每次run()调用时设置。run()的签名如下run( prompt: str, generation_kwargs: dict[str, Any] | None None ) - dict[str, list[str] | list[dict[str, Any]]]两次设置按按 key 合并run()中的键优先的规则生效run()里显式给出的键会覆盖初始化时同名的键初始化时设置了而run()未涉及的键则继续保留。因此你可以把通用默认参数放在初始化阶段把本次请求专属参数放在run()阶段。具体支持哪些参数取决于你的模型。参考文档指出对于 HuggingFace 模型可参考其部署说明文档以Llama-2 系列为例SageMaker 端点支持以下推理负载参数参数类型约束说明max_new_tokens正整数必须为正整数模型生成文本直到输出长度不含输入上下文长度达到该值temperature正浮点数必须为正 float控制输出随机性值越高越倾向低概率词值越低越倾向高概率词temperature0即贪婪解码top_p浮点数介于 0 和 1 之间每一步生成时从累计概率为top_p的最小候选词集合中采样return_full_text布尔值必须为 bool默认False为True时输入文本会包含在输出文本中示例用法generator SagemakerGenerator( modeljumpstart-dft-meta-textgenerationneuron-llama-2-7b, generation_kwargs{max_new_tokens: 256, temperature: 0.7, top_p: 0.9}, ) # 本次运行单独覆盖 temperature response generator.run(Explain RAG in one paragraph., generation_kwargs{temperature: 0.2})aws_custom_attributes向端点透传自定义属性部分模型在推理时需要额外的自定义属性此时使用aws_custom_attributes参数它会被原样透传给 SageMaker 请求。参考文档给出的典型场景是Llama-2 模型必须显式接受 EULA最终用户许可协议generator SagemakerGenerator( modeljumpstart-dft-meta-textgenerationneuron-llama-2-7b, aws_custom_attributes{accept_eula: True}, )该参数的类型为dict[str, Any] | None在初始化时一次性传入如果你的模型文档要求其他自定义头或属性也按同样的字典结构传入。run() 的异常处理参考文档明确列出了run()可能抛出的三类异常生产环境建议逐一捕获处理ValueError模型返回的响应类型既不是字典列表、也不是单个字典时抛出——即端点返回了无法解析的 payload 结构SagemakerNotReadyErrorSageMaker 模型尚未就绪、无法接受请求时抛出例如端点仍在创建或更新中SagemakerInferenceErrorSageMaker 推理服务本身返回错误时抛出例如端点不可达、权限不足、请求被拒。from haystack_integrations.components.generators.amazon_sagemaker import SagemakerGenerator try: response generator.run(Hello, model!) except ValueError: print(Unexpected response format from the endpoint.) except Exception as e: # SagemakerNotReadyError / SagemakerInferenceError print(fSageMaker inference failed: {e})序列化to_dict 与 from_dict作为 Haystack 组件SagemakerGenerator实现了标准的序列化协议便于 Pipeline 的 YAML/JSON 存档与还原to_dict() - dict[str, Any] from_dict(data: dict[str, Any]) - SagemakerGeneratorto_dict()将组件序列化为字典返回dict[str, Any]包含类型名与全部初始化参数from_dict(data)从字典反序列化出组件实例返回SagemakerGenerator。其中Secret类型的 AWS 凭证参数在序列化时会遵循 Haystack 的 Secret 序列化约定默认不会把明文密钥写入序列化结果而是保留环境变量引用这保证了导出的 Pipeline 配置可以安全地共享、版本化。序列化后即可配合 Haystack Pipeline 的 YAML 加载机制在任意环境中重建组件。小结SagemakerGenerator把部署在 SageMaker 端点上的 LLM无缝接入了 Haystack 的组件化编排体系通过环境变量或Secret注入 AWS 凭证用model指定端点用generation_kwargs灵活控制推理参数用aws_custom_attributes满足 Llama-2 等模型的特殊要求最后在 RAG Pipeline 中与PromptBuilder、InMemoryBM25Retriever等组件协同完成检索—提示—生成的完整链路。其异常类型SagemakerNotReadyError、SagemakerInferenceError和to_dict/from_dict序列化接口也让它在生产环境中的错误处理与配置管理更加规范。进一步阅读SagemakerGenerator 组件使用指南含参数总览、独立用法与 RAG 示例Amazon SageMaker 集成 API 参考完整签名与异常契约Haystack 生成器总览对比各云端生成器能力配合组件源码PromptBuilder、InMemoryBM25Retriever【免费下载链接】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），仅供参考