Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Valuta con Inspect AI Container
Il contenitore SageMaker Inspect AI esegue valutazioni del modello LLM su SageMaker Training Jobs. Il contenitore utilizza [Inspect AI](https://inspect.ai-safety-institute.org.uk/) per fornire un processo di valutazione standardizzato per i modelli distribuiti su SageMaker endpoint di inferenza o Amazon Bedrock, inclusi i modelli Amazon Nova 1.0 (Micro, Lite, Pro) e 2.0 (Lite 2).
I precedenti [approcci di valutazione](https://docs.aws.amazon.com//nova/latest/nova2-userguide/nova-model-evaluation.html) (basati su [lighteval](https://github.com/huggingface/lighteval)) univano strettamente l'inferenza e la logica di valutazione offline, il che limitava la flessibilità nel modo in cui i modelli potevano essere serviti e testati. Il contenitore Inspect AI separa completamente la logica di valutazione dall'inferenza.
## Panoramica di
I vantaggi principali includono:
+ **Crea i tuoi benchmark**: scrivi attività di valutazione nel formato Inspect AI, quindi inserisci attività di valutazione specifiche del dominio senza dipendere da un team centralizzato per l'onboarding.
+ **Valuta con diverse opzioni di inferenza**: funziona con SageMaker Inference (endpoint esistente o creazione immediata), Amazon Bedrock e altri backend di inferenza in arrivo.
+ **Iterazione più rapida: passa dallo** sviluppo di benchmark alla valutazione della produzione senza modifiche all'infrastruttura. L'onboarding di nuovi benchmark, che in precedenza richiedeva giorni, avviene in pochi minuti.
+ **Esegui su larga scala**: concatena più benchmark in un unico lavoro, combina benchmark standard della libreria inspect-evals con attività personalizzate nello stesso lavoro.
+ **Un unico punto di accesso per tutte le tecniche di formazione**: indipendentemente dal fatto che il modello sia stato ottimizzato con SFT (SMTJ, SMHP), CPT (SMHP) o RFT (SMTJ, SMHP), il container lo valuta tramite la stessa interfaccia. È supportata anche la valutazione dei checkpoint intermedi dell'allenamento salvati in fasi specifiche (ad esempio, fase 500, fase 1000) indicando il percorso del checkpoint. `model_s3_uri`
### Come funziona
Fornisci due input al contenitore:
1. Un file di configurazione YAML (ricetta) che definisce il provider di inferenza, i benchmark e i parametri di valutazione
1. File di benchmark (script Python con `@task` decoratore) caricati su Amazon S3
Il contenitore gestisce la gestione degli endpoint, l'esecuzione della valutazione e la raccolta dei risultati. Al termine del processo di formazione, i risultati vengono scritti nella posizione di output S3 specificata.
## Immagine del contenitore
La tabella seguente elenca gli URI dell'immagine del contenitore Inspect AI per AWS regione.
| Region | URI dell'immagine del contenitore |
| --- | --- |
| 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 |
## Prerequisiti
Prima di iniziare, assicurati di disporre delle seguenti risorse e dei seguenti accessi.
| Requisito | Description |
| --- | --- |
| AWS account con SageMaker accesso | Un attivo Account AWS con le autorizzazioni per creare lavori di SageMaker formazione |
| Bucket S3 | Un bucket per archiviare le ricette di valutazione, i file di benchmark e i risultati di output |
| Ruolo di esecuzione IAM | Un ruolo che SageMaker puoi assumere per accedere alle tue risorse |
| SageMaker endpoint di inferenza o accesso ad Amazon Bedrock | Un endpoint del modello distribuito o un accesso al modello Amazon Bedrock per il modello che desideri valutare |
| AWS CLI o SageMaker Python SDK | Strumenti per inviare lavori di formazione e gestire le risorse |
| Prenotazione della capacità (modelli di grandi dimensioni) | Per i modelli che richiedono istanze accelerate (come p5 per Nova Lite 2), contatta il AWS supporto per riservare capacità per SageMaker Inference o Amazon Bedrock |
## Fase 1: configurare le autorizzazioni IAM
Il SageMaker Training Job viene eseguito con un ruolo di esecuzione fornito dall'utente. Questo ruolo richiede le autorizzazioni per leggere i benchmark da S3, scrivere risultati, richiamare l'endpoint di inferenza e scrivere log. CloudWatch
**1.1 Creare la politica di fiducia**
Salva quanto segue come`trust_policy.json`:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "sagemaker.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
**1.2 Creare il ruolo**
```
aws iam create-role \
--role-name InspectLensEvalRole \
--assume-role-policy-document file://trust_policy.json
```
**1.3 Allega la politica delle autorizzazioni**
Salva quanto segue con nome`eval_policy.json`, sostituendo tutti i valori segnaposto (`REGION`,`ACCOUNT_ID`, nomi dei bucket) con i tuoi valori:
```
{
"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/*"
}
]
}
```
Collegare la policy al ruolo:
```
aws iam put-role-policy \
--role-name InspectLensEvalRole \
--policy-name InspectLensEvalPolicy \
--policy-document file://eval_policy.json
```
## Passaggio 2: scrivi la tua ricetta di valutazione
La ricetta eval è un file di configurazione YAML che definisce il modo in cui il contenitore esegue le valutazioni. La ricetta specifica il fornitore di inferenza, i benchmark, i parametri di valutazione e le impostazioni di output.
Per esempi completi, consultate i seguenti notebook:
+ [ SageMaker Valuta un endpoint esistente](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/inspect_eval_container/eval_sagemaker_endpoint.ipynb)
+ [Esegui la valutazione con un endpoint gestito](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/inspect_eval_container/eval_managed_endpoint.ipynb)
+ [Valuta un modello Amazon Bedrock](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/inspect_eval_container/eval_bedrock_model.ipynb)
**Opzione A: valuta un endpoint esistente SageMaker **
Utilizzate questa opzione quando avete già un modello distribuito su un endpoint di SageMaker inferenza.
```
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/"
```
**Opzione B: crea un endpoint, valuta, quindi pulisci**
Usa questa opzione per fare in modo che il container distribuisca un modello base o perfezionato di Amazon Nova, esegua valutazioni e smonti automaticamente l'endpoint. Questo è l'approccio consigliato per esecuzioni di valutazione una tantum. Recupera il contenitore di SageMaker inferenza più recente dalla documentazione delle immagini del contenitore [Amazon Nova 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/"
```
**Nota su: `model_s3_uri`**
+ **Modelli Amazon Nova GA (checkpoint di base)**: ad esempio, `s3://escrow-nova-model-708977205387-us-east-1/nova-lite-2/prod/` — SageMaker gestisce l'accesso automaticamente, non sono necessarie autorizzazioni S3 aggiuntive.
+ **Modelli Amazon Nova personalizzati (punti di controllo post-formazione)**: `s3://customer-escrow-ACCOUNT_ID-SUFFIX/YOUR_RUN_NAME/outputs/checkpoints/step_N/` — questo è il percorso escrow bucket dei risultati del tuo lavoro di formazione.
**Opzione C: valutazione tramite Amazon Bedrock**
Utilizza questa opzione per valutare un modello disponibile tramite Amazon Bedrock senza gestire un 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/
```
**Configurazione dei benchmark**
La `benchmarks` sezione definisce quali attività di valutazione eseguire. È possibile concatenare più benchmark in un unico job.
| Campo | Obbligatorio | Predefinita | Description |
| --- | --- | --- | --- |
| name | Sì | — | Un nome descrittivo per l'esecuzione del benchmark |
| path | Sì | — | Percorso relativo al file Python di benchmark nella directory dei benchmark S3 |
| limit | No | Nessuno (tutti gli esempi) | Numero massimo di campioni da valutare. Utilizzare per i test prima delle esecuzioni complete. |
| epochs | No | 1 | Numero di volte in cui ripetere la valutazione ai fini della significatività statistica |
| task\_args | No | — | Key-value coppie passate come argomenti alla funzione task benchmark |
**Valuta la configurazione**
La `eval` sezione controlla il modo in cui il contenitore esegue le valutazioni.
| Parametro | Obbligatorio | Predefinita | Description |
| --- | --- | --- | --- |
| fail\_on\_error | No | false | Interrompi la valutazione se un campione fallisce. Impostato su true per una convalida rigorosa. |
| max\_connections | No | 10 | Numero di richieste parallele all'endpoint di inferenza |
| max\_retries | No | 3 | Numero di tentativi di ripetizione per richieste di inferenza non riuscite |
| timeout | No | 600 | Timeout della richiesta in secondi per ogni chiamata di inferenza |
| extra\_args | No | — | Coppie chiave-valore aggiuntive passate direttamente al comando Inspect AI eval |
**Parametri di decodifica**
Configura i parametri di decodifica del modello all'interno della sezione`eval.decoding`:
| Parametro | Obbligatorio | Predefinita | Description |
| --- | --- | --- | --- |
| temperature | No | 0,0 | Controlla la casualità nella generazione. Da utilizzare 0.0 per risultati di benchmark deterministici e riproducibili. |
| top\_p | No | 1.0 | Soglia di campionamento del nucleo. 1.0significa nessuna restrizione. |
| top\_k | No | -1 | Limita la scelta delle parole ai primi K token più probabili. -1disabilita questo filtro. |
| max\_tokens | No | 8192 | Numero massimo di token da generare per risposta. Aumento dei benchmark che richiedono lunghe catene di ragionamento. |
| reasoning\_effort | No | null | Controlla la profondità di ragionamento per i modelli che la supportano (ad esempio, modelli Amazon Nova con pensiero esteso). Opzioni: lowhigh, o null da disabilitare. |
**Configurazione dell'output**
La `output` sezione definisce dove e come vengono archiviati i risultati della valutazione.
| Campo | Obbligatorio | Predefinita | Description |
| --- | --- | --- | --- |
| s3\_path | Sì | — | URI S3 in cui vengono scritti i risultati della valutazione |
| output\_format | No | eval | Formato per i file dei risultati. Per informazioni sulle opzioni, consulta la tabella seguente. |
Sono disponibili i seguenti formati di output:
| Formato | Description |
| --- | --- |
| eval | Formato AI nativo di Inspect. Compatibile con inspect view per l'analisi interattiva. |
| csv | Comma-separated valori. Adatto per l'analisi di fogli di calcolo e le pipeline di dati. |
| jsonl | Formato JSON Lines. Un oggetto JSON per riga per l'elaborazione in streaming. |
| json | Formato JSON standard. Risultati completi in un unico file strutturato. |
**Configurazione MLFlow**
Facoltativamente, è possibile registrare le metriche di valutazione su un server di tracciamento MLFlow. Aggiungi la `tracking` sezione alla tua ricetta:
```
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 | Obbligatorio | Predefinita | Description |
| --- | --- | --- | --- |
| mlflow\_tracking\_arn | No | null | ARN del server di tracciamento SageMaker MLFlow. L'impostazione di questo abilita la registrazione MLFlow. Ometti o imposta su per disabilitare. null |
| mlflow\_experiment\_name | No | ispeziona l'obiettivo | Nome dell'esperimento MLFlow con cui registrare le esecuzioni. |
| mlflow\_tracing | No | true | Whentrue, registra le request/response tracce complete per ogni campione. |
| mlflow\_log\_artifacts | No | true | Whentrue, carica i file di .eval registro come artefatti MLFlow. |
**Riferimento completo alla ricetta**
L'esempio seguente mostra una ricetta completa con tutte le opzioni di configurazione disponibili:
```
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
```
## Fase 3: Preparare i file di benchmark
I benchmark sono file Python che utilizzano il decoratore Inspect `@task` AI per definire le attività di valutazione. Il [repository inspect-evals](https://github.com/UKGovernmentBEIS/inspect_evals) fornisce oltre 128 benchmark pronti all'uso, oppure puoi scriverne di tuoi.
**Esempio di benchmark**
L'esempio seguente mostra un benchmark minimo che valuta le prestazioni a scelta multipla su un set di dati: 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(),
)
```
**Dipendenze**
Se il tuo benchmark necessita di dipendenze aggiuntive, includi un `pyproject.toml` or `requirements.txt` nella stessa directory S3:
```
[project]
name = "my-benchmark"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
"datasets>=2.14.0",
]
```
**Pre-installed pacchetti**
Il contenitore include i seguenti pacchetti. Non è necessario elencarli nel tuo`pyproject.toml`.
| Pacchetto | Versione |
| --- | --- |
| Python | 3.12 |
| ispect-ai | 0,3220 |
| boto3 | 1,40,61 |
| aio bot 3 | 15.5.0 |
| apri | 2.36.0 |
| mlflow | 3.12.0 |
| pyaml | 6.0.3 |
**Selezione delle attività**
Il `tasks` campo della ricetta controlla quali attività eseguire all'interno di un file di benchmark.
| Configurazione | Esempio | Comportamento |
| --- | --- | --- |
| Vuoto tasks | tasks: [] | Esegue tutte le attività definite nel file di benchmark |
| Filtro dei nomi | tasks: ["algebra"] | Esegue attività il cui nome contiene la sottostringa «algebra» |
| limit | limit: 50 | Limita il numero di campioni valutati per attività |
| epochs | epochs: 3 | Ripete la valutazione più volte per misurare la varianza |
## Fase 4: Preparare la struttura S3
La seguente struttura è un consiglio per mantenere organizzate configurazioni, benchmark e risultati. Puoi puntare il contenitore verso qualsiasi posizione S3: la struttura stessa non è necessaria.
```
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
```
Carica i tuoi file su 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
```
## Fase 5: Invia il lavoro di formazione
Invia un SageMaker Training Job per eseguire la valutazione. Puoi usare AWS CLI o l'SDK SageMaker Python.
**Opzione 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
```
**Opzione 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/",
)
]
)
```
**Parametri chiave**
| Parametro | Valore | Description |
| --- | --- | --- |
| TrainingImage | 763104351884.dkr.ecr.us-east-1.amazonaws.com/sagemaker-inspect-ai:latest | L'immagine del contenitore Inspect AI |
| InstanceType | ml.m5.large | Tipo di istanza Orchestrator (non l'istanza di inferenza) |
| VolumeSizeInGB | 30 | Archiviazione per dati e log di benchmark |
| MaxRuntimeInSeconds | 86400 | Durata massima del lavoro (24 ore) |
| ChannelName | config | Canale di input contenente i file di ricette e benchmark |
**Guida al tipo di istanza di Orchestrator**
L'istanza del processo di formazione esegue la logica di orchestrazione della valutazione, non l'inferenza del modello. Scegliete un tipo di istanza in base al carico di lavoro di valutazione.
| Tipo di istanza | Caso d’uso | Linee guida |
| --- | --- | --- |
| ml.m5.large | Impostazione predefinita consigliata | Sufficiente per la maggior parte dei carichi di lavoro di valutazione con parallelismo moderato |
| ml.m5.4xlarge | Suite di benchmark di grandi dimensioni | Da utilizzare quando si eseguono molti benchmark con valori elevati max\_connections |
| ml.c5.large | Cost-sensitive | Alternativa a basso costo per valutazioni semplici con basso parallelismo |
**Variabili di ambiente**
È possibile passare variabili di ambiente al contenitore per l'autenticazione o la configurazione. Aggiungi il `--environment` parametro al AWS CLI comando:
```
aws sagemaker create-training-job \
...
--environment '{
"HF_TOKEN": "hf_your_token_here",
"HF_HUB_DOWNLOAD_TIMEOUT": "300"
}'
```
## Fase 6: Monitora il lavoro
Dopo aver inviato il lavoro di formazione, puoi monitorarne l'avanzamento tramite AWS CLI o CloudWatch Logs.
**Controlla lo stato del lavoro**
```
aws sagemaker describe-training-job \
--training-job-name your-job-name \
--query "TrainingJobStatus" \
--output text
```
**Registri di streaming**
```
aws logs tail /aws/sagemaker/TrainingJobs \
--log-stream-name-prefix your-job-name \
--follow
```
**Cosa aspettarsi dai log**
I log del contenitore mostrano l'avanzamento nelle seguenti fasi:
1. **Avvio**: inizializzazione del contenitore e convalida della configurazione
1. Download **di benchmark: download** di file di benchmark e installazione delle dipendenze
1. **Configurazione dell'endpoint**: creazione o connessione all'endpoint di inferenza
1. **Valutazione**: esecuzione di attività di benchmark con indicatori di avanzamento
1. **Caricamento dei risultati**: scrittura dei risultati su S3 e, facoltativamente, registrazione su MLFlow
1. **Pulizia: eliminazione degli endpoint** temporanei se `cleanup_endpoint: true`
**Tempistiche stimate**
| Stage | Durata stimata |
| --- | --- |
| Avvio del contenitore | 2—5 minuti |
| Creazione dell'endpoint (se applicabile) | 15-30 minuti |
| Valutazione | Varia in base alla dimensione del benchmark e alla latenza del modello |
| Pulizia | 1—2 minuti |
## Fase 7: Visualizzare e interpretare i risultati
Al termine del lavoro, visualizza i risultati della valutazione.
**Visualizza con Inspect AI**
Usa il visualizzatore Inspect AI per esplorare in modo interattivo i risultati direttamente da S3:
```
inspect view --log-dir s3://your-bucket/eval-results/
```
Questo comando apre un'interfaccia web locale in cui è possibile sfogliare i punteggi, visualizzare singoli campioni e confrontare le esecuzioni.
**Scarica e condividi**
Per scaricare i risultati localmente:
```
aws s3 cp s3://your-bucket/eval/output/ ./results/ --recursive
INSPECT_LOG_DIR=./results inspect view
```
**Estensione VS Code**
L'[estensione Inspect AI VS Code](https://inspect.aisi.org.uk/vscode.html) ti consente di sfogliare i log di valutazione direttamente da S3 senza prima scaricarli.
1. Installa l'estensione dal marketplace VS Code (cerca «Inspect AI»)
1. Nella barra delle attività di Inspect, individua il riquadro Registri e scegli l'icona della cartella
1. Inserisci il tuo percorso S3: `s3://your-bucket/eval-results/`
**Struttura di output**
Ogni valutazione produce un file di `.eval` registro che contiene le seguenti sezioni:
+ `results.scores`— Punteggi aggregati per ogni metrica
+ `samples`— Esempi di valutazione individuali con input, output e punteggi
+ `stats`— Statistiche di runtime, tra cui l'utilizzo e la latenza dei token
+ `eval.config`— La configurazione utilizzata per l'esecuzione della valutazione
**Visualizzazione dei risultati in MLFlow (opzionale)**
Se hai configurato MLFlow nella tua ricetta, genera un URL predefinito per accedere al server di tracciamento:
```
aws sagemaker create-presigned-mlflow-tracking-server-url \
--tracking-server-name my-server \
--region us-west-2
```
Apri l'URL restituito nel browser per visualizzare le metriche, confrontare le esecuzioni e analizzare le tendenze tra le valutazioni.
## Benchmark disponibili
Il contenitore Inspect AI funziona con qualsiasi benchmark scritto nel formato di attività Inspect AI. Il [repository inspect-evals](https://github.com/UKGovernmentBEIS/inspect_evals) fornisce oltre 128 benchmark pronti all'uso che coprono aree come ragionamento, conoscenza, codifica e sicurezza.
[Per scrivere i tuoi benchmark, consulta la documentazione sulla scrittura delle attività di Inspect AI.](https://inspect.aisi.org.uk/tasks.html) Se trovi un benchmark pubblico che non è ancora disponibile in inspect-evals, puoi utilizzare il [prompt di onboarding dell'assistente AI](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/ai_assisted_benchmark_creation.md) per convertirlo nel formato Inspect AI.
## Valutazioni agentiche
I benchmark Agentic testano la capacità di un modello di completare attività in più fasi che richiedono l'uso di strumenti, la pianificazione e il ragionamento iterativo. Queste valutazioni simulano scenari reali in cui il modello deve utilizzare strumenti, interpretare i risultati e decidere le azioni successive.
**Requisiti degli endpoint**
Le valutazioni degli agenti richiedono endpoint che supportino le seguenti funzionalità:
+ **Richiamo di strumenti**: l'endpoint deve supportare la chiamata di funzione per consentire al modello di richiamare gli strumenti durante la valutazione
+ **Ampie dimensioni del contesto**: Multi-turn le conversazioni con i risultati degli strumenti richiedono una lunghezza del contesto sufficiente per conservare la cronologia delle conversazioni
**SageMaker Configurazione degli endpoint di inferenza**
Quando utilizzi un endpoint di SageMaker inferenza per le valutazioni agentiche, configura le seguenti variabili di ambiente sull'endpoint:
| Variabile di ambiente | Valore | Description |
| --- | --- | --- |
| ENABLE\_TOOL\_CALLING | True | Attiva il supporto per le chiamate agli strumenti sull'endpoint di inferenza |
| CONTEXT\_LENGTH | Sufficiente per il multigiro | Impostato su un valore sufficientemente ampio da consentire conversazioni a più turni con i risultati degli strumenti |
Per informazioni sulla configurazione degli endpoint Amazon Nova su SageMaker Inference, consulta [Deploy Amazon Nova](https://docs.aws.amazon.com//nova/latest/userguide/deploy-sagemaker.html) models on. SageMaker [Per informazioni sulle caratteristiche e sulla configurazione del contenitore, consulta Funzionalità del contenitore.](https://docs.aws.amazon.com//nova/latest/userguide/container-features.html)
**Endpoint Amazon Bedrock**
Per gli endpoint Amazon Bedrock, la chiamata agli strumenti è supportata nativamente per i modelli compatibili. Per ulteriori informazioni, consulta [Uso dello strumento con Amazon Bedrock](https://docs.aws.amazon.com//bedrock/latest/userguide/tool-use.html).
**Guida introduttiva alle valutazioni degli agenti**
Per eseguire le valutazioni agentiche, completa i seguenti prerequisiti:
1. Implementa un endpoint con le chiamate agli strumenti abilitate
1. Scegliete un benchmark agentic dal [repository inspect-evals](https://github.com/UKGovernmentBEIS/inspect_evals) (cercate i benchmark che utilizzano risolutori che richiedono strumenti)
1. Configura `timeout` la tua ricetta con i `max_tokens` valori e i valori appropriati per le interazioni a più turni
**Endpoint Amazon Bedrock**
+ Per la configurazione e la distribuzione complete, consulta [Amazon Bedrock endpoint](https://docs.aws.amazon.com//bedrock/latest/userguide/endpoints.html).
+ Per il supporto per le chiamate agli strumenti, consulta la sezione relativa alle chiamate agli strumenti lato client in [Uso degli strumenti con Amazon](https://docs.aws.amazon.com//bedrock/latest/userguide/tool-use.html) Bedrock.
**Taccuini di esempio**
Il seguente taccuino dimostra l'esecuzione di un benchmark agentico che richiama strumenti con il contenitore Inspect AI:
+ [tau-bench (basato sul lavoro): valuta il ragionamento basato sugli](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/inspect_eval_container/eval_tau_bench.ipynb) strumenti sulle attività di assistenza clienti utilizzando il contenitore Inspect AI
Per i benchmark agentici che richiedono una sandbox Docker, usa l'SDK Inspect AI:
+ [SWE-bench con Inspect AI SDK](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/local_inspect_sdk/eval_swe_bench.ipynb): valuta le funzionalità di ingegneria del software utilizzando la sandbox Docker
**Importante**
I benchmark agentici che richiedono una sandbox Docker (ad esempio SWE-bench) non sono supportati nell'esperienza del contenitore Inspect AI. L'ambiente SageMaker Training Job non fornisce Docker-in-Docker funzionalità. Per eseguire questi benchmark, utilizza l'[SDK Inspect AI](nova-eval-on-sagemaker-inference.md) in un ambiente di calcolo con accesso Docker (ad esempio, un'istanza o un notebook Amazon EC2 con Docker installato). SageMaker
## Risoluzione dei problemi
Questa sezione fornisce soluzioni per problemi comuni relativi all'esecuzione di valutazioni con il contenitore Inspect AI.
**Suggerimento rapido per l'iterazione**
Prima di inviare un SageMaker Training Job, testate i benchmark localmente con l'SDK Inspect AI. Eseguilo `inspect eval my_benchmark.py` sul tuo computer locale per convalidare le definizioni delle attività, le dipendenze e la logica di punteggio prima di eseguirle su larga scala.
**InsufficientInstanceCapacity error**
Questo errore si verifica quando AWS la capacità non è sufficiente per il tipo di istanza richiesto nella regione.
+ Prova un tipo di istanza diverso o invia il lavoro in un'altra AWS regione
+ Utilizza un tipo di istanza diverso (ad esempio, `ml.m5.xlarge` anziché`ml.m5.large`)
+ Riprova la richiesta dopo alcuni minuti
**AccessDenied error**
Se il processo di formazione fallisce con un errore di accesso negato, verifica quanto segue:
+ L'ARN del ruolo nella configurazione del lavoro è corretto
+ La politica di fiducia consente di `sagemaker.amazonaws.com` assumere il ruolo
+ L'utente o il ruolo dispone dell'`iam:PassRole`autorizzazione per il ruolo di esecuzione
+ Il ruolo di esecuzione dispone delle autorizzazioni per accedere al bucket S3, all'endpoint di inferenza o al modello Amazon Bedrock
**La creazione degli endpoint non riesce**
Quando si utilizza `cleanup_endpoint: true` con la creazione automatica di endpoint, potrebbero verificarsi i seguenti problemi:
| Errore | Soluzione |
| --- | --- |
| ResourceLimitExceeded | Richiedi un aumento della quota di servizio per il tipo di istanza di inferenza nella tua regione |
| OutOfMemoryError | Utilizza un tipo di istanza di inferenza più grande o riduci le dimensioni del modello |
| Errato model\_s3\_uri | Verifica che il percorso S3 punti a una directory di artefatti del modello valida |
| URI dell'immagine di inferenza errato | Verifica che l'URI dell'immagine sia corretto per la tua regione e il framework del modello |
| Endpoint bloccato in fase di creazione | Controlla CloudWatch i log per l'endpoint. Il modello potrebbe non superare i controlli di integrità. Aumenta MaxRuntimeInSeconds se l'endpoint richiede più tempo. |
**HuggingFace timeout di download**
Se i benchmark che scaricano i set di dati dall' HuggingFace Hub sono scaduti, imposta la variabile di `HF_HUB_DOWNLOAD_TIMEOUT` ambiente su un valore più alto (in secondi):
```
--environment '{"HF_HUB_DOWNLOAD_TIMEOUT": "600"}'
```
**Job interrotto ma l'endpoint è ancora in esecuzione**
Se il processo di formazione viene interrotto prima del completamento della pulizia, l'endpoint di inferenza potrebbe rimanere attivo. Elimina manualmente l'endpoint per evitare addebiti continui:
```
# 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
```
**Conflitti di dipendenza da benchmark**
Se un benchmark fallisce a causa di conflitti di dipendenza con pacchetti preinstallati, creane uno `pyproject.toml` nella directory del benchmark con vincoli di versione espliciti. Il contenitore installa le dipendenze dei benchmark in modo isolato per ridurre al minimo i conflitti.
**I punteggi di valutazione sembrano sbagliati**
Se i punteggi di valutazione sono inaspettatamente bassi o incoerenti, controlla le seguenti impostazioni nella tua ricetta:
+ **temperatura**: impostata `0.0` per risultati deterministici e riproducibili
+ **max\_tokens** — Assicurati che il valore sia sufficientemente grande da consentire al modello di completare la sua risposta
+ **completion\_mode** — Per i modelli base (non legati alla chat), impostate `completion_mode: true` nella vostra ricetta l'utilizzo di istruzioni in stile completamento anziché in formato chat
## Privacy dei dati
I dati di valutazione vengono gestiti in modo diverso a seconda del provider di inferenza utilizzato.
**SageMaker endpoint**
Quando utilizzi un endpoint SageMaker Inference, tutti i dati rimangono all'interno del tuo. Account AWS Le richieste di valutazione e le risposte dei modelli non vengono inviate all'esterno dell'account e non vengono utilizzate per migliorare i servizi. AWS Non è necessaria alcuna politica di opt-out.
**Amazon Bedrock**
Quando utilizzi Amazon Bedrock come provider di inferenza, i tuoi dati sono soggetti alla politica sui servizi AWS Opt-Out AI. Per evitare che i tuoi dati vengano utilizzati per migliorare i servizi di AWS intelligenza artificiale, abilita la politica di opt-out a livello di AWS Organizations. Per ulteriori informazioni, consulta le politiche di [opt-out dei servizi di intelligenza artificiale](https://docs.aws.amazon.com//organizations/latest/userguide/orgs_manage_policies_ai-opt-out.html).
| Fornitore di inferenze | Opt-out richiesto | Informazioni |
| --- | --- | --- |
| SageMaker endpoint | No | I dati rimangono nel tuo account. Non coperto dalla politica di opt-out dell'IA. |
| Amazon Bedrock | Sì | Abilita la Opt-Out politica sui servizi di AWS intelligenza artificiale a livello di Organizzazioni per impedire l'uso dei dati per il miglioramento del servizio. |