> 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

NVIDIA의 Cosmos 3 Edge 비전-언어 월드 모델을 서버리스 클라우드 API를 통해 사용

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

{% hint style="info" %}
자체 호스팅 Cosmos 3 Edge에는 CUDA를 지원하는 GPU가 필요합니다. CPU에서는 실행할 수 없습니다. 다음 환경에서 실행하세요:  [Serverless Cloud API](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api),  [Dedicated Deployment](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments) 의 GPU 환경 또는 GPU를 사용하는  [자체 호스팅 Inference](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="What is likely going to happen next in this scene?",
    max_new_tokens=128,
)
print(result["response"])
```

{% endstep %}
{% endstepper %}

위 코드는 모델 응답을 터미널에 출력합니다. 다음은 샘플 이미지에 대한 결과입니다:

<figure><img src="https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-cb5b18a7741195d6a2a5be4d730ddea029cc0ce7%2Fcosmos-3-edge-reasoning.webp?alt=media" 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를 미세 조정할 수 있습니다. 프로젝트에서 "학습"을 열고 "사용자 지정 학습"을 클릭한 다음 모델 아키텍처 목록에서 "Cosmos 3"를 선택합니다. Cosmos 3는 베타 버전이며 유료 요금제가 필요합니다. 나머지 과정은  [모델 학습](https://docs.roboflow.com/models/ko/train/train-a-model.md) 을, 데이터 세트 준비 방법은  [멀티모달 데이터 주석 달기](https://docs.roboflow.com/datasets/annotate/annotate/annotate-multimodal-data) 를 참조하세요.

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

Cosmos 3 Edge는 다음에서 사용할 수 있습니다:  [워크플로](https://docs.roboflow.com/workflows) "Cosmos 3" 블록으로. 이 블록은 이미지와 선택적 텍스트 `prompt` (기본값 `"Describe what's in this image."`) 및 선택적 시스템 프롬프트를 입력으로 받아 모델의 텍스트 응답을 출력합니다. 이 출력을 후속 블록에 연결해 파싱, 필터링 또는 알림을 처리할 수 있습니다.

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

* `https://serverless.roboflow.com` Serverless Cloud API를 사용하는 경우.
* `http://localhost:9001` 로컬 [Inference](https://inference.roboflow.com/) 서버를 사용하는 경우.
* 비공개 엔드포인트의 [Dedicated Deployment](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  # serves 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="What is likely going to happen next in this scene?",
)
print(result["response"])
```

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

HTTP 서버 없이도 [Inference](https://inference.roboflow.com/) Python 패키지를 사용해 모델을 프로세스 내에서 실행할 수 있습니다. Cosmos 종속 항목은 `-cosmos3` Docker 이미지에만 포함되어 있으므로, 해당 이미지 안에서 스크립트를 실행하세요. 다음을 생성합니다: `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="What is likely going to happen next in this scene?",
)

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` 에서 사용하는 캐시 디렉터리와 동일합니다.
