Artifact references

Deeploy uses configuration in JSON notation to specify details for model, explainer and transformer artifacts. This can be either be specified in a 'reference.json' file when using a linked Git repository, or in the Deeploy UI when not using a linked Git repository. This article includes examples for various configurations.

Model reference schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "reference": {
      "type": "object",
      "properties": {
        "azureML": {
          "type": "object",
          "properties": {
            "image": {
              "type": "string"
            },
            "uri": {
              "type": "string"
            },
            "port": {
              "type": "integer"
            },
            "readinessPath": {
              "type": "string"
            },
            "livenessPath": {
              "type": "string"
            },
            "model": {
              "type": ["string", "null"]
            },
            "version": {
              "type": ["string", "null"]
            }
          },
          "required":["image", "uri", "port", "readinessPath", "livenessPath"]
        },
        "docker": {
          "type": "object",
          "properties": {
            "image": {
              "type": "string"
            },
            "uri": {
              "type": "string"
            },
            "port": {
              "type": ["integer", "null"]
            }
          },
          "required": ["image", "uri"]
        },
        "blob": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string"
            },
            "region": {
              "type": ["string", "null"]
            }
          },
          "required": ["url"]
        },
        "huggingface": {
          "type": "object",
          "properties": {
            "model": {
              "type": "string"
            }
          },
        },
        "mlflow": {
          "type": "object",
          "properties": {
            "model": {
              "type": "string"
            },
            "version": {
              "type": ["string", "null"]
            },
            "stage": {
              "type": ["string", "null"]
            },
            "alias": {
              "type": ["string", "null"]
            },
            "blob": {
              "type": "object",
              "properties": {
                "region": {
                  "type": "string"
                }
              },
            }
          },
          "required":["model"]
        },
        "databricks": {
          "type": "object",
          "properties": {
            "model": {
              "type": "string"
            },
            "alias": {
              "type": ["string", "null"]
            },
            "version": {
              "type": ["string", "null"]
            }
          },
          "required":["model"]
        }
      },
    }
  },
}

Explainer reference schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "reference": {
      "type": "object",
      "properties": {
        "azureML": {
          "type": "object",
          "properties": {
            "image": {
              "type": "string"
            },
            "uri": {
              "type": "string"
            },
            "port": {
              "type": "integer"
            },
            "readinessPath": {
              "type": "string"
            },
            "livenessPath": {
              "type": "string"
            },
            "model": {
              "type": ["string", "null"]
            },
            "version": {
              "type": ["string", "null"]
            }
          },
          "required":["image", "uri", "port", "readinessPath", "livenessPath"]
        },
        "docker": {
          "type": "object",
          "properties": {
            "image": {
              "type": "string"
            },
            "uri": {
              "type": "string"
            },
            "port": {
              "type": ["integer", "null"]
            }
          },
          "required": ["image", "uri"]
        },
        "blob": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string"
            },
            "region": {
              "type": ["string", "null"]
            }
          },
          "required": ["url"]
        },
        "mlflow": {
          "type": "object",
          "properties": {
            "model": {
              "type": "string"
            },
            "version": {
              "type": ["string", "null"]
            },
            "stage": {
              "type": ["string", "null"]
            },
            "alias": {
              "type": ["string", "null"]
            },
            "blob": {
              "type": "object",
              "properties": {
                "region": {
                  "type": "string"
                }
              },
            }
          },
          "required":["model"]
        },
        "databricks": {
          "type": "object",
          "properties": {
            "model": {
              "type": "string"
            },
            "alias": {
              "type": ["string", "null"]
            },
            "version": {
              "type": ["string", "null"]
            }
          },
          "required":["model"]
        }
      },
    }
  },
}

Transformer reference schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "reference": {
      "type": "object",
      "properties": {
        "docker": {
          "type": "object",
          "properties": {
            "image": {
              "type": "string"
            },
            "uri": {
              "type": "string"
            },
            "port": {
              "type": ["integer", "null"]
            }
          },
          "required": ["image", "uri"]
        },
        "blob": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string"
            },
            "region": {
              "type": ["string"]
            }
          },
          "required": ["url"]
        },
      "required":["docker"] 
      },
    }
  },
}

Reference in Git repository

When using a Git repository to deploy from, the repository should meet the repository requirements.

Reference to object storage

Using the reference system to deploy a model or explainer from object storage, requires the following format:

1. The URL should link to a folder in the Object Storage
2. The folder in the object storage should contain the model and/or explainer in this exact format: model.<extension> or explainer.<extension>.

Caution

It is crucial that you only have one model file or explainer file in the Object Storage folder, named model.<extension> or explainer.<extension> (i.e. if you use my_model.<extension>, your Deployment will fail)

When using an object storage, it is essential to upload a versioned new file to the object storage and update your reference.json whenever you intend to deploy a new version to uphold a consistent level of provenance. Avoid overwriting files within object storage.

An example of the reference.json file to refer to a model object uploaded in the folder model_folder in S3, as seen in the Scikit-Learn census example:

{
    "reference": {
        "blob": {
            "url": "s3://deeploy-examples/sklearn/census/20220801171658/model_folder"
        }
    }
}

When specifying an S3 bucket in a different region (Deeploy Cloud only) than eu-central-1, you need to specify it in the blob section. In this example, the folder is named model:

# this reference is used in example repository: 
# https://gitlab.com/deeploy-ml/sample-models/example-pytorch-mnist
{  
 "reference": {
     "blob": {
         "url": "s3://deeploy-examples/pytorch/mnist/model",
         "region": "eu-west-1"
     }
  }
}

Reference to Docker image

An example of the reference.json file that refers to a Docker image, as seen in the Custom Image Hello World Example:

# this reference is used in example repository:
# https://gitlab.com/deeploy-ml/sample-models/example-custom-image-hello-world/
{
    "reference": {
        "docker": {
            "image": "deeployml/example-custom-image-hello-world:0.3.0",
            "port": 8080
        }
    }
}

Note

For model and explainer reference.json both docker and blob configurations can be specified.

{
    "reference": {
        "blob": {
            "url": "s3://path-to-folder"
        },
        "docker": {
            "image": "image-name",
            "port": port-number
        }
    }
}

Reference to Databricks Unity Catalog

View the documentation on how to configure the Databricks Unity Catalog integration and how to create Databricks Unity Catalog Deployments.

An example of the reference.json that uses the Databricks Unity Catalog integration in combination with a model alias:

{
    "reference": {
        "databricks": {
            "model": "deeploy.default.model",
            "alias": "Champion"
        }
    }
}

An example of the reference.json that uses the Databricks Unity Catalog integration in combination with a model version:

{
    "reference": {
        "databricks": {
            "model": "deeploy.default.model",
            "version": "5"
        }
    }
}

Other references

View the documentation on Azure Machine Learning Deployments, Hugging Face Deployments, AWS Sagemaker Deployments, or MLflow Deployments to see how to use the reference system if you want to create Deployments using these integrations.