Model Configuration#

Is this your first time writing a config file? Check out this guide or this example!

Each model in a model repository must include a model configuration that provides required and optional information about the model. Typically, this configuration is provided in a config.pbtxt file specified as ModelConfig protobuf. In some cases, discussed in Auto-Generated Model Configuration, the model configuration can be generated automatically by Triton and so does not need to be provided explicitly.

This section describes the most important model configuration properties but the documentation in the ModelConfig protobuf should also be consulted.

Minimal Model Configuration#

A minimal model configuration must specify the platform and/or backend properties, the max_batch_size property, and the input and output tensors of the model.

As an example consider a TensorRT model that has two inputs, input0 and input1, and one output, output0, all of which are 16 entry float32 tensors. The minimal configuration is:

  platform: "tensorrt_plan"
  max_batch_size: 8
  input [
    {
      name: "input0"
      data_type: TYPE_FP32
      dims: [ 16 ]
    },
    {
      name: "input1"
      data_type: TYPE_FP32
      dims: [ 16 ]
    }
  ]
  output [
    {
      name: "output0"
      data_type: TYPE_FP32
      dims: [ 16 ]
    }
  ]

Name, Platform and Backend#

The model configuration name property is optional. If the name of the model is not specified in the configuration it is assumed to be the same as the model repository directory containing the model. If name is specified it must match the name of the model repository directory containing the model. The required values for platform and backend are described in the backend documentation.

Model Transaction Policy#

The model_transaction_policy property describes the nature of transactions expected from the model.

Decoupled#

This boolean setting indicates whether responses generated by the model are decoupled with the requests issued to it. Using decoupled means the number of responses generated by the model may differ from number of requests issued, and the responses may be out of order relative to the order of requests. The default is false, which means the model will generate exactly one response for each request.

Maximum Batch Size#

The max_batch_size property indicates the maximum batch size that the model supports for the types of batching that can be exploited by Triton. If the model’s batch dimension is the first dimension, and all inputs and outputs to the model have this batch dimension, then Triton can use its dynamic batcher or sequence batcher to automatically use batching with the model. In this case max_batch_size should be set to a value greater-or-equal-to 1 that indicates the maximum batch size that Triton should use with the model.

For models that do not support batching, or do not support batching in the specific ways described above, max_batch_size must be set to zero.

Inputs and Outputs#

Each model input and output must specify a name, datatype, and shape. The name specified for an input or output tensor must match the name expected by the model.

Special Conventions for PyTorch Backend#

Naming Convention:

Due to the absence of sufficient metadata for inputs/outputs in TorchScript model files, the “name” attribute of inputs/outputs in the configuration must follow specific naming conventions. These are detailed below.

[Only for Inputs] When the input is not a Dictionary of Tensors, the input names in the configuration file should mirror the names of the input arguments to the forward function in the model’s definition.

For example, if the forward function for the Torchscript model was defined as forward(self, input0, input1), the first and second inputs should be named “input0” and “input1” respectively.

<name>__<index>: Where <name> can be any string and <index> is an integer index that refers to the position of the corresponding input/output.

This means that if there are two inputs and two outputs, the first and second inputs can be named “INPUT__0” and “INPUT__1” and the first and second outputs can be named “OUTPUT__0” and “OUTPUT__1” respectively.

If all inputs (or outputs) do not follow the same naming convention, then we enforce strict ordering from the model configuration i.e. we assume the order of inputs (or outputs) in the configuration is the true ordering of these inputs.

Dictionary of Tensors as Input:

The PyTorch backend supports passing of inputs to the model in the form of a Dictionary of Tensors. This is only supported when there is a single input to the model of type Dictionary that contains a mapping of string to tensor. As an example, if there is a model that expects the input of the form:

{'A': tensor1, 'B': tensor2}

The input names in the configuration in this case must not follow the above naming conventions <name>__<index>. Instead, the names of the inputs in this case must map to the string value ‘key’ for that specific tensor. For this case, the inputs would be “A” and “B”, where input “A” refers to value corresponding to tensor1 and “B” refers to the value corresponding to tensor2.

