# Interface do SageMaker
Os modelos personalizados do Amazon Nova agora estão disponíveis na inferência do SageMaker. Com o Amazon Nova no SageMaker, você pode começar a obter predições ou inferências dos modelos treinados personalizados do Amazon Nova. O SageMaker oferece uma ampla seleção de infraestrutura de machine learning e opções de implantação de modelos para ajudar a atender a todas as suas necessidades de inferência de ML. Com a inferência do SageMaker, você pode escalar a implantação de modelos, gerenciar os modelos em produção de forma mais eficaz e reduzir a carga operacional.
O SageMaker fornece várias opções de inferência, como endpoints em tempo real para obter inferência de baixa latência e endpoints assíncronos para lotes de solicitações. Ao utilizar a opção de inferência apropriada para o caso de uso, você pode garantir a eficiência da implantação e inferência do modelo. Para obter mais informações sobre a inferência do SageMaker, consulte [Implantar modelos para inferência](https://docs.aws.amazon.com//sagemaker/latest/dg/deploy-model.html).
**Importante**
Somente modelos personalizados full-rank e modelos mesclados com LoRA são compatíveis com a inferência do SageMaker. Para modelos LoRA e modelos de base não mesclados, use o Amazon Bedrock.
## Recursos
Os seguintes recursos estão disponíveis para modelos do Amazon Nova na inferência do SageMaker:
**Recursos dos modelos**
+ Geração de texto
**Implantação e escalabilidade**
+ Endpoints em tempo real com seleção de instância personalizada
+ Ajuste de escala automático: ajuste automaticamente a capacidade com base nos padrões de tráfego para otimizar os custos e a utilização da GPU. Para obter mais informações, consulte [Ajuste de escala automático de modelos do Amazon SageMaker](https://docs.aws.amazon.com//sagemaker/latest/dg/endpoint-auto-scaling.html).
+ Suporte à API de streaming para geração de tokens em tempo real
**Monitoramento e otimização**
+ Integração do Amazon CloudWatch para monitoramento e alertas
+ Otimização de latência com reconhecimento de zonas de disponibilidade por meio da configuração de VPC
**ferramentas de desenvolvimento da**
+ Suporte da AWS CLI: para obter mais informações, consulte [Referência de comandos da AWS CLI para o SageMaker](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/).
+ Integração de cadernos via suporte do SDK
## Modelos e instâncias compatíveis
Ao criar seus endpoints de inferência do SageMaker, você pode definir duas variáveis de ambiente para configurar sua implantação: `CONTEXT_LENGTH` e `MAX_CONCURRENCY`.
+ `CONTEXT_LENGTH`: tamanho máximo total do token (entrada \$1 saída) por solicitação
+ `MAX_CONCURRENCY`: número máximo de solicitações simultâneas atendidas pelo endpoint
A tabela a seguir lista os modelos compatíveis do Amazon Nova, os tipos de instâncias e as configurações compatíveis. Os valores de MAX\$1CONCURRENCY representam a simultaneidade máxima suportada para cada configuração CONTEXT\$1LENGTH:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/nova/latest/nova2-userguide/nova-model-sagemaker-inference.html)
**nota**
Os valores de MAX\$1CONCURRENCY mostrados são limites máximos para cada configuração CONTEXT\$1LENGTH. Você pode usar tamanhos de contexto menores com a mesma simultaneidade, mas exceder esses valores fará com que a criação do endpoint do SageMaker falhe.
Por exemplo, no Amazon Nova Micro com ml.g5.12xlarge:
`CONTEXT_LENGTH=2000`, `MAX_CONCURRENCY=32` → Válido
`CONTEXT_LENGTH=8000`, `MAX_CONCURRENCY=32` → Rejeitado (o limite de simultaneidade é 16 no tamanho de contexto 8000)
`CONTEXT_LENGTH=8000`, `MAX_CONCURRENCY=4` → Válido
`CONTEXT_LENGTH=8000`, `MAX_CONCURRENCY=16` → Válido
`CONTEXT_LENGTH=10000` → Rejeitado (a extensão máxima do contexto é 8.000 nesta instância)
## Regiões do AWS compatíveis
A tabela abaixo lista as regiões da AWS em que os modelos do Amazon Nova estão disponíveis na inferência do SageMaker:
****
| Nome da Região | Código da região | Disponibilidade |
| --- | --- | --- |
| Leste dos EUA (Norte da Virgínia) | us-east-1 | Available (Disponível) |
| Oeste dos EUA (Oregon) | us-west-2 | Available (Disponível) |
## Imagens de contêineres compatíveis
A tabela a seguir lista os URIs de imagens de contêineres para modelos do Amazon Nova na inferência do SageMaker por região. Duas tags de imagem estão disponíveis para cada região: uma tag versionada (`v1.0.0`) e uma tag mais recente (`SM-Inference-latest`). Para implantações de produção, recomendamos usar a tag versionada.
****
| Região | URIs das imagens de contêineres |
| --- | --- |
| us-east-1 | 708977205387.dkr.ecr.us-east-1.amazonaws.com/nova-inference-repo:SM-Inference-latest |
| us-west-2 | 176779409107.dkr.ecr.us-west-2.amazonaws.com/nova-inference-repo:SM-Inference-latest |
## Práticas recomendadas
Para verificar as práticas recomendadas de implantação e gerenciamento de modelos no SageMaker, consulte [Práticas recomendadas do SageMaker](https://docs.aws.amazon.com//sagemaker/latest/dg/best-practices.html).
## Suporte
Para obter suporte e resolver problemas com os modelos do Amazon Nova na inferência do SageMaker, entre em contato com o AWS Support pelo console ou seu gerente de conta da AWS.
**Topics**
+ [Recursos](#nova-sagemaker-inference-features)
+ [Modelos e instâncias compatíveis](#nova-sagemaker-inference-supported)
+ [Regiões do AWS compatíveis](#nova-sagemaker-inference-regions)
+ [Imagens de contêineres compatíveis](#nova-sagemaker-inference-container-images)
+ [Práticas recomendadas](#nova-sagemaker-inference-best-practices)
+ [Suporte](#nova-sagemaker-inference-support)
+ [Conceitos básicos](nova-sagemaker-inference-getting-started.md)
+ [Referência da API](nova-sagemaker-inference-api-reference.md)
+ [Avaliar modelos hospedados na inferência do SageMaker](nova-eval-on-sagemaker-inference.md)
+ [Implantação de modelos do Amazon Nova Forge na detecção de abusos da Inferência do Amazon SageMaker](nova-sagemaker-inference-abuse-detection.md)
# Conceitos básicos
Este guia mostra como implantar modelos personalizados do Amazon Nova nos endpoints em tempo real do SageMaker, configurar parâmetros de inferência e invocar seus modelos para testes.
## Pré-requisitos
Confira abaixo os pré-requisitos para implantar modelos do Amazon Nova na inferência do SageMaker:
+ Crie uma Conta da AWS: se você ainda não tiver uma, consulte [Criar uma conta da AWS](https://docs.aws.amazon.com//sagemaker/latest/dg/gs-set-up.html#sign-up-for-aws).
+ Permissões necessárias do IAM - certifique-se de que seu usuário ou perfil do IAM tenha as seguintes políticas gerenciadas:
+ `AmazonSageMakerFullAccess`
+ `AmazonS3FullAccess`
+ Versões obrigatórias de SDKs/CLI - as seguintes versões de SDK foram testadas e validadas com modelos do Amazon Nova na inferência do SageMaker:
+ SageMaker Python SDK v3.0.0\$1 (`sagemaker>=3.0.0`) para abordagem de API baseada em recursos.
+ Boto3 versão 1.35.0\$1 (`boto3>=1.35.0`) para chamadas diretas de API. Os exemplos neste guia usam essa abordagem.
+ Aumento da cota de serviço: solicite um aumento da cota de serviço do Amazon SageMaker para o tipo de instância de ML que você planeja usar para seu endpoint da Inferência do SageMaker (por exemplo, `ml.p5.48xlarge for endpoint usage`). Para obter uma lista dos tipos de instâncias compatíveis, consulte [Modelos e instâncias compatíveis](nova-model-sagemaker-inference.md#nova-sagemaker-inference-supported). Para solicitar um aumento, consulte [Solicitar um aumento de cota](https://docs.aws.amazon.com//servicequotas/latest/userguide/request-quota-increase.html). Para obter mais informações sobre cotas de instâncias do SageMaker, consulte [Endpoints e cotas do SageMaker](https://docs.aws.amazon.com//general/latest/gr/sagemaker.html).
## Etapa 1: configurar as credenciais da AWS
Configure suas credenciais da AWS usando um dos seguintes métodos:
**Opção 1: AWS CLI (recomendado)**
```
aws configure
```
Insira o ID da chave de acesso da AWS, a chave secreta e nome da região padrão quando solicitado.
**Opção 2: arquivo de credenciais da AWS**
Crie ou edite `~/.aws/credentials`:
```
[default]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY
```
**Opção 3: variáveis de ambiente**
```
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
```
**nota**
Para obter mais informações sobre as credenciais da AWS, consulte [Definições do arquivo de credenciais e configurações](https://docs.aws.amazon.com//cli/latest/userguide/cli-configure-files.html).
**Inicializar clientes da AWS**
Crie um script ou caderno Python com o código abaixo para inicializar o AWS SDK e verificar suas credenciais:
```
import boto3
# AWS Configuration - Update these for your environment
REGION = "us-east-1" # Supported regions: us-east-1, us-west-2
AWS_ACCOUNT_ID = "YOUR_ACCOUNT_ID" # Replace with your AWS account ID
# Initialize AWS clients using default credential chain
sagemaker = boto3.client('sagemaker', region_name=REGION)
sts = boto3.client('sts')
# Verify credentials
try:
identity = sts.get_caller_identity()
print(f"Successfully authenticated to AWS Account: {identity['Account']}")
if identity['Account'] != AWS_ACCOUNT_ID:
print(f"Warning: Connected to account {identity['Account']}, expected {AWS_ACCOUNT_ID}")
except Exception as e:
print(f"Failed to authenticate: {e}")
print("Please verify your credentials are configured correctly.")
```
Se a autenticação tiver êxito, você deverá ver um resultado confirmando o ID da sua conta da AWS.
## Etapa 2: criar um perfil de execução do SageMaker
Um perfil de execução do SageMaker é um perfil do IAM que concede ao SageMaker permissões para acessar recursos da AWS em seu nome, como buckets do Amazon S3 para artefatos de modelos e o CloudWatch para registro em log.
**Criação do perfil de execução**
**nota**
A criação de perfis do IAM requer as permissões `iam:CreateRole` e `iam:AttachRolePolicy`. Antes de continuar, certifique-se de que seu usuário ou perfil do IAM tenha essas permissões.
O código abaixo cria um perfil do IAM com as permissões necessárias para implantar modelos personalizados do Amazon Nova:
```
import json
# Create SageMaker Execution Role
role_name = f"SageMakerInference-ExecutionRole-{AWS_ACCOUNT_ID}"
trust_policy = {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {"Service": "sagemaker.amazonaws.com"},
"Action": "sts:AssumeRole"
}
]
}
iam = boto3.client('iam', region_name=REGION)
# Create the role
role_response = iam.create_role(
RoleName=role_name,
AssumeRolePolicyDocument=json.dumps(trust_policy),
Description='SageMaker execution role with S3 and SageMaker access'
)
# Attach required policies
iam.attach_role_policy(
RoleName=role_name,
PolicyArn='arn:aws:iam::aws:policy/AmazonSageMakerFullAccess'
)
iam.attach_role_policy(
RoleName=role_name,
PolicyArn='arn:aws:iam::aws:policy/AmazonS3FullAccess'
)
SAGEMAKER_EXECUTION_ROLE_ARN = role_response['Role']['Arn']
print(f"Created SageMaker execution role: {SAGEMAKER_EXECUTION_ROLE_ARN}")
```
**Uso de um perfil de execução existente (opcional)**
Se já tiver um perfil de execução do SageMaker, você poderá usá-lo:
```
# Replace with your existing role ARN
SAGEMAKER_EXECUTION_ROLE_ARN = "arn:aws:iam::YOUR_ACCOUNT_ID:role/YOUR_EXISTING_ROLE_NAME"
```
Para encontrar perfis existentes do SageMaker em sua conta:
```
iam = boto3.client('iam', region_name=REGION)
response = iam.list_roles()
sagemaker_roles = [role for role in response['Roles'] if 'SageMaker' in role['RoleName']]
for role in sagemaker_roles:
print(f"{role['RoleName']}: {role['Arn']}")
```
**Importante**
O perfil de execução deve ter uma relação de confiança com `sagemaker.amazonaws.com` e permissões para acessar os recursos do Amazon S3 e do SageMaker.
Para obter mais informações sobre perfis de execução do SageMaker, consulte [Perfis do SageMaker](https://docs.aws.amazon.com//sagemaker/latest/dg/sagemaker-roles.html).
## Etapa 3: configurar parâmetros de modelos
Configure os parâmetros de implantação para seu modelo do Amazon Nova. Essas configurações controlam o comportamento do modelo, a alocação de recursos e as características de inferência. Para ver uma lista dos tipos de instâncias compatíveis e dos valores de CONTEXT\$1LENGTH e MAX\$1CONCURRENCY compatíveis para cada um, consulte [Modelos e instâncias compatíveis](nova-model-sagemaker-inference.md#nova-sagemaker-inference-supported).
**Parâmetros obrigatórios**
+ `IMAGE`: o URI da imagem do contêiner do Docker para o contêiner de inferência do Amazon Nova. Será fornecido pela AWS.
+ `CONTEXT_LENGTH`: tamanho do contexto do modelo.
+ `MAX_CONCURRENCY`: número máximo de sequências por iteração; define o limite de quantas solicitações (prompts) de usuários individuais podem ser processadas simultaneamente em um único lote na GPU. Intervalo: inteiro maior que 0.
**Parâmetros opcionais de geração**
+ `DEFAULT_TEMPERATURE`: controla a randomização na geração. Intervalo: de 0,0 a 2,0 (0,0 = determinístico, maior = mais randomizado).
+ `DEFAULT_TOP_P`: limite de amostragem de núcleo para a seleção de tokens. Intervalo: de 1e-10 a 1,0.
+ `DEFAULT_TOP_K`: limita a seleção de tokens aos K tokens mais prováveis. Intervalo: inteiro -1 ou maior (-1 = sem limite).
+ `DEFAULT_MAX_NEW_TOKENS`: número máximo de tokens a serem gerados na resposta (ou seja, máximo de tokens de saída). Intervalo: inteiro 1 ou maior.
+ `DEFAULT_LOGPROBS`: número de probabilidades logarítmicas a serem retornadas por token. Intervalo: inteiro de 1 a 20.
**Configure sua implantação**
```
# AWS Configuration
REGION = "us-east-1" # Must match region from Step 1
# ECR Account mapping by region
ECR_ACCOUNT_MAP = {
"us-east-1": "708977205387",
"us-west-2": "176779409107"
}
# Container Image
IMAGE = f"{ECR_ACCOUNT_MAP[REGION]}.dkr.ecr.{REGION}.amazonaws.com/nova-inference-repo:SM-Inference-latest"
print(f"IMAGE = {IMAGE}")
# Model Parameters
CONTEXT_LENGTH = "16000" # Maximum total context length
MAX_CONCURRENCY = "2" # Maximum concurrent sequences
# Optional: Default generation parameters (uncomment to use)
DEFAULT_TEMPERATURE = "0.0" # Deterministic output
DEFAULT_TOP_P = "1.0" # Consider all tokens
# DEFAULT_TOP_K = "50" # Uncomment to limit to top 50 tokens
# DEFAULT_MAX_NEW_TOKENS = "2048" # Uncomment to set max output tokens
# DEFAULT_LOGPROBS = "1" # Uncomment to enable log probabilities
# Build environment variables for the container
environment = {
'CONTEXT_LENGTH': CONTEXT_LENGTH,
'MAX_CONCURRENCY': MAX_CONCURRENCY,
}
# Add optional parameters if defined
if 'DEFAULT_TEMPERATURE' in globals():
environment['DEFAULT_TEMPERATURE'] = DEFAULT_TEMPERATURE
if 'DEFAULT_TOP_P' in globals():
environment['DEFAULT_TOP_P'] = DEFAULT_TOP_P
if 'DEFAULT_TOP_K' in globals():
environment['DEFAULT_TOP_K'] = DEFAULT_TOP_K
if 'DEFAULT_MAX_NEW_TOKENS' in globals():
environment['DEFAULT_MAX_NEW_TOKENS'] = DEFAULT_MAX_NEW_TOKENS
if 'DEFAULT_LOGPROBS' in globals():
environment['DEFAULT_LOGPROBS'] = DEFAULT_LOGPROBS
print("Environment configuration:")
for key, value in environment.items():
print(f" {key}: {value}")
```
**Configurar parâmetros específicos da implantação**
Agora configure os parâmetros específicos para a implantação de modelos do Amazon Nova, incluindo o local dos artefatos do modelo e a seleção do tipo de instância.
**Definir identificador de implantação**
```
# Deployment identifier - use a descriptive name for your use case
JOB_NAME = "my-nova-deployment"
```
**Especificar o local dos artefatos dos modelos**
Forneça o URI do Amazon S3 em que os artefatos treinados dos modelos do Amazon Nova foram armazenados. Deve ser o local da saída da tarefa de treinamento de modelo ou de ajuste fino.
```
# S3 location of your trained Nova model artifacts
# Replace with your model's S3 URI - must end with /
MODEL_S3_LOCATION = "s3://your-bucket-name/path/to/model/artifacts/"
```
**Selecionar a variante do modelo e o tipo de instância**
```
# Configure model variant and instance type
TESTCASE = {
"model": "lite2", # Options: micro, lite, lite2
"instance": "ml.p5.48xlarge" # Refer to "Supported models and instances" section
}
# Generate resource names
INSTANCE_TYPE = TESTCASE["instance"]
MODEL_NAME = JOB_NAME + "-" + TESTCASE["model"] + "-" + INSTANCE_TYPE.replace(".", "-")
ENDPOINT_CONFIG_NAME = MODEL_NAME + "-Config"
ENDPOINT_NAME = MODEL_NAME + "-Endpoint"
print(f"Model Name: {MODEL_NAME}")
print(f"Endpoint Config: {ENDPOINT_CONFIG_NAME}")
print(f"Endpoint Name: {ENDPOINT_NAME}")
```
**Convenções de nomenclatura**
O código gera automaticamente nomes consistentes para os recursos da AWS:
+ Nome do modelo: .: `{JOB_NAME}-{model}-{instance-type}`
+ Configuração de endpoint: `{MODEL_NAME}-Config`
+ Nome do endpoint: `{MODEL_NAME}-Endpoint`
## Etapa 4: criar a configuração do modelo e endpoint do SageMaker
Nesta etapa, você criará dois recursos essenciais: um objeto de modelo do SageMaker que faz referência aos artefatos dos modelos do Amazon Nova e uma configuração do endpoint que define como o modelo será implantado.
**Modelo do SageMaker**: um objeto de modelo que empacota a imagem do contêiner de inferência, o local dos artefatos do modelo e a configuração do ambiente. Este é um recurso reutilizável que pode ser implantado em vários endpoints.
**Configuração do endpoint**: define as configurações de infraestrutura para implantação, incluindo tipo de instância, contagem de instâncias e variantes do modelo. Isso permite que você gerencie as configurações de implantação separadamente do próprio modelo.
**Criar o modelo do SageMaker**
O código abaixo cria um modelo do SageMaker que faz referência aos artefatos do seu modelo do Amazon Nova:
```
try:
model_response = sagemaker.create_model(
ModelName=MODEL_NAME,
PrimaryContainer={
'Image': IMAGE,
'ModelDataSource': {
'S3DataSource': {
'S3Uri': MODEL_S3_LOCATION,
'S3DataType': 'S3Prefix',
'CompressionType': 'None'
}
},
'Environment': environment
},
ExecutionRoleArn=SAGEMAKER_EXECUTION_ROLE_ARN,
EnableNetworkIsolation=True
)
print("Model created successfully!")
print(f"Model ARN: {model_response['ModelArn']}")
except sagemaker.exceptions.ClientError as e:
print(f"Error creating model: {e}")
```
Principais parâmetros:
+ `ModelName`: identificador exclusivo do seu modelo
+ `Image`: URI de imagem de contêiner do Docker para inferência do Amazon Nova
+ `ModelDataSource`: local do Amazon S3 dos seus artefatos de modelos
+ `Environment`: variáveis de ambiente configuradas na Etapa 3
+ `ExecutionRoleArn`: perfil do IAM da Etapa 2
+ `EnableNetworkIsolation`: defina como True para aumentar a segurança (impede que o contêiner faça chamadas de rede de saída)
**Criar a configuração do endpoint**
Em seguida, crie uma configuração do endpoint que defina sua infraestrutura de implantação:
```
# Create Endpoint Configuration
try:
production_variant = {
'VariantName': 'primary',
'ModelName': MODEL_NAME,
'InitialInstanceCount': 1,
'InstanceType': INSTANCE_TYPE,
}
config_response = sagemaker.create_endpoint_config(
EndpointConfigName=ENDPOINT_CONFIG_NAME,
ProductionVariants=[production_variant]
)
print("Endpoint configuration created successfully!")
print(f"Config ARN: {config_response['EndpointConfigArn']}")
except sagemaker.exceptions.ClientError as e:
print(f"Error creating endpoint configuration: {e}")
```
Principais parâmetros:
+ `VariantName`: identificador para essa variante de modelo (use “primary” para implantações de modelo único)
+ `ModelName`: faz referência ao modelo criado acima
+ `InitialInstanceCount`: número de instâncias a serem implantadas (comece com 1 e escale posteriormente, se necessário)
+ `InstanceType`: tipo de instância de ML selecionado na Etapa 3
**Verificar a criação de recursos**
Você pode verificar se os recursos foram criados com êxito:
```
# Describe the model
model_info = sagemaker.describe_model(ModelName=MODEL_NAME)
print(f"Model Status: {model_info['ModelName']} created")
# Describe the endpoint configuration
config_info = sagemaker.describe_endpoint_config(EndpointConfigName=ENDPOINT_CONFIG_NAME)
print(f"Endpoint Config Status: {config_info['EndpointConfigName']} created")
```
## Etapa 5: implantar o endpoint
A próxima etapa é implantar seu modelo do Amazon Nova criando um endpoint em tempo real do SageMaker. Esse endpoint hospedará seu modelo e fornecerá um endpoint HTTPS seguro para fazer solicitações de inferência.
A criação do endpoint normalmente leva de 15 a 30 minutos, pois a AWS provisiona a infraestrutura, faz o download dos artefatos do modelo e inicializa o contêiner de inferência.
**Criar o endpoint**
```
import time
try:
endpoint_response = sagemaker.create_endpoint(
EndpointName=ENDPOINT_NAME,
EndpointConfigName=ENDPOINT_CONFIG_NAME
)
print("Endpoint creation initiated successfully!")
print(f"Endpoint ARN: {endpoint_response['EndpointArn']}")
except Exception as e:
print(f"Error creating endpoint: {e}")
```
**Monitorar a criação do endpoint**
O código abaixo pesquisa o status do endpoint até a conclusão da implantação:
```
# Monitor endpoint creation progress
print("Waiting for endpoint creation to complete...")
print("This typically takes 15-30 minutes...\n")
while True:
try:
response = sagemaker.describe_endpoint(EndpointName=ENDPOINT_NAME)
status = response['EndpointStatus']
if status == 'Creating':
print(f"⏳ Status: {status} - Provisioning infrastructure and loading model...")
elif status == 'InService':
print(f"✅ Status: {status}")
print("\nEndpoint creation completed successfully!")
print(f"Endpoint Name: {ENDPOINT_NAME}")
print(f"Endpoint ARN: {response['EndpointArn']}")
break
elif status == 'Failed':
print(f"❌ Status: {status}")
print(f"Failure Reason: {response.get('FailureReason', 'Unknown')}")
print("\nFull response:")
print(response)
break
else:
print(f"Status: {status}")
except Exception as e:
print(f"Error checking endpoint status: {e}")
break
time.sleep(30) # Check every 30 seconds
```
**Verificar se o endpoint está pronto**
Quando o endpoint estiver InService, você poderá verificar sua configuração:
```
# Get detailed endpoint information
endpoint_info = sagemaker.describe_endpoint(EndpointName=ENDPOINT_NAME)
print("\n=== Endpoint Details ===")
print(f"Endpoint Name: {endpoint_info['EndpointName']}")
print(f"Endpoint ARN: {endpoint_info['EndpointArn']}")
print(f"Status: {endpoint_info['EndpointStatus']}")
print(f"Creation Time: {endpoint_info['CreationTime']}")
print(f"Last Modified: {endpoint_info['LastModifiedTime']}")
# Get endpoint config for instance type details
endpoint_config_name = endpoint_info['EndpointConfigName']
endpoint_config = sagemaker.describe_endpoint_config(EndpointConfigName=endpoint_config_name)
# Display production variant details
for variant in endpoint_info['ProductionVariants']:
print(f"\nProduction Variant: {variant['VariantName']}")
print(f" Current Instance Count: {variant['CurrentInstanceCount']}")
print(f" Desired Instance Count: {variant['DesiredInstanceCount']}")
# Get instance type from endpoint config
for config_variant in endpoint_config['ProductionVariants']:
if config_variant['VariantName'] == variant['VariantName']:
print(f" Instance Type: {config_variant['InstanceType']}")
break
```
**Solução de problemas de falhas na criação de endpoints**
Motivos de falha comuns:
+ **Capacidade insuficiente**: o tipo de instância solicitada não está disponível na sua região.
+ Solução: tente um tipo de instância diferente ou solicite um aumento da cota
+ **Permissões do IAM**: o perfil de execução não tem as permissões necessárias
+ Solução: verifique se o perfil tem acesso aos artefatos dos modelos do Amazon S3 e às permissões necessárias do SageMaker
+ **Artefatos do modelo não encontrados**: o URI do Amazon S3 está incorreto ou inacessível
+ Solução: verifique o URI do Amazon S3, as permissões do bucket e se você está na região correta
+ **Limites de recursos**: limites da conta excedidos para endpoints ou instâncias
+ Solução: solicite um aumento de cota de serviço por meio do Service Quotas ou do AWS Support
**nota**
Se você precisar excluir um endpoint com falha e começar de novo:
```
sagemaker.delete_endpoint(EndpointName=ENDPOINT_NAME)
```
## Etapa 6: invocar o endpoint
Quando seu endpoint estiver InService, você poderá enviar solicitações de inferência para gerar predições do seu modelo do Amazon Nova. O SageMaker oferece suporte a endpoints síncronos (em tempo real com os modos de streaming/não streaming) e endpoints assíncronos (baseados no Amazon S3 para processamento em lote).
**Configurar o cliente de runtime**
Crie um cliente de runtime do SageMaker com as configurações de tempo limite apropriadas:
```
import json
import boto3
import botocore
from botocore.exceptions import ClientError
# Configure client with appropriate timeouts
config = botocore.config.Config(
read_timeout=120, # Maximum time to wait for response
connect_timeout=10, # Maximum time to establish connection
retries={'max_attempts': 3} # Number of retry attempts
)
# Create SageMaker Runtime client
runtime_client = boto3.client('sagemaker-runtime', config=config, region_name=REGION)
```
**Criar uma função de inferência universal**
A função abaixo processa solicitações com ou sem streaming:
```
def invoke_nova_endpoint(request_body):
"""
Invoke Nova endpoint with automatic streaming detection.
Args:
request_body (dict): Request payload containing prompt and parameters
Returns:
dict: Response from the model (for non-streaming requests)
None: For streaming requests (prints output directly)
"""
body = json.dumps(request_body)
is_streaming = request_body.get("stream", False)
try:
print(f"Invoking endpoint ({'streaming' if is_streaming else 'non-streaming'})...")
if is_streaming:
response = runtime_client.invoke_endpoint_with_response_stream(
EndpointName=ENDPOINT_NAME,
ContentType='application/json',
Body=body
)
event_stream = response['Body']
for event in event_stream:
if 'PayloadPart' in event:
chunk = event['PayloadPart']
if 'Bytes' in chunk:
data = chunk['Bytes'].decode()
print("Chunk:", data)
else:
# Non-streaming inference
response = runtime_client.invoke_endpoint(
EndpointName=ENDPOINT_NAME,
ContentType='application/json',
Accept='application/json',
Body=body
)
response_body = response['Body'].read().decode('utf-8')
result = json.loads(response_body)
print("✅ Response received successfully")
return result
except ClientError as e:
error_code = e.response['Error']['Code']
error_message = e.response['Error']['Message']
print(f"❌ AWS Error: {error_code} - {error_message}")
except Exception as e:
print(f"❌ Unexpected error: {str(e)}")
```
**Exemplo 1: conclusão de chat sem streaming**
Use o formato de chat para interações conversacionais:
```
# Non-streaming chat request
chat_request = {
"messages": [
{"role": "user", "content": "Hello! How are you?"}
],
"max_tokens": 100,
"max_completion_tokens": 100, # Alternative to max_tokens
"stream": False,
"temperature": 0.7,
"top_p": 0.9,
"top_k": 50,
"logprobs": True,
"top_logprobs": 3,
"reasoning_effort": "low", # Options: "low", "high"
"allowed_token_ids": None, # List of allowed token IDs
"truncate_prompt_tokens": None, # Truncate prompt to this many tokens
"stream_options": None
}
response = invoke_nova_endpoint(chat_request)
```
**Resposta de exemplo:**
```
{
"id": "chatcmpl-123456",
"object": "chat.completion",
"created": 1234567890,
"model": "default",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! I'm doing well, thank you for asking. I'm here and ready to help you with any questions or tasks you might have. How can I assist you today?"
},
"logprobs": {
"content": [
{
"token": "Hello",
"logprob": -0.123,
"top_logprobs": [
{"token": "Hello", "logprob": -0.123},
{"token": "Hi", "logprob": -2.456},
{"token": "Hey", "logprob": -3.789}
]
}
# Additional tokens...
]
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 28,
"total_tokens": 40
}
}
```
**Exemplo 2: conclusão de texto simples**
Use o formato de conclusão para geração de texto simples:
```
# Simple completion request
completion_request = {
"prompt": "The capital of France is",
"max_tokens": 50,
"stream": False,
"temperature": 0.0,
"top_p": 1.0,
"top_k": -1, # -1 means no limit
"logprobs": 3, # Number of log probabilities to return
"allowed_token_ids": None, # List of allowed token IDs
"truncate_prompt_tokens": None, # Truncate prompt to this many tokens
"stream_options": None
}
response = invoke_nova_endpoint(completion_request)
```
**Resposta de exemplo:**
```
{
"id": "cmpl-789012",
"object": "text_completion",
"created": 1234567890,
"model": "default",
"choices": [
{
"text": " Paris.",
"index": 0,
"logprobs": {
"tokens": [" Paris", "."],
"token_logprobs": [-0.001, -0.002],
"top_logprobs": [
{" Paris": -0.001, " London": -5.234, " Rome": -6.789},
{".": -0.002, ",": -4.567, "!": -7.890}
]
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 6,
"completion_tokens": 2,
"total_tokens": 8
}
}
```
**Exemplo 3: conclusão de chat com streaming**
```
# Streaming chat request
streaming_request = {
"messages": [
{"role": "user", "content": "Tell me a short story about a robot"}
],
"max_tokens": 200,
"stream": True,
"temperature": 0.7,
"top_p": 0.95,
"top_k": 40,
"logprobs": True,
"top_logprobs": 2,
"reasoning_effort": "high", # For more detailed reasoning
"stream_options": {"include_usage": True}
}
invoke_nova_endpoint(streaming_request)
```
**Exemplo de saída de streaming:**
```
Chunk: data: {"id":"chatcmpl-029ca032-fa01-4868-80b7-c4cb1af90fb9","object":"chat.completion.chunk","created":1772060532,"model":"default","choices":[{"index":0,"delta":{"role":"assistant","content":"","reasoning_content":null},"logprobs":null,"finish_reason":null}],"prompt_token_ids":null}
Chunk: data: {"id":"chatcmpl-029ca032-fa01-4868-80b7-c4cb1af90fb9","object":"chat.completion.chunk","created":1772060532,"model":"default","choices":[{"index":0,"delta":{"content":" Once","reasoning_content":null},"logprobs":{"content":[{"token":"\u2581Once","logprob":-0.6078429222106934,"bytes":[226,150,129,79,110,99,101],"top_logprobs":[{"token":"\u2581Once","logprob":-0.6078429222106934,"bytes":[226,150,129,79,110,99,101]},{"token":"\u2581In","logprob":-0.7864127159118652,"bytes":[226,150,129,73,110]}]}]},"finish_reason":null,"token_ids":null}]}
Chunk: data: {"id":"chatcmpl-029ca032-fa01-4868-80b7-c4cb1af90fb9","object":"chat.completion.chunk","created":1772060532,"model":"default","choices":[{"index":0,"delta":{"content":" upon","reasoning_content":null},"logprobs":{"content":[{"token":"\u2581upon","logprob":-0.0012345,"bytes":[226,150,129,117,112,111,110],"top_logprobs":[{"token":"\u2581upon","logprob":-0.0012345,"bytes":[226,150,129,117,112,111,110]},{"token":"\u2581a","logprob":-6.789,"bytes":[226,150,129,97]}]}]},"finish_reason":null,"token_ids":null}]}
Chunk: data: {"id":"chatcmpl-029ca032-fa01-4868-80b7-c4cb1af90fb9","object":"chat.completion.chunk","created":1772060532,"model":"default","choices":[{"index":0,"delta":{"content":" a","reasoning_content":null},"logprobs":{"content":[{"token":"\u2581a","logprob":-0.0001234,"bytes":[226,150,129,97],"top_logprobs":[{"token":"\u2581a","logprob":-0.0001234,"bytes":[226,150,129,97]},{"token":"\u2581time","logprob":-9.123,"bytes":[226,150,129,116,105,109,101]}]}]},"finish_reason":null,"token_ids":null}]}
Chunk: data: {"id":"chatcmpl-029ca032-fa01-4868-80b7-c4cb1af90fb9","object":"chat.completion.chunk","created":1772060532,"model":"default","choices":[{"index":0,"delta":{"content":" time","reasoning_content":null},"logprobs":{"content":[{"token":"\u2581time","logprob":-0.0023456,"bytes":[226,150,129,116,105,109,101],"top_logprobs":[{"token":"\u2581time","logprob":-0.0023456,"bytes":[226,150,129,116,105,109,101]},{"token":",","logprob":-6.012,"bytes":[44]}]}]},"finish_reason":null,"token_ids":null}]}
# Additional chunks...
Chunk: data: {"id":"chatcmpl-029ca032-fa01-4868-80b7-c4cb1af90fb9","object":"chat.completion.chunk","created":1772060532,"model":"default","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}],"usage":{"prompt_tokens":15,"completion_tokens":87,"total_tokens":102}}
Chunk: data: [DONE]
```
**Exemplo 4: conclusão do chat multimodal**
Use o formato multimodal para entradas de imagem e texto:
```
# Multimodal chat request (if supported by your model)
multimodal_request = {
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "What's in this image?"},
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
]
}
],
"max_tokens": 150,
"temperature": 0.3,
"top_p": 0.8,
"stream": False
}
response = invoke_nova_endpoint(multimodal_request)
```
**Resposta de exemplo:**
```
{
"id": "chatcmpl-345678",
"object": "chat.completion",
"created": 1234567890,
"model": "default",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "The image shows..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 1250,
"completion_tokens": 45,
"total_tokens": 1295
}
}
```
## Etapa 7: limpar os recursos (opcional)
Para evitar cobranças desnecessárias, exclua os recursos da AWS que você criou durante este tutorial. Os endpoints do SageMaker são cobrados enquanto estão em execução, mesmo que você não esteja ativamente fazendo solicitações de inferência.
**Importante**
A exclusão de recursos é permanente e não poderá ser desfeita. Antes de continuar, certifique-se de que não precisará mais desses recursos.
**Excluir o endpoint**
```
import boto3
# Initialize SageMaker client
sagemaker = boto3.client('sagemaker', region_name=REGION)
try:
print("Deleting endpoint...")
sagemaker.delete_endpoint(EndpointName=ENDPOINT_NAME)
print(f"✅ Endpoint '{ENDPOINT_NAME}' deletion initiated")
print("Charges will stop once deletion completes (typically 2-5 minutes)")
except Exception as e:
print(f"❌ Error deleting endpoint: {e}")
```
**nota**
A exclusão do endpoint é assíncrona. Você pode monitorar o status da exclusão:
```
import time
print("Monitoring endpoint deletion...")
while True:
try:
response = sagemaker.describe_endpoint(EndpointName=ENDPOINT_NAME)
status = response['EndpointStatus']
print(f"Status: {status}")
time.sleep(10)
except sagemaker.exceptions.ClientError as e:
if e.response['Error']['Code'] == 'ValidationException':
print("✅ Endpoint successfully deleted")
break
else:
print(f"Error: {e}")
break
```
**Excluir a configuração do endpoint**
Depois que o endpoint for excluído, remova a configuração dele:
```
try:
print("Deleting endpoint configuration...")
sagemaker.delete_endpoint_config(EndpointConfigName=ENDPOINT_CONFIG_NAME)
print(f"✅ Endpoint configuration '{ENDPOINT_CONFIG_NAME}' deleted")
except Exception as e:
print(f"❌ Error deleting endpoint configuration: {e}")
```
**Excluir o modelo**
Remova o objeto do modelo do SageMaker:
```
try:
print("Deleting model...")
sagemaker.delete_model(ModelName=MODEL_NAME)
print(f"✅ Model '{MODEL_NAME}' deleted")
except Exception as e:
print(f"❌ Error deleting model: {e}")
```
# Referência da API
Os modelos do Amazon Nova no SageMaker usam a API de execução padrão do SageMaker para inferência. Para verificar a documentação completa da API, consulte [Testar um modelo implantado](https://docs.aws.amazon.com//sagemaker/latest/dg/realtime-endpoints-test-endpoints.html).
## Invocação de endpoints
Os modelos do Amazon Nova no SageMaker são compatíveis com dois métodos de invocação:
+ **Invocação síncrona**: use a API [InvokeEndpoint](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html) para solicitações de inferência em tempo real e sem streaming.
+ **Invocação com streaming**: use a API [InvokeEndpointWithResponseStream](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpointWithResponseStream.html) para solicitações de inferência com streaming em tempo real.
## Formato de solicitação
Os modelos do Amazon Nova são compatíveis com dois formatos de solicitação:
**Formato de conclusão de chat**
Use esse formato para interações conversacionais:
```
{
"messages": [
{"role": "user", "content": "string"}
],
"max_tokens": integer,
"max_completion_tokens": integer,
"stream": boolean,
"temperature": float,
"top_p": float,
"top_k": integer,
"logprobs": boolean,
"top_logprobs": integer,
"reasoning_effort": "low" | "high",
"allowed_token_ids": [integer],
"truncate_prompt_tokens": integer,
"stream_options": {
"include_usage": boolean
}
}
```
**Formato de conclusão de texto**
Use esse formato para geração de texto simples:
```
{
"prompt": "string",
"max_tokens": integer,
"stream": boolean,
"temperature": float,
"top_p": float,
"top_k": integer,
"logprobs": integer,
"allowed_token_ids": [integer],
"truncate_prompt_tokens": integer,
"stream_options": {
"include_usage": boolean
}
}
```
**Formato de conclusão de chat multimodal**
Use esse formato para entradas de imagem e texto:
```
{
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "What's in this image?"},
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
]
}
],
"max_tokens": integer,
"temperature": float,
"top_p": float,
"stream": boolean
}
```
**Parâmetros de solicitação**
+ `messages` (matriz): para formato de conclusão de chat. Matriz de objetos de mensagem com os campos `role` e `content`. O conteúdo pode ser uma string somente para texto ou uma matriz para entradas multimodais.
+ `prompt` (string): para formato de conclusão de texto. O texto de entrada para a geração.
+ `max_tokens` (inteiro): número máximo de tokens a serem gerados na resposta. Intervalo: 1 ou maior.
+ `max_completion_tokens` (inteiro): alternativa a max\$1tokens para conclusões de chats. Número máximo de tokens de conclusão a serem gerados.
+ `temperature` (flutuante): controla a randomização na geração. Intervalo: de 0,0 a 2,0 (0,0 = determinístico, 2,0 = randomização máxima).
+ `top_p` (flutuante): limite da amostragem do núcleo. Intervalo: de 1e-10 a 1,0.
+ `top_k` (inteiro): limita a seleção de tokens aos K tokens mais prováveis. Intervalo: -1 ou maior (-1 = sem limite).
+ `stream` (boleano): se a resposta deve ser transmitida. Defina como `true` para streaming, `false` para sem streaming.
+ `logprobs` (boleano/inteiro): para conclusões de chat, use boleano. Em conclusões de texto, use um número inteiro para o número de probabilidades logarítmicas a serem retornadas. Intervalo: de 1 a 20.
+ `top_logprobs` (inteiro): número de tokens mais prováveis para os quais retornar probabilidades logarítmicas (somente para conclusões de chat).
+ `reasoning_effort` (string): nível de esforço de raciocínio. Opções: “baixo”, “alto” (conclusões de bate-papo somente para modelos personalizados do Nova 2 Lite).
+ `allowed_token_ids` (matriz): lista de IDs de tokens que podem ser gerados. Restringe a saída aos tokens especificados.
+ `truncate_prompt_tokens` (inteiro): trunque o prompt para este número de tokens se ele exceder o limite.
+ `stream_options` (objeto): opções para respostas em streaming. Contém o boleano `include_usage` para incluir o uso de tokens nas respostas em streaming.
## Formato de resposta
O formato da resposta depende do método de invocação e do tipo de solicitação:
**Resposta de conclusão de chat (não streaming)**
Para solicitações síncronas de conclusão de chat:
```
{
"id": "chatcmpl-123e4567-e89b-12d3-a456-426614174000",
"object": "chat.completion",
"created": 1677652288,
"model": "nova-micro-custom",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! I'm doing well, thank you for asking. How can I help you today?",
"refusal": null,
"reasoning": null,
"reasoning_content": null
},
"logprobs": {
"content": [
{
"token": "Hello",
"logprob": -0.31725305,
"bytes": [72, 101, 108, 108, 111],
"top_logprobs": [
{
"token": "Hello",
"logprob": -0.31725305,
"bytes": [72, 101, 108, 108, 111]
},
{
"token": "Hi",
"logprob": -1.3190403,
"bytes": [72, 105]
}
]
}
]
},
"finish_reason": "stop",
"stop_reason": null,
"token_ids": [9906, 0, 358, 2157, 1049, 11, 1309, 345, 369, 6464, 13]
}
],
"usage": {
"prompt_tokens": 9,
"completion_tokens": 12,
"total_tokens": 21,
"prompt_tokens_details": {
"cached_tokens": 0
}
},
"prompt_token_ids": [9906, 0, 358]
}
```
**Resposta de conclusão de texto (não streaming)**
Para solicitações síncronas de conclusão de texto:
```
{
"id": "cmpl-123e4567-e89b-12d3-a456-426614174000",
"object": "text_completion",
"created": 1677652288,
"model": "nova-micro-custom",
"choices": [
{
"index": 0,
"text": "Paris, the capital and most populous city of France.",
"logprobs": {
"tokens": ["Paris", ",", " the", " capital"],
"token_logprobs": [-0.31725305, -0.07918124, -0.12345678, -0.23456789],
"top_logprobs": [
{
"Paris": -0.31725305,
"London": -1.3190403,
"Rome": -2.1234567
},
{
",": -0.07918124,
" is": -1.2345678
}
]
},
"finish_reason": "stop",
"stop_reason": null,
"prompt_token_ids": [464, 6864, 315, 4881, 374],
"token_ids": [3915, 11, 279, 6864, 323, 1455, 95551, 3363, 315, 4881, 13]
}
],
"usage": {
"prompt_tokens": 5,
"completion_tokens": 11,
"total_tokens": 16,
"prompt_tokens_details": {
"cached_tokens": 0
}
}
}
```
**Resposta em streaming para conclusão de chat**
Para solicitações de conclusão de chat em streaming, as respostas são enviadas como eventos enviados pelo servidor (SSE):
```
data: {
"id": "chatcmpl-123e4567-e89b-12d3-a456-426614174000",
"object": "chat.completion.chunk",
"created": 1677652288,
"model": "nova-micro-custom",
"choices": [
{
"index": 0,
"delta": {
"role": "assistant",
"content": "Hello",
"refusal": null,
"reasoning": null,
"reasoning_content": null
},
"logprobs": {
"content": [
{
"token": "Hello",
"logprob": -0.31725305,
"bytes": [72, 101, 108, 108, 111],
"top_logprobs": [
{
"token": "Hello",
"logprob": -0.31725305,
"bytes": [72, 101, 108, 108, 111]
}
]
}
]
},
"finish_reason": null,
"stop_reason": null
}
],
"usage": null,
"prompt_token_ids": null
}
data: {
"id": "chatcmpl-123e4567-e89b-12d3-a456-426614174000",
"object": "chat.completion.chunk",
"created": 1677652288,
"model": "nova-micro-custom",
"choices": [
{
"index": 0,
"delta": {
"content": "! I'm"
},
"logprobs": null,
"finish_reason": null,
"stop_reason": null
}
],
"usage": null
}
data: {
"id": "chatcmpl-123e4567-e89b-12d3-a456-426614174000",
"object": "chat.completion.chunk",
"created": 1677652288,
"model": "nova-micro-custom",
"choices": [
{
"index": 0,
"delta": {},
"finish_reason": "stop",
"stop_reason": null
}
],
"usage": {
"prompt_tokens": 9,
"completion_tokens": 12,
"total_tokens": 21,
"prompt_tokens_details": {
"cached_tokens": 0
}
}
}
data: [DONE]
```
**Resposta em streaming para conclusão de texto**
Para solicitações de conclusão de texto em streaming:
```
data: {
"id": "cmpl-123e4567-e89b-12d3-a456-426614174000",
"object": "text_completion",
"created": 1677652288,
"model": "nova-micro-custom",
"choices": [
{
"index": 0,
"text": "Paris",
"logprobs": {
"tokens": ["Paris"],
"token_logprobs": [-0.31725305],
"top_logprobs": [
{
"Paris": -0.31725305,
"London": -1.3190403
}
]
},
"finish_reason": null,
"stop_reason": null
}
],
"usage": null
}
data: {
"id": "cmpl-123e4567-e89b-12d3-a456-426614174000",
"object": "text_completion",
"created": 1677652288,
"model": "nova-micro-custom",
"choices": [
{
"index": 0,
"text": ", the capital",
"logprobs": null,
"finish_reason": null,
"stop_reason": null
}
],
"usage": null
}
data: {
"id": "cmpl-123e4567-e89b-12d3-a456-426614174000",
"object": "text_completion",
"created": 1677652288,
"model": "nova-micro-custom",
"choices": [
{
"index": 0,
"text": "",
"finish_reason": "stop",
"stop_reason": null
}
],
"usage": {
"prompt_tokens": 5,
"completion_tokens": 11,
"total_tokens": 16
}
}
data: [DONE]
```
**Explicação dos campos de resposta**
+ `id`: identificador exclusivo para a conclusão
+ `object`: tipo de objeto retornado (“chat.completion”, “text\$1completion”, “chat.completion.chunk”)
+ `created`: carimbo de data e hora do Unix de quando a conclusão foi criada
+ `model`: modelo usado para a conclusão
+ `choices`: matriz de opções de conclusão
+ `usage`: informações de uso do token, incluindo prompt, conclusão e total de tokens
+ `logprobs`: informações de probabilidade logarítmica para tokens (quando solicitadas)
+ `finish_reason`: motivo pelo qual o modelo parou de gerar (“stop”, “length”, “content\$1filter”)
+ `delta`: conteúdo incremental em respostas em streaming
+ `reasoning`: conteúdo de raciocínio quando reasoning\$1effort é usado
+ `token_ids`: matriz de IDs de tokens para o texto gerado
Para verificar a documentação completa das APIs, consulte a [referência da API InvokeEndpoint](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html) e a [referência da API InvokeEndpointWithResponseStream](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpointWithResponseStream.html).
# Avaliar modelos hospedados na inferência do SageMaker
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
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
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
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
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
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
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
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
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
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
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
**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
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
**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
+ [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)
# Implantação de modelos do Amazon Nova Forge na detecção de abusos da Inferência do Amazon SageMaker
A AWS está comprometida com o uso responsável da IA. Para ajudar a evitar possíveis usos indevidos, quando você implementa modelos do Amazon Nova Forge na Inferência do Amazon SageMaker, ela implementa mecanismos automatizados de detecção de abusos para identificar possíveis violações da [Política de uso aceitável](https://aws.amazon.com/aup/) (AUP) e dos Termos de Serviço da AWS, incluindo a [Política de IA responsável](https://aws.amazon.com/ai/responsible-ai/policy/).
Nossos mecanismos de detecção de abuso são totalmente automatizados, portanto não há análise humana nem acesso às entradas do usuário ou às saídas do modelo.
A detecção automática de abuso inclui:
+ **Categorizar o conteúdo**: usamos classificadores para detectar conteúdo prejudicial (como conteúdo que incita à violência) nas entradas dos usuários e nas saídas dos modelos. Um classificador é um algoritmo que processa entradas e saídas do modelo e atribui o tipo de dano e nível de confiança. Podemos executar esses classificadores no uso de modelos do Amazon Nova Forge. O processo de classificação é automatizado e não envolve análise humana das entradas ou saídas do usuário modelo.
+ **Identificar padrões**: usamos métricas classificadoras para identificar possíveis violações e comportamentos recorrentes. Podemos compilar e compartilhar métricas de classificadores anonimizadas. A Inferência do Amazon SageMaker não armazena a entrada do usuário ou a saída do modelo.
+ **Detecção e bloqueio de material de abuso sexual infantil (CSAM)**: você é responsável pelo conteúdo que carrega (e de seus usuários finais) na Inferência do Amazon SageMaker e deve garantir que ela esteja livre de imagens ilegais. Para ajudar a impedir a disseminação de CSAM, ao implantar um modelo do Amazon Nova Forge na Inferência do Amazon SageMaker, ela pode usar mecanismos automatizados de detecção de abuso (como tecnologia de correspondência de hash ou classificadores) para detectar um possível CSAM. Se a Inferência do Amazon SageMaker detectar um possível CSAM nas entradas de imagens do cliente, ela bloqueará a solicitação e enviará uma mensagem de erro automática. A Inferência do Amazon SageMaker também pode registrar uma denúncia no Centro Nacional para Crianças Desaparecidas e Exploradas (NCMEC) ou em uma autoridade relevante. Levamos o CSAM a sério e continuaremos a atualizar nossos mecanismos de detecção, bloqueio e denúncia. De acordo com as leis aplicáveis, o cliente pode ser obrigado a tomar medidas adicionais e é responsável por essas medidas.
Quando nossos mecanismos automatizados de detecção de abusos identificarem possíveis violações, poderemos solicitar informações sobre o seu uso da Inferência do Amazon SageMaker e sua conformidade com nossos termos de serviço. Caso você se mostre omisso, relutante ou incapaz de cumprir com esses termos ou políticas, a AWS poderá suspender seu acesso à Inferência do Amazon SageMaker. Além disso, você também poderá ser cobrado pela falha no processamento de inferência se nossos testes automatizados detectarem que as respostas do modelo são inconsistentes com nossos termos e políticas.
Em caso de dúvidas, entre em contato com o AWS Support. Para obter mais informações, consulte [Perguntas frequentes sobre o Amazon SageMaker](https://aws.amazon.com/sagemaker/ai/faqs/).