> 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/models/ko/supported-models/cosmos-3-edge.md).

# Cosmos 3 Edge

Cosmos 3 Edge는 NVIDIA의 비전-언어 "월드 모델"입니다. 이는 물리적 장면 이해에 맞춰 조정되어 있으며, 객체 간의 공간 관계를 추론하고, 장면을 안전 조건과 대조해 확인하며, 다음에 일어날 가능성이 높은 일을 예측합니다. 이미지를 입력하고 텍스트 프롬프트를 받아 텍스트 응답을 반환하며, 동작을 조정하기 위한 선택적 시스템 프롬프트를 사용할 수 있습니다. 우리는 Cosmos 3 Edge를 다음을 통해 지원합니다 [서버리스 클라우드 API](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api), [전용 배포](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments), 그리고 [자체 호스팅 추론](https://inference.roboflow.com/).

{% hint style="info" %}
자체 호스팅 Cosmos 3 Edge에는 CUDA 지원 GPU가 필요합니다. CPU에서는 실행할 수 없습니다. 다음에서 실행하세요 [서버리스 클라우드 API](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api),  [전용 배포](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments) GPU가 있는 배포 또는 GPU 기반 [자체 호스팅 추론](https://inference.roboflow.com/) 서버에서.
{% endhint %}

## Cosmos 3 Edge API

{% stepper %}
{% step %}

### API 키를 받으세요

Roboflow 계정을 만들고, 다음에서 키를 찾으세요 [Roboflow API 설정 페이지](https://app.roboflow.com/settings/api) 그리고 셸에서 사용할 수 있게 만드세요:

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

{% endstep %}

{% step %}

### 의존성을 설치하세요

설치하세요 [Inference SDK](https://inference.roboflow.com/):

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

{% endstep %}

{% step %}

### 모델 실행

예제는 `nvidia/cosmos-3-edge` 모델에 이미지에 관한 물리 추론 질문을 하고 응답을 출력합니다.

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

image = cv2.imread("my-image.jpg")
client = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key=os.environ["ROBOFLOW_API_KEY"],
).configure(InferenceConfiguration(api_key_transport="header"))
result = client.infer_lmm(
    image,
    model_id="nvidia/cosmos-3-edge",
    prompt="이 장면에서 다음에 무슨 일이 일어날 가능성이 높습니까?",
    max_new_tokens=128,
)
print(result["response"])
```

{% endstep %}
{% endstepper %}

위 코드는 모델 응답을 터미널에 출력합니다. 샘플 이미지에서의 결과는 다음과 같습니다:

<figure><img src="/files/956fcc7a8364df692dbaa3649f1e67e77d2cd547" alt="Cosmos 3 Edge predicting what will happen next in a street scene with a red SUV"><figcaption><p>Cosmos 3 Edge는 장면에서 다음에 일어날 가능성이 높은 일을 예측합니다.</p></figcaption></figure>

## 워크플로우에서 Cosmos 3 Edge 사용

Cosmos 3 Edge는 [워크플로우](https://docs.roboflow.com/workflows) 에서 "Cosmos 3" 블록으로 사용할 수 있습니다. 이 블록은 이미지와 선택적 텍스트 `프롬프트` (기본값 `"이 이미지에 무엇이 있는지 설명하세요."`), 그리고 선택적 시스템 프롬프트를 받아 모델의 텍스트 응답을 출력합니다. 이 출력을 파싱, 필터링 또는 알림을 위한 하위 단계 블록으로 연결할 수 있습니다.

{% hint style="info" %}
설정하세요 `api_url` 를 배포 대상에 맞게:

* `https://serverless.roboflow.com` 서버리스 클라우드 API용.
* `http://localhost:9001` 로컬 [Inference](https://inference.roboflow.com/) 서버에서.
* 귀하의 [전용 배포](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments) 비공개 엔드포인트용 URL입니다.
  {% endhint %}

## 자체 호스팅 Inference로 Cosmos 3 Edge 실행

Cosmos 3 Edge는 사용자가 직접 호스팅하는 [Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted) 서버에서도 실행됩니다.

{% hint style="warning" %}
자체 호스팅 Cosmos 3 Edge에는 CUDA 지원 GPU와 GPU Inference 서버 Docker 이미지의 Cosmos 빌드( `-cosmos3` 접미사가 붙은 태그, 예: `roboflow/roboflow-inference-server-gpu:1.3.9-cosmos3`). 이 모델은 해당 이미지 내부에만 포함된 사전 릴리스 `transformers` 빌드에 의존합니다. 표준 `latest` 이미지로는 실행할 수 없으며, `inference` Python 패키지를 pip으로 설치하는 것만으로는 충분하지 않습니다.
{% endhint %}

Cosmos 이미지로 로컬 서버를 시작하세요:

```bash
pip install inference-cli
inference server start --image roboflow/roboflow-inference-server-gpu:1.3.9-cosmos3  # http://localhost:9001 제공
```

그런 다음 동일한 SDK 코드를 서버에 연결하세요:

```python
import os
from inference_sdk import InferenceHTTPClient

client = InferenceHTTPClient(
    api_url="http://127.0.0.1:9001",
    api_key=os.environ["ROBOFLOW_API_KEY"],
)

result = client.infer_lmm(
    inference_input="./my-image.jpg",
    model_id="nvidia/cosmos-3-edge",
    prompt="이 장면에서 다음에 무슨 일이 일어날 가능성이 높습니까?",
)
print(result["response"])
```

## Inference Python 패키지로 Cosmos 3 Edge 실행

또한 HTTP 서버 없이 [Inference](https://inference.roboflow.com/) Python 패키지로 모델을 프로세스 내에서 실행할 수 있습니다. Cosmos 종속성은 `-cosmos3` Docker 이미지에만 포함되어 있으므로, 해당 이미지 내부에서 스크립트를 실행하세요. Create `app.py`:

```python
from inference import get_model

model = get_model("nvidia/cosmos-3-edge", api_key="YOUR_ROBOFLOW_API_KEY")

result = model.infer(
    "https://media.roboflow.com/dog.jpeg",
    prompt="이 장면에서 다음에 무슨 일이 일어날 가능성이 높습니까?",
)

print(result[0].response)
```

그런 다음 Cosmos 이미지 내부에서 실행하세요:

```bash
docker run --rm --gpus all \\
  -v $(pwd):/workspace -w /workspace \\
  -v /tmp/model-cache:/tmp/model-cache -e MODEL_CACHE_DIR=/tmp/model-cache \\
  --entrypoint python3 \\
  roboflow/roboflow-inference-server-gpu:1.3.9-cosmos3 app.py
```

이 `/tmp/model-cache` 마운트는 다운로드한 가중치를 실행 간에 유지합니다. 이는 동일한 캐시 디렉터리입니다 `inference server start` 사용합니다.