.PB File Format

Introduction

This file holds one ONNX value that is not a plain tensor: a sequence, a list of values of one kind, or an optional value, which may be absent. It is one SequenceProto or OptionalProto message from the schema onnx-data.proto of ONNX, the open format for neural networks, stored as a Protocol Buffers message with no header around it.

Such files come from ONNX’s test data: models whose inputs or outputs are sequences or optional values have input_0.pb and output_0.pb files of this kind beside them, where other tests have plain tensor files. The elements are usually tensors.

The two messages share their field numbers and types; only whether the value fields are repeated differs. With one element their bytes are the same, so one file can be either, and this site treats them as one format. Later ONNX versions have only added to them. A .pb file dropped on any page of this site opens in the explorer, which shows the value’s name and element type, lists the elements, and shows the first tensor’s values, as a picture when its shape looks like an image.

Structure

The file is one SequenceProto or OptionalProto:

A file from ONNX’s test data, a sequence of tensors:

An empty optional value from the test data is the whole of these 18 bytes:

0A 0E 6F 70 74 69 6F 6E 61 6C 5F 69 6E 70 75 74 10 00

ONNX’s schema is proto2, so elem_type is written even though it holds 0. In the files examined for this site, most of these values were sequences of tensors, a few were sequences of sequences, and some were empty.

Telling it apart

The file has no signature. The explorer takes it as Protocol Buffers when the name ends .pb, .binpb or .onnx, the first field reads cleanly and the first 512 bytes are not all printable text. It tries the ONNX tensor parser first; when that turns the file down, the parser for this format checks:

• every field number is one of SequenceProto’s (1 to 7), each with the wire type its type is stored with;
• elem_type is present and from 0 to 5;
• values appear only in the field that matches it: TENSOR in field 3, SPARSE_TENSOR in 4, SEQUENCE in 5, MAP in 6, OPTIONAL in 7;
• the nested tensors pass the same checks as an ONNX tensor: a valid data type and values whose size fits the shape;
• strings declared string are valid UTF-8 (checked up to 4 KB).

It then says which message the file is. With two or more elements it can only be a SequenceProto. With one element, or none, the bytes are the same for both, and the explorer says “SequenceProto or OptionalProto”. Only the type that the model declares for that input or output says which it is meant to be.

The field numbers come from onnx 1.23. A later version of the schema that adds a field is still this format, but the parser turns such a file down until it learns the field, and the file is then shown as a message without a schema.

Variants

• ONNX tensor (TensorProto) – one tensor, as in ONNX’s test data
• ONNX sequence or optional value – a list of tensors, or a value that may be absent
• ONNX model (ModelProto) – a whole model: graph, operators and weights
• TensorFlow SavedModel (saved_model.pb) – meta graphs, signatures and functions
• TensorFlow GraphDef (frozen graph) – nodes, with the weights as constants
• Protocol Buffers message – any message, read without its schema

Links