> 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/get-started/ko/guides/run-model-serverless-api.md).

# 모델 API 엔드포인트 사용

별도의 하드웨어 설정 없이 5분 만에 Roboflow의 클라우드 GPU에서 모델을 실행하세요.

Roboflow의 [Serverless Cloud API](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api) 는 Roboflow 클라우드의 GPU에서 모델과 워크플로를 실행합니다. 이미지를 보내면 결과를 받을 수 있습니다. 하드웨어를 설정하거나 계속 실행할 서버를 유지할 필요가 없습니다.

이 가이드를 따라 5분 만에 모델을 실행해 보세요. 객체 이름만 지정해 이미지에서 객체를 찾고, 사전 제작된 모델로 일상적인 객체를 감지하고, 직접 만든 모델도 모두 동일한 Serverless Cloud API 엔드포인트에서 실행할 수 있습니다.

## 이름만 지정해 객체 찾기

모델에 다음과 같은 단어를 몇 개 입력하세요. `"taxi"`, `"blue bus"`, 또는 `"bush"` 이미지에서 일치하는 모든 객체의 윤곽을 표시합니다. 먼저 설정하거나 학습할 필요가 없습니다. 다음을 실행합니다 [SAM3](https://docs.roboflow.com/models/supported-models/sam3).

{% tabs %}
{% tab title="HTTP(Python)" icon="webhook" %}
{% stepper %}
{% step %}

### API 키 가져오기

Roboflow 계정을 만들고, 다음 페이지에서 키를 찾은 뒤 [Roboflow API 설정 페이지](https://app.roboflow.com/settings/api) 셸에서 사용할 수 있도록 설정합니다:

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

{% endstep %}

{% step %}

### 의존 항목 설치

`supervision` 은 다음을 불러옵니다: `cv2` 및 `numpy`:

```bash
pip install -U supervision
```

{% endstep %}

{% step %}

### 모델 실행

모델을 실행하려면 다음으로 POST 요청을 보내세요. `/sam3/concept_segment` 로. `sv.Detections.from_sam3` 해당 결과를 다음 형식으로 변환합니다. [`supervision`](https://supervision.roboflow.com) 에서 그릴 수 있습니다.

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

image = sv.load_image_from_url("https://media.roboflow.com/quickstart/traffic.jpg")
image_b64 = base64.b64encode(content).decode("utf-8")
h, w = image.shape[:2]

response = requests.post(
    "https://serverless.roboflow.com/sam3/concept_segment",
    headers={"Authorization": f"Bearer {os.environ['ROBOFLOW_API_KEY']}"},
    json={
        "image": {"type": "base64", "value": image_b64},
        "prompts": [
            {"type": "text", "text": "taxi"},
            {"type": "text", "text": "blue bus"},
            {"type": "text", "text": "bush"},
        ],
    },
)

detections = sv.Detections.from_sam3(response.json(), (w, h))
annotated = sv.MaskAnnotator().annotate(image.copy(), detections)
cv2.imwrite("sam3.jpg", annotated)
```

{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="SDK(Python)" icon="python" %}
{% stepper %}
{% step %}

### API 키 가져오기

Roboflow 계정을 만들고, 다음 페이지에서 키를 찾은 뒤 [Roboflow API 설정 페이지](https://app.roboflow.com/settings/api) 셸에서 사용할 수 있도록 설정합니다:

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

{% endstep %}

{% step %}

### 의존 항목 설치

이 두 패키지는 모델을 호출하고 결과를 그려 줍니다:

```bash
pip install -U inference-sdk supervision
```

{% endstep %}

{% step %}

### 모델 실행

이 [Inference SDK](https://docs.roboflow.com/reference/inference/inference-sdk) 는 이미지를 클라우드로 전송하고 결과를 반환합니다. `sv.Detections.from_sam3` 이 결과를 다음 형식으로 변환합니다. [`supervision`](https://supervision.roboflow.com) 그릴 수 있습니다:

```python
import os
import cv2
import supervision as sv
from inference_sdk import InferenceHTTPClient, InferenceConfiguration

image = sv.load_image_from_url("https://media.roboflow.com/quickstart/traffic.jpg")
h, w = image.shape[:2]

client = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key=os.environ["ROBOFLOW_API_KEY"],
).configure(InferenceConfiguration(api_key_transport="header"))

data = client.sam3_concept_segment(
    image,
    prompts=[
        {"type": "text", "text": "taxi"},
        {"type": "text", "text": "blue bus"},
        {"type": "text", "text": "bush"},
    ],
)

detections = sv.Detections.from_sam3(data, (w, h))
annotated = sv.MaskAnnotator().annotate(image.copy(), detections)
annotated = sv.BoxAnnotator().annotate(annotated, detections)
cv2.imwrite("sam3.jpg", annotated)
```

{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

응답에는 각 프롬프트에서 찾은 윤곽선과 각각의 신뢰도 점수가 나열됩니다. `sv.Detections.from_sam3` 가 이 모든 데이터를 읽어 옵니다.

<figure><img src="https://83860450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1YMZNIiZMBdlCHUDeZMP%2Fuploads%2Fgit-blob-fc88d211337fc1990e06fab3fc499075fdedd7c1%2Fserverless-sam3-out.jpg?alt=media" alt="Outlines around taxis, a blue bus, and bushes from text prompts"><figcaption><p>텍스트 프롬프트로 윤곽선을 표시한 객체</p></figcaption></figure>

시각적 프롬프트, 예시 바운딩 박스, RLE 출력을 포함한 전체 SAM3 API는 [SAM3 문서](https://docs.roboflow.com/models/supported-models/sam3).

## 기성 모델로 일상적인 객체 감지하기

{% tabs %}
{% tab title="HTTP(Python)" icon="webhook" %}
이름을 지정한 객체의 윤곽선을 표시하는 대신 일반적인 객체 주위에 바운딩 박스를 그리려면 `POST /{project}/{version}` 을 호출할 때 `POST /sam3/concept_segment`대신 모델 ID를 사용합니다. 이 예제에서는 바로 사용할 수 있는 [RF-DETR](https://docs.roboflow.com/models/supported-models/rf-detr) 모델을 사용합니다. 이 모델은 차량, 사람, 반려동물과 같은 일반적인 객체를 감지할 수 있습니다. RF-DETR은 Apache 2.0 라이선스에 따라 상업적 용도로도 무료로 사용할 수 있습니다:

```python
result = requests.post(
    "https://serverless.roboflow.com/coco/40",  # coco/40 is the rfdetr-medium alias
    data=image_b64,  # raw base64 in the body, not JSON
    headers={
        "Authorization": f"Bearer {os.environ['ROBOFLOW_API_KEY']}",
        "Content-Type": "application/x-www-form-urlencoded",
    },
).json()
detections = sv.Detections.from_inference(result)

print(f"Found {len(detections)} objects")

annotated = sv.BoxAnnotator().annotate(image.copy(), detections)
annotated = sv.LabelAnnotator().annotate(annotated, detections)
cv2.imwrite("rf-detr.jpg", annotated)
```

{% endtab %}

{% tab title="SDK(Python)" icon="python" %}
이름을 지정한 객체의 윤곽선을 표시하는 대신 일반적인 객체 주위에 바운딩 박스를 그리려면 `client.infer()` 을 호출할 때 `client.sam3_concept_segment()`대신 모델 ID를 사용합니다. 이 예제에서는 바로 사용할 수 있는 [RF-DETR](https://docs.roboflow.com/models/supported-models/rf-detr) 모델을 사용합니다. 이 모델은 차량, 사람, 반려동물과 같은 일반적인 객체를 감지할 수 있습니다. RF-DETR은 Apache 2.0 라이선스에 따라 상업적 용도로도 무료로 사용할 수 있습니다:

```python
result = client.infer(image, model_id="rfdetr-medium")
detections = sv.Detections.from_inference(result)

print(f"Found {len(detections)} objects")

annotated = sv.BoxAnnotator().annotate(image.copy(), detections)
annotated = sv.LabelAnnotator().annotate(annotated, detections)
cv2.imwrite("rf-detr.jpg", annotated)
```

{% endtab %}
{% endtabs %}

<figure><img src="https://83860450-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1YMZNIiZMBdlCHUDeZMP%2Fuploads%2Fgit-blob-516089a73418852ced8eddbeeb1a94db1bc11421%2Fserverless-rfdetr-out.jpg?alt=media" alt="RF-DETR bounding boxes for cars, buses, people, and motorcycles"><figcaption><p>RF-DETR은 자동차, 버스, 사람, 오토바이를 감지합니다</p></figcaption></figure>

## 직접 학습한 모델 또는 다른 모델 실행하기

동일한 `client.infer()` 또는 `POST /{project}/{version}` 호출로 모든 모델을 해당 모델의 `model_id`:

* 로 실행할 수 있습니다. Roboflow에서 학습한 모델의 모델 ID를 복사하세요(형식은 `{project}/{version}`) 프로젝트에서 [Roboflow 앱](https://app.roboflow.com)
* 다음에서 제공하는 공개 모델: [Roboflow Universe](https://docs.roboflow.com/datasets/universe/universe/what-is-roboflow-universe)
* 바로 사용할 수 있는 [사전 학습된 모델](https://docs.roboflow.com/models/pretrained-aliases) 별칭으로 지정할 수 있습니다. 예: `rfdetr-nano`, `rfdetr-seg-medium`, 또는 `yolo26l-640` (추론 SDK에서만 사용 가능). RF-DETR은 Apache 2.0 라이선스이며, YOLO26은 AGPL-3.0 라이선스입니다. Roboflow에 배포하면 상업용 라이선스가 포함됩니다. 자세한 내용은 [모델 라이선스](https://docs.roboflow.com/models/model-licenses)

## 다음 단계

클라우드에서 모델을 실행하고 있습니다. 여기서 다음 작업을 할 수 있습니다:

* 동일한 모델을 자체 하드웨어에서 실행할 수 있습니다. 자세한 내용은 [모델을 로컬에서 실행](https://docs.roboflow.com/get-started/ko/guides/run-a-model-locally.md)
* 대형 모델과 안정적인 트래픽을 위한 비공개 단일 테넌트 엔드포인트를 사용하려면 [전용 배포](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments)
* 모델과 로직을 연결해 애플리케이션을 만들려면 [워크플로](https://docs.roboflow.com/workflows)
* 각 요청의 비용을 확인하려면 [서버리스 요금 페이지](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api/model-pricing)