The datatypes allowed for input and output tensors varies based on the type of the model. Section Datatypes describes the allowed datatypes and how they map to the datatypes of each model type.

An input shape indicates the shape of an input tensor expected by the model and by Triton in inference requests. An output shape indicates the shape of an output tensor produced by the model and returned by Triton in response to an inference request. Both input and output shape must have rank greater-or-equal-to 1, that is, the empty shape [ ] is not allowed.

Input and output shapes are specified by a combination of max_batch_size and the dimensions specified by the input or output dims property. For models with max_batch_size greater-than 0, the full shape is formed as [ -1 ] + dims. For models with max_batch_size equal to 0, the full shape is formed as dims. For example, for the following configuration the shape of “input0” is [ -1, 16 ] and the shape of “output0” is [ -1, 4 ].

  platform: "tensorrt_plan"
  max_batch_size: 8
  input [
    {
      name: "input0"
      data_type: TYPE_FP32
      dims: [ 16 ]
    }
  ]
  output [
    {
      name: "output0"
      data_type: TYPE_FP32
      dims: [ 4 ]
    }
  ]

For a configuration that is identical except that max_batch_size equal to 0, the shape of “input0” is [ 16 ] and the shape of “output0” is [ 4 ].

  platform: "tensorrt_plan"
  max_batch_size: 0
  input [
    {
      name: "input0"
      data_type: TYPE_FP32
      dims: [ 16 ]
    }
  ]
  output [
    {
      name: "output0"
      data_type: TYPE_FP32
      dims: [ 4 ]
    }
  ]

For models that support input and output tensors with variable-size dimensions, those dimensions can be listed as -1 in the input and output configuration. For example, if a model requires a 2-dimensional input tensor where the first dimension must be size 4 but the second dimension can be any size, the model configuration for that input would include dims: [ 4, -1 ]. Triton would then accept inference requests where that input tensor’s second dimension was any value greater-or-equal-to 0. The model configuration can be more restrictive than what is allowed by the underlying model. For example, even though the framework model itself allows the second dimension to be any size, the model configuration could be specified as dims: [ 4, 4 ]. In this case, Triton would only accept inference requests where the input tensor’s shape was exactly [ 4, 4 ].

The reshape property must be used if there is a mismatch between the input shape that Triton receives in an inference request and the input shape expected by the model. Similarly, the reshape property must be used if there is a mismatch between the output shape produced by the model and the shape that Triton returns in a response to an inference request.

Model inputs can specify allow_ragged_batch to indicate that the input is a ragged input. The field is used with dynamic batcher to allow batching without enforcing the input to have the same shape in all requests.

Auto-Generated Model Configuration#

The model configuration file containing the required settings must be available with each model to be deployed on Triton. In some cases the required portions of the model configuration can be generated automatically by Triton. The required portion of the model configuration are the settings shown in the Minimal Model Configuration. By default, Triton will try to complete these sections. However, by starting Triton with --disable-auto-complete-config option, Triton can be configured to not auto-complete model configuration on the backend side. However, even with this option Triton will fill in missing instance_group settings with default values.

Triton can derive all the required settings automatically for most of the TensorRT, TensorFlow saved-model, ONNX models, and OpenVINO models. For Python models, auto_complete_config function can be implemented in Python backend to provide max_batch_size, input and output properties using set_max_batch_size, add_input, and add_output functions. These properties will allow Triton to load the Python model with Minimal Model Configuration in absence of a configuration file. All other model types must provide a model configuration file.

When developing a custom backend, you can populate required settings in the configuration and call TRITONBACKEND_ModelSetConfig API to update completed configuration with Triton core. You can take a look at TensorFlow and Onnxruntime backends as examples of how to achieve this. Currently, only inputs, outputs, max_batch_size and dynamic batching settings can be populated by backend. For custom backends, your config.pbtxt file must include a backend field or your model name must be in the form <model_name>.<backend_name>.

