작업 수준 디버깅 에이전트 수준 디버깅 디버깅에 CloudTrail 사용 AWS CloudTrail을 사용하여 API 호출 로깅 모델 패키지 및 체크포인트

문제 해결

훈련 작업이 실패하거나 예기치 않게 작동하는 경우 다음 섹션을 통해 문제를 식별하고 해결할 수 있습니다. 작업 상태를 확인하면 문제가 구성 또는 에이전트에 있는지 여부를 좁히는 데 도움이 될 수 있으며, 아래 에이전트별 섹션에서는 각 배포 경로에 대한 로그와 일반적인 문제를 다룹니다.

작업 수준 디버깅

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: 타임스탬프가 있는 상태 변경의 전체 타임라인

작업 CloudWatch 로그

훈련 진행 상황 및 롤아웃 수준 정보는 계정의 다음 로그 그룹에 기록됩니다.


/aws/sagemaker/Job/AgentRFT

로그 스트림 이름은 입니다<job-name>/.

이러한 로그는 훈련 단계 진행 상황, 롤아웃 호출 이벤트 및 상위 수준 오류를 캡처합니다. 이는 작업이 얼마나 진행되었는지, 롤아웃이 성공적으로 호출되고 있는지 이해하는 데 도움이 될 수 있습니다.

작업이 실패하면 FailureReason 필드에 세부 정보가 있는지 확인합니다. Training 단계에서 실패하면 에이전트에 문제가 있을 수 있습니다. 이 경우 에이전트 로그에서 자세한 내용을 확인하세요.

에이전트 수준 디버깅

Amazon Bedrock AgentCore 디버깅

Amazon Bedrock AgentCore에 에이전트를 배포한 경우 다음은 에이전트 측 문제를 조사하는 데 도움이 될 수 있습니다.

에이전트 로그

에이전트 컨테이너의 stdout 및 stderr 출력은 계정의 Amazon CloudWatch Logs에 캡처됩니다. 다음 로그 그룹에서 찾을 수 있습니다.


/aws/bedrock-agentcore/runtimes/<runtime-name>-<id>-<qualifier>

이러한 로그는 오류, 스택 추적 및 SDK 메시지를 포함하여 에이전트 코드의 출력을 캡처합니다. 이러한 로그는 에이전트 코드, 종속성 또는 RFT 런타임에 대한 연결과 관련된 문제를 조사하는 데 사용할 수 있습니다.

에이전트 상태 확인

에이전트 런타임이 정상인지 확인합니다.


aws bedrock-agentcore-control list-agent-runtimes --region us-west-2

특정 런타임에 대한 세부 정보:


aws bedrock-agentcore-control get-agent-runtime \
  --agent-runtime-id <runtime-id> \
  --region us-west-2

사용자 지정 에이전트 디버깅

Lambda 전달자 경로를 사용하는 경우 Lambda 함수 자체 또는 외부 에이전트에서 문제가 발생할 수 있습니다. 다음은 둘 다 조사하는 데 도움이 될 수 있습니다.

Lambda 전달자 로그

Lambda 함수의 실행 로그는 Amazon CloudWatch Logs에 캡처됩니다. 다음 로그 그룹에서 찾을 수 있습니다.


/aws/lambda/<function-name>

이러한 로그는 요청 전달, 제한 시간 또는 Lambda와 에이전트 간의 연결과 관련된 문제를 조사하는 데 사용할 수 있습니다. 다음을 확인합니다.

호출 오류(Lambda가 에이전트에 연결할 수 없음)
제한 시간 오류(에이전트가 응답하는 데 너무 오래 걸림)
검증 오류(잘못된 롤아웃 요청)

연결 확인

Lambda 로그에 호출 오류 또는 제한 시간이 표시되면 Lambda가 에이전트에 연결할 수 없다는 문제일 수 있습니다. 다음 검사는 Lambda와 에이전트 간의 연결이 작동하는지 확인하는 데 도움이 될 수 있습니다.

상태 확인 - 에이전트가 실행 중인지 확인합니다.


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 런타임에 대한 추론 호출 또는 보상 보고와 관련된 문제를 조사하는 데 사용할 수 있습니다.

예를 들어 에이전트를 Amazon EKS에 배포한 경우 다음을 사용하여 에이전트의 로그를 확인할 수 있습니다.


kubectl logs -l app=external-agent --tail=50

디버깅에 CloudTrail 사용

CloudTrail 데이터 이벤트는 에이전트의 RFT 런타임 호출이 성공하고 있는지 확인하는 데 도움이 될 수 있습니다. 다음을 사용하여 이벤트를 찾습니다.

