From 89c2ac57e401b096cd65d6e3c3cf15d9bcb76580 Mon Sep 17 00:00:00 2001 From: Andrew Brown Date: Mon, 14 Aug 2023 15:01:03 -0700 Subject: [PATCH] ci: use new version of `wit-abi` This change adds a new document `ml-example.md` which is generated from the WIT world in `wasi-nn.wit`. `wasi-nn.wit` has to be moved back into a `wit` directory to be found by the `wit-abi` tool to [check the document]. Also, this updates documentation on how to keep `ml-example.md` up to date. [check the document]: https://github.com/WebAssembly/wit-abi-up-to-date/blob/71653db16a81a4319b87cada0bafff5a52f64a9b/main.js#L32 --- .github/workflows/main.yml | 4 +- CONTRIBUTING.md | 15 +-- ml-example.md | 202 +++++++++++++++++++++++++++++++++ wasi-nn.witx | 2 +- wasi-nn.wit => wit/wasi-nn.wit | 0 5 files changed, 211 insertions(+), 12 deletions(-) create mode 100644 ml-example.md rename wasi-nn.wit => wit/wasi-nn.wit (100%) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 82c83e6..90e28a1 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -11,6 +11,6 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - - uses: WebAssembly/wit-abi-up-to-date@v4 + - uses: WebAssembly/wit-abi-up-to-date@v13 with: - wit-abi-tag: wit-abi-0.4.0 + wit-abi-tag: wit-abi-0.11.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a383b13..a717e9b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,18 +5,15 @@ same guidelines as the [WASI contribution guidelines]. [WASI contribution guidelines]: https://github.com/WebAssembly/WASI/blob/main/Contributing.md -The specification is written in WIT (WebAssembly Interface Types) syntax in code -blocks inside a Markdown file (`wasi-nn.wit.md`). This is parseable by WIT tools -(e.g., [`wit-bindgen`], [`wit-abi`]). Note that, when altering the WIT -specification, the ABI file (`wasi-nn.abi.md`) must also be updated or CI will -fail. To use [`wit-abi`] to update the ABI file, run: +The specification is written in WIT (WebAssembly Interface Types) — see `wit/wasi-nn.wit`. +This is parseable by WIT tools (e.g., [`wit-bindgen`], [`wit-abi`]). Note that, when altering the +WIT specification, the Markdown example file (`ml-example.md`) must also be updated or CI will fail. +To use [`wit-abi`] to update the ABI file, run: [`wit-bindgen`]: https://github.com/bytecodealliance/wit-bindgen [`wit-abi`]: https://github.com/WebAssembly/wasi-tools/tree/main/wit-abi ```console -$ git clone https://github.com/WebAssembly/wasi-tools -$ cd wasi-tools/wit-abi -$ cargo build -$ target/debug/wit-abi +$ cargo install wit-abi --locked --git https://github.com/WebAssembly/wasi-tools --tag wit-abi-0.11.0 +$ wit-abi markdown --html-in-md wit ``` diff --git a/ml-example.md b/ml-example.md new file mode 100644 index 0000000..bf82f84 --- /dev/null +++ b/ml-example.md @@ -0,0 +1,202 @@ +

World ml-example

+

wasi-nn is a WASI API for performing machine learning (ML) inference. The API is not (yet) +capable of performing ML training. WebAssembly programs that want to use a host's ML +capabilities can access these capabilities through wasi-nn's core abstractions: graphs and +tensors. A user loads a model -- instantiated as a graph -- to use in an ML backend. +Then, the user passes tensor inputs to the graph, computes the inference, and retrieves the +tensor outputs.

+

This example world shows how to use these primitives together.

+ +

Import interface wasi:nn/tensor

+

All inputs and outputs to an ML inference are represented as tensors.

+
+

Types

+

enum tensor-type

+

The type of the elements in a tensor.

+
Enum Cases
+ +

type tensor-dimensions

+

tensor-dimensions

+

The dimensions of a tensor. +

