Packaging models

FLM file structure

The structure of an FLM file is thought to be as simple as possible, and aims at keeping in a single file all the information needed to load and use the model. The structure of an FLM file is as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
├── model.flm
│   └── model
│       ├── model (python object)
│       └── meta
│           ├── id
│           ├── timestamp
│           ├── framework
│           ├── model
│           │   ├── obj
│           │   ├── info
│           │   ├── params
│           │   └── metrics
│           └── extra
└── artifacts
    ├── foo.json
    └── bar.csv

Dump method

Flama dump method uses optimal compression with the aim of making the packing process more efficient, and faster. The packing step can live completely out of any Flama application. Indeed, the natural place to package your models will be at the model-building stage, which will be very likely happening on your Jupyter notebook. An example of usage of this method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import flama

flama.dump(
    model,
    "path/to/file.flm",
    model_id=uuid.uuid4(),
    compression="high",
    timestamp=datetime.datetime(2023, 3, 10, 11, 30, 0),
    params={"optimizer": "adams"},
    metrics={"recall": "0.95"},
    extra={
        "model_version": "1.0.0",
        "model_description": "This is a test model",
        "model_author": "John Doe",
        "model_license": "MIT",
        "tags": ["test", "example"],
    },
    artifacts={"foo.json": "path/to/artifact.json"},
)

The first two parameters are the model object itself, and the path where the resulting file will be stored. The remaining parameters are optional, and are used to add metadata to the resulting file which might be quite useful for model management purposes:

• model_id: a unique identifier for the model. If not provided, a random UUID will be generated.
• compression: the compression level to be used. It can be one of the following: "fast", "standard", or "high". The default value is "standard".
• timestamp: the timestamp of the model. If not provided, the current timestamp will be used.
• params: a dictionary containing hyper-parameters used to train the model.
• metrics: a dictionary containing metrics of the model, e.g. accuracy, recall, precision, etc.
• extra: a dictionary containing any other metadata you might want to add to the model. This is a good place to add information about model version, description, author, license, tags, etc.
• artifacts: a dictionary containing any artifacts associated with the model. The keys are the names of the artifacts, and the values are the paths to the files containing the artifacts. These files will be automatically packed and unpacked when the model is loaded.

Load method

Flama load method is responsible for the efficient unpacking of the model file. The unpacking stage will typically happen within the context of a Flama application. If you're not planning the development of any because you'll be using Flama CLI for this, then you won't have to use the load methods at all. An example of usage of this method:

1
2
3
import flama

model_artifact = flama.load("path/to/file.flm")

The only parameter is the path to the file containing the model. The method returns a ModelArtifact object, which contains the attributes used with the dump method, plus the model itself. The model can be accessed through the model attribute of the ModelArtifact object. As you can easily check, this object contains the artifacts dictionary, which you can inspect to find the path where the artifacts were unpacked automatically. This is a very convenient feature, which allows you to keep track of the artifacts associated with your model, and access them easily, all within the same binary file.

Once we have introduced the methods which allow for packing (flama.dump) and loading (flama.load), we can proceed and introduce how the example files we've been using so far were generated. These files were:

• Scikit Learn model
• TensorFlow model
• PyTorch model

Scikit-Learn

1
2
3
4
5
6
7
8
9
10
import flama
from sklearn.neural_network import MLPClassifier

model = MLPClassifier(activation="tanh", max_iter=2000, hidden_layer_sizes=(10,))
model.fit(
    np.array([[0, 0], [0, 1], [1, 0], [1, 1]]),
    np.array([0, 1, 1, 0]),
)

flama.dump(model, "sklearn_model.flm")

TensorFlow

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import flama
import tensorflow as tf

model = tf.keras.models.Sequential(
    [
        tf.keras.layers.Flatten(input_shape=(2,)),
        tf.keras.layers.Dense(10, activation="tanh"),
        tf.keras.layers.Dense(1, activation="sigmoid"),
    ]
)

model.compile(optimizer="adam", loss="mse")
model.fit(
    np.array([[0, 0], [0, 1], [1, 0], [1, 1]]),
    np.array([[0], [1], [1], [0]]),
    epochs=2000,
    verbose=0,
)

flama.dump(model, "tensorflow_model.flm")

PyTorch

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
import flama
import torch

class Model(torch.nn.Module):
    def __init__(self):
        super().__init__()
        self.l1 = torch.nn.Linear(2, 10)
        self.l2 = torch.nn.Linear(10, 1)

    def forward(self, x):
        x = torch.tanh(self.l1(x))
        x = torch.sigmoid(self.l2(x))
        return x

    def _train(self, X, Y, loss, optimizer):
        for m in self.modules():
            if isinstance(m, torch.nn.Linear):
                m.weight.data.normal_(0, 1)

        steps = X.size(0)
        for i in range(2000):
            for j in range(steps):
                data_point = np.random.randint(steps)
                x_var = torch.autograd.Variable(X[data_point], requires_grad=False)
                y_var = torch.autograd.Variable(Y[data_point], requires_grad=False)

                optimizer.zero_grad()
                y_hat = model(x_var)
                loss_result = loss.forward(y_hat, y_var)
                loss_result.backward()
                optimizer.step()

        return self


X = torch.Tensor([[0, 0], [0, 1], [1, 0], [1, 1]])
Y = torch.Tensor([0, 1, 1, 0]).view(-1, 1)
model = Model()
model._train(X, Y, loss=torch.nn.BCELoss(), optimizer=torch.optim.Adam(model.parameters()))

flama.dump(model, "pytorch_model.flm")