LlamaIndex 接入 Amazon SageMaker Endpoint 部署的 LLM：SageMakerLLM 集成实战与源码解析-北京尧图网络

LlamaIndex 接入 Amazon SageMaker Endpoint 部署的 LLMSageMakerLLM 集成实战与源码解析【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_indexSageMakerLLM 是 LlamaIndex 官方 LLM 集成llama-index-llms-sagemaker-endpoint提供的适配器类用于在 LlamaIndex 生态中直接调用部署在 Amazon SageMaker Endpoint 上的自建或微调大模型。本文围绕 API 参考文档 docs/api_reference/api_reference/llms/sagemaker_endpoint.md 所暴露的SageMakerLLM类展开结合其真实源码、单元测试与官方示例 Notebook讲解从安装、凭据配置、基础补全/对话/流式调用到多模型提示词适配与请求响应编解码IO Handler的全部要点。读完本文你将能够在索引、查询引擎、Agent 等 LlamaIndex 组件中像使用普通 LLM 一样无缝使用 SageMaker 上托管的模型。一、模块定位与文档形态该 API 参考页是一份 mkdocstrings 自动生成的类参考入口核心指令为渲染llama_index.llms.sagemaker_endpoint模块中的SageMakerLLM成员。它对应的仓库实现位于类实现llama-index-integrations/llms/llama-index-llms-sagemaker-endpoint/llama_index/llms/sagemaker_endpoint/base.pyIO 编解码工具llama-index-integrations/llms/llama-index-llms-sagemaker-endpoint/llama_index/llms/sagemaker_endpoint/utils.py官方实战示例docs/examples/llm/sagemaker_endpoint_llm.ipynb从源码结构看该模块只导出一个公开类SageMakerLLM见init.py模块中另保留了一个向后兼容别名SageMakerLLMEndPoint SageMakerLLM。与同目录下的 Embedding 集成llama-index-embeddings-sagemaker-endpoint其 API 参考页见 docs/api_reference/api_reference/embeddings/sagemaker_endpoint.md相互独立本篇文章只聚焦 LLM 侧。二、安装与前置条件pip install llama-index-llms-sagemaker-endpoint从该包的 pyproject.toml 可以看到其运行时依赖与要求项目要求Python3.10,4.0llama-index-core0.13.0,0.15llama-index-llms-llama-cpp0.5.0,0.6提供默认的提示词转换函数注意源码在构建 AWS 客户端时依赖boto3/botocore若缺失会抛出ImportError: Please run pip install boto3 botocore to use AWS services.。因此建议同步安装pip install boto3 botocore此外使用本集成的前提是已有一个运行中的 SageMaker Endpoint即已在 SageMaker 中部署好 LLM本文只负责说明如何通过SageMakerLLM与之交互。三、初始化 SageMakerLLM必填参数、凭据与默认值构造函数要求必须显式提供endpoint_name否则直接抛出ValueError(Missing required argument: endpoint_name ...)见 base.py。3.1 字段速查表下表汇总了SageMakerLLM核心字段Field的语义与默认值均以 base.py 为准字段类型默认值说明endpoint_namestr必填SageMaker Endpoint 名称endpoint_kwargsDict[str, Any]{}追加到invoke_endpoint请求上的额外参数model_kwargsDict[str, Any]{}传给模型的采样参数temperature会被合并进来content_handlerBaseIOHandlerIOHandler()负责请求输入序列化、响应反序列化与去掉回显前缀profile_nameOptional[str]NoneAWS 配置文件profile名称缺省使用默认 profileaws_access_key_idOptional[str]NoneAWS 访问密钥 IDaws_secret_access_keyOptional[str]NoneAWS 访问密钥aws_session_tokenOptional[str]NoneAWS 会话令牌region_nameOptional[str]NoneAWS 区域名缺省使用 AWS CLI 中配置的区域max_retriesOptional[int]3API 最大重试次数ge0timeoutOptional[float]60.0API 请求超时秒ge0temperature构造参数Optional[float]0.5在初始化时写入model_kwargs[temperature]除以上字段外构造参数还支持system_prompt、messages_to_prompt、completion_to_prompt、callback_manager、output_parser等与基类LLM一致的能力。任何额外的**kwargs会透传。3.2 提供 AWS 凭据的三种方式官方示例 Notebook 演示了两种写法加上 SDK 默认链实际有三种方式一直接传访问密钥适合临时密钥或环境变量注入from llama_index.llms.sagemaker_endpoint import SageMakerLLM ENDPOINT_NAME YOUR-ENDPOINT-NAME AWS_ACCESS_KEY_ID YOUR-AWS-ACCESS-KEY-ID AWS_SECRET_ACCESS_KEY YOUR-AWS-SECRET-ACCESS-KEY AWS_SESSION_TOKEN YOUR-AWS-SESSION-TOKEN REGION_NAME YOUR-ENDPOINT-REGION-NAME llm SageMakerLLM( endpoint_nameENDPOINT_NAME, aws_access_key_idAWS_ACCESS_KEY_ID, aws_secret_access_keyAWS_SECRET_ACCESS_KEY, aws_session_tokenAWS_SESSION_TOKEN, aws_region_nameREGION_NAME, )方式二使用 AWS profile本地已配置~/.aws/credentials与~/.aws/configfrom llama_index.llms.sagemaker_endpoint import SageMakerLLM ENDPOINT_NAME YOUR-ENDPOINT-NAME PROFILE_NAME YOUR-PROFILE-NAME llm SageMakerLLM(endpoint_nameENDPOINT_NAME, profile_namePROFILE_NAME) # 省略 profile_name 即使用默认 profile方式三什么都不传走 boto3 默认凭据链环境变量、共享凭据文件、IAM Role 等。3.3 区域参数与弃用提示需要注意region_name参数的写法在源码中有一段历史包袱在 base.py 中若通过**kwargs传入旧的region_name会触发DeprecationWarning并提示改用aws_region_name。因此新代码推荐使用aws_region_name同时它的底层仍会映射到 Pydantic 字段region_name与 AWS 客户端构造逻辑最终配置顺序为显式区域 AWS CLI 配置区域。凭据解析最终落到 core 的工具函数get_aws_service_client见 llama-index-core/llama_index/core/utilities/aws_utils.py它创建boto3.Session若给了access key则用它构建 session否则用profile_name并构造 botocoreConfig(retries{max_attempts: max_retries or 0, mode: standard}, connect_timeouttimeout)再创建sagemaker-runtime客户端。任何凭据错误都会被包装成ValueError(Please verify the provided credentials.)这是排查认证问题时的关键线索。四、基础用法补全与对话拿到llm实例后即可调用与 LlamaIndex 其他 LLM 完全一致的接口。4.1complete文本补全resp llm.complete(Paul Graham is , formattedTrue) print(resp)这里formattedTrue表示跳过 completion_to_prompt 的包装避免自动拼系统提示词与对话模板适合只想把原始字符串喂给端点、且端点本身不会回显输入的场景。若formattedFalse默认源码会先执行self._completion_to_prompt(prompt, self.system_prompt)见 base.py。4.2chat多轮对话from llama_index.core.llms import ChatMessage messages [ ChatMessage(rolesystem, contentYou are a pirate with a colorful personality), ChatMessage(roleuser, contentWhat is your name), ] resp llm.chat(messages) print(resp) # assistant: Arrrr, shiver me timbers! ...从实现看chat并非直接发送消息而是先把消息列表经self.messages_to_prompt(messages)折叠成一段字符串提示词再调用complete(..., formattedTrue)最后把CompletionResponse包装成ChatResponse见 base.py。也就是说SageMaker Endpoint 侧看到的是纯文本格式的提示词对话能力完全取决于你提供的模板函数。五、流式输出5.1stream_completeresp llm.stream_complete(Paul Graham is , formattedTrue) for r in resp: print(r.delta, end)底层调用的是 SageMaker Runtime 的invoke_endpoint_with_response_stream并逐块解析response[Body]中的PayloadPart[Bytes]见 base.py。每轮会基于累计的raw_text用 IO Handler 的remove_prefix去掉回显再与上一轮的prev_clean_text求差得到增量delta。5.2stream_chatfrom llama_index.core.llms import ChatMessage messages [ ChatMessage(rolesystem, contentYou are a pirate with a colorful personality), ChatMessage(roleuser, contentWhat is your name), ] resp llm.stream_chat(messages) for r in resp: print(r.delta, end)stream_chat同样先把消息折叠为提示词再委托给stream_complete最后把流式CompletionResponse逐条转换为ChatResponse。5.3 异步接口的现状需要提醒的是achat、astream_chat、acomplete、astream_complete四个异步方法在源码中直接raise NotImplementedError见 base.py。因此当前版本该集成不支持异步调用如需并发建议自行用线程池包装同步方法。六、多模型适配messages_to_prompt 与 completion_to_promptSageMakerLLM是与具体模型解耦的抽象层它只负责把提示词按端点要求的格式序列化。官方文档与 Notebook 明确说明默认参数与 Llama 2 兼容。这意味着如果你部署的是其他模型很可能需要自定义下面两个可调用对象messages_to_prompt(messages)接收ChatMessage列表以及缺省时的 system prompt返回端点 LLM 兼容格式的字符串completion_to_prompt(completion)接收补全字符串与可选的 system prompt返回端点 LLM 兼容格式的字符串。默认实现取自 llama-cpp 集成包的通用函数见 llama-index-integrations/llms/llama-index-llms-llama-cpp/llama_index/llms/llama_cpp/llama_utils.py 中的messages_to_prompt/completion_to_prompt并在 base.py 中被赋为默认值LLAMA_MESSAGES_TO_PROMPT与LLAMA_COMPLETION_TO_PROMPT。SageMakerLLM类 docstring 给出了针对HuggingFaceH4/zephyr-7b-beta的自定义示例见 base.py完整代码如下from llama_index.llms.sagemaker_endpoint import SageMakerLLM # hooks for HuggingFaceH4/zephyr-7b-beta # 不同模型可能需要不同的格式 def messages_to_prompt(messages): prompt for message in messages: if message.role system: prompt f|system|\n{message.content}/s\n elif message.role user: prompt f|user|\n{message.content}/s\n elif message.role assistant: prompt f|assistant|\n{message.content}/s\n # 保证以 system prompt 开头缺失则插入空 system if not prompt.startswith(|system|\n): prompt |system|\n/s\n prompt # 追加最终的 assistant 提示符 prompt prompt |assistant|\n return prompt def completion_to_prompt(completion): return f|system|\n/s\n|user|\n{completion}/s\n|assistant|\n llm SageMakerLLM( model_nameHuggingFaceH4/zephyr-7b-beta, api_keyyour_api_key, regionyour_region, messages_to_promptmessages_to_prompt, completion_to_promptcompletion_to_prompt, )说明上面 docstring 示例中的model_name、api_key、region为展示性占位写法真实构造时请以本文第三节的表单参数为准如endpoint_name必填、区域用aws_region_name。七、请求/响应编解码BaseIOHandler 与 IOHandler 原理SageMaker 端点与客户端之间的“协议”并不统一——不同容器Hugging Face Transformers、自定义推理代码等的 JSON 结构差异很大。为此集成抽象出content_handler概念。7.1 BaseIOHandler 接口utils.py 中BaseIOHandler是一个 pydantic ABC 的抽象基类包含两个字段与四个必须实现的方法成员类型/签名职责content_typestr请求体 MIME 类型acceptstr期望的响应 MIME 类型serialize_input(request, model_kwargs)(str, dict) - bytes把提示词与模型参数序列化为请求体deserialize_output(response)StreamingBody - str把响应体解析为生成文本deserialize_streaming_output(response)bytes - str把流式字节块解析为增量文本remove_prefix(response, prompt)(str, str) - str去掉文本中回显的输入提示词前缀7.2 默认 IOHandler 的 JSON 协议默认的IOHandler使用application/json其协议如下请求体serialize_input{inputs: 提示词, parameters: {temperature: 0.5, ...}}即json.dumps({inputs: request, parameters: model_kwargs}).encode(utf-8)。响应解析deserialize_outputjson.load(...)[0][generated_text]对应形如[{generated_text: ...}]的标准 Hugging Face Text Generation Inference 输出结构。流式响应deserialize_streaming_output内部通过decode(utf-8).lstrip([{generated_text:).rstrip(}])裁剪出文本后包装为{response: ...}再解析。可见流式协议同样假定是[{generated_text:片段}]形式的拼接载荷。去前缀remove_prefix由于很多端点会在生成内容中回显输入提示词默认实现直接按raw_text[len(prompt):]切除提示词部分complete与stream_complete都会调用它来得到“干净”的生成结果。7.3 自定义 Handler如果你的容器使用自定义 JSON 结构例如{prompt: ..., max_new_tokens: ...}或返回{generated_text: ...}之外的字段就应继承llama_index.llms.sagemaker_endpoint.utils.BaseIOHandler并实现上述四个方法然后通过content_handler传入实例。这正是多框架、多容器部署场景下该集成的主要扩展点。八、底层调用链与设计细节一次同步补全调用llm.complete(prompt)在源码中的完整链路如下对应 base.py合并model_kwargs与调用时传入的**kwargs若formattedFalse用completion_to_prompt(prompt, system_prompt)包装提示词content_handler.serialize_input(prompt, model_kwargs)序列化请求体通过 boto3 客户端调用invoke_endpoint(EndpointName..., Body..., ContentType..., Accept..., **endpoint_kwargs)用content_handler.deserialize_output(...)反序列化响应体用content_handler.remove_prefix(...)去掉回显封装为CompletionResponse(text..., rawresponse, additional_kwargs{model_kwargs: ..., endpoint_kwargs: ...})返回。其他值得注意的实现细节endpoint_kwargs会被原样展开到每次invoke_endpoint*请求中可用来传递如CustomAttributes、TargetModel、InferenceComponentName等 SageMaker Runtime 参数model_kwargs会在构造时强制写入temperature默认 0.5并可在每次调用时通过关键字参数临时覆盖{**self.model_kwargs, **kwargs}的合并顺序保证调用方优先LLMMetadata.model_name直接返回endpoint_name见 base.py因此下游的 token 统计、回调等元信息以端点为粒度complete、chat等公开方法上都挂有llm_completion_callback()/llm_chat_callback()装饰器事件会接入 LlamaIndex 的 CallbackManager 链路模块保留了旧类名SageMakerLLMEndPoint作为别名base.py老代码可继续使用但建议迁移到SageMakerLLM集成测试tests/test_llms_sagemaker_endpoint.py通过检查SageMakerLLM.__mro__验证其继承自BaseLLM确保它能被 LlamaIndex 各类上层组件索引、Query Engine、Agent按标准 LLM 协议使用。九、小结与继续阅读综上SageMakerLLM以极低的接入成本把 SageMaker Endpoint 变成 LlamaIndex 中的标准 LLM你只需要给出端点名与 AWS 凭据即可使用complete/chat/ 流式接口并通过messages_to_prompt、completion_to_prompt、content_handler三个扩展点适配任意模型容器与协议。若你在 SageMaker 上还部署了 Embedding 模型可参考同仓库的 Embedding 集成docs/api_reference/api_reference/embeddings/sagemaker_endpoint.md配套使用。建议进一步阅读的仓库资源完整可运行示例docs/examples/llm/sagemaker_endpoint_llm.ipynb类源码字段/方法/弃用逻辑base.pyIO 协议与自定义 Handlerutils.pyAWS 客户端构造逻辑llama-index-core/llama_index/core/utilities/aws_utils.py默认提示词函数来源llama_utils.py继承关系测试test_llms_sagemaker_endpoint.py【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

