MNN Python Binding

Common errors

• ModuleNotFoundError: No module named 'MNN'

  cause The MNN Python package is not installed in the current Python environment or the environment where the script is being run.
  fix Install the package using pip: `pip install MNN`

• AttributeError: module 'MNN' has no attribute 'some_function'

  cause Attempting to access a function or submodule that does not exist directly under the `MNN` top-level module, or using a deprecated API. For example, some functionalities are under `MNN.nn`, `MNN.cv`, `MNN.numpy`, or `MNN.expr`.
  fix Verify the correct import path and module structure. Most new APIs reside in `MNN.nn`, `MNN.cv`, `MNN.numpy`, or `MNN.expr`. For instance, `MNN.Interpreter` is deprecated; use `MNN.nn`.

• TypeError: 'float' object is not subscriptable

  cause This often happens when model outputs or intermediate tensors are treated as Python lists or arrays prematurely. MNN operations often return `MNN.expr.Var` objects that need further processing (e.g., conversion or explicit numpy operations) before direct Python list-like access.
  fix Ensure `Var` objects are properly converted to NumPy arrays (e.g., `output_var.read()`) or processed with `MNN.numpy` operations before attempting direct indexing or iteration.

• FileNotFoundError: [Errno 2] No such file or directory: 'your_model.mnn'

  cause The specified MNN model file (e.g., `mobilenet_v1.mnn`) or image file (`cat.jpg`) cannot be found at the given path. This can be due to an incorrect file path, the file not existing, or incorrect working directory.
  fix Double-check the file path. Ensure the model and image files are in the expected location relative to your script, or provide an absolute path. Use `os.path.exists()` for debugging.

Warnings

• deprecated The MNN Python Session API (`MNN.Interpreter`, `MNN.Session`) is deprecated. Users should migrate to the Module API (`MNN.nn.Module`, `MNN.nn.load_module_from_file`) for all inference and training tasks.
  Fix: Rewrite code to use `MNN.nn.load_module_from_file` to load models and interact with `_Module` objects (or custom `nn.Module` subclasses) and their `forward` method.
• gotcha MNN.cv and MNN.numpy, while lightweight, involve graph construction, operation, and destruction which can become a performance bottleneck on mobile devices if overused. Keep pre/post-processing logic simple.
  Fix: Minimize complex or repetitive operations using `MNN.cv` and `MNN.numpy` in performance-critical loops. Optimize data flow and batching.
• gotcha When converting models using `MNNConvert` with the `--saveExternalData` flag, a separate weight file (`.mnn.weight`) is generated. This external weight file must be explicitly specified when loading the model via the Python Module API using `RuntimeManager::setExternalFile` for correct operation.
  Fix: Ensure that if `--saveExternalData` was used during conversion, the corresponding `.mnn.weight` file is present alongside the `.mnn` model, and specify its path when initializing the `RuntimeManager` or loading the module.

Install

• pip install MNN Install stable version

Imports

• MNN

  import MNN

• MNN.nn

  import MNN.nn as nn

• MNN.cv

  import MNN.cv as cv

• MNN.numpy

  import MNN.numpy as np

• MNN.expr
  wrong:

  import MNN.core.expr

  correct:

  import MNN.expr as expr

  Direct `MNN.expr` is the current pattern.
• MNN.Interpreter
  wrong:

  from MNN.Interpreter import Interpreter

  correct:

  from MNN import Interpreter

  The Session API (which uses Interpreter) is deprecated; prefer Module API.

Quickstart

This quickstart demonstrates loading an MNN model, preprocessing an image using `MNN.cv` and `MNN.numpy`, performing inference with the `Module API`, and post-processing the output. Replace `mobilenet_v1.mnn` and `cat.jpg` with your actual model and input data. The code includes creation of dummy files for runnable demonstration purposes if actual files are not present.

import MNN.nn as nn
import MNN.cv as cv
import MNN.numpy as np
import MNN.expr as expr
import os

# Assuming 'mobilenet_v1.mnn' and 'cat.jpg' exist in the current directory
# In a real scenario, you'd download these or replace with your model/image.
# For demonstration, we'll create dummy files if they don't exist.

# Create a dummy MNN model file if it doesn't exist (for runnable example)
if not os.path.exists('mobilenet_v1.mnn'):
    print("Creating dummy mobilenet_v1.mnn for quickstart. This won't run a real model.")
    with open('mobilenet_v1.mnn', 'w') as f:
        f.write('dummy_model_content')

# Create a dummy image file if it doesn't exist (for runnable example)
if not os.path.exists('cat.jpg'):
    print("Creating dummy cat.jpg for quickstart. This won't process a real image.")
    # Using PIL to create a simple dummy image
    try:
        from PIL import Image
        img = Image.new('RGB', (224, 224), color = 'red')
        img.save('cat.jpg')
    except ImportError:
        print("Pillow not installed. Skipping dummy image creation.")
        print("Please install Pillow (pip install Pillow) or provide a 'cat.jpg'.")

# Configure runtime (e.g., backend, threads, precision)
# Backend 0 typically refers to CPU. 'low' precision might enable FP16 if hardware supports.
config = {
    'precision': 'low', 
    'backend': 0,      
    'numThread': 4     
}
runtime_manager = nn.create_runtime_manager((config,))

# Load model using the Module API
# 'data' and 'prob' are example input/output names, adapt to your model
try:
    net = nn.load_module_from_file('mobilenet_v1.mnn', ['data'], ['prob'], runtime_manager=runtime_manager)
except Exception as e:
    print(f"Could not load dummy model: {e}. Please ensure 'mobilenet_v1.mnn' is a valid MNN model.")
    exit()

# Read and preprocess image using MNN.cv and MNN.numpy
# Mean and norm values are typical for MobileNet preprocessing
image = cv.imread('cat.jpg')
if image is not None:
    image = cv.resize(image, (224, 224), mean=[103.94, 116.78, 123.68], norm=[0.017, 0.017, 0.017])
    input_var = np.expand_dims(image, 0) # Add batch dimension (HWC to NHWC)
    input_var = expr.convert(input_var, expr.NC4HW4) # NHWC to NC4HW4 for MNN

    # Perform inference
    output_var = net.forward(input_var)

    # Post-process output
    output_var = expr.convert(output_var, expr.NHWC) # NC4HW4 to NHWC
    # For a real classification model, you would interpret 'output_var' here
    print(f"Inference output shape: {output_var.shape}")
    # Example: print top-1 class if it's a classification model
    # print(f"Output belongs to class: {np.argmax(output_var)}")
else:
    print("Could not read image. Ensure 'cat.jpg' exists and is a valid image.")