# Realice evaluaciones con el contenedor Inspect AI
<a name="nova-eval-inspect-ai-container"></a>

El contenedor SageMaker Inspect AI ejecuta evaluaciones de modelos de lenguaje de gran tamaño (LLM) en los trabajos de entrenamiento de SageMaker. Utiliza [Inspect AI](https://inspect.ai-safety-institute.org.uk/) a fin de proporcionar un proceso de evaluación estandarizado para los modelos implementados en los puntos de conexión de inferencia de SageMaker o en Amazon Bedrock, incluidos los modelos Amazon Nova 1.0 (Micro, Lite, Pro) y 2.0 (Lite 2).

Los [enfoques de evaluación](https://docs.aws.amazon.com//nova/latest/nova2-userguide/nova-model-evaluation.html) anteriores (basados en [lighteval](https://github.com/huggingface/lighteval)) combinaban estrechamente la lógica de evaluación y la inferencia sin conexión, lo que limitaba la flexibilidad de la forma en que se podían distribuir y probar los modelos. El contenedor Inspect AI separa por completo la lógica de evaluación de la inferencia.

## Descripción general
<a name="nova-eval-container-overview"></a>

También ofrece otras ventajas como las siguientes:
+ **Cree sus propios puntos de referencia**. Escriba las tareas de evaluación en el formato de Inspect AI y, luego, incorpore las tareas de evaluación específicas del dominio sin tener que depender de un equipo centralizado que lleve a cabo esta acción.
+ **Realice evaluaciones con distintas opciones de inferencia**. El contenedor funciona con SageMaker Inference (punto de conexión existente o creación sobre la marcha), Amazon Bedrock y más backends de inferencia entrantes.
+ **Realice iteraciones más rápido**. Pase del desarrollo de puntos de referencia a la evaluación de la producción sin efectuar cambios en la infraestructura. La incorporación de nuevos puntos de referencia, que antes tardaba días, ahora se lleva a cabo en cuestión de minutos.
+ **Realice ejecuciones a escala**. Encadene varios puntos de referencia en un solo trabajo, combine los puntos de referencia estándar de la biblioteca inspect-evals con sus propias tareas personalizadas en el mismo trabajo.
+ **Cuente con un punto de partida para todas las técnicas de entrenamiento**. Independientemente de que el modelo se haya refinado con SFT (SMTJ, SMHP), CPT (SMHP) o RFT (SMTJ, SMHP), el contenedor lo evalúa a través de la misma interfaz. También se pueden evaluar los puntos de control de la mitad del entrenamiento que se guardaron en pasos específicos (por ejemplo, en el paso 500 o el paso 1000) dirigiendo `model_s3_uri` a la ruta del punto de control.

### Funcionamiento
<a name="nova-eval-container-how-it-works"></a>

Debe proporcionar dos entradas al contenedor:

1. Un archivo de configuración YAML (fórmula) que define el proveedor de inferencias, los puntos de referencia y los parámetros de evaluación

1. Los archivos de referencia (scripts de Python con el decorador `@task`) cargados en Amazon S3

El contenedor se encarga de la administración de los puntos de conexión, la ejecución de la evaluación y la recopilación de los resultados. Cuando se completa el trabajo de entrenamiento, los resultados se escriben en la ubicación de salida de S3 que se haya especificado.

## Imagen de contenedor
<a name="nova-eval-container-images"></a>

En la siguiente tabla, se enumeran los URI de imagen de contenedor Inspect AI por región de AWS.


| Región | ID de imagen de contenedor | 
| --- | --- | 
| us-east-1 | 763104351884.dkr.ecr.us-east-1.amazonaws.com/sagemaker-inspect-ai:latest | 
| us-west-2 | 763104351884.dkr.ecr.us-west-2.amazonaws.com/sagemaker-inspect-ai:latest | 
| eu-west-2 | 763104351884.dkr.ecr.eu-west-2.amazonaws.com/sagemaker-inspect-ai:latest | 

## Requisitos previos
<a name="nova-eval-container-prerequisites"></a>

Antes de empezar, asegúrese de disponer de los siguientes recursos y accesos.


| Requisito | Descripción | 
| --- | --- | 
| Cuenta de AWS con acceso a SageMaker | Una Cuenta de AWS activa con permisos para crear trabajos de entrenamiento de SageMaker | 
| Bucket de S3 | Un bucket para almacenar las fórmulas de evaluaciones, los archivos de referencia y los resultados de salida | 
| Rol de ejecución de IAM | Un rol que SageMaker puede asumir para acceder a sus recursos | 
| Punto de conexión de inferencia de SageMaker o acceso de Amazon Bedrock | Un punto de conexión del modelo implementado o acceso de Amazon Bedrock al modelo que desea evaluar | 
| AWS CLI o SageMaker Python SDK | Herramientas para enviar los trabajos de entrenamiento y gestionar los recursos | 
| Reserva de capacidad (modelos de gran tamaño) | Para los modelos que requieren instancias aceleradas (como p5 para Nova Lite 2), póngase en contacto con AWS Support y reserve capacidad para SageMaker Inference o Amazon Bedrock | 

## Paso 1: Configure los permisos de IAM
<a name="nova-eval-container-step1"></a>

El trabajo de entrenamiento de SageMaker se lleva a cabo mediante un rol de ejecución que usted proporciona, el cual necesita permisos para leer los puntos de referencia de S3, escribir los resultados, invocar el punto de conexión de inferencia y escribir los registros de CloudWatch.

**1.1 Cree la política de confianza**

Guarde lo siguiente como `trust_policy.json`:

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "sagemaker.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```

**1.2 Cree el rol**

```
aws iam create-role \
  --role-name InspectLensEvalRole \
  --assume-role-policy-document file://trust_policy.json
```

**1.3 Asocie la política de permisos**

Guarde lo siguiente como `eval_policy.json` y sustituya todos los valores de los marcadores de posición (`REGION`, `ACCOUNT_ID`, nombres de buckets) por sus valores:

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "S3ReadBenchmarkData",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::YOUR_BENCHMARK_BUCKET",
        "arn:aws:s3:::YOUR_BENCHMARK_BUCKET/*"
      ]
    },
    {
      "Sid": "S3WriteResults",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::YOUR_RESULTS_BUCKET",
        "arn:aws:s3:::YOUR_RESULTS_BUCKET/*"
      ]
    },
    {
      "Sid": "SageMakerInvokeExistingEndpoint",
      "Effect": "Allow",
      "Action": [
        "sagemaker:InvokeEndpoint",
        "sagemaker:InvokeEndpointWithResponseStream",
        "sagemaker:DescribeEndpoint"
      ],
      "Resource": "arn:aws:sagemaker:REGION:ACCOUNT_ID:endpoint/*"
    },
    {
      "Sid": "BedrockInference",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": [
        "arn:aws:bedrock:REGION::foundation-model/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:inference-profile/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:provisioned-model/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:custom-model/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:imported-model/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:custom-model-deployment/*"
      ]
    },
    {
      "Sid": "BedrockCustomModelAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:GetCustomModel",
        "bedrock:GetImportedModel",
        "bedrock:GetProvisionedModelThroughput",
        "bedrock:GetCustomModelDeployment",
        "bedrock:GetInferenceProfile"
      ],
      "Resource": [
        "arn:aws:bedrock:REGION:ACCOUNT_ID:custom-model/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:imported-model/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:provisioned-model/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:custom-model-deployment/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:inference-profile/*"
      ]
    },
    {
      "Sid": "SageMakerCreateEndpointLifecycle",
      "Effect": "Allow",
      "Action": [
        "sagemaker:CreateModel",
        "sagemaker:DescribeModel",
        "sagemaker:DeleteModel",
        "sagemaker:CreateEndpointConfig",
        "sagemaker:DescribeEndpointConfig",
        "sagemaker:DeleteEndpointConfig",
        "sagemaker:CreateEndpoint",
        "sagemaker:DescribeEndpoint",
        "sagemaker:DeleteEndpoint",
        "sagemaker:InvokeEndpoint",
        "sagemaker:InvokeEndpointWithResponseStream"
      ],
      "Resource": [
        "arn:aws:sagemaker:REGION:ACCOUNT_ID:model/inspectlens-*",
        "arn:aws:sagemaker:REGION:ACCOUNT_ID:endpoint/inspectlens-*",
        "arn:aws:sagemaker:REGION:ACCOUNT_ID:endpoint-config/inspectlens-*"
      ]
    },
    {
      "Sid": "ECRAuth",
      "Effect": "Allow",
      "Action": "ecr:GetAuthorizationToken",
      "Resource": "*"
    },
    {
      "Sid": "PassRoleToSageMaker",
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::ACCOUNT_ID:role/InspectLensEvalRole",
      "Condition": {
        "StringEquals": {
          "iam:PassedToService": "sagemaker.amazonaws.com"
        }
      }
    },
    {
      "Sid": "VPCNetworkingForEndpoint",
      "Effect": "Allow",
      "Action": [
        "ec2:CreateNetworkInterface",
        "ec2:CreateNetworkInterfacePermission",
        "ec2:DeleteNetworkInterface",
        "ec2:DeleteNetworkInterfacePermission",
        "ec2:DescribeNetworkInterfaces",
        "ec2:DescribeVpcs",
        "ec2:DescribeDhcpOptions",
        "ec2:DescribeSubnets",
        "ec2:DescribeSecurityGroups"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchLogs",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents",
        "logs:DescribeLogStreams"
      ],
      "Resource": [
        "arn:aws:logs:REGION:ACCOUNT_ID:log-group:/aws/sagemaker/TrainingJobs:*",
        "arn:aws:logs:REGION:ACCOUNT_ID:log-group:/aws/sagemaker/Endpoints/*"
      ]
    },
    {
      "Sid": "MLflowTrackingServer",
      "Effect": "Allow",
      "Action": [
        "sagemaker:DescribeMlflowTrackingServer",
        "sagemaker:CreatePresignedMlflowTrackingServerUrl"
      ],
      "Resource": "arn:aws:sagemaker:REGION:ACCOUNT_ID:mlflow-tracking-server/*"
    },
    {
      "Sid": "MLflowTrackingOperations",
      "Effect": "Allow",
      "Action": [
        "sagemaker-mlflow:AccessUI",
        "sagemaker-mlflow:CreateExperiment",
        "sagemaker-mlflow:GetExperiment",
        "sagemaker-mlflow:GetExperimentByName",
        "sagemaker-mlflow:SearchExperiments",
        "sagemaker-mlflow:CreateRun",
        "sagemaker-mlflow:GetRun",
        "sagemaker-mlflow:UpdateRun",
        "sagemaker-mlflow:SearchRuns",
        "sagemaker-mlflow:LogMetric",
        "sagemaker-mlflow:LogParam",
        "sagemaker-mlflow:LogBatch",
        "sagemaker-mlflow:SetTag",
        "sagemaker-mlflow:LogArtifact",
        "sagemaker-mlflow:ListArtifacts"
      ],
      "Resource": "arn:aws:sagemaker:REGION:ACCOUNT_ID:mlflow-tracking-server/*"
    },
    {
      "Sid": "KMSForVolumeEncryption",
      "Effect": "Allow",
      "Action": [
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:GenerateDataKey",
        "kms:CreateGrant",
        "kms:DescribeKey"
      ],
      "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:key/*"
    }
  ]
}
```

Asocie la política al rol:

```
aws iam put-role-policy \
  --role-name InspectLensEvalRole \
  --policy-name InspectLensEvalPolicy \
  --policy-document file://eval_policy.json
