Skip to content
This repository has been archived by the owner on Sep 29, 2024. It is now read-only.
/ zomi-server Public archive

FastAPI ML server designed for ZoneMinder (zomi-client)

Notifications You must be signed in to change notification settings

baudneo/zomi-server

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

88 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Development has been moved to a private repo, this repo will be archived.

ZoneMinder Machine Learning API (zomi-server)

Caution

⚠️ This software is in ALPHA stage, expect issues and incomplete, unoptimized, janky code ;) ⚠️

This is a FastAPI (with uvicorn and pydantic V2) based server component for the new ZoneMinder ML add-on. Please see the workflow docs for information on how the server processes inference requests. There is also rudimentary support for color detection of cropped bounding boxes.

Supported ML backends and hardware

Note

At the moment, only pretrained models are supported. Custom models are planned for the future (or you can open PR's!).

The server currently has basic support for several ML backends and hardware accelerators.

ML backends

Hardware

  • CPU
    • OpenVINO is planned
  • Nvidia GPU (CUDA / cuDNN / Tensor RT)
  • AMD GPU (Pytorch/onnxruntime ROCm) WIP / Untested
  • Coral.ai Edge TPU

See the docs/hardware directory for more information on hardware support.

Install

Please see the installation docs for more information.

The link between zomi-server and zomi-client

Important

The server defines models in its configuration file models: section. The name: of the model is how it will be called in inference requests. The client will use the name: to send requests to the server.

The name: of each of the models: defined is the link between zomi-server and zomi-client.

Example

  • A client sends an inference request to the server with at least 1 image and 1 model name; yolo v10.
  • The server will look in its internal state to see if there is a model named yolo v10.
  • If the model is found, enabled and no issues loading into memory, the server will run the image through the model and return the results.
    • if the model is not found/enabled/loaded, the server will return an error message. WIP

Swagger UI

Tip

Swagger UI is available at the server root: http://<server>:<port>/

The server uses FastAPIs built-in Swagger UI which shows available endpoints, response/request schema and serves as self-explanatory documentation.

Warning

Make sure to authorize first! All requests require a valid JWT token. If you haven't enabled auth in the server.yml config file, any username:password combo will work. Authorize in Swagger UI

User authentication

Caution

You can enable and disable authentication, but all requests must have a valid JWT token. When authentication is disabled, the login endpoint will accept any username:password combo and supply a valid usable token.

Default user

The default user is imoz with the password zomi.

Start the server

Tip

After installation, there should be a system-wide mlapi script command available in /usr/local/bin

The server can be started with the mlapi script.

mlapi -C /path/to/config/file.yml #--debug

# The server can be started in debug mode with the `--debug` or `-D` flag.
mlapi -C /path/to/config/file.yml --debug

User Management

User management is done using the mlapi script and the user sub-command. For more information, please see the User Management docs.

SystemD service

Important

You must edit the following example files first before installing them!

A SystemD service file example is provided in the configs/systemd directory.

# Edit the service file first!
sudo cp ./configs/systemd/mlapi.service /etc/systemd/system
sudo chmod 644 /etc/systemd/system/mlapi.service
sudo systemctl daemon-reload
# --now also starts the service while enabling it to run on boot
sudo systemctl enable mlapi.service --now

Fail2Ban

Important

You must edit the following example files first before installing them!

A Fail2Ban filter and jail configuration example is provided in the configs/fail2ban directory.

logrotate

Important

You must edit the following example files first before installing them!

A logrotate configuration file example is provided in the configs/logrotate directory.

Docker

Caution

Work is being done to create Docker images for the server.