Merge pull request #193 from roboflow/feature/introduce_model_aliases

Introduce model aliases

Author: PawelPeczek-Roboflow

docs/quickstart/explore_models.md

@@ -2,6 +2,17 @@ With Inference, you can run any of the 50,000+ models available on Roboflow Univ
 
 All models run on your own hardware.
 
+## Run pre-trained YOLOv8 model
+Roboflow Universe exposes pre-trained YOLOv8 models.
+
+* object-detection: `yolov8{model_size}-{inference_resolution}`
+  * supported model sizes: `[n, s, m, l, x]`
+  * supported inference resolutions: `[640, 1280]`
+
+* instance-segmentation: `yolov8{model_size}-seg-{inference_resolution}`
+  * supported model sizes: `[n, s, m, l, x]`
+  * supported inference resolutions: `[640, 1280]`
+
 ## Run a Model on Universe
 
 In the first example, we showed how to run a rock paper scissors model. This model was hosted on Universe. Let's find another model to try.

inference/core/models/roboflow.py

@@ -60,6 +60,7 @@
 from inference.core.utils.onnx import get_onnxruntime_execution_providers
 from inference.core.utils.preprocess import letterbox_image, prepare
 from inference.core.utils.visualisation import draw_detection_predictions
+from inference.models.aliases import resolve_roboflow_model_alias
 
 NUM_S3_RETRY = 5
 SLEEP_SECONDS_BETWEEN_RETRIES = 3
@@ -123,7 +124,7 @@ def __init__(
                 f"Visit https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key to learn how to "
                 f"retrieve the key."
             )
-
+        model_id = resolve_roboflow_model_alias(model_id=model_id)
         self.dataset_id, self.version_id = model_id.split("/")
         self.endpoint = model_id
         self.device_id = GLOBAL_DEVICE_ID

inference/core/registries/roboflow.py

@@ -17,6 +17,7 @@
 )
 from inference.core.utils.file_system import dump_json, read_json
 from inference.core.utils.roboflow import get_model_id_chunks
+from inference.models.aliases import resolve_roboflow_model_alias
 
 GENERIC_MODELS = {
     "clip": ("embed", "clip"),
@@ -69,6 +70,7 @@ def get_model_type(model_id: str, api_key: str) -> Tuple[TaskType, ModelType]:
         MissingDefaultModelError: If default model is not configured and API does not provide this info
         MalformedRoboflowAPIResponseError: Roboflow API responds in invalid format.
     """
+    model_id = resolve_roboflow_model_alias(model_id=model_id)
     dataset_id, version_id = get_model_id_chunks(model_id=model_id)
     if dataset_id in GENERIC_MODELS:
         logger.debug(f"Loading generic model: {dataset_id}.")

inference/models/aliases.py

@@ -0,0 +1,26 @@
+REGISTERED_ALIASES = {
+    "yolov8n-640": "coco/3",
+    "yolov8n-1280": "coco/9",
+    "yolov8s-640": "coco/6",
+    "yolov8s-1280": "coco/10",
+    "yolov8m-640": "coco/8",
+    "yolov8m-1280": "coco/11",
+    "yolov8l-640": "coco/7",
+    "yolov8l-1280": "coco/12",
+    "yolov8x-640": "coco/5",
+    "yolov8x-1280": "coco/13",
+    "yolov8n-seg-640": "coco-dataset-vdnr1/2",
+    "yolov8n-seg-1280": "coco-dataset-vdnr1/7",
+    "yolov8s-seg-640": "coco-dataset-vdnr1/4",
+    "yolov8s-seg-1280": "coco-dataset-vdnr1/8",
+    "yolov8m-seg-640": "coco-dataset-vdnr1/5",
+    "yolov8m-seg-1280": "coco-dataset-vdnr1/9",
+    "yolov8l-seg-640": "coco-dataset-vdnr1/6",
+    "yolov8l-seg-1280": "coco-dataset-vdnr1/10",
+    "yolov8x-seg-640": "coco-dataset-vdnr1/3",
+    "yolov8x-seg-1280": "coco-dataset-vdnr1/11",
+}
+
+
+def resolve_roboflow_model_alias(model_id: str) -> str:
+    return REGISTERED_ALIASES.get(model_id, model_id)

tests/inference/unit_tests/models/__init__.py

@@ -0,0 +1,17 @@
+from inference.models.aliases import resolve_roboflow_model_alias
+
+
+def test_resolve_roboflow_model_alias_when_registry_hit_should_happen() -> None:
+    # when
+    result = resolve_roboflow_model_alias(model_id="yolov8m-1280")
+
+    # then
+    assert result == "coco/11"
+
+
+def test_resolve_roboflow_model_alias_when_registry_hit_should_not_happen() -> None:
+    # when
+    result = resolve_roboflow_model_alias(model_id="my_project/3")
+
+    # then
+    assert result == "my_project/3"