翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# LoRA アダプターを使用してモデルのレコメンデーションを取得する
<a name="generative-ai-inference-recommendations-adapters"></a>

Low-Rank Adaptation (LoRA) は、固定ベースモデル上にアダプターの重みの小さなセットをトレーニングする、パラメータ効率の高い微調整手法です。1 つのエンドポイントで 1 つのベースモデルを共有する多くのアダプターを提供できます。これは、微調整されたバリアントごとにモデルの個別のコピーをデプロイするよりもコスト効率が高くなります。

推奨ジョブにアダプターを追加すると、SageMaker AI は*マルチアダプター*デプロイのサイズとベンチマークを行います。このデプロイは、同じエンドポイント上のアダプター[推論コンポーネント](realtime-endpoints-deploy-models.md#inference-components)ごとに 1 つの を持つ単一のベースモデルです。レコメンデーションはアダプターに必要な追加メモリを考慮するため、SageMaker AI はベースモデルとアダプターに対して返された設定を一緒に検証します。

## 前提条件
<a name="generative-ai-inference-recommendations-adapters-prereqs"></a>

レコメンデーションジョブ[前提条件](generative-ai-inference-recommendations-get-started.md#generative-ai-inference-recommendations-get-started-prereqs)の に加えて、アダプターを含めるには以下が必要です。
+ 1～10 個の LoRA アダプター。各アダプターは、 で指定したベースモデルに対してトレーニングされます`ModelSource`。
+ PEFT 形式の各アダプター。アダプターの場所には、正のランク (`r`) の`adapter_config.json`ファイルとアダプターの重みファイル (`.safetensors` または ) が含まれている必要があります`.bin`。
+ Amazon S3 または登録済みの SageMaker AI モデルパッケージのいずれかの 1 つの形式で提供されるすべてのアダプター。2 つのフォームを 1 つのジョブに混在させることはできません。

SageMaker AI は、 で渡す IAM 実行ロールを使用してアダプターを読み取ります`RoleArn`。ロールは、各アダプターの Amazon S3 の場所を読み取ることができる必要があります (`s3:GetObject` および `s3:ListBucket`)。これらは、ベースモデルアーティファクトに使用するのと同じアクセス許可です。アダプターをモデルパッケージとして提供する場合、SageMaker AI がアダプターの Amazon S3 の場所を解決できるように、ロールは`sagemaker:DescribeModelPackage`各パッケージにも必要です。

## 要件と制限
<a name="generative-ai-inference-recommendations-adapters-restrictions"></a>

レコメンデーションジョブにアダプターを追加する場合、次の要件と制限が適用されます。
+ **ジョブごとに 1 つのソースフォーム。** `AdapterSource`はユニオンです。`S3Uris` または の 1 つだけを設定します`ModelPackageArns`。SageMaker AI は、両方のフィールドまたはどちらのフィールドも設定しないジョブを拒否します。
+ **アダプターランク。**アダプターのランクは、vLLM供給エンジンがサポートする最大の LoRA ランクである 512 を超えることはできません。詳細については、「」の注記を参照してください[レコメンデーションジョブにアダプターを追加する](#generative-ai-inference-recommendations-adapters-input)。

## レコメンデーションジョブにアダプターを追加する
<a name="generative-ai-inference-recommendations-adapters-input"></a>

アダプターを含めるには、オプションの `AdapterSource` オブジェクトを`CreateAIRecommendationJob`リクエストに追加します。 `AdapterSource`はユニオンです。次のフィールドの 1 つを正確に設定し、それぞれに 1～10 個のアダプターエントリのリストを設定します。

`S3Uris`  
`{"AdapterId": ..., "S3Uri": ...}` エントリのリスト。このフォームは、独自の PEFT パイプラインまたはオープンソースの PEFT パイプラインで作成したアダプターに使用します。各 `S3Uri`は、アダプターの および重みファイルを保持する Amazon S3 プレフィックスです。 `adapter_config.json`

`ModelPackageArns`  
`{"AdapterId": ..., "ModelPackageArn": ...}` エントリのリスト。このフォームは、SageMaker AI ファインチューニングワークフローによって生成されたアダプターなど、SageMaker AI モデルパッケージとして既に登録されているアダプターに使用します。SageMaker AI は、各モデルパッケージからアダプターアーティファクトの場所を読み取ります。

`AdapterId` は、各アダプターに割り当てる名前です。次の要件を満たしている必要があります。
+ リクエスト内で一意である必要があります。
+ 63 文字以下にする必要があります。
+ パターン と一致する必要があります`^[a-zA-Z0-9](-*[a-zA-Z0-9])*$`。先頭と末尾は英数字で、英数字間のハイフンのみが許可され、アンダースコアは使用されません。

SageMaker AI は、そのアダプターの推論コンポーネント名`AdapterId`として を使用します。この名前は、デプロイされたエンドポイントを呼び出すときにアダプターにリクエストを送信するために使用するルーティングハンドルでもあります。

**Python (boto3) — Amazon S3 のアダプター**

```
try:
    response = client.create_ai_recommendation_job(
        AIRecommendationJobName="my-lora-recommendation-job",
        ModelSource={
            "S3": {
                "S3Uri": "s3://amzn-s3-demo-bucket/models/my-base-model/",
            }
        },
        OutputConfig={
            "S3OutputLocation": "s3://amzn-s3-demo-bucket/recommendations/"
        },
        AdapterSource={
            "S3Uris": [
                {"AdapterId": "sql", "S3Uri": "s3://amzn-s3-demo-bucket/adapters/sql/"},
                {"AdapterId": "chat", "S3Uri": "s3://amzn-s3-demo-bucket/adapters/chat/"},
            ]
        },
        PerformanceTarget={
            "Constraints": [
                {"Metric": "throughput"}
            ]
        },
        AIWorkloadConfigIdentifier="my-recommendation-workload",
        RoleArn="arn:aws:iam::111122223333:role/ExampleRole",
    )
    print(response["AIRecommendationJobArn"])
except client.exceptions.ResourceInUse as error:
    print(f"A job with this name already exists: {error}")
except Exception as error:
    print(f"Error creating recommendation job: {error}")
    raise
```

**Python (boto3) — モデルパッケージとしてのアダプター**

```
try:
    response = client.create_ai_recommendation_job(
        AIRecommendationJobName="my-lora-recommendation-job",
        ModelSource={
            "S3": {
                "S3Uri": "s3://amzn-s3-demo-bucket/models/my-base-model/",
            }
        },
        OutputConfig={
            "S3OutputLocation": "s3://amzn-s3-demo-bucket/recommendations/"
        },
        AdapterSource={
            "ModelPackageArns": [
                {
                    "AdapterId": "sql",
                    "ModelPackageArn": "arn:aws:sagemaker:us-west-2:111122223333:model-package/my-sql-adapter/1",
                }
            ]
        },
        PerformanceTarget={
            "Constraints": [
                {"Metric": "throughput"}
            ]
        },
        AIWorkloadConfigIdentifier="my-recommendation-workload",
        RoleArn="arn:aws:iam::111122223333:role/ExampleRole",
    )
    print(response["AIRecommendationJobArn"])
except client.exceptions.ResourceInUse as error:
    print(f"A job with this name already exists: {error}")
except Exception as error:
    print(f"Error creating recommendation job: {error}")
    raise
```

**AWS CLI**

```
aws sagemaker create-ai-recommendation-job \
  --ai-recommendation-job-name "my-lora-recommendation-job" \
  --model-source '{"S3": {"S3Uri": "s3://amzn-s3-demo-bucket/models/my-base-model/"}}' \
  --output-config '{"S3OutputLocation": "s3://amzn-s3-demo-bucket/recommendations/"}' \
  --adapter-source '{
    "S3Uris": [
      {"AdapterId": "sql", "S3Uri": "s3://amzn-s3-demo-bucket/adapters/sql/"},
      {"AdapterId": "chat", "S3Uri": "s3://amzn-s3-demo-bucket/adapters/chat/"}
    ]
  }' \
  --performance-target '{"Constraints": [{"Metric": "throughput"}]}' \
  --ai-workload-config-identifier "my-recommendation-workload" \
  --role-arn "arn:aws:iam::111122223333:role/ExampleRole" \
  --region us-west-2
```

**注記**  
アダプターのランク (`r` の `adapter_config.json`) は、vLLM供給エンジンがサポートする最大の LoRA ランクである 512 を超えることはできません。SageMaker AI は、すべてのアダプターを 1 ランクで提供し、 がvLLMサポートする最も近いランクにランク付けします。1、8、16、32、64、128、256、320、または 512。たとえば、SageMaker AI はランク 4 と 12 のアダプターをランク 16 で提供します。アダプター全体の最大ランクが 512 を超えると、ジョブは検証エラーで失敗します。影響を受けるアダプターを小さいランクで再トレーニングするか、 から省略します`AdapterSource`。

## レコメンデーションの解釈
<a name="generative-ai-inference-recommendations-adapters-output"></a>

ジョブが完了したら、 を呼び出します`DescribeAIRecommendationJob`。で説明されているフィールドに加えて[ステップ 3: レコメンデーションを確認する](generative-ai-inference-recommendations-get-started.md#generative-ai-inference-recommendations-get-started-results)、レスポンスにはアダプター固有の情報が含まれます。

`AdapterSource`  
最上位のレスポンスは、指定した `AdapterSource` を同じ形式 (`S3Uris` または ) でエコーします`ModelPackageArns`。

`AdapterDetails`  
`Recommendations` 配列内の各レコメンデーションには、 `S3Uris`と *の両方*の形式ですべてのアダプターを一覧表示する `AdapterDetails` オブジェクトが格納されます。`ModelPackageArns`キーは です`AdapterId`。アダプターを Amazon S3 URIs としてのみ指定した場合、SageMaker AI はユーザーに代わって各アダプターのモデルパッケージを登録し、ここで ARN を返します。これにより、デプロイする登録済みのバージョニングされたアーティファクトが提供されます。

各レコメンデーション`DeploymentConfiguration`の では、マルチアダプタ、inference-component-basedトポロジ (ベースモデルとアダプターごとに 1 つの推論コンポーネント) について説明します。 は、その設定のベンチマークされたメトリクス`ExpectedPerformance`を報告します。

次の例は、Amazon S3 アダプターで作成されたジョブの`DescribeAIRecommendationJob`レスポンスのアダプター関連フィールドを示しています。

```
{
    "AIRecommendationJobName": "my-lora-recommendation-job",
    "AIRecommendationJobStatus": "Completed",
    "AdapterSource": {
        "S3Uris": [
            {"AdapterId": "sql", "S3Uri": "s3://amzn-s3-demo-bucket/adapters/sql/"},
            {"AdapterId": "chat", "S3Uri": "s3://amzn-s3-demo-bucket/adapters/chat/"}
        ]
    },
    "Recommendations": [
        {
            "AdapterDetails": {
                "S3Uris": [
                    {"AdapterId": "sql", "S3Uri": "s3://amzn-s3-demo-bucket/adapters/sql/"},
                    {"AdapterId": "chat", "S3Uri": "s3://amzn-s3-demo-bucket/adapters/chat/"}
                ],
                "ModelPackageArns": [
                    {"AdapterId": "sql", "ModelPackageArn": "arn:aws:sagemaker:us-west-2:111122223333:model-package/my-lora-recommendation-job-adapters/1"},
                    {"AdapterId": "chat", "ModelPackageArn": "arn:aws:sagemaker:us-west-2:111122223333:model-package/my-lora-recommendation-job-adapters/2"}
                ]
            },
            "DeploymentConfiguration": {
                "InstanceType": "ml.g6e.12xlarge",
                "InstanceCount": 1,
                "CopyCountPerInstance": 2,
                "MinCpuMemoryRequiredInMb": 12288,
                "EnvironmentVariables": {
                    "SAGEMAKER_SHM_SIZE_MB": "2048"
                }
            },
            "ExpectedPerformance": [
                {"Metric": "throughput", "Stat": "average", "Value": "512.0", "Unit": "tokens/second"}
            ]
        }
    ]
}
```

デプロイされたマルチアダプターエンドポイントをベンチマークしたり、アダプターを互いに比較したりするには、ベンチマークジョブの各アダプターの推論コンポーネントをターゲットにします。詳細については、「[マルチ LoRA エンドポイントのベンチマーク](generative-ai-inference-recommendations-benchmark.md#generative-ai-inference-recommendations-benchmark-multi-lora)」を参照してください。