ovkit

OpenVINO inference in one line. One Model class, clean Results, and 19 composed capabilities over 68 ready models — with AUTO/NPU/GPU devices, async throughput, INT8, and your own detector trainable in the same package.

Docs · 한국어 문서 · Model catalog · Examples

from ovkit import Model

r = Model("detect", "image.jpg")      # download -> convert -> cache -> run
print(r)                              # 2x person, car
r.save("out.jpg")                     # the boxes drawn on the photo

One call fits every input — and Korean names work too:

r = Model("얼굴분석", "group.jpg")      # == Model("face_analyze", ...)
for row in r.found:                    # [{'name': '사람', 'name_en': 'person',
    print(row["name"], row["pos"])     #   'score': 0.93, 'box': [...], 'pos': '왼쪽 위'}]

for r in Model("track", 0):            # webcam / video / "mic" -> a stream
    print(r, r.elapsed_ms, r.device)   # 2x person (#1, #4) 14.2 GPU
    if not r.show("track"):            # a window; q or Esc ends the loop
        break

The same call also runs whole capabilities — several models chained into one answer, so you never have to crop, chain and stitch by hand:

r = Model("face_analyze", "group.jpg")
print(r)                # 2 faces: age 31 · male 98% · happy 92%, age 27 · female 95% · neutral 88%

Or without writing Python at all:

ovkit gui                             # a window: pick a capability, point it at your webcam
ovkit run detect image.jpg            # prints results, saves image_out.jpg
ovkit capabilities                    # what Model(name) can answer

Install

pip install ovkit

Extras: ovkit[quant] (INT8/NNCF) · ovkit[genai] (LLM/STT) · ovkit[all]. Python 3.10+. For development, install from source:

git clone https://github.com/leeyunjai82/ovkit.git && cd ovkit
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

python scripts/check.py --fix    # what CI runs: ruff, black, pytest

Capabilities

A capability name gives you the answer, not the plumbing. Each one chains a detector with the models that describe what it found — same Model(...) call, same Results, and it takes the same sources (path, ndarray, folder, video, camera index).

from ovkit import Model, list_pipelines

list_pipelines()                                    # every capability, described
Model("read_text")("sign.jpg")[0].text              # 'STOP AHEAD'
Model("track")(0)                                   # webcam, ids kept across frames
Model("face_analyze", attributes=("age_gender",))   # configure what runs

Aliases: ocr, anpr, blur, driver, describe, faces, people, vehicle, tracking, reid.

Teach your own AI (no GPU)

A Teachable Machine in five lines — an embedding model turns examples into vectors, new inputs match the nearest ones. Five modes: photo (default), face (expressions), hand (needs ovkit[hand]), upper, body:

ai = Model("teach")                       # or Model("가르치기")
ai.learn("can", "photos/cans/")           # a folder per thing to recognise
ai.learn("bottle", "photos/bottles/")
print(ai.guess("new_photo.jpg"))          # ('can', 0.93)
print(ai.score("test_photos/"))           # accuracy + what it confuses
ai.save("recycling")                      # -> Documents/ovkit/recycling.json
for r in ai.predict(0, stream=True): ...  # webcam over YOUR classes

Korean method names work too: 배우기, 맞혀봐, 점수, 저장. Collect examples with the webcam: from ovkit.pipelines.teach import collect; collect("가위", 30).

Any model on the Hugging Face Hub

The Open Model Zoo is an archive; the models people want are on the Hub. optimum-intel converts almost any of them to OpenVINO IR, so ovkit does not have to mirror a model to serve it:

pip install "ovkit[hf]"                      # the converter — needed once
ovkit pull google/vit-base-patch16-224

Model("google/vit-base-patch16-224", "photo.jpg")   # tabby 0.94

Converting is the heavy half and happens once; what lands in the cache is a plain OpenVINO model, so running it afterwards needs nothing but ovkit — a classroom machine can be handed the cache and never see PyTorch. The pull also writes the model's own class names and the normalisation its image processor declares, so results read as answers and not as confident nonsense.

Tasks: image classification, zero-shot (CLIP) classification, feature extraction. Detection and segmentation come from the registry instead (detect, segment) — optimum-intel does not export those.

Train your own detector

RT-DETR, trainable, Apache-2.0 end to end — an Ultralytics-style workflow with no AGPL code or weights anywhere (pip install "ovkit[train]"):

from ovkit import RTDETR

model = RTDETR("rtdetr-r18")                 # COCO weights, downloaded on first use
model.train(data="data.yaml", epochs=100)    # the YOLO-format labels you already have
model.val(data="data.yaml").box.map50        # mAP50 / mAP50-95
model.export(half=True)                      # -> IR + labels.txt

