Skills Development Discover and Select OpenMed Model Registry

Discover and Select OpenMed Model Registry

v20260803
choosing-openmed-models
This skill helps developers programmatically discover, filter, and inspect the entire OpenMed model registry. It allows users to find the correct model key for specific clinical tasks (e.g., diseases, oncology, PII detection), filter by language, size, or task, and review model metadata before loading. It pairs with `loading-openmed-models`.
Get Skill
410 downloads
Overview

Choosing OpenMed Models

OpenMed ships a registry of clinical and biomedical NER models grouped into 12
categories. Never hardcode a model list — query the registry at runtime so
your code stays correct as models are added. This skill helps you go from "I need
to find diseases in Spanish discharge notes" to a concrete model key.

When to use

  • The user knows the task (find diseases / tumors / PHI) but not the model.
  • You need the right PII model for a language (es, fr, de, …).
  • You want to filter models by size, task, or tier before loading.
  • You want to inspect a model's labels, params, and license first.

Once you have a key, hand off to loading-openmed-models to load it.

Install

pip install openmed         # registry queries work without the [hf] extra

Quick start: browse categories, then pick

import openmed

# 1) The 12 categories
openmed.list_model_categories()
# ['Medical', 'Privacy', 'Anatomy', 'Hematology', 'Chemical', 'Disease',
#  'Genomics', 'Oncology', 'Species', 'Pathology', 'Pharmaceutical', 'Protein']

# 2) Models in a category -> list[ModelInfo]
for m in openmed.get_models_by_category("Disease"):
    print(m.model_id, "|", m.size_category, "|", m.entity_types)

# 3) Inspect one model before loading
info = openmed.get_model_info("OpenMed/OpenMed-NER-DiseaseDetect-BigMed-278M")
print(info.display_name, info.task, info.param_count, info.license)

get_models_by_category and get_all_models return ModelInfo objects.
get_all_models() returns a dict[str, ModelInfo] keyed by registry key.

What ModelInfo tells you

Every model exposes (real attributes):

model_id          # HF repo id, e.g. "OpenMed/OpenMed-NER-DiseaseDetect-BigMed-278M"
display_name      # human-friendly name
category          # one of the 12 categories
specialization    # e.g. "disease entity detection"
entity_types      # list[str] of labels the model emits, e.g. ["DISEASE", ...]
size_category     # "Tiny" | "Small" | "Medium" | "Large" | "XLarge"
recommended_confidence   # suggested confidence_threshold for this model
family            # "NER" | "PII" | ...
task              # "token-classification"
languages         # e.g. ["en"], ["es"]
param_count       # e.g. 278000000
license           # e.g. "apache-2.0"

Use entity_types to confirm the model emits the labels you need, and
recommended_confidence as a sensible default confidence_threshold.

Disease vs Oncology vs Privacy: worked choices

import openmed

# Disease conditions in a general clinical note:
disease = openmed.get_models_by_category("Disease")
# e.g. "OpenMed/OpenMed-NER-DiseaseDetect-BigMed-278M"
#      "OpenMed/OpenMed-NER-DiseaseDetect-BioClinical-108M" (smaller/faster)

# Tumors, staging, oncologic findings -> Oncology, not Disease:
onco = openmed.get_models_by_category("Oncology")
# e.g. "OpenMed/OpenMed-NER-OncologyDetect-BigMed-278M"

# PHI / PII detection -> Privacy category:
privacy = openmed.get_models_by_category("Privacy")

Rule of thumb: bigger (278M/560M) = more accurate, slower; **smaller
(108M, "Small"/"Tiny") = faster, edge-friendly**. Start with a mid-size model and
size up only if recall is short.

Pick a PII model by language

import openmed

# All PII models for Spanish -> dict[str, ModelInfo]
es_models = openmed.get_pii_models_by_language("es")

# The recommended default PII model id for a language:
default_es = openmed.get_default_pii_model("es")
print(default_es)   # HF repo id, or None if unsupported

deidentify(..., lang="es") and extract_pii(..., lang="es") already select an
appropriate default — use these helpers when you need to override or to confirm
coverage. Supported de-id languages live in
openmed.SUPPORTED_LANGUAGES (en es pt fr de it nl hi te ar tr ja).

Structured search with ModelQuery

For filtering by task, language, size, or tier, use the typed search:

from openmed import search_models, ModelQuery

results = search_models(ModelQuery(
    task="token-classification",
    language="en",
    max_params=200_000_000,   # keep it small for on-device
    license="apache-2.0",
))
for r in results:
    print(r.repo_id, r.param_count, r.languages, r.formats)

Each result is a ModelSearchResult with fields like repo_id, family, task,
languages, tier, param_count, architecture, base_model, formats,
canonical_labels, license, and released. ModelQuery filters include
task, language, tier, max_params, min_params, format, license, and a
free-text query.

Let OpenMed suggest a model from text

import openmed

for key, info, reason in openmed.get_model_suggestions(
    "Stage III adenocarcinoma with metastasis to regional lymph nodes."
):
    print(key, "->", reason)

get_model_suggestions(text) returns (registry_key, ModelInfo, reason) tuples —
handy when the domain is unclear from the request.

CLI

openmed models list                 # registry keys (add --include-remote to query the Hub)
openmed models info <registry-key>  # max sequence length for a key
openmed analyze --text "Stage III adenocarcinoma." --model oncology_detection_bigmed_278m

Hand-off to / from OpenMed

  • To loading-openmed-models: pass the chosen model_id/registry key as

model_name= to ModelLoader.load_model(...) or openmed.analyze_text(...).

  • To extracting-clinical-entities: use the model's recommended_confidence

as your confidence_threshold and verify entity_types matches your schema.

  • To de-identification: feed get_default_pii_model(lang) into

openmed.deidentify(model_name=..., lang=...).

import openmed
key = "oncology_detection_bigmed_278m"
info = openmed.get_model_info(key)
result = openmed.analyze_text(
    "Stage III adenocarcinoma with nodal metastasis.",
    model_name=key,
    confidence_threshold=info.recommended_confidence,
)

Edge cases & gotchas

  • Category, not keyword. "cancer" is the Oncology category; "diabetes" is

Disease. Check entity_types if unsure which fits.

  • get_default_pii_model(lang) can return None for an unsupported language —

fall back to a supported one and warn, do not silently use English on non-English
text.

  • search_models reads a committed manifest, so it only returns models that

have been catalogued — combine with get_all_models() for the full registry.

  • Match labels before committing. A model in the right category may still not

emit the exact label you need; confirm via entity_types / canonical_labels.

  • Licensing. All OpenMed registry models are permissively licensed; do not

swap in models that bundle restricted terminologies (UMLS/SNOMED/CPT).

Standards & references

  • OpenMed model org & cards: https://huggingface.co/OpenMed
  • Canonical PII label taxonomy: openmed.CANONICAL_LABELS (see

extracting-pii-entities).

Info
Category Development
Name choosing-openmed-models
Version v20260803
Size 7.54KB
Updated At 2026-08-04
Language