eventName: Sample, SampleWithResponseStream, CompleteRollout, UpdateReward
resources.type: AWS::SageMaker::Job

이러한 이벤트가 표시되지 않으면 에이전트가 RFT 런타임을 성공적으로 호출하지 못한 것입니다. 에이전트 로그 및 권한을 확인합니다.

AWS CloudTrail을 사용하여 API 호출 로깅

Amazon SageMaker AI는 사용자, 역할 또는 서비스가 수행한 작업에 대한 레코드를 제공하는 AWS 서비스인 AWS CloudTrail과 통합됩니다. CloudTrail은 Amazon SageMaker AI에 대한 모든 API 직접 호출을 이벤트로 캡처합니다. 캡처되는 직접 호출에는 Amazon SageMaker AI 콘솔로부터의 직접 호출과 Amazon SageMaker AI API 작업에 대한 코드 직접 호출이 포함됩니다. CloudTrail에서 수집한 정보를 사용하여 Amazon SageMaker AI에 전송된 요청, 요청이 이루어진 IP 주소, 요청이 이루어진 시간, 추가 세부 사항을 확인할 수 있습니다.

모든 이벤트 또는 로그 항목에는 요청을 생성했던 사용자에 관한 정보가 포함됩니다. 자격 증명을 이용하면 다음을 쉽게 판단할 수 있습니다.

요청을 루트 사용자로 했는지 사용자 보안 인증으로 했는지 여부.
IAM Identity Center 사용자를 대신하여 요청이 이루어졌는지 여부입니다.
역할 또는 페더레이션 사용자의 임시 자격 증명을 사용하여 요청이 생성되었는지 여부.
요청이 다른 AWS 서비스에 의해 이루어졌는지 여부입니다.

AWS 계정을 생성하면 계정에서 CloudTrail이 활성화되고 CloudTrail 이벤트 기록에 자동으로 액세스할 수 있습니다. CloudTrail 이벤트 기록은 AWS 리전에서 지난 90일간 기록된 관리 이벤트에 대한 보기, 검색, 다운로드 및 변경 불가능한 레코드를 제공합니다. 자세한 내용은 CloudTrail 사용 설명서의 CloudTrail 이벤트 기록 작업을 참조하세요. AWS CloudTrail 이벤트 기록 보기는 CloudTrail 요금이 부과되지 않습니다.

지난 90일 동안 AWS 계정에 이벤트를 지속적으로 기록하려면 추적 또는 CloudTrail Lake 이벤트 데이터 스토어를 생성합니다.

CloudTrail 추적

CloudTrail은 추적을 사용하여 Amazon S3 버킷으로 로그 파일을 전송할 수 있습니다. AWS Management Console을 사용하여 생성된 모든 추적은 다중 리전입니다. AWS CLI를 사용하여 단일 리전 또는 다중 리전 추적을 생성할 수 있습니다. 계정의 모든 리전에서 활동을 캡처하기 때문에 다중 AWS 리전 추적을 생성하는 것이 좋습니다. 단일 리전 추적을 생성하는 경우 추적의 AWS 리전에 기록된 이벤트만 볼 수 있습니다. 추적에 대한 자세한 내용은 AWS CloudTrail 사용 설명서의 AWS 계정에 대한 추적 생성 및 조직에 대한 추적 생성을 참조하세요.

CloudTrail에서 추적을 생성하여 진행 중인 관리 이벤트의 사본 하나를 Amazon S3 버킷으로 무료로 전송할 수는 있지만, Amazon S3 스토리지 요금이 부과됩니다. CloudTrail 요금에 대한 자세한 내용은 AWS CloudTrail 요금을 참조하세요. Amazon S3 요금에 관한 자세한 내용은 Amazon S3 요금을 참조하세요.

CloudTrail Lake 이벤트 데이터 스토어

CloudTrail Lake를 사용하면 이벤트에 대해 SQL 기반 쿼리를 실행할 수 있습니다. CloudTrail Lake는 행 기반 JSON 형식의 기존 이벤트를 Apache ORC 형식으로 변환합니다. ORC는 빠른 데이터 검색에 최적화된 열 기반 스토리지 형식입니다. 이벤트는 이벤트 데이터 스토어로 집계되며, 이벤트 데이터 스토어는 고급 이벤트 선택기를 적용하여 선택한 기준을 기반으로 하는 변경 불가능한 이벤트 컬렉션입니다. 이벤트 데이터 스토어에 적용하는 선택기는 어떤 이벤트가 지속되고 쿼리에 사용 가능한지를 제어합니다. CloudTrail Lake에 대한 자세한 내용은 AWS CloudTrail 사용 설명서의 CloudTrail Lake 작업을 참조하세요. AWS CloudTrail

