> 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/reference/ko/inference/inference-python/native-python-api.md).

# 네이티브 Python API

기본 Python API는 Inference를 사용하는 가장 간단한 방법으로, 기본 패키지 API에 직접 접근하는 방식을 사용합니다. 이 경로를 따르면 Inference 모듈을 Python 코드에 직접 가져와 사용하게 됩니다. 모델을 로드하고, 추론을 실행하고, 결과를 모두 직접 만든 로직 안에서 처리합니다. 또한 Python 환경 내에서 종속성도 관리해야 합니다. 간단한 앱을 만들거나 단순히 테스트하는 경우라면, 기본 Python API가 시작하기에 좋은 곳입니다.

기본 Python API를 사용할 때는 모델을 로드한 다음, 그 모델의 `infer(...)` 메서드를 호출해 추론 결과를 얻습니다.

## 빠른 시작

이 예시는 모델을 로드하고, 추론을 실행한 다음, 결과를 표시하는 방법을 보여줍니다.

다음을 사용하는 것을 권장합니다. [Python 가상 환경(venv)](https://docs.python.org/3/tutorial/venv.html) 를 사용해 Inference의 종속성을 분리하세요.

```bash
pip install inference
```

NVIDIA GPU가 있다면, 다음으로 추론을 가속할 수 있습니다:

```bash
pip install --extra-index-url https://download.pytorch.org/whl/cu124 inference-gpu
# 설치된 OS의 CUDA 버전에 맞게 --extra-index-url을 조정하세요
```

다음으로, 모델을 가져옵니다:

```python
from inference import get_model

model = get_model(model_id="rfdetr-large")
```

해당 `get_model` 메서드는 Roboflow에서 컴퓨터 비전 모델을 불러오는 유틸리티 함수입니다. 우리는 해당 모델의 `model_id`. Roboflow 모델의 경우, 모델 ID는 프로젝트 이름과 버전 번호의 조합입니다: `f"{project_name}/{version_number}"`.

{% hint style="success" %}
모델의 프로젝트 이름과 버전 번호는 [Roboflow 앱](/reference/ko/authentication/authentication/workspace-and-project-ids.md). 또한 [Roboflow Universe](https://universe.roboflow.com/). 이 예시에서는 COCO 사전 학습 모델의 별칭인 특수 모델 ID를 사용하고 있습니다. 다음을 참고하세요. [사전 학습 모델 별칭](https://docs.roboflow.com/models/pretrained-aliases) 별칭 목록을 확인하세요.
{% endhint %}

다음으로, 입력 이미지를 제공하여 모델로 추론을 실행할 수 있습니다:

```python
from inference import get_model

model = get_model(model_id="rfdetr-large")

results = model.infer("people-walking.jpg") # 이미지 경로로 바꿔주세요
```

results 객체는 추론 응답 객체입니다(예: `ObjectDetectionInferenceResponse`, 정의는 [`inference/core/entities/responses/inference.py`](https://github.com/roboflow/inference/blob/main/inference/core/entities/responses/inference.py)). 여기에는 일부 메타데이터(예: 처리 시간)와 예측 배열이 포함됩니다. 응답의 유형과 속성은 모델 유형에 따라 달라집니다.

이제 다음을 사용해 결과를 시각화해 봅시다. [Supervision](https://supervision.roboflow.com):

```python
from inference import get_model
import supervision as sv
import cv2

# 모델 로드
model = get_model(model_id="rfdetr-large")

# cv2로 이미지 로드
image = cv2.imread("people-walking.jpg")

# 추론 실행
results = model.infer(image)[0]

# 결과를 Supervision Detection API에 로드
detections = sv.Detections.from_inference(results)

# Supervision annotator 생성
bounding_box_annotator = sv.BoxAnnotator()
label_annotator = sv.LabelAnnotator()

# 추론 결과에서 레이블 배열 추출
labels = [p.class_name for p in results.predictions]

# Supervision annotator를 사용해 결과를 이미지에 적용
annotated_image = bounding_box_annotator.annotate(scene=image, detections=detections)
annotated_image = label_annotator.annotate(
    scene=annotated_image, detections=detections, labels=labels
)

# 주석이 추가된 이미지를 파일로 저장하거나 이미지 표시
sv.plot_image(annotated_image)
```

<img src="https://storage.googleapis.com/com-roboflow-marketing/inference/people-walking-annotated.jpg" alt="주석이 추가된 사람들의 걷는 모습" width="100%">

## 다양한 이미지 유형

해당 `infer(...)` 메서드는 PIL 이미지, OpenCV 이미지(NumPy 배열), 로컬 이미지 경로, 이미지 URL 등 다양한 형식의 이미지를 허용합니다. 내부적으로 모델은 `load_image(...)` 의 [`image_utils` 모듈의](https://github.com/roboflow/inference/blob/main/inference/core/utils/image_utils.py).

```python
from inference import get_model

import cv2
from PIL import Image

model = get_model(model_id="rfdetr-large")

image_url = "https://media.roboflow.com/inference/people-walking.jpg"
local_image_file = "people-walking.jpg"
pil_image = Image.open(local_image_file)
numpy_image = cv2.imread(local_image_file)

results = model.infer(image_url)
# 또는     = model.infer(local_image_file)
# 또는     = model.infer(pil_image)
# 또는     = model.infer(numpy_image)
```

## 추론 매개변수

해당 `infer(...)` 메서드는 추론 매개변수를 설정하기 위한 키워드 인자를 허용합니다. 아래 예시는 신뢰도 임계값과 IoU 임계값을 설정하는 방법을 보여줍니다.

```python
from inference import get_model

model = get_model(model_id="rfdetr-large")

results = model.infer("people-walking.jpg", confidence=0.75, iou_threshold=0.5)
```

## 다음 단계

* [추론 파이프라인](/reference/ko/inference/inference-python/inference-pipeline.md) - 비디오 스트림에서 동일한 모델을 실행합니다.
* [모델 가중치 다운로드](/reference/ko/inference/inference-python/offline-weights.md) - 가중치가 캐시되는 위치를 제어합니다.