Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Resolución de problemas
Si su trabajo de formación no funciona o se comporta de forma inesperada, las siguientes secciones pueden ayudarle a identificar y resolver el problema. Comprobar el estado de su trabajo puede ayudar a determinar si el problema está en su configuración o en su agente, y las secciones específicas del agente que aparecen a continuación cubren los registros y los problemas comunes de cada ruta de implementación.
## Depuración a nivel de trabajo
Usa la `DescribeJob` API para comprobar el estado actual de tu trabajo y ver por qué ha fallado. La respuesta incluye el estado del trabajo, el motivo del error si el trabajo ha fallado y un cronograma de las transiciones de estado que muestra cuánto progresó el trabajo antes de que se produjera el problema.
```
aws sagemaker describe-job \
--job-name "my-agent-rft-job" \
--job-category AgentRFT \
--region us-west-2
```
Campos clave que hay que comprobar:
+ **JobStatus:** Estado actual (`InProgress``Completed`,`Failed`,`Stopping`,`Stopped`)
+ **SecondaryStatus:** Fase más granular (`Starting`,`Downloading`,`Training`,`Uploading`)
+ **FailureReason:** Si el trabajo ha fallado, una descripción del motivo
+ **SecondaryStatusTransitions:** Cronología completa de los cambios de estado con marcas de tiempo
** CloudWatch Registros de trabajos**
La información sobre el progreso de la formación y el nivel de implementación se registra en el siguiente grupo de registros de su cuenta:
```
/aws/sagemaker/Job/AgentRFT
```
El nombre del flujo de registro es. `/`
Estos registros capturan el progreso de los pasos de entrenamiento, los eventos de invocación de la implementación y los errores de alto nivel. Pueden resultar útiles para saber hasta qué punto ha progresado tu trabajo y si las implementaciones se están invocando correctamente.
Si tu trabajo no funciona, consulta el `FailureReason` campo para obtener más información. Si se produce un error durante la `Training` fase, es probable que el problema esté en tu agente. En este caso, consulta los registros de tus agentes para obtener más información.
## Depuración a nivel de agente
### Depuración de Amazon Bedrock AgentCore
Si ha enviado a su agente a Amazon Bedrock AgentCore, lo siguiente puede resultarle útil para investigar los problemas del agente.
**Registros del agente**
Los resultados stdout y stderr de su contenedor de agentes se capturan en Amazon CloudWatch Logs de su cuenta. Puede encontrarlos en el siguiente grupo de registros:
```
/aws/bedrock-agentcore/runtimes/--
```
Estos registros capturan los resultados del código del agente, incluidos los errores, los seguimientos de las pilas y los mensajes del SDK. Estos registros se pueden usar para investigar problemas relacionados con el código de agente, las dependencias o la conectividad con el RFT Runtime.
**Compruebe el estado del agente**
Compruebe que el tiempo de ejecución de su agente esté en buen estado:
```
aws bedrock-agentcore-control list-agent-runtimes --region us-west-2
```
Para obtener información sobre un tiempo de ejecución específico:
```
aws bedrock-agentcore-control get-agent-runtime \
--agent-runtime-id \
--region us-west-2
```
### Depuración de agentes personalizada
Si utiliza la ruta del reenviador Lambda, pueden producirse problemas en la propia función Lambda o en su agente externo. Lo siguiente puede resultar útil para investigar ambos aspectos.
**Registros del reenviador Lambda**
Los registros de ejecución de la función Lambda se capturan en Amazon CloudWatch Logs. Puede encontrarlos en el siguiente grupo de registros:
```
/aws/lambda/
```
Estos registros se pueden usar para investigar problemas relacionados con el reenvío de solicitudes, los tiempos de espera o la conectividad entre la Lambda y su agente. Consultar si:
+ Errores de invocación (Lambda no pudo comunicarse con su agente)
+ Errores de tiempo de espera (el agente tardó demasiado en responder)
+ Errores de validación (solicitud de despliegue mal formada)
**Compruebe la conectividad**
Si sus registros de Lambda muestran errores de invocación o tiempos de espera, es posible que el problema sea que Lambda no pueda comunicarse con su agente. Las siguientes comprobaciones pueden ayudar a confirmar si la conexión entre la Lambda y el agente funciona.
Health Check: confirme que su agente esté ejecutando:
```
curl -s "http://$AGENT_ENDPOINT/health"
# Expected: {"status": "ok"}
```
Invocar una prueba de Lambda: confirme que Lambda puede comunicarse con su agente:
```
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.
```
Si su Lambda se ejecuta correctamente pero el trabajo sigue fallando, es posible que los registros del agente contengan más detalles. Compruebe los registros de sus agentes para ver si hay errores relacionados con las llamadas de inferencia o los informes de recompensas.
**Registros de agentes**
Los propios registros de su agente dependen del lugar donde esté desplegado. Estos registros se pueden usar para investigar problemas relacionados con el código de su agente, realizar llamadas de inferencia al RFT Runtime o generar informes de recompensas.
Por ejemplo, si ha desplegado su agente en Amazon EKS, puede comprobar los registros de su agente con:
```
kubectl logs -l app=external-agent --tail=50
```
## Se utiliza CloudTrail para la depuración
CloudTrail los eventos de datos pueden ayudar a confirmar si las llamadas de su agente al RFT Runtime se realizan correctamente. Busque eventos con:
+ **EventName:**`Sample`,,, `SampleWithResponseStream` `CompleteRollout` `UpdateReward`
+ **recursos.tipo:** `AWS::SageMaker::Job`
Si no ve estos eventos, su agente no está llamando correctamente al RFT Runtime. Compruebe los registros y permisos de los agentes.
## Registro de llamadas a la API de con AWS CloudTrail
Amazon SageMaker AI está integrado con AWS CloudTrail un servicio que proporciona un registro de las acciones realizadas por un usuario, un rol o un AWS servicio. CloudTrail captura todas las llamadas a la API de Amazon SageMaker AI como eventos. Las llamadas capturadas incluyen llamadas desde la consola Amazon SageMaker AI y llamadas en código a las operaciones de la API Amazon SageMaker AI. Con la información recopilada por CloudTrail, puede determinar la solicitud que se realizó a Amazon SageMaker AI, la dirección IP desde la que se realizó la solicitud, cuándo se realizó y detalles adicionales.
Cada entrada de registro o evento contiene información sobre quién generó la solicitud. La información de identidad del usuario le ayuda a determinar lo siguiente:
+ Si la solicitud se realizó con las credenciales del usuario raíz o del usuario.
+ Si la solicitud se realizó en nombre de un usuario de IAM Identity Center.
+ Si la solicitud se realizó con credenciales de seguridad temporales de un rol o fue un usuario federado.
+ Si la solicitud la realizó otro AWS servicio.
CloudTrail está activa en tu AWS cuenta cuando la creas y tienes acceso automáticamente al **historial de CloudTrail eventos**. El **historial de CloudTrail eventos** proporciona un registro visible, consultable, descargable e inmutable de los últimos 90 días de los eventos de gestión registrados en una región. AWS *Para obtener más información, consulte [Uso del historial de CloudTrail eventos en la Guía del usuario](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html).AWS CloudTrail * La visualización del **historial de eventos** no conlleva ningún CloudTrail cargo.
Para tener un registro continuo de los eventos de tu AWS cuenta durante los últimos 90 días, crea un almacén de datos de eventos de senderos o [CloudTrail lagos](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake.html).
### CloudTrail senderos
Un *rastro* permite CloudTrail entregar archivos de registro a un bucket de Amazon S3. Todos los senderos creados con la consola AWS de administración son multirregionales. Puede crear una ruta de una sola región o de varias regiones mediante la CLI AWS . Se recomienda crear una ruta multirregional porque permite capturar la actividad en todas AWS las regiones de su cuenta. Si creas una ruta de una sola región, solo podrás ver los eventos registrados en la región de AWS la ruta. Para obtener más información sobre las rutas, consulta [Crear una ruta para tu AWS cuenta](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) y [Crear una ruta para una organización](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/creating-trail-organization.html) en la *Guía del AWS CloudTrail usuario*.
Puede enviar una copia de sus eventos de administración en curso a su bucket de Amazon S3 sin coste alguno CloudTrail mediante la creación de una ruta; sin embargo, hay cargos por almacenamiento en Amazon S3. Para obtener más información sobre CloudTrail los precios, consulte [AWS CloudTrailPrecios](https://aws.amazon.com/cloudtrail/pricing/). Para obtener información acerca de los precios de Amazon S3, consulte [Precios de Amazon S3](https://aws.amazon.com/s3/pricing/).
### CloudTrail Almacenes de datos de eventos en Lake
*CloudTrail Lake* le permite realizar SQL-based consultas sobre sus eventos. CloudTrail Lake convierte los eventos existentes en formato JSON basado en filas al formato [Apache ORC](https://orc.apache.org/). ORC es un formato de almacenamiento en columnas optimizado para una recuperación rápida de datos. Los eventos se agregan en *almacenes de datos de eventos*, que son recopilaciones inmutables de eventos en función de criterios que se seleccionan aplicando [selectores de eventos avanzados](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake-concepts.html#adv-event-selectors). Los selectores que se aplican a un almacén de datos de eventos controlan los eventos que perduran y están disponibles para la consulta. Para obtener más información sobre CloudTrail Lake, consulte Cómo [trabajar con AWS CloudTrail Lake](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake.html) en la Guía del *AWS CloudTrail usuario*.
CloudTrail Los almacenes de datos y las consultas sobre eventos de Lake conllevan costes. Cuando crea un almacén de datos de eventos, debe elegir la [opción de precios](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake-manage-costs.html#cloudtrail-lake-manage-costs-pricing-option) que desee utilizar para él. La opción de precios determina el costo de la incorporación y el almacenamiento de los eventos, así como el período de retención predeterminado y máximo del almacén de datos de eventos. Para obtener más información sobre los precios de CloudTrail , consulte [Precios de AWS CloudTrail](https://aws.amazon.com/cloudtrail/pricing/).
### SageMaker Eventos de datos de IA en CloudTrail
Los [eventos de datos](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events) proporcionan información sobre las operaciones de recursos realizadas en o dentro de un recurso (por ejemplo, leer o escribir en un objeto de Amazon S3). Se denominan también operaciones del plano de datos. Los eventos de datos suelen ser actividades de gran volumen. De forma predeterminada, CloudTrail no registra los eventos de datos. El **historial de CloudTrail eventos** no registra los eventos de datos.
Se aplican cargos adicionales a los eventos de datos. Para obtener más información sobre los precios de CloudTrail, consulte [Precios de AWS CloudTrail](https://aws.amazon.com/cloudtrail/pricing/).
Puede registrar eventos de datos para varios tipos de recursos de Amazon SageMaker AI mediante las operaciones de CloudTrail consola, AWS CLI o CloudTrail API. Para obtener más información sobre cómo registrar eventos de datos, consulte [Registrar eventos de datos con la consola de AWS administración](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events-console) y [Registrar eventos de datos con la interfaz de línea de AWS comandos](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#creating-data-event-selectors-with-the-AWS-CLI) en la *Guía del AWS CloudTrail usuario*.
En la siguiente tabla se enumeran los tipos de recursos de Amazon SageMaker AI para los que puede registrar eventos de datos:
| Tipo de recurso (consola) | resources.type value | API de datos registradas en CloudTrail | referencia de la API |
| --- | --- | --- | --- |
| SageMaker punto de conexión | AWS::SageMaker::Endpoint | InvokeEndpoint, InvokeEndpointAsync, InvokeEndpointWithResponseStream | [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html), [InvokeEndpointAsync](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpointAsync.html), [InvokeEndpointWithResponseStream](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpointWithResponseStream.html) |
| SageMaker trabajos | AWS::SageMaker::Job | CompleteRollout, Muestra, SampleWithResponseStream | [CompleteRollout](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_job_runtime_CompleteRollout.html), [Muestra](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_job_runtime_Sample.html), [SampleWithResponseStream](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_job_runtime_SampleWithResponseStream.html) |
**nota**
Las llamadas a la `SampleWithResponseStream` API `InvokeEndpoint` `InvokeEndpointAsync``Sample`,, y no registran los parámetros de la solicitud.
Puede configurar selectores de eventos avanzados para filtrar según los campos `eventName`, `readOnly` y `resources.ARN` y así registrar solo los eventos que son importantes para usted. Para obtener más información acerca de estos campos, consulte [AdvancedFieldSelector](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_AdvancedFieldSelector.html) en la *Referencia de la API de AWS CloudTrail *.
**Ejemplo: Registra eventos de datos para un SageMaker punto final y un trabajo**
El siguiente ejemplo muestra cómo utilizar el comando AWS CLI [put-event-selectors](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/put-event-selectors.html) para añadir selectores de eventos avanzados:
```
[
{
"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"] }
]
}
]
```
A continuación, ejecute:
```
aws cloudtrail put-event-selectors \
--trail-name your-trail-name \
--advanced-event-selectors=file://advanced-event-selectors.json
```
### SageMaker Eventos de gestión de IA en CloudTrail
[Los eventos de administración](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html#logging-management-events) proporcionan información sobre las operaciones de administración que se realizan en los recursos de su AWS cuenta. Se denominan también operaciones del plano de control. De forma predeterminada, CloudTrail registra los eventos de administración.
Amazon SageMaker AI registra todas las operaciones del plano de control de Amazon SageMaker AI como eventos de gestión. Para obtener una lista de las operaciones del plano de control de Amazon SageMaker AI en las que Amazon SageMaker AI inicia sesión CloudTrail, consulte la [referencia de la API de Amazon SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/APIReference).
### CloudTrail ejemplos de eventos
Para obtener información sobre el contenido de los CloudTrail registros, consulte el [contenido de los CloudTrail registros](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-record-contents.html) en la *Guía del AWS CloudTrail usuario*.
## Modele paquetes y puntos de control
### Descripción general de
**Durante el entrenamiento de RL con varias vueltas, la plataforma guarda periódicamente los parámetros aprendidos del modelo como puntos de control.** Estos puntos de control se almacenan como paquetes de **SageMaker modelos dentro de los grupos de paquetes** **de modelos, lo que permite el control de versiones, el seguimiento del** linaje y la continuidad entre trabajos.
### Conceptos clave
**Paquete modelo**
Un Model Package es un artefacto versionado e inmutable en la SageMaker IA que contiene pesos de modelos entrenados en un momento específico. Cada punto de control producido durante el entrenamiento se almacena como un Model Package. Un Model Package incluye:
+ Un ARN (por ejemplo,) `arn:aws:sagemaker:us-west-2:123456789012:model-package/my-group/5`
+ Una ubicación S3 que contiene los archivos del modelo
+ Metadatos sobre cuándo se creó y a partir de qué paso de entrenamiento
**Model Package Group**
Un grupo de paquetes de modelos es un contenedor que contiene varias versiones de paquetes de modelos. Multi-turn RL usa dos grupos separados:
| Group | Finalidad | Contenido |
| --- | --- | --- |
| Grupo de paquetes de modelos de salida | Puntos de control finales del modelo entrenado | HuggingFace-compatible Los pesos del adaptador LoRa son adecuados para la inferencia y el entrenamiento continuo |
| Grupo de paquetes modelo de punto de control intermedio | Estado de entrenamiento reanudable | Estado de optimización completo y pesos del adaptador para reanudar el entrenamiento interrumpido |
Al crear un trabajo, debe especificar ambas opciones:
```
{
"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"
}
}
```
### Tipos de puntos de control
**Punto de control reanudable (estado completo)**
+ **Contenido: los** pesos del adaptador LoRa, los estados del optimizador y los metadatos de los pasos de entrenamiento (por rango de GPU)
+ **Almacenado en**: Intermediate Checkpoint Model Package Group
+ **Propósito**: Reanudar el entrenamiento desde el punto exacto en que se interrumpió
+ **Formato: formato** interno (no se puede utilizar directamente para hacer inferencias)
+ **Cuándo se crea**: cada paso
+ **Caso de uso**: resiliencia automática o formación continua explícita
**Punto de control modelo (solo pesas)**
+ **Contenido**: el adaptador HuggingFace-compatible LoRa pesa en formato SafeTensors
+ **Almacenado en**: Output Model Package Group
+ **Propósito**: inferencia, despliegue o formación continua
+ **Formato: formato** de HuggingFace adaptador estándar (`adapter_config.json`\+`adapter_model.safetensors`)
+ **Cuándo se crea**: en cada paso, al finalizar el trabajo y cuando se detiene un trabajo
+ **Caso de uso**: Implemente el modelo ajustado para realizar inferencias o utilícelo como entrada para un nuevo trabajo de formación
### Reanudar el entrenamiento interrumpido
Si un trabajo de formación fracasa o se interrumpe a mitad del entrenamiento, puedes empezar un nuevo trabajo que se reanude desde el punto exacto en el que lo dejó el anterior. La plataforma carga todo el estado del entrenamiento (pesas, optimizador y contador de pasos) desde un punto de control que se puede reanudar.
Para reanudar, especifique un punto de control reanudable (del Intermediate Checkpoint Model Package Group) como: `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"
}
}
```
**Requisitos:**
+ `InputModelPackageArn`Debe apuntar a un punto de control reanudable (uno que figure `IsCheckpoint=true` en sus metadatos del Model Package)
+ El nuevo trabajo debe usar el mismo modelo base
+ El nuevo trabajo debe usar la misma configuración LoRa (rango, alfa)
+ El nuevo trabajo debe usar los mismos hiperparámetros (tasa de aprendizaje, tamaño del lote, etc.)
+ El nuevo trabajo debe usar el mismo conjunto de datos
### Entrenamiento iterativo (entrenamiento continuo)
El entrenamiento iterativo te permite basarte en un modelo previamente entrenado con nuevos hiperparámetros, un conjunto de datos diferente o una configuración de entrenamiento diferente. A diferencia de la reanudación, esto inicia una nueva sesión de entrenamiento que se inicia a partir de las pesas LoRa entrenadas, pero con un nuevo estado de optimización.
Para realizar un entrenamiento iterativo, especifique un punto de control del modelo (del Output Model Package Group) como: `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"
}
}
```
**Qué puede cambiar entre iteraciones:**
+ Hiperparámetros (tasa de aprendizaje, tamaño del lote, max\_steps, group\_size, etc.)
+ Conjunto de datos (diferentes indicaciones, diferente distribución de datos)
+ Función de recompensa (lambda de recompensa diferente)
+ Configuración del agente
**Qué debe permanecer igual:**
+ El modelo base (el adaptador LoRa es específico de la arquitectura del modelo base)
**Casos de uso típicos:**
+ Entrénese primero en los problemas fáciles y luego continúe con los problemas más difíciles (aprendizaje curricular)
+ Entrena con una función de recompensa sencilla y, después, perfecciona con una más matizada
+ Aumente el tamaño del lote o ajuste la velocidad de aprendizaje después de observar la dinámica inicial del entrenamiento
### Ciclo de vida de los puntos
```
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
```
Cuando un trabajo se completa correctamente: los pesos del modelo final se guardan como un paquete de modelos en el grupo de paquetes de modelos de salida. El `OutputModelPackageArn` campo del registro de trabajo contiene el ARN del modelo final.
Cuando un trabajo falla o se detiene: el último punto de control intermedio pasa a ser el Output Model Package Group (best effort).
### Mejores prácticas para los puntos de control
+ **Supervise la creación de puntos de control**: utilícelos `DescribeJob` para realizar un seguimiento `ResumableCheckpoint` y controlarlos durante el `ModelCheckpoint` entrenamiento
+ **Para trabajos de larga duración, utiliza la formación iterativa**: si un trabajo con muchos pasos puede fallar, planifica reanudarlo desde los puntos de control en lugar de volver a empezar desde cero