The three sizes are rtdetr_r18 (20M, 46.4 COCO AP — what detect uses), rtdetr_r34 (31M, 48.9) and rtdetr_r50 (43M, 53.1), mirrored like every other model. Running them needs nothing but ovkit; ovkit[train] adds PyTorch for fine-tuning:

Model("detect", "street.jpg")      # r18 — keeps up with a webcam
Model("rtdetr_r50", "street.jpg")  # when you want the accuracy instead

A fine-tuned model's exported IR drops straight into Model("path/to/best.xml") — the labels.txt written next to it means your classes answer by name. CLI: ovkit train --data data.yaml, ovkit val, ovkit export.

Supported tasks

Every single-model task below runs end-to-end through the same 3 lines — swap the alias:

The registry exposes one well-tested model per capability (43 OpenVINO IR + 13 GenAI); the HF mirror hosts the full Apache-2.0 OMZ set (other tiers, int8, sparse variants) — surfacing a variant is a one-line edit (catalog). ovkit list shows everything with descriptions.

Devices

Single images run synchronously; stream=True uses an AsyncInferQueue for video/webcam throughput. INT8: model.quantize(calib_images) (NNCF).

Benchmarks

python scripts/benchmark.py        # prints a paste-ready CPU/GPU/NPU table

Measured on an Intel® Core™ Ultra (Lunar Lake) laptop — CPU / integrated GPU / NPU, median of 30 runs, 1280x720 input, OpenVINO 2026.3. — = model not supported by the NPU compiler (dynamic shapes or unsupported ops).

Usage

from ovkit import Model

model = Model("face_detection")              # alias, name, .xml, or .onnx
results = model("photo.jpg", conf=0.25)      # image / ndarray / folder / video
for r in model.predict(0, stream=True):      # webcam (lazy generator)
    annotated = r.plot()

print(Model("age_gender")("face.jpg")[0].text)   # "age 31 · male 98%"

ovkit run detect image.jpg --save out.jpg   # one-shot inference
ovkit run age_gender face.jpg --device NPU
ovkit list                                  # aliases + models with descriptions
ovkit info face_detection                   # source / task / license
ovkit download detect                       # warm the cache
ovkit devices                               # available OpenVINO devices

from ovkit.genai import pipeline

llm = pipeline("llm")                        # qwen25_1_5b_instruct from the mirror
print(llm.generate("Explain OpenVINO in one sentence.", max_new_tokens=64))

stt = pipeline("stt")                        # whisper_base
print(stt.generate(audio_16k_mono_float32))

pip install -r examples/requirements.txt
python examples/web_app.py                   # http://127.0.0.1:8000

The model mirror

Everything ovkit downloads comes from one repository, leeyunjai/ovkit-models — one copy for an offline site to take, one repository to keep alive. Models that originate elsewhere (the RT-DETR sizes, Depth Anything V2 Small, U2-Net) are copied in, and their home stays registered as the fallback.

To refresh it after adding a model, run the Sync the model mirror workflow from the Actions tab (dry run by default; tick upload to copy). It needs an HF_TOKEN repository secret with write access, set once. The same thing runs locally:

export HF_TOKEN=hf_...
python scripts/sync_mirror.py            # what is missing
python scripts/sync_mirror.py --upload   # copy just that

It lists the target first and copies only what is absent, so re-running is safe.

The traffic goes the other way too. A mirror only ever added to fills up with models that left the lineup and weights uploaded under an old path — and it is the thing a school clones whole:

python scripts/audit_mirror.py           # what no manifest references
python scripts/audit_mirror.py --prune   # delete just that

A model's README.md, LICENSE and labels.txt stay as long as the model does, and go with it when it leaves. Deletions are ordinary Hub commits, so the history still has them.

Adding a model

Models are data, not code — one manifest entry (src/ovkit/manifests/):

my_model:
  src: hf
  repo: leeyunjai/ovkit-models
  filename: detect/my_model/model.xml
  task: detect
  description: Shown by `ovkit list`.
  license: apache-2.0            # must be permissive — enforced at load time

Resolution: alias → local path → cache (~/.cache/ovkit) → download → convert → cache, with atomic writes, sha256 checks, upstream fallback, and OVKIT_OFFLINE=1. Maintainer tooling (mirror build / verify / self-check / benchmark) lives in scripts/ — see the guide.

License

ovkit is Apache-2.0 and license-clean by design: only permissive (Apache/MIT/BSD) models and libraries — no AGPL model stacks, no non-commercial weights; every manifest entry must declare a permissive license (enforced at load time).