Claude CodeにSageMaker AIプラグインを入れてモデルのファインチューニングを進める

AWSが公開しているsagemaker-aiプラグインは、Claude Codeに「基盤モデルのファインチューニングから評価、デプロイまで」と「SageMaker HyperPodクラスターの診断」の手順書(skill)を17個まとめて足します。AWS CLIの認証とIAMロールの用意さえ済んでいれば、導入は2コマンドで終わります。この記事は、何が入るのか、どう入れるのか、つまずきやすいIAMの条件はどこかを順に扱います。

sagemaker-aiプラグインは何を足すのか

プラグインはAWSのagent-pluginsリポジトリに含まれる1つで、Claude Code・Codex・Cursor向けに配られています。プラグイン本体の説明では、Amazon SageMaker AIの機能範囲に対するAWSの知見をコーディングアシスタントに持ち込むものと位置づけられています。

用意されている能力は2領域です。

MCPサーバーはaws-mcpが1つで、mcp-proxy-for-awsを介してAWSのドキュメントと手順(SOP)を引くための接続です。導入にはuvが必要です。

導入する

前提は3つです。Claude Codeが2.1.29以降であること、AWS CLIに認証情報が設定済みであること、MCPサーバーの起動に使うuvが入っていることです。

セッション内からは、マーケットプレイスを追加してからプラグインを入れます。

/plugin marketplace add awslabs/agent-plugins
/plugin install sagemaker-ai@agent-plugins-for-aws

ターミナルから直接入れる場合は、次のコマンドです。

claude plugins marketplace add awslabs/agent-plugins
claude plugins install sagemaker-ai@agent-plugins-for-aws

マーケットプレイスはagent-plugins-for-awsという名前で、同じリポジトリに他のAWS向けプラグインも入っています。他のプラグインの扱いはaws-serverlessプラグインの記事とDeploy on AWSプラグインの記事にまとめています。

先に整えるIAMロールとリージョン

生成されたskillはSageMaker AIのAPIを実際に呼びます。そのため、ロールの用意が導入の本体といえます。

ロールに必要な権限と信頼関係

README記載の条件は次のとおりです。

• SageMaker AIの操作(CreateTrainingJob、CreateEndpoint、CreateModelなど)に必要なIAM権限。AmazonSageMakerFullAccessマネージドポリシーで、skillが使う操作は賄えます
• 実行ロール(execution role)として使えること。信頼ポリシーにsagemaker.amazonaws.comが必要です
• BedrockへのデプロイとBedrockでの評価を使う場合は、bedrock.amazonaws.comも信頼し、Bedrock用の追加権限を付けます
• RLVRでのファインチューニングでは、報酬関数のLambdaをskillが作るためlambda.amazonaws.comも信頼します

Bedrock用の追加権限は、AmazonSageMakerFullAccessに含まれません。README掲載のポリシーは次の形です。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BedrockModelImportAndDeploy",
      "Effect": "Allow",
      "Action": [
        "bedrock:CreateModelImportJob",
        "bedrock:GetModelImportJob",
        "bedrock:DeleteImportedModel",
        "bedrock:CreateCustomModel",
        "bedrock:GetFoundationModel",
        "bedrock-runtime:Converse"
      ],
      "Resource": "*"
    }
  ]
}

リージョンはAWS_DEFAULT_REGIONで指定します。認証はAWS CLIのaws configureか、AWS_ACCESS_KEY_ID・AWS_SECRET_ACCESS_KEY・AWS_SESSION_TOKENの環境変数のどちらかです。condaやvenvを使う場合は、その環境の内側で環境変数を設定します。

名前に「sagemaker」が必要なバケットとLambda

見落としやすいのが、命名に依存した権限です。READMEによると、既定のSageMaker実行ポリシーがs3:GetObjectとs3:PutObjectを許すのは、名前に「sagemaker」を含むS3バケットだけです。データセットやモデルの成果物を別名のバケットに置くなら、そのバケットへのS3権限を足す必要があります。

RLVRの報酬関数も同じで、lambda:InvokeFunctionが許されるのは名前に「sagemaker」を含むLambda関数に限られます。別名で作るなら、より広いinvoke権限を付けます。

権限エラーが出たときは、Claudeにエラーを貼る前にバケット名とロールのポリシーを確認すると切り分けが早く済みます。

ローカルではなくSageMaker Spacesへのリモート接続の中でClaude Codeを使う場合は、認証情報と環境変数が構成済みです。READMEでは、認証と設定の前提手順を飛ばして、インストールからそのまま使えるとされています。

17個のskillの役割

skillは17個あり、前半9個がモデルカスタマイズ、後半8個がHyperPod向けです。

