# Custom model components

> Custom model components - Describes custom model support and how to structure a custom model's
> files.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-04-24T16:03:56.256184+00:00` (UTC).

## Primary page

- [Custom model components](https://docs.datarobot.com/en/docs/api/code-first-tools/drum/custom-model-components.html): Full documentation for this topic (HTML).

## Sections on this page

- [Model content](https://docs.datarobot.com/en/docs/api/code-first-tools/drum/custom-model-components.html#model-content): In-page section heading.
- [Model code](https://docs.datarobot.com/en/docs/api/code-first-tools/drum/custom-model-components.html#model-code): In-page section heading.
- [Model metadata](https://docs.datarobot.com/en/docs/api/code-first-tools/drum/custom-model-components.html#model-metadata): In-page section heading.
- [Model environment](https://docs.datarobot.com/en/docs/api/code-first-tools/drum/custom-model-components.html#model-environment): In-page section heading.

## Related documentation

- [Developer documentation](https://docs.datarobot.com/en/docs/api/index.html): Linked from this page.
- [Code-first tools](https://docs.datarobot.com/en/docs/api/code-first-tools/index.html): Linked from this page.
- [DataRobot User Models](https://docs.datarobot.com/en/docs/api/code-first-tools/drum/index.html): Linked from this page.
- [custom model environments](https://docs.datarobot.com/en/docs/workbench/nxt-registry/nxt-environment-workshop/index.html): Linked from this page.
- [runtime parameters](https://docs.datarobot.com/en/docs/workbench/nxt-registry/nxt-model-workshop/nxt-define-custom-model-runtime-parameters.html): Linked from this page.
- [structured custom models](https://docs.datarobot.com/en/docs/api/code-first-tools/drum/structured-custom-models.html): Linked from this page.
- [unstructured custom models](https://docs.datarobot.com/en/docs/api/code-first-tools/drum/unstructured-custom-models.html): Linked from this page.
- [metadata and input validation schema](https://docs.datarobot.com/en/docs/api/code-first-tools/drum/custom-model-metadata.html): Linked from this page.
- [runtime parameters](https://docs.datarobot.com/en/docs/api/code-first-tools/drum/custom-model-runtime-parameters.html): Linked from this page.
- [drop-in environments](https://docs.datarobot.com/en/docs/workbench/nxt-registry/nxt-environment-workshop/nxt-drop-in-envs.html): Linked from this page.
- [custom environment](https://docs.datarobot.com/en/docs/workbench/nxt-registry/nxt-environment-workshop/nxt-create-custom-env.html): Linked from this page.
- [new environment version](https://docs.datarobot.com/en/docs/classic-ui/mlops/deployment/custom-models/custom-model-environments/custom-environments.html#add-an-environment-version): Linked from this page.

## Documentation content

# Custom model components

To create and upload a custom model, you need to define two components—the model’s content and an environment where the model’s content will run:

- Themodel contentis code written in Python or R. To be correctly parsed by DataRobot, the code must follow certain criteria. The model artifact's structure should match the library used by the model. In addition, it should use the appropriatecustom hooksfor Python, R, and Java models. (Optional) You can add files that will be uploaded and used together with the model’s code (for example, you might want to add a separate file with a dictionary if your custom model contains text preprocessing).
- Themodel environmentis defined using a Docker file and additional files that will allow DataRobot to build an image where the model will run. There are a variety of built-in environments; you only need to build your own environment when you need to install Linux packages. For more detailed information, see the section oncustom model environments.

At a high level, the steps to define a custom model with these components include:

1. Define and test model content locally (i.e., on your computer).
2. (Optional) Create a container environment where the model will run.
3. Upload the model content and environment (if applicable) into DataRobot.

## Model content

To define a custom model, create a local folder containing the files listed in the table below (detailed descriptions follow the table).

> [!TIP] Tip
> To ensure your assembled custom model folder has the correct contents, you can find examples of these files in the [DataRobot model template repository](https://github.com/datarobot/datarobot-user-models/tree/master/model_templates) on GitHub.

| File | Description | Required |
| --- | --- | --- |
| Model artifact fileorcustom.py/custom.R file | Provide a model artifact and/or a custom code file. Model artifact: a serialized model artifact with a file extension corresponding to the chosen environment language.Custom code: custom capabilities implemented with hooks (or functions) that enable DataRobot to run the code and integrate it with other capabilities. | Yes |
| model-metadata.yaml | A file describing a model's metadata, including input/output data requirements and runtime parameters. You can supply a schema that can then be used to validate the model when building and training a blueprint. A schema lets you specify whether a custom model supports or outputs: Certain data typesMissing valuesSparse dataA certain number of columns | Required when a custom model outputs non-numeric data. If not provided, a default schema is used. |
| requirements.txt | A list of Python or R packages to add to the base environment. This list pre-installs Python or R packages that the custom model is using but are not a part of the base environment | No |
| Additional files | Other files used by the model (for example, a file that defines helper functions used inside custom.py). | No |

**requirements.txt Python example:**
For Python, provide a list of packages with their versions (1 package per row). For example:

```
numpy>=1.16.0, <1.19.0
pandas==1.1.0
scikit-learn==0.23.1
lightgbm==3.0.0
gensim==3.8.3
sagemaker-scikit-learn-extension==1.1.0
```

**requirements.txt R example:**
For R, provide a list of packages without versions (1 package per row). For example:

```
dplyr
stats
```


### Model code

To define a custom model using DataRobot’s framework, your custom model should include a model artifact corresponding to the chosen environment language, custom code in a `custom.py` (for Python models) or `custom.R` (for R models) file, or both. If you provide only the custom code (without a model artifact), you must use the `load_model` hook. A hook is a function called by the custom model framework during a specific time in the custom model lifecycle. The following hooks can be used in your custom code:

> [!WARNING] Include all required custom model code in hooks
> Custom model hooks are callbacks passed to the custom model. All code required by the custom model must be in a custom model hook—the custom model can't access any code provided outside a defined custom model hook. In addition, you can't modify the input arguments of these hooks as they are predefined.

| Hook (Function) | Unstructured/Structured | Purpose |
| --- | --- | --- |
| init() | Both | Initialize the model run by loading model libraries and reading model files. This hook is executed only once at the beginning of a run. |
| load_model() | Both | Load all supported and trained objects from multiple artifacts, or load a trained object stored in an artifact with a format not natively supported by DataRobot. This hook is executed only once at the beginning of a run. |
| read_input_data() | Structured | Customize how the model reads data; for example, with encoding and missing value handling. |
| transform() | Structured | Define the logic used by custom transformers and estimators to generate transformed data. |
| score() | Structured | Define the logic used by custom estimators to generate predictions. |
| score_unstructured() | Unstructured | Define the output of a custom estimator and returns predictions on input data. Do not use this hook for transform models. |
| chat() | Structured | Define a text generation custom model's handing of real-time chat completion requests. |
| get_supported_llm_models() | Structured | Define a text generation custom model's response to the OpenAI "List Models" API. |
| post_process() | Structured | Define the post-processing steps applied to the model's predictions. |

> [!NOTE] Custom model hook execution order
> These hooks are executed in the order listed, as each hook represents a step in the custom model lifecycle.

For more information on defining a custom model's code, see the hooks for [structured custom models](https://docs.datarobot.com/en/docs/api/code-first-tools/drum/structured-custom-models.html) or [unstructured custom models](https://docs.datarobot.com/en/docs/api/code-first-tools/drum/unstructured-custom-models.html).

### Model metadata

To define a custom model's [metadata and input validation schema](https://docs.datarobot.com/en/docs/api/code-first-tools/drum/custom-model-metadata.html), create a `model-metadata.yaml` file and add it to the top level of the model/model directory. The file specifies additional information about a custom model, including [runtime parameters](https://docs.datarobot.com/en/docs/api/code-first-tools/drum/custom-model-runtime-parameters.html) through `runtimeParameterDefinitions`.

## Model environment

There are multiple options for defining the environment where a custom model runs. You can:

- Choose from a variety ofdrop-in environments.
- Modify a drop-in environment to include missing Python or R packages by specifying the packages in the model'srequirements.txtfile. If provided, therequirements.txtfile must be uploaded together with thecustom.pyorcustom.Rfile in the model content. If model content contains subfolders, it must be placed in the top folder.
- Build acustom environmentif you need to install Linux packages. When creating a custom model with a custom environment, the environment used must be compatible with the model contents, as it defines the model's runtime environment. To ensure you follow the compatibility guidelines:
- By default, when creating a model version, if the selected execution environment does not change, the version of that execution environment persists from the previous custom model version, even if a newer environment version is available. For more information on how to ensure the custom model version uses the latest version of the execution environment, seeTrigger base execution environment update.