# Avaliar modelos hospedados na inferência do SageMaker
<a name="nova-eval-on-sagemaker-inference"></a>

Este guia explica como avaliar seus modelos personalizados do Amazon Nova implantados nos endpoints de inferência do SageMaker usando o [Inspect AI](https://github.com/UKGovernmentBEIS/inspect_ai), um framework de avaliação de código aberto.

**nota**  
Para uma explicação prática, consulte o [caderno de início rápido do Inspect A do SageMaker](https://github.com/aws-samples/amazon-nova-samples/tree/main/customization/sagemaker-inference/sagemaker_inspect_quickstart.ipynb).

## Visão geral
<a name="nova-eval-sagemaker-overview"></a>

Você pode avaliar seus modelos personalizados do Amazon Nova implantados nos endpoints do SageMaker usando avaliações comparativas padronizadas da comunidade de pesquisa de IA. Essa abordagem permite que você:
+ Avalie modelos personalizados do Amazon Nova (ajustados, destilados ou adaptados de outra forma) em grande escala
+ Execute avaliações com inferência paralela em várias instâncias de endpoint
+ Compare a performance do modelo usando avaliações comparativas como MMLU, TruthfulQA e HumanEval
+ Integre-se à sua infraestrutura existente do SageMaker

## Modelos compatíveis
<a name="nova-eval-sagemaker-supported-models"></a>

O provedor de inferência do SageMaker trabalha com:
+ Modelos do Amazon Nova (Nova Micro, Nova Lite, Nova Lite 2)
+ Modelos implantados por meio de servidores de inferência compatíveis com vLLM ou OpenAI
+ Qualquer endpoint compatível com o formato da API OpenAI Chat Completions

## Pré-requisitos
<a name="nova-eval-sagemaker-prerequisites"></a>

Antes de começar, verifique se você tem:
+ Uma Conta da AWS com permissões para criar e invocar endpoints do SageMaker
+ Credenciais da AWS configuradas por meio da AWS CLI, das variáveis de ambiente ou dos perfis do IAM.
+ Python 3.9 ou posterior

**Permissões obrigatórias do IAM**

O usuário ou o perfil do IAM precisa das seguintes permissões:

```
{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sagemaker:InvokeEndpoint",
        "sagemaker:DescribeEndpoint"
      ],
      "Resource": "arn:aws:sagemaker:*:*:endpoint/*"
    }
  ]
}
```

## Etapa 1: implantar um endpoint do SageMaker
<a name="nova-eval-sagemaker-step1"></a>

Antes de executar avaliações, você precisa de um endpoint de inferência do SageMaker executando seu modelo.

Para obter instruções sobre como criar um endpoint de inferência do SageMaker com modelos do Amazon Nova, consulte [Conceitos básicos](nova-sagemaker-inference-getting-started.md).

Quando seu endpoint estiver no status `InService`, anote o nome dele para ser usado nos comandos de avaliação.

## Etapa 2: instalar dependências de avaliação
<a name="nova-eval-sagemaker-step2"></a>

Crie um ambiente virtual Python e instale os pacotes necessários.

```
# Create virtual environment
python3.12 -m venv venv
source venv/bin/activate

# Install uv for faster package installation
pip install uv

# Install Inspect AI and evaluation benchmarks
uv pip install inspect-ai inspect-evals

# Install AWS dependencies
uv pip install aioboto3 boto3 botocore openai
```

## Etapa 3: configurar as credenciais da AWS
<a name="nova-eval-sagemaker-step3"></a>

Escolha um dos seguintes métodos de autenticação:

**Opção 1: AWS CLI (recomendado)**

```
aws configure
```

Insira o ID da chave de acesso da AWS, a chave de acesso secreta e a região padrão quando solicitado.

**Opção 2: variáveis de ambiente**

```
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_DEFAULT_REGION=us-west-2
```

**Opção 3: perfil do IAM**

Se estiver sendo executada em cadernos do Amazon EC2 ou SageMaker, o perfil do IAM da instância será usado automaticamente.

**Verificar as credenciais**

```
import boto3

sts = boto3.client('sts')
identity = sts.get_caller_identity()
print(f"Account: {identity['Account']}")
print(f"User/Role: {identity['Arn']}")
```

## Etapa 4: instalar o provedor do SageMaker
<a name="nova-eval-sagemaker-step4"></a>

O provedor do SageMaker permite que o Inspect AI se comunique com seus endpoints do SageMaker. O processo de instalação do provedor é simplificado no [notebook de início rápido](https://github.com/aws-samples/amazon-nova-samples/tree/main/customization/sagemaker-inference/sagemaker_inspect_quickstart.ipynb).

## Etapa 5: fazer o download das avaliações comparativas
<a name="nova-eval-sagemaker-step5"></a>

Clone o repositório Inspect Evals para acessar as avaliações comparativas padrão:

```
git clone https://github.com/UKGovernmentBEIS/inspect_evals.git
```

Esse repositório inclui avaliações comparativas como:
+ MMLU e MMLU-Pro (conhecimento e raciocínio)
+ TruthfulQA (veracidade)
+ HumanEval (geração de código)
+ GSM8K (raciocínio matemático)

## Etapa 6: executar avaliações
<a name="nova-eval-sagemaker-step6"></a>

Execute uma avaliação usando seu endpoint do SageMaker:

```
cd inspect_evals/src/inspect_evals/

inspect eval mmlu_pro/mmlu_pro.py \
  --model sagemaker/my-nova-endpoint \
  -M region_name=us-west-2 \
  --max-connections 256 \
  --max-retries 100 \
  --display plain
```

**Principais parâmetros**


| Parâmetro | Padrão | Descrição | 
| --- | --- | --- | 
| --max-connections | 10 | Número de solicitações paralelas para o endpoint. Escale com contagem de instâncias (por exemplo, 10 instâncias × 25 = 250). | 
| --max-retries | 3 | Tente novamente as solicitações com falha. Use de 50 a 100 para avaliações grandes. | 
| -M region\$1name | us-east-1 | Região da AWS em que seu endpoint está implantado. | 
| -M read\$1timeout | 600 | Tempo limite da solicitação em segundos. | 
| -M connect\$1timeout | 60 | O tempo limite da conexão em segundos. | 

**Recomendações de ajuste**

Para um endpoint de várias instâncias:

```
# 10-instance endpoint example
--max-connections 250   # ~25 connections per instance
--max-retries 100       # Handle transient errors
```

Configurar `--max-connections` muito alto pode sobrecarregar o endpoint e gerar controle de utilização. Configurá-lo muito baixo subutiliza a capacidade.

## Etapa 7: visualizar os resultados
<a name="nova-eval-sagemaker-step7"></a>

Inicie o visualizador do Inspect AI para analisar os resultados da avaliação:

```
inspect view
```

O visualizador exibe:
+ Pontuações e métricas gerais
+ Resultados por amostra com respostas do modelo
+ Análise de erros e padrões de falha

## Gerenciar endpoints
<a name="nova-eval-sagemaker-managing-endpoints"></a>

**Atualizar um endpoint**

Para atualizar um endpoint existente com um novo modelo ou configuração:

```
import boto3

sagemaker = boto3.client('sagemaker', region_name=REGION)

# Create new model and endpoint configuration
# Then update the endpoint
sagemaker.update_endpoint(
    EndpointName=EXISTING_ENDPOINT_NAME,
    EndpointConfigName=NEW_ENDPOINT_CONFIG_NAME
)
```

**Excluir um endpoint**

```
sagemaker.delete_endpoint(EndpointName=ENDPOINT_NAME)
```

## Integração de avaliações comparativas personalizadas
<a name="nova-eval-sagemaker-custom-benchmarks"></a>

Você pode adicionar novas avaliações comparativas ao Inspect AI usando o seguinte fluxo de trabalho:

1. Estude o formato do conjunto de dados e as métricas de avaliação da avaliação comparativa

1. Analisar implementações semelhantes em `inspect_evals/`

1. Crie um arquivo de tarefa que converta registros do conjunto de dados em amostras do Inspect AI

1. Implemente solucionadores e pontuadores apropriados

1. Valide com a execução de um pequeno teste

Exemplo de estrutura de tarefa:

```
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("dataset_name", split="test"),
        solver=multiple_choice(),
        scorer=choice()
    )
```

## Solução de problemas
<a name="nova-eval-sagemaker-troubleshooting"></a>

**Problemas comuns**

**Tempos limite ou controle de utilização de endpoints**
+ Reduza `--max-connections`
+ Aumente `--max-retries`
+ Verifique as métricas do endpoint do CloudWatch quanto a problemas de capacidade

**Erros de autenticação**
+ Verifique se as credenciais da AWS estão configuradas corretamente
+ Verifique se as permissões do IAM incluem `sagemaker:InvokeEndpoint`

**Erros de modelo**
+ Verifique se o endpoint está no status `InService`
+ Verifique se o modelo é compatível com o formato da API OpenAI Chat Completions

## Recursos relacionados
<a name="nova-eval-sagemaker-related-resources"></a>
+ [Inspecionar a documentação de IA](https://inspect.ai-safety-institute.org.uk/)
+ [Inspecionar o repositório Evals](https://github.com/UKGovernmentBEIS/inspect_evals)
+ [Guia do desenvolvedor do SageMaker](https://docs.aws.amazon.com//sagemaker/latest/dg/whatis.html)
+ [Implantar modelos para inferência](https://docs.aws.amazon.com//sagemaker/latest/dg/deploy-model.html)
+ [Configurando a AWS CLI](https://docs.aws.amazon.com//cli/latest/userguide/cli-chap-configure.html)