# 评估在 SageMaker 推理上托管的模型
<a name="nova-eval-on-sagemaker-inference"></a>

本指南介绍如何使用开源评估框架 [Inspect AI](https://github.com/UKGovernmentBEIS/inspect_ai)，对部署在 SageMaker 推理端点上的自定义 Amazon Nova 模型进行评估。

**注意**  
有关实操演示，请参阅 [SageMaker Inspect AI 快速入门笔记本](https://github.com/aws-samples/amazon-nova-samples/tree/main/customization/sagemaker-inference/sagemaker_inspect_quickstart.ipynb)。

## 概述
<a name="nova-eval-sagemaker-overview"></a>

您可以使用人工智能研究社区的标准化基准，对部署在 SageMaker 端点上的自定义 Amazon Nova 模型进行评估。该方式支持：
+ 大规模评估自定义 Amazon Nova 模型（微调、蒸馏或其他适配版本）
+ 通过多端点实例并行推理执行评估
+ 使用 MMLU、TruthfulQA、HumanEval 等基准对比模型性能
+ 与现有的 SageMaker 基础设施集成

## 支持的模型
<a name="nova-eval-sagemaker-supported-models"></a>

SageMaker 推理提供程序支持以下模型/端点类型：
+ Amazon Nova 系列模型（Nova Micro、Nova Lite、Nova Lite 2）
+ 通过 vLLM 或兼容 OpenAI 协议的推理服务器部署的模型
+ 任何支持 OpenAI Chat Completions API 格式的端点

## 先决条件
<a name="nova-eval-sagemaker-prerequisites"></a>

在开始之前，请确保您满足以下条件：
+ 拥有 AWS 账户，且该账户具备创建和调用 SageMaker 端点的权限
+ 已通过 AWS CLI CLI、环境变量或 IAM 角色配置好 AWS 凭证
+ Python 3.9 或更高版本

**所需的 IAM 权限**

您的 IAM 用户或角色需具备以下权限：

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

## 步骤 1：部署 SageMaker端点
<a name="nova-eval-sagemaker-step1"></a>

运行评估前，需先部署承载目标模型的 SageMaker 推理端点。

有关使用 Amazon Nova 模型创建 SageMaker 推理端点的操作指引，请参阅[入门](nova-sagemaker-inference-getting-started.md)。

当端点状态变为 `InService` 后，请记录端点名称，以便在评估命令中使用。

## 步骤 2：安装评估依赖项
<a name="nova-eval-sagemaker-step2"></a>

创建 Python 虚拟环境，并安装所需的依赖包。

```
# 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
```

## 步骤 3：配置 AWS 凭证
<a name="nova-eval-sagemaker-step3"></a>

选择以下任一身份验证方式：

**选项 1：AWS CLI（建议）**

```
aws configure
```

提示后，输入 AWS 访问密钥 ID、秘密访问密钥和默认区域名称。

**选项 2：环境变量**

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

**选项 3：IAM 角色**

若在 Amazon EC2 或 SageMaker 笔记本中运行，将自动使用实例的 IAM 角色。

**验证凭证**

```
import boto3

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

## 步骤 4：安装 SageMaker 提供程序
<a name="nova-eval-sagemaker-step4"></a>

SageMaker 提供程序用于让 Inspect AI 与您的 SageMaker 端点通信。[快速入门笔记本](https://github.com/aws-samples/amazon-nova-samples/tree/main/customization/sagemaker-inference/sagemaker_inspect_quickstart.ipynb)中已简化该提供程序的安装流程。

## 步骤 5：下载评估基准
<a name="nova-eval-sagemaker-step5"></a>

克隆 Inspect Evals 存储库以获取标准评估基准：

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

该存储库包含的评估基准包括：
+ MMLU 和 mmlu-Pro（知识与推理）
+ TruthfulQA（真实性）
+ HumanEval（代码生成）
+ GSM8K（数学推理）

## 步骤 6：运行评估
<a name="nova-eval-sagemaker-step6"></a>

使用您的 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
```

**关键参数**


| 参数 | 默认值 | 说明 | 
| --- | --- | --- | 
| --max-connections | 10 | 发送到端点的并行请求数。需随实例数量调整（例如：10 个实例 x 25 = 250）。 | 
| --max-retries | 3 | 失败请求的重试次数。大规模评估建议设为 50–100。 | 
| -M region\$1name | us-east-1 | 端点部署所在的 AWS 区域。 | 
| -M read\$1timeout | 600 | 请求超时时间（单位：秒）。 | 
| -M connect\$1timeout | 60 | 连接超时时间（单位：秒）。 | 

**调优建议**

针对多实例端点：

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

`--max-connections` 设置过高可能导致端点过载并触发节流；设置过低则会造成资源利用率不足。

## 步骤 7：查看结果
<a name="nova-eval-sagemaker-step7"></a>

启动 Inspect AI 可视化工具分析评估结果：

```
inspect view
```

该工具将展示以下内容：
+ 整体得分与指标
+ 含模型响应的单样本评估结果
+ 错误分析与失败模式

## 管理终端节点
<a name="nova-eval-sagemaker-managing-endpoints"></a>

**更新端点**

如需使用新模型或新配置更新现有端点：

```
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
)
```

**删除端点**

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

## 添加自定义评估基准
<a name="nova-eval-sagemaker-custom-benchmarks"></a>

您可通过以下工作流向 Inspect AI 添加新的评估基准：

1. 研究基准数据集格式与评估指标

1. 参考 `inspect_evals/` 中类似的实现

1. 创建任务文件，将数据集记录转换为 Inspect AI 样本

1. 实现对应的求解器与评分器

1. 使用小规模测试运行进行验证

示例任务结构：

```
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()
    )
```

## 问题排查
<a name="nova-eval-sagemaker-troubleshooting"></a>

**常见问题**

**端点节流或超时**
+ 降低 `--max-connections`
+ 提高 `--max-retries`
+ 查看端点的 CloudWatch 指标，确认是否存在容量问题

**身份验证错误**
+ 确认 AWS 凭证配置正确
+ 检查 IAM 权限是否包含 `sagemaker:InvokeEndpoint`

**模型错误**
+ 确认端点处于 `InService` 状态
+ 检查模型是否支持 OpenAI Chat Completions API 格式

## 相关资源
<a name="nova-eval-sagemaker-related-resources"></a>
+ [Inspect AI 文档](https://inspect.ai-safety-institute.org.uk/)
+ [Inspect Evals 存储库](https://github.com/UKGovernmentBEIS/inspect_evals)
+ [SageMaker 开发人员指南](https://docs.aws.amazon.com//sagemaker/latest/dg/whatis.html)
+ [署模型用于推理](https://docs.aws.amazon.com//sagemaker/latest/dg/deploy-model.html)
+ [配置 AWS CLI](https://docs.aws.amazon.com//cli/latest/userguide/cli-chap-configure.html)