> This is the documentation for LibreYOLO 1.5.0. Current version: https://www.libreyolo.com/docs/models/owlv2

# OWLv2
OWLv2 is an open-vocabulary object detector, developed by Google Research, that scores image regions against text embeddings from a CLIP-style encoder. LibreYOLO wraps it as a predict-only family in its open-vocabulary detector tier.
Tasks: Detection. Install: pip install libreyolo.
Verified against LibreYOLO v1.5.0.

## Install

OWLv2 loads through LibreYOLO's open-vocabulary detector tier, which needs the
`openvocab` extra:

```bash
pip install "libreyolo[openvocab]"
```

That extra pulls in `transformers` and `timm`, the Hugging Face libraries this
tier calls into.

## Predict

OWLv2 is not a checkpoint LibreYOLO loads through `LibreYOLO()`. It loads
through the sibling `LibreOpenVocab` factory, which downloads a Hugging Face
snapshot on first use and caches it under `weights/`.

**Python**

```python
from libreyolo import LibreOpenVocab, SAMPLE_IMAGE

model = LibreOpenVocab("owlv2-b16")
model.set_classes(["person", "dog", "skateboard"])

result = model.predict(SAMPLE_IMAGE, conf=0.1)
for box in result.boxes:
    print(box.cls, box.conf, box.xyxy)
```

**Default vocabulary**

```python
from libreyolo import LibreOpenVocab, SAMPLE_IMAGE

# Skipping set_classes() keeps the tier's default COCO-80 vocabulary.
model = LibreOpenVocab("owlv2-l14")
result = model.predict(SAMPLE_IMAGE, conf=0.1)
print(result.names)
```

`set_classes()` sets a sticky text vocabulary: call it again to replace the
list, or skip it to keep the default COCO-80 labels. Each label is wrapped in
a fixed prompt template before it reaches the text tower, matching how
`transformers`' `Owlv2ForObjectDetection` was trained.

OWLv2 has no text-token threshold: only `conf` filters detections, and passing
`text_threshold` raises. `iou` is accepted for API compatibility but warns and
does nothing, since nothing here runs non-maximum suppression. `imgsz` and
`augment=True` are rejected outright: the `transformers` processor owns
resizing, and test-time augmentation is out of scope for this tier.
`predict()` on a single image returns one `Results`, not a list; pass a
directory, a list of images, or `stream=True` for a video source to get
several. There is no CLI path for this family, `libreyolo predict` only loads
`.pt` checkpoints through `LibreYOLO()`, so `LibreOpenVocab` families run from
Python. See [prediction](/docs/v1.5.0/predict) for source types and streaming.

## Variants

Two checkpoints, `b16` (base, patch size 16) and `l14` (large, patch size 14).
`b16` is this tier's default size when none is given. Both mirror the official
Google Research release through `transformers`' `Owlv2ForObjectDetection`,
downloaded once into a LibreYOLO-hosted Hugging Face snapshot that preserves
the upstream files. No accuracy or latency numbers are published for this
family yet.

Training, dataset validation and export are all out of scope for this tier:
`train()`, `val()` and `export()` all raise `NotImplementedError`
unconditionally. This is a predict-only wrapper around a published checkpoint.

## Checkpoints

Every published weight file for this family.

| File | Input (px) | Task | Weights license |
| --- | --- | --- | --- |
| `LibreOWLv2b16.pt` | 960 | Detection | apache-2.0 |
| `LibreOWLv2l14.pt` | 1008 | Detection | apache-2.0 |

## Licensing

Check the license on the Hugging Face repository of the specific weights you download. That repository is authoritative and licenses are not always uniform across a family. This is a description of the licenses involved, not legal advice.

- Original work: OWLv2, Google Research
- Upstream license: Apache-2.0
- Upstream source: https://github.com/google-research/scenic/tree/main/scenic/projects/owl_vit
- LibreYOLO code: MIT
- Weights: Apache-2.0, republished at https://huggingface.co/LibreYOLO
- Interpretation: Apache-2.0 is a permissive license, so these checkpoints can be used in commercial and closed-source products. It asks you to keep the license text and attribution notices with any copy of the weights you redistribute, and it grants a patent license. LibreYOLO vendors no OWLv2 model source of its own: LibreOWLv2 calls the Apache-2.0 `transformers` implementation, `Owlv2ForObjectDetection`, directly, and downloads the official checkpoints into a LibreYOLO-hosted mirror repository that preserves the upstream snapshot files.

## Citation

```bibtex
@article{minderer2023scaling,
  title={Scaling Open-Vocabulary Object Detection},
  author={Matthias Minderer, Alexey Gritsenko, Neil Houlsby},
  journal={NeurIPS},
  year={2023},
}
```

Copied from https://github.com/google-research/scenic/blob/main/scenic/projects/owl_vit/README.md#references


## OWLv2 architecture

- OWLv2 b16: [SVG](/diagrams/models/owlv2/b16-detect.svg), [interactive diagram](/diagrams/models/owlv2/b16-detect.html)
- OWLv2 l14: [SVG](/diagrams/models/owlv2/l14-detect.svg), [interactive diagram](/diagrams/models/owlv2/l14-detect.html)
- OWLv2 family: [SVG](/diagrams/models/owlv2/family-detect.svg), [interactive diagram](/diagrams/models/owlv2/family-detect.html)