> 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.md).

# Inference Python 패키지

이 `inference` Python 패키지는 Roboflow의 컴퓨터 비전 배포 스택을 구동하는 핵심 오픈 소스 라이브러리입니다. 모델 로딩, 전/후처리, GPU/CPU 최적화, 그리고 [워크플로](https://docs.roboflow.com/workflows) 실행을 제공하며, Python에서 직접 호출할 수 있습니다.

이 [Inference Server](https://docs.roboflow.com/deployment/self-hosted/inference-server) 이 패키지를 래핑하여 HTTP로 노출합니다(모든 종속성이 설치된 Docker 이미지로 배포됨). 하지만 또한 `inference` 자신의 스크립트와 애플리케이션에서 직접 사용할 수도 있습니다.

## 각 구성 요소가 어떻게 맞물리는가

Inference에는 컴퓨터 비전 모델을 서비스하기 위해 함께 작동하는 여러 구성 요소가 있습니다:

* [**inference**](/reference/ko/inference/inference-python.md) - 모델 로딩, 추론, Workflows 실행을 위한 핵심 Python 패키지.
* [**inference-sdk**](/reference/ko/inference/inference-sdk.md) - HTTP를 통해 Inference Server와 통신하는 경량 Python 클라이언트.
* [**inference-cli**](/reference/ko/inference/inference-cli.md) - Inference Server를 관리하고 일반 작업을 실행하는 명령줄 도구.
* [**Inference Server**](https://docs.roboflow.com/deployment/self-hosted/inference-server) - 다음을 래핑하는 HTTP 서버(Docker): `inference` 패키지를 REST API로.

이 구성 요소들이 런타임에서 어떻게 동작하는지(요청 라우팅, 병렬화, 마이크로서비스 및 어플라이언스 패턴)는 다음을 참조하세요: [Inference 아키텍처](https://docs.roboflow.com/deployment/self-hosted/inference-server/architecture).

## 다중 백엔드 지원

Inference 1.0은 ONNX, TensorRT, Hugging Face, PyTorch 등 여러 추론 런타임 백엔드를 지원합니다. 하드웨어에서 가장 빠르게 사용 가능한 백엔드를 자동으로 선택합니다. 예를 들어 NVIDIA GPU가 있거나 Jetson 장치에서 실행 중이고, 플랫폼에서 해당 모델에 사용할 수 있는 TensorRT 엔진이 있다면 Inference는 기본적으로 TensorRT를 사용합니다.

## 설치

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

pip을 통해 Inference를 설치하려면:

```bash
pip install inference
```

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

```bash
pip install --extra-index-url https://download.pytorch.org/whl/cu124 inference-gpu
# --extra-index-url를 OS에 설치된 CUDA 버전에 맞게 조정하세요
# https://download.pytorch.org/whl/cu<major><minor>, 예를 들어 CUDA 13.0의 경우 https://download.pytorch.org/whl/cu130
```

## 간단한 예시

HTTP를 통해 Inference Server에 대해 추론을 실행할 수 있습니다( `inference-sdk`) 또는 프로세스 내에서 직접 실행할 수 있습니다(기본 제공 `inference` 패키지). 기본 제공 `get_model()` 호출은 모델을 스크립트에 로드하고 호출할 수 있는 객체를 반환합니다 `.infer()` 에 대해; HTTP 클라이언트는 이미지를 동일한 작업을 수행하는 서버로 전송합니다.

{% tabs %}
{% tab title="추론(기본)" %}

```python
from inference import get_model

model = get_model(model_id="rfdetr-small")
results = model.infer("https://media.roboflow.com/inference/people-walking.jpg")
```

{% endtab %}

{% tab title="inference-sdk(HTTP 클라이언트)" %}

```python
from inference_sdk import InferenceHTTPClient, InferenceConfiguration

client = InferenceHTTPClient(
    # api_url="http://localhost:9001",  # 자체 호스팅용
    api_url="https://serverless.roboflow.com",
    api_key="ROBOFLOW_API_KEY",
).configure(InferenceConfiguration(api_key_transport="header"))
results = client.infer(
    "https://media.roboflow.com/inference/people-walking.jpg",
    model_id="rfdetr-small",
)
```

{% endtab %}
{% endtabs %}

API 키가 필요한 모델을 사용하려면 다음을 설정하세요: `ROBOFLOW_API_KEY` 환경 변수를 설정하거나 직접 전달하세요:

```python
model = get_model(model_id="my-project/1", api_key="ROBOFLOW_API_KEY")
```

다음을 참조하세요 [기본 Python API](/reference/ko/inference/inference-python/native-python-api.md) 시각화가 포함된 더 자세한 안내는 페이지를 참조하고, [모델 실행](https://docs.roboflow.com/deployment/self-hosted/self-hosted#run-a-model) 서버 기반 경로는

## Inference 파이프라인

`InferencePipeline` 비디오를 다음과 동일한 Python 프로세스 내에서 실행합니다: `inference` 패키지. 직접 Inference Library 실행을 선택하고 해당 사용자 정의 로직이나 싱크 인터페이스에 접근해야 할 때만 사용하세요. Inference Server 또는 Serverless를 사용하는 애플리케이션은 다음을 사용해야 합니다: [WebRTC 스트리밍](/reference/ko/inference/inference-sdk/webrtc.md).

```python
from inference import InferencePipeline
from inference.core.interfaces.stream.sinks import render_boxes

pipeline = InferencePipeline.init(
    model_id="rfdetr-large",
    video_reference="https://storage.googleapis.com/com-roboflow-marketing/inference/people-walking.mp4",
    on_prediction=render_boxes,
    api_key="ROBOFLOW_API_KEY",
)

pipeline.start()
pipeline.join()
```

위 코드는 객체 탐지 주석을 직접 수행합니다(다음을 통해: `render_boxes` 싱크). 자세한 내용은 다음을 참조하세요: [Inference 파이프라인](/reference/ko/inference/inference-python/inference-pipeline.md) 페이지.

## 기여하기

Inference는 오픈 소스입니다. 소스 코드, 이슈 트래커, 기여 가이드는 다음에 있습니다: [roboflow/inference](https://github.com/roboflow/inference) 저장소; 다음을 참조하세요: [CONTRIBUTING.md](https://github.com/roboflow/inference/blob/main/CONTRIBUTING.md) 시작하려면.

## 다음 단계

* [기본 Python API](/reference/ko/inference/inference-python/native-python-api.md) - 모델을 로드하고 자신의 프로세스에서 추론을 실행합니다.
* [Inference 파이프라인](/reference/ko/inference/inference-python/inference-pipeline.md) - 비디오 스트림에서 모델을 실행합니다.
* [모델 가중치 다운로드](/reference/ko/inference/inference-python/offline-weights.md) - 가중치 캐싱 및 지속적 저장.
* [벤치마크](/reference/ko/inference/inference-python/benchmarks.md) - 일반적인 하드웨어에서 측정된 처리량.