Guide to DLHubClient¶
The DLHubClient provides a Python wrapper around the DLHub and funcX web services. In this part of the guide, we describe how to use the client to publish, discover, and use servables.
The DLHubClient provides several routes for publishing servables to DLHub. The first is to request DLHub to publish from a GitHub repository:
There are also functions for publishing a model stored on the local system.
In either case, you must first create a
BaseServableModel describing your
servable or load in an existing one from disk:
from dlhub_sdk.utils import unserialize_object
with open('dlhub.json') as fp:
model = unserialize_object(json.load(fp))
Then, submit the model via HTTP by calling:
See the Publication Guide for details on how to describe a servable.
The client also provides tools for querying the library of servables available through DLHub.
The most general route for discovering models is to perform a free-text search of the model library:
You can also perform a query to match specific fields of the metadata records by setting the “advanced” flag on your query. For example, matching all Keras models related to materials science is accomplished by:
client.search('servable.type:"Keras Model" AND dlhub.domains:"chemistry"', advanced=True)
The client also provides functions for common queries, such as:
Each of these tools returns metadata for only the most recent version of the servable by default, but can be configured to return all versions.
A way to perform advanced queries besides to craft your own query string is to use the “query helper” object that backs each of the pre-configured search functions. A new query helper is created by calling:
to return a blank query object, which you can then use to create a query with the advanced functions provided by the DLHubSearchHelper. For example, the advanced query shown above can be executed using:
client.query.match_term('servable.type', '"Keras Model"').match_domains('chemistry').search()
The DLHubClient.run command runs servables published through DLHub. DLHub uses the funcX to perform remote inference tasks. funcX is a function-as-a-service platform designed to reliably and securely perform remote invocation. Using the DLHub Client to perform an inference task invokes a funcX function on the target servable. To invoke the servable, you need to know the name of the servable:
The data (
x) will be serialized and passed to the servable to act on.
funcX performs client-side rate limiting to avoid accidentally overloading the service. By default, these limits restrict the number of invocations to 20 over 10 seconds and restrict input size to 5MB. These limits are described in detail in the funcX docs. The soft limits can be increased by modifying the DLHub client’s funcX client::
client._fx_client.max_requests = 30
Note: The funcX web service will still restrict unnecessarily large inputs. Please contact us if this becomes an issue and we can help orchestrate big data invocations.
The DLHubClient.describe_servable and
are especially useful when using an unfamiliar servable. The
describe_servable method returns complete information
about a servable, and the
describe_method returns information about a certain method of the servable.
Use these function to understand what the servable does and to learn how to use it.