Skip to main content
Version: 1.59

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", "null"]
            },
            "uri": {
              "type": ["string", "null"]
            },
            "port": {
              "type": ["integer", "null"]
            },
            "readinessPath": {
              "type": ["string", "null"]
            },
            "livenessPath": {
              "type": ["string", "null"]
            },
            "model": {
              "type": ["string", "null"]
            },
            "version": {
              "type": ["string", "null"]
            },
            "customPath": {
              "type": ["string", "null"]
            }
          },
          "required":[]
        },
        "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", "null"]
            },
            "uri": {
              "type": ["string", "null"]
            },
            "port": {
              "type": ["integer", "null"]
            },
            "readinessPath": {
              "type": ["string", "null"]
            },
            "livenessPath": {
              "type": ["string", "null"]
            },
            "model": {
              "type": ["string", "null"]
            },
            "version": {
              "type": ["string", "null"]
            },
            "customPath": {
              "type": ["string", "null"]
            }
          },
          "required":[]
        },
        "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. We also support docker with databricks and docker with mlflow configurations. The artifacts downloaded from blob storage/databricks/mlflow are mounted on /mnt/models in the docker container.

{
  "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"
    }
  }
}
note

When deploying an explainer with Databricks Unity Catalog, Deeploy looks for a folder named explainer by default to retrieve explainer artifacts. For models, the root folder is retrieved by default.

Custom artifact paths​

To specify a custom path for model or explainer artifacts, use the customPath parameter in the reference.json:

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

Reference to Azure Machine Learning model registry​

View the documentation on how to configure the Azure Machine Learning integration and how to create Azure Machine Learning Deployments.

An example of the reference.json that uses the Azure Machine Learning integration:

{
  "reference": {
    "azureML": {
      "model": "my-model",
      "version": "5"
    }
  }
}
note

When deploying an explainer with the Azure Machine Learning registry, Deeploy looks for a folder named explainer by default to retrieve explainer artifacts. For models, the root folder is retrieved by default.

Custom artifact paths​

To specify a custom path for model or explainer artifacts, use the customPath parameter in the reference.json:

{
  "reference": {
    "azureML": {
      "model": "my-azureml-model",
      "version": "2",
      "customPath": "folder1"
    }
  }
}

Other references​

View the documentation on 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.