Back

VDP 101 [4/7] How to trigger a SYNC pipeline?

In this tutorial, we are going to demonstrate how to trigger a SYNC pipeline step-by-step using an Objective Detection example.
Po-Yu Chen's github avatar

Published by

Po-Yu Chen

on 3/6/2023

The theme of this tutorial

In the previous tutorial VDP 101 [3/7] Create your first pipeline on VDP, you've learnt how to create a pipeline in SYNC mode with ID vdp-101-sync via VDP Console. In this tutorial, we use it to showcase how to trigger this SYNC pipeline step-by-step.

INFO

You can create a VDP pipeline in SYNC, ASYNC, or PULL mode, depending on the use case. The combination of selected source and destination determines the pipeline mode. Further details can be found in VDP 101 [6/7] Pipeline modes - SYNC, ASYNC, and PULL.

#Trigger the pipeline with cURL requests

You can also trigger your pipelines in the command line. Choose a pipeline such as vdp-101-sync on your VDP Console. You can find the corresponding HTTP request at the bottom of your pipeline page.

cURL(url)
cURL(base64)
cURL(multipart)
Copy

curl -X POST http://localhost:8080/v1alpha/pipelines/vdp-101-sync/triggerSync -d '{
"task_inputs": [
{
"detection": {
"image_url": "https://artifacts.instill.tech/imgs/dog.jpg"
}
},
{
"detection": {
"image_url": "https://artifacts.instill.tech/imgs/polar-bear.jpg"
}
}
]
}'

#Trigger the pipeline via Python example

#Create a Python virtual environment

In addition to the cURL examples above, you can trigger the pipeline in our Python example.

In this tutorial, we'll use Conda as the package management system. You can install Conda via anaconda or miniconda. Using a virtual environment is not required but recommended.

Create and activate a Conda virtual environment named vdp-101-sync with Python 3.8:


conda create --name vdp-101-sync python=3.8
conda activate vdp-101-sync

Once activated, you can run scripts from this environment.

#Install app dependencies

Clone the VDP repo and go to /examples/vdp-101/sync directory of the VDP project.


git clone https://github.com/instill-ai/vdp.git
cd vdp/examples/vdp-101/sync

The directory will look like the following:


├── README.md
├── dog.jpg
├── requirement.txt
├── sync-http-base64.py
├── sync-http-multipart.py
├── sync-http-url.py
└── utils.py

where requirements.txt file contains all the required dependencies. Install all the dependencie to run the app from the activated virtual environment.


pip install -r requirements.txt

Let's dive into our example codes to see what happened.

To check if you got everything ready, run the Python example with the command below.


python sync-http-url.py --api-gateway-url=http://localhost:8080 --pipeline-id=vdp-101-sync --image-url=https://artifacts.instill.tech/imgs/dog.jpg

Voilà! You just triggered the object detection pipeline vdp-101-sync! You should see the detection results shown on the input dog image:

An example demonstrating object detection with VDP.

#How to form a trigger request

VDP currently supports HTTP and gRPC protocols. When triggering the pipeline with HTTP protocol, users can send their data via HTTP POST Requests or HTTP Multipart Requests. You can find these examples in /examples/vdp-101/sync/ folder of the VDP project.

#POST request to send JSON

HTTP POST Requests allows users to trigger the pipeline and upload input data as a JSON object in the message payload. VDP currently supports two types of JSON objects:

  • URL: clients pass Internet links service, which will locate and download the image files accordingly. An example can be found in sync-http-url.py.
  • base64: clients upload image files in base64 format, encoding images into UTF-8 Strings. We convert JPG to BASE64 using the base64 library in this tutorial example. An example can be found in sync-http-base64.py.

Below are examples that demonstrate the structure of the JSON objects. Inputs can be a list of multiple payloads if needed.

Python(url)
Python(base64)
Copy

body = {
"task_inputs": [
{
"detection": {
"image_url": image_url
}
}
]
}

INFO

Although JSON object is commonly used, it is not optimal to upload large objects, for which we recommend you trigger the pipeline using HTTP Multipart Request.

Once the JSON payload is ready, we can trigger the pipeline using standard HTTP POST requests. There are three arguments In the HTTP POST messages. They are pipeline backend URL, pipeline_id, and json, the JSON object prepared above.


# Post HTTP requests to trigger VDP pipeline
requests.post(f"{api_gateway_url}/pipelines/{pipeline_id}/trigger", json=body)

API Gateway is single point of entry for all VDP services. In this example, the API Gateway URL is defined as {api_gateway_url}. The value is set to http://localhost:8080/v1alpha by default for local deployment, in which v1alpha shows the VDP version. {pipeline-id} indicates the pipeline that have been created beforehand for us to trigger. In this example, it is set to vdp-101-sync.

#Multipart request to upload a file

If you're uploading large objects, we recommend you use HTTP Multipart Requests. Multipart upload allows you to upload a single object as a set of parts. Each part is a contiguous portion of the object's data. If transmission of any part fails, you can retransmit that part without affecting other parts.

We recommend that you use multipart upload in the following ways:

  • If you're uploading large objects over a stable high-bandwidth network, use multipart upload to maximise the use of your available bandwidth by uploading object parts in parallel for multi-threaded performance.
  • If you're uploading over a spotty network, use multipart upload to increase resiliency to network errors by avoiding upload restarts. When using multipart upload, you need to retry uploading only the parts that are interrupted during the upload. You don't need to restart uploading your object from the beginning.

In sync-http-multipart.py, we demonstrate how to exploit Multipart Request.

Below is an example demonstrating how to prepare the payload for multipart upload, where images is a list consisting of the image file names.


body = [("file", (img, open(img, 'rb'))) for img in images]

The HTTP POST request is similar to the HTTP POST Request. The only differences are:

  • API endpoint URL: instead of ending with trigger in HTTP POST Request, the URL ends with trigger-multipart.
  • files=body: instead of passing the files as a JSON object, use a list of files in tuples.

requests.post(f"{pipeline_backend_base_url}/pipelines/{pipeline_id}/triggerSyncMultipart", files=body)

INFO

For further details of the Python requests.post() method, we refer readers here.

#What's next?

Okay, we have learned how to trigger pipelines on VDP. Let's see how to parse the Object Detection pipeline responses in our following tutorial → VDP 101 [5/7] How to parse responses from SYNC pipelines.



↓↓↓ VDP 101 - Get familiar with the basics ↓↓↓

Last updated: 8/2/2023, 1:52:16 PM