Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Lift-and-shift Código Python con el decorador @step El decorador `@step` es una característica que convierte el código de machine learning (ML) local en uno o más pasos de canalización. Puede escribir su función de ML como para cualquier proyecto de ML. Una vez probada localmente o como un trabajo de formación con el `@remote` decorador, puedes convertir la función en un paso de proceso de SageMaker IA añadiendo un `@step` decorador. A continuación, puede pasar la salida de la llamada a la función decorada con `@step` como un paso a Canalizaciones para crear y ejecutar una canalización. También puede encadenar una serie de funciones con el decorador `@step` para crear también una canalización de gráficos acíclicos dirigidos (DAG) de varios pasos. La configuración para usar el decorador `@step` es la misma que la configuración para usar el decorador `@remote`. Puede consultar la documentación de las funciones remotas para obtener información sobre cómo [configurar el entorno](https://docs.aws.amazon.com/sagemaker/latest/dg/train-remote-decorator.html#train-remote-decorator-env) y [utilizar un archivo de configuración](https://docs.aws.amazon.com/sagemaker/latest/dg/train-remote-decorator-config.html) para establecer los valores predeterminados. Para obtener más información sobre el decorador `@step`, consulte [sagemaker.workflow.function\$1step.step](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.function_step.step). Para ver ejemplos de cuadernos que demuestran el uso del decorador `@step`, consulte [@step decorator sample notebooks](https://github.com/aws/amazon-sagemaker-examples/tree/main/sagemaker-pipelines/step-decorator). En las siguientes secciones, se explica cómo anotar el código de ML local con un decorador `@step`para crear un paso, crear y ejecutar una canalización utilizando el paso y personalizar la experiencia para su caso de uso. **Topics** + [ # Creación de una canalización con funciones decoradas con `@step` ](pipelines-step-decorator-create-pipeline.md) + [ # Ejecución de una canalización ](pipelines-step-decorator-run-pipeline.md) + [ # Configuración de la canalización ](pipelines-step-decorator-cfg-pipeline.md) + [ # Prácticas recomendadas ](pipelines-step-decorator-best.md) + [ # Limitaciones ](pipelines-step-decorator-limit.md) # Creación de una canalización con funciones decoradas con `@step` Puede crear una canalización convirtiendo las funciones de Python en pasos de canalización mediante el decorador `@step`, creando dependencias entre esas funciones para crear un gráfico de canalización (o gráfico acíclico dirigido [DAG]) y pasando los nodos de hoja de ese gráfico como una lista de pasos a la canalización. En las siguientes secciones, se explica este procedimiento en detalle con ejemplos. **Topics** + [ ## Conversión de una función en un paso ](#pipelines-step-decorator-run-pipeline-convert) + [ ## Creación de dependencias entre los pasos ](#pipelines-step-decorator-run-pipeline-link) + [ ## Uso de `ConditionStep` con pasos decorados con `@step` ](#pipelines-step-decorator-condition) + [ ## Definición de una canalización utilizando la salida `DelayedReturn` de los pasos ](#pipelines-step-define-delayed) + [ ## Creación de una canalización ](#pipelines-step-decorator-pipeline-create) ## Conversión de una función en un paso Para crear un paso con el decorador `@step`, anote la función con `@step`. En el siguiente ejemplo, se muestra una función decorada con `@step` que preprocesa los datos. ``` from sagemaker.workflow.function_step import step @step def preprocess(raw_data): df = pandas.read_csv(raw_data) ... return procesed_dataframe step_process_result = preprocess(raw_data) ``` Cuando invocas una función `@step` decorada con símbolos, la SageMaker IA devuelve una `DelayedReturn` instancia en lugar de ejecutar la función. Una instancia de `DelayedReturn` es un proxy de la devolución real de esa función. La instancia de `DelayedReturn` se puede pasar a otra función como argumento o directamente a una instancia de canalización como paso. [Para obtener información sobre la `DelayedReturn` clase, consulta sagemaker.workflow.function\$1step. DelayedReturn](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.function_step.DelayedReturn). ## Creación de dependencias entre los pasos Al crear una dependencia entre dos pasos, se crea una conexión entre los pasos del gráfico de canalización. En las siguientes secciones, se presentan varias formas de crear una dependencia entre los pasos de la canalización. ### Dependencias de datos a través de argumentos de entrada Al pasar la salida `DelayedReturn` de una función como entrada a otra función, se crea automáticamente una dependencia de datos en el DAG de la canalización. En el siguiente ejemplo, al pasar la salida `DelayedReturn` de la función `preprocess` a la función `train`, se crea una dependencia entre `preprocess` y `train`. ``` from sagemaker.workflow.function_step import step @step def preprocess(raw_data): df = pandas.read_csv(raw_data) ... return procesed_dataframe @step def train(training_data): ... return trained_model step_process_result = preprocess(raw_data) step_train_result = train(step_process_result) ``` El ejemplo anterior define una función de entrenamiento que está decorada con `@step`. Cuando se invoca esta función, recibe como entrada la salida `DelayedReturn` del paso de la canalización de preprocesamiento. Al invocar la función de entrenamiento, se devuelve otra instancia de `DelayedReturn`. Esta instancia contiene la información sobre todos los pasos anteriores definidos en esa función (es decir, el paso `preprocess` de este ejemplo) que forman el DAG de la canalización. En el ejemplo anterior, la función `preprocess` devuelve un valor único. Para ver tipos de devoluciones más complejas, como listas o tuplas, consulte [Limitaciones](pipelines-step-decorator-limit.md). ### Definición de dependencias personalizadas En el ejemplo anterior, la función `train` recibió la salida `DelayedReturn` de `preprocess` y creó una dependencia. Si desea definir la dependencia de forma explícita sin pasar la salida del paso anterior, utilice la función `add_depends_on` con el paso. Puede usar la función `get_step()` para recuperar el paso subyacente de su instancia de `DelayedReturn` y, a continuación, llamar a `add_depends_on`\$1on con la dependencia como entrada. Para ver la definición de la función `get_step()`, consulte [sagemaker.workflow.step\$1outputs.get\$1step](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.step_outputs.get_step). El siguiente ejemplo muestra cómo crear una dependencia entre `preprocess` y `train` usando `get_step()` y `add_depends_on()`. ``` from sagemaker.workflow.step_outputs import get_step @step def preprocess(raw_data): df = pandas.read_csv(raw_data) ... processed_data = .. return s3.upload(processed_data) @step def train(): training_data = s3.download(....) ... return trained_model step_process_result = preprocess(raw_data) step_train_result = train() get_step(step_train_result).add_depends_on([step_process_result]) ``` ### Transferencia de datos desde y hacia una función decorada con `@step` para un paso de canalización tradicional Puede crear una canalización que incluya un paso decorado con `@step` y un paso de canalización tradicional y pasar datos entre ellos. Por ejemplo, puede utilizar `ProcessingStep` para procesar los datos y pasar su resultado a la función de entrenamiento decorada con `@step`. En el siguiente ejemplo, un paso de entrenamiento decorado con `@step` hace referencia al resultado de un paso de procesamiento. ``` # Define processing step from sagemaker.sklearn.processing import SKLearnProcessor from sagemaker.processing import ProcessingInput, ProcessingOutput from sagemaker.workflow.steps import ProcessingStep sklearn_processor = SKLearnProcessor( framework_version='1.2-1', role='arn:aws:iam::123456789012:role/SagemakerExecutionRole', instance_type='ml.m5.large', instance_count='1', ) inputs = [ ProcessingInput(source=input_data, destination="/opt/ml/processing/input"), ] outputs = [ ProcessingOutput(output_name="train", source="/opt/ml/processing/train"), ProcessingOutput(output_name="validation", source="/opt/ml/processing/validation"), ProcessingOutput(output_name="test", source="/opt/ml/processing/test") ] process_step = ProcessingStep( name="MyProcessStep", step_args=sklearn_processor.run(inputs=inputs, outputs=outputs,code='preprocessing.py'), ) ``` ``` # Define a @step-decorated train step which references the # output of a processing step @step def train(train_data_path, test_data_path): ... return trained_model step_train_result = train( process_step.properties.ProcessingOutputConfig.Outputs["train"].S3Output.S3Uri, process_step.properties.ProcessingOutputConfig.Outputs["test"].S3Output.S3Uri, ) ``` ## Uso de `ConditionStep` con pasos decorados con `@step` Canalizaciones admite una clase `ConditionStep` que evalúa los resultados de los pasos anteriores para decidir qué medidas tomar en la canalización. También puede utilizar `ConditionStep` con un paso decorado con `@step`. Para usar la salida de cualquier paso decorado con `@step` con `ConditionStep`, introduzca la salida de ese paso como argumento para `ConditionStep`. En el siguiente ejemplo, el paso de condición recibe el resultado del paso de evaluación del modelo decorado con `@step`. ``` # Define steps @step(name="evaluate") def evaluate_model(): # code to evaluate the model return { "rmse":rmse_value } @step(name="register") def register_model(): # code to register the model ... ``` ``` # Define ConditionStep from sagemaker.workflow.condition_step import ConditionStep from sagemaker.workflow.conditions import ConditionGreaterThanOrEqualTo from sagemaker.workflow.fail_step import FailStep conditionally_register = ConditionStep( name="conditional_register", conditions=[ ConditionGreaterThanOrEqualTo( # Output of the evaluate step must be json serializable left=evaluate_model()["rmse"], # right=5, ) ], if_steps=[FailStep(name="Fail", error_message="Model performance is not good enough")], else_steps=[register_model()], ) ``` ## Definición de una canalización utilizando la salida `DelayedReturn` de los pasos La canalización se define de la misma manera independientemente de si se utiliza o no un decorador `@step`. Cuando pasa una instancia de `DelayedReturn` a su canalización, no es necesario pasar una lista completa de pasos para crear la canalización. El SDK deduce automáticamente los pasos anteriores en función de las dependencias que defina. Todos los pasos anteriores de los objetos `Step` que ha pasado a la canalización o a los objetos `DelayedReturn` se incluyen en el gráfico de la canalización. En el siguiente ejemplo, la canalización recibe el objeto `DelayedReturn` de la función `train`. SageMaker La IA añade el `preprocess` paso, como paso anterior`train`, al gráfico de canalización. ``` from sagemaker.workflow.pipeline import Pipeline pipeline = Pipeline( name="", steps=[step_train_result], sagemaker_session=, ) ``` Si no hay datos o dependencias personalizadas entre los pasos y ejecuta varios pasos en paralelo, el gráfico de canalización tiene más de un nodo hoja. Pase todos estos nodos de hoja en una lista al argumento `steps` de la definición de la canalización, tal y como se muestra en el siguiente ejemplo: ``` @step def process1(): ... return data @step def process2(): ... return data step_process1_result = process1() step_process2_result = process2() pipeline = Pipeline( name="", steps=[step_process1_result, step_process2_result], sagemaker_session=sagemaker-session, ) ``` Cuando se ejecuta la canalización, ambos pasos se ejecutan en paralelo. Solo se pasan los nodos de hoja del gráfico a la canalización, ya que los nodos de hoja contienen información sobre todos los pasos anteriores definidos mediante dependencias de datos o personalizadas. Al compilar la canalización, la SageMaker IA también deduce todos los pasos subsiguientes que forman el gráfico de la canalización y añade cada uno de ellos como un paso independiente a la canalización. ## Creación de una canalización Cree una canalización mediante una llamada a `pipeline.create()`, tal y como se muestra en el siguiente fragmento. Para obtener más información sobre `create()`, consulte [sagemaker.workflow.pipeline.Pipeline.create](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.pipeline.Pipeline.create). ``` role = "pipeline-role" pipeline.create(role) ``` Cuando llamas`pipeline.create()`, la SageMaker IA compila todos los pasos definidos como parte de la instancia de canalización. SageMaker La IA carga la función serializada, los argumentos y todos los demás artefactos relacionados con los pasos en Amazon S3. Los datos residen en el bucket de S3 de acuerdo con la siguiente estructura: ``` s3_root_uri/ pipeline_name/ sm_rf_user_ws/ workspace.zip # archive of the current working directory (workdir) step_name/ timestamp/ arguments/ # serialized function arguments function/ # serialized function pre_train_dependencies/ # any dependencies and pre_execution scripts provided for the step execution_id/ step_name/ results # returned output from the serialized function including the model ``` `s3_root_uri`se define en el archivo de configuración de SageMaker AI y se aplica a toda la canalización. Si no está definido, se utiliza el depósito de SageMaker IA predeterminado. **nota** Cada vez que la SageMaker IA compila una canalización, SageMaker guarda las funciones, los argumentos y las dependencias serializados de los pasos en una carpeta con la fecha y hora actuales. Esto ocurre cada vez que ejecuta `pipeline.create()`, `pipeline.update()`, `pipeline.upsert()` o `pipeline.definition()`. # Ejecución de una canalización En la siguiente página se describe cómo ejecutar una canalización con Amazon SageMaker Pipelines, ya sea con recursos de SageMaker IA o de forma local. Inicie una nueva ejecución de canalización con la `pipeline.start()` función como lo haría con una canalización de SageMaker IA tradicional. Para obtener más información sobre la función `start()`, consulte [sagemaker.workflow.pipeline.Pipeline.start](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.pipeline.Pipeline.start). **nota** Un paso definido con el decorador `@step` funciona como un trabajo de entrenamiento. Por tanto, debe tener en cuenta los siguientes límites: Límites de instancias y límites de trabajos de entrenamiento en sus cuentas. Actualice sus límites en consecuencia para evitar problemas de limitación o límites de recursos. El costo económico asociado a cada ejecución de un paso de entrenamiento de la canalización. Para obtener más información, consulta los [ SageMaker precios de Amazon](https://aws.amazon.com/sagemaker/pricing/). ## Recuperación de los resultados de una canalización ejecutada localmente Para ver el resultado de cualquier paso de la ejecución de una canalización, use [execution.result()](https://sagemaker.readthedocs.io/en/stable/workflows/pipelines/sagemaker.workflow.pipelines.html#sagemaker.workflow.pipeline._PipelineExecution.result ), como se muestra en el siguiente fragmento: ``` execution = pipeline.start() execution.result(step_name="train") ``` **nota** Canalizaciones no es compatible con `execution.result()` en el modo local. Solo puede recuperar los resultados de un paso cada vez. Si el nombre del paso lo generó la SageMaker IA, puedes recuperarlo llamando de la `list_steps` siguiente manera: ``` execution.list_step() ``` ## Ejecución de una canalización de forma local Puede ejecutar una canalización con pasos decorados con `@step` localmente, como lo haría con los pasos de una canalización tradicional. Para obtener más información sobre la ejecución de canalizaciones en modo local, consulte [Ejecución de canalizaciones en modo local](pipelines-local-mode.md). Para usar el modo local, proporciona una `LocalPipelineSession` en lugar de una `SageMakerSession` a su definición de canalización, tal y como se muestra en el siguiente ejemplo: ``` from sagemaker.workflow.function_step import step from sagemaker.workflow.pipeline import Pipeline from sagemaker.workflow.pipeline_context import LocalPipelineSession @step def train(): training_data = s3.download(....) ... return trained_model step_train_result = train() local_pipeline_session = LocalPipelineSession() local_pipeline = Pipeline( name="", steps=[step_train_result], sagemaker_session=local_pipeline_session # needed for local mode ) local_pipeline.create(role_arn="role_arn") # pipeline runs locally execution = local_pipeline.start() ``` # Configuración de la canalización Se recomienda utilizar el archivo de configuración de SageMaker AI para establecer los valores predeterminados de la canalización. Para obtener información sobre el archivo de configuración de SageMaker AI, consulte [Configuración y uso de valores predeterminados con el SDK de SageMaker Python](https://sagemaker.readthedocs.io/en/stable/overview.html#configuring-and-using-defaults-with-the-sagemaker-python-sdk). Cualquier configuración que se añada al archivo de configuración se aplica a todos los pasos de la canalización. Si quiere anular las opciones de alguno de los pasos, proporcione nuevos valores en los argumentos del decorador `@step`. En el siguiente tema, se describe cómo configurar un archivo de configuración. La configuración del decorador `@step` en el archivo de configuración es idéntica a la configuración del decorador `@remote`. Para configurar el ARN del rol de canalización y las etiquetas de canalización en el archivo de configuración, use la sección `Pipeline` que se muestra en el siguiente fragmento: ``` SchemaVersion: '1.0' SageMaker: Pipeline: RoleArn: 'arn:aws:iam::555555555555:role/IMRole' Tags: - Key: 'tag_key' Value: 'tag_value' ``` La mayoría de los valores predeterminados que se pueden establecer en el archivo de configuración también se pueden anular pasando nuevos valores al decorador `@step`. Por ejemplo, puede anular el tipo de instancia establecido en el archivo de configuración para el paso de preprocesamiento, tal y como se muestra en el ejemplo siguiente: ``` @step(instance_type="ml.m5.large") def preprocess(raw_data): df = pandas.read_csv(raw_data) ... return procesed_dataframe ``` Algunos argumentos no forman parte de la lista de parámetros del `@step` decorador; solo se pueden configurar para toda la canalización a través del archivo de configuración de SageMaker AI. Son los siguientes: + `sagemaker_session`(`sagemaker.session.Session`): La sesión de SageMaker IA subyacente en la que la SageMaker IA delega las llamadas de servicio. Si no se especifica, se crea una sesión con la siguiente configuración predeterminada: ``` SageMaker: PythonSDK: Modules: Session: DefaultS3Bucket: 'default_s3_bucket' DefaultS3ObjectKeyPrefix: 'key_prefix' ``` + `custom_file_filter` (`CustomFileFilter)`: un objeto `CustomFileFilter` que especifica los directorios y archivos locales que se van a incluir en el paso de canalización. Si no se especifica, este valor se establece de forma predeterminada en `None`. Para que `custom_file_filter` se aplique, debe establecer `IncludeLocalWorkdir` en `True`. El siguiente ejemplo muestra una configuración que ignora todos los archivos del cuaderno, así como los archivos y directorios denominados `data`. ``` SchemaVersion: '1.0' SageMaker: PythonSDK: Modules: RemoteFunction: IncludeLocalWorkDir: true CustomFileFilter: IgnoreNamePatterns: # files or directories to ignore - "*.ipynb" # all notebook files - "data" # folder or file named "data" ``` Para obtener más información sobre cómo utilizar `IncludeLocalWorkdir` con `CustomFileFilter`, consulte [Uso de código modular con el decorador @remote](train-remote-decorator-modular.md). + `s3_root_uri (str)`: la carpeta raíz de Amazon S3 en la que SageMaker AI carga los archivos de código y los datos. Si no se especifica, se utiliza el depósito de SageMaker IA predeterminado. + `s3_kms_key (str)`: clave utilizada para cifrar los datos de entrada y salida. Solo puedes configurar este argumento en el archivo de configuración de SageMaker AI y el argumento se aplica a todos los pasos definidos en la canalización. Si no se especifica, el valor se establece de forma predeterminada en `None`. Consulte el siguiente fragmento para ver un ejemplo de la configuración de claves KMS de S3: ``` SchemaVersion: '1.0' SageMaker: PythonSDK: Modules: RemoteFunction: S3KmsKeyId: 's3kmskeyid' S3RootUri: 's3://amzn-s3-demo-bucket/my-project ``` # Prácticas recomendadas En las secciones siguientes, se incluyen prácticas recomendadas para usar el decorador `@step` en los pasos de la canalización. ## Uso de grupos de calentamiento Para agilizar las ejecuciones de las canalizaciones, utilice la funcionalidad de grupos de calentamiento que se proporciona para los trabajos de entrenamiento. Para activar la funcionalidad de grupos de calentamiento, proporcione el argumento `keep_alive_period_in_seconds` al decorador `@step`, tal y como se muestra en el siguiente fragmento: ``` @step( keep_alive_period_in_seconds=900 ) ``` Para obtener más información acerca de los grupos de calentamiento, consulte [SageMaker Piscinas calientes gestionadas por IA](train-warm-pools.md). ## Estructuración del directorio Se recomienda utilizar módulos de código mientras se utiliza el decorador `@step`. Coloque el módulo `pipeline.py`, en el que invoca las funciones de pasos y se define la canalización, en la raíz del espacio de trabajo. La estructura recomendada se muestra de la siguiente manera: ``` . ├── config.yaml # the configuration file that define the infra settings ├── requirements.txt # dependencies ├── pipeline.py # invoke @step-decorated functions and define the pipeline here ├── steps/ | ├── processing.py | ├── train.py ├── data/ ├── test/ ``` # Limitaciones En las secciones siguientes, se describen las limitaciones que hay que tener en cuenta al utilizar el decorador `@step` en los pasos de canalización. ## Limitaciones de los argumentos de funciones Al pasar un argumento de entrada a la función decorada con `@step`, se aplican las siguientes limitaciones: + Puede pasar los objetos `DelayedReturn`, `Properties` (de pasos de otros tipos) `Parameter` y `ExecutionVariable` a funciones decoradas con `@step` como argumentos. Sin embargo, las funciones decoradas con `@step` no admiten objetos `JsonGet` y `Join` como argumentos. + No se puede acceder directamente a una variable de canalización desde una función `@step`. El siguiente ejemplo produce un error: ``` param = ParameterInteger(name="", default_value=10) @step def func(): print(param) func() # this raises a SerializationError ``` + No puede anidar una variable de canalización en otro objeto y pasarlo a una función `@step`. El siguiente ejemplo produce un error: ``` param = ParameterInteger(name="", default_value=10) @step def func(arg): print(arg) func(arg=(param,)) # this raises a SerializationError because param is nested in a tuple ``` + Como las entradas y salidas de una función están serializadas, existen restricciones en cuanto al tipo de datos que se puede transferir como entrada o salida desde una función. Consulte la sección *Serialización y deserialización de datos* de [Invocación de una función remota](train-remote-decorator-invocation.md) para obtener más información. Las mismas restricciones se aplican a las funciones decoradas con `@step`. + Ningún objeto que tenga un cliente boto se puede serializar, por lo que no se pueden pasar dichos objetos como entrada o salida desde una función decorada con `@step`. Por ejemplo, las clases de cliente del SDK de SageMaker Python`Estimator`, como`Predictor`, y, no se `Processor` pueden serializar. ## Importaciones de funciones Debe importar las bibliotecas necesarias para el paso dentro más que fuera de la función. Si las importa a escala global, corre el riesgo de que se produzca un error de importación al serializar la función. Por ejemplo, `sklearn.pipeline.Pipeline` podría ser anulada por `sagemaker.workflow.pipeline.Pipeline`. ## Referencia a miembros secundarios del valor de devolución de la función Si hace referencia a los miembros secundarios del valor de devolución de una función decorada con `@step`, se aplican las siguientes limitaciones: + Puede hacer referencia a los miembros secundarios con `[]` si el objeto `DelayedReturn` representa una tupla, una lista o un dictado, como se muestra en el siguiente ejemplo: ``` delayed_return[0] delayed_return["a_key"] delayed_return[1]["a_key"] ``` + No se puede desempaquetar el resultado de una tupla o lista, porque no se puede conocer la longitud exacta de la tupla o lista subyacente al invocar la función. El siguiente ejemplo produce un error: ``` a, b, c = func() # this raises ValueError ``` + No se puede iterar sobre un objeto `DelayedReturn`. El siguiente ejemplo da un error: ``` for item in func(): # this raises a NotImplementedError ``` + No se puede hacer referencia a miembros secundarios arbitrarios con `.`. El siguiente ejemplo produce un error: ``` delayed_return.a_child # raises AttributeError ``` ## Características de canalización existentes que no se admiten No puede usar el decorador `@step` con las siguientes características de canalización: + [Almacenamiento en caché de pasos de canalización](https://docs.aws.amazon.com/sagemaker/latest/dg/pipelines-caching.html) + [Archivos de propiedades](https://docs.aws.amazon.com/sagemaker/latest/dg/build-and-manage-propertyfile.html#build-and-manage-propertyfile-property)