> 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 엔드포인트 사용
해당 [서버리스 호스팅 API](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api) Roboflow의 클라우드에서 GPU로 모델과 워크플로를 실행합니다. 이미지를 보내면 결과를 돌려받습니다. 설정할 하드웨어도 없고, 계속 실행해 둘 서버도 없습니다.
이 가이드는 아무것도 없는 상태에서 시작해 5분 안에 모델을 실행하는 방법을 안내합니다. 이름만 입력해 이미지에서 객체를 찾고, 준비된 모델로 일상적인 객체를 감지하고, 동일한 Serverless 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 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
import numpy as np
content = requests.get("https://media.roboflow.com/quickstart/traffic.jpg").content
image = cv2.imdecode(np.frombuffer(content, np.uint8), cv2.IMREAD_COLOR)
image_b64 = base64.b64encode(content).decode("utf-8")
h, w = image.shape[:2]
response = requests.post(
"https://serverless.roboflow.com/sam3/concept_segment",
params={"api_key": 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 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 numpy as np
import requests
import supervision as sv
from inference_sdk import InferenceHTTPClient
content = requests.get("https://media.roboflow.com/quickstart/traffic.jpg").content
image = cv2.imdecode(np.frombuffer(content, np.uint8), cv2.IMREAD_COLOR)
h, w = image.shape[:2]
client = InferenceHTTPClient(
api_url="https://serverless.roboflow.com",
api_key=os.environ["ROBOFLOW_API_KEY"],
)
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` 그 모든 것을 대신 읽어줍니다.
텍스트 프롬프트에서 윤곽선이 표시된 객체
시각적 프롬프트, 예시 박스, 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) 모델을 사용하며, 차량, 사람, 반려동물 같은 일반적인 객체를 감지할 수 있습니다:
```python
result = requests.post(
"https://serverless.roboflow.com/coco/40", # coco/40 is the rfdetr-medium alias
params={"api_key": os.environ["ROBOFLOW_API_KEY"]},
data=image_b64, # raw base64 in the body, not JSON
headers={"Content-Type": "application/x-www-form-urlencoded"},
).json()
detections = sv.Detections.from_inference(result)
print(f"개체 {len(detections)}개를 찾았습니다")
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) 모델을 사용하며, 차량, 사람, 반려동물 같은 일반적인 객체를 감지할 수 있습니다:
```python
result = client.infer(image, model_id="rfdetr-medium")
detections = sv.Detections.from_inference(result)
print(f"개체 {len(detections)}개를 찾았습니다")
annotated = sv.BoxAnnotator().annotate(image.copy(), detections)
annotated = sv.LabelAnnotator().annotate(annotated, detections)
cv2.imwrite("rf-detr.jpg", annotated)
```
{% endtab %}
{% endtabs %}
RF-DETR은 자동차, 버스, 사람, 오토바이를 감지합니다
## 직접 만든 모델 또는 다른 모델 실행하기
동일한 `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 전용)
## 다음 단계
클라우드에서 모델을 실행하고 있습니다. 여기서 할 수 있는 일:
* 자신의 하드웨어에서 동일한 모델을 실행합니다. 다음을 참조하세요 [모델을 로컬에서 실행](/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/pricing)