ovkit

OpenVINO inference in 3 lines. One Model class, clean Results, 30+ ready models — with AUTO/NPU/GPU devices, async throughput, and INT8.

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

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]"

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).

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")                 # or RTDETR("best.pt") to resume
model.train(data="data.yaml", epochs=100)    # the YOLO-format labels you already have
model.val(data="data.yaml")                  # mAP50 / mAP50-95
model.export(half=True)                      # -> IR + labels.txt

r = model("bus.jpg", conf=0.5)               # ovkit Results: print(r), r.found, r.save()

The exported IR drops straight into Model("path/to/rtdetr-r18.xml") — the labels.txt written next to it means your classes answer by name. CLI: ovkit train --data data.yaml, ovkit val, ovkit export. ovkit capabilities prints the list; ovkit gui opens a window where you can click through them against your webcam or a picture.

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 (35 total); 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")                        # tinyllama_chat 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

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).