AWS Machine Learning Blog

Architecture patterns for fast session startup on Amazon Bedrock AgentCore runtime

7.1内容质量
Architecture patterns for fast session startup on Amazon Bedrock AgentCore runtime

TL;DR · AI 摘要

Architecture patterns for fast session startup on Amazon Bedrock AgentCore runtime Artificial Intelligence Architecture...

核心要点

  • 主题聚焦:Architecture patterns for fast session startup o
  • 来源:AWS Machine Learning Blog,建议结合原文判断细节。
  • AI 分析暂不可用,本条为保底评分与摘要。
#AI#编程#前端#后端#云计算
打开原文

用于 Amazon Bedrock AgentCore 运行时快速会话启动的架构模式 | 人工智能

用于 Amazon Bedrock AgentCore 运行时快速会话启动的架构模式

当今的代理程序会审查代码、处理索赔,并且可以无人值守地运行数小时。许多代理程序还位于交互式体验之后,其中一个人需要等待第一个响应。Amazon Bedrock AgentCore 运行时为这些代理程序提供了一个完全托管的无服务器环境:每个会话都在其自己的隔离微虚拟机中运行,当没有工作时平台会扩展到零,并且您只需为您会话消耗的资源付费。

将 AgentCore 运行时的 platformVersion 设置为 "V2" 会改变会话的启动方式。它不再为每个会话初始化您的容器,而是准备一次环境,对其快照并为每个新会话恢复该快照。会话启动时间更快且更一致。V2 还会回收会话未使用的内存,因此您的账单将跟踪您的代理程序实际使用的资源。

对于大多数代理程序,切换到 V2 就足够了。一些代理程序需要重新设计才能获得全部好处,而对于聊天和语音体验,即使 2 秒也太慢了。本文解释了 V2 如何启动会话,如何测量会话启动时间,以及如何避免首次请求的处理,包括 AgentCore 运行时现在支持的构建钩子。我们介绍了四种模式,从对代理程序代码的修改到在用户需要之前启动会话。

您需要哪种模式?

您的情况

需要执行的操作

章节

大约 2 秒的新会话是可以接受的

切换到 V2 并在启动前完成所有初始化

code
app.run()

避免首次请求的处理

您的代理程序需要在早期加载大型文件、CLI 或浏览器,且无法在进程中保留它们

添加构建钩子,在快照构建时加载并预热它们

与钩子配合使用

您需要亚秒级响应,且用户在发送第一个请求之前就会参与(打开应用或聊天窗口)

当用户参与时在后台启动会话

在用户参与时预热

V2 如何启动会话

AgentCore 运行时在新的微虚拟机中运行每个会话。在 V1 中,AgentCore 从 Amazon Elastic Container Registry (Amazon ECR) 拉取您的容器镜像,启动容器,并在处理第一个请求之前运行您的初始化代码。镜像拉取占主导地位,因此冷启动时间会随着镜像大小的增加而延长。

V2 仅执行一次该操作。当您创建或更新运行时,AgentCore 运行时会在新的微虚拟机中启动您的容器,并等待第一个健康 ping(GET /ping),该 ping 必须在 120 秒内到达。然后它会清除操作系统的文件缓存以保持快照较小,冻结微虚拟机,并将其内存和磁盘存储为快照。

这与 V1 不同:现在每次创建或更新都需要几分钟时间来构建快照。

在本文中,init 指的是您的代理程序在 /ping 报告健康之前执行的所有操作。使用 AgentCore Python SDK 时,这是 app.run() 之前的所有内容。如果您运行自己的 HTTP 服务器(如 Node.js 或其他语言),请在初始化完成后才报告健康状态。

图 1:每次创建或更新时构建一次

当新会话到达时,AgentCore 会将快照恢复到新的微虚拟机中。您的进程会从冻结的位置精确恢复,所有导入、对象和客户端都保持原样。来自镜像的文件会按需加载:每个块会在会话首次读取时获取。

图 2:每次新会话调用