```

## Paso 2: Escriba su fórmula de evaluación
<a name="nova-eval-container-step2"></a>

La fórmula de evaluación es un archivo de configuración YAML que define cómo el contenedor ejecuta sus evaluaciones. La fórmula especifica el proveedor de inferencias, los puntos de referencia, los parámetros de evaluación y la configuración de salida.

Para ver ejemplos integrales, consulte los siguientes cuadernos:
+ [Evaluar un punto de conexión de SageMaker existente](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/inspect_eval_container/eval_sagemaker_endpoint.ipynb)
+ [Evaluar con un punto de conexión gestionado](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/inspect_eval_container/eval_managed_endpoint.ipynb)
+ [Evaluar un modelo de Amazon Bedrock](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/inspect_eval_container/eval_bedrock_model.ipynb)

**Opción A: Evalúe un punto de conexión de SageMaker existente**

Utilice esta opción si ya tiene un modelo implementado en un punto de conexión de inferencia de SageMaker.

```
inference_provider:
  sagemaker_endpoint:
    endpoint_name: "my-existing-endpoint"
    region: "us-east-1"

benchmarks:
  s3_path: "s3://your-bucket/benchmarks/my_benchmarks/"
  tasks:
    - name: mmlu

eval:
  max_connections: 10
  max_retries: 100
  timeout: 600