The array length matches the tensor rank and each element in the array describes the size of +each dimension

+

type tensor-data

+

tensor-data

+

The tensor data. +

Initially conceived as a sparse representation, each empty cell would be filled with zeros +and the array length must match the product of all of the dimensions and the number of bytes +in the type (e.g., a 2x2 tensor with 4-byte f32 elements would have a data array of length +16). Naturally, this representation requires some knowledge of how to lay out data in +memory--e.g., using row-major ordering--and could perhaps be improved.

+

record tensor

+
Record Fields
+ +

Import interface wasi:nn/errors

+

TODO: create function-specific errors (https://github.com/WebAssembly/wasi-nn/issues/42)

+
+

Types

+

enum error

+
Enum Cases
+ +

Import interface wasi:nn/graph

+

A graph is a loaded instance of a specific ML model (e.g., MobileNet) for a specific ML +framework (e.g., TensorFlow):

+
+

Types

+

type error

+

error

+

+#### `type tensor` +[`tensor`](#tensor) +

+#### `enum graph-encoding` +

Describes the encoding of the graph. This allows the API to be implemented by various +backends that encode (i.e., serialize) their graph IR with different formats.

+
Enum Cases
+ +

type graph-builder

+

graph-builder

+

The graph initialization data. +

This gets bundled up into an array of buffers because implementing backends may encode their +graph IR in parts (e.g., OpenVINO stores its IR and weights separately).

+

type graph

+

u32

+

An execution graph for performing inference (i.e., a model). +

TODO: replace with resource (https://github.com/WebAssembly/wasi-nn/issues/47).

+

enum execution-target

+

Define where the graph should be executed.

+
Enum Cases
+ +
+

Functions

+

load: func

+

Load a graph from an opaque sequence of bytes to use for inference.

+
Params
+ +
Return values
+ +

load-named-model: func

+

Load a graph by name.

+

How the host expects the names to be passed and how it stores the graphs for retrieval via +this function is implementation-specific. This allows hosts to choose name schemes that +range from simple to complex (e.g., URLs?) and caching mechanisms of various kinds.

+
Params
+ +
Return values
+ +

Import interface wasi:nn/inference

+

An inference "session" is encapsulated by a graph-execution-context. This structure binds a +graph to input tensors before compute-ing an inference:

+
+

Types

+

type error

+

error

+

+#### `type tensor` +[`tensor`](#tensor) +

+#### `type tensor-data` +[`tensor-data`](#tensor_data) +

+#### `type graph` +[`graph`](#graph) +

+#### `type graph-execution-context` +`u32` +

Bind a `graph` to the input and output tensors for an inference. +

TODO: this is no longer necessary in WIT (https://github.com/WebAssembly/wasi-nn/issues/43)

+
+

Functions

+

init-execution-context: func

+

Create an execution instance of a loaded graph.

+
Params
+ +
Return values
+ +

set-input: func

+

Define the inputs to use for inference.

+
Params
+ +
Return values
+ +

compute: func

+

Compute the inference on the given inputs.

+

Note the expected sequence of calls: set-input, compute, get-output. TODO: this +expectation could be removed as a part of https://github.com/WebAssembly/wasi-nn/issues/43.

+
Params
+ +
Return values
+ +

get-output: func

+

Extract the outputs after inference.

+
Params
+ +
Return values
+ diff --git a/wasi-nn.witx b/wasi-nn.witx index d2900c3..efc841d 100644 --- a/wasi-nn.witx +++ b/wasi-nn.witx @@ -1,4 +1,4 @@ -;; This WITX version of the wasi-nn API is retained for consistency only. See the `wasi-nn.wit` +;; This WITX version of the wasi-nn API is retained for consistency only. See the `wit/wasi-nn.wit` ;; version for the official specification and documentation. (typename $buffer_size u32) diff --git a/wasi-nn.wit b/wit/wasi-nn.wit similarity index 100% rename from wasi-nn.wit rename to wit/wasi-nn.wit