> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/models/ko/supported-models/owlv2.md).

# OWLv2

OWLv2 원샷 객체 감지 API를 전용 배포 또는 자체 호스팅 추론에서 실행

OWLv2는 Google의 개방형 어휘 객체 탐지기입니다. 참조 이미지에 하나 이상의 예시 바운딩 박스를 제공하면, OWLv2는 학습 없이 대상 이미지에서 유사한 객체를 탐지합니다.

{% hint style="info" %}
OWLv2는 Serverless Cloud API에서 사용할 수 없습니다. 다음에서 실행하세요: [전용 배포](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments) 또는 [자체 호스팅 추론](https://docs.roboflow.com/deployment/self-hosted/self-hosted).
{% endhint %}

## OWLv2 API

{% stepper %}
{% step %}

### API 키 받기

Roboflow 계정을 만들고, [Roboflow API 설정 페이지](https://app.roboflow.com/settings/api) 에서 키를 찾아 셸에서 사용할 수 있게 하세요:

```bash
export ROBOFLOW_API_KEY="your-key-here"
```

{% endstep %}

{% step %}

### 의존성을 설치하세요

이 패키지들은 API를 호출하고 그 결과를 그립니다:

```bash
pip install -U requests supervision opencv-python
```

{% endstep %}

{% step %}

### 모델 실행

아래 샘플은 입력 이미지의 단일 예시 박스를 프롬프트로 사용하여 같은 이미지에서 일치하는 객체를 탐지합니다. 실제로는 보통 별도의 참조 이미지를 전달합니다. 다음을 설정하세요: `URL` 전용 배포 URL 또는 로컬 추론 서버에.

```python
import base64
import os
import cv2
import numpy as np
import requests
import supervision as sv

URL = "https://your-deployment.roboflow.cloud"
image = sv.load_image_from_url("https://media.roboflow.com/notebooks/examples/dog.jpeg")
_, buffer = cv2.imencode(".jpg", image)
image_base64 = base64.b64encode(buffer).decode("utf-8")

response = requests.post(
    f"{URL}/owlv2/infer",
    headers={"Authorization": f"Bearer {os.environ['ROBOFLOW_API_KEY']}"},
    json={
        "image": {"type": "base64", "value": image_base64},
        "training_data": [{
            "image": {"type": "base64", "value": image_base64},
            "boxes": [{"x": 360, "y": 800, "w": 500, "h": 500, "cls": "dog"}],
        }],
        "confidence": 0.99,
    },
)
preds = response.json()["predictions"]

xyxys = [
    [p["x"] - p["width"] / 2, p["y"] - p["height"] / 2,
     p["x"] + p["width"] / 2, p["y"] + p["height"] / 2]
    for p in preds
]
detections = sv.Detections(
    xyxy=np.array(xyxys, dtype=float),
    class_id=np.array([p.get("class_id", 0) for p in preds]),
    confidence=np.array([p["confidence"] for p in preds], dtype=float),
    data={"class_name": np.array([p["class"] for p in preds])},
)
labels = [f"{p['class']} {p['confidence']:.2f}" for p in preds]
annotated = sv.BoxAnnotator().annotate(image.copy(), detections)
annotated = sv.LabelAnnotator().annotate(annotated, detections, labels=labels)
cv2.imwrite("dog_annotated.png", annotated)
```

<figure><img src="https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-f4adb52af13e34818467da65a9b2becda5b6355e%2Fowlv2-detection.webp?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

## OWLv2 추론 속도

다음을 사용하여 측정한 지연 시간 [Roboflow Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted) 에서 NVIDIA L4 1개, 배치 크기 1, 워밍업 후 평균.

<table data-search="false"><thead><tr><th>모델</th><th>지연 시간(ms)</th></tr></thead><tbody><tr><td><code>owlv2</code></td><td>541.2</td></tr></tbody></table>

다음에서 측정됨: `owlv2-large-patch14-ensemble` 두 개의 텍스트 프롬프트가 있는 체크포인트.

{% hint style="info" %}
설정하세요 `URL` 를 배포 대상에 맞게:

* `http://localhost:9001` 로컬 [Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted) 서버용입니다.
* 귀하의 [전용 배포](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments) 는 비공개 엔드포인트의 URL입니다.
  {% endhint %}

OWLv2의 신뢰도는 보통 매우 높습니다(0.99 이상). 다음을 조정하세요: `confidence` 매개변수를 그에 맞게.

## 자체 호스팅 Inference로 OWLv2 실행하기

OWLv2는 다음을 사용해 직접 로드할 수 있습니다. [`inference`](https://docs.roboflow.com/deployment/self-hosted/self-hosted) 패키지. Inference의 구현은 다음에서 객체를 탐지합니다. *시각적* 예시: 하나 이상의 예시 객체를 박스로 지정하면, 모델이 유사한 객체를 찾습니다.

{% stepper %}
{% step %}

### 패키지를 설치하세요

```bash
pip install "inference[transformers]"
```

사용 `inference-gpu[transformers]` GPU 머신에서.
{% endstep %}

{% step %}

### 모델 실행

```python
import base64
import io

from PIL import Image

from inference.core.entities.requests.owlv2 import OWLv2InferenceRequest
from inference.models.owlv2.owlv2 import OWLv2

image = {"type": "url", "value": "https://media.roboflow.com/inference/seawithdock.jpeg"}

request = OWLv2InferenceRequest(
    image=image,
    training_data=[
        {
            "image": image,
            "boxes": [{"x": 223, "y": 306, "w": 40, "h": 226, "cls": "post"}],
        }
    ],
    visualize_predictions=True,
    confidence=0.9999,
)

response = OWLv2().infer_from_request(request)

visualization = Image.open(io.BytesIO(response.visualization))
visualization.save("owlv2_visualization.jpg")
```

바꾸세요 `training_data` 일치시키고 싶은 예시 객체와 함께, 이미지 URL은 자신의 입력으로 바꾸세요. 주석이 달린 결과는 다음에 저장됩니다. `owlv2_visualization.jpg`.
{% endstep %}
{% endstepper %}