MLTensor

Experimental: This is an experimental technology. Check the browser compatibility table carefully before using it in production.

The MLTensor interface of the Web Neural Network (WebNN) API represents a block of memory, owned by an MLContext, that can be used as an input or output of an MLGraph, or as a constant when building one.

Tensor memory is allocated in an implementation-defined way that suits the context’s device, for example in GPU or NPU memory, with a particular byte alignment, or in a particular memory pool. Script never accesses this memory directly: data is copied in with MLContext.writeTensor() and copied out with MLContext.readTensor(). Keeping data in tensors between calls to MLContext.dispatch() avoids unnecessary copies, for example when the output of one graph is the input of the next.

Tensors are created with MLContext.createTensor(), MLContext.createExportableTensor(), or MLContext.createConstantTensor().

This feature is available only in secure contexts  (HTTPS or localhost), and is available in both the main thread and Web Workers .

Web IDL

dictionary MLTensorDescriptor : MLOperandDescriptor {
  boolean readable = false;
  boolean writable = false;
};

[SecureContext, Exposed=(Window, Worker)]
interface MLTensor {
  readonly attribute MLOperandDataType dataType;
  readonly attribute FrozenArray<unsigned long> shape;
  readonly attribute boolean readable;
  readonly attribute boolean writable;
  readonly attribute boolean constant;

  undefined destroy();
};

Constructor

None. Use the MLContext tensor creation methods.

Instance properties

dataType

A read-only MLOperandDataType string giving the tensor’s element type.

shape

A read-only, frozen array of unsigned long values giving the tensor’s dimensions.

readable

A read-only boolean that is true if the tensor’s contents can be read with MLContext.readTensor().

writable

A read-only boolean that is true if the tensor’s contents can be written with MLContext.writeTensor().

constant

A read-only boolean that is true if the tensor was created with MLContext.createConstantTensor(). A constant tensor is neither readable nor writable and cannot be bound as a dispatch() input or output; it can only be used with MLGraphBuilder.constant(tensor).

Instance methods

destroy()

The destroy() method releases the resources associated with the tensor. It is idempotent: calling it more than once has the same effect as calling it once.

After destroy() is called:

• Any pending readTensor() promise for the tensor is rejected with an InvalidStateError DOMException.
• Using the tensor with dispatch(), readTensor(), writeTensor(), exportToGPU() or MLGraphBuilder.constant() fails with a TypeError.
• Work already queued on the context that uses the tensor still completes before the memory is released.

Destroying a constant tensor after the graphs that use it have been built is allowed; those graphs remain valid. Tensors are also destroyed automatically when their context is lost or destroyed.

Syntax

destroy()

Parameters

None.

Return value

None (undefined).

MLTensorDescriptor

The MLTensorDescriptor dictionary extends MLOperandDescriptor with the capabilities of a tensor. It is passed to MLContext.createTensor() and MLContext.createExportableTensor().

Request only the capabilities you need. A tensor that is neither readable nor writable can still be used as a dispatch() input or output, for example to pass intermediate results between graphs without copying them to script, and lets the implementation choose the most efficient memory.

Exporting to WebGPU

A tensor created with createExportableTensor() can be handed to WebGPU with MLContext.exportToGPU(), which returns a GPUBuffer. While the tensor is exported, WebGPU has exclusive access to it and WebNN operations that use it fail with a TypeError. Calling destroy() on the returned GPUBuffer returns the tensor to WebNN.

Examples

Creating, writing and reading a tensor

const context = await navigator.ml.createContext();
 
const tensor = await context.createTensor({
  dataType: 'float32',
  shape: [2, 2],
  readable: true,
  writable: true,
});
console.log(tensor.shape, tensor.dataType); // [2, 2] "float32"
 
context.writeTensor(tensor, new Float32Array([1, 2, 3, 4]));
const data = new Float32Array(await context.readTensor(tensor));
console.log(data); // Float32Array [1, 2, 3, 4]
 
tensor.destroy();

Chaining graphs without copying to script

const desc = { dataType: 'float32', shape: [1, 1024] };
 
// An intermediate tensor that never needs to be read or written by script.
const hidden = await context.createTensor(desc);
const input = await context.createTensor({ ...desc, writable: true });
const output = await context.createTensor({ ...desc, readable: true });
 
context.writeTensor(input, inputData);
context.dispatch(encoderGraph, { x: input }, { h: hidden });
context.dispatch(decoderGraph, { h: hidden }, { y: output });
 
const result = new Float32Array(await context.readTensor(output));

Handling a non-readable tensor

const tensor = await context.createTensor({ dataType: 'float32', shape: [4] });
try {
  await context.readTensor(tensor);
} catch (e) {
  console.log(e.name); // "TypeError" — the tensor was not created with readable: true.
}

Specifications

The latest Editor’s Draft is available at webmachinelearning.github.io/webnn .

Browser compatibility

WebNN is under active development and support varies across browsers, operating systems, and hardware. The constant property and exportable tensors are recent additions and may not be implemented yet.

See Browser Compatibility: WebNN APIs.

See also

• MLContext
• MLGraphBuilder.constant()
• MLTensor explainer