Upload, Train, and Deploy a Model

From a folder of images to a hosted, callable model - end to end.

This recipe takes a folder of labeled images and ends with a hosted Roboflow model you can call from your application. Each step is short - the whole flow is ~30 lines of Python.

What you'll need

• A Roboflow workspace and API key - see Find Your Roboflow API Key.

• A folder of images plus matching annotations (COCO / VOC / YOLO).

• Python >=3.10 and pip install roboflow.

• Time and credits to train (typically minutes for small datasets).

export ROBOFLOW_API_KEY=rf_xxxxx

1. Create the project

import roboflow

rf = roboflow.Roboflow()
ws = rf.workspace()

project = ws.create_project(
    project_name="My Detector",
    project_type="object-detection",
    project_license="MIT",            # or "Private" on paid plans
    annotation="objects",              # what you're labeling
)
print(project.id)

If the project already exists, fetch it instead:

project = ws.project("my-detector")

2. Upload the dataset

ws.upload_dataset(
    "./my-images",                     # path to your dataset
    "my-detector",                     # project id
    num_workers=10,                    # parallel uploads
    project_type="object-detection",
)

The expected layout for a COCO dataset:

my-images/
├── train/
│   ├── image1.jpg
│   ├── image2.jpg
│   └── _annotations.coco.json
├── valid/
│   └── _annotations.coco.json
└── test/
    └── _annotations.coco.json

For VOC and YOLO, drop the corresponding annotation files alongside the images.

3. Generate a version

A version freezes a snapshot of the dataset with preprocessing and augmentation applied. The web app has a UI for this; from the SDK:

new_version = project.generate_version({
    "preprocessing": {
        "auto-orient": True,
        "resize": {"width": 640, "height": 640, "format": "Stretch to"},
    },
    "augmentation": {},
})
version = project.version(new_version)

4. Train

model = version.train(
    model_type="rfdetr-nano",          # see version.train help for full list
    epochs=100,
)

train() schedules the job server-side and returns once the queue accepts it. Check progress in the web app or via GET /:workspace/:project/jobs/:jobId.

5. Run inference

Once training completes, call the hosted model:

predictions = version.model.predict("test-image.jpg", confidence=40, overlap=30).json()
for p in predictions["predictions"]:
    print(p["class"], p["confidence"])

That's the same hosted Serverless v2 endpoint the REST API and CLI infer hit.

6. (Optional) Move to a Dedicated Deployment

For high throughput or pinned latency, provision a Dedicated Deployment and point inference at its public_url:

from roboflow.adapters import deploymentapi
from inference_sdk import InferenceHTTPClient

deploymentapi.add_deployment(
    api_key=ROBOFLOW_API_KEY,
    creator_email="[e-mail]",
    deployment_name="my-deployment",
    machine_type="gpu-small",
    duration=8,
    delete_on_expiration=False,
    inference_version=None,
)

# poll deploymentapi.get_deployment until status == "ready", then:
status, info = deploymentapi.get_deployment(ROBOFLOW_API_KEY, "my-deployment")

client = InferenceHTTPClient(api_url=info["public_url"], api_key=ROBOFLOW_API_KEY)
print(client.infer("test-image.jpg", model_id="my-detector/3"))

Variations

• CI-driven retraining: replace step 1's create_project with project = ws.project(...), automate steps 2–4 in a GitHub Action that runs whenever new labeled images land in your data store. The CLI flavor (roboflow upload, roboflow version create, roboflow train start) makes the YAML cleaner.

• Active-learning loop: skip step 5 and use Workspace.active_learning() to triage new images against the trained model and feed back the uncertain ones.

• Custom weights: skip steps 3–4 and use Version.deploy() to upload an externally trained model into the version.