Principle:Microsoft Onnxruntime Tensor Construction
| Field | Value |
|---|---|
| Principle Name | Tensor_Construction |
| Overview | Construction of typed multi-dimensional tensors as input data for ONNX Runtime inference in JavaScript. |
| Category | API Doc |
| Domains | ML_Inference, JavaScript_Integration |
| Source Repository | microsoft/onnxruntime |
| Last Updated | 2026-02-10 |
Overview
Construction of typed multi-dimensional tensors as input data for ONNX Runtime inference in JavaScript. The ort.Tensor class wraps JavaScript TypedArrays with dimension and type metadata, forming the fundamental data container for passing inputs to and receiving outputs from inference sessions.
Description
The ort.Tensor class wraps JavaScript TypedArrays (Float32Array, Uint8Array, Float64Array, etc.) with dimension and type metadata. Tensors are the fundamental data container for passing inputs to and receiving outputs from inference sessions in the ONNX Runtime JavaScript API.
The Tensor constructor accepts several combinations of arguments:
- Explicit type: Provide a type string (e.g., Template:'float32', Template:'bool', Template:'string', Template:'float64', Template:'uint8') as the first argument, followed by the data array and optional dimensions.
- Inferred type: Omit the type string and provide a TypedArray directly; the type is inferred from the TypedArray type (e.g., Float32Array maps to Template:'float32').
- Dimension specification: Provide a number[] array for multi-dimensional tensors, an empty array [] for scalars, or omit for 1-D tensors.
Key supported data types and their corresponding TypedArrays:
| ONNX Type | JavaScript TypedArray |
|---|---|
| float32 | Float32Array |
| float64 | Float64Array |
| int32 | Int32Array |
| uint8 | Uint8Array |
| bool | Uint8Array (with type 'bool' specified explicitly) |
| string | string[] (JavaScript string array) |
The constructor validates that the data buffer size matches the declared dimensions and that the TypedArray type matches the declared tensor type, throwing an error on mismatches.
Theoretical Basis
Tensors provide a typed, shaped view over contiguous memory buffers, matching the mathematical abstraction used in neural network computation. The type system ensures data compatibility between JavaScript and the native ONNX Runtime engine.
In the mathematical sense, a tensor is a multi-dimensional array of numerical values. In the ONNX Runtime context, tensors carry both the raw data and metadata (shape and element type) needed for the runtime to correctly interpret the memory buffer. The shape information determines how the flat buffer is logically organized into dimensions (batch, channels, height, width, etc.).
The use of JavaScript TypedArrays is essential because they provide direct access to contiguous memory buffers, unlike standard JavaScript arrays which store boxed values. This enables efficient zero-copy or minimal-copy data transfer between JavaScript and the native ONNX Runtime C++ layer via N-API.
Usage
Tensor construction is required before every inference call. The typical workflow is:
- Prepare input data in an appropriate JavaScript TypedArray.
- Construct ort.Tensor objects with the correct type, data, and dimensions.
- Assemble tensors into a feeds object keyed by input names.
- Pass feeds to session.run().
The Tensor class is also used for output data: after inference, the results object contains ort.Tensor instances whose .data property provides the output TypedArray.