ai_recommendation_jobs

Creates, updates, deletes, gets or lists an ai_recommendation_jobs resource.

Overview

Name	ai_recommendation_jobs
Type	Resource
Id	aws.sagemaker.ai_recommendation_jobs

Fields

The following fields are returned by SELECT queries:

describe_ai_recommendation_job

Name	Datatype	Description
ai_recommendation_job_arn	string	The Amazon Resource Name (ARN) of the AI recommendation job. (pattern: <code>arn:aws[a-z-]:sagemaker:[a-z0-9-]:[0-9]{12}:ai-recommendation-job/[a-zA-Z0-9](-*[a-zA-Z0-9]){0,62}</code>)
ai_recommendation_job_name	string	The name of the AI recommendation job. (pattern: <code>[a-zA-Z0-9](-*[a-zA-Z0-9]){0,62}</code>)
ai_recommendation_job_status	string	The status of the AI recommendation job. (InProgress, Completed, Failed, Stopping, Stopped)
ai_workload_config_identifier	string	The name or Amazon Resource Name (ARN) of the AI workload configuration used for this recommendation job. (pattern: <code>(arn:aws[a-z-]:sagemaker:[a-z0-9-]:[0-9]{12}:[a-z-]*/)?([a-zA-Z0-9]([a-zA-Z0-9-]){0,62})(?<!-)</code>)
adapter_source	object	The LoRA adapter source that you specified when you created the recommendation job. This field is absent when you created the job without LoRA adapters.
compute_spec	object	The compute resource specification for the recommendation job.
creation_time	string (date-time)	A timestamp that indicates when the recommendation job was created.
end_time	string (date-time)	A timestamp that indicates when the recommendation job completed.
failure_reason	string	If the recommendation job failed, the reason it failed.
inference_specification	object	The inference framework configuration.
model_source	object	The source of the model that was analyzed.
optimize_model	boolean	Whether model optimization techniques were allowed.
output_config	object	The output configuration for the recommendation job.
performance_target	object	The performance targets specified for the recommendation job.
recommendations	array	The list of optimization recommendations generated by the job. Each recommendation includes optimization details, deployment configuration, expected performance metrics, and the associated benchmark job ARN.
role_arn	string	The Amazon Resource Name (ARN) of the IAM role used by the recommendation job. (pattern: <code>arn:aws[a-z-]*:iam::\d{12}:role/?[a-zA-Z_0-9+=,.@-_/]+</code>)
start_time	string (date-time)	A timestamp that indicates when the recommendation job started running.
tags	array	The tags associated with the recommendation job.

list_ai_recommendation_jobs

Name	Datatype	Description
ai_recommendation_job_arn	string	The Amazon Resource Name (ARN) of the recommendation job. (pattern: <code>arn:aws[a-z-]:sagemaker:[a-z0-9-]:[0-9]{12}:ai-recommendation-job/[a-zA-Z0-9](-*[a-zA-Z0-9]){0,62}</code>)
ai_recommendation_job_name	string	The name of the recommendation job. (pattern: <code>[a-zA-Z0-9](-*[a-zA-Z0-9]){0,62}</code>)
ai_recommendation_job_status	string	The status of the recommendation job. (InProgress, Completed, Failed, Stopping, Stopped)
creation_time	string (date-time)	A timestamp that indicates when the recommendation job was created.
end_time	string (date-time)	A timestamp that indicates when the recommendation job completed.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_ai_recommendation_job	select	region		Returns details of an AI recommendation job, including its status, model source, performance targets, optimization recommendations, and deployment configurations.
list_ai_recommendation_jobs	select	region		Returns a list of AI recommendation jobs in your account. You can filter the results by name, status, and creation time, and sort the results. The response is paginated.
create_ai_recommendation_job	insert	region, AIRecommendationJobName, ModelSource, OutputConfig, AIWorkloadConfigIdentifier, PerformanceTarget, RoleArn		Creates a recommendation job that generates intelligent optimization recommendations for generative AI inference deployments. The job analyzes your model, workload configuration, and performance targets to recommend optimal instance types, model optimization techniques (such as quantization and speculative decoding), and deployment configurations.
delete_ai_recommendation_job	delete	region		Deletes the specified AI recommendation job.
stop_ai_recommendation_job	exec	region, AIRecommendationJobName		Stops a running AI recommendation job.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

describe_ai_recommendation_job

Returns details of an AI recommendation job, including its status, model source, performance targets, optimization recommendations, and deployment configurations.

SELECT
ai_recommendation_job_arn,
ai_recommendation_job_name,
ai_recommendation_job_status,
ai_workload_config_identifier,
adapter_source,
compute_spec,
creation_time,
end_time,
failure_reason,
inference_specification,
model_source,
optimize_model,
output_config,
performance_target,
recommendations,
role_arn,
start_time,
tags
FROM aws.sagemaker.ai_recommendation_jobs
WHERE region = '{{ region }}' -- required
;

list_ai_recommendation_jobs

Returns a list of AI recommendation jobs in your account. You can filter the results by name, status, and creation time, and sort the results. The response is paginated.

