As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Avaliação de modelos
A avaliação compara seu agente com base em um conjunto imediato e relata métricas de recompensa, pass @k e trajetória. Use-o para comparar um modelo ajustado com sua base ou comparar um candidato antes da implantação.
**Nota:** Uso de trabalhos de avaliação `JobCategory: AgentRFTEvaluation` (não `AgentRFT` como usado em treinamento). Use esta categoria em `CreateJob` e `DescribeJob` solicite trabalhos de avaliação.
## Preparando dados de avaliação
Os conjuntos de dados de avaliação usam o mesmo formato e esquema dos conjuntos de dados de treinamento. Consulte [Formato de conjunto de dados imediato](model-customize-mtrl-assets.md#model-customize-mtrl-assets-prompt-dataset-format). A orientação abaixo é específica para cada avaliação.
1. **Guarde os dados de avaliação dos conjuntos de dados de treinamento.** Nunca avalie as instruções de treinamento, pois as pontuações exagerarão o desempenho. Reserve uma parte dos dados para um conjunto retido ou mantenha um conjunto de dados de avaliação separado. Mantenha o mesmo conjunto de avaliações em todas as iterações para que os resultados sejam comparáveis.
1. **Combine o formato do prompt de treinamento.** O agente deve analisar os prompts de avaliação da mesma forma que analisou os prompts de treinamento. Se você usou codificação ou criptografia durante o treinamento, use a estrutura idêntica aqui. Gerar ambos a partir do mesmo caminho de código evita desvios.
1. **Cubra os comportamentos que lhe interessam.** Exercite cada ferramenta e combinação de ferramentas que seu agente usa. Inclua solicitações que anteriormente causaram falhas para que as regressões surjam.
1. **Proteja o conteúdo confidencial da mesma forma que no treinamento**, pois o serviço passa as solicitações sem inspeção.
## Lançamento de um trabalho de avaliação
Após a conclusão do treinamento, avalie seu modelo usando um dos métodos a seguir.
### SageMaker Estúdio AI
+ Navegue até a página de detalhes do seu modelo personalizado (**Modelos** > **Meus modelos** > selecione seu modelo MTRL).
+ Escolha **Avaliar** para abrir a página de configuração da avaliação.
+ Selecione **Multi-Turn RL** como o tipo de avaliação.
+ Configure seu ambiente de agente — selecione seu tempo de AgentCore execução do Bedrock ou forneça o ARN do encaminhador Lambda.
+ Forneça seu conjunto de dados de avaliação (URI do S3 ou conjunto de dados registrado contendo instruções de avaliação retidas).
+ Escolha **Enviar** para iniciar o trabalho de avaliação.
### SageMaker SDK AI para Python
`MultiTurnRLEvaluator`Ele fornece uma interface de alto nível para iniciar trabalhos de avaliação. Quando você é aprovado em um instrutor completo, o avaliador resolve automaticamente o ARN do pacote de modelos, a configuração do agente e o qualificador do agente.
**Avalie um modelo ajustado**
```
from sagemaker.train.evaluate import MultiTurnRLEvaluator
from sagemaker.train.multi_turn_rl_trainer import MultiTurnRLTrainer
# Attach to a completed training job
trainer = MultiTurnRLTrainer.attach(job_name="my-mtrl-job-20260512082005")
# Minimal evaluator — everything else inferred from trainer
evaluator = MultiTurnRLEvaluator(
model=trainer,
dataset="s3://my-bucket/eval-prompts.parquet",
s3_output_path="s3://my-bucket/eval-output/",
)
execution = evaluator.evaluate()
print(f"Evaluation started: {execution.arn}")
# Wait for completion
execution.wait()
print(f"Status: {execution.status.overall_status}")
print(f"S3 Output: {execution.s3_output_path}")
print(f"MLflow: {execution.mlflow_url}")
```
**Avalie um modelo básico (sem treinamento)**
Ao avaliar um modelo básico diretamente, `agent_config` é necessário, pois não há treinador do qual herdar:
```
from sagemaker.train.evaluate import MultiTurnRLEvaluator
# With Bedrock AgentCore
evaluator_base = MultiTurnRLEvaluator(
model="openai-reasoning-gpt-oss-20b",
dataset="s3://my-bucket/eval-prompts.parquet",
agent_config="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent",
s3_output_path="s3://my-bucket/eval-output/base/",
mlflow_resource_arn="arn:aws:sagemaker:us-west-2:123456789012:mlflow-tracking-server/my-mlflow",
role="arn:aws:iam::123456789012:role/SageMakerRole",
accept_eula=True,
)
execution = evaluator_base.evaluate()
execution.wait()
```
**Side-by-side comparação (básica versus ajustada)**
Uma única `evaluate()` chamada que avalia o modelo básico e o modelo ajustado em um único pipeline:
```
comparison_evaluator = MultiTurnRLEvaluator(
model=trainer,
dataset="s3://my-bucket/eval-prompts.parquet",
s3_output_path="s3://my-bucket/eval-output/comparison/",
evaluate_base_model=True,
)
execution = comparison_evaluator.evaluate()
execution.wait()
print(f"Status: {execution.status.overall_status}")
```
**Monitore e recupere resultados**
```
# Refresh status
execution.refresh()
print(f"Status: {execution.status.overall_status}")
# Step-level detail
for step in execution.status.step_details:
print(f" {step.name}: {step.status}")
if step.job_arn:
print(f" Job ARN: {step.job_arn}")
# MLflow URL
print(f"MLflow: {execution.mlflow_url}")
```
### AWS CLI e boto3
Você também pode criar trabalhos de avaliação diretamente usando a `CreateJob` API.
**Crie um trabalho de avaliação (Bedrock AgentCore)**
Para criar um trabalho de avaliação, chame a `CreateJob` API com `JobCategory` set to`AgentRFTEvaluation`. A instalação e configuração do agente seguem o mesmo processo dos trabalhos de treinamento.
**Usando a AWS CLI**
```
aws sagemaker create-job \
--job-category AgentRFTEvaluation \
--job-name "my-agent-rft-eval-job" \
--role-arn "arn:aws:iam::123456789012:role/SageMakerFineTuningJobRole" \
--job-config-schema-version "1.0.0" \
--job-config-document '{
"AgentConfig": {
"BedrockAgentCoreConfig": {
"AgentRuntimeArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent"
}
},
"InputDataConfig": [{
"ChannelName": "evaluation",
"DataSource": {
"S3DataSource": {
"S3DataType": "S3Prefix",
"S3Uri": "s3://your-bucket-name/eval-prompts/"
}
}
}],
"OutputDataConfig": {
"S3OutputPath": "s3://your-bucket-name/eval-output/",
"MlflowConfig": {
"MlflowResourceArn": "arn:aws:sagemaker:us-west-2:123456789012:mlflow-app/my-rft-mlflow-app"
}
},
"EvaluationConfig": {
"BaseModelArn": "arn:aws:sagemaker:us-west-2:aws:hub-content/SageMakerPublicHub/Model/openai-reasoning-gpt-oss-20b",
"AcceptEula": true,
"HyperParameters": {"batch": { "eval_group_size": 1 }, "eval_metrics_config": { "pass_k_values": [1, 2, 4, 8, 16, 32], "success_threshold": 1 }}
}
}' \
--region us-west-2
```
**Usando o SDK SageMaker AI Python (boto3)**
```
import json
import boto3
sm = boto3.client("sagemaker")
response = sm.create_job(
JobName="my-agent-rft-eval-job",
RoleArn="arn:aws:iam::123456789012:role/SageMakerFineTuningJobRole",
JobCategory="AgentRFTEvaluation",
JobConfigSchemaVersion="1.0.0",
JobConfigDocument=json.dumps({
"AgentConfig": {
"BedrockAgentCoreConfig": {
"AgentRuntimeArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent"
}
},
"InputDataConfig": [{
"ChannelName": "evaluation",
"DataSource": {
"S3DataSource": {
"S3DataType": "S3Prefix",
"S3Uri": "s3://your-bucket-name/eval-prompts/"
}
}
}],
"OutputDataConfig": {
"S3OutputPath": "s3://your-bucket-name/eval-output/",
"MlflowConfig": {
"MlflowResourceArn": "arn:aws:sagemaker:us-west-2:123456789012:mlflow-app/my-rft-mlflow-app"
}
},
"EvaluationConfig": {
"BaseModelArn": "arn:aws:sagemaker:us-west-2:aws:hub-content/SageMakerPublicHub/Model/openai-reasoning-gpt-oss-20b",
"AcceptEula": True,
"HyperParameters": {"batch": { "eval_group_size": 1 }, "eval_metrics_config": { "pass_k_values": [1, 2, 4, 8, 16, 32], "success_threshold": 1 }}
}
})
)
print(f"Eval Job ARN: {response['JobArn']}")
```
**Avaliando um modelo ajustado**
Para avaliar um modelo produzido por um trabalho de treinamento, inclua `ModelPackageConfig` com`InputModelPackageArn`:
```
import json
import boto3
sm = boto3.client("sagemaker")
response = sm.create_job(
JobName="my-agent-rft-eval-finetuned",
RoleArn="arn:aws:iam::123456789012:role/SageMakerFineTuningJobRole",
JobCategory="AgentRFTEvaluation",
JobConfigSchemaVersion="1.0.0",
JobConfigDocument=json.dumps({
"AgentConfig": {...},
"InputDataConfig": [...],
"OutputDataConfig": {...},
"ModelPackageConfig": {
"InputModelPackageArn": "arn:aws:sagemaker:us-west-2:123456789012:model-package/my-final-models/1"
},
"EvaluationConfig": {...}
})
)
print(f"Eval Job ARN: {response['JobArn']}")
```
**Crie um trabalho de avaliação (agente personalizado com Lambda Forwarder)**
Use a mesma abordagem da AgentCore avaliação Bedrock, mas especifique `CustomAgentLambdaConfig` em: `AgentConfig`
```
"AgentConfig": {
"CustomAgentLambdaConfig": {
"LambdaArn": "arn:aws:lambda:us-west-2:account-id:function:rft-agent-forwarder"
}
}
```
## Hiperparâmetros de avaliação
| Categoria | Parâmetro | Tipo | Padrão | Description |
| --- | --- | --- | --- | --- |
| lote | avaliar\_tamanho\_do\_grupo | integer | 1 | Lançamentos por solicitação. Nota: Para calcular pass @k, defina eval\_group\_size >= k. |
| eval\_metrics\_config | pass\_k\_values | array | [1, 2, 4, 8, 16, 32] | Lista de valores k para calcular as métricas pass @k e pass^k. pass @k = probabilidade de que pelo menos 1 das k implementações amostradas seja bem-sucedida. pass^k = probabilidade de que todas as k implementações sejam bem-sucedidas. |
| eval\_metrics\_config | limiar de sucesso | flutuação | 1 | Um lançamento é “bem-sucedido” quando a recompensa é >= success\_threshold. Observe que isso se aplica às métricas pass @k, pass^k, succeeded/failed count. |
| parâmetros eval\_sampling\_ | temperatura | flutuação | 0 | Temperatura de amostragem para implementações de avaliação. Observação: é recomendável aumentar esse valor além de 0 para as métricas pass @k e pass^k para evitar um comportamento determinístico. |
| parâmetros eval\_sampling\_ | sampling\_top\_p | flutuação | 1 | Corte de amostragem de núcleo para lançamentos de avaliação. |
| parâmetros eval\_sampling\_ | sampling\_max\_tokens | integer | 4096 | Máximo de tokens que o modelo pode gerar por turno durante os lançamentos de avaliação. |
| lançamento | timeout | flutuação | 600 | Tempo (segundos) após o qual uma implementação de avaliação é tratada como falha e pode ser repetida. |
| lançamento | simultaneidade máxima | int | 96 | Número máximo de lançamentos de avaliação que podem ser executados paralelamente. |
| lançamento | max\_retries | int | 3 | Número de tentativas de repetição de implementações de avaliação malsucedidas antes de marcá-las como falhas permanentes. |
## Monitoramento e avaliação
```
aws sagemaker describe-job \
--job-name "my-agent-rft-eval-job" \
--job-category AgentRFTEvaluation \
--region us-west-2
```
## Interpretando os resultados da avaliação
Abra seu aplicativo MLflow para visualizar métricas registradas, distribuições de recompensas e visualizações de trajetória para a execução da avaliação. Veja abaixo a explicação sobre o que cada uma das métricas significa.
### Métricas de recompensa (`eval/reward/`)
| Métrica | Description |
| --- | --- |
| eval/reward/mean | Pontuação média de recompensa em todos os lançamentos. |
| eval/reward/min | Pontuação mínima de recompensa em todos os lançamentos. |
| eval/reward/max | Pontuação máxima de recompensa em todos os lançamentos. |
| eval/reward/std | Desvio padrão das pontuações de recompensa em todos os lançamentos. |
| eval/reward/zero\_frac | Fração de lançamentos com pontuação exata de 0 (falhas completas). |
| eval/reward/pass\_at\_1 | Probabilidade de que pelo menos 1 amostra em cada solicitação seja bem-sucedida. Essa é a principal métrica de sucesso. |
| eval/reward/pass\_power\_1 | Taxa de aprovação com ponderação de potência. |
| eval/reward/succeeded\_rollouts | Número total de lançamentos que obtiveram uma recompensa positiva. |
| eval/reward/failed\_rollouts | Número total de lançamentos que obtiveram pontuação 0. |
| eval/reward/num\_prompts | Número de solicitações distintas avaliadas. |
| eval/reward/rollouts\_per\_prompt | Número de tentativas (amostras) geradas por solicitação. |
| eval/reward/success\_threshold | O valor da recompensa necessário para considerar um lançamento como “bem-sucedido”. |
| eval/reward/mean\_within\_groups | Recompensa média por grupo de prompts (requer definir rollouts\_per\_prompt > 1). |
| eval/reward/std\_within\_groups | Desvio padrão da recompensa dentro de cada grupo de solicitações. |
| eval/reward/min\_within\_groups | Recompensa mínima em cada grupo de solicitações. |
| eval/reward/max\_within\_groups | Recompensa máxima dentro de cada grupo de solicitações. |
### Métricas de token (`eval/tokens/`)
| Métrica | Description |
| --- | --- |
| eval/tokens/prompt\_mean | Tamanho médio do prompt em tokens (inclui o prompt do sistema, as descrições das ferramentas e o contexto de vários turnos). |
| eval/tokens/response\_mean | Duração média da resposta do modelo em tokens por turno. |
| eval/tokens/response\_min | Resposta mais curta do modelo em tokens. |
| eval/tokens/response\_max | Resposta de modelo mais longa em tokens. |
| eval/tokens/response\_std | Desvio padrão dos comprimentos de resposta. A alta variação pode indicar um comportamento inconsistente do agente. |
### Métricas de turnos (`eval/turns/`)
| Métrica | Description |
| --- | --- |
| eval/turns/mean | Número médio de turnos por lançamento. Valores altos podem indicar que o agente está fazendo um loop ou tentando novamente em excesso. |
| eval/turns/min | Menos turnos em qualquer lançamento. |
| eval/turns/max | A maioria dos turnos em qualquer lançamento. Valores muito altos sugerem que o agente ficou preso sem resolver a tarefa. |
### Registrar métricas de probabilidade (`eval/logprob/`)
| Métrica | Description |
| --- | --- |
| eval/logprob/nz\_mean | Probabilidade logarítmica média de tokens diferentes de zero (sem preenchimento). Valores próximos a 0 indicam alta confiança do modelo. |
| eval/logprob/nz\_min | Símbolo de probabilidade logarítmica mais baixa (previsão menos confiável). |
| eval/logprob/nz\_max | Token de maior probabilidade logarítmica (previsão mais confiável). |
| eval/logprob/nz\_std | Desvio padrão de probabilidades logarítmicas diferentes de zero. Valores baixos significam confiança consistentemente alta. |
| eval/logprob/zero\_frac | Fração de tokens com probabilidade logarítmica exatamente zero (probabilidade 1,0), normalmente fichas de preenchimento ou forçadas. |
| eval/logprob/zero\_count | Contagem total de tokens zero-logprob. |
| eval/logprob/zero\_per\_group | Média de tokens zero-logprob por grupo de prompts. |
### Métricas de tempo (`timing_s/`)
| Métrica | Description |
| --- | --- |
| timing\_s/eval | Tempo total do relógio de parede para a avaliação em segundos. Divida por eval/reward/num\_prompts para ver o tempo médio por solicitação. |
### Como diagnosticar padrões comuns
| Padrão | Causa provável |
| --- | --- |
| pass\_at\_1 = 0, alto turns/mean | O agente está em loop sem resolver tarefas. Verifique o uso da ferramenta e os padrões de ação nas trajetórias. |
| pass\_at\_1 = 0, baixo tokens/response\_mean | Agente que produz respostas muito curtas (possivelmente vazias ou malformadas). Verifique o formato imediato e a compatibilidade do modelo. |
| Alto turns/max com baixo turns/min | O agente está mostrando um comportamento inconsistente em todas as solicitações. Algumas tarefas podem ser muito mais difíceis ou o agente pode estar falhando em interações específicas da ferramenta. |
| Alta confiança (logprob/nz\_meanperto de 0), mas baixa recompensa | O modelo está produzindo com confiança saídas erradas. Pode ser necessário mais diversidade de dados de treinamento ou refinamento do sinal de recompensa. |
| zero\_frac = 1.0em recompensa | Falha completa. Verifique a implantação do agente, a conectividade da ferramenta e se o formato do conjunto de dados de avaliação está correto. |
Para obter resultados brutos, revise os artefatos gravados no `S3OutputPath` especificado em`OutputDataConfig`.
## Limita as & cotas para avaliação
Use cotas AWS de serviço para solicitar um aumento de limite no número máximo de trabalhos de avaliação simultâneos.
| Quota | Padrão |
| --- | --- |
| rft-evaluation-job: máximo de trabalhos simultâneos | 1 |