Update 0.10.0 docs & refactor docs structure

.github/workflows/docs.yml

@@ -82,7 +82,7 @@ jobs:
           cd ./furiosa-models
           export GIT_HASH=$(git rev-parse --short HEAD)
           export ISSUE_URL=$(echo $ISSUE | cut -d'/' -f-5)
-          export DOCS_PATH=$(echo $BODY | head -n 1 | cut -d'/' -f3)
+          export DOCS_PATH=$(echo $BODY | head -n 1 | cut -d'/' -f3 | xargs)  # use xargs to trim ws/newline chars
           echo "Git short hash: $GIT_HASH"
           echo "Issue URL base: $ISSUE_URL"
           if [ ! $(echo "$DOCS_PATH" | grep -P "v([0-9]+\.){2}[0-9]+") ]; then

Makefile

@@ -4,8 +4,8 @@ ONNXRUNTIME_VERSION := 1.15.1-?
 TOOLCHAIN_VERSION := 0.10.0-?
 LIBHAL_VERSION := 0.11.0-?
 
-.PHONY: check-docker-tag toolchain lint test unit_tests examples regression-test-all \
-regression-test-resnet50 regression-test-ssd-mobilenet \
+.PHONY: check-docker-tag toolchain lint test unit_tests notebook_tests examples \
+regression-test-all regression-test-resnet50 regression-test-ssd-mobilenet \
 regression-test-ssd-resnet34 regression-test-yolov5 doc docker-build docker-push \
 regression-test-efficientnet-b0 regression-test-efficientnet-v2-s
 
@@ -33,8 +33,11 @@ test:
 unit_tests:
 	pytest ./tests/unit/ -s
 
+notebook_tests:
+	pytest --nbmake --nbmake-timeout=3600 ./docs
+
 examples:
-	for f in $$(find docs/examples/ -name *.py); do printf "\n[TEST] $$f ...\n"; python3 $$f || exit 1; done
+	for f in $$(find docs/examples/ -name *.py | grep -v "serving"); do printf "\n[TEST] $$f ...\n"; python3 $$f || exit 1; done
 
 regression-test-all:
 	pytest ./tests/bench/

README.md

@@ -9,20 +9,21 @@ for FuriosaAI NPU. However, all models are standard ONNX or tflite models,
 and they can run even on CPU and GPU as well.
 
 ## Releases