finetuningやmodel-deploymentのSKILL.mdは、sdk-getting-startedやmodel-selectionといった別のskillの起動も前提に書かれています。表の17個以外にも、リポジトリ内で参照されるskillがあります。

ファインチューニングを任せるときの流れ

READMEが示す使い方は、「Hi, help me customize a model」「I want to fine-tune a model for customer support classification」のように目的を話しかけるだけです。内部ではplanningが最初に起動します。

planningのSKILL.mdには、動きを理解するための決まりがいくつかあります。

• 質問は1回に1つだけ。すでに会話やプロジェクトのファイルから分かることは聞かない
• 最初に「評価から始める(evaluate-first)」か「直接ファインチューニングする」かを選ばせる。「ファインチューニングしたい」と言っただけでは、評価を飛ばす選択とはみなされない
• ベースモデルの選択はmodel-selectionだけが扱い、planningは好みを聞かない
• 計画をユーザーが承認するとPLAN.mdに書き出し、タスクの進行に応じて⬜・🔄・✅を更新する

つまり、Claudeが勝手に学習ジョブを走らせる設計ではなく、計画の承認と段階ごとの確認が挟まる作りです。finetuningのskillも、use_case_spec.mdが無ければ先にuse-case-specificationを起動するよう定められています。

デプロイの対象は限られる

model-deploymentが扱えるのは、SageMaker Serverless Model Customizationでファインチューニングしたモデルだけです。SKILL.mdには、次が対象外と書かれています。

• ファインチューニング前のベースモデル
• ほかの手順でファインチューニングしたモデル
• フルファインチューニング(LoRAのモデルのみ対応)

自前のノートブックで学習したモデルをこのskillで展開しようとしても、受け付けられません。展開まで一気通貫で任せたいなら、学習もプラグイン経由で行う必要があります。

制約が付くリージョンとモデル

READMEの注記は3点です。

• NovaモデルのカスタマイズはUS East(us-east-1)のみ。LLM-as-a-judgeによる評価にも対応しません
• LLM-as-a-judgeはAmazon Bedrock Evaluationsを使うため、Bedrock Evaluationsの料金が別にかかります。地理的な範囲内でリージョンをまたいでデータが送られる場合もあります
• Bedrockへデプロイして推論するときは、リージョン推論ポリシーでスケールの地理的な範囲を決めます

組織向けに手順を書き換える

READMEには、リポジトリをフォークしてSKILL.mdを書き換える使い方が示されています。承認済みの手法、必須の評価ベンチマーク、社内ツールの指定などを織り込めます。ワークスペース側のskillはグローバルのskillより優先されるため、チームごとの版を別々に持てます。

Claude Code側の設定としては、HyperPodのノードを操作するhyperpod-ssmに注意が要ります。このskillのSKILL.mdでは、aws CLI v2・session-manager-plugin・jq・unbuffer(expectパッケージ)が前提です。unbufferが無いと、コマンドが実行されたのに出力が空で返ることがあると書かれています。

権限設定では、AWSの認証情報を持つ環境でClaudeがAPIを呼べるため、学習ジョブの作成や削除を含むコマンドを自動承認にせず、プロンプトに残すほうが安全です。例えば.claude/settings.jsonのpermissions.askに、課金や削除につながるコマンドを置けます。

{
  "permissions": {
    "ask": [
      "Bash(aws sagemaker create-*)",
      "Bash(aws sagemaker delete-*)",
      "Bash(aws ssm start-session:*)"
    ]
  }
}

これは一例です。skillが生成するのは主にPythonのノートブックで、AWS CLIを直接呼ぶとは限らないため、実行前にセルの内容を読む運用が基本になります。

後継のAgent Toolkit for AWSとの関係

agent-pluginsリポジトリのREADME冒頭には、Agent Toolkit for AWSがAWS Labs上のMCPサーバー・プラグイン・skillの後継として公開されたと案内があります。本番ソフトウェアを作る場合や自社顧客向けのエージェントを作る場合は、そちらを推奨するという内容です。このリポジトリは引き続き動作し、貢献も受け付けられていますが、有用なプロジェクトは時間をかけてAgent Toolkit側へ移っていく方針です。

sagemaker-aiを今入れて使うのは問題ありません。ただ、長く運用するチームは、移行先の動向を見ながらフォークの管理範囲を決めておくと後で困りません。

まとめ

sagemaker-aiプラグインの導入そのものは2コマンドですが、実際に動かす前の作業が大半です。ロールの信頼ポリシー(sagemaker・bedrock・lambda)、名前に「sagemaker」を含むバケットとLambda、リージョンの3点を先に確認しておけば、学習の途中で権限エラーに当たる回数を減らせます。デプロイは同プラグインで学習したモデルだけが対象になるため、学習から展開までを1本の計画にまとめて始めるのが筋の通った使い方です。