Azure Machine Learning Component SDK

Common errors

• ModuleNotFoundError: No module named 'azure.ml.component.core'

  cause Attempting to directly import internal modules of `azure-ml-component` which are not exposed or intended for direct user consumption.
  fix Instead, use the `azure.ai.ml` SDK, which is the high-level API for defining components. For example, use `from azure.ai.ml import command` or `from azure.ai.ml.entities import CommandComponent`.

• azure.ai.ml.exceptions.ValidationException: Invalid schema for component

  cause This error typically occurs when the component definition (e.g., inputs, outputs, command, environment) does not conform to the expected schema of `azure.ai.ml`.
  fix Carefully review the component's YAML definition or the arguments passed to the `command` decorator/ `CommandComponent` constructor. Ensure all required fields are present and their types/formats match the official `azure.ai.ml` component schema documentation.

Warnings

• gotcha The `azure-ml-component` library is a low-level dependency of the `azure-ai-ml` SDK and is generally not intended for direct end-user interaction for defining or managing components. For these tasks, the `azure.ai.ml` package (the main Azure Machine Learning Python SDK) is the recommended and stable entry point.
  Fix: Always use `azure.ai.ml` for creating, registering, and managing components. Refer to official Azure ML documentation for examples using `from azure.ai.ml import command` or `from azure.ai.ml.entities import CommandComponent`.
• breaking Versions of `azure-ml-component` are tightly coupled with `azure-ai-ml` versions. Direct upgrades of `azure-ml-component` without upgrading `azure-ai-ml` can lead to version conflicts, unexpected behavior, or API incompatibilities.
  Fix: Manage `azure-ai-ml` as your primary dependency. Let `pip` resolve `azure-ml-component` as a sub-dependency when installing or upgrading `azure-ai-ml`. Avoid manually pinning `azure-ml-component` unless explicitly instructed for specific advanced scenarios.

Install

• pip install azure-ml-component Install `azure-ml-component`
• pip install azure-ai-ml Recommended: Install `azure-ai-ml` (includes `azure-ml-component`)

Imports

• CommandComponent

  from azure.ai.ml.entities import CommandComponent

  While `azure-ml-component` contains base classes, `azure.ai.ml.entities.CommandComponent` is the high-level, recommended way to define components using the `azure-ai-ml` SDK.
• command

  from azure.ai.ml import command

  The `@command` decorator from `azure.ai.ml` is the most common and ergonomic way to define a command component.

Quickstart

This quickstart demonstrates defining a basic command component using the `azure.ai.ml` SDK, which is the recommended way to interact with Azure Machine Learning components. Although `azure-ml-component` provides underlying classes, direct usage is uncommon. This example defines a component that takes a string input and writes a processed string to an output file. To actually register and run this component, an `MLClient` connected to an Azure ML Workspace would be required (commented out for quickstart runnability).

import os
from azure.ai.ml import command, Input, Output
from azure.ai.ml.entities import CommandComponent

# Define a simple command component using the recommended azure.ai.ml SDK
# This component takes an input string and produces an output string.

# For this example, we'll define a simple Python script as the command source
component_script_content = """
import argparse

parser = argparse.ArgumentParser()
parser.add_argument("--input_data", type=str)
parser.add_argument("--output_data", type=str)
args = parser.parse_args()

print(f"Received input: {args.input_data}")

with open(args.output_data, "w") as f:
    f.write(f"Processed: {args.input_data.upper()}")
print(f"Wrote output to {args.output_data}")
"""

# Create a temporary directory and save the script
import tempfile
import shutil

with tempfile.TemporaryDirectory() as temp_dir:
    script_path = os.path.join(temp_dir, "process.py")
    with open(script_path, "w") as f:
        f.write(component_script_content)

    # Define the command component
    hello_world_component = command(
        name="hello_world_component",
        display_name="Hello World Component Example",
        description="A simple component that processes input text.",
        inputs={
            "input_data": Input(type="string", description="Input string for processing")
        },
        outputs={
            "output_data": Output(type="uri_file", description="Processed output string")
        },
        command=f"python {{inputs.script_path}}/process.py --input_data {{inputs.input_data}} --output_data {{outputs.output_data}}",
        environment=dict(
            conda_file=os.path.join(temp_dir, "conda_env.yml"),
            image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest"
        ),
        code=temp_dir
    )

    print("\n--- Component Definition ---")
    print(hello_world_component.as_dict())

    # To actually run this, you would need an MLClient connected to an Azure ML workspace.
    # from azure.ai.ml import MLClient
    # from azure.identity import DefaultAzureCredential
    # ml_client = MLClient(
    #     DefaultAzureCredential(), 
    #     subscription_id=os.environ.get("AZURE_SUBSCRIPTION_ID", ""),
    #     resource_group_name=os.environ.get("AZURE_RESOURCE_GROUP", ""),
    #     workspace_name=os.environ.get("AZURE_WORKSPACE_NAME", "")
    # )
    # registered_component = ml_client.components.create_or_update(hello_world_component)
    # print(f"Component registered with name: {registered_component.name}, version: {registered_component.version}")