skip to content

How does an mlflow.pyfunc.PythonModel package a scikit-learn pipeline with custom pre-filter code, and how does it find the pipeline file when loaded?

level: middleimportance: should knowfreq 14%

answer

  1. subclass, then two methods
  2. load once, predict many
  3. a name-to-file dictionary
  4. copied into the model directory
  5. context.artifacts gives local paths

basics

~20 s

Subclass mlflow.pyfunc.PythonModel: load_context loads the pipeline once, predict applies the keyword rules and calls it. Log with artifacts={"pipeline": path}; MLflow copies the file into the model, and context.artifacts maps each name to its local path.

solid answer

~40 s

You write a class that subclasses `mlflow.pyfunc.PythonModel`. `load_context(self, context)` runs once, when `mlflow.pyfunc.load_model` builds the model, and is where the pipeline is loaded. `predict(self, context, model_input, params=None)` runs on every call: it applies the keyword pre-filter and sends the remaining tickets to the pipeline. Since MLflow 2.20 `context` may be dropped from `predict` if unused. You log it with `mlflow.pyfunc.log_model(name=..., python_model=..., artifacts={"pipeline": "pipeline_dir"}, input_example=...)`. MLflow copies each artifact into the model directory at log time, and at load time `context.artifacts["pipeline"]` is the absolute local path of that copy, so nothing reaches back to the notebook's disk. `python_model` can be the class instance, which is cloudpickled, or the path of a script that calls `mlflow.models.set_model`, which is stored as code.

code

python · 23 lines
python
# router_model.py -- logged with mlflow.pyfunc.log_model(
#     name="ticket-router", python_model="router_model.py",
#     artifacts={"pipeline": "pipeline_dir"}, input_example=sample)
import mlflow
import numpy as np
from mlflow.models import set_model

BILLING_WORDS = "refund|invoice|chargeback"


class TicketRouter(mlflow.pyfunc.PythonModel):
    def load_context(self, context):
        # absolute path of the copy stored inside the model directory
        self.pipeline = mlflow.sklearn.load_model(context.artifacts["pipeline"])

    def predict(self, context, model_input, params=None):
        text = (model_input["subject"] + " " + model_input["body"]).str.lower()
        is_billing = text.str.contains(BILLING_WORDS).to_numpy()
        routed = self.pipeline.predict(model_input)
        return np.where(is_billing, "billing", routed).tolist()


set_model(TicketRouter())

go deeper

for a junior

Recall the two methods of a PythonModel, what each one is for, and that files the model needs are passed through an artifacts dictionary.

for a middle

Explain the artifact lifecycle from log to load, why load_context runs once, and what python_model accepts: an instance or a script path ending in set_model.

for a senior

Show the production details: a signature from an input example, extra_pip_requirements and code_paths for what inference misses, no credentials in the script, consistent output types.

for a principal

Weigh one custom wrapper per model against shared wrapper libraries, and decide how much business logic belongs inside a logged model rather than in the calling service.