LlamaIndex 接入 Amazon SageMaker Endpoint 部署的 LLM：SageMakerLLM 集成实战与源码解析

相关推荐

GSD 代码库漂移检测门（codebase_drift_gate）：execute-phase 执行后的结构一致性守护

GPS/BDS双频RTK解算实战：基于NovAtel观测数据的模糊度固定

cpp-httplib 请求追踪：用 2 个路由钩子给轻量服务补上可观测性

更多资讯

OpenClaw Fireworks 插件：接入 Fireworks 模型提供商的完整实践

KPCA故障诊断：SPE与T²双统计量工业实战指南

Linera 应用内动态创建并调用合约：create-and-call 示例深度解析

TVBoxOSC文档查看指南：遥控器三键把说明书读明白

商超蔬菜价格弹性与补货策略：Python数据清洗到报童模型实战

Vibe-Trading 行为金融技能：过反应与无反应、情绪周期与去偏差的定量化实战指南

今日更新

CopilotKit Vue Demo 与 React Demo 的 Parity 实现指南：路由、运行时端点与交互语义的全框架对齐

Harbor RBAC 实战：db_auth 模式下非管理员用户管理项目成员的完整验证与权限模型解析

STM32平衡车纯平衡程序从拆包到参数整定的完整调试指南

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？