# SageMaker 推論
カスタム Amazon Nova モデルが SageMaker 推論で利用可能になりました。SageMaker の Amazon Nova を使用すると、トレーニングされたカスタム Amazon Nova モデルから予測または推論の取得を開始できます。SageMaker の広範な ML インフラストラクチャとモデルデプロイオプションは、ML 推論のあらゆるニーズを満たすのに役立ちます。SageMaker 推論を使用すると、モデルのデプロイをスケールし、本番環境でモデルをより効果的に管理して、運用上の負担を軽減できます。
SageMaker には、低遅延推論を取得するためのリアルタイムエンドポイント、リクエストのバッチ用の非同期エンドポイントなど、さまざまな推論オプションが用意されています。ユースケースに適した推論オプションを活用することで、効率的なモデルのデプロイと推論を確保できます。SageMaker 推論の詳細については、「[推論のためのモデルをデプロイする](https://docs.aws.amazon.com//sagemaker/latest/dg/deploy-model.html)」を参照してください。
**重要**
SageMaker 推論では、フルランクのカスタムモデルと LoRA マージモデルのみがサポートされています。マージされていない LoRA モデルとベースモデルの場合は、Amazon Bedrock を使用します。
## 機能
SageMaker 推論の Amazon Nova モデルでは、以下の機能を使用できます。
**モデル機能**
+ テキスト生成
**デプロイとスケーリング**
+ カスタムインスタンス選択によるリアルタイムエンドポイント
+ Auto Scaling – トラフィックパターンに基づいてキャパシティを自動的に調整し、コストと GPU 使用率を最適化します。詳細については、「[Amazon SageMaker モデルを自動スケーリングする](https://docs.aws.amazon.com//sagemaker/latest/dg/endpoint-auto-scaling.html)」を参照してください。
+ リアルタイムトークン生成のためのストリーミング API サポート
**モニタリングと最適化**
+ モニタリングとアラートのための Amazon CloudWatch 統合
+ VPC 設定によるアベイラビリティーゾーンを考慮したレイテンシー最適化
**開発用ツール**
+ AWS CLI サポート – 詳細については、「[SageMaker の AWS CLI コマンドリファレンス](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/)」を参照してください。
+ SDK サポートによるノートブックの統合
## サポートされているモデルとインスタンス
SageMaker 推論エンドポイントを作成するときに、`CONTEXT_LENGTH` と `MAX_CONCURRENCY` の 2 つの環境変数を設定してデプロイを設定できます。
+ `CONTEXT_LENGTH` – リクエストあたりのトークンの最大合計長 (入力 \$1 出力)
+ `MAX_CONCURRENCY` – エンドポイントが処理する同時リクエストの最大数
以下の表に、サポートされている Amazon Nova モデル、インスタンスタイプ、およびサポートされている設定を示します。MAX\$1CONCURRENCY 値は、各 CONTEXT\$1LENGTH 設定でサポートされている最大同時実行数を表します。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/nova/latest/nova2-userguide/nova-model-sagemaker-inference.html)
**注記**
表示される MAX\$1CONCURRENCY 値は、各 CONTEXT\$1LENGTH 設定の上限です。同じ同時実行性でより短いコンテキスト長を使用することもできますが、これらの値を超えると、SageMaker エンドポイントの作成が失敗します。
例えば、Amazon Nova Micro を ml.g5.12xlarge で使用する場合:
`CONTEXT_LENGTH=2000`、`MAX_CONCURRENCY=32` → 有効
`CONTEXT_LENGTH=8000`、`MAX_CONCURRENCY=32` → 拒否 (コンテキスト長 8000 の場合、同時実行制限は 16 です)
`CONTEXT_LENGTH=8000`、`MAX_CONCURRENCY=4` → 有効
`CONTEXT_LENGTH=8000`、`MAX_CONCURRENCY=16` → 有効
`CONTEXT_LENGTH=10000` → 拒否 (このインスタンスの最大コンテキスト長は 8000 であるため)
## サポート対象の AWS リージョン
以下の表に、Amazon Nova モデルが SageMaker 推論で使用できる AWS リージョンを示します。
****
| リージョン名 | リージョンコード | 利用可能な状況 |
| --- | --- | --- |
| 米国東部 (バージニア北部) | us–east–1 | 使用可能 |
| 米国西部 (オレゴン) | us-west-2 | 使用可能 |
## サポートされているコンテナイメージ
以下の表に、SageMaker 推論の Amazon Nova モデルのコンテナイメージ URI をリージョン別に一覧表示します。リージョンごとに、バージョニングされたタグ (`v1.0.0`) と最新のタグ (`SM-Inference-latest`) の 2 つのイメージタグを使用できます。本番デプロイでは、バージョニングされたタグを使用することをお勧めします。
****
| リージョン | コンテナイメージ URI |
| --- | --- |
| 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 |
## ベストプラクティス
SageMaker でのモデルのデプロイと管理に関するベストプラクティスについては、「[SageMaker のベストプラクティス](https://docs.aws.amazon.com//sagemaker/latest/dg/best-practices.html)」を参照してください。
## サポート
SageMaker 推論における Amazon Nova モデルの問題とサポートについては、コンソールまたは AWS アカウントマネージャーを通じて AWS サポートにお問い合わせください。
**Topics**
+ [
## 機能
](#nova-sagemaker-inference-features)
+ [
## サポートされているモデルとインスタンス
](#nova-sagemaker-inference-supported)
+ [
## サポート対象の AWS リージョン
](#nova-sagemaker-inference-regions)
+ [
## サポートされているコンテナイメージ
](#nova-sagemaker-inference-container-images)
+ [
## ベストプラクティス
](#nova-sagemaker-inference-best-practices)
+ [
## サポート
](#nova-sagemaker-inference-support)
+ [
# 開始方法
](nova-sagemaker-inference-getting-started.md)
+ [
# API リファレンス
](nova-sagemaker-inference-api-reference.md)
+ [
# SageMaker 推論でホストされるモデルを評価する
](nova-eval-on-sagemaker-inference.md)
+ [
# Amazon SageMaker 推論不正検出での Amazon Nova Forge モデルのデプロイ
](nova-sagemaker-inference-abuse-detection.md)
# 開始方法
このガイドでは、カスタマイズされた Amazon Nova モデルを SageMaker リアルタイムエンドポイントにデプロイし、推論パラメータを設定し、テスト用にモデルを呼び出す方法について説明します。
## 前提条件
Amazon Nova モデルを SageMaker 推論にデプロイするための前提条件は以下のとおりです。
+ AWS アカウント の作成 - まだ作成していない場合は、「[AWS アカウントを作成する](https://docs.aws.amazon.com//sagemaker/latest/dg/gs-set-up.html#sign-up-for-aws)」を参照してください。
+ 必要な IAM アクセス許可 - IAM ユーザーまたはロールに以下の管理ポリシーがアタッチされていることを確認します。
+ `AmazonSageMakerFullAccess`
+ `AmazonS3FullAccess`
+ 必要な SDK/CLI バージョン - 以下の SDK バージョンは、SageMaker 推論の Amazon Nova モデルでテストおよび検証されています。
+ リソースベースの API アプローチ用の SageMaker Python SDK v3.0.0\$1 (`sagemaker>=3.0.0`)
+ 直接 API コール用の Boto3 バージョン 1.35.0\$1 (`boto3>=1.35.0`)。このガイドの例では、このアプローチを使用します。
+ サービスクォータの引き上げ – SageMaker 推論エンドポイント用に使用する予定の ML インスタンスタイプに対する Amazon SageMaker サービスクォータの引き上げをリクエストします (例: `ml.p5.48xlarge for endpoint usage`)。サポートされているインスタンスタイプについては、「[サポートされているモデルとインスタンス](nova-model-sagemaker-inference.md#nova-sagemaker-inference-supported)」を参照してください。引き上げをリクエストするには、「[クォータ引き上げのリクエスト](https://docs.aws.amazon.com//servicequotas/latest/userguide/request-quota-increase.html)」を参照してください。SageMaker インスタンスのクォータについては、「[SageMaker エンドポイントとクォータ](https://docs.aws.amazon.com//general/latest/gr/sagemaker.html)」を参照してください。
## ステップ 1: AWS 認証情報を設定する
以下のいずれかの方法を使用して、AWS 認証情報を設定します。
**オプション 1: AWS CLI (推奨)**
```
aws configure
```
プロンプトが表示されたら、AWS アクセスキー、シークレットキー、およびデフォルトのリージョンを入力します。
**オプション 2: AWS 認証情報ファイル**
`~/.aws/credentials` を作成または編集します。
```
[default]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY
```
**オプション 3: 環境変数**
```
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
```
**注記**
AWS 認証情報の詳細については、「[設定ファイルと認証情報ファイルの設定](https://docs.aws.amazon.com//cli/latest/userguide/cli-configure-files.html)」を参照してください。
**AWS クライアントを初期化する**
以下のコードを使用して Python スクリプトまたはノートブックを作成し、AWS SDK を初期化して認証情報を検証します。
```
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.")
```
認証が成功すると、AWS アカウント ID を確認する出力が表示されます。
## ステップ 2: SageMaker 実行ロールを作成する
SageMaker 実行ロールは、モデルアーティファクト用の Amazon S3 バケットやログ記録用の CloudWatch など、ユーザーに代わって AWS リソースにアクセスするためのアクセス許可を SageMaker に付与する IAM ロールです。
**実行ロールを作成する**
**注記**
IAM ロールを作成するには、`iam:CreateRole` および `iam:AttachRolePolicy` アクセス許可が必要です。先に進む前に、IAM ユーザーまたはロールにこれらのアクセス許可があることを確認してください。
以下のコードは、Amazon Nova カスタマイズモデルをデプロイするために必要なアクセス許可を持つ IAM ロールを作成します。
```
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}")
```
**既存の実行ロールを使用する (オプション)**
SageMaker 実行ロールが既にある場合は、代わりに使用できます。
```
# Replace with your existing role ARN
SAGEMAKER_EXECUTION_ROLE_ARN = "arn:aws:iam::YOUR_ACCOUNT_ID:role/YOUR_EXISTING_ROLE_NAME"
```
アカウント内の既存の SageMaker ロールを検索するには:
```
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']}")
```
**重要**
実行ロールには、Amazon S3 および SageMaker リソースにアクセスするための `sagemaker.amazonaws.com` との信頼関係とアクセス許可が必要です。
SageMaker 実行ロールの詳細については、「[SageMaker ロール](https://docs.aws.amazon.com//sagemaker/latest/dg/sagemaker-roles.html)」を参照してください。
## ステップ 3: モデルパラメータを設定する
Amazon Nova モデルのデプロイパラメータを設定します。これらの設定は、モデルの動作、リソース割り当て、推論特性を制御します。サポートされているインスタンスタイプと、それぞれでサポートされている CONTEXT\$1LENGTH および MAX\$1CONCURRENCY 値のリストについては、「[サポートされているモデルとインスタンス](nova-model-sagemaker-inference.md#nova-sagemaker-inference-supported)」を参照してください。
**必須パラメータ**
+ `IMAGE`: Amazon Nova 推論コンテナの Docker コンテナイメージ URI。これは AWS によって提供されます。
+ `CONTEXT_LENGTH`: モデルコンテキストの長さ。
+ `MAX_CONCURRENCY`: イテレーションあたりのシーケンスの最大数。GPU 上の 1 つのバッチ内で同時に処理できる個々のユーザーリクエスト (プロンプト) の数に制限を設定します。範囲: 0 より大きい整数。
**オプションの生成パラメータ**
+ `DEFAULT_TEMPERATURE`: 生成時のランダム性を制御します。範囲: 0.0～2.0 (0.0 は決定的、値が高いほどランダム性が増加)。
+ `DEFAULT_TOP_P`: トークン選択の Nucleus サンプリングしきい値。範囲: 1e-10～1.0。
+ `DEFAULT_TOP_K`: 最も可能性の高い上位 K 個のトークンにトークン選択を制限します。範囲: 整数 -1 以上 (-1 は制限なし)。
+ `DEFAULT_MAX_NEW_TOKENS`: レスポンスで生成するトークンの最大数 (最大出力トークン)。範囲: 整数 1 以上。
+ `DEFAULT_LOGPROBS`: トークンごとに返されるログ確率の数。範囲: 整数 1～20。
**デプロイを設定する**
```
# 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}")
```
**デプロイ固有のパラメータを設定する**
ここで、モデルアーティファクトの場所やインスタンスタイプの選択など、Amazon Nova モデルデプロイの特定のパラメータを設定します。
**デプロイ識別子を設定する**
```
# Deployment identifier - use a descriptive name for your use case
JOB_NAME = "my-nova-deployment"
```
**モデルアーティファクトの場所を指定する**
トレーニングされた Amazon Nova モデルアーティファクトが保存されている Amazon S3 URI を指定します。これは、モデルトレーニングまたはファインチューニングジョブの出力場所である必要があります。
```
# 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/"
```
**モデルバリアントとインスタンスタイプを選択する**
```
# 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}")
```
**命名規則**
コードは、AWS リソースの一貫した名前を自動的に生成します。
+ モデル名: `{JOB_NAME}-{model}-{instance-type}`
+ エンドポイント設定: `{MODEL_NAME}-Config`
+ エンドポイント名: `{MODEL_NAME}-Endpoint`
## ステップ 4: SageMaker モデルとエンドポイント設定を作成する
このステップでは、Amazon Nova モデルアーティファクトを参照する SageMaker モデルオブジェクトと、モデルのデプロイ方法を定義するエンドポイント設定の 2 つの重要なリソースを作成します。
**SageMaker モデル**: 推論コンテナイメージ、モデルアーティファクトの場所、環境設定をパッケージ化するモデルオブジェクト。これは、複数のエンドポイントにデプロイできる再利用可能なリソースです。
**エンドポイント設定**: インスタンスタイプ、インスタンス数、モデルバリアントなど、デプロイのインフラストラクチャ設定を定義します。これにより、モデル自体とは別にデプロイ設定を管理できます。
**SageMaker モデルを作成する**
以下のコードは、Amazon Nova モデルアーティファクトを参照する SageMaker モデルを作成します。
```
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}")
```
主要パラメータ:
+ `ModelName`: モデルの一意の識別子
+ `Image`: Amazon Nova 推論の Docker コンテナイメージ URI
+ `ModelDataSource`: モデルアーティファクトの Amazon S3 の場所
+ `Environment`: ステップ 3 で設定した環境変数
+ `ExecutionRoleArn`: ステップ 2 の IAM ロール
+ `EnableNetworkIsolation`: セキュリティを強化するために True に設定 (コンテナがアウトバウンドネットワークコールを実行できないようにします)
**エンドポイント設定を作成する**
次に、デプロイインフラストラクチャを定義するエンドポイント設定を作成します。
```
# 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}")
```
主要パラメータ:
+ `VariantName`: このモデルバリアントの識別子 (単一モデルデプロイには 'primary' を使用)
+ `ModelName`: 上記で作成したモデルを参照します
+ `InitialInstanceCount`: デプロイするインスタンスの数 (1 で始まり、必要に応じて後でスケールします)
+ `InstanceType`: ステップ 3 で選択した ML インスタンスタイプ
**リソースの作成を確認する**
リソースが正常に作成されたことを確認できます。
```
# 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")
```
## ステップ 5: エンドポイントをデプロイする
次のステップでは、SageMaker リアルタイムエンドポイントを作成して Amazon Nova モデルをデプロイします。このエンドポイントはモデルをホストし、推論リクエストを行うための安全な HTTPS エンドポイントを提供します。
AWS がインフラストラクチャをプロビジョニングし、モデルアーティファクトをダウンロードし、推論コンテナを初期化するため、エンドポイントの作成には通常 15～30 分かかります。
**エンドポイントの作成**
```
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}")
```
**エンドポイントの作成をモニタリングする**
以下のコードは、デプロイが完了するまでエンドポイントのステータスをポーリングします。
```
# 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
```
**エンドポイントの準備が整っていることを確認する**
エンドポイントが InService になったら、その設定を確認できます。
```
# 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
```
**エンドポイント作成失敗のトラブルシューティング**
一般的な障害の理由:
+ **キャパシティ不足**: 要求されたインスタンスタイプは、お客様のリージョンでは利用できません
+ 解決策: 別のインスタンスタイプを試すか、クォータの引き上げをリクエストします
+ **IAM アクセス許可**: 実行ロールに必要なアクセス許可がありません
+ 解決策: ロールが Amazon S3 モデルアーティファクトと必要な SageMaker アクセス許可にアクセスできることを確認します
+ **モデルアーティファクトが見つかりません**: Amazon S3 URI が正しくないか、アクセスできません
+ 解決策: Amazon S3 URI を検証し、バケットのアクセス許可を確認し、正しいリージョンにいることを確認します
+ **リソース制限**: エンドポイントまたはインスタンスのアカウント制限を超えました
+ 解決策: Service Quotas または AWS サポートを通じて Service Quotas の引き上げをリクエストします
**注記**
失敗したエンドポイントを削除してやり直す必要がある場合:
```
sagemaker.delete_endpoint(EndpointName=ENDPOINT_NAME)
```
## ステップ 6: エンドポイントを呼び出す
エンドポイントが InService になったら、推論リクエストを送信して Amazon Nova モデルから予測を生成できます。SageMaker は、同期エンドポイント (ストリーミング/非ストリーミングモードによるリアルタイム) と非同期エンドポイント (バッチ処理用の Amazon S3 ベース) をサポートしています。
**ランタイムクライアントをセットアップする**
適切なタイムアウト設定で SageMaker Runtime クライアントを作成します。
```
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)
```
**ユニバーサル推論関数を作成する**
以下の関数は、ストリーミングリクエストと非ストリーミングリクエストの両方を処理します。
```
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)}")
```
**例 1: 非ストリーミング形式のチャット補完**
会話型インタラクションには、チャット形式を使用します。
```
# 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)
```
**レスポンス例**:
```
{
"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
}
}
```
**例 2: シンプルなテキスト補完**
簡単なテキスト生成には、補完形式を使用します。
```
# 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)
```
**レスポンス例**:
```
{
"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
}
}
```
**例 3: ストリーミング形式のチャット補完**
```
# 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)
```
**ストリーミング出力の例:**
```
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]
```
**例 4: マルチモーダル形式のチャット補完**
イメージとテキストの入力には、マルチモーダル形式を使用します。
```
# 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)
```
**レスポンス例**:
```
{
"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
}
}
```
## ステップ 7: リソースをクリーンアップする (オプション)
不要な料金が発生しないようにするには、このチュートリアルで作成した AWS リソースを削除します。SageMaker エンドポイントでは、推論リクエストをアクティブに行っていない場合でも、実行中に料金が発生します。
**重要**
リソースの削除は永続的であり、元に戻すことはできません。続行する前に、これらのリソースが不要になったことを確認してください。
**エンドポイントを削除する**
```
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}")
```
**注記**
エンドポイントの削除は非同期で実行されます。削除ステータスをモニタリングできます。
```
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
```
**エンドポイント設定を削除する**
エンドポイントが削除されたら、エンドポイント設定を削除します。
```
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}")
```
**モデルを削除する**
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}")
```
# API リファレンス
SageMaker の Amazon Nova モデルは、推論に標準の SageMaker ランタイム API を使用します。完全な API ドキュメントについては、「[デプロイされたモデルをテストする](https://docs.aws.amazon.com//sagemaker/latest/dg/realtime-endpoints-test-endpoints.html)」を参照してください。
## エンドポイントの呼び出し
SageMaker の Amazon Nova モデルは、以下の 2 つの呼び出し方法をサポートしています。
+ **同期呼び出し**: [InvokeEndpoint](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html) API をリアルタイムの非ストリーミング推論リクエストに使用します。
+ **ストリーミング呼び出し**: リアルタイムストリーミング推論リクエストには [InvokeEndpointWithResponseStream](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpointWithResponseStream.html) API を使用します。
## リクエストの形式
Amazon Nova モデルは、以下の 2 つのリクエスト形式をサポートしています。
**チャット補完形式**
会話型インタラクションには、以下の形式を使用します。
```
{
"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
}
}
```
**テキスト補完形式**
シンプルなテキスト生成には、以下の形式を使用します。
```
{
"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
}
}
```
**マルチモーダルチャット補完形式**
イメージとテキストの入力には、以下の形式を使用します。
```
{
"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
}
```
**リクエストパラメータ**
+ `messages` (配列): チャット補完形式用。フィールド `role` と `content` フィールドを持つメッセージオブジェクトの配列。コンテンツは、テキストのみの文字列でも、マルチモーダル入力の配列でもかまいません。
+ `prompt` (文字列): テキスト補完形式用。生成元の入力テキスト。
+ `max_tokens` (整数): レスポンスで生成するトークンの最大数。範囲: 1 以上。
+ `max_completion_tokens` (整数): チャット補完用の max\$1tokens の代替。生成する補完トークンの最大数。
+ `temperature` (浮動): 生成時のランダム性を制御します。範囲: 0.0～2.0 (0.0 = 決定的、2.0 = 最大ランダム性)。
+ `top_p` (浮動): Nucleus サンプリングしきい値。範囲: 1e-10～1.0。
+ `top_k` (整数): 最も可能性の高い上位 K 個のトークンにトークン選択を制限します。範囲: -1 以上 (-1 = 制限なし)。
+ `stream` (ブール値): レスポンスをストリーミングするかどうか。ストリーミングする場合は `true` に設定し、ストリーミングしない場合は `false` に設定します。
+ `logprobs` (ブール値/整数): チャット補完の場合は、ブール値を使用します。テキスト補完の場合は、返されるログ確率の数に整数を使用します。範囲: 1～20 です。
+ `top_logprobs` (整数): 確率の高い上位トークンのログ確率をいくつ返すか指定します (チャットの完了のみ)。
+ `reasoning_effort` (文字列): 推論の労力のレベル。オプション:「low」、「high」(Nova 2 Lite カスタムモデルのチャット完了のみ)。
+ `allowed_token_ids` (配列): 生成できるトークン ID のリスト。指定されたトークンへの出力を制限します。
+ `truncate_prompt_tokens` (整数): 制限を超えた場合は、この数のトークンにプロンプトを切り捨てます。
+ `stream_options` (オブジェクト): ストリーミングレスポンスのオプション。ストリーミングレスポンスにトークン使用量を含める `include_usage` ブール値が含まれます。
## レスポンスの形式
レスポンスの形式は、呼び出し方法とリクエストタイプによって異なります。
**チャット補完レスポンス (非ストリーミング)**
同期チャット補完リクエストの場合:
```
{
"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]
}
```
**テキスト補完レスポンス (非ストリーミング)**
同期テキスト補完リクエストの場合:
```
{
"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
}
}
}
```
**チャット補完ストリーミングレスポンス**
ストリーミングチャット補完リクエストの場合、レスポンスはサーバー送信イベント (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]
```
**テキスト補完ストリーミングレスポンス**
ストリーミングテキスト補完リクエストの場合:
```
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]
```
**レスポンスフィールドの説明**
+ `id`: 補完の一意の識別子
+ `object`: 返されるオブジェクトのタイプ ("chat.completion"、"text\$1completion"、"chat.completion.chunk")
+ `created`: 補完が作成された時刻の Unix タイムスタンプ
+ `model`: 補完に使用されるモデル
+ `choices`: 補完選択肢の配列
+ `usage`: プロンプト、補完、合計トークンを含むトークン使用状況情報
+ `logprobs`: トークンのログ確率情報 (リクエストされた場合)
+ `finish_reason`: モデルが生成を停止した理由 ("stop"、"length"、"content\$1filter")
+ `delta`: ストリーミングレスポンスの増分コンテンツ
+ `reasoning`: reasoning\$1effort を使用する場合の推論コンテンツ
+ `token_ids`: 生成されたテキストのトークン ID の配列
完全な API ドキュメントについては、「[InvokeEndpoint API リファレンス](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html)」および「[InvokeEndpointWithResponseStream API リファレンス](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_runtime_InvokeEndpointWithResponseStream.html)」を参照してください。
# SageMaker 推論でホストされるモデルを評価する
このガイドでは、オープンソースの評価フレームワークである [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)」を参照してください。
## 概要:
AI 研究コミュニティの標準化されたベンチマークを使用して、SageMaker エンドポイントにデプロイされたカスタマイズされた Amazon Nova モデルを評価できます。このアプローチにより、以下のことが可能になります。
+ カスタマイズされた Amazon Nova モデル (ファインチューニング済み、蒸留済み、またはその他の方法で適応させた) を大規模に評価する
+ 複数のエンドポイントインスタンスで並列推論を使用して評価を実行する
+ MMLU、TruthfulQA、HumanEval などのベンチマークを使用してモデルのパフォーマンスを比較する
+ 既存の SageMaker インフラストラクチャとの統合
## サポートされているモデル
SageMaker 推論プロバイダーは以下を使用します。
+ Amazon Nova モデル (Nova Micro、Nova Lite、Nova Lite 2)
+ vLLM または OpenAI 互換推論サーバーを介してデプロイされたモデル
+ OpenAI Chat Completions API 形式をサポートするエンドポイント
## 前提条件
開始する前に、以下を確認してください。
+ SageMaker エンドポイントを作成して呼び出すアクセス許可を持つ AWS アカウント
+ AWS 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 エンドポイントをデプロイする
評価を実行する前に、モデルを実行する SageMaker 推論エンドポイントが必要です。
Amazon Nova モデルで SageMaker 推論エンドポイントを作成する手順については、「[開始方法](nova-sagemaker-inference-getting-started.md)」を参照してください。
エンドポイントのステータスが `InService` になったら、評価コマンドで使用するエンドポイント名を書き留めます。
## ステップ 2: 評価の依存関係をインストールする
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 認証情報を設定する
以下のいずれかの認証方法を選択します。
**オプション 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 プロバイダーをインストールする
SageMaker プロバイダーは、Inspect AI が SageMaker エンドポイントと通信できるようにします。プロバイダーのインストールプロセスは、[クイックスタートノートブック](https://github.com/aws-samples/amazon-nova-samples/tree/main/customization/sagemaker-inference/sagemaker_inspect_quickstart.ipynb)で合理化されています。
## ステップ 5: 評価ベンチマークをダウンロードする
Inspect Evals リポジトリのクローンを作成して、標準ベンチマークにアクセスします。
```
git clone https://github.com/UKGovernmentBEIS/inspect_evals.git
```
このリポジトリには、以下のようなベンチマークが含まれています。
+ MMLU と MMLU-Pro (知識と推論)
+ TruthfulQA (真実性)
+ HumanEval (コード生成)
+ GSM8K (数学的推論)
## ステップ 6: 評価を実行する
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 インスタンス × 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: 結果を表示する
Inspect AI ビューワーを起動して、評価結果を分析します。
```
inspect view
```
ビューワーに以下が表示されます。
+ 全体的なスコアとメトリクス
+ モデルレスポンスを含むサンプルごとの結果
+ エラー分析と障害パターン
## エンドポイントの管理
**エンドポイントを更新する**
既存のエンドポイントを新しいモデルまたは設定で更新するには:
```
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)
```
## カスタムベンチマークをオンボードする
以下のワークフローを使用して、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()
)
```
## トラブルシューティング
**一般的な問題**
**エンドポイントのスロットリングまたはタイムアウト**
+ `--max-connections` を減らします
+ `--max-retries` を増やします
+ エンドポイントの CloudWatch メトリクスにキャパシティの問題がないか確認します
**認証エラー**
+ AWS 認証情報が正しく設定されていることを確認します
+ IAM アクセス許可に `sagemaker:InvokeEndpoint` が含まれているか確認します
**モデルエラー**
+ エンドポイントが `InService` ステータスであることを確認します
+ モデルが OpenAI Chat Completions API 形式をサポートしていることを確認します
## 関連リソース
+ [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)
# Amazon SageMaker 推論不正検出での Amazon Nova Forge モデルのデプロイ
AWS は AI の責任ある利用に取り組んでいます。誤用の可能性を防ぐために、Amazon SageMaker 推論に Amazon Nova Forge Models をデプロイする際、SageMaker 推論は自動不正検出メカニズムを実装して、[責任ある AI ポリシー](https://aws.amazon.com/ai/responsible-ai/policy/)を含む AWS の[適正利用ポリシー](https://aws.amazon.com/aup/) (AUP) とサービス利用規約への潜在的な違反を特定します。
Amazon の不正検出メカニズムは完全に自動化されているため、ユーザー入力やモデル出力を人間が確認したりアクセスしたりする必要はありません。
不正利用の自動検出には以下が含まれます。
+ **コンテンツの分類** – 分類子を使用して、ユーザー入力やモデル出力に含まれる有害なコンテンツ (暴力を扇動するコンテンツなど) を検出します。分類子は、モデルの入力と出力を処理し、攻撃の種類と信頼度を割り当てるアルゴリズムです。Amazon Nova Forge モデルの使用時にこれらの分類子を実行する場合があります。分類プロセスは自動化されており、ユーザー入力やモデル出力を人間が確認する必要はありません。
+ **パターンの特定** – 分類メトリクスを使用して、違反の芽や繰り返し発生する動作を特定します。匿名化された分類子メトリクスをコンパイルして共有する場合があります。Amazon SageMaker Inference はユーザー入力またはモデル出力を保存しません。
+ **児童性的虐待コンテンツ (CSAM) の検出とブロック** – お客様は、お客様自身 (およびエンドユーザー) が Amazon SageMaker 推論にアップロードするコンテンツについて責任を負い、こうした違法な画像が含まれるコンテンツを確実に排除する必要があります。CSAM の拡散を防止するために、Amazon SageMaker 推論で Amazon Nova Forge モデルをデプロイする際、SageMaker 推論は自動不正検出メカニズム (ハッシュマッチング技術や分類子など) を使用して、CSAM とみられるコンテンツの検出が行われる場合があります。画像入力に CSAM とみられるコンテンツが検出されると、Amazon SageMaker 推論はリクエストをブロックし、ユーザーに自動エラーメッセージを送信します。Amazon SageMaker 推論は、National Center for Missing and Exploited Children (NCMEC) または関連機関に報告を提出する場合もあります。当社では、CSAM の問題を重く受け止め、検出、ブロック、報告のメカニズムを引き続き更新していきます。お客様は、適用される法律により追加のアクションを求められる場合があり、こうしたアクションの実施は、お客様の責任となります。
当社の自動不正検出メカニズムによって違反の芽が特定されると、お客様による Amazon SageMaker 推論の使用状況、および当社のサービス利用規約の遵守について、当社から情報を求める場合があります。お客様がこれらの規約またはポリシーを遵守するための対策を取らない場合、遵守する意思がない場合、または遵守することができない場合、AWS は Amazon SageMaker 推論へのアクセスを停止することがあります。また、自動テストでモデルのレスポンスが当社の利用規約やポリシーに反していることが検出された場合、失敗した推論ジョブに対して課金される場合があります。
ご質問がある場合は、AWS サポートまでご連絡ください。詳細については、「[Amazon SageMaker に関するよくある質問](https://aws.amazon.com/sagemaker/ai/faqs/)」を参照してください。