Intro Tutorial

Caffe2 Concepts

Below you can learn more about the main concepts of Caffe2 that are crucial for understanding and developing Caffe2 models.

Blobs and Workspace, Tensors

Data in Caffe2 is organized as blobs. A blob is just a named chunk of data in memory. Most blobs contain a tensor (think multidimensional array), and in Python they are translated to numpy arrays (numpy is a popular numerical library for Python and is already installed as a prerequisite with Caffe2).

A Workspace stores all the blobs. The following example shows how to feed blobs into a workspace and fetch them again. Workspaces initialize themselves the moment you start using them.

  1. from caffe2.python import workspace, model_helper
  2. import numpy as np
  3. # Create random tensor of three dimensions
  4. x = np.random.rand(4, 3, 2)
  5. print(x)
  6. print(x.shape)
  7.  
  8. workspace.FeedBlob("my_x", x)
  9.  
  10. x2 = workspace.FetchBlob("my_x")
  11. print(x2)

Nets and Operators

The fundamental model abstraction in Caffe2 is a net (short for network). A net is a graph of operators and each operator takes a set of input blobs and produces one or more output blobs.

In the code block below we will create a super simple model. It will have these components:

  • One fully-connected layer (FC)
  • a Sigmoid activation with a Softmax
  • a CrossEntropy loss

Composing nets directly is quite tedious, so it is better to use model helpers that are Python classes that aid in creating the nets. Even though we call it and pass in a single name “my first net”, ModelHelper will create two interrelated nets:

  • one that initializes the parameters (ref. init_net)
  • one that runs the actual training (ref. exec_net)
  1. # Create the input data
  2. data = np.random.rand(16, 100).astype(np.float32)
  3.  
  4. # Create labels for the data as integers [0, 9].
  5. label = (np.random.rand(16) * 10).astype(np.int32)
  6.  
  7. workspace.FeedBlob("data", data)
  8. workspace.FeedBlob("label", label)
  9.  

We created some random data and random labels and then fed those as blobs into the workspace.

  1. # Create model using a model helper
  2. m = model_helper.ModelHelper(name="my first net")

You’ve now used the model_helper to create the two nets we mentioned earlier (init_net and exec_net). We plan to add a fully connected layer using the FC operator in this model next, but first we need to do prep work by creating randomly filled blobs for weight and bias that the FC op expects. We will reference the weights and bias blobs by name as inputs when we add the FC op.

  1. weight = m.param_init_net.XavierFill([], 'fc_w', shape=[10, 100])
  2. bias = m.param_init_net.ConstantFill([], 'fc_b', shape=[10, ])

In Caffe2 the FC op takes in an input blob (our data), weights, and bias. Weights and bias using either XavierFill or ConstantFill will both take an empty array, name, and shape (as shape=[output, input]).

  1. fc_1 = m.net.FC(["data", "fc_w", "fc_b"], "fc1")
  2. pred = m.net.Sigmoid(fc_1, "pred")
  3. softmax, loss = m.net.SoftmaxWithLoss([pred, "label"], ["softmax", "loss"])

Reviewing the code blocks above:

First, we created the input data and label blobs in memory (in practice, you would be loading data from a input data source such as database). Note that the data and label blobs have first dimension ‘16’; this is because the input to the model is a mini batch of 16 samples at a time. Many Caffe2 operators can be accessed directly through ModelHelper and can handle a mini batch of input at a time.

Second, we create a model by defining a bunch of operators: FC, Sigmoid and SoftmaxWithLoss. Note: at this point, the operators are not executed, you are just creating the definition of the model.

Model helper will create two nets: m.param_init_net which is a net you run only once. It will initialize all the parameter blobs such as weights for the FC layer. The actual training is done by executing m.net. This is transparent to you and happens automatically.

The net definition is stored in a protobuf structure (see Google’s Protocol Buffer documentation to learn more). You can easily inspect it by calling net.Proto():

  1. print(m.net.Proto())

The output should look like:

  1. name: "my first net"
  2. op {
  3.   input: "data"
  4.   input: "fc_w"
  5.   input: "fc_b"
  6.   output: "fc1"
  7.   name: ""
  8.   type: "FC"
  9. }
  10. op {
  11.   input: "fc1"
  12.   output: "pred"
  13.   name: ""
  14.   type: "Sigmoid"
  15. }
  16. op {
  17.   input: "pred"
  18.   input: "label"
  19.   output: "softmax"
  20.   output: "loss"
  21.   name: ""
  22.   type: "SoftmaxWithLoss"
  23. }
  24. external_input: "data"
  25. external_input: "fc_w"
  26. external_input: "fc_b"
  27. external_input: "label"

You also should have a look at the param initialization net:

  1. print(m.param_init_net.Proto())

You can see how there are two operators that create random fill for the weight and bias blobs of the FC operator.

This is the primary idea of Caffe2 API: use Python to conveniently compose nets to train your model, pass those nets to C++ code as serialized protobuffers, and then let the C++ code run the nets with full performance.

Executing

Now when we have the model training operators defined, we can start to run it to train our model.

First, we run only once the param initialization:

  1. workspace.RunNetOnce(m.param_init_net)

Note, as usual, this will actually pass the protobuffer of the param_init_net down to the C++ runtime for execution.

Then we create the actual training Net:

  1. workspace.CreateNet(m.net)

We create it once and then we can efficiently run it multiple times:

  1. # Run 100 x 10 iterations
  2. for _ in range(100):
  3.     data = np.random.rand(16, 100).astype(np.float32)
  4.     label = (np.random.rand(16) * 10).astype(np.int32)
  5.  
  6.     workspace.FeedBlob("data", data)
  7.     workspace.FeedBlob("label", label)
  8.  
  9.     workspace.RunNet(m.name, 10)   # run for 10 times

Note how we just pass m.name and not the net definition itself to RunNet(). Since the net was created inside workspace, we don’t need to pass the definition again.

After execution, you can inspect the results stored in the output blobs (that contain tensors i.e numpy arrays):

  1. print(workspace.FetchBlob("softmax"))
  2. print(workspace.FetchBlob("loss"))

Backward pass

This net only contains the forward pass, thus it is not learning anything. The backward pass is created by adding the gradient operators for each operator in the forward pass.

If you want to try this, add the following steps and examine the results!

Insert before you call RunNetOnce():

  1. m.AddGradientOperators([loss])

Examine the protobuf output:

  1. print(m.net.Proto())

This concludes the overview, but there’s a lot more to be found in the tutorials.