Installation#
This page walks through getting medvision_bm onto your machine, pulling in the dataset codebase, and setting the environment variables that the loader and benchmark drivers read at runtime.
Two ways to install the package#
Full clone (benchmarking, SFT, RFT)#
Choose this if you plan to run evaluations or fine-tuning. Those workflows depend on files that ship in the repository but are not part of the Python package — the launcher scripts under script/, the task-list JSONs under tasks_list/, and the Results/ layout that outputs are written into. Cloning gives you that folder structure and installs the package from it in one shot:
git clone https://github.com/YongchengYAO/MedVision.git MedVision
cd MedVision
pip install .
pip show medvision_bm # confirm the install
Treat the cloned MedVision/ directory as your working directory from here on. Datasets land in Data/, per-model outputs in Results/<task_tag>/<model>/, checkpoints in SFT/<run_name>/, and resumable status trackers in completed_tasks/.
Import-only (use the modules in your own code)#
Choose this if you only want to import from the package — for example pulling in a parsing helper — and do not need the repo’s scripts or folder layout. Install from PyPI:
pip install medvision-bm
# or the latest development version from GitHub:
pip install "git+https://github.com/YongchengYAO/MedVision.git"
pip show medvision_bm
Note
The PyPI (or GitHub) install gives you the importable package only. If you later decide to benchmark or fine-tune, switch to the full clone so the script/ and tasks_list/ directories are present.
Docker#
Prebuilt images bundle the CUDA and Python dependencies for specific models, which saves you from resolving them by hand. Browse the available tags on Docker Hub, then pull the one you want:
docker pull vincentycyao/medvision:<tag>
Start a container with GPU access and a bind mount so your work survives container removal. The mount maps a host folder onto the working directory inside the container:
# Replace </path/to/working/folder> and <tag>
docker run -it --rm \
--gpus all \
-v </path/to/working/folder>:/root/Documents/MedVision \
vincentycyao/medvision:<tag> \
bash
Once inside, clone the repo into the mounted path, activate the image’s Conda environment, install the package, and pull in the dataset codebase:
# In the container
git clone https://github.com/YongchengYAO/MedVision.git /root/Documents/MedVision
cd /root/Documents/MedVision
conda env list # find the bundled env
conda activate <env-name>
pip install .
pip show medvision_bm
python -m medvision_bm.benchmark.install_medvision_ds --data_dir ./Data
pip show medvision_ds
Dataset codebase and environment setup#
medvision_bm (the benchmark/training code) is separate from medvision_ds (the data-loading code that downloads the imaging data and builds the dataset). Installing the package does not pull in medvision_ds, so install it explicitly. The one required flag is --data_dir, the folder where datasets and the loader source will live:
python -m medvision_bm.benchmark.install_medvision_ds --data_dir ./Data
Note
This installs the base medvision_ds, which is everything benchmarking and training need — the loader downloads each dataset’s preprocessed release from Hugging Face.
Rebuilding a dataset from its original sources is a separate path. Those are the download_raw.py scripts under medvision_ds/datasets/, and they need the raw extra:
pip install "medvision_ds[raw]"
It adds pydicom, pydicom-seg and pylidc. They are not in the base install because pydicom-seg requires numpy<2, which cannot be satisfied alongside the numpy 2.x stack the evaluation environments pin. Running a raw script without the extra fails immediately with a message naming this command.
If you want the full dependency stack in one command — the vendored lmms_eval, medvision_ds, a CUDA toolkit, vLLM, and any extra requirements file — use env_setup instead. It requires both a requirements file (-r/--requirement) and --data_dir:
python -m medvision_bm.benchmark.env_setup \
--requirement requirements.txt \
--data_dir ./Data
env_setup also accepts --cuda_version (default 12.4), --vllm_version (default 0.10.0), and --lmms_eval_opt_deps for optional lmms_eval extras. In practice you rarely call it directly — the per-model launchers under script/benchmark-*/ invoke it for you with the right arguments.
Tip
The benchmark and SFT/RFT launcher scripts run the dataset install and environment setup as their first steps, so if you go through those scripts you usually do not need to run these commands by hand.
Environment variables#
The dataset loader and the benchmark drivers read their configuration from the environment. Set the required ones before running anything; the rest have sensible defaults.
Variable |
Required? |
Purpose |
Values |
|---|---|---|---|
|
Yes |
Root folder for datasets and the working tree; the full dataset is roughly 1 TB. |
Absolute or relative path |
|
Yes |
Selects which annotation version the loader builds. |
|
|
Only when pinning below latest |
Acknowledges you have read the release note before loading legacy annotations. |
|
|
No |
Reinstall |
|
|
No |
Force re-download of raw images and annotations. |
|
|
No |
Also fetch the per-slice QC figures, which ship in their own archives and are not needed to load any config. Never re-triggers the image/landmark/planner download; figures already on disk are skipped, and re-fetched only when the dataset’s biometry annotations are regenerated. |
|
|
No |
Per-sample response cache that makes an interrupted evaluation resumable; set to |
enabled by default / |
|
Restricted data only |
Hugging Face access token, so the loader can read your own private repo holding restricted data. |
Token string |
|
Restricted data only |
Synapse authentication token for Synapse-hosted source datasets (e.g. FeTA24). |
Token string |
|
Restricted data only |
Your own private Hugging Face repo holding the SKM-TEA data you prepared. |
|
|
Restricted data only |
Your own private Hugging Face repo holding the ToothFairy2 data you prepared. |
|
Warning
MedVision_ACK_RELEASE=1.4.0 is required only when you pin MedVision_PLANNER_VERSION below the newest version published for the dataset you are loading. It confirms you have read the release note explaining what changed — most importantly the regenerated tumour/lesion measurements in 1.4.0. When you run with latest (or 1.4.0) you do not need to set it, and because 1.4.0 changed only the T/L annotations, Angle/Distance and detection workloads load older pins without it.
Three source datasets (FeTA24, SKM-TEA, ToothFairy2) cannot be redistributed, so you apply for access from the data owner and — for SKM-TEA and ToothFairy2 — host the data you prepared in your own private Hugging Face repo. Only set the restricted variables above if a subtask you are running touches one of those datasets; everything else downloads without credentials. See Restricted source datasets for the full procedure.
Next steps#
With the package installed, medvision_ds in place, and the environment variables exported, head to the Quickstart to load a sample and run your first evaluation.