How to Load OpenMed Models from Local Directories for Offline and Air-Gapped Use

Pass a filesystem path to load_model() or ModelLoader and OpenMed automatically injects local_files_only=True, forcing the transformers library to read from disk without attempting network requests.

OpenMed is an open-source medical NLP framework designed for sensitive healthcare data. When deploying in secure, air-gapped environments without internet access, you must load models from local directories rather than the Hugging Face Hub. The library handles this transparently through the ModelLoader class in openmed/core/models.py, detecting local paths and enforcing offline mode automatically.

How Local Model Detection Works

OpenMed's model loading architecture distinguishes between remote Hugging Face identifiers and local filesystem paths through two key internal mechanisms.

Path Resolution via _as_existing_local_path

When you call a loading method, ModelLoader._resolve_model_name first checks whether the supplied string is an existing directory on disk. The private helper _as_existing_local_path (implemented at openmed/core/models.py#L478) validates the path. If the directory exists, the loader returns the absolute path unchanged and marks the request for offline processing.

Offline Flag Injection via _local_loading_kwargs

Once a local path is confirmed, ModelLoader._local_loading_kwargs (at openmed/core/models.py#L492) prepares the loading arguments. It returns {"local_files_only": True}, which gets passed to every Hugging Face from_pretrained call. This flag instructs the transformers library to raise an error if required files are missing, but never to contact the Hugging Face Hub.

Step-by-Step Implementation

You can load local models using either the convenience wrapper or the class directly, depending on your need for control over the loading process.

Using the High-Level load_model Helper

The simplest approach uses the module-level load_model function, which creates a ModelLoader instance and delegates to ModelLoader.load_model (entry point at openmed/core/models.py#L96).

from openmed.core.models import load_model

# Directory must contain: config.json, pytorch_model.bin (or tf_model.h5),

# and tokenizer files (vocab.txt, tokenizer_config.json, etc.)

model_dir = "/opt/models/openmed-ner-en"

# Automatically uses local_files_only=True

model_data = load_model(model_dir)

model = model_data["model"]
tokenizer = model_data["tokenizer"]
config = model_data["config"]

Using ModelLoader Directly for Advanced Control

For custom pipelines or configuration management, instantiate ModelLoader directly and call its methods.

from openmed.core.models import ModelLoader

loader = ModelLoader()  # reads global config from openmed/core/config.py

model_path = "/data/openmed/models/ner-fr"

# Create a pipeline in offline mode

pipeline = loader.create_pipeline(model_path)

# Or load raw components separately

components = loader.load_model(model_path)
model = components["model"]
tokenizer = components["tokenizer"]

Forcing Offline Mode for Hub Identifiers

If you have cached a Hugging Face model identifier but want to ensure no network fallback occurs, manually pass local_files_only=True via kwargs.

loader = ModelLoader()
components = loader.load_model(
    "OpenMed/ner-en",
    local_files_only=True,  # Enforces offline even for hub IDs

)

Deployment Example for Air-Gapped Environments

The repository includes a practical demonstration in examples/privacy_filter_book/app.py showing how to enforce offline loading in production applications.

from transformers import pipeline

# When download=False, enforce air-gapped mode

pipeline = pipeline(
    "token-classification",
    model=model_path,
    tokenizer=model_path,
    local_files_only=not download,  # True when download is disabled

)

This pattern ensures that when download is set to False, the application operates entirely within the local filesystem, making it safe for secure labs and isolated servers.

Summary

• Automatic detection: Supply a filesystem path to load_model() or ModelLoader, and OpenMed detects it via _as_existing_local_path without requiring extra flags.
• Guaranteed offline mode: The _local_loading_kwargs method injects local_files_only=True into all transformers calls, preventing any network requests.
• Flexible APIs: Use the high-level load_model wrapper (at openmed/core/models.py#L668) for simplicity, or ModelLoader directly for pipeline creation and component management.
• Air-gapped ready: The logic works in completely isolated environments provided the model directory contains all required files (config.json, weights, and tokenizer assets).

Frequently Asked Questions

What directory structure is required for local models?

The local directory must contain the standard Hugging Face model files: config.json, the model weights file (pytorch_model.bin, model.safetensors, or tf_model.h5), and the tokenizer assets (vocab.txt or tokenizer.json, plus tokenizer_config.json). If any required file is missing, from_pretrained raises a FileNotFoundError since local_files_only=True prevents automatic downloads.

How does OpenMed prevent network requests in offline mode?

When ModelLoader detects a local path, it calls _local_loading_kwargs to generate {"local_files_only": True}. This dictionary is merged into the authentication kwargs and passed to AutoConfig.from_pretrained, AutoTokenizer.from_pretrained, and AutoModelForTokenClassification.from_pretrained. According to the transformers library specification, this flag disables all HTTP calls to the Hugging Face Hub.

Can I use local models with the pipeline API?

Yes. When using ModelLoader.create_pipeline, the local path and local_files_only=True kwargs are forwarded to the underlying transformers pipeline constructor. Alternatively, you can manually construct a pipeline as shown in examples/privacy_filter_book/app.py, explicitly setting local_files_only=True when initializing the pipeline with local model and tokenizer paths.

What happens if required files are missing from the local directory?

The transformers library will raise an EnvironmentError or FileNotFoundError indicating which specific file is missing (e.g., config.json or pytorch_model.bin). Because local_files_only=True is enforced, the library will not attempt to download the missing files from the internet. You must ensure the complete model directory is copied to the target machine before running in air-gapped mode.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}