SELECT
ai_recommendation_job_arn,
ai_recommendation_job_name,
ai_recommendation_job_status,
creation_time,
end_time
FROM aws.sagemaker.ai_recommendation_jobs
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_ai_recommendation_job

Creates a recommendation job that generates intelligent optimization recommendations for generative AI inference deployments. The job analyzes your model, workload configuration, and performance targets to recommend optimal instance types, model optimization techniques (such as quantization and speculative decoding), and deployment configurations.

INSERT INTO aws.sagemaker.ai_recommendation_jobs (
AIRecommendationJobName,
ModelSource,
OutputConfig,
AIWorkloadConfigIdentifier,
PerformanceTarget,
RoleArn,
InferenceSpecification,
OptimizeModel,
ComputeSpec,
AdapterSource,
Tags,
region
)
SELECT 
'{{ AIRecommendationJobName }}' /* required */,
'{{ ModelSource }}' /* required */,
'{{ OutputConfig }}' /* required */,
'{{ AIWorkloadConfigIdentifier }}' /* required */,
'{{ PerformanceTarget }}' /* required */,
'{{ RoleArn }}' /* required */,
'{{ InferenceSpecification }}',
{{ OptimizeModel }},
'{{ ComputeSpec }}',
'{{ AdapterSource }}',
'{{ Tags }}',
'{{ region }}'
RETURNING
ai_recommendation_job_arn
;

Manifest

# Description fields are for documentation purposes
- name: ai_recommendation_jobs
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the ai_recommendation_jobs resource.
  - name: AIRecommendationJobName
    value: "{{ AIRecommendationJobName }}"
    description: |
      The name of the AI recommendation job. The name must be unique within your Amazon Web Services account in the current Amazon Web Services Region.
  - name: ModelSource
    description: |
      The source of the model to optimize. Specify the Amazon S3 location of the model artifacts.
    value:
      S3:
        S3Uri: "{{ S3Uri }}"
  - name: OutputConfig
    description: |
      The output configuration for the recommendation job, including the Amazon S3 location for results and an optional model package group where the optimized model is registered.
    value:
      S3OutputLocation: "{{ S3OutputLocation }}"
      ModelPackageGroupIdentifier: "{{ ModelPackageGroupIdentifier }}"
      MlflowConfig:
        MlflowResourceArn: "{{ MlflowResourceArn }}"
        MlflowExperimentName: "{{ MlflowExperimentName }}"
        MlflowRunName: "{{ MlflowRunName }}"
  - name: AIWorkloadConfigIdentifier
    value: "{{ AIWorkloadConfigIdentifier }}"
    description: |
      The name or Amazon Resource Name (ARN) of the AI workload configuration to use for this recommendation job.
  - name: PerformanceTarget
    description: |
      The performance targets for the recommendation job. Specify constraints on metrics such as time to first token (ttft-ms), throughput, or cost.
    value:
      Constraints:
        - Metric: "{{ Metric }}"
  - name: RoleArn
    value: "{{ RoleArn }}"
    description: |
      The Amazon Resource Name (ARN) of an IAM role that enables Amazon SageMaker AI to perform tasks on your behalf.
  - name: InferenceSpecification
    description: |
      The inference framework configuration. Specify the framework (such as LMI or vLLM) for the recommendation job.
    value:
      Framework: "{{ Framework }}"
  - name: OptimizeModel
    value: {{ OptimizeModel }}
    description: |
      Whether to allow model optimization techniques such as quantization, speculative decoding, and kernel tuning. The default is true.
  - name: ComputeSpec
    description: |
      The compute resource specification for the recommendation job. You can specify up to 3 instance types to consider, and optionally provide capacity reservation configuration.
    value:
      InstanceTypes:
        - "{{ InstanceTypes }}"
      CapacityReservationConfig:
        CapacityReservationPreference: "{{ CapacityReservationPreference }}"
        MlReservationArns:
          - "{{ MlReservationArns }}"
  - name: AdapterSource
    description: |
      The LoRA adapter source for the recommendation job. Specify either a list of model package ARNs or Amazon S3 URIs for your LoRA adapters. When this parameter is absent, the recommendation job runs without LoRA adapter support.
    value:
      ModelPackageArns:
        - AdapterId: "{{ AdapterId }}"
          ModelPackageArn: "{{ ModelPackageArn }}"
      S3Uris:
        - AdapterId: "{{ AdapterId }}"
          S3Uri: "{{ S3Uri }}"
  - name: Tags
    description: |
      The metadata that you apply to Amazon Web Services resources to help you categorize and organize them.
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"

DELETE examples

delete_ai_recommendation_job

Deletes the specified AI recommendation job.

DELETE FROM aws.sagemaker.ai_recommendation_jobs
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

stop_ai_recommendation_job

Stops a running AI recommendation job.

EXEC aws.sagemaker.ai_recommendation_jobs.stop_ai_recommendation_job 
@region='{{ region }}' --required 
@@json=
'{
"AIRecommendationJobName": "{{ AIRecommendationJobName }}"
}'
;