以下是从这些流程中得出的三个事实,本文其余部分将基于这些事实进行展开:

  • 内存以完整形式恢复。在快照时刻进程持有的任何内容,以及如 /dev/shm 这类基于 RAM 的文件系统中的内容,首次访问时均可以内存速度直接获取。
  • 文件读取不会保留。在冻结之前文件缓存会被清除,因此在初始化期间读取文件不会使恢复后的会话加快文件读取速度。
  • 镜像文件在首次读取时获取。块的首次读取来自快照存储,之后会被缓存到更接近主机的位置。

下表展示了这些规则对典型代理工作内容的影响,具体取决于工作执行的位置:

| 工作内容 | 在初始化期间完成 | 在处理程序中完成 | |---------|------------------|------------------| | 导入库 | 会话启动时加载到内存 | 每个新会话从镜像中读取 | | 创建客户端(例如 boto3) | 恢复时已包含端点和凭证解析,首次使用时重新连接套接字 | 每个新会话从零构建 | | 打开网络连接 | 恢复后失效,需在快照前关闭 | 每次打开新连接 | | 从镜像加载静态数据并保存到对象 | 从镜像读取文件但不保留数据 | 无影响,因为文件缓存已被清除 |

如果你了解 AWS Lambda SnapStart,这些规则会显得很熟悉。Marc Brooker 关于 SnapStart 如何加载快照的博文,以及 SnapStart 预加载策略的博文,都是有用的背景资料。

表格中的所有内容都假设代理能够在其进程中保留所需内容。但并非总是如此。作为独立进程运行并在启动后退出的 CLI,或浏览器二进制文件,会在初始化期间读取,然后消失,因此恢复后的会话需要再次从镜像中获取。对于这些情况,可以添加构建钩子,相关内容见“使用钩子”。图 3 显示了钩子的执行位置。

图 3:使用钩子进行构建和调用

优化前先进行测量

代理应用程序中的延迟不是一个单一数字。请求会在 AgentCore 运行时花费时间准备会话以运行你的代码,然后在你的代码中花费时间:模型调用、工具调用、子代理以及响应流式传输。你通过不同方式修复这些问题,因此首先要找出哪个部分占主导地位。

AgentCore 运行时会将这两个指标发布为 Amazon CloudWatch 指标,指标命名空间为 AWS/Bedrock-AgentCore。Latency 是首次字节的时间。OverheadLatency 是平台相关部分,例如启动微虚拟机和在新会话中恢复快照的时间。

你想要的指标 | 获取方式 -------------|--------- TTFB(首次字节时间) | Latency 指标 运行时时间 | OverheadLatency 指标 你的代码运行时间 | Latency - OverheadLatency 初始化时间 | 在代码启动时测量(见下例)。它不包含在 V2 的任何请求中

初始化时间不会出现在这些指标中,因为 V2 的初始化只在快照构建时执行一次,而不是每个会话都执行。它会影响创建或更新达到 READY 状态所需的时间,而不是请求延迟。要查看初始化时间,可在 app.run() 之前记录一次日志。该行会出现在运行时的构建日志中:

python
import time
INIT_START = time.time()  # 模块的第一行
# 导入、客户端、数据加载...
print(f"init_ms={round((time.time() - INIT_START) * 1000)}")
app.run()

如何解读指标拆分:

  • 新会话的 OverheadLatency 较高:时间消耗在会话启动阶段。使用本文后续部分提到的模式,在用户需要之前提前启动会话。
  • 在同一会话中,第一次请求的耗时明显高于第二次请求:属于初始化阶段的工作正在你的处理程序中运行。在 AgentCore Observability(Amazon Bedrock AgentCore 的一项功能)中,围绕工具设置、文件加载和延迟导入添加自定义时间跨度,定位问题后将其移至初始化阶段。

报告 P90 和 P99 等分位数,或 TM90 等截尾均值(计算最快 90% 请求的平均值并剔除最慢的尾部)。普通平均值会掩盖慢请求的影响。OverheadLatency 包含对正在运行会话和新会话的请求,因此其分布取决于你的请求中有多少会启动新会话。请使用相似混合比例的运行进行对比。

在测试时应使用预期的生产环境新会话生成速率,而非部署后仅测试少量会话。

若需包含客户端的网络耗时,请在客户端一并进行测量。记录 invoke 调用耗时,让处理程序返回实际运行时长并进行减法运算。由于两个时间戳均来自同一台机器,客户端与微虚拟机之间的时钟差异无需考虑。若使用流式传输,非常小的事件可能需要等待输出累积到数百字节才会发出,因此首次事件耗时可能高于会话启动时间。