You can also see the model configuration generated for a model by Triton using the model configuration endpoint. The easiest way to do this is to use a utility like curl:

$ curl localhost:8000/v2/models/<model name>/config

This will return a JSON representation of the generated model configuration. From this you can take the max_batch_size, inputs, and outputs sections of the JSON and convert it to a config.pbtxt file. Triton only generates the minimal portion of the model configuration. You must still provide the optional portions of the model configuration by editing the config.pbtxt file.

Default Max Batch Size and Dynamic Batcher#

When a model is using the auto-complete feature, a default maximum batch size may be set by using the --backend-config=default-max-batch-size=<int> command line argument. This allows all models which are capable of batching and which make use of Auto Generated Model Configuration to have a default maximum batch size. This value is set to 4 by default. Backend developers may make use of this default-max-batch-size by obtaining it from the TRITONBACKEND_BackendConfig api. Currently, the following backends which utilize these default batch values and turn on dynamic batching in their generated model configurations are:

TensorFlow backend
Onnxruntime backend
TensorRT backend
1. TensorRT models store the maximum batch size explicitly and do not make use of the default-max-batch-size parameter. However, if max_batch_size > 1 and no scheduler is provided, the dynamic batch scheduler will be enabled.

If a value greater than 1 for the maximum batch size is set for the model, the dynamic_batching config will be set if no scheduler is provided in the configuration file.

Datatypes#

The following table shows the tensor datatypes supported by Triton. The first column shows the name of the datatype as it appears in the model configuration file. The next four columns show the corresponding datatype for supported model frameworks. If a model framework does not have an entry for a given datatype, then Triton does not support that datatype for that model. The sixth column, labeled “API”, shows the corresponding datatype for the TRITONSERVER C API, TRITONBACKEND C API, HTTP/REST protocol and GRPC protocol. The last column shows the corresponding datatype for the Python numpy library.

Model Config	TensorRT	TensorFlow	ONNX Runtime	PyTorch	API	NumPy
TYPE_BOOL	kBOOL	DT_BOOL	BOOL	kBool	BOOL	bool
TYPE_UINT8	kUINT8	DT_UINT8	UINT8	kByte	UINT8	uint8
TYPE_UINT16		DT_UINT16	UINT16		UINT16	uint16
TYPE_UINT32		DT_UINT32	UINT32		UINT32	uint32
TYPE_UINT64		DT_UINT64	UINT64		UINT64	uint64
TYPE_INT8	kINT8	DT_INT8	INT8	kChar	INT8	int8
TYPE_INT16		DT_INT16	INT16	kShort	INT16	int16
TYPE_INT32	kINT32	DT_INT32	INT32	kInt	INT32	int32
TYPE_INT64		DT_INT64	INT64	kLong	INT64	int64
TYPE_FP16	kHALF	DT_HALF	FLOAT16		FP16	float16
TYPE_FP32	kFLOAT	DT_FLOAT	FLOAT	kFloat	FP32	float32
TYPE_FP64		DT_DOUBLE	DOUBLE	kDouble	FP64	float64
TYPE_STRING		DT_STRING	STRING		BYTES	dtype(object)
TYPE_BF16					BF16

For TensorRT each value is in the nvinfer1::DataType namespace. For example, nvinfer1::DataType::kFLOAT is the 32-bit floating-point datatype.

For TensorFlow each value is in the tensorflow namespace. For example, tensorflow::DT_FLOAT is the 32-bit floating-point value.

For ONNX Runtime each value is prepended with ONNX_TENSOR_ELEMENT_DATA_TYPE_. For example, ONNX_TENSOR_ELEMENT_DATA_TYPE_FLOAT is the 32-bit floating-point datatype.

For PyTorch each value is in the torch namespace. For example, torch::kFloat is the 32-bit floating-point datatype.

For Numpy each value is in the numpy module. For example, numpy.float32 is the 32-bit floating-point datatype.

Reshape#

The ModelTensorReshape property on a model configuration input or output is used to indicate that the input or output shape accepted by the inference API differs from the input or output shape expected or produced by the underlying framework model or custom backend.