CloudTrail Lake 이벤트 데이터 스토어 및 쿼리에는 비용이 발생합니다. 이벤트 데이터 스토어를 생성할 때 이벤트 데이터 스토어에 사용할 요금 옵션을 선택합니다. 요금 옵션에 따라 이벤트 모으기 및 저장 비용과 이벤트 데이터 스토어의 기본 및 최대 보존 기간이 결정됩니다. CloudTrail 요금에 대한 자세한 내용은 AWS CloudTrail 요금을 참조하세요.

CloudTrail의 SageMaker AI 데이터 이벤트

데이터 이벤트는 리소스 기반 또는 리소스에서 수행된 리소스 작업에 대한 정보를 제공합니다(예: Amazon S3 객체 읽기 또는 쓰기). 이를 데이터 플레인 작업이라고도 합니다. 데이터 이벤트는 흔히 대량 활동입니다. 기본적으로 CloudTrail은 데이터 이벤트를 로깅하지 않습니다. CloudTrail 이벤트 기록은 데이터 이벤트를 기록하지 않습니다.

데이터 이벤트에는 추가 요금이 적용됩니다. CloudTrail 요금에 대한 자세한 내용은 AWS CloudTrail 요금을 참조하세요.

CloudTrail 콘솔, AWS CLI 또는 CloudTrail API 작업을 사용하여 다양한 Amazon SageMaker AI 리소스 유형에 대한 데이터 이벤트를 로깅할 수 있습니다. 데이터 이벤트를 로깅하는 방법에 대한 자세한 내용은 AWS CloudTrail 사용 설명서의 AWS 관리 콘솔을 사용하여 데이터 이벤트 로깅 및 AWS 명령줄 인터페이스를 사용하여 데이터 이벤트 로깅을 참조하세요.

다음 표에는 데이터 이벤트를 로깅할 수 있는 Amazon SageMaker AI 리소스 유형이 나열되어 있습니다.

리소스 유형(콘솔)	resources.type 값	CloudTrail에 로깅되는 데이터 API	API 참조
SageMaker 엔드포인트	`AWS::SageMaker::Endpoint`	InvokeEndpoint, InvokeEndpointAsync, InvokeEndpointWithResponseStream	InvokeEndpoint, InvokeEndpointAsync, InvokeEndpointWithResponseStream
SageMaker 작업	`AWS::SageMaker::Job`	CompleteRollout, 샘플, SampleWithResponseStream	CompleteRollout, 샘플, SampleWithResponseStream

참고

InvokeEndpoint, InvokeEndpointAsyncSample, 및 SampleWithResponseStream API 호출은 요청 파라미터를 로깅하지 않습니다.

eventName, readOnly 및 resources.ARN 필드를 필터링하여 중요한 이벤트만 로깅하도록 고급 이벤트 선택기를 구성할 수 있습니다. 이러한 필드에 대한 자세한 내용은 CloudTrail API 참조의 AdvancedFieldSelector를 참조하세요. AWS CloudTrail

예: SageMaker 엔드포인트 및 작업에 대한 데이터 이벤트 로깅

다음 예제에서는 put-event-selectors AWS CLI 명령을 사용하여 고급 이벤트 선택기를 추가하는 방법을 보여줍니다.