将工作从首次请求中剥离

通常的冷启动建议是延迟导入并保持初始化过程简洁。但在 V2 版本中,做法恰恰相反:初始化仅在快照构建时执行一次,而延迟到处理程序中的工作需要为每个新会话支付代价。这适用于静态工作:导入、客户端和镜像中的数据。动态数据无法进行快照处理。下一节将专门讨论动态数据的处理方式。

最能察觉性能问题的代理是那些在请求时从镜像中读取大型文件的代理:小型本地模型的权重、嵌入向量、数据集、大型库、自动化用的浏览器二进制文件,或编码代理运行的 CLI 工具链作为子进程。读取大量小文件(如 TypeScript 项目编译时)会产生相同影响。仅导入少量库并调用托管模型的代理,主要需要确保导入和客户端配置正确。

如何重构你的代理

在初始化阶段创建对象,而不仅仅是进行导入。创建对象会加载其依赖的模块并保持在活动内存中。同样在初始化阶段启动使用外部库的本地工具,而非在代理首次调用时启动。

在初始化阶段创建客户端。端点解析、凭证解析和客户端模块都会随快照返回。套接字不会,但 boto3 客户端在首次调用时能干净地重新连接。其他一些网络客户端会先尝试使用过期的套接字连接,这会增加数百毫秒的延迟,因此在快照生成前应关闭这些连接。

将静态数据保留在内存中,如提示词、技能前言、配置和小型索引。以对象形式持有数据,而不仅仅是读取操作:

code
INDEX = pathlib.Path("/opt/data/index.bin").read_bytes()  # 在初始化阶段:保留字节数据

保持工具持续运行而非每次请求都启动。在处理程序中启动的子进程会在每个新会话中从镜像读取其二进制文件和库。在初始化阶段启动的长期运行辅助进程(如语言服务器或已完成导入的工作者进程)会作为进程内存的一部分返回。通过管道或套接字与其通信。

将无法保留在内存中的文件复制到基于 RAM 的磁盘。像 tsc 这样的工具链作为独立程序运行,读取自己的文件。在初始化阶段将其复制到 /dev/shm 或 ramfs 挂载点,使读取操作直接来自内存。

发布编译后的字节码。uv pip install 默认不会编译,因此晚期导入也会从源代码编译。设置 UV_COMPILE_BYTECODE=1 或使用 pip install --compile。

以下示例在初始化期间构建代理、其模型及其客户端,因此每个会话都会继承这些内容:

code
import json, pathlib
import boto3
import pandas as pd  # 初始化期间导入,包括使用频率较低的库
from strands import Agent
from strands.models import BedrockModel
from bedrock_agentcore.runtime import BedrockAgentCoreApp

MODEL_ID = "us.anthropic.claude-haiku-5-5"

# 初始化:在快照之前运行一次,每个新会话都会继承这些对象
PROMPTS = json.loads(pathlib.Path("prompts.json").read_text())
ddb = boto3.client("dynamodb")
agent = Agent(model=BedrockModel(model_id=MODEL_ID), system_prompt=PROMPTS["system"])

app = BedrockAgentCoreApp()

@app.entrypoint
def invoke(payload):
    return agent(payload["prompt"])

app.run()  # /ping 仅在该行之后才会响应

权衡取舍:新会话首次字节耗时等于启动微虚拟机和恢复快照的时间,加上处理程序的执行时间。将工作移至初始化阶段可以缩短处理程序的执行时间,但任何保留在内存中的内容都会使快照体积增大。你还需要为每个会话中保留的内存付费。在更改前后测量端到端会话启动时间,以确保你确实减少了延迟,而不仅仅是将延迟从处理程序转移到了恢复过程。

参考卡片

数据类型 | 建议方案 --- | --- 首次请求需要的大文件(如模型、CLI 或浏览器) | 在初始化期间将其保留在内存中,或通过构建钩子预加载 需要选择性读取的大参考数据 | 通过访问点(需要虚拟私有云(VPC)模式)在初始化期间挂载 Amazon S3 文件或 Amazon 弹性文件系统(Amazon EFS) 代理很少读取的文件 | 保留在镜像中,或移动到 Amazon 简单存储服务(Amazon S3)、S3 文件或 Amazon EFS 会话创建的文件 | 无需更改