For an input, reshape can be used to reshape the input tensor to a different shape expected by the framework or backend. A common use-case is where a model that supports batching expects a batched input to have shape [ batch-size ], which means that the batch dimension fully describes the shape. For the inference API the equivalent shape [ batch-size, 1 ] must be specified since each input must specify a non-empty dims. For this case the input should be specified as:

  input [
    {
      name: "in"
      dims: [ 1 ]
      reshape: { shape: [ ] }
    }

For an output, reshape can be used to reshape the output tensor produced by the framework or backend to a different shape that is returned by the inference API. A common use-case is where a model that supports batching expects a batched output to have shape [ batch-size ], which means that the batch dimension fully describes the shape. For the inference API the equivalent shape [ batch-size, 1 ] must be specified since each output must specify a non-empty dims. For this case the output should be specified as:

  output [
    {
      name: "in"
      dims: [ 1 ]
      reshape: { shape: [ ] }
    }

Shape Tensors#

For models that support shape tensors, the is_shape_tensor property must be set appropriately for inputs and outputs that are acting as shape tensors. The following shows an example configuration that specifies shape tensors.

  name: "myshapetensormodel"
  platform: "tensorrt_plan"
  max_batch_size: 8
  input [
    {
      name: "input0"
      data_type: TYPE_FP32
      dims: [ 1 , 3]
    },
    {
      name: "input1"
      data_type: TYPE_INT32
      dims: [ 2 ]
      is_shape_tensor: true
    }
  ]
  output [
    {
      name: "output0"
      data_type: TYPE_FP32
      dims: [ 1 , 3]
    }
  ]

As discussed above, Triton assumes that batching occurs along the first dimension which is not listed in in the input or output tensor dims. However, for shape tensors, batching occurs at the first shape value. For the above example, an inference request must provide inputs with the following shapes.

  "input0": [ x, 1, 3]
  "input1": [ 3 ]
  "output0": [ x, 1, 3]

Where x is the batch size of the request. Triton requires the shape tensors to be marked as shape tensors in the model when using batching. Note that “input1” has shape [ 3 ] and not [ 2 ], which is how it is described in model configuration. As myshapetensormodel model is a batching model, the batch size should be provided as an additional value. Triton will accumulate all the shape values together for “input1” in batch dimension before issuing the request to model.

For example, assume the client sends following three requests to Triton with following inputs:

Request1:
input0: [[[1,2,3]]] <== shape of this tensor [1,1,3]
input1: [1,4,6] <== shape of this tensor [3]

Request2:
input0: [[[4,5,6]], [[7,8,9]]] <== shape of this tensor [2,1,3]
input1: [2,4,6] <== shape of this tensor [3]

Request3:
input0: [[[10,11,12]]] <== shape of this tensor [1,1,3]
input1: [1,4,6] <== shape of this tensor [3]

Assuming these requests get batched together would be delivered to the model as:

Batched Requests to model:
input0: [[[1,2,3]], [[4,5,6]], [[7,8,9]], [[10,11,12]]] <== shape of this tensor [4,1,3]
input1: [4, 4, 6] <== shape of this tensor [3]

Currently, only TensorRT supports shape tensors. Read Shape Tensor I/O to learn more about shape tensors.

Version Policy#

Each model can have one or more versions. The ModelVersionPolicy property of the model configuration is used to set one of the following policies.

All: All versions of the model that are available in the model repository are available for inferencing. version_policy: { all: {}}
Latest: Only the latest ‘n’ versions of the model in the repository are available for inferencing. The latest versions of the model are the numerically greatest version numbers. version_policy: { latest: { num_versions: 2}}
Specific: Only the specifically listed versions of the model are available for inferencing. version_policy: { specific: { versions: [1,3]}}

If no version policy is specified, then Latest (with n=1) is used as the default, indicating that only the most recent version of the model is made available by Triton. In all cases, the addition or removal of version subdirectories from the model repository can change which model version is used on subsequent inference requests.

The following configuration specifies that all versions of the model will be available from the server.

  platform: "tensorrt_plan"
  max_batch_size: 8
  input [
    {
      name: "input0"
      data_type: TYPE_FP32
      dims: [ 16 ]
    },
    {
      name: "input1"
      data_type: TYPE_FP32
      dims: [ 16 ]
    }
  ]
  output [
    {
      name: "output0"
      data_type: TYPE_FP32
      dims: [ 16 ]
    }
  ]
  version_policy: { all { }}

Instance Groups#

Triton can provide multiple instances of a model so that multiple inference requests for that model can be handled simultaneously. The model configuration ModelInstanceGroup property is used to specify the number of execution instances that should be made available and what compute resource should be used for those instances.

Multiple Model Instances#

By default, a single execution instance of the model is created for each GPU available in the system. The instance-group setting can be used to place multiple execution instances of a model on every GPU or on only certain GPUs. For example, the following configuration will place two execution instances of the model to be available on each system GPU.

  instance_group [
    {
      count: 2
      kind: KIND_GPU
    }
  ]

And the following configuration will place one execution instance on GPU 0 and two execution instances on GPUs 1 and 2.

  instance_group [
    {
      count: 1
      kind: KIND_GPU
      gpus: [ 0 ]
    },
    {
      count: 2
      kind: KIND_GPU
      gpus: [ 1, 2 ]
    }
  ]

For a more detailed example of using instance groups, see this guide.

CPU Model Instance#

The instance group setting is also used to enable execution of a model on the CPU. A model can be executed on the CPU even if there is a GPU available in the system. The following places two execution instances on the CPU.

  instance_group [
    {
      count: 2
      kind: KIND_CPU
    }
  ]

If no count is specified for a KIND_CPU instance group, then the default instance count will be 2 for selected backends (Tensorflow and Onnxruntime). All other backends will default to 1.

Host Policy#

The instance group setting is associated with a host policy. The following configuration will associate all instances created by the instance group setting with host policy “policy_0”. By default the host policy will be set according to the device kind of the instance, for instance, KIND_CPU is “cpu”, KIND_MODEL is “model”, and KIND_GPU is “gpu_<gpu_id>”.

  instance_group [
    {
      count: 2
      kind: KIND_CPU
      host_policy: "policy_0"
    }
  ]

Rate Limiter Configuration#

Instance group optionally specifies rate limiter configuration which controls how the rate limiter operates on the instances in the group. The rate limiter configuration is ignored if rate limiting is off. If rate limiting is on and if an instance_group does not provide this configuration, then the execution on the model instances belonging to this group will not be limited in any way by the rate limiter. The configuration includes the following specifications:

Resources#

The set of resources required to execute a model instance. The “name” field identifies the resource and “count” field refers to the number of copies of the resource that the model instance in the group requires to run. The “global” field specifies whether the resource is per-device or shared globally across the system. Loaded models can not specify a resource with the same name both as global and non-global. If no resources are provided then triton assumes the execution of model instance does not require any resources and will start executing as soon as model instance is available.

Priority#

Priority serves as a weighting value to be used for prioritizing across all the instances of all the models. An instance with priority 2 will be given 1/2 the number of scheduling chances as an instance with priority 1.

The following example specifies the instances in the group requires four “R1” and two “R2” resources for execution. Resource “R2” is a global resource. Additionally, the rate-limiter priority of the instance_group is 2.

  instance_group [
    {
      count: 1
      kind: KIND_GPU
      gpus: [ 0, 1, 2 ]
      rate_limiter {
        resources [
          {
            name: "R1"
            count: 4
          },
          {
            name: "R2"
            global: True
            count: 2
          }
        ]
        priority: 2
      }
    }
  ]

The above configuration creates 3 model instances, one on each device (0, 1 and 2). The three instances will not contend for “R1” among themselves as “R1” is local for their own device, however, they will contend for “R2” because it is specified as a global resource which means “R2” is shared across the system. Though these instances don’t contend for “R1” among themselves, but they will contend for “R1” with other model instances which includes “R1” in their resource requirements and run on the same device as them.

Ensemble Model Instance Groups#

Ensemble models are an abstraction Triton uses to execute a user-defined pipeline of models. Since there is no physical instance associated with an ensemble model, the instance_group field can not be specified for it.

However, each composing model that makes up an ensemble can specify instance_group in its config file and individually support parallel execution as described above when the ensemble receives multiple requests.

CUDA Compute Capability#

Similar to the default_model_filename field, you can optionally specify the cc_model_filenames field to map the GPU’s CUDA Compute Capability to a corresponding model filename at model load time. This is particularly useful for TensorRT models, since they are generally tied to a specific compute capability.

cc_model_filenames [
  {
    key: "7.5"
    value: "resnet50_T4.plan"
  },
  {
    key: "8.0"
    value: "resnet50_A100.plan"
  }
]

Scheduling And Batching#

Triton supports batch inferencing by allowing individual inference requests to specify a batch of inputs. The inferencing for a batch of inputs is performed at the same time which is especially important for GPUs since it can greatly increase inferencing throughput. In many use cases the individual inference requests are not batched, therefore, they do not benefit from the throughput benefits of batching.

The inference server contains multiple scheduling and batching algorithms that support many different model types and use-cases. More information about model types and schedulers can be found in Models And Schedulers.

Default Scheduler#

The default scheduler is used for a model if none of the scheduling_choice properties are specified in the model configuration. The default scheduler simply distributes inference requests to all model instances configured for the model.

Dynamic Batcher#

Dynamic batching is a feature of Triton that allows inference requests to be combined by the server, so that a batch is created dynamically. Creating a batch of requests typically results in increased throughput. The dynamic batcher should be used for stateless models. The dynamically created batches are distributed to all model instances configured for the model.

Dynamic batching is enabled and configured independently for each model using the ModelDynamicBatching property in the model configuration. These settings control the preferred size(s) of the dynamically created batches, the maximum time that requests can be delayed in the scheduler to allow other requests to join the dynamic batch, and queue properties such a queue size, priorities, and time-outs. Refer to this guide for a more detailed example of dynamic batching.

Recommended Configuration Process#

The individual settings are described in detail below. The following steps are the recommended process for tuning the dynamic batcher for each model. It is also possible to use the Model Analyzer to automatically search across different dynamic batcher configurations.

Decide on a maximum batch size for the model.
Add the following to the model configuration to enable the dynamic batcher with all default settings. By default the dynamic batcher will create batches as large as possible up to the maximum batch size and will not delay when forming batches.

  dynamic_batching { }

Use the Performance Analyzer to determine the latency and throughput provided by the default dynamic batcher configuration.
If the default configuration results in latency values that are within your latency budget, try one or both of the following to trade off increased latency for increased throughput:
- Increase maximum batch size.
- Set batch delay to a non-zero value. Try increasing delay values until the latency budget is exceeded to see the impact on throughput.
Preferred batch sizes should not be used for most models. A preferred batch size(s) should only be configured if that batch size results in significantly higher performance than other batch sizes.

Preferred Batch Sizes#

The preferred_batch_size property indicates the batch sizes that the dynamic batcher should attempt to create. For most models, preferred_batch_size should not be specified, as described in Recommended Configuration Process. An exception is TensorRT models that specify multiple optimization profiles for different batch sizes. In this case, because some optimization profiles may give significant performance improvement compared to others, it may make sense to use preferred_batch_size for the batch sizes supported by those higher-performance optimization profiles.

The following example shows the configuration that enables dynamic batching with preferred batch sizes of 4 and 8.

  dynamic_batching {
    preferred_batch_size: [ 4, 8 ]
  }

When a model instance becomes available for inferencing, the dynamic batcher will attempt to create batches from the requests that are available in the scheduler. Requests are added to the batch in the order the requests were received. If the dynamic batcher can form a batch of a preferred size(s) it will create a batch of the largest possible preferred size and send it for inferencing. If the dynamic batcher cannot form a batch of a preferred size (or if the dynamic batcher is not configured with any preferred batch sizes), it will send a batch of the largest size possible that is less than the maximum batch size allowed by the model (but see the following section for the delay option that changes this behavior).

The size of generated batches can be examined in aggregate using count metrics.

Delayed Batching#

The dynamic batcher can be configured to allow requests to be delayed for a limited time in the scheduler to allow other requests to join the dynamic batch. For example, the following configuration sets the maximum delay time of 100 microseconds for a request.

  dynamic_batching {
    max_queue_delay_microseconds: 100
  }

The max_queue_delay_microseconds property setting changes the dynamic batcher behavior when a maximum size (or preferred size) batch cannot be created. When a batch of a maximum or preferred size cannot be created from the available requests, the dynamic batcher will delay sending the batch as long as no request is delayed longer than the configured max_queue_delay_microseconds value. If a new request arrives during this delay and allows the dynamic batcher to form a batch of a maximum or preferred batch size, then that batch is sent immediately for inferencing. If the delay expires the dynamic batcher sends the batch as is, even though it is not a maximum or preferred size.

Preserve Ordering#

The preserve_ordering property is used to force all responses to be returned in the same order as requests were received. See the protobuf documentation for details.

Priority Levels#

By default the dynamic batcher maintains a single queue that holds all inference requests for a model. The requests are processed and batched in order. The priority_levels property can be used to create multiple priority levels within the dynamic batcher so that requests with higher priority are allowed to bypass requests with lower priority. Requests at the same priority level are processed in order. Inference requests that do not set a priority are scheduled using the default_priority_level property.

Queue Policy#

The dynamic batcher provides several settings that control how requests are queued for batching.

When priority_levels is not defined, the ModelQueuePolicy for the single queue can be set with default_queue_policy. When priority_levels is defined, each priority level can have a different ModelQueuePolicy as specified by default_queue_policy and priority_queue_policy.

The ModelQueuePolicy property allows a maximum queue size to be set using the max_queue_size. The timeout_action, default_timeout_microseconds and allow_timeout_override settings allow the queue to be configured so that individual requests are rejected or deferred if their time in the queue exceeds a specified timeout.

Custom Batching#

You can set custom batching rules that work in addition to the specified behavior of the dynamic batcher. To do so, you would implement five functions in tritonbackend.h and create a shared library. These functions are described below.

Function	Description
TRITONBACKEND_ModelBatchIncludeRequest	Determines whether a request should be included in the current batch
TRITONBACKEND_ModelBatchInitialize	Initializes a record-keeping data structure for a new batch
TRITONBACKEND_ModelBatchFinalize	Deallocates the record-keeping data structure after a batch is formed
TRITONBACKEND_ModelBatcherInitialize	Initializes a read-only data structure for use with all batches
TRITONBACKEND_ModelBatcherFinalize	Deallocates the read-only data structure after the model is unloaded

The path to the shared library can be passed into the model configuration via the parameter TRITON_BATCH_STRATEGY_PATH. If not provided, the dynamic batcher will look for a custom batching strategy named batchstrategy.so in the model version, model, and backend directories, in that order. If found, it will load it. This lets you easily share a custom batching strategy among all models using the same backend.

For a tutorial of how to create and use a custom batching library, please see the backend examples directory.

Sequence Batcher#

Like the dynamic batcher, the sequence batcher combines non-batched inference requests, so that a batch is created dynamically. Unlike the dynamic batcher, the sequence batcher should be used for stateful models where a sequence of inference requests must be routed to the same model instance. The dynamically created batches are distributed to all model instances configured for the model.

Sequence batching is enabled and configured independently for each model using the ModelSequenceBatching property in the model configuration. These settings control the sequence timeout as well as configuring how Triton will send control signals to the model indicating sequence start, end, ready and correlation ID. See Stateful Models for more information and examples.

Iterative Sequences#

[!NOTE] Iterative sequences are provisional and likely to change in future versions.

The sequence batcher supports stateful execution of “iterative sequences” where a single request is processed over a number of scheduling iterations. “Iterative sequences” enable the scheduler to batch multiple inflight requests at each step and allow the model or backend to complete a request at any iteration.

For models and backends that support “iterative sequences”, users can enable support in the sequence batcher by specifying:

  sequence_batching {
    iterative_sequence: true
  }

An “iterative sequence” refers to stateful models that iteratively process a single request until a complete response is generated. When iterative sequence is enabled, the sequence scheduler will expect a single incoming request to initiate the sequence. Backends that support iterative sequences can then yield back to the sequence batcher to reschedule the request for further execution in a future batch.

Because only one request is used to represent the “iterative sequence”, the user doesn’t need to set control inputs mentioned in the previous section. They will be filled internally by the scheduler.

“Iterative sequences” can be decoupled where more than one response can be generated during execution or non-decoupled where a single response is generated when the full response is complete.

The main advantage of “iterative sequences” is the ability to use Triton’s native batching capabilities to form batches of requests at different iteration stages without having to maintain additional state in the backend. Typically batches executed by backends are completed in the same execution which can waste resources if the execution of one of the requests in the batch takes much longer than the rest. With “iterative sequences”, processing for each request in a batch can be broken down into multiple iterations and a backend can start processing new requests as soon as any request is complete.

Continuous/Inflight Batching with Iterative Sequences#

Continuous batching, iteration level batching, and inflight batching are terms used in large language model (LLM) inferencing to describe batching strategies that form batches of requests at each iteration step. By forming batches “continuously” inference servers can increase throughput by reusing batch slots as soon as they are free without waiting for all requests in a batch to complete.

As the number of steps required to process a request can vary significantly, batching existing requests and new requests continuously can have a significant improvement on throughput and latency.

To achieve inflight batching with iterative sequences, the backend should break request processing into a number of steps, where each step corresponds to one Triton model instance execution. At the end of each step, the model instance will release requests that have been completed and reschedule requests that are still inflight. Triton will then form and schedule the next batch of requests that mixes new and rescheduled requests.

Ensemble Scheduler#

The ensemble scheduler must be used for ensemble models and cannot be used for any other type of model.

The ensemble scheduler is enabled and configured independently for each model using the ModelEnsembleScheduling property in the model configuration. The settings describe the models that are included in the ensemble and the flow of tensor values between the models. See Ensemble Models for more information and examples.

Optimization Policy#

The model configuration ModelOptimizationPolicy property is used to specify optimization and prioritization settings for a model. These settings control if/how a model is optimized by the backend and how it is scheduled and executed by Triton. See the ModelConfig protobuf and optimization documentation for the currently available settings.

Model Warmup#

When a model is loaded by Triton the corresponding backend initializes for that model. For some backends, some or all of this initialization is deferred until the model receives its first inference request (or first few inference requests). As a result, the first (few) inference requests can be significantly slower due to deferred initialization.

To avoid these initial, slow inference requests, Triton provides a configuration option that enables a model to be “warmed up” so that it is completely initialized before the first inference request is received. When the ModelWarmup property is defined in a model configuration, Triton will not show the model as being ready for inference until model warmup has completed.

The model configuration ModelWarmup is used to specify warmup settings for a model. The settings define a series of inference requests that Triton will create to warm-up each model instance. A model instance will be served only if it completes the requests successfully. Note that the effect of warming up models varies depending on the framework backend, and it will cause Triton to be less responsive to model update, so the users should experiment and choose the configuration that suits their need. See the ModelWarmup protobuf documentation for the currently available settings, and L0_warmup for examples on specifying different variants of warmup samples.

Response Cache#

The model configuration response_cache section has an enable boolean used to enable the Response Cache for this model.

response_cache {
  enable: true
}

In addition to enabling the cache in the model config, a --cache-config must be specified when starting the server to enable caching on the server-side. See the Response Cache doc for more details on enabling server-side caching.

Model Configuration

Contents