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

# Inference SDK

Roboflow Inference Server용 HTTP 클라이언트로, Python에서 로컬, 호스티드, 비동기, 배치 추론을 지원합니다.

그 `inference-sdk` Python 패키지는 제공합니다 `InferenceHTTPClient`, HTTP를 통해 Inference Server와 통신하기 위한 클라이언트입니다 [Inference Server](https://docs.roboflow.com/deployment/self-hosted/inference-server) 입니다. 호환되는 HTTP 메서드의 경우, 이 클라이언트는 Roboflow [서버리스 클라우드 API](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api), a [전용 배포](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments), 자체 호스팅 서버 또는 에지 장치에서 실행 중인 서버로 변경하여 `api_url`. 관리형 라이브 카메라 [클라우드 스트리밍](https://docs.roboflow.com/deployment/roboflow-cloud/cloud-streaming) 별도의 소스와 작업 수명 주기를 사용하며, 이 클라이언트의 `api_url`.

```bash
pip install inference-sdk
```

{% hint style="info" %}
`inference-sdk` 은 얇은 HTTP 클라이언트이며 모델을 직접 실행하지 않습니다. 자체 Python 프로세스 안에서 모델을 로드하고 실행하려면 [`inference` 패키지를 사용하세요](https://docs.roboflow.com/reference/ko/inference/inference-python.md).
{% endhint %}

## 빠른 시작

URL, 파일 경로, PIL 이미지, NumPy 배열에서 추론을 실행할 수 있습니다.

{% tabs %}
{% tab title="URL" %}

```python
from inference_sdk import InferenceHTTPClient, InferenceConfiguration
import os

image_url = "https://media.roboflow.com/inference/soccer.jpg"

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

results = client.infer(image_url, model_id="soccer-players-5fuqs/1")
print(results)
```

{% endtab %}

{% tab title="NumPy 배열" %}

```python
from inference_sdk import InferenceHTTPClient, InferenceConfiguration
import cv2
import os

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

numpy_image = cv2.imread("path/to/local/image.jpg")
results = client.infer(numpy_image, model_id="soccer-players-5fuqs/1")
print(results)
```

{% endtab %}

{% tab title="PIL 이미지" %}

```python
from inference_sdk import InferenceHTTPClient, InferenceConfiguration
from PIL import Image
import os

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

pil_image = Image.open("path/to/local/image.jpg")
results = client.infer(pil_image, model_id="soccer-players-5fuqs/1")
print(results)
```

{% endtab %}
{% endtabs %}

그 `api_key_transport="header"` 설정은 API 키를 오직 `Authorization: Bearer` 헤더로만 전송하여 URL과 로그에서 제외합니다. 릴리스 1.5.0 이상인 추론 서버가 필요합니다. 사용 중인 구형 서버를 계속 호출하려면 `"both"` 를 사용하세요. 참조: [API 키 전송](https://docs.roboflow.com/reference/ko/inference/inference-sdk/configuration.md#api-key-transport) 세 가지 모드에 대해.

자가 호스팅 서버에 대한 첫 요청에서는 모델 가중치가 다운로드되어 설정됩니다. 이 요청은 네트워크 연결과 모델 크기에 따라 다소 시간이 걸릴 수 있습니다. 모델이 다운로드되면 후속 요청은 훨씬 빨라집니다. 또한 [모델을 사전 로드하고 로드된 가중치를 관리](https://docs.roboflow.com/reference/ko/inference/inference-sdk/model-management.md) 하여 이 과정을 제어할 수 있습니다.

{% hint style="info" %}
모델 ID는 문자열 `<project_id>/<version_id>`. 참조: [Workspace 및 Project ID](https://docs.roboflow.com/reference/ko/authentication/authentication/workspace-and-project-ids.md) 에서 자신의 값을 찾으세요.
{% endhint %}

### 자가 호스팅 서버

Inference Server를 직접 호스팅할 수도 있습니다(참조: [Inference CLI](https://docs.roboflow.com/reference/ko/inference/inference-cli.md)), 그런 다음 `api_url` 에서 `InferenceHTTPClient`:

```python
client = InferenceHTTPClient(
    api_url="http://localhost:9001",
    api_key=os.environ["API_KEY"],
)
```

### AsyncIO 클라이언트

```python
import asyncio
from inference_sdk import InferenceHTTPClient

CLIENT = InferenceHTTPClient(
    api_url="http://localhost:9001",
    api_key="ROBOFLOW_API_KEY"
)

image_url = "https://source.roboflow.com/pwYAXv9BTpqLyFfgQoPZ/u48G0UpWfk8giSw7wrU8/original.jpg"
loop = asyncio.get_event_loop()
result = loop.run_until_complete(
  CLIENT.infer_async(image_url, model_id="soccer-players-5fuqs/1")
)
```

## 병렬 및 배치 추론

한 번의 호출로 여러 이미지에 대해 예측하고 싶을 수 있습니다. 다음의 두 매개변수는 [`InferenceConfiguration`](https://docs.roboflow.com/reference/ko/inference/inference-sdk/configuration.md) 배치 처리와 병렬 처리를 제어합니다:

* `max_concurrent_requests` - 시작할 수 있는 최대 동시 요청 수
* `max_batch_size` - 단일 요청에 주입할 수 있는 최대 요소 수

이를 통해 다음과 같은 개선이 가능합니다:

* 강력한 온프레미스 GPU 머신에서 추론 컨테이너를 실행하는 경우, `max_batch_size` 적절히 설정하면 처리량 이점을 얻을 수 있습니다
* 호스팅된 Roboflow API에 대해 추론을 실행하는 경우, `max_concurrent_requests` 설정하면 여러 이미지를 한 번에 서비스할 수 있어 처리량 이점을 얻을 수 있습니다
* 두 옵션을 함께 사용하면 머신 클러스터에서 추론 컨테이너를 실행하는 클라이언트에 유리할 수 있습니다. 단일 노드의 부하를 최적화하고 동시에 서로 다른 노드에 대한 병렬 요청을 보낼 수 있습니다

```python
from inference_sdk import InferenceHTTPClient

image_url = "https://source.roboflow.com/pwYAXv9BTpqLyFfgQoPZ/u48G0UpWfk8giSw7wrU8/original.jpg"

# ROBOFLOW_API_KEY를 Roboflow API 키로 바꾸세요
CLIENT = InferenceHTTPClient(
    api_url="http://localhost:9001",
    api_key="ROBOFLOW_API_KEY"
)
predictions = CLIENT.infer([image_url] * 5, model_id="soccer-players-5fuqs/1")

print(predictions)
```

배치 처리와 병렬 처리를 지원하는 메서드:

* `infer(...)` 및 `infer_async(...)`
* `ocr_image(...)` 및 `ocr_image_async(...)` (강제하여 `max_batch_size=1`)
* `detect_gazes(...)` 및 `detect_gazes_async(...)` - **사용 중단됨**, 항상 `inference_sdk.http.errors.FeatureDeprecatedError`
* `get_clip_image_embeddings(...)` 및 `get_clip_image_embeddings_async(...)`

이 클라이언트는 또한 [핵심 파운데이션 모델](https://docs.roboflow.com/reference/ko/inference/inference-sdk/core-models.md) (CLIP, DocTR), [워크플로 실행](https://docs.roboflow.com/reference/ko/inference/inference-sdk/workflows.md) 다단계 파이프라인용이며, [WebRTC 스트리밍](https://docs.roboflow.com/reference/ko/inference/inference-sdk/webrtc.md) 을 자가 호스팅 Inference Server에서 사용할 수 있습니다. 새 관리형 라이브 카메라 처리는 [클라우드 스트리밍](https://docs.roboflow.com/deployment/roboflow-cloud/cloud-streaming)를 사용하세요. WebRTC 참조는 기존 통합을 위해 사용 중단된 호스팅 API 세부 정보를 유지합니다.

## 예측으로 실제로 반환되는 것은 무엇인가요?

`InferenceHTTPClient` 모델 서빙 API의 응답인 일반 Python 사전을 반환합니다. 수정은 오직 `시각화` 키의 맥락에서만 수행되며, 서버가 생성한 예측 시각화를 유지하고 원하는 형식으로 트랜스코딩할 수 있습니다. 클라이언트 측 리스케일링은 입력 크기만 조정합니다.

## 다음 단계

* [구성](https://docs.roboflow.com/reference/ko/inference/inference-sdk/configuration.md) - 클라이언트 및 모델 매개변수, 컨텍스트 관리자, 기본값.
* [모델 관리](https://docs.roboflow.com/reference/ko/inference/inference-sdk/model-management.md) - 서버에서 모델을 사전 로드, 목록 표시, 언로드합니다.
* [핵심 모델](https://docs.roboflow.com/reference/ko/inference/inference-sdk/core-models.md) - CLIP 및 DocTR 엔드포인트.
* [워크플로](https://docs.roboflow.com/reference/ko/inference/inference-sdk/workflows.md) - 클라이언트를 통해 워크플로를 실행합니다.
* [클라우드 스트리밍](https://docs.roboflow.com/deployment/roboflow-cloud/cloud-streaming): 관리형 라이브 카메라 소스, 워크플로 작업, 결과.
* [WebRTC 스트리밍](https://docs.roboflow.com/reference/ko/inference/inference-sdk/webrtc.md): 자가 호스팅 서버에서 모델 또는 워크플로를 통해 비디오를 스트리밍하거나 기존 레거시 통합을 유지합니다.
