Merge pull request #7 from relaypro-open/develop

Doc fixes and examples for `Ortex.Serving`

Author: mortont

lib/ortex/model.ex

@@ -21,6 +21,7 @@ defmodule Ortex.Model do
   @enforce_keys [:reference]
   defstruct [:reference]
 
+  @doc false
   def load(path, eps \\ [:cpu], opt \\ 3) do
     case Ortex.Native.init(path, eps, opt) do
       {:error, msg} ->
@@ -31,10 +32,12 @@ defmodule Ortex.Model do
     end
   end
 
+  @doc false
   def run(%Ortex.Model{} = model, tensor) when not is_tuple(tensor) do
     run(model, {tensor})
   end
 
+  @doc false
   def run(%Ortex.Model{reference: model}, tensors) do
     # Move tensors into Ortex backend and pass the reference to the Ortex NIF
     output =

lib/ortex/native.ex

@@ -1,9 +1,5 @@
 defmodule Ortex.Native do
-  @moduledoc """
-  Documentation for `Ortex.Native`.
-
-  Stubs for `Rustler` NIFs. These should never be called directly.
-  """
+  @moduledoc false
 
   # We have to compile the crate before `use Rustler` compiles the crate since
   # cargo downloads the onnxruntime shared libraries and they are not available

lib/ortex/serving.ex

@@ -2,9 +2,58 @@ defmodule Ortex.Serving do
   @moduledoc """
   `Ortex.Serving` Documentation
 
-  This is a light wrapper for using `Nx.Serving` behaviour with `Ortex`. Using `jit` and
+  This is a lightweight wrapper for using `Nx.Serving` behaviour with `Ortex`. Using `jit` and
   `defn` functions in this are not supported, it is strictly for serving batches to
   an `Ortex.Model` for inference.
+
+  ## Examples
+
+  ### Inline/serverless workflow 
+
+  To quickly create an `Ortex.Serving` and run it
+
+  ```elixir
+  iex> model = Ortex.load("./models/resnet50.onnx")
+  iex> serving = Nx.Serving.new(Ortex.Serving, model)
+  iex> batch = Nx.Batch.stack([{Nx.broadcast(0.0, {3, 224, 224})}])
+  iex> {result} = Nx.Serving.run(serving, batch)
+  iex> result |> Nx.backend_transfer |> Nx.argmax(axis: 1)
+  #Nx.Tensor<
+    s64[1]
+    [499]
+  >
+  ```
+
+  ### Stateful/process workflow
+
+  An `Ortex.Serving` can also be started in your Application's supervision tree
+  ```elixir
+  model = Ortex.load("./models/resnet50.onnx")
+  children = [
+      {Nx.Serving,
+       serving: Nx.Serving.new(Ortex.Serving, model),
+       name: MyServing,
+       batch_size: 10,
+       batch_timeout: 100}
+    ]
+  opts = [strategy: :one_for_one, name: OrtexServing.Supervisor]
+  Supervisor.start_link(children, opts)
+  ```
+
+  With the application started, batches can now be sent to the `Ortex.Serving` process
+
+  ```elixir
+  iex> Nx.Serving.batched_run(MyServing, Nx.Batch.stack([{Nx.broadcast(0.0, {3, 224, 224})}]))
+  ...> {#Nx.Tensor<
+  f32[1][1000]
+  Ortex.Backend
+   [
+     [...]
+   ]
+  >}
+
+  ```
+
   """
 
   @behaviour Nx.Serving

lib/ortex/util.ex

@@ -1,4 +1,5 @@
 defmodule Ortex.Util do
+  @moduledoc false
   def copy_ort_libs() do
     build_root = Path.absname(:code.priv_dir(:ortex)) |> Path.dirname()