Using files in deployments¶

file is available in UbiOps as a structured data type. You can select the file data type for in- or output fields when defining the deployment. For each file field, one file can be used per request.

Passing files in a request¶

When making a request, files are passed to the file fields of a deployment by passing the file URI of an existing file. This means that prior to making the request either a new file needs to be uploaded, or an already existing file should be selected. The file URI should be formatted as ubiops-file://{bucket-name}/{file_name}.

When using the WebApp, the uploading of the file and passing the URI in the deployment request is handled automatically in the background. When using the API, CLI or client library, you need to upload the file with a separate API request(s) before making the deployment request. Here's an example with the Python client library:

import ubiops
configuration = ubiops.Configuration()
# Configure API token authorization
configuration.api_key['Authorization'] = 'Token <YOUR_API_TOKEN>'

# Enter a context with an instance of the API client
api_client = ubiops.ApiClient(configuration)

project_name = 'project_name_example'
bucket_name = 'bucket_name_example'
file_input = 'file_example.png'

# Upload a file
file_uri = ubiops.utils.upload_file(api_client, project_name, file_input, bucket_name)

# Define request data with file
data = {'file_input': file_uri}

api_client.deployment_version_requests_create(
    project_name=project_name,
    deployment_name='file-example-deployment',
    version='v1',
    data=data
)

Retrieving files is done using the file URI's as well. In the WebApp a download button is available after completing a request or by navigating to a file in your bucket. In code a file is downloaded using the API, for example, using the UbiOps Python client library:

# Download a file
file_uri = 'ubiops-file://example-bucket/file_example.png'

ubiops.utils.download_file(
    api_client,
    project_name,
    file_uri=file_uri,
    output_path='.',
    stream=True,
    chunk_size=8192
)

See platform limits for limitations on the usage of files.

Handling file input in the deployment code¶

UbiOps makes sure that input files given in the request are automatically made available on the file system of the deployment during the request. The file URI initially passed while creating the request is replaced by the absolute path where the file can be accessed.

For example, for a request made with the following request data containing a file identified by a file URI:

{
    "file": "ubiops-file://default/file_example.png"
}

The data object available inside the request method of the deployment class would look as follows:

{
    "file": "/home/deployment/files/{file-id}/file_example.png"
}

The file can then be used as a normal file in the request method of the deployment, for example, in Python:

class Deployment:
    def request(self, data):
        with open(data['file'], "rb") as f:
            # Process the file

Handling file output in the deployment code¶

For file outputs in a deployment, UbiOps handles the uploading of the file to the project file storage and returning a file URI in the response of the request.

For fields of type file, the path to the file should be returned in the response of the request method. For example in Python, for a deployment with a file output field output_file:

class Deployment:
    def request(self, data):
        with open("/tmp/file.txt", "w") as f:
            f.write("test")

        return {
            "output_file": "/tmp/file.txt"
        }

The above snippet will store the outputted file in the default bucket. In case you want to store it in a different bucket, you can pass the bucket name in the return statement as well. You can also pass the optional bucket_file paramater, which specifies exactly where to store the file in your bucket. This can be usefull when you want to store the output in a specific folder.

class Deployment:
    def request(self, data):
        with open("/tmp/file.txt", "w") as f:
            f.write("test")

        return {
            "output_file": {
                "file": "/tmp/file.txt",
                "bucket": "example-bucket",
                "bucket_file": "request-output/file.txt"
            }
        }

The processed response of the request will then look as follows:

{
    "output_file": "ubiops-file://example-bucket/file.txt"
}