|
| 1 | +--- |
| 2 | +sidebar_position: 5 |
| 3 | +--- |
| 4 | + |
| 5 | +# Asynchronous Queries |
| 6 | + |
| 7 | +Groundlight provides a simple interface for submitting asynchronous queries. This is useful for times in which the thread or process or machine submitting image queries is not the same thread or machine that will be retrieving and using the results. For example, you might have a forward deployed robot or camera that submits image queries to Groundlight, and a separate server that retrieves the results and takes action based on them. We will refer to these two machines as the **submitting machine** and the **retrieving machine**. |
| 8 | + |
| 9 | +## Setup Submitting Machine |
| 10 | +On the **submitting machine**, you will need to install the Groundlight Python SDK. Then you can submit image queries asynchronously using the `ask_async` interface (read the full documentation [here](pathname:///python-sdk/api-reference-docs/#groundlight.client.Groundlight.ask_async)). `ask_async` submits your query and returns as soon as the query is submitted. It does not wait for an answer to be available prior to returning to minimize the time your program spends interacting with Groundlight. As a result, the `ImageQuery` object `ask_async` returns lacks a `result` (the `result` field will be `None`). This is acceptable for this use case as the **submitting machine** is not interested in the result. Instead, the **submitting machine** just needs to communicate the `ImageQuery.id`s to the **retrieving machine** - this might be done via a database, a message queue, or some other mechanism. For this example, we assume you are using a database where you save the `ImageQuery.id` to it via `db.save(image_query.id)`. |
| 11 | + |
| 12 | +```python notest |
| 13 | +from groundlight import Groundlight |
| 14 | +import cv2 |
| 15 | +from time import sleep |
| 16 | + |
| 17 | +detector = gl.get_or_create_detector(name="your_detector_name", query="your_query") |
| 18 | + |
| 19 | +cam = cv2.VideoCapture(0) # Initialize camera (0 is the default index) |
| 20 | + |
| 21 | +while True: |
| 22 | + _, image = cam.read() # Capture one frame from the camera |
| 23 | + image_query = gl.ask_async(detector=detector, image=image) # Submit the frame to Groundlight |
| 24 | + db.save(image_query.id) # Save the image_query.id to a database for the retrieving machine to use |
| 25 | + sleep(10) # Sleep for 10 seconds before submitting the next query |
| 26 | + |
| 27 | +cam.release() # Release the camera |
| 28 | + |
| 29 | +``` |
| 30 | + |
| 31 | +## Setup Retrieving Machine |
| 32 | +On the **retrieving machine** you will need to install the Groundlight Python SDK. Then you can retrieve the results of the image queries submitted by another machine using `get_image_query`. The **retrieving machine** can then use the `ImageQuery.result` to take action based on the result for whatever application you are building. For this example, we assume your application looks up the next image query to process from a database via `db.get_next_image_query_id()` and that this function returns `None` once all `ImageQuery`s are processed. |
| 33 | +```python notest |
| 34 | +from groundlight import Groundlight |
| 35 | + |
| 36 | +detector = gl.get_or_create_detector(name="your_detector_name", query="your_query") |
| 37 | + |
| 38 | +image_query_id = db.get_next_image_query_id() |
| 39 | + |
| 40 | +while image_query_id is not None: |
| 41 | + image_query = gl.get_image_query(id=image_query_id) # retrieve the image query from Groundlight |
| 42 | + result = image_query.result |
| 43 | + |
| 44 | + # take action based on the result of the image query |
| 45 | + if result.label == 'YES': |
| 46 | + pass # TODO: do something based on your application |
| 47 | + elif result.label == 'NO': |
| 48 | + pass # TODO: do something based on your application |
| 49 | + elif result.label == 'UNCLEAR': |
| 50 | + pass # TODO: do something based on your application |
| 51 | + |
| 52 | + # update image_query_id for next iteration of the loop |
| 53 | + image_query_id = db.get_next_image_query_id() |
| 54 | +``` |
| 55 | + |
| 56 | +## Important Considerations |
| 57 | +When you submit an image query asynchronously, ML prediction on your query is **not** instant. So attempting to retrieve the result immediately after submitting an async query will likely result in an `UNCLEAR` result as Groundlight is still processing your query. Instead, if your code needs a `result` synchronously we recommend using one of our methods with a polling mechanism to retrieve the result. You can see all of the interfaces available in the documentation [here](pathname:///python-sdk/api-reference-docs/#groundlight.client.Groundlight). |
| 58 | + |
| 59 | +```python notest |
| 60 | +from groundlight import Groundlight |
| 61 | +from PIL import Image |
| 62 | + |
| 63 | +detector = gl.get_or_create_detector(name="your_detector_name", query="your_query") |
| 64 | +image = Image.open("/path/to/your/image.jpg") |
| 65 | +image_query = gl.ask_async(detector=detector, image=image) # Submit async query to Groundlight |
| 66 | +result = image_query.result # This will always be 'None' as you asked asynchronously |
| 67 | + |
| 68 | +image_query = gl.get_image_query(id=image_query.id) # Immediately retrieve the image query from Groundlight |
| 69 | +result = image_query.result # This will likely be 'UNCLEAR' as Groundlight is still processing your query |
| 70 | +``` |
0 commit comments