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

> Load OpenMed models from local directories for seamless offline and air-gapped use. Simply pass a filesystem path to auto-enable local file loading without network requests.

- Repository: [Maziyar Panahi/openmed](https://github.com/maziyarpanahi/openmed)
- Tags: how-to-guide
- Published: 2026-06-11

---

**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`](https://github.com/maziyarpanahi/openmed/blob/main/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`).

```python
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.

```python
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.

```python
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`](https://github.com/maziyarpanahi/openmed/blob/main/examples/privacy_filter_book/app.py) showing how to enforce offline loading in production applications.

```python
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`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/config.json), the model weights file (`pytorch_model.bin`, `model.safetensors`, or `tf_model.h5`), and the tokenizer assets ([`vocab.txt`](https://github.com/maziyarpanahi/openmed/blob/main/vocab.txt) or [`tokenizer.json`](https://github.com/maziyarpanahi/openmed/blob/main/tokenizer.json), plus [`tokenizer_config.json`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/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`](https://github.com/maziyarpanahi/openmed/blob/main/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.