[
  {
    "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

CloudTrail의 SageMaker AI 관리 이벤트

관리 이벤트는 AWS 계정의 리소스에 대해 수행되는 관리 작업에 대한 정보를 제공합니다. 이를 컨트롤 플레인 작업이라고도 합니다. 기본적으로 CloudTrail은 관리 이벤트를 로깅합니다.

Amazon SageMaker AI는 모든 Amazon SageMaker AI 컨트롤 플레인 작업을 관리 이벤트로 로깅합니다. Amazon SageMaker AI에서 CloudTrail에 로깅하는 Amazon SageMaker AI 컨트롤 플레인 작업 목록은 Amazon SageMaker AI API 참조를 참조하세요.

CloudTrail 이벤트 예제

CloudTrail 레코드 콘텐츠에 대한 자세한 내용은 CloudTrail 사용 설명서의 CloudTrail 레코드 콘텐츠를 참조하세요. AWS CloudTrail

모델 패키지 및 체크포인트

개요

멀티턴 RL 훈련 중에 플랫폼은 주기적으로 모델의 학습된 파라미터를 체크포인트로 저장합니다. 이러한 체크포인트는 모델 패키지 그룹 내에 SageMaker 모델 패키지로 저장되어 버전 관리, 계보 추적 및 작업 간 연속성을 지원합니다.

주요 개념

모델 패키지

모델 패키지는 특정 시점의 훈련된 모델 가중치를 포함하는 SageMaker AI의 버전 관리되고 변경 불가능한 아티팩트입니다. 훈련 중에 생성된 각 체크포인트는 모델 패키지로 저장됩니다. 모델 패키지에는 다음이 포함됩니다.

ARN(예: arn:aws:sagemaker:us-west-2:123456789012:model-package/my-group/5)
모델 파일이 포함된 S3 위치
생성 시기 및 훈련 단계에 대한 메타데이터

모델 패키지 그룹

모델 패키지 그룹은 여러 모델 패키지 버전을 포함하는 컨테이너입니다. 다중 회전 RL은 두 개의 개별 그룹을 사용합니다.

Group	용도	내용
출력 모델 패키지 그룹	최종 훈련된 모델 체크포인트	추론 및 지속적인 훈련에 적합한 HuggingFace 호환 LoRA 어댑터 가중치
중간 체크포인트 모델 패키지 그룹	재개 가능한 훈련 상태	전체 옵티마이저 상태 + 중단된 훈련 재개를 위한 어댑터 가중치

작업을 생성할 때 둘 다 지정합니다.


{
  "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 순위당)
저장 위치: 중간 체크포인트 모델 패키지 그룹
용도: 중단된 정확한 시점부터 훈련 재개
형식: 내부 형식(추론에 직접 사용할 수 없음)
생성 시: 모든 단계
사용 사례: 자동 복원력 또는 명시적인 지속적인 훈련

모델 체크포인트(가중치만 해당)

콘텐츠: SafeTensors 형식의 HuggingFace 호환 LoRA 어댑터 가중치
저장 위치: 출력 모델 패키지 그룹
용도: 추론, 배포 또는 지속적인 교육
형식: 표준 HuggingFace 어댑터 형식(adapter_config.json + adapter_model.safetensors)
생성 시: 모든 단계, 작업 완료 시 및 작업이 중지된 시간
사용 사례: 추론을 위해 미세 조정된 모델을 배포하거나 새 훈련 작업에 대한 입력으로 사용

중단된 훈련 재개

훈련 작업이 실패하거나 훈련 중 중지된 경우 이전 작업이 중단된 정확한 시점부터 재개되는 새 작업을 시작할 수 있습니다. 플랫폼은 재개 가능한 체크포인트에서 전체 훈련 상태(가중치 + 최적화 프로그램 + 단계 카운터)를 로드합니다.

재개하려면 재개 가능한 체크포인트(중간 체크포인트 모델 패키지 그룹에서)를 로 지정합니다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"
  }
}

요구 사항:

는 재개 가능한 체크포인트(모델 패키지 메타데이터IsCheckpoint=true에가 있는 체크포인트)를 가리켜InputModelPackageArn야 합니다.
새 작업은 동일한 기본 모델을 사용해야 합니다.
새 작업은 동일한 LoRA 구성(순위, 알파)을 사용해야 합니다.
새 작업은 동일한 하이퍼파라미터(학습 속도, 배치 크기 등)를 사용해야 합니다.
새 작업은 동일한 데이터 세트를 사용해야 합니다.

반복 훈련(지속 훈련)

반복 훈련을 사용하면 새 하이퍼파라미터, 다른 데이터 세트 또는 다른 훈련 구성을 사용하여 이전에 훈련된 모델을 구축할 수 있습니다. 재개와 달리 이렇게 하면 훈련된 LoRA 가중치에서 초기화되지만 새로운 옵티마이저 상태로 초기화되는 새로운 훈련 실행이 시작됩니다.

반복 훈련을 수행하려면 모델 체크포인트(출력 모델 패키지 그룹에서)를 로 지정합니다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"
  }
}

반복 간에 변경할 수 있는 사항:

하이퍼파라미터(학습 속도, 배치 크기, max_steps, group_size 등)
데이터 세트(다른 프롬프트, 다른 데이터 배포)
보상 함수(다른 보상 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이 포함됩니다.

작업이 실패하거나 중지된 경우: 마지막 중간 체크포인트가 출력 모델 패키지 그룹(최상의 노력)으로 승격됩니다.

체크포인트 모범 사례

체크포인트 생성 모니터링 - 훈련 중 ResumableCheckpoint 및 ModelCheckpoint 필드를 추적DescribeJob하는 데 사용
긴 작업의 경우 반복 훈련 사용 - 단계가 많은 작업이 실패할 수 있는 경우 처음부터 다시 시작하는 대신 체크포인트에서 다시 시작하도록 계획합니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

저장 시 암호화

할당량