## Why a custom model Built-in flavors cover a model that one library produced. The support-ticket router is more than that: a scikit-learn text pipeline, plus a keyword pre-filter written in plain Python that sends anything mentioning a refund or an invoice straight to the billing queue. `mlflow.pyfunc.PythonModel` is MLflow's extension point for exactly this: your own prediction logic, packaged in the standard `python_function` format so that every generic loader and the scoring server can use it. ## The PythonModel contract A subclass implements up to three methods: - **`load_context(self, context)`** — optional. Called once, as soon as `mlflow.pyfunc.load_model` constructs the model. Put expensive work here: loading the pipeline, reading a vocabulary file. - **`predict(self, context, model_input, params=None)`** — required. Called for every prediction. `model_input` is usually a pandas DataFrame; `params` carries inference-time parameters declared in the signature. Since MLflow 2.20 the `context` argument may be omitted when unused. - **`predict_stream(...)`** — optional, for models that yield results incrementally. The `context` object is a `PythonModelContext` with two properties: `artifacts` and `model_config`. ## Artifacts: how files travel with the model The pipeline is a file (or a directory) the custom code needs at load time. You declare it in the `artifacts` dictionary when logging, and MLflow handles the move: 1. At log time, each entry `{"pipeline": "<path or URI>"}` is resolved; remote URIs are downloaded. 2. The files are copied into an `artifacts/` subdirectory of the model directory, and the mapping is recorded in the `python_function` flavor entry in `MLmodel`. 3. At load time, MLflow rebuilds the dictionary with **absolute local paths** inside the downloaded model directory and passes it as `context.artifacts`. 4. `load_context` opens the path — for a pipeline saved with `mlflow.sklearn.save_model`, by calling `mlflow.sklearn.load_model(context.artifacts["pipeline"])`. Because the copy is part of the model, the platform team's environment never needs access to the data scientist's disk or bucket. ## Logging it: an instance or a file | `python_model=` | How it is stored | Notes | |---|---|---| | an instance, `TicketRouter()` | serialized with cloudpickle as `python_model.pkl` | MLflow 3.16 logs a warning recommending a file path | | a path, `"router_model.py"` | the script is copied into the model as code | the script must end with `set_model(TicketRouter())`; it is executed once at log time to validate it | The file form is called **models-from-code**. It keeps the wrapper readable and avoids cloudpickle, at the price of the script having to import everything it needs at its top level. ## Signature and dependencies for a custom model A custom model gets a signature in one of three ways. With `input_example`, MLflow calls `load_context` and then `predict` on the example and infers the schema from both. A `predict` annotated with supported type hints yields one from the hints. And an explicit `signature=` always works. Without any of the three it has none, and pyfunc will not check inputs. Dependencies are inferred by loading the model in a subprocess and recording which packages it imports. A package imported only on a rare code path can be missed, so add it with `extra_pip_requirements`. A local helper module that is not pip-installable goes in `code_paths`, which copies it into the model and puts it on `sys.path` before loading. ## Testing the wrapper before handing it over A wrapper that works inside the notebook can still fail once it is loaded from its own directory, so test the logged copy, not the class: 1. Load it back with `mlflow.pyfunc.load_model(model_info.model_uri)`; this runs `load_context` against the copied artifacts, exactly as a consumer would. 2. Call `predict` on a handful of real tickets, including ones the keyword rules should catch and ones they should not. 3. For debugging, `unwrap_python_model()` on the loaded model returns the `TicketRouter` instance itself, so you can inspect `self.pipeline` directly. A clean environment is a separate question, answered by scoring the model in an environment built from its own dependency files. ## Pitfalls - Loading the pipeline inside `predict` instead of `load_context` reloads it on every request. - Hard-coding a notebook path such as `/home/ds/pipeline` instead of reading `context.artifacts` works on the author's machine only. - Returning a different type from `predict` for the keyword-routed rows than for the pipeline rows breaks any consumer that expects one column of labels. - Putting a credential in a models-from-code script stores it in plain text inside the model; read it from an environment variable instead.

  • The pre-filter should be tunable per request, for example a min_confidence threshold. How do you expose it?
    Read it from `params` in `predict` and declare it in the signature, for example with `infer_signature(sample, output, params={"min_confidence": 0.6})`. Pyfunc then fills the default when a caller omits it, type-checks it when one is sent, and drops any parameter the schema does not name, with a warning.
  • The keyword list lives in a helper module, router_rules.py, next to the script. What breaks, and how do you fix it?
    Requirement inference records pip packages, not local files, so loading elsewhere fails with an import error. Pass `code_paths=["router_rules.py"]` to `log_model`; MLflow copies the file into the model and puts it on `sys.path` before loading. The docs recommend keeping a models-from-code model's local dependencies in the one script where possible.

  • load_context runs before every predict call, so it is no place for heavy loading.
  • context.artifacts holds the loaded Python objects rather than file paths.
  • Artifacts stay at their original location and are read from there at load time.
  • A PythonModel instance passed to log_model is stored as readable source code.
  • Local helper modules are captured automatically with the inferred pip requirements.