<jupyter_start><jupyter_text>Run in Colab                        View on GitHub                  Open in Google Cloud Notebooks        Introduction to Vertex Pipelines using the KFP SDK  OverviewThis notebook provides an introduction to using [Vertex Pipelines](https://cloud.google.com/vertex-ai/docs/pipelines) with [the Kubeflow Pipelines (KFP) SDK](https://www.kubeflow.org/docs/components/pipelines/). ObjectiveIn this example, you learn:- How to define and compile a pipeline.- How to schedule recurring pipeline runs.- How to specify which service account to use for a pipeline run. Costs This tutorial uses billable components of Google Cloud:* Vertex AI Training* Cloud Storage* Cloud Functions* Cloud SchedulerLearn about pricing for [Vertex AI](https://cloud.google.com/vertex-ai/pricing), [Cloud Storage](https://cloud.google.com/storage/pricing), [Cloud Functions](https://cloud.google.com/functions/pricing), and [Cloud Scheduler](https://cloud.google.com/scheduler/pricing), and use the [PricingCalculator](https://cloud.google.com/products/calculator/)to generate a cost estimate based on your projected usage.  Set up your local development environment**If you are using Colab or Google Cloud Notebooks**, your environment already meetsall the requirements to run this notebook. You can skip this step. **Otherwise**, make sure your environment meets this notebook's requirements.You need the following:* The Google Cloud SDK* Git* Python 3* virtualenv* Jupyter notebook running in a virtual environment with Python 3The Google Cloud guide to [Setting up a Python developmentenvironment](https://cloud.google.com/python/setup) and the [Jupyterinstallation guide](https://jupyter.org/install) provide detailed instructionsfor meeting these requirements. The following steps provide a condensed set ofinstructions:1. [Install and initialize the Cloud SDK.](https://cloud.google.com/sdk/docs/)1. [Install Python 3.](https://cloud.google.com/python/setupinstalling_python)1. [Install   virtualenv](https://cloud.google.com/python/setupinstalling_and_using_virtualenv)   and create a virtual environment that uses Python 3. Activate the virtual environment.1. To install Jupyter, run `pip install jupyter` on thecommand-line in a terminal shell.1. To launch Jupyter, run `jupyter notebook` on the command-line in a terminal shell.1. Open this notebook in the Jupyter Notebook Dashboard.  Install additional packagesInstall the KFP SDK.<jupyter_code>import os

# The Google Cloud Notebook product has specific requirements
IS_GOOGLE_CLOUD_NOTEBOOK = os.path.exists("/opt/deeplearning/metadata/env_version")

# Google Cloud Notebook requires dependencies to be installed with '--user'
USER_FLAG = ""
if IS_GOOGLE_CLOUD_NOTEBOOK:
    USER_FLAG = "--user"
!pip3 install {USER_FLAG} kfp --upgrade<jupyter_output><empty_output><jupyter_text>Restart the kernelAfter you install the additional packages, you need to restart the notebook kernel so it can find the packages.<jupyter_code># Automatically restart kernel after installs
import os

if not os.getenv("IS_TESTING"):
    # Automatically restart kernel after installs
    import IPython

    app = IPython.Application.instance()
    app.kernel.do_shutdown(True)<jupyter_output><empty_output><jupyter_text>Check the version of the package you installed.  The KFP SDK version should be >=1.6.<jupyter_code>!python3 -c "import kfp; print('KFP SDK version: {}'.format(kfp.__version__))"<jupyter_output><empty_output><jupyter_text>Before you beginThis notebook does not require a GPU runtime.  Set up your Google Cloud project**The following steps are required, regardless of your notebook environment.**1. [Select or create a Google Cloud project](https://console.cloud.google.com/cloud-resource-manager). When you first create an account, you get a $300 free credit towards your compute/storage costs.1. [Make sure that billing is enabled for your project](https://cloud.google.com/billing/docs/how-to/modify-project).1. [Enable the Vertex AI, Cloud Storage, and Compute Engine APIs](https://console.cloud.google.com/flows/enableapi?apiid=aiplatform.googleapis.com,compute_component,storage-component.googleapis.com). 1. Follow the "**Configuring your project**" instructions from the Vertex Pipelines documentation.1. If you are running this notebook locally, you will need to install the [Cloud SDK](https://cloud.google.com/sdk).1. Enter your project ID in the cell below. Then run the cell to make sure theCloud SDK uses the right project for all the commands in this notebook.**Note**: Jupyter runs lines prefixed with `!` as shell commands, and it interpolates Python variables prefixed with `$` into these commands.  Set your project ID**If you don't know your project ID**, you may be able to get your project ID using `gcloud`.<jupyter_code>import os

PROJECT_ID = ""

# Get your Google Cloud project ID from gcloud
if not os.getenv("IS_TESTING"):
    shell_output=!gcloud config list --format 'value(core.project)' 2>/dev/null
    PROJECT_ID = shell_output[0]
    print("Project ID: ", PROJECT_ID)<jupyter_output><empty_output><jupyter_text>Otherwise, set your project ID here.<jupyter_code>if PROJECT_ID == "" or PROJECT_ID is None:
    PROJECT_ID = "python-docs-samples-tests"  # @param {type:"string"}<jupyter_output><empty_output><jupyter_text>TimestampIf you are in a live tutorial session, you might be using a shared test account or project. To avoid name collisions between users on resources created, you create a timestamp for each instance session, and append it onto the name of resources you create in this tutorial.<jupyter_code>from datetime import datetime

TIMESTAMP = datetime.now().strftime("%Y%m%d%H%M%S")<jupyter_output><empty_output><jupyter_text>Authenticate your Google Cloud account**If you are using Google Cloud Notebooks**, your environment is alreadyauthenticated. Skip this step. **If you are using Colab**, run the cell below and follow the instructionswhen prompted to authenticate your account via oAuth.**Otherwise**, follow these steps:1. In the Cloud Console, go to the [**Create service account key**   page](https://console.cloud.google.com/apis/credentials/serviceaccountkey).2. Click **Create service account**.3. In the **Service account name** field, enter a name, and   click **Create**.4. In the **Grant this service account access to project** section, click the **Role** drop-down list. Type "Vertex AI"into the filter box, and select   **Vertex AI Administrator**. Type "Storage Object Admin" into the filter box, and select **Storage Object Admin**.5. Click *Create*. A JSON file that contains your key downloads to yourlocal environment.6. Enter the path to your service account key as the`GOOGLE_APPLICATION_CREDENTIALS` variable in the cell below and run the cell.<jupyter_code>import os
import sys

# If you are running this notebook in Colab, run this cell and follow the
# instructions to authenticate your GCP account. This provides access to your
# Cloud Storage bucket and lets you submit training jobs and prediction
# requests.

# The Google Cloud Notebook product has specific requirements
IS_GOOGLE_CLOUD_NOTEBOOK = os.path.exists("/opt/deeplearning/metadata/env_version")

# If on Google Cloud Notebooks, then don't execute this code
if not IS_GOOGLE_CLOUD_NOTEBOOK:
    if "google.colab" in sys.modules:
        from google.colab import auth as google_auth

        google_auth.authenticate_user()

    # If you are running this notebook locally, replace the string below with the
    # path to your service account key and run this cell to authenticate your GCP
    # account.
    elif not os.getenv("IS_TESTING"):
        %env GOOGLE_APPLICATION_CREDENTIALS ''<jupyter_output><empty_output><jupyter_text>Create a Cloud Storage bucket as necessaryYou will need a Cloud Storage bucket for this example.  If you don't have one that you want to use, you can make one now.Set the name of your Cloud Storage bucket below. It must be unique across allCloud Storage buckets.You may also change the `REGION` variable, which is used for operationsthroughout the rest of this notebook. Make sure to [choose a region where Vertex AI services areavailable](https://cloud.google.com/vertex-ai/docs/general/locationsavailable_regions). You maynot use a Multi-Regional Storage bucket for training with Vertex AI.<jupyter_code>BUCKET_NAME = "gs://[your-bucket-name]"  # @param {type:"string"}
REGION = "us-central1"  # @param {type:"string"}
if BUCKET_NAME == "" or BUCKET_NAME is None or BUCKET_NAME == "gs://[your-bucket-name]":
    BUCKET_NAME = "gs://" + PROJECT_ID + "aip-" + TIMESTAMP<jupyter_output><empty_output><jupyter_text>**Only if your bucket doesn't already exist**: Run the following cell to create your Cloud Storage bucket.<jupyter_code>! gsutil mb -l $REGION $BUCKET_NAME<jupyter_output><empty_output><jupyter_text>Finally, validate access to your Cloud Storage bucket by examining its contents:<jupyter_code>! gsutil ls -al $BUCKET_NAME<jupyter_output><empty_output><jupyter_text>Import libraries and define constants Define constants used in this tutorial.<jupyter_code>PATH=%env PATH
%env PATH={PATH}:/home/jupyter/.local/bin

USER = "your-user-name"  # <---CHANGE THIS
PIPELINE_ROOT = "{}/pipeline_root/{}".format(BUCKET_NAME, USER)

PIPELINE_ROOT<jupyter_output><empty_output><jupyter_text>Import packages used in this tutorial.<jupyter_code>from typing import NamedTuple

from kfp import dsl
from kfp.v2 import compiler
from kfp.v2.dsl import component
from kfp.v2.google.client import AIPlatformClient<jupyter_output><empty_output><jupyter_text>Define a simple pipelineThis example defines a simple pipeline that has three steps.The following sections define some pipeline *components*, and then defines a pipeline that uses them.  Create Python function-based pipeline componentsFirst, create a component based on a very simple Python function. It takes a string input parameter and returns that value as output.Note the use of the `@component` decorator, which compiles the function to a KFP component when evaluated.  For example purposes, this example specifies a base image to use for the component (`python:3.9`), and a component YAML file, `hw.yaml`. The compiled component spec will be written to this file.  (The default base image is `python:3.7`, which would of course work just fine too).Next, run the cell below to generate the component yaml file in your local directory.<jupyter_code>@component(output_component_file="hw.yaml", base_image="python:3.9")
def hello_world(text: str) -> str:
    print(text)
    return text<jupyter_output><empty_output><jupyter_text>As you'll see below, compilation of this component creates a [task factory function](https://www.kubeflow.org/docs/components/pipelines/sdk/python-function-components/)—called `hello_world`— that you can use in defining a pipeline step.  While not shown here, if you want to share this component definition, or use it in another context, you could also load it from its yaml file like this:`hello_world_op = components.load_component_from_file('./hw.yaml')`.  You can also use the `load_component_from_url` method, if your component yaml file is stored online. (For GitHub URLs, load the 'raw' file.) Next, define two additional pipeline components.  For example purposes, the first component below, `two_outputs`, installs the given `google-cloud-storage` package. To keep the example code simple, the component function code won't actually use this import. This is one way that you can install the necessary package components.  Alternatively, you can specify a base image that includes the necessary installations.The `two_outputs` component returns two named outputs. In the next section, you'll see how those outputs can be consumed by other pipeline steps. The second component below, `consumer`, takes three string inputs and prints them out.<jupyter_code>@component(packages_to_install=["google-cloud-storage"])
def two_outputs(
    text: str,
) -> NamedTuple(
    "Outputs",
    [
        ("output_one", str),  # Return parameters
        ("output_two", str),
    ],
):
    # the import is not actually used for this simple example, but the import
    # is successful, as it was included in the `packages_to_install` list.
    from google.cloud import storage  # noqa: F401

    o1 = f"output one from text: {text}"
    o2 = f"output two from text: {text}"
    print("output one: {}; output_two: {}".format(o1, o2))
    return (o1, o2)


@component
def consumer(text1: str, text2: str, text3: str):
    print(f"text1: {text1}; text2: {text2}; text3: {text3}")<jupyter_output><empty_output><jupyter_text>Define a pipeline that uses the componentsNext, define a pipeline that uses these three components.By evaluating the component definitions above, you've created task factory functions that are used in the pipeline definition to create pipeline steps.The pipeline takes an input parameter, and passes that parameter as an argument to the first two pipeline steps (`hw_task` and `two_outputs_task`).  Then, the third pipeline step (`consumer_task`) consumes the outputs of the first and second steps.  Because the `hello_world` component definition just returns one unnamed output, you refer to it as `hw_task.output`.  The `two_outputs` task returns two named outputs, which you access as `two_outputs_task.outputs[""]`.Note: in the `@dsl.pipeline` decorator, you're defining the `PIPELINE_ROOT` Cloud Stora path to use.  If you had not included that info here, it would be required to specify it when creating the pipeline run, as you'll see below.<jupyter_code>@dsl.pipeline(
    name="hello-world-v2",
    description="A simple intro pipeline",
    pipeline_root=PIPELINE_ROOT,
)
def intro_pipeline(text: str = "hi there"):
    hw_task = hello_world(text)
    two_outputs_task = two_outputs(text)
    consumer_task = consumer(  # noqa: F841
        hw_task.output,
        two_outputs_task.outputs["output_one"],
        two_outputs_task.outputs["output_two"],
    )<jupyter_output><empty_output><jupyter_text>Compile and run the pipelineNext, you compile the pipeline.<jupyter_code>from kfp.v2 import compiler  # noqa: F811

compiler.Compiler().compile(
    pipeline_func=intro_pipeline, package_path="hw_pipeline_job.json"
)<jupyter_output><empty_output><jupyter_text>The pipeline compilation generates the `hw_pipeline_job.json` job spec file.Next, instantiate an API client object:<jupyter_code>from kfp.v2.google.client import AIPlatformClient  # noqa: F811

api_client = AIPlatformClient(
    project_id=PROJECT_ID,
    region=REGION,
)<jupyter_output><empty_output><jupyter_text>Then, you run the defined pipeline like this:<jupyter_code>response = api_client.create_run_from_job_spec(
    job_spec_path="hw_pipeline_job.json",
    # pipeline_root=PIPELINE_ROOT  # this argument is necessary if you did not specify PIPELINE_ROOT as part of the pipeline definition.
)<jupyter_output><empty_output><jupyter_text>Click on the generated link to see your run in the Cloud Console.  It should look like this:  Recurring pipeline runs: create a scheduled pipeline jobThis section shows how to create a **scheduled pipeline job**.  You do this using the pipeline you already defined.Under the hood, the scheduled jobs are supported by the Cloud Scheduler and a Cloud Functions function.  Check first that the APIs for both of these services are enabled. You will need to first enable the [enable the Cloud Scheduler API](http://console.cloud.google.com/apis/library/cloudscheduler.googleapis.com) and the [Cloud Functions and Cloud Build APIs](https://console.cloud.google.com/flows/enableapi?apiid=cloudfunctions,cloudbuild.googleapis.com) if you have not already done so.  Note:you need to [create an App Engine app for your project](https://cloud.google.com/scheduler/docs/quickstart) if one does not already exist.See the [Cloud Scheduler](https://cloud.google.com/scheduler/docs/configuring/cron-job-schedules) documentation for more on the cron syntax. Create a scheduled pipeline job, passing as an arg the job spec file that you compiled above.  Note that you can pass a `parameter_values` dict that specifies the pipeline input parameters you want to use.<jupyter_code># adjust time zone and cron schedule as necessary
response = api_client.create_schedule_from_job_spec(
    job_spec_path="hw_pipeline_job.json",
    schedule="2 * * * *",
    time_zone="America/Los_Angeles",  # change this as necessary
    parameter_values={"text": "Hello world!"},
    # pipeline_root=PIPELINE_ROOT  # this argument is necessary if you did not specify PIPELINE_ROOT as part of the pipeline definition.
)<jupyter_output><empty_output><jupyter_text>Once the scheduled job is created, you can see it listed in the [Cloud Scheduler](https://console.cloud.google.com/cloudscheduler/) panel in the Console.You can test the setup from the Cloud Scheduler panel by clicking 'RUN NOW'.> **Note**: The implementation is using a Cloud Functions function, which you can see listed in the [Cloud Functions](https://console.cloud.google.com/functions/list) panel in the console as `templated_http_request-v1`.  Don't delete this function, as it will prevent the Cloud Scheduler jobs from actually kicking off the pipeline run.  If you do delete it, create a new scheduled job in order to recreate the function.   When you're done experimenting, you probably want to **PAUSE** your scheduled job from the Cloud Scheduler panel, so that the recurrent jobs do not keep running.  Specifying a service account to use for a pipeline runBy default, the [service account](https://cloud.google.com/iam/docs/service-accounts) used for your pipeline run is your [default compute engine service account](https://cloud.google.com/compute/docs/access/service-accountsdefault_service_account).  However, you might want to run pipelines with permissions to access different roles than those configured for your default SA (e.g. perhaps using a more restricted set of permissions).If you want to execute your pipeline using a different service account, this is straightforward to do.  You just need to give the new service account the correct permissions.   Create a service account See the [documentation](https://cloud.google.com/vertex-ai/docs/pipelines/configure-projectservice-account) for information on the process of creating and configuring a service account to work with Vertex Pipelines.  Once your service account is configured, you can pass it as an arg to the `create_run_from_job_spec` method, as follows.  Set `SERVICE_ACCOUNT` to your info and uncomment the `service_account` arg in `create_run_from_job_spec`:<jupyter_code>SERVICE_ACCOUNT = (
    "<<EMAIL>"  # <--- CHANGE THIS
)

api_client = AIPlatformClient(
    project_id=PROJECT_ID,
    region=REGION,
)

response = api_client.create_run_from_job_spec(
    job_spec_path="hw_pipeline_job.json",  # <--- CHANGE THIS IF YOU WANT TO RUN OTHER PIPELINES
    pipeline_root=PIPELINE_ROOT,
    #     service_account=SERVICE_ACCOUNT,  # <-- UNCOMMENT to use non-default service account
)<jupyter_output><empty_output><jupyter_text>The pipeline job runs with the permissions of the given service account.  Pipeline step cachingBy default, pipeline step caching is enabled. This means that the results of previous step executions are reused when possible. if you want to disable caching for a pipeline run, you can pass the `enable_caching=False` arg to the `create_run_from_job_spec` function when you submit the pipeline job, as shown below.  Try submitting the example pipeline job again, first with and then without caching enabled.<jupyter_code># response = api_client.create_run_from_job_spec(
#     job_spec_path="hw_pipeline_job.json",
#     enable_caching=False
# )<jupyter_output><empty_output><jupyter_text>Using the Pipelines REST APIAt times you may want to use the REST API instead of the Python KFP SDK.  Below are examples of how to do that.Where a command requires a pipeline ID, you can get that info from the "Run" column in the pipelines list— as shown below— as well as from the 'details' page for a given pipeline.  You can also see that info when you list pipeline job(s) via the API.> Note: Currently, the KFP SDK does not support all the API calls below.<jupyter_code>ENDPOINT = REGION + "-aiplatform.googleapis.com"<jupyter_output><empty_output><jupyter_text>List pipeline jobs(This request may generate a large response if you have many pipeline runs).<jupyter_code>! curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)"   -H "Content-Type: application/json"   https://{ENDPOINT}/v1beta1/projects/{PROJECT_ID}/locations/{REGION}/pipelineJobs<jupyter_output><empty_output><jupyter_text>Create a pipeline jobFor this API request, you need to submit a compiled pipeline job spec.  We're using the one we generated above, "hw_pipeline_job.json".<jupyter_code>! curl -X POST  -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json; charset=utf-8"   https://{ENDPOINT}/v1beta1/projects/{PROJECT_ID}/locations/{REGION}/pipelineJobs  --data "@sample_pipeline.json"<jupyter_output><empty_output><jupyter_text>Get a pipeline job from its ID<jupyter_code>PIPELINE_RUN_ID = "xxxx"  # <---CHANGE THIS
! curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)"   -H "Content-Type: application/json"   https://{ENDPOINT}/v1beta1/projects/{PROJECT_ID}/locations/{REGION}/pipelineJobs/{PIPELINE_RUN_ID}<jupyter_output><empty_output><jupyter_text>Cancel a pipeline job given its ID<jupyter_code>PIPELINE_RUN_ID_TO_CANCEL = "xxxx"  # <---CHANGE THIS
! curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)"   -H "Content-Type: application/json"   https://{ENDPOINT}/v1beta1/projects/{PROJECT_ID}/locations/{REGION}/pipelineJobs/{PIPELINE_RUN_ID_TO_CANCEL}:cancel<jupyter_output><empty_output><jupyter_text>Delete a pipeline job given its ID<jupyter_code>PIPELINE_RUN_ID_TO_DELETE = "xxxx"  # <---CHANGE THIS
! curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)"   -H "Content-Type: application/json"   https://{ENDPOINT}/v1beta1/projects/{PROJECT_ID}/locations/{REGION}/pipelineJobs/{PIPELINE_RUN_ID_TO_DELETE}<jupyter_output><empty_output><jupyter_text>Cleaning upTo clean up all Google Cloud resources used in this project, you can [delete the Google Cloudproject](https://cloud.google.com/resource-manager/docs/creating-managing-projectsshutting_down_projects) you used for the tutorial.Otherwise, you can delete the individual resources you created in this tutorial:- delete Cloud Storage objects that were created.  Uncomment and run the command in the cell below **only if you are not using the `PIPELINE_ROOT` path for any other purpose**.<jupyter_code># Warning: this command will delete ALL Cloud Storage objects under the PIPELINE_ROOT path.
# ! gsutil -m rm -r $PIPELINE_ROOT<jupyter_output><empty_output>
{'fraction_non_alphanumeric': 0.08465400567561668, 'fraction_numerical': 0.00366732154551408, 'mean_word_length': 5.246523043359694, 'pattern_counts': {'":': 2, '<': 122, '<?xml version=': 0, '>': 120, 'https://': 33, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'chain_length': '28', 'dir': 'jupyter-structured-clean-dedup', 'id': '96038', 'license': 'Apache-2.0', 'n_tokens_mistral': 6469, 'n_tokens_neox': 6356, 'n_words': 2499, 'path': 'ai-platform-unified/notebooks/official/pipelines/pipelines_intro_kfp.ipynb', 'repo_name': 'polong-lin/ai-platform-samples', 'size': '22959'}