> 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/depth-anything-v2.md). # Depth Anything V2 Depth Anything V2는 단안 깊이 추정 모델입니다. 입력 이미지에 대해 정규화된 깊이 맵(0과 1 사이의 값)을 반환합니다. {% hint style="info" %} Depth Anything V2는 Serverless Hosted API에서 사용할 수 없습니다. 다음에서 실행하세요. [전용 배포](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments) 또는 [자가 호스팅 Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted). {% endhint %} ## 코드 샘플 {% 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://docs.roboflow.com/deployment/self-hosted/self-hosted): ```bash pip install -U inference-sdk opencv-python supervision ``` {% endstep %} {% step %} ### 모델 실행하기 설정하세요 `api_url` 을 전용 배포 URL 또는 로컬 Inference 서버로 설정하세요. 이 스크립트는 깊이 맵에 색을 입히고 입력과 나란히 비교한 결과를 저장합니다. ```python import os import cv2 import numpy as np import supervision as sv from inference_sdk import InferenceHTTPClient image = sv.load_image_from_url("https://media.roboflow.com/notebooks/examples/bicycle.png") client = InferenceHTTPClient( api_url="https://your-deployment.roboflow.cloud", api_key=os.environ["ROBOFLOW_API_KEY"], ) result = client.depth_estimation(image) depth = np.array(result["normalized_depth"], dtype=np.float32) depth = cv2.resize(depth, (image.shape[1], image.shape[0])) depth_vis = (depth * 255).astype(np.uint8) depth_color = cv2.applyColorMap(depth_vis, cv2.COLORMAP_INFERNO) cv2.imwrite("depth_annotated.png", np.hstack([image, depth_color])) ```
{% endstep %} {% endstepper %} ## 추론 속도 다음을 사용해 측정한 지연 시간 [Roboflow Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted) 1x NVIDIA L4, 배치 크기 1, 워밍업 후 평균.
모델지연 시간(ms)
depth-anything-v240.1
Small 체크포인트에서 측정했습니다. {% hint style="info" %} 설정하세요 `api_url` 배포 대상에 맞게 설정하세요: * `http://localhost:9001` 로컬 [Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted) 서버. * 사용자 [전용 배포](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments) 비공개 엔드포인트용 URL. {% endhint %} ## 사용 가능한 모델 깊이 추정 엔드포인트와 `depth_estimation@v1` Workflow 블록은 하나의 순서 기반 깊이 계약 뒤에서 두 개의 모델 계열을 제공합니다. 이미지 크기의 맵이 이미지별로 정규화되며, `1.0` 가장 가까운 값이고 `0.0` 가장 먼 값입니다. * **Depth Anything** (상대 깊이): `depth-anything-v2/small`, `depth-anything-v3/small`, `depth-anything-v3/base` * **YOLO26 깊이** (메트릭 깊이, 이 경로에서는 정규화되며, 훨씬 더 빠름): `yolo26n-depth-768`, `yolo26s-depth-768`, `yolo26m-depth-768`, `yolo26l-depth-768`, `yolo26x-depth-768` 공유 출력은 모델 간에 형태, 범위, 가까움에서 멂까지의 순서를 보존하지만, 중간 값은 모델 계열 간에 기하학적으로 동등하지 않습니다. 값은 실제 거리값이 아니라 서수형 근접도 점수이며, 서로 다른 이미지나 모델 계열 간에 수치적으로 비교해서는 안 됩니다. YOLO26 체크포인트에서 미터 단위의 절대 메트릭 깊이를 얻으려면, 다음으로 직접 불러오세요 `inference_models.AutoModel`. ## 응답 형식 해당 `/infer/depth-estimation` 엔드포인트는 `normalized_depth` 를 요청의 `depth_map_format` 필드에 따라 직렬화합니다: * `json` (기본값): 0과 1 사이의 float 중첩 리스트입니다. 이전 클라이언트와는 와이어 호환되지만, 1080x810 이미지 기준으로 대략 17MB입니다. * `png16` : 16비트 그레이스케일 PNG를 base64로 인코딩한 형식입니다(양자화 단계 1/65535, 보통 10배 이상 작고 제공도 훨씬 빠릅니다). * `png8` : 8비트 그레이스케일 PNG를 base64로 인코딩한 형식입니다(256개의 깊이 수준, 대략 한 차수 더 작음). 시각화와 임계값 처리에는 적합하지만, 미분 기반 기하학적 사용에는 손실이 있습니다. SDK의 `depth_estimation()` 메서드는 기본값으로 `json`설정되어 있으므로, 기존 통합은 계속 중첩 리스트를 받습니다. 전달하세요 `depth_map_format="png16"` (또는 `"png8"`)를 사용해 компакт payload로 전환하세요: SDK가 이를 다시 `numpy.ndarray` 로 디코딩합니다(필요하면 `.tolist()` 를 호출하여 JSON 직렬화 가능한 출력을 얻으세요). {% hint style="warning" %} SDK의 `json` 기본값은 더 이상 사용되지 않습니다. 2027년 Inference의 초기 릴리스 중 하나에서 기본값은 `png16` 호환성을 깨는 방식으로 변경되며, `normalized_depth` 그때는 다음으로 반환됩니다 `numpy.ndarray`. SDK는 다음 경고를 발생시킵니다 `InferenceSDKDeprecationWarning` 해당 `json` 형식을 사용할 때. 미리 사용하도록 전환하려면 `png16` 조기에 사용하거나 다음을 전달하세요 `depth_map_format="json"` 전환 후에도 목록 형식을 유지하려면 명시적으로 지정하세요. Raw REST 호출자는 영향을 받지 않습니다. 서버 측 기본값은 계속 `json`. {% endhint %} ## Inference(자가 호스팅)와 함께 사용 다음으로 모델을 직접 불러올 수도 있습니다. [`inference`](https://docs.roboflow.com/deployment/self-hosted/self-hosted) 패키지. {% stepper %} {% step %} ### 패키지 설치하기 ```bash pip install "inference[transformers]" ``` 사용 `inference-gpu[transformers]` 를 GPU 머신에서 사용하세요. {% endstep %} {% step %} ### Hugging Face로 인증하기 가중치는 Hugging Face에서 가져오므로, 다음을 설정하세요 [Hugging Face 토큰](https://huggingface.co/join): ```bash export HUGGING_FACE_HUB_TOKEN=your_token_here ``` {% endstep %} {% step %} ### 모델 실행하기 ```python from PIL import Image from inference.models.depth_estimation.depthestimation import DepthEstimator model = DepthEstimator() image = Image.open("your_image.jpg") results = model.predict(image) depth_map = results[0]["normalized_depth"] visualization = results[0]["image"] ``` `normalized_depth` 는 이미지별 깊이 맵을 담고 있고, `image` 는 밝은 색일수록 더 가깝고 어두운 색일수록 더 먼 색상화된 시각화를 담고 있습니다. {% endstep %} {% endstepper %} ### Workflows의 실행 모드 다음에서 사용될 때 [Workflow](https://docs.roboflow.com/workflows)에서는 깊이 추정이 두 가지 모드 중 하나로 실행됩니다: * **로컬 실행** : 모델이 사용자 Inference 서버에서 실행됩니다(GPU 권장). * **원격 실행** : 모델은 `depth_estimation()` 클라이언트 메서드를 통해 원격 Inference 서버에서 HTTP로 호출됩니다.