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.
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.
#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.8conda 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.gitcd 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:
#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.
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 pipelinerequests.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 withtriggerin HTTP POST Request, the URL ends withtrigger-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}/trigger-multipart", files=body)
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 ↓↓↓