output:
  s3_path: "s3://your-bucket/eval-results/"
```

**Opción B: Cree un punto de conexión, evalúelo y depúrelo**

Utilice esta opción para que el contenedor implemente un modelo base o de ajuste fino de Amazon Nova, ejecute evaluaciones y elimine el punto de conexión automáticamente. Este es el enfoque recomendado para las evaluaciones de una sola vez. Recupere el contenedor de inferencias de SageMaker más reciente de la documentación de [imágenes de contenedor de SageMaker Inference de Amazon Nova](https://docs.aws.amazon.com//nova/latest/userguide/nova-model-sagemaker-inference.html#nova-sagemaker-inference-container-images).

```
inference_provider:
  sagemaker_endpoint:
    endpoint_name: null                 # null = create new endpoint
    model_s3_uri: "s3://your-bucket/models/nova-micro/"
    inference_image_uri: "708977205387.dkr.ecr.us-east-1.amazonaws.com/nova-inference-repo:SM-Inference-latest"
    instance_type: "ml.p5.48xlarge"
    instance_count: 1
    execution_role_arn: "arn:aws:iam::ACCOUNT_ID:role/InspectLensEvalRole"
    region: "us-east-1"
    context_length: "16000"
    max_concurrency: "32"
    cleanup_endpoint: true              # Auto-delete after eval

benchmarks:
  s3_path: "s3://your-bucket/benchmarks/my_benchmarks/"
  tasks:
    - name: mmlu_pro
    - name: arc_c
    - name: boolq

eval:
  fail_on_error: false
  decoding:
    temperature: 0.0
    top_p: 1.0
    top_k: -1
    max_tokens: 16000
    reasoning_effort: null
  max_connections: 16
  max_retries: 100
  timeout: 600
  extra_args:
    - "-M"
    - "completion_mode=True"
    - "--logprobs"
    - "--top-logprobs"
    - "5"

output:
  s3_path: "s3://your-bucket/eval-results/"
```

**Nota sobre `model_s3_uri`:**
+ **Modelos de disponibilidad general de Amazon Nova (puntos de control básicos)**: Por ejemplo, `s3://escrow-nova-model-708977205387-us-east-1/nova-lite-2/prod/`. SageMaker administra el acceso automáticamente, sin necesidad de contar con permisos adicionales de S3.
+ **Modelos personalizados de Amazon Nova (puntos de control posteriores al entrenamiento)**: `s3://customer-escrow-ACCOUNT_ID-SUFFIX/YOUR_RUN_NAME/outputs/checkpoints/step_N/`. Esta es la ruta del bucket de depósito a partir del resultado del trabajo de entrenamiento.

**Opción C: Realiza evaluaciones a través de Amazon Bedrock**

Use esta opción para evaluar un modelo disponible a través de Amazon Bedrock sin administrar un punto de conexión.

```
inference_provider:
  bedrock:
    model_id: amazon.nova-pro-v1:0
    region: us-east-1

benchmarks:
  - name: mmlu
    path: benchmarks/mmlu_pro.py
    limit: 100

eval:
  fail_on_error: false
  decoding:
    temperature: 0.0
    top_p: 1.0
    top_k: -1
    max_tokens: 8192
    reasoning_effort: null
  max_connections: 10
  max_retries: 50
  timeout: 600
  extra_args:
    - "--display"
    - "plain"

output:
  s3_path: s3://your-bucket/eval/output/
```

**Configuración de los puntos de referencia**

En la sección `benchmarks`, se definen las tareas de evaluación que se deben ejecutar. Puede encadenar varios puntos de referencia en un solo trabajo.


| Campo | Obligatorio | Predeterminado | Descripción | 
| --- | --- | --- | --- | 
| name | Sí | — | Nombre descriptivo para la ejecución del punto de referencia. | 
| path | Sí | — | Ruta relativa al archivo Python de referencia en su directorio de puntos de referencia de S3. | 
| limit | No | Ninguno (todas las muestras) | Número máximo de muestras para evaluar. Se utiliza para realizar pruebas antes de realizar ejecuciones completas. | 
| epochs | No | 1 | Número de veces que se debe repetir la evaluación para determinar su significancia estadística. | 
| task\_args | No | — | Pares clave-valor transferidos como argumentos a la función de tarea de referencia. | 

**Configuración de las evaluaciones**

En la sección `eval`, se controla la forma en que el contenedor ejecuta las evaluaciones.


| Parámetro | Obligatorio | Predeterminado | Descripción | 
| --- | --- | --- | --- | 
| fail\_on\_error | No | false | Detiene la evaluación si alguna muestra falla. Configúrelo en true para una validación estricta. | 
| max\_connections | No | 10 | Número de solicitudes paralelas al punto de conexión de inferencia. | 
| max\_retries | No | 3 | Número de reintentos para solicitudes de inferencia fallidas. | 
| timeout | No | 600 | Tiempo de espera de la solicitud en segundos para cada llamada de inferencia. | 
| extra\_args | No | — | Pares clave-valor adicionales transferidos directamente al comando de evaluación de Inspect AI. | 

**Parámetros de decodificación**

Configure los parámetros de decodificación del modelo en la sección `eval.decoding`:


| Parámetro | Obligatorio | Predeterminado | Descripción | 
| --- | --- | --- | --- | 
| temperature | No | 0.0 | Controla la aleatoriedad en la generación. Utilice 0.0 para obtener resultados de referencia deterministas y reproducibles. | 
| top\_p | No | 1.0 | Umbral de muestreo del núcleo. 1.0 significa que no hay ninguna restricción. | 
| top\_k | No | -1 | Limita la elección de palabras a una cierta cantidad (K) de tokens más probables. -1 desactiva este filtro. | 
| max\_tokens | No | 8192 | Número máximo de tokens que se generarán por respuesta. Incremento para los puntos de referencia que requieren cadenas de razonamiento largas. | 
| reasoning\_effort | No | null | Controla la profundidad de razonamiento de los modelos que lo respaldan (por ejemplo, los modelos de Amazon Nova con pensamiento extendido). Opciones: low, high o null para deshabilitarlo. | 

**Configuración de la salida**

En la sección `output`, se define dónde y cómo se almacenan los resultados de la evaluación.


| Campo | Obligatorio | Predeterminado | Descripción | 
| --- | --- | --- | --- | 
| s3\_path | Sí | — | URI de S3 donde se escriben los resultados de la evaluación. | 
| output\_format | No | eval | Formato de los archivos de resultados. Consulte la siguiente tabla para ver las opciones. | 

Se encuentran disponibles los siguientes formatos de salida:


| Formato | Descripción | 
| --- | --- | 
| eval | Formato propio de Inspect AI. Compatible con inspect view para realizar análisis interactivos. | 
| csv | Valores separados por comas. Adecuado para el análisis de hojas de cálculo y los canales de datos. | 
| jsonl | Formato JSON Lines. Un objeto JSON por línea para el procesamiento de flujos. | 
| json | Formato JSON estándar. Resultados completos en un solo archivo estructurado. | 

**Configuración de MLflow**

Si lo desea, puede registrar las métricas de evaluación en un servidor de seguimiento de MLflow. Agregue la sección `tracking` a su fórmula:

```
tracking:
  mlflow_tracking_arn: null       # ARN of SageMaker MLflow tracking server
  mlflow_experiment_name: "inspectlens" # experiment name
  mlflow_tracing: true          # log full request/response traces
  mlflow_log_artifacts: true       # upload .eval files to MLflow
```


| Campo | Obligatorio | Predeterminado | Descripción | 
| --- | --- | --- | --- | 
| mlflow\_tracking\_arn | No | null | ARN del servidor de seguimiento de MLflow de SageMaker. Al configurarlo, se habilita el registro de MLflow. Omítalo o configúrelo en null para deshabilitarlo. | 
| mlflow\_experiment\_name | No | inspectlens | Nombre del experimento de MLflow con el que se registrarán las ejecuciones. | 
| mlflow\_tracing | No | true | Cuando está establecido en true, se registra el seguimiento completo de las solicitudes y respuestas de cada muestra. | 
| mlflow\_log\_artifacts | No | true | Cuando está establecido en true, se cargan los archivos de registro .eval como artefactos de MLflow. | 

**Referencia completa de fórmulas**

En el siguiente ejemplo, se muestra una fórmula completa con todas las opciones de configuración disponibles:

```
inference_provider:
  sagemaker_endpoint:
    endpoint_name: my-nova-endpoint
    model_s3_uri: s3://your-bucket/models/my-model/
    inference_image_uri: "708977205387.dkr.ecr.us-east-1.amazonaws.com/nova-inference-repo:SM-Inference-latest"
    instance_type: ml.g5.12xlarge
    cleanup_endpoint: true
    region: us-west-2

benchmarks:
  - name: mmlu
    path: benchmarks/mmlu_pro.py
    limit: 100
    epochs: 3
    task_args:
      subject: math
  - name: truthfulqa
    path: benchmarks/truthfulqa.py
    limit: 50

eval:
  fail_on_error: false
  decoding:
    temperature: 0.0
    top_p: 1.0
    top_k: -1
    max_tokens: 8192
    reasoning_effort: null
  max_connections: 256
  max_retries: 50
  timeout: 600
  extra_args:
    - "--display"
    - "plain"

output:
  s3_path: s3://your-bucket/eval/output/
  output_format: eval

tracking:
  mlflow_tracking_arn: "arn:aws:sagemaker:us-west-2:123456789012:mlflow-tracking-server/my-server"
  mlflow_experiment_name: "inspectlens"
  mlflow_tracing: true
  mlflow_log_artifacts: true
```