+* [v0.10.0](https://furiosa-ai.github.io/furiosa-models/v0.10.0/changelog/) - 2023-08-28
 * [v0.9.1](https://furiosa-ai.github.io/furiosa-models/v0.9.1/changelog/) - 2023-05-26
 * [v0.9.0](https://furiosa-ai.github.io/furiosa-models/v0.9.0/changelog/) - 2023-05-12
 * [v0.8.0](https://furiosa-ai.github.io/furiosa-models/v0.8.0/changelog/) - 2022-11-10
 
 ## Online Documentation
-If you are new, you can start from [Getting Started](https://furiosa-ai.github.io/furiosa-models/latest/getting_started/).
+If you are new, you can start from [Getting Started](https://furiosa-ai.github.io/furiosa-models/v0.10.0/getting_started/).
 You can also find the latest online documents,
 including programming guides, API references, and examples from the followings:
 
 * [Furiosa Models - Latest Documentation](https://furiosa-ai.github.io/furiosa-models/latest/)
-* [Model object](https://furiosa-ai.github.io/furiosa-models/latest/model_object/)
-* [Model List](https://furiosa-ai.github.io/furiosa-models/latest/#model_list)
-* [Command Tool](https://furiosa-ai.github.io/furiosa-models/latest/command_tool/)
-* [Furiosa SDK - Tutorial and Code Examples](https://furiosa-ai.github.io/docs/latest/en/software/tutorials.html)
+* [Model Object](https://furiosa-ai.github.io/furiosa-models/v0.10.0/model_object/)
+* [Model List](https://furiosa-ai.github.io/furiosa-models/v0.10.0/#model_list)
+* [Command Line Tool](https://furiosa-ai.github.io/furiosa-models/v0.10.0/command_line_tool/)
+* [Furiosa SDK - Tutorial and Code Examples](https://furiosa-ai.github.io/docs/v0.10.0/en/software/tutorials.html)
 
 
 ## <a name="model_list"></a>Model List
@@ -31,13 +32,13 @@ you can find details about loading a model, their input and output tensors, pre/
 
 | Model                                                                                            | Task                 | Size | Accuracy                  |
 | ------------------------------------------------------------------------------------------------ | -------------------- | ---- | ------------------------- |
-| [ResNet50](https://furiosa-ai.github.io/furiosa-models/latest/models/resnet50_v1.5/)             | Image Classification | 25M  | 75.618% (ImageNet1K-val)  |
-| [EfficientNetB0](https://furiosa-ai.github.io/furiosa-models/latest/models/efficientnet_b0/)     | Image Classification | 6.4M | 72.44% (ImageNet1K-val)   |
-| [EfficientNetV2-S](https://furiosa-ai.github.io/furiosa-models/latest/models/efficientnet_v2_s/) | Image Classification | 26M  | 83.532% (ImageNet1K-val)  |
-| [SSDMobileNet](https://furiosa-ai.github.io/furiosa-models/latest/models/ssd_mobilenet/)         | Object Detection     | 7.2M | mAP 0.232 (COCO 2017-val) |
-| [SSDResNet34](https://furiosa-ai.github.io/furiosa-models/latest/models/ssd_resnet34/)           | Object Detection     | 20M  | mAP 0.220 (COCO 2017-val) |
-| [YOLOv5M](https://furiosa-ai.github.io/furiosa-models/latest/models/yolov5m/)                    | Object Detection     | 21M  | mAP 0.272 (Bdd100k-val)\* |
-| [YOLOv5L](https://furiosa-ai.github.io/furiosa-models/latest/models/yolov5l/)                    | Object Detection     | 46M  | mAP 0.284 (Bdd100k-val)\* |
+| [ResNet50](https://furiosa-ai.github.io/furiosa-models/v0.10.0/models/resnet50_v1.5/)             | Image Classification | 25M  | 75.618% (ImageNet1K-val)  |
+| [EfficientNetB0](https://furiosa-ai.github.io/furiosa-models/v0.10.0/models/efficientnet_b0/)     | Image Classification | 6.4M | 72.44% (ImageNet1K-val)   |
+| [EfficientNetV2-S](https://furiosa-ai.github.io/furiosa-models/v0.10.0/models/efficientnet_v2_s/) | Image Classification | 26M  | 83.532% (ImageNet1K-val)  |
+| [SSDMobileNet](https://furiosa-ai.github.io/furiosa-models/v0.10.0/models/ssd_mobilenet/)         | Object Detection     | 7.2M | mAP 0.232 (COCO 2017-val) |
+| [SSDResNet34](https://furiosa-ai.github.io/furiosa-models/v0.10.0/models/ssd_resnet34/)           | Object Detection     | 20M  | mAP 0.220 (COCO 2017-val) |
+| [YOLOv5M](https://furiosa-ai.github.io/furiosa-models/v0.10.0/models/yolov5m/)                    | Object Detection     | 21M  | mAP 0.272 (Bdd100k-val)\* |
+| [YOLOv5L](https://furiosa-ai.github.io/furiosa-models/v0.10.0/models/yolov5l/)                    | Object Detection     | 46M  | mAP 0.284 (Bdd100k-val)\* |
 
 _\*: The accuracy of the yolov5 f32 model trained with bdd100k-val dataset, is mAP 0.295 (for yolov5m) and mAP 0.316 (for yolov5l)._
 

docker/Dockerfile

@@ -14,8 +14,7 @@ RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
     | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
     && apt update && apt install gh -y
 
-RUN pip3 install --upgrade pip wheel setuptools Cython pytest pycocotools \
-    dvc[s3] pytest-benchmark
+RUN pip3 install --upgrade pip wheel setuptools Cython dvc[s3]
 
 RUN echo "deb [arch=amd64] https://internal-archive.furiosa.dev/ubuntu focal restricted" \
     > /etc/apt/sources.list.d/furiosa.list && \

docs/changelog.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.10.0 - 2023-08-28]
+
+### New Features
+- Provide 1pe artifacts too #158
+
+### Improvements
+- Resolve artifact binaries lazily #155
+- Added `ruff` linter #160
+- Automatically build documentation on comment #162
+- Upgrade `pydantic` library version to `2.0.0` #166
+- Added `model.resolve_all()` to resolve all lazily loaded fields at once #166
+- Added local artifact binary cache #166
+
+## Removed
+- Removed unused `timm` dependency #149
+- **Breaking:** Now uses default Python initializer instead of `model.load()` #166
+- **Breaking:** `model.enf` field has been removed #166
+- **Breaking:** `model.source`, `model.calib_yaml` fields have been renamed #166
+
 ## [0.9.1 - 2023-05-26]
 
 ## [0.9.0 - 2023-05-12]

docs/command_tool.md → docs/command_line_tool.md

@@ -1,4 +1,4 @@
-# Command Tool
+# Command Line Tool
 We provide a simple command line tool called `furiosa-models` to allow users to
 evaluate or run quickly one of models with FuriosaAI NPU.
 
@@ -13,7 +13,7 @@ furiosa-models [-h] {list, desc, bench} ...
 
 `furiosa-models` command has three subcommands: `list`, `desc`, and `bench`.
 
-## Subcommand: list
+## Subcommand: `list`
 
 `list` subcommand prints out the list of models with attributes.
 You will be able to figure out what models are available.
@@ -35,7 +35,7 @@ $ furiosa-models list
 +-----------------+------------------------------+----------------------+-------------------------+
 ```
 
-## Subcommand: bench
+## Subcommand: `bench`
 
 `bench` subcommand runs a specific model with a given path where the input sample data are located.
 It will print out the performance benchmark results like QPS.
@@ -72,7 +72,7 @@ QPS: 790.88645
 Avg. elapsed time / sample: 1.26440 ms
 ```
 
-## Subcommand: desc
+## Subcommand: `desc`
 
 `desc` subcommand shows the details of a specific model.
 

docs/developers-guide.md

@@ -1,4 +1,4 @@
-# Developer's guide
+# Developer's Guide
 
 This documentation is for developers who want to contribute to Furiosa Models.
 

docs/examples/serving.py

@@ -0,0 +1,45 @@
+from tempfile import NamedTemporaryFile
+from typing import Dict, List
+
+from fastapi import FastAPI, File, UploadFile
+import numpy as np
+import uvicorn
+
+from furiosa.common.thread import synchronous
+from furiosa.models import vision
+from furiosa.serving import ServeAPI, ServeModel
+
+serve = ServeAPI()
+app: FastAPI = serve.app
+
+resnet50 = vision.ResNet50()
+# ServeModel does not support in-memory model binary for now,
+# so we write model into temp file and pass its path
+model_file = NamedTemporaryFile()
+model_file.write(resnet50.model_source())
+model_file_path = model_file.name
+
+model: ServeModel = synchronous(serve.model("furiosart"))('ResNet50', location=model_file_path)
+
+
+@model.post("/infer")
+async def infer(image: UploadFile = File(...)) -> Dict[str, str]:
+    # Model Zoo's preprocesses do not consider in-memory image file for now
+    # (note that it's different from in-memory tensor)
+    # so we write in-memory image into temp file and pass its path
+    image_file_path = NamedTemporaryFile()
+    image_file_path.write(await image.read())
+
+    tensors, _ctx = resnet50.preprocess(image_file_path.name)
+
+    # Infer from ServeModel
+    result: List[np.ndarray] = await model.predict(tensors)
+
+    response: str = resnet50.postprocess(result)
+
+    return {"result": response}
+
+
+# Run the server if current Python script is called directly
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)

docs/examples/ssd_mobilenet_native.py

@@ -1,9 +1,10 @@
+from furiosa.models.types import Platform
 from furiosa.models.vision import SSDMobileNet
 from furiosa.runtime.sync import create_runner
 
 image = ["tests/assets/cat.jpg"]
 
-mobilenet = SSDMobileNet(postprocessor_type="Rust")
+mobilenet = SSDMobileNet(postprocessor_type=Platform.RUST)
 with create_runner(mobilenet.model_source()) as runner:
     inputs, contexts = mobilenet.preprocess(image)
     outputs = runner.run(inputs)

docs/examples/ssd_mobilenet_onnx.py

@@ -8,13 +8,19 @@
 
 mobilenet = SSDMobileNet()
 onnx_model: bytes = mobilenet.origin
-calib_range: dict = mobilenet.tensor_name_to_range
+tensor_name_to_range: dict = mobilenet.tensor_name_to_range
 
 # See https://furiosa-ai.github.io/docs/latest/en/api/python/furiosa.quantizer.html#furiosa.quantizer.quantize
 # for more details
-quantized_onnx = quantize(onnx_model, calib_range)
+quantized_onnx = quantize(onnx_model, tensor_name_to_range)
 
 with create_runner(quantized_onnx, compiler_config=compiler_config) as runner:
+    # Models in the Model Zoo have built-in optimizations that, by default,
+    # bypass normalization, quantization, and type conversion. If you compile
+    # and utilize these models without employing these optimizations, it's
+    # necessary to set up preprocessing steps to incorporate normalization and
+    # type casting. To accomplish this, you should introduce an extra parameter,
+    # `with_scaling=True`.
     inputs, contexts = mobilenet.preprocess(image, with_scaling=True)
     outputs = runner.run(inputs)
     mobilenet.postprocess(outputs, contexts[0])

docs/examples/ssd_resnet34_native.py

@@ -1,7 +1,8 @@
+from furiosa.models.types import Platform
 from furiosa.models.vision import SSDResNet34
 from furiosa.runtime.sync import create_runner
 
-resnet34 = SSDResNet34(postprocessor_type="Rust")
+resnet34 = SSDResNet34(postprocessor_type=Platform.RUST)
 
 with create_runner(resnet34.model_source()) as runner:
     image, contexts = resnet34.preprocess(["tests/assets/cat.jpg"])

docs/getting_started.md

@@ -23,12 +23,18 @@ pip install --upgrade pip setuptools wheel
 pip install 'furiosa-models'
 ```
 
+!!!Info
+    Older versions of wheel may reject the native-build wheels of furiosa-models.
+    Please make sure of installing & upgrading Python packaging tools before
+    installing furiosa-models.
+
+
 ??? "Building from Source Code (click to see)"
     Or you can build from the source code as following:
 
     ```
     git clone https://github.com/furiosa-ai/furiosa-models
-    pip install .
+    pip install ./furiosa-models
     ```
 
 ## Quick example and Guides
@@ -49,7 +55,7 @@ You can simply load a model and run through furiosa-sdk as the following:
 This example does:
 
 1. Load the [SSDMobileNet](models/ssd_mobilenet.md) model
-2. Create a `session`, which is the main class of Furiosa Runtime, that can load an ONNX/tflite model onto NPU and run inferences.
+2. Create a `Runner`, which is one of the main classes of Furiosa Runtime, that can load an ONNX/tflite model onto NPU and run inferences.
 3. Run an inference with pre/post process functions.
 
 A `Model` instance is a Python object, including model artifacts, metadata, and its pre/postprocessors.
@@ -60,5 +66,8 @@ Also, you can find all available models at
 Each model page includes the details of the model, input and output tensors, and pre/post processings,
 and API reference.
 
-If you want to learn more about `furiosa.runtime.session` in Furiosa Runtime, please refer to
-[Furiosa SDK - Tutorial and Code Examples](https://furiosa-ai.github.io/docs/latest/en/software/tutorials.html).
+If you want to learn more about `Runner` in Furiosa Runtime, please refer to below links.
+
+- [Furiosa SDK - furiosa.runtime API Reference](https://furiosa-ai.github.io/docs/latest/en/api/python/furiosa.runtime.html)
+- [Furiosa SDK - furiosa.runtime.sync.create_runner Reference](https://furiosa-ai.github.io/docs/latest/en/api/python/furiosa.runtime.html#furiosa.runtime.sync.Runtime)
+- [Furiosa SDK - Tutorial and Code Examples](https://furiosa-ai.github.io/docs/latest/en/software/tutorials.html).