本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 问题排查 如果您的训练作业失败或行为异常，以下各节可以帮助您识别和解决问题。检查任务状态可以帮助缩小问题出在您的配置还是代理中，而下面的代理特定部分涵盖了每种部署路径的日志和常见问题。 ## Job 级别调试 使用 `DescribeJob` API 检查任务的当前状态并查看失败的原因。响应包括作业的状态、任务失败时的失败原因，以及显示问题发生前任务进展情况的状态转换时间表。 ``` aws sagemaker describe-job \ --job-name "my-agent-rft-job" \ --job-category AgentRFT \ --region us-west-2 ``` 要检查的关键字段： + **JobStatus:** 当前状态 (`InProgress`、`Completed`、`Failed`、`Stopping`、`Stopped`) + **SecondaryStatus:** 更精细的相 (`Starting`、、`Downloading``Training`、`Uploading`) + **FailureReason:** 如果任务失败，说明原因 + **SecondaryStatusTransitions:** 带有时间戳的状态变化的完整时间表 **Job CloudWatch 日志** 训练进度和推出级别信息将记录到您账户中的以下日志组中： ``` /aws/sagemaker/Job/AgentRFT ``` 日志流名称是`/`。 这些日志捕获训练步骤进度、部署调用事件和高级错误。它们可能有助于了解您的工作进展情况，以及是否成功调用了部署。 如果您的任务失败，请查看该`FailureReason`字段以了解详细信息。如果在此`Training`阶段失败，则问题可能出在您的代理上。在这种情况下，请查看您的代理日志以获取更多信息。 ## 代理级别调试 ### Amazon Bedrock 调试 AgentCore 如果您已将代理部署到 Amazon Bedrock AgentCore，则以下内容可能有助于调查代理方面的问题。 **代理日志** 您的代理容器的 stdout 和 stderr 输出将在您账户的 Amazon CloudWatch 日志中捕获。你可以在以下日志组中找到它们： ``` /aws/bedrock-agentcore/runtimes/-- ``` 这些日志会捕获代理代码的输出，包括错误、堆栈跟踪和 SDK 消息。这些日志可用于调查与您的代理代码、依赖关系或与 RFT 运行时的连接相关的问题。 **检查代理运行状况** 验证您的代理运行时是否正常： ``` aws bedrock-agentcore-control list-agent-runtimes --region us-west-2 ``` 有关特定运行时的详细信息： ``` aws bedrock-agentcore-control get-agent-runtime \ --agent-runtime-id \ --region us-west-2 ``` ### 自定义代理调试 如果您使用的是 Lambda 转发器路径，则可能会在 Lambda 函数本身或外部代理中出现问题。以下内容可能有助于对两者进行调查。 **Lambda 转发器日志** 您的 Lambda 函数的执行日志会记录在亚马逊 CloudWatch 日志中。你可以在以下日志组中找到它们： ``` /aws/lambda/ ``` 这些日志可用于调查与请求转发、超时或 Lambda 与您的代理之间的连接相关的问题。检查： + 调用错误（Lambda 无法联系到您的代理） + 超时错误（代理响应时间过长） + 验证错误（发布请求格式错误） **验证连通性** 如果您的 Lambda 日志显示调用错误或超时，则问题可能是 Lambda 无法到达您的代理。以下检查有助于确认您的 Lambda 和代理之间的连接是否正常。 Health check — 确认您的代理正在运行： ``` curl -s "http://$AGENT_ENDPOINT/health" # Expected: {"status": "ok"} ``` Lambda 测试调用 — 确认 Lambda 可以联系到您的代理： ``` aws lambda invoke \ --function-name rft-agent-forwarder \ --cli-binary-format raw-in-base64-out \ --payload '{"prompt": "test", "metadata": {"jobArn": "test", "rolloutId": "test-1"}}' \ --region us-west-2 \ /tmp/response.json && cat /tmp/response.json # Note: This will return an InternalServerError because the jobArn "test" # does not correspond to an active training job. This is expected. # Success means the Lambda executed and reached your agent — check agent # logs to confirm the request was received. ``` 如果您的 Lambda 成功执行但任务仍然失败，则您的代理日志可能包含更多详细信息。查看您的代理日志，了解与推理调用或奖励报告相关的错误。 **代理日志** 您的代理自己的日志取决于其部署位置。这些日志可用于调查与您的代理代码、对 RFT Runtime 的推理调用或奖励报告相关的问题。 例如，如果您将代理部署到 Amazon EKS，则可以通过以下方式查看代理的日志： ``` kubectl logs -l app=external-agent --tail=50 ``` ## CloudTrail 用于调试 CloudTrail 数据事件可以帮助确认您的代理对 RFT 运行时的调用是否成功。通过以下方式查找活动： + **事件名称:,,**`Sample`, `SampleWithResponseStream` `CompleteRollout` `UpdateReward` + **资源。类型：**`AWS::SageMaker::Job` 如果您没有看到这些事件，则说明您的代理无法成功调用 RFT 运行时。检查代理日志和权限。 ## 使用 记录 API 调用 Amazon CloudTrail Amazon SageMaker AI 与 Amazon CloudTrail一项服务集成，该服务提供用户、角色或 Amazon 服务所执行操作的记录。 CloudTrail 将 Amazon A SageMaker I 的所有 API 调用捕获为事件。捕获的调用包括来自亚马逊 A SageMaker I 控制台的调用和对亚马逊 AI AP SageMaker I 操作的代码调用。使用收集的信息 CloudTrail，您可以确定向 Amazon A SageMaker I 发出的请求、发出请求的 IP 地址、发出请求的时间以及其他详细信息。 每个事件或日志条目都包含有关生成请求的人员信息。身份信息有助于您确定以下内容： + 请求是使用根用户凭证还是用户凭证发出的。 + 请求是否代表 IAM Identity Center 用户发出。 + 请求是使用角色还是联合用户的临时安全凭证发出的。 + 请求是否由其他 Amazon 服务发出。 CloudTrail 在您创建 Amazon 账户时在您的账户中处于活动状态，并且您自动可以访问 CloudTrail **活动历史记录**。 CloudTrail **事件历史记录**提供了一个地区过去 90 天记录的管理事件的可查看、可搜索、可下载且不可变的记录。 Amazon 有关更多信息，请参阅《*Amazon CloudTrail 用户指南》*中的 “[使用 CloudTrail 事件历史记录](https://docs.amazonaws.cn/awscloudtrail/latest/userguide/view-cloudtrail-events.html)”。查看**活动历史记录**不 CloudTrail 收取任何费用。 要在过去 90 天内持续记录您的 Amazon 账户中的事件，请创建跟踪或 [CloudTrail Lake](https://docs.amazonaws.cn/awscloudtrail/latest/userguide/cloudtrail-lake.html) 事件数据存储。 ### CloudTrail 步道 *跟踪*允许 CloudTrail 将日志文件传输到 Amazon S3 存储桶。使用 Amazon 管理控制台创建的所有跟踪都是多区域的。您可以使用 CLI Amazon 创建单区域或多区域跟踪。建议创建多区域跟踪，因为您可以捕获账户中所有 Amazon 区域的活动。如果您创建了单区域跟踪，则只能查看在该跟踪 Amazon 区域中记录的事件。有关跟踪的更多信息，请参阅*Amazon CloudTrail 用户指南*中的[为您的 Amazon 账户](https://docs.amazonaws.cn/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)[创建跟踪和为组织](https://docs.amazonaws.cn/awscloudtrail/latest/userguide/creating-trail-organization.html)创建跟踪。 通过创建跟踪，您可以免费将正在进行的管理事件的一份副本传送到您的 Amazon S3 存储桶，但会收取 Amazon S3 存储费用。 CloudTrail 有关 CloudTrail 定价的更多信息，请参阅[Amazon CloudTrail定价](https://www.amazonaws.cn/cloudtrail/pricing/)。有关 Amazon S3 定价的信息，请参阅 [Amazon S3 定价](https://www.amazonaws.cn/s3/pricing/)。 ### CloudTrail 湖泊事件数据存储 *CloudTrail Lak* e 允许您对自己的活动进行 SQL-based 查询。 CloudTrail Lake 将基于行的 JSON 格式的现有事件转换为 [Apache ORC](https://orc.apache.org/) 格式。ORC 是一种针对快速检索数据进行优化的列式存储格式。事件将被聚合到*事件数据存储*中，它是基于您通过应用[高级事件选择器](https://docs.amazonaws.cn/awscloudtrail/latest/userguide/cloudtrail-lake-concepts.html#adv-event-selectors)选择的条件的不可变的事件集合。应用于事件数据存储的选择器用于控制哪些事件持续存在并可供您查询。有关 CloudTrail Lake 的更多信息，请参阅《*Amazon CloudTrail 用户指南》*中的 “[使用 Amazon CloudTrail Lake](https://docs.amazonaws.cn/awscloudtrail/latest/userguide/cloudtrail-lake.html)”。 CloudTrail 湖泊事件数据存储和查询会产生费用。创建事件数据存储时，您可以选择要用于事件数据存储的[定价选项](https://docs.amazonaws.cn/awscloudtrail/latest/userguide/cloudtrail-lake-manage-costs.html#cloudtrail-lake-manage-costs-pricing-option)。定价选项决定了摄取和存储事件的成本，以及事件数据存储的默认和最长保留期。有关 CloudTrail 定价的更多信息，请参阅 [Amazon CloudTrail 定价](https://www.amazonaws.cn/cloudtrail/pricing/)。 ### SageMaker 中的 AI 数据事件 CloudTrail [数据事件](https://docs.amazonaws.cn/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events)可提供对资源或在资源中所执行资源操作（例如，读取或写入 Amazon S3 对象）的相关信息。这些也称为数据面板操作。数据事件通常是高容量活动。默认情况下， CloudTrail 不记录数据事件。 CloudTrail **事件历史**记录不记录数据事件。 记录数据事件将收取额外费用。有关 CloudTrail 定价的更多信息，请参阅 [Amazon CloudTrail 定价](https://www.amazonaws.cn/cloudtrail/pricing/)。 您可以使用 CloudTrail 控制台、 Amazon CLI 或 CloudTrail AP SageMaker I 操作记录各种 Amazon AI 资源类型的数据事件。有关如何记录数据事件的更多信息，请参阅《*Amazon CloudTrail 用户指南*[》中的使用 Amazon 管理控制台](https://docs.amazonaws.cn/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events-console)[记录数据事件和使用 Amazon 命令行界面](https://docs.amazonaws.cn/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#creating-data-event-selectors-with-the-AWS-CLI)记录数据事件。 下表列出了您可以记录数据事件的 SageMaker Amazon AI 资源类型： | 资源类型（控制台） | resources.type 值 | 数据 API 已登录到 CloudTrail | API 参考 | | --- | --- | --- | --- | | SageMaker 终端节点 | AWS::SageMaker::Endpoint | InvokeEndpoint, InvokeEndpointAsync, InvokeEndpointWithResponseStream | [InvokeEndpoint](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html), [InvokeEndpointAsync](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_runtime_InvokeEndpointAsync.html), [InvokeEndpointWithResponseStream](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_runtime_InvokeEndpointWithResponseStream.html) | | SageMaker 工作 | AWS::SageMaker::Job | CompleteRollout，示例， SampleWithResponseStream | [CompleteRollout](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_job_runtime_CompleteRollout.html)，[示例](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_job_runtime_Sample.html)，[SampleWithResponseStream](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_job_runtime_SampleWithResponseStream.html) | **注意** `InvokeEndpoint`、`InvokeEndpointAsync``Sample`、和 `SampleWithResponseStream` API 调用不记录请求参数。 您可以将高级事件选择器配置为在 `eventName`、`readOnly` 和 `resources.ARN` 字段上进行筛选，从而仅记录那些对您很重要的事件。有关这些字段的更多信息，请参阅《Amazon CloudTrail API 参考》**中的 [AdvancedFieldSelector](https://docs.amazonaws.cn/awscloudtrail/latest/APIReference/API_AdvancedFieldSelector.html)。 **示例：记录 SageMaker 终端节点和作业的数据事件** 以下示例说明如何使用 [put-event-selectors Amazon CLI 命令添加高级事件选择器](https://docs.amazonaws.cn/cli/latest/reference/cloudtrail/put-event-selectors.html)： ``` [ { "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["Data"] }, { "Field": "resources.ARN", "Equals": ["arn:aws:sagemaker:us-east-1:111122223333:endpoint/your-inference-endpoint-arn"] }, { "Field": "resources.type", "Equals": ["AWS::SageMaker::Endpoint"] } ] }, { "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["Data"] }, { "Field": "resources.ARN", "Equals": ["arn:aws:sagemaker:us-east-1:111122223333:job/your-job-arn"] }, { "Field": "resources.type", "Equals": ["AWS::SageMaker::Job"] } ] } ] ``` 然后运行： ``` aws cloudtrail put-event-selectors \ --trail-name your-trail-name \ --advanced-event-selectors=file://advanced-event-selectors.json ``` ### SageMaker 中的 AI 管理事件 CloudTrail [管理事件](https://docs.amazonaws.cn/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html#logging-management-events)提供有关对您 Amazon 账户中的资源执行的管理操作的信息。这些也称为控制面板操作。默认情况下， CloudTrail 记录管理事件。 Amazon SageMaker AI 将所有亚马逊 SageMaker AI 控制平面操作记录为管理事件。有关亚马逊 AI 记录到的亚马逊 SageMaker AI 控制平面操作的列表 CloudTrail，请参阅[亚马逊 AI AP SageMaker I 参考](https://docs.amazonaws.cn/sagemaker/latest/APIReference)。 SageMaker ### CloudTrail 事件示例 有关 CloudTrail 录音内容的信息，请参阅《*Amazon CloudTrail 用户指南》*中的[CloudTrail 录制内容](https://docs.amazonaws.cn/awscloudtrail/latest/userguide/cloudtrail-event-reference-record-contents.html)。 ## 模型包和检查点 ### 概述 **在多回合 RL 训练期间，平台会定期将模型学习到的参数保存为检查点。**这些检查点作为**SageMaker 模型包**存储在 Model Package **Grou** ps 中，从而实现版本控制、世系跟踪和跨任务连续性。 ### 重要概念 **模型 Package** Model Package 是 SageMaker AI 中一个版本化、不可变的工件，它包含在特定时间点经过训练的模型权重。训练期间生成的每个检查点都存储为 Model Package。Model Package 有： + ARN（例如）`arn:aws:sagemaker:us-west-2:123456789012:model-package/my-group/5` + 包含模型文件的 S3 位置 + 关于创建时间以及从哪个训练步骤开始的元数据 **Model Package 组** 模型包组是一个包含多个模型包版本的容器。 Multi-turn RL 使用两个不同的组： | Group | 用途 | 内容 | | --- | --- | --- | | 输出模型 Package 组 | 经过最终训练的模型检查点 | HuggingFace-compatible LoRa 适配器砝码适用于推理和持续训练 | | 中级检查点模型 Package 组 | 可恢复训练状态 | 完整优化器状态 \+ 用于恢复中断训练的适配器权重 | 在创建作业时，您可以同时指定两者： ``` { "ModelPackageConfig": { "OutputModelPackageGroupArn": "arn:aws:sagemaker:us-west-2:123456789012:model-package-group/my-final-models", "IntermediateCheckpointModelPackageGroupArn": "arn:aws:sagemaker:us-west-2:123456789012:model-package-group/my-intermediate-checkpoints" } } ``` ### 检查点类型 **可恢复检查点（完整状态）** + **内容**：LoRa 适配器权重 \+ 优化器状态 \+ 训练步骤元数据（每个 GPU 等级） + **存储于**：中间检查点模型 Package Group + **目的**：从训练被中断的确切位置恢复训练 + **格式**：内部格式（不能直接用于推理） + **创建时间**：每个步骤 + **用例**：自动恢复能力或明确的继续训练 **模型检查点（仅限权重）** + **内容**：格式化的 HuggingFace-compatible LoRa 适配器 SafeTensors 权重 + **存储于**：输出模型 Package Group + **目的**：推理、部署或继续训练 + **格式**：标准 HuggingFace 适配器格式 (`adapter_config.json`\+`adapter_model.safetensors`) + **创建**时间：每个步骤、任务完成时和作业停止时 + **用例**：部署经过微调的模型进行推理，或者将其用作新训练作业的输入 ### 恢复中断的训练 如果训练作业失败或在训练中停止，则可以开始一项新作业，该作业从上一个作业中断的确切位置恢复。平台从可恢复的检查点加载完整的训练状态（权重 \+ 优化器 \+ 计步器）。 要恢复，请将可恢复检查点（来自中间检查点模型 Package Group）指定为`InputModelPackageArn`： ``` { "ModelPackageConfig": { "OutputModelPackageGroupArn": "arn:aws:sagemaker:us-west-2:123456789012:model-package-group/my-final-models", "IntermediateCheckpointModelPackageGroupArn": "arn:aws:sagemaker:us-west-2:123456789012:model-package-group/my-intermediate-checkpoints", "InputModelPackageArn": "arn:aws:sagemaker:us-west-2:123456789012:model-package/my-intermediate-checkpoints/5" } } ``` **要求：** + `InputModelPackageArn`必须指向可恢复的检查点（其 Model Package 元数据`IsCheckpoint=true`中包含的检查点） + 新作业必须使用相同的基本模型 + 新任务必须使用相同的 LoRa 配置（等级、alpha） + 新作业必须使用相同的超参数（学习率、批量大小等） + 新作业必须使用相同的数据集 ### 迭代训练（继续训练） 迭代训练允许你使用新的超参数、不同的数据集或不同的训练配置在先前训练过的模型的基础上进行构建。与恢复不同，这会开始新的训练运行，该训练从训练过的 LoRa 权重进行初始化，但具有全新的优化器状态。 要进行迭代训练，请将模型检查点（来自 Output Model Package Group）指定为`InputModelPackageArn`： ``` { "ModelPackageConfig": { "OutputModelPackageGroupArn": "arn:aws:sagemaker:us-west-2:123456789012:model-package-group/my-final-models", "IntermediateCheckpointModelPackageGroupArn": "arn:aws:sagemaker:us-west-2:123456789012:model-package-group/my-intermediate-checkpoints", "InputModelPackageArn": "arn:aws:sagemaker:us-west-2:123456789012:model-package/my-final-models/3" } } ``` **在迭代之间可以更改的内容：** + 超参数（学习率、批次大小、最大步数、组大小等） + 数据集（不同的提示，不同的数据分布） + 奖励函数（不同的奖励 lambda） + 代理配置 **什么必须保持不变：** + 基本型号（LoRa 适配器特定于基本模型架构） **典型用例：** + 先针对简单问题进行训练，然后继续处理更难的问题（课程学习） + 使用简单的奖励功能进行训练，然后使用更细致入微的奖励功能进行改进 + 观察初始训练动态后，增加批次大小或调整学习率 ### 检查点生命周期 ``` Training Step 1 → Intermediate Checkpoint (Resumable) Training Step 1 → Intermediate Checkpoint (HFCompatible) ... Training Step N-1 → Intermediate Checkpoint (Resumable) Training Step N-1 → Intermediate Checkpoint (HFCompatible) ... Training Step N (final) → Model Checkpoint (HuggingFace LoRA) → Output Model Package Group ``` 作业成功完成后：最终模型权重将作为模型包保存在输出模型包组中。作业记录中的`OutputModelPackageArn`字段包含最终模型的 ARN。 当作业失败或停止时：最后一个中间检查点将提升到 Output Model Package 组（尽力而为）。 ### 检查点的最佳实践 + **监控检查点的创建** — 用于在训练期间`DescribeJob`进行追踪`ResumableCheckpoint`和`ModelCheckpoint`田径训练 + **对于长时间的作业，请使用迭代训练** — 如果包含许多步骤的作业可能失败，请计划从检查点恢复，而不是从头开始