Quickstart - Bioptimus Documentation

Bioptimus models run on three platforms. Choose the path that fits your use case — each tab below has the steps and links you need.

AWS & SageMaker

Managed cloud endpoints. Best for production pipelines and scale.

On-premise

Self-hosted container. Best for data residency and air-gapped sites.

Hugging Face

Direct model weights for non-commercial academic research (H-Optimus only).

Not sure which model? See Choosing a model. H-Optimus-1 extracts histology features; M-Optimus-1 adds spatial gene-expression prediction (and also produces embeddings).

Runnable notebooks

Prefer to start from a notebook? h1-jumpstart (H-Optimus) and m-jumpstart (M-Optimus) are end-to-end, runnable examples.

Pick your platform

AWS & SageMaker
On-premise
Hugging Face (academic)

The fastest path to a managed endpoint. Full steps in AWS & SageMaker.

Subscribe on AWS Marketplace

Subscribe to H-Optimus-1 or M-Optimus-1 to obtain the Model Package ARN.

Deploy a real-time endpoint

We recommend deploying a real-time endpoint on ml.g5.xlarge — the models are compiled for that GPU architecture (NVIDIA A10G, CUDA Compute Capability 8.6). See AWS & SageMaker for the full deploy script.

Run inference with the SDK

The SDK routes through the SageMaker /invocations endpoint automatically.

from bioptimus.models.backbones import Backbone
from bioptimus.models.types import Models

model = Backbone(Models.H1, backend="aws",
                 endpoint_name="h-optimus", region_name="us-east-1")

For whole-slide inference, see the SDK guide.

Self-hosted container serving the same API. Full steps in On-premise.

Load & start the container

Each package bundles its model plus tissue segmentation.

docker load < bioptimus-h1-onpremise-v1.0.1.tar.gz
docker run -d --name bioptimus-server --gpus all -p 8080:8080 \
  bioptimus-h1-onpremise:v1.0.1 serve

Verify it's healthy

curl -s http://localhost:8080/ping
# {"status": "ok", "models": ["h1", "tissue-seg"]}

Run inference with the SDK

from bioptimus.models.backbones import Backbone
from bioptimus.models.types import Models
model = Backbone(Models.H1, backend="remote", base_url="http://localhost:8080")

For whole-slide inference, see the SDK guide.

Load H-Optimus-1 weights directly with timm. Non-commercial academic use only (CC-BY-NC-ND 4.0); access is gated. Full details in Hugging Face.

Request access

Accept the license on huggingface.co/bioptimus/H-optimus-1 using your institutional email.

Load the model

import timm, torch
from huggingface_hub import login
login()

model = timm.create_model(
    "hf-hub:bioptimus/H-optimus-1",
    pretrained=True, init_values=1e-5, dynamic_img_size=False,
).to("cuda").eval()

Extract features

Apply the published normalization and run inference on a 224×224 tile at 0.5 µm/px → a (1, 1536) feature vector. See Hugging Face for the full snippet.

AWS & SageMaker

On-premise

Hugging Face

Runnable notebooks

​Pick your platform

​Next steps

SDK guide

Choosing a model

Pick your platform

Next steps