使用钩子

构建钩子在初始化期间构建,不会替换初始化过程。在初始化阶段完成尽可能多的工作,将初始化无法覆盖的部分交给钩子处理。你需在容器中暴露一个 HTTP 端点,AgentCore 运行时在构建运行时期间会向该端点发送两次 POST 请求:

  • 在快照之前:在构建微虚拟机上,你的代理报告健康状态后、冻结之前。代理在此处加载并保留在内存中的任何内容都会成为快照的一部分,因此每个会话都会从这些内容开始。
  • 在测试恢复之后:在恢复快照以进行检查的独立微虚拟机上。此调用的内容不会被快照记录。使用它来读取会话需要的文件,这决定了恢复后的会话首先获取哪些内容。

X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type 请求头会告诉你的代理正在处理的是哪种调用:首次调用用于内存预热,第二次调用用于磁盘预热。两次调用共享 120 秒时间,因此磁盘调用会获得内存调用剩余的时间。仅在工作完成后返回 2xx 响应。任何其他响应、连接失败或超时都会导致创建或更新失败,AgentCore 运行时不会重试。你的运行时日志组中的 build-logs- 会显示哪个调用失败及其原因。

钩子功能适用于 V2 运行时。创建或更新运行时时,通过 hooksConfiguration 进行配置:

code
client = boto3.client("bedrock-agentcore-control")
client.create_agent_runtime(
    agentRuntimeName="my_agent",
    agentRuntimeArtifact={"containerConfiguration": {"containerUri": IMAGE_URI}},
    roleArn=ROLE_ARN,
    networkConfiguration={"networkMode": "PUBLIC"},
    platformVersion="V2",
    hooksConfiguration={
        "build": {
            "warmup": {
                "action": {"httpPost": {"path": "/warmup", "port": 8080}}
            }
        }
    },
)

端口是可选参数,默认使用代理的服务端口。如果手动设置端口,需选择8000到12000之间的非平台保留端口。路径不能与AgentCore运行时在该端口上已使用的路由冲突,例如POST /invocations或GET /ping。UpdateAgentRuntime会替换整个钩子配置,因此每次需要保留钩子配置时都必须在更新请求中包含hooksConfiguration。

在代理实现中,需在同一个端点处理两种请求类型:

code
import asyncio
from fastapi import FastAPI, Request, Response

app = FastAPI()

# 每个会话启动时读取的文件列表
STARTUP_FILES = ["/app/models/tokenizer.json", "/app/config/agent.json"]

def load_shared_state():
    # 将所有会话需要的资源加载到内存中,如重型导入、
    # 模型权重和缓存
    ...

def read_startup_files():
    # 读取会话启动时需要的文件,使新会话能更快使用这些资源
    for path in STARTUP_FILES:
        with open(path, "rb") as f:
            while f.read(1024 * 1024):
                pass

@app.get("/ping")
def ping():
    return {"status": "Healthy"}

@app.post("/warmup")
async def warmup(request: Request):
    # Starlette和FastAPI的请求头查找是大小写不敏感的
    warmup_type = request.headers.get(
        "X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type", ""
    ).lower()
    # 在工作线程中执行操作,确保/ping接口持续响应
    if warmup_type == "memory":
        await asyncio.to_thread(load_shared_state)
    elif warmup_type == "disk":
        await asyncio.to_thread(read_startup_files)
    # 操作完成后才返回响应
    return Response(status_code=200)

@app.post("/invocations")
async def invoke(request: Request):
    payload = await request.json()
    # 每个会话都需要执行的请求级操作
    return {"response": payload.get("prompt", "")}

如需查看完整配置参考,请参阅[配置AgentCore运行时生命周期钩子](#)。如需查看完整代码示例,请参阅[示例代码](#)。

快照陷阱:必须保留在处理函数中的内容

初始化过程中创建的所有内容都会被冻结到快照中,直到下次部署,每个会话都从相同的副本开始。对于大多数对象来说,这是预期的行为。但对于以下值来说,这会导致错误,对于随机值则会引发安全问题。

在处理函数中,按会话加载动态数据一次。来自AgentCore网关(Amazon Bedrock AgentCore的一项功能)的工具目录、特性标志和价格表在部署后会发生变化。应在处理函数中加载这些数据并在模块级别进行缓存,使每个会话只需获取一次。由于会话最长可持续8小时,因此为缓存设置过期时间:

code
_tools, _loaded_at = None, 0.0

def get_tools():
    global _tools, _loaded_at
    if _tools is None or time.time() - _loaded_at > 300:  # 壁钟时间:5分钟后刷新
        _tools, _loaded_at = load_gateway_tools(), time.time()
    return _tools

从处理函数中调用get_tools(),并将结果传递给初始化期间创建的代理。

创建会话级别的值应在处理程序中完成。

| 值类型 | 创建位置 | 原因 | |--------|----------|------| | 随机值、随机数、密钥、秘密 | 在处理程序中,使用 secrets、os.urandom() 或 uuid.uuid4() | 初始化期间创建的库随机状态(如 Python 的 random、NumPy)在每个会话中是相同的,而操作系统生成的值是唯一的 | | 当前时间和经过时间 | 使用 time.time() | 初始化时间戳在快照时固定,而 time.monotonic() 不计算快照存储期间的时间 | | 计时器、速率限制器、TTL 缓存 | 使用墙钟时间或在首次请求时重置 | 使用单调时钟测量经过时间的任何内容在恢复时几乎不会出现间隙 | | 自行获取的凭证和令牌 | 在过期时刷新 | 初始化期间加载的值可能在会话开始前过期 |

了解限制。会话会在以下情况结束:空闲超时到期(默认空闲超时 idleRuntimeSessionTimeout 为 15 分钟,范围 60 秒到 8 小时)、达到最大生命周期(默认 maxLifetime 为 8 小时)或你主动停止时。

毫秒级响应:在用户需要前启动会话

假设你的新会话启动需要约 2 秒(包括前面章节提到的所有时间分解)。一个已经运行的会话响应时间约为 200 毫秒。对于聊天或语音体验,实现毫秒级响应的关键是确保会话在用户首次请求到达前已经启动。有两种实现方式:

在用户交互时预热

大多数交互式应用在首次提示前会收到信号:用户打开应用、聊天窗口或支持页面。利用这个信号:生成会话 ID,在后台向代理发送预热请求,并将会话 ID 与对话关联。当用户输入第一条消息时,会话已经运行。

python
# 后端,当用户打开聊天时(不要阻塞 UI)
session_id = f"chat-{uuid.uuid4().hex}"  # 会话 ID 需要至少 33 个字符
agentcore.invoke_agent_runtime(agentRuntimeArn=ARN, runtimeSessionId=session_id,
                               payload=json.dumps({"action": "prime"}).encode())
save_conversation(user_id, session_id)  # 后续所有对话都复用这个会话 ID

# 代理处理程序:在任何模型调用前响应预热请求
@app.entrypoint
def invoke(payload):
    if payload.get("action") == "prime":
        return {"primed": True}
    return agent(payload["prompt"])

这种模式无需额外基础设施,能完全隐藏会话启动时间(当用户发送首条消息耗时超过约 2 秒时)。每个与用户交互但从未发送提示的用户会消耗一个会话。短空闲超时可保持这个消耗最小。

总结

在 V2 版本中,AgentCore 运行时将大部分会话启动工作转移到部署阶段。你的容器只需启动一次,每个新会话都会恢复该容器的状态:内存完整恢复,文件在首次读取时加载。

为将会话启动时间保持在约 2 秒内:在初始化阶段完成静态工作,将首次请求所需的数据保留在内存中,将动态和会话级别的值保留在处理程序中。对于无法在内存中保存的文件,添加构建钩子。若要实现低于 1 秒的启动时间,请在用户需要前启动会话:在用户交互时(当收到信号时)启动。

要开始使用,请在创建或更新运行时时将 platformVersion 设置为 V2,然后查看 优化您的代理以适配 AgentCore 运行时 V2。如需了解工作负载相关问题,请联系您的 AWS 账户团队。

关于作者

'"`