# Avaliação com o contêiner do Inspect AI
O contêiner do Inspect AI para o SageMaker realiza avaliações de modelos de LLM em Tarefas de Treinamento do SageMaker. O contêiner usa o [Inspect AI](https://inspect.ai-safety-institute.org.uk/) para fornecer um processo de avaliação padronizado para modelos implantados em endpoints de inferência do SageMaker ou no Amazon Bedrock, incluindo modelos do Amazon Nova 1.0 (como Micro, Lite e Pro) e 2.0 (Lite 2).
Nas [abordagens de avaliação](https://docs.aws.amazon.com//nova/latest/nova2-userguide/nova-model-evaluation.html) anteriores (baseadas no [lighteval](https://github.com/huggingface/lighteval)), a inferência off-line e a lógica de avaliação eram fortemente integradas, reduzindo a flexibilidade para diferentes estratégias de disponibilização e teste dos modelos. O contêiner do Inspect AI separa totalmente a lógica de avaliação do processo de inferência.
## Visão geral
Os benefícios importantes incluem:
+ **Adotar suas próprias avaliações comparativas**: desenvolva tarefas de avaliação no formato do Inspect AI e, em seguida, integre avaliações específicas para o domínio sem depender de uma equipe centralizada para incorporá-las à plataforma.
+ **Avaliar usando diferentes opções de inferência**: compatível com o SageMaker Inference, utilizando um endpoint existente ou criado sob demanda, com o Amazon Bedrock e com outros backends de inferência que serão adicionados futuramente.
+ **Realizar iterações com mais rapidez**: passe do desenvolvimento de avaliações comparativas para avaliações em ambientes de produção sem a necessidade de alterações na infraestrutura. O processo de integração de novas avaliações comparativas, que antes demorava dias, agora pode ser concluído em minutos.
+ **Realizar execuções em grande escala**: encadeie várias avaliações comparativas em um único trabalho, combinando avaliações padrão da biblioteca inspect-evals com suas próprias tarefas personalizadas no mesmo trabalho.
+ **Disponibilizar um único ponto de entrada para todas as técnicas de treinamento**: independentemente de o modelo ter sido ajustado com SFT (SMTJ e SMHP), CPT (SMHP) ou RFT (SMTJ e SMHP), o contêiner o avalia usando a mesma interface. A avaliação de pontos de verificação durante o treinamento, salvos em etapas específicas (por exemplo, etapa 500 e etapa 1.000), também é possível, com direcionamento a `model_s3_uri` para o caminho do ponto de verificação.
### Como funciona
Você fornece duas entradas para o contêiner:
1. Um arquivo de configuração YAML (receita) que define o provedor de inferência, as avaliações comparativas e os parâmetros de avaliação
1. Os arquivos destinados à avaliação comparativa (scripts Python com o decorador `@task`) enviados para o Amazon S3
O contêiner gerencia os endpoints, a execução da avaliação e a coleta de resultados. Quando a tarefa de treinamento é concluída, os resultados são gravados no local de saída do S3 especificado.
## Imagem de contêiner
A tabela apresentada a seguir lista os URIs das imagens de contêiner do Inspect AI por região da AWS.
| Região | URI da imagem do contêiner |
| --- | --- |
| 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 |
## Pré-requisitos
Antes de começar, verifique se você conta com os recursos e o acesso necessários apresentados a seguir.
| Requisito | Descrição |
| --- | --- |
| Conta da AWS com acesso ao SageMaker | Uma Conta da AWS ativa com permissões para criar Tarefas de Treinamento do SageMaker |
| Bucket do S3 | Um bucket para armazenar as receitas de avaliação, os arquivos de avaliações comparativas e os resultados de saída |
| Perfil de execução do IAM | Um perfil que o SageMaker pode assumir para acessar os recursos |
| Endpoint de inferência do SageMaker ou acesso ao Amazon Bedrock | Um endpoint de modelo implantado ou acesso ao modelo do Amazon Bedrock para o modelo que você deseja avaliar |
| AWS CLI ou SDK do SageMaker para Python | Ferramentas para o envio de tarefas de treinamento e para o gerenciamento de recursos |
| Reserva de capacidade (modelos grandes) | Para modelos que requerem instâncias aceleradas (como p5 para o Nova Lite 2), entre em contato com o AWS Support para realizar a reserva de capacidade para o SageMaker Inference ou para o Amazon Bedrock |
## Etapa 1: configurar permissões do IAM
A Tarefa de Treinamento do SageMaker é executada em um perfil de execução fornecido por você. Esse perfil precisa de permissões para ler avaliações comparativas do S3, gravar resultados, invocar o endpoint de inferência e gravar logs no CloudWatch.
**1.1 Criar a política de confiança**
Salve o seguinte como `trust_policy.json`:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "sagemaker.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
**1.2 Criar o perfil**
```
aws iam create-role \
--role-name InspectLensEvalRole \
--assume-role-policy-document file://trust_policy.json
```
**1.3 Anexar a política de permissões**
Salve o seguinte como `eval_policy.json`, substituindo todos os valores de espaço reservado (como `REGION`, `ACCOUNT_ID` e nomes de bucket) pelos seus 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/*"
}
]
}
```
Anexe a política à função:
```
aws iam put-role-policy \
--role-name InspectLensEvalRole \
--policy-name InspectLensEvalPolicy \
--policy-document file://eval_policy.json
```
## Etapa 2: gravar a receita de avaliação
A receita de avaliação consiste em um arquivo de configuração em YAML que define como o contêiner executa as avaliações. A receita especifica o provedor de inferência, as avaliações comparativas, os parâmetros de avaliação e as configurações de saída.
Para obter exemplos completos, consulte os seguintes cadernos:
+ [Avaliação de um endpoint existente do SageMaker](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/inspect_eval_container/eval_sagemaker_endpoint.ipynb)
+ [Avaliação com um endpoint gerenciado](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/inspect_eval_container/eval_managed_endpoint.ipynb)
+ [Avaliação de um modelo do Amazon Bedrock](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/inspect_eval_container/eval_bedrock_model.ipynb)
**Opção A: avaliação de um endpoint existente do SageMaker**
Use esta opção quando você já tiver um modelo implantado em um endpoint de inferência do 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/"
```
**Opção B: criação de um endpoint, avaliação e posterior limpeza**
Use esta opção para fazer com que o contêiner implante um modelo de base ou um modelo ajustado do Amazon Nova, execute avaliações e desative o endpoint automaticamente. Esta é a abordagem recomendada para execuções de avaliação pontuais. Recupere o contêiner do SageMaker Inference mais recente na documentação de [imagens do contêiner para o Amazon Nova no SageMaker Inference](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/"
```
**Observação sobre `model_s3_uri`:**
+ **Modelos do Amazon Nova em disponibilidade geral (pontos de verificação de base)**: por exemplo, `s3://escrow-nova-model-708977205387-us-east-1/nova-lite-2/prod/`, no qual o SageMaker gerencia o acesso automaticamente, sem a necessidade de permissões adicionais do S3.
+ **Modelos do Amazon Nova personalizados (pontos de verificação posteriores ao treinamento)**: `s3://customer-escrow-ACCOUNT_ID-SUFFIX/YOUR_RUN_NAME/outputs/checkpoints/step_N/`, o qual é o caminho do bucket de garantia da saída da tarefa de treinamento.
**Opção C: avaliação por meio do Amazon Bedrock**
Use esta opção para avaliar um modelo disponível no Amazon Bedrock sem precisar gerenciar um endpoint.
```
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/
```
**Configuração de avaliações comparativas**
A seção `benchmarks` define quais tarefas de avaliação serão executadas. É possível encadear diversas avaliações comparativas em um único trabalho.
| Campo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- |
| name | Sim | — | Um nome descritivo para a execução da avaliação comparativa |
| path | Sim | — | Caminho relativo ao arquivo em Python da avaliação comparativa no diretório de avaliações comparativas do S3 |
| limit | Não | Nenhum (todas as amostras) | Número máximo de amostras a serem avaliadas. Útil para realizar testes antes de uma execução completa. |
| epochs | Não | 1 | Número de repetições necessárias para que os resultados apresentem significância estatística |
| task\_args | Não | — | Pares de chave-valor transferidos como argumentos para a função de tarefa da avaliação comparativa. |
**Configuração de avaliação**
A seção `eval` controla como o contêiner executa as avaliações.
| Parâmetro | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- |
| fail\_on\_error | Não | false | Interrompe a avaliação se qualquer amostra falhar. Defina como true para obter uma validação estrita. |
| max\_connections | Não | 10 | Número de solicitações paralelas para o endpoint de inferência |
| max\_retries | Não | 3 | Número de tentativas de repetição para solicitações de inferência que falharem |
| timeout | Não | 600 | Tempo limite da solicitação em segundos para cada chamada de inferência |
| extra\_args | Não | — | Pares de chave-valor adicionais transferidos diretamente ao comando de avaliação do Inspect AI |
**Parâmetros de decodificação**
Configure os parâmetros de decodificação do modelo na seção `eval.decoding`:
| Parâmetro | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- |
| temperature | Não | 0.0 | Controla a aleatoriedade na geração. Use 0.0 para resultados de avaliações comparativas determinísticos e reproduzíveis. |
| top\_p | Não | 1,0 | Limite de amostragem por núcleo. O valor 1.0 significa que não há restrição. |
| top\_k | Não | -1 | Limita as escolhas de palavras aos K tokens mais prováveis. O valor -1 desabilita este filtro. |
| max\_tokens | Não | 8192 | Número máximo de tokens a serem gerados por resposta. Aumente para avaliações comparativas que requerem cadeias longas de raciocínio. |
| reasoning\_effort | Não | nulo | Controla a profundidade do raciocínio para modelos que oferecem suporte a essa funcionalidade (por exemplo, modelos do Amazon Nova com pensamento estendido). Opções: low, high ou null para desabilitar. |
**Configuração da saída**
A seção `output` define o local e a forma como os resultados da avaliação são armazenados.
| Campo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- |
| s3\_path | Sim | — | URI do S3 no qual os resultados da avaliação serão gravados |
| output\_format | Não | eval | Formato dos arquivos de resultado. Confira as opções na tabela a seguir. |
Os seguintes formatos de saída estão disponíveis:
| Formato | Descrição |
| --- | --- |
| eval | Formato nativo do Inspect AI. Compatível com a ferramenta inspect view para análise interativa. |
| csv | Valores separados por vírgula. Adequado para análise em planilhas e pipelines de dados. |
| jsonl | Formato JSON Lines. Um objeto JSON por linha, ideal para processamento em streaming. |
| json | Formato JSON padrão. Resultados completos em um único arquivo estruturado. |
**Configuração do MLflow**
Opcionalmente, você pode registrar em log as métricas de avaliação em um servidor de rastreamento do MLflow. Adicione a seção `tracking` à sua receita:
```
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 | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- |
| mlflow\_tracking\_arn | Não | nulo | ARN do servidor de rastreamento do MLflow no SageMaker. Configurar este campo habilita o registro em log do MLflow. Realize a omissão ou defina como null para desabilitá-lo. |
| mlflow\_experiment\_name | Não | inspectlens | Nome do experimento do MLflow no qual as execuções serão registradas em log. |
| mlflow\_tracing | Não | true | Quando definido como true, registra em log os rastreamentos completos de solicitações e de respostas para cada amostra. |
| mlflow\_log\_artifacts | Não | true | Quando definido como true, faz o upload dos arquivos de log .eval como artefatos do MLflow. |
**Referência completa da receita**
O exemplo abaixo apresenta uma receita completa com todas as opções de configuração disponíveis:
```
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
```
## Etapa 3: preparar os arquivos de avaliação comparativa
As avaliações comparativas consistem em arquivos em Python que usam o decorador `@task` do Inspect AI para definir tarefas de avaliação. O [repositório inspect-evals](https://github.com/UKGovernmentBEIS/inspect_evals) fornece mais de 128 avaliações comparativas prontas para uso. Entretanto, se desejar, você pode escrever suas próprias avaliações.
**Exemplo de avaliação comparativa**
O exemplo abaixo apresenta uma avaliação comparativa mínima que avalia a performance de múltipla escolha em um conjunto de dados da 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(),
)
```
**Dependências**
Se a avaliação comparativa precisar de dependências adicionais, inclua um arquivo `pyproject.toml` ou `requirements.txt` no mesmo diretório do S3:
```
[project]
name = "my-benchmark"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
"datasets>=2.14.0",
]
```
**Pacotes pré-instalados**
O contêiner inclui os pacotes apresentados a seguir. Você não precisa listá-los no arquivo `pyproject.toml`.
| Pacote | Versão |
| --- | --- |
| 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 |
**Seleção de tarefas**
O campo `tasks` na receita controla quais tarefas serão executadas em um arquivo de avaliação comparativa.
| Configuração | Exemplo | Comportamento |
| --- | --- | --- |
| Vazio tasks | tasks: [] | Executa todas as tarefas definidas no arquivo da avaliação comparativa |
| Filtro por nome | tasks: ["algebra"] | Executa tarefas cujo nome contenha a substring “algebra”. |
| limit | limit: 50 | Limita o número de amostras avaliadas por tarefa |
| epochs | epochs: 3 | Repete a avaliação diversas vezes para medir a variação |
## Etapa 4: preparar a estrutura do S3
A estrutura apresentada a seguir é uma recomendação para manter as configurações, as avaliações comparativas e os resultados organizados. Você pode realizar o direcionamento do contêiner para qualquer localização do S3, portanto, a estrutura em si não é obrigatória.
```
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
```
Faça o upload dos arquivos para o 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
```
## Etapa 5: enviar a tarefa de treinamento
Envie uma Tarefa de Treinamento do SageMaker para executar a avaliação. Você pode usar a AWS CLI ou o SDK do SageMaker para Python.
**Opção 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
```
**Opção B: SDK do SageMaker para Python na 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/",
)
]
)
```
**Principais parâmetros**
| Parâmetro | Valor | Descrição |
| --- | --- | --- |
| TrainingImage | 763104351884.dkr.ecr.us-east-1.amazonaws.com/sagemaker-inspect-ai:latest | A imagem de contêiner do Inspect AI |
| InstanceType | ml.m5.large | Tipo de instância do orquestrador (não a instância de inferência) |
| VolumeSizeInGB | 30 | Armazenamento para logs e dados das avaliações comparativas |
| MaxRuntimeInSeconds | 86400 | Duração máxima do trabalho (24 horas) |
| ChannelName | config | Canal de entrada que contém a receita e os arquivos da avaliação comparativa |
**Orientação sobre o tipo de instância do orquestrador**
A instância da tarefa de treinamento executa a lógica de orquestração da avaliação, não a inferência do modelo. Escolha um tipo de instância com base na workload de avaliação.
| Tipo de instância | Caso de uso | Orientação |
| --- | --- | --- |
| ml.m5.large | Padrão recomendado | Suficiente para a maioria das workloads de avaliação com paralelismo moderado |
| ml.m5.4xlarge | Conjuntos de avaliação comparativa grandes | Use ao executar muitas avaliações comparativas com valores elevados de max\_connections |
| ml.c5.large | Sensível a custos | Alternativa de menor custo para avaliações simples com baixo paralelismo |
**Variáveis de ambiente**
Você pode transferir variáveis de ambiente para o contêiner à autenticação ou à configuração. Adicione o parâmetro `--environment` ao comando da AWS CLI:
```
aws sagemaker create-training-job \
...
--environment '{
"HF_TOKEN": "hf_your_token_here",
"HF_HUB_DOWNLOAD_TIMEOUT": "300"
}'
```
## Etapa 6: monitorar o trabalho
Depois de enviar a tarefa de treinamento, é possível monitorar o progresso dela por meio da AWS CLI ou do CloudWatch Logs.
**Verificar status de tarefa**
```
aws sagemaker describe-training-job \
--training-job-name your-job-name \
--query "TrainingJobStatus" \
--output text
```
**Transmitir logs**
```
aws logs tail /aws/sagemaker/TrainingJobs \
--log-stream-name-prefix your-job-name \
--follow
```
**O que esperar dos logs**
Os logs do contêiner mostram o progresso por meio das seguintes etapas:
1. **Inicialização**: inicialização do contêiner e validação da configuração
1. **Download das avaliações comparativas**: download dos arquivos de avaliação comparativa e instalação de dependências
1. **Configuração do endpoint**: criação ou conexão com o endpoint de inferência
1. **Avaliação**: execução das tarefas de avaliação comparativa com indicadores de progresso
1. **Upload de resultados**: gravação dos resultados no S3 e, opcionalmente, registro em log no MLflow.
1. **Limpeza**: exclusão de endpoints temporários caso `cleanup_endpoint: true` esteja configurado
**Prazos estimados**
| Estágio | Duração estimada |
| --- | --- |
| Inicialização do contêiner | 2 a 5 minutos |
| Criação do endpoint (se aplicável) | 15 a 30 minutos |
| Avaliação | Varia conforme o tamanho da avaliação comparativa e a latência do modelo |
| Limpeza | 1 a 2 minutos |
## Etapa 7: visualizar e interpretar os resultados
Após a conclusão do trabalho, visualize os resultados da avaliação.
**Visualizar com o Inspect AI**
Use o visualizador do Inspect AI para explorar os resultados de forma interativa diretamente do S3:
```
inspect view --log-dir s3://your-bucket/eval-results/
```
Este comando abre uma interface da web local na qual é possível navegar por pontuações, visualizar amostras individuais e comparar execuções.
**Fazer o download e o compartilhamento**
Para fazer o download de resultados localmente:
```
aws s3 cp s3://your-bucket/eval/output/ ./results/ --recursive
INSPECT_LOG_DIR=./results inspect view
```
**Extensão do VS Code**
A [extensão do VS Code para o Inspect AI](https://inspect.aisi.org.uk/vscode.html) permite navegar pelos logs de avaliação diretamente do S3 sem a necessidade de fazer o download prévio.
1. Instale a extensão usando o marketplace do VS Code (pesquise por “Inspect AI”)
1. Na barra de atividades do Inspect, localize o painel Logs e escolha o ícone de pasta
1. Insira o seu caminho do S3: `s3://your-bucket/eval-results/`
**Estrutura de saída**
Cada avaliação produz um arquivo de log `.eval` que contém as seguintes seções:
+ `results.scores`: pontuações agregadas para cada métrica
+ `samples`: amostras de avaliação individuais com entradas, saídas e pontuações
+ `stats`: estatísticas de runtime, incluindo o uso de tokens e a latência
+ `eval.config`: a configuração usada para a execução da avaliação
**Visualizar resultados no MLflow (opcional)**
Caso tenha configurado o MLflow em sua receita, gere um URL assinado previamente para acessar o servidor de rastreamento:
```
aws sagemaker create-presigned-mlflow-tracking-server-url \
--tracking-server-name my-server \
--region us-west-2
```
Abra o URL retornado no navegador para visualizar métricas, comparar execuções e analisar tendências entre as avaliações.
## Avaliações comparativas disponíveis
O contêiner do Inspect AI é compatível com qualquer avaliação comparativa escrita no formato de tarefa do Inspect AI. O [repositório inspect-evals](https://github.com/UKGovernmentBEIS/inspect_evals) fornece mais de 128 avaliações comparativas prontas para uso, abrangendo áreas como raciocínio, conhecimento, codificação e segurança.
Para escrever suas próprias avaliações comparativas, consulte a [documentação destinada à gravação de tarefas do Inspect AI](https://inspect.aisi.org.uk/tasks.html). Se você encontrar uma avaliação comparativa pública que ainda não esteja disponível no repositório inspect-evals, poderá usar o [prompt de integração do assistente de IA](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/ai_assisted_benchmark_creation.md) para ajudar a convertê-la para o formato do Inspect AI.
## Avaliações agênticas
As avaliações comparativas agênticas testam a capacidade de um modelo de concluir tarefas de várias etapas que exigem o uso de ferramentas, planejamento e raciocínio iterativo. Essas avaliações simulam cenários reais nos quais o modelo deve acionar ferramentas, interpretar resultados e decidir as próximas ações a serem realizadas.
**Requisitos de endpoint**
Avaliações agênticas requerem endpoints que ofereçam suporte às seguintes funcionalidades:
+ **Chamada de ferramentas**: o endpoint deve fornecer suporte para a chamada de função a fim de permitir que o modelo invoque ferramentas durante a avaliação
+ **Grande capacidade de contexto**: conversas de vários turnos, especialmente quando envolvem resultados de ferramentas, requerem uma janela de contexto ampla para preservar o histórico e manter a continuidade da interação
**Configuração do endpoint do SageMaker Inference**
Ao usar um endpoint do SageMaker Inference para avaliações agênticas, configure as seguintes variáveis de ambiente no endpoint:
| Variável de ambiente | Valor | Descrição |
| --- | --- | --- |
| ENABLE\_TOOL\_CALLING | True | Ativa o suporte à chamada de ferramentas no endpoint de inferência |
| CONTEXT\_LENGTH | Suficiente para conversas vários turnos | Defina um valor grande o bastante para preservar o contexto de conversas longas com vários turnos e uso de ferramentas |
Para obter informações sobre como configurar endpoints do Amazon Nova no SageMaker Inference, consulte [Implantação de modelos do Amazon Nova no SageMaker](https://docs.aws.amazon.com//nova/latest/userguide/deploy-sagemaker.html). Para obter informações sobre recursos e configuração de contêineres, consulte [Recursos do contêiner](https://docs.aws.amazon.com//nova/latest/userguide/container-features.html).
**Endpoints do Amazon Bedrock**
Nos endpoints do Amazon Bedrock, modelos compatíveis oferecem suporte nativo às chamadas de ferramentas. Para obter mais informações, consulte [Uso de ferramentas com o Amazon Bedrock](https://docs.aws.amazon.com//bedrock/latest/userguide/tool-use.html).
**Conceitos básicos das avaliações agênticas**
Para executar avaliações agênticas, conclua os seguintes pré-requisitos:
1. Implantar um endpoint com a chamada de ferramentas habilitada
1. Escolher uma avaliação comparativa agêntica do [repositório inspect-evals](https://github.com/UKGovernmentBEIS/inspect_evals) (procure por avaliações comparativas que usem solucionadores de chamadas de ferramentas)
1. Configurar a receita com valores apropriados de `timeout` e `max_tokens` para interações de vários turnos
**Endpoint do Amazon Bedrock**
+ Para obter a configuração e a implantação completas, consulte [Endpoints do Amazon Bedrock](https://docs.aws.amazon.com//bedrock/latest/userguide/endpoints.html).
+ Para obter suporte às chamadas de ferramentas, consulte a seção de chamada de ferramenta do lado do cliente em [Uso de ferramentas com o Amazon Bedrock](https://docs.aws.amazon.com//bedrock/latest/userguide/tool-use.html).
**Cadernos de amostra**
O seguinte caderno demonstra a execução de uma avaliação comparativa agêntica de chamada de ferramenta com o contêiner do Inspect AI:
+ [tau-bench (baseado em trabalho)](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/inspect_eval_container/eval_tau_bench.ipynb): avalie o raciocínio aumentado por ferramentas em tarefas de atendimento ao cliente usando o contêiner do Inspect AI
Para avaliações comparativas agênticas que exigem um sandbox do Docker, use o SDK do Inspect AI:
+ [SWE-bench com SDK do Inspect AI](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/local_inspect_sdk/eval_swe_bench.ipynb): avalie funcionalidades de engenharia de software usando o sandbox do Docker
**Importante**
As avaliações comparativas agênticas que exigem um sandbox do Docker (como o SWE-bench) não são suportadas na experiência de contêiner do Inspect AI. O ambiente da Tarefa de Treinamento do SageMaker não fornece funcionalidades de Docker-in-Docker. Para executar essas avaliações comparativas, use o [SDK do Inspect AI](nova-eval-on-sagemaker-inference.md) em um ambiente de computação com acesso ao Docker (por exemplo, uma instância do Amazon EC2 ou um caderno do SageMaker com o Docker instalado).
## Solução de problemas
Esta seção fornece soluções para problemas comuns ao executar avaliações com o contêiner do Inspect AI.
**Dica de iteração rápida**
Antes de enviar uma Tarefa de Treinamento do SageMaker, teste suas avaliações comparativas localmente com o SDK do Inspect AI. Execute `inspect eval my_benchmark.py` na sua máquina local para validar definições de tarefas, dependências e lógica de pontuação antes de realizar a execução em grande escala.
**Erro InsufficientInstanceCapacity**
Este erro ocorre quando a AWS não tem capacidade suficiente para o tipo de instância solicitado na sua região.
+ Tente usar um tipo de instância diferente ou envie o trabalho em outra região da AWS
+ Use outro tipo de instância (por exemplo, `ml.m5.xlarge` em vez de`ml.m5.large`)
+ Tente realizar novamente a solicitação após alguns minutos
**Erro AccessDenied**
Se a tarefa de treinamento falhar com um erro de acesso negado, verifique o seguinte:
+ O ARN do perfil na configuração do trabalho está correto
+ A política de confiança permite que `sagemaker.amazonaws.com` assuma o perfil
+ O usuário ou o perfil tem a permissão `iam:PassRole` para o perfil de execução
+ O perfil de execução tem permissões para acessar o bucket do S3, o endpoint de inferência ou o modelo do Amazon Bedrock
**Falha na criação do endpoint**
Ao usar `cleanup_endpoint: true` com a criação automática de endpoint, os seguintes problemas podem ocorrer:
| Erro | Solução |
| --- | --- |
| ResourceLimitExceeded | Solicite um aumento da cota de serviço para o tipo de instância de inferência na sua região |
| OutOfMemoryError | Use um tipo de instância de inferência maior ou reduza o tamanho do modelo |
| model\_s3\_uri incorreto | Verifique se o caminho do S3 aponta para um diretório de artefatos de modelos válido |
| URI da imagem de inferência incorreto | Verifique se o URI da imagem está correto para a região e para o framework do modelo |
| Endpoint travado no estado “Criando” | Verifique o CloudWatch Logs para o endpoint. O modelo pode estar apresentando falhas nas verificações de integridade. Aumente MaxRuntimeInSeconds se o endpoint precisar de mais tempo. |
**Tempos limite de download da Hugging Face**
Se as avaliações comparativas que fazem download de conjuntos de dados do Hugging Face Hub atingirem o tempo limite, defina a variável de ambiente `HF_HUB_DOWNLOAD_TIMEOUT` para um valor maior (em segundos):
```
--environment '{"HF_HUB_DOWNLOAD_TIMEOUT": "600"}'
```
**Trabalho interrompido, mas o endpoint continua em execução**
Se a tarefa de treinamento for interrompida antes da conclusão da limpeza, o endpoint de inferência poderá permanecer ativo. Exclua manualmente o endpoint para evitar cobranças contínuas:
```
# 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
```
**Conflitos de dependências da avaliação comparativa**
Se uma avaliação comparativa falhar devido a conflitos de dependências com pacotes pré-instalados, crie um arquivo `pyproject.toml` no diretório da avaliação comparativa com restrições explícitas de versão. O contêiner instala as dependências da avaliação comparativa em um ambiente isolado para minimizar conflitos.
**As pontuações da avaliação parecem incorretas**
Se as pontuações da avaliação estiverem inesperadamente baixas ou inconsistentes, verifique as seguintes configurações na receita:
+ **temperature**: defina como `0.0` para resultados determinísticos e reprodutíveis
+ **max\_tokens**: certifique-se de que o valor seja grande o suficiente para o modelo concluir a resposta
+ **completion\_mode**: para modelos de base (não de chat), defina `completion_mode: true` na receita para usar prompts de modelos baseados em conclusão em vez do formato de chat
## Privacidade de dados
Os dados de avaliação são processados de forma diferente dependendo do provedor de inferência que você usa.
**Endpoint do SageMaker**
Ao usar um endpoint do SageMaker Inference, todos os dados permanecem na Conta da AWS. Os prompts de avaliação e as respostas do modelo não são enviados para locais externos à conta nem usados para melhorar os serviços da AWS. Nenhuma política de exclusão é necessária.
**Amazon Bedrock**
Quando você usa o Amazon Bedrock como provedor de inferência, os dados estão sujeitos à política de exclusão de serviços de IA da AWS. Para evitar que seus dados sejam usados para melhorar os serviços de IA da AWS, habilite a política de exclusão no nível do AWS Organizations. Para obter mais informações, consulte [Políticas de exclusão de serviços de IA](https://docs.aws.amazon.com//organizations/latest/userguide/orgs_manage_policies_ai-opt-out.html).
| Provedor de inferência | Recusa necessária | Detalhes |
| --- | --- | --- |
| Endpoint do SageMaker | Não | Os dados permanecem na conta. Não abrangido pela política de exclusão de serviços de IA. |
| Amazon Bedrock | Sim | Habilite a política de exclusão de serviços de IA da AWS no nível do Organizations para evitar o uso de dados para melhoria do serviço. |