## Paso 3: Prepare archivos de referencia
<a name="nova-eval-container-step3"></a>

Los puntos de referencia son archivos de Python que utilizan el decorador `@task` de Inspect AI para definir las tareas de evaluación. El [repositorio inspect-evals](https://github.com/UKGovernmentBEIS/inspect_evals) proporciona más de 128 puntos de referencia listos para usar. Si lo desea, puede escribir los suyos propios.

**Ejemplo de punto de referencia**

En el siguiente ejemplo, se muestra un punto de referencia mínimo que evalúa el rendimiento de opción múltiple en un conjunto de datos de HuggingFace:

```
from inspect_ai import task, Task
from inspect_ai.dataset import hf_dataset
from inspect_ai.scorer import choice
from inspect_ai.solver import multiple_choice


@task
def my_benchmark():
    return Task(
        dataset=hf_dataset(
            path="cais/mmlu",
            name="abstract_algebra",
            split="test",
        ),
        solver=multiple_choice(),
        scorer=choice(),
    )
```

**Dependencias**

Si el punto de referencia necesita dependencias adicionales, incluya `pyproject.toml` o `requirements.txt` en el mismo directorio de S3:

```
[project]
name = "my-benchmark"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "datasets>=2.14.0",
]
```

**Paquetes preinstalados**

El contenedor incluye los siguientes paquetes. No es necesario que los enumere en su `pyproject.toml`.


| Paquete | Versión | 
| --- | --- | 
| Python | 3.12 | 
| inspect-ai | 0.3.220 | 
| boto3 | 1.40.61 | 
| aioboto3 | 15.5.0 | 
| openai | 2.36.0 | 
| mlflow | 3.12.0 | 
| pyyaml | 6.0.3 | 

**Selección de tareas**

El campo `tasks` de la fórmula controla cuáles tareas de un archivo de referencia se van a ejecutar.


| Configuración | Ejemplo | Comportamiento | 
| --- | --- | --- | 
| Vacío tasks | tasks: [] | Ejecuta todas las tareas definidas en el archivo de referencia. | 
| Filtro de nombres | tasks: ["algebra"] | Ejecuta tareas cuyos nombres contienen la subcadena “algebra”. | 
| limit | limit: 50 | Limita el número de muestras evaluadas por tarea. | 
| epochs | epochs: 3 | Repite la evaluación varias veces para medir la varianza. | 

## Paso 4: Prepare su estructura de S3
<a name="nova-eval-container-step4"></a>

La siguiente estructura es una recomendación para mantener organizadas las configuraciones, los puntos de referencia y los resultados. Puede dirigir el contenedor a cualquier ubicación de S3; la estructura en sí no es necesaria.

```
s3://your-bucket/
├── config/
│   └── inspect_config.yaml       # Your eval recipe
├── benchmarks/
│   └── my_benchmarks/            # Your benchmark Python files
│       ├── pyproject.toml        # Optional: benchmark dependencies
│       ├── my_task.py            # @task decorated functions
│       └── _helpers.py           # Shared utilities
└── output/                       # Results written here
```

Cargue sus archivos a S3.

```
# Upload benchmark files
aws s3 cp my_benchmarks/ s3://your-bucket/benchmarks/my_benchmarks/ --recursive

# Upload your eval recipe
aws s3 cp inspect_config.yaml s3://your-bucket/config/inspect_config.yaml
```

## Paso 5: Envíe el trabajo de entrenamiento
<a name="nova-eval-container-step5"></a>

Envíe un trabajo de entrenamiento de SageMaker para ejecutar la evaluación. Puede usar la AWS CLI o el SageMaker Python SDK.

**Opción A: AWS CLI**

```
aws sagemaker create-training-job \
    --training-job-name inspect-eval-$(date +%Y%m%d-%H%M%S) \
    --algorithm-specification \
        TrainingImage=763104351884.dkr.ecr.us-east-1.amazonaws.com/sagemaker-inspect-ai:latest,TrainingInputMode=File \
    --role-arn arn:aws:iam::123456789012:role/SageMakerInspectAIRole \
    --resource-config \
        InstanceType=ml.m5.large,InstanceCount=1,VolumeSizeInGB=30 \
    --stopping-condition MaxRuntimeInSeconds=86400 \
    --input-data-config '[
        {
            "ChannelName": "config",
            "DataSource": {
                "S3DataSource": {
                    "S3DataType": "S3Prefix",
                    "S3Uri": "s3://your-bucket/eval/config/",
                    "S3DataDistributionType": "FullyReplicated"
                }
            }
        }
    ]' \
    --output-data-config S3OutputPath=s3://your-bucket/eval/output/ \
    --region us-west-2
```

**Opción B: SageMaker Python SDK V3**

```
from sagemaker.train import ModelTrainer
from sagemaker.train.configs import InputData, Compute
from sagemaker.core.shapes.shapes import StoppingCondition, OutputDataConfig

trainer = ModelTrainer(
    training_image="763104351884.dkr.ecr.us-east-1.amazonaws.com/sagemaker-inspect-ai:latest",
    compute=Compute(
        instance_type="ml.m5.large",
        instance_count=1,
        volume_size_in_gb=30,
    ),
    output_data_config=OutputDataConfig(
        s3_output_path="s3://your-bucket/eval/output/"
    ),
    role="arn:aws:iam::123456789012:role/SageMakerInspectAIRole",
    stopping_condition=StoppingCondition(max_runtime_in_seconds=86400),
)

trainer.train(
    input_data_config=[
        InputData(
            channel_name="config",
            data_source="s3://your-bucket/eval/config/",
        )
    ]
)
```

**Parámetros clave**


| Parámetro | Valor | Descripción | 
| --- | --- | --- | 
| TrainingImage | 763104351884.dkr.ecr.us-east-1.amazonaws.com/sagemaker-inspect-ai:latest | La imagen del contenedor Inspect AI | 
| InstanceType | ml.m5.large | Tipo de instancia de Orchestrator (no la instancia de inferencia) | 
| VolumeSizeInGB | 30 | Almacenamiento para datos y registros de referencia | 
| MaxRuntimeInSeconds | 86400 | Duración máxima del trabajo (24 horas) | 
| ChannelName | config | Canal de entrada que contiene sus archivos de puntos de referencia y fórmulas | 

**Guía sobre el tipo de instancia de Orchestrator**

La instancia del trabajo de entrenamiento ejecuta la lógica de orquestación de la evaluación, no la inferencia del modelo. Elija un tipo de instancia en función de la carga de trabajo de evaluación.


| Tipo de instancia | Caso de uso | Directrices | 
| --- | --- | --- | 
| ml.m5.large | Tipo predeterminado recomendado | Adecuado para la mayoría de las cargas de trabajo de evaluación con un paralelismo moderado | 
| ml.m5.4xlarge | Amplios conjuntos de puntos de referencia | Recomendado para ejecutar muchos puntos de referencia con valores max\_connections altos | 
| ml.c5.large | Enfoque en los costos | Alternativa de menor costo para evaluaciones sencillas con bajo paralelismo | 

**Variables de entorno**

Puede transferir variables de entorno al contenedor para su autenticación o configuración. Agregue el parámetro `--environment` al comando AWS CLI:

```
aws sagemaker create-training-job \
    ...
    --environment '{
        "HF_TOKEN": "hf_your_token_here",
        "HF_HUB_DOWNLOAD_TIMEOUT": "300"
    }'
```

## Paso 6: Monitoree el trabajo
<a name="nova-eval-container-step6"></a>

Una vez enviado el trabajo de entrenamiento, puede supervisar su progreso a través de la AWS CLI o de CloudWatch Logs.

**Comprobar el estado del trabajo**

```
aws sagemaker describe-training-job \
    --training-job-name your-job-name \
    --query "TrainingJobStatus" \
    --output text
```

**Registros de flujos**

```
aws logs tail /aws/sagemaker/TrainingJobs \
    --log-stream-name-prefix your-job-name \
    --follow
```

**Qué esperar de los registros**

En los registros de contenedores se muestran los avances en las siguientes etapas:

1. **Inicio**: Inicialización del contenedor y validación de la configuración.

1. **Descarga de puntos de referencia**: Descarga de los archivos de referencia e instalación de las dependencias.

1. **Configuración del punto de conexión**: Creación del punto de conexión de inferencia o conexión a él.

1. **Evaluación**: Ejecución de las tareas de puntos de referencia con indicadores de progreso.

1. **Carga de resultados**: Escritura de los resultados en S3 y, opcionalmente, su registro en MLflow.

1. **Depuración**: Eliminación de los puntos de conexión temporales si `cleanup_endpoint: true`.

**Plazos estimados**


| Etapa | Duración estimada | 
| --- | --- | 
| Inicio de contenedores | Entre 2 y 5 minutos | 
| Creación del punto de conexión (si corresponde) | Entre 15 y 30 minutos | 
| Evaluación | Varía según el tamaño del punto de referencia y la latencia del modelo | 
| Eliminación | Entre 1 y 2 minutos | 

## Paso 7: Observe e interprete los resultados
<a name="nova-eval-container-step7"></a>

Cuando se complete el trabajo, consulte los resultados de la evaluación.

**Visualizar con Inspect AI**

Utilice el visor de Inspect AI para explorar los resultados de forma interactiva directamente desde S3:

```
inspect view --log-dir s3://your-bucket/eval-results/
```

Este comando abre una interfaz web local en la que puede buscar puntuaciones, ver muestras individuales y comparar ejecuciones.

**Descargar y compartir**

Para descargar los resultados de forma local:

```
aws s3 cp s3://your-bucket/eval/output/ ./results/ --recursive

INSPECT_LOG_DIR=./results inspect view
```

**Extensión VS Code**

La [extensión VS Code para Inspect AI](https://inspect.aisi.org.uk/vscode.html) le permite explorar los registros de evaluación directamente desde S3 sin tener que descargarlos primero.

1. Instale la extensión desde la tienda de VS Code (busque “Inspect AI”).

1. En la barra de actividades de Inspect, localice el panel “Registros” y elija el ícono de la carpeta.

1. Escriba su ruta de S3: `s3://your-bucket/eval-results/`.

**Estructura de salida**

Cada evaluación genera un archivo de registro `.eval` que contiene las siguientes secciones:
+ `results.scores`: Puntuaciones agregadas para cada métrica.
+ `samples`: Muestras de evaluación individuales con entradas, salidas y puntuaciones.
+ `stats`: Estadísticas de tiempo de ejecución, que incluyen el uso de tokens y la latencia.
+ `eval.config`: Configuración utilizada para la ejecución de la evaluación.

**Ver los resultados en MLflow (opcional)**

Si configuró MLflow en su fórmula, genere una URL prefirmada para acceder al servidor de seguimiento:

```
aws sagemaker create-presigned-mlflow-tracking-server-url \
    --tracking-server-name my-server \
    --region us-west-2
```

Abra la URL devuelta en su navegador para ver las métricas, comparar las ejecuciones y analizar las tendencias de las evaluaciones.

## Puntos de referencia disponibles
<a name="nova-eval-container-benchmarks"></a>

El contenedor Inspect AI funciona con cualquier punto de referencia escrito en el formato de tareas de Inspect AI. El [repositorio inspect-evals](https://github.com/UKGovernmentBEIS/inspect_evals) proporciona más de 128 puntos de referencia listos para usar, los cuales abarcan áreas como el razonamiento, el conocimiento, la codificación y la seguridad.

Para escribir sus propios puntos de referencia, consulte la [documentación sobre redacción de tareas de Inspect AI.](https://inspect.aisi.org.uk/tasks.html) Si encuentra un punto de referencia público que aún no está disponible en inspect-evals, puede utilizar la [petición de incorporación del asistente de IA](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/ai_assisted_benchmark_creation.md) para convertirlo al formato de Inspect AI.

## Evaluaciones con agentes
<a name="nova-eval-container-agentic"></a>

Los puntos de referencia con agentes ponen a prueba la capacidad de un modelo para completar tareas de varios pasos que requieren el uso de herramientas, la planificación y el razonamiento iterativo. Estas evaluaciones simulan escenarios del mundo real en los que el modelo debe llamar a las herramientas, interpretar los resultados y decidir las próximas acciones.

**Requisitos de punto de enlace**

Las evaluaciones con agentes requieren puntos de conexión que respalden las siguientes funciones:
+ **Llamadas a herramientas**: El punto de conexión debe admitir la llamada a funciones para que el modelo pueda invocar herramientas durante la evaluación.
+ **Amplio tamaño del contexto**: Las conversaciones de varios turnos con los resultados de las herramientas requieren una longitud de contexto suficiente para mantener el historial de conversaciones.

**Configuración del punto de conexión de SageMaker Inference**

Cuando utilice un punto de conexión de SageMaker Inference para las evaluaciones con agentes, configure las siguientes variables de entorno en el punto de conexión:


| Variable de entorno | Valor | Descripción | 
| --- | --- | --- | 
| ENABLE\_TOOL\_CALLING | True | Activa la compatibilidad de llamadas a herramientas en el punto de conexión de inferencia. | 
| CONTEXT\_LENGTH | Apropiado para varios turnos | Establézcalo en un valor lo suficientemente alto como para admitir conversaciones de varios turnos con los resultados de las herramientas. | 

Para obtener información sobre la configuración de los puntos de conexión de Amazon Nova en SageMaker Inference, consulte cómo [implementar modelos de Amazon Nova en SageMaker](https://docs.aws.amazon.com//nova/latest/userguide/deploy-sagemaker.html). Para obtener información sobre las características y la configuración de los contenedores, consulte las [características del contenedor](https://docs.aws.amazon.com//nova/latest/userguide/container-features.html).

**Puntos de conexión de Amazon Bedrock**

En el caso de los puntos de conexión de Amazon Bedrock, las llamadas a las herramientas se admiten de forma nativa en los modelos compatibles. Para obtener más información, consulte [Uso de herramienta con Amazon Bedrock](https://docs.aws.amazon.com//bedrock/latest/userguide/tool-use.html).

**Cómo empezar a realizar evaluaciones con agentes**

Para ejecutar evaluaciones con agentes, se deben cumplir los siguientes requisitos previos:

1. Implemente un punto de conexión con la función de llamadas a herramientas habilitada.

1. Elija un punto de referencia con agentes del [repositorio inspect-evals](https://github.com/UKGovernmentBEIS/inspect_evals) (busque puntos de referencia que utilicen solucionadores de llamadas a herramientas).

1. Configure su fórmula con los valores `timeout` y `max_tokens` adecuados para las interacciones de varios turnos.

**Punto de conexión de Amazon Bedrock**
+ Para lograr una configuración e implementación completas, consulte los [puntos de conexión de Amazon Bedrock](https://docs.aws.amazon.com//bedrock/latest/userguide/endpoints.html).
+ Para activar la compatibilidad con llamadas a herramientas, consulte la sección de llamadas a herramientas del lado del cliente en [Uso de herramienta con Amazon Bedrock](https://docs.aws.amazon.com//bedrock/latest/userguide/tool-use.html).

**Cuadernos de ejemplo**

En el siguiente cuaderno, se muestra la ejecución de un punto de referencia con agentes de llamadas a herramientas con el contenedor Inspect AI:
+ [tau-bench (basado en el trabajo)](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/inspect_eval_container/eval_tau_bench.ipynb): Evalúe el razonamiento basado en herramientas sobre las tareas de servicio al cliente mediante el contenedor Inspect AI.

Para los puntos de referencia con agentes que requieren un entorno de pruebas de Docker, utilice el Inspect AI SDK:
+ [SWE-bench con el Inspect AI SDK](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/local_inspect_sdk/eval_swe_bench.ipynb): Evalúe las capacidades de ingeniería de software con el entorno de pruebas de Docker.

**importante**  
En la experiencia del contenedor Inspect AI, no se admiten los puntos de referencia con agentes que requieren un entorno de pruebas de Docker (como SWE-bench). El entorno de trabajo de entrenamiento de SageMaker no proporciona funciones de Docker-in-Docker. Para ejecutar estos puntos de referencia, utilice el [Inspect AI SDK](nova-eval-on-sagemaker-inference.md) en un entorno informático con acceso a Docker (por ejemplo, una instancia de Amazon EC2 o un cuaderno de SageMaker con Docker instalado).

## Solución de problemas
<a name="nova-eval-container-troubleshooting"></a>

En esta sección, se brindan soluciones a problemas comunes que surgen al ejecutar evaluaciones con el contenedor Inspect AI.

**Consejo rápido de iteración**

Antes de enviar un trabajo de entrenamiento de SageMaker, pruebe sus puntos de referencia localmente con el Inspect AI SDK. Ejecute `inspect eval my_benchmark.py` en su máquina local para validar las definiciones, las dependencias y la lógica de puntuación de las tareas antes de ejecutarlas a gran escala.

**Error InsufficientInstanceCapacity**

Este error se produce cuando AWS no tiene suficiente capacidad para el tipo de instancia solicitada en su región.
+ Pruebe un tipo de instancia diferente o envíe el trabajo en otra región de AWS.
+ Use un tipo de instancia diferente (por ejemplo, `ml.m5.xlarge` en lugar de `ml.m5.large`).
+ Intente volver a realizar la solicitud después de unos minutos.

**Error AccessDenied**

Si el trabajo de entrenamiento falla y se produce un error de acceso denegado, compruebe lo siguiente:
+ El ARN del rol en la configuración del trabajo es correcto.
+ La política de confianza permite a `sagemaker.amazonaws.com` asumir el rol.
+ Su rol o usuario tienen el permiso `iam:PassRole` para el rol de ejecución.
+ El rol de ejecución tiene permisos para acceder al bucket de S3, al punto de conexión de inferencia o al modelo de Amazon Bedrock.

**Falla en la creación del punto de conexión**

Cuando se utiliza `cleanup_endpoint: true` con la creación automática de puntos de conexión, pueden ocasionarse los siguientes problemas:


| Error | Solución | 
| --- | --- | 
| ResourceLimitExceeded | Solicite un aumento de la cuota de servicio para el tipo de instancia de inferencia en su región. | 
| OutOfMemoryError | Utilice un tipo de instancia de inferencia más grande o reduzca el tamaño del modelo. | 
| model\_s3\_uri incorrecto | Compruebe que la ruta de S3 dirija a un directorio de artefactos de modelos válido. | 
| URI de imagen de inferencia incorrecto | Compruebe que el URI de la imagen sea correcto para su región y marco de modelo. | 
| El punto de conexión se bloquea en la creación | Consulte CloudWatch Logs para el punto de conexión. Es posible que el modelo no supere las comprobaciones de estado. Aumente MaxRuntimeInSeconds si el punto de conexión necesita más tiempo. | 

**Tiempos de espera de descarga de HuggingFace**

Si se agota el tiempo de espera de los puntos de referencia que descargan conjuntos de datos de HuggingFace Hub, establezca la variable de entorno `HF_HUB_DOWNLOAD_TIMEOUT` en un valor más alto (en segundos):

```
--environment '{"HF_HUB_DOWNLOAD_TIMEOUT": "600"}'
```

**El trabajo está interrumpido, pero el punto de conexión sigue ejecutándose**

Si el trabajo de entrenamiento se interrumpe antes de que se complete la depuración, es posible que el punto de conexión de inferencia permanezca activo. Elimine manualmente el punto de conexión para evitar cargos continuos:

```
# List endpoints to find the orphaned one
aws sagemaker list-endpoints \
    --name-contains inspect \
    --query "Endpoints[].EndpointName" \
    --output table

# Delete the endpoint
aws sagemaker delete-endpoint \
    --endpoint-name your-endpoint-name

# Delete the endpoint configuration
aws sagemaker delete-endpoint-config \
    --endpoint-config-name your-endpoint-name

# Delete the model
aws sagemaker delete-model \
    --model-name your-endpoint-name
```

**Conflictos de dependencia de los puntos de referencia**

Si un punto de referencia falla debido a conflictos de dependencia con los paquetes preinstalados, cree un `pyproject.toml` en el directorio del punto de referencia con restricciones de versión explícitas. El contenedor instala las dependencias de los puntos de referencia de forma aislada para minimizar los conflictos.

**Puntuaciones de evaluaciones incorrectas**

Si las puntuaciones de las evaluaciones son inesperadamente bajas o inconsistentes, compruebe los siguientes ajustes en su fórmula:
+ **temperature**: Configure el valor en `0.0` para obtener resultados deterministas y reproducibles.
+ **max\_tokens**: Asegúrese de que el valor sea lo suficientemente alto como para que el modelo complete su respuesta.
+ **completion\_mode**: Para los modelos base (que no son de chat), establezca `completion_mode: true` en su fórmula para que se utilicen peticiones con estilo de finalización en lugar del formato de chat.

## Privacidad de datos
<a name="nova-eval-container-data-privacy"></a>

Los datos de evaluación se gestionan de forma diferente según el proveedor de inferencias que utilice.

**Punto de conexión de SageMaker**

Cuando utiliza un punto de conexión de SageMaker Inference, todos los datos permanecen dentro de su Cuenta de AWS. Las peticiones de evaluación y las respuestas de los modelos no se envían fuera de su cuenta ni se utilizan para mejorar los servicios de AWS. No se necesita ninguna política de exclusión.

**Amazon Bedrock**

Cuando utiliza Amazon Bedrock como proveedor de inferencias, sus datos están sujetos a la Política de exclusión de los servicios de IA de AWS. Para que sus datos no se utilicen para mejorar los servicios de IA de AWS, habilite la política de exclusión en AWS Organizations. Para obtener más información, consulte las [políticas de exclusión de los servicios de IA](https://docs.aws.amazon.com//organizations/latest/userguide/orgs_manage_policies_ai-opt-out.html).


| Proveedor de inferencias | Exclusión obligatoria | Details | 
| --- | --- | --- | 
| Punto de conexión de SageMaker | No | Los datos permanecen en su cuenta. No está cubierto por la política de exclusión de IA. | 
| Amazon Bedrock | Sí | Habilite la Política de exclusión de los servicios de IA de AWS en Organizations a fin de evitar el uso de los datos para mejorar el servicio. |