# OpenMed Tutorials: Complete Guide to Examples, Documentation, and Getting Started

> Explore OpenMed tutorials for NER extraction to REST API deployment. Get started with examples and documentation to quickly deploy your solution.

- Repository: [Maziyar Panahi/openmed](https://github.com/maziyarpanahi/openmed)
- Tags: getting-started
- Published: 2026-06-13

---

**Yes, OpenMed provides comprehensive tutorials covering everything from one-line NER extraction to production REST API deployment, located in the `docs/` and `examples/` directories.**

The maziyarpanahi/openmed repository ships with a complete tutorial suite designed to take you from basic installation to production deployment. These tutorials for OpenMed include ready-to-run Python scripts, conceptual guides, and real-world examples that demonstrate clinical text analysis, privacy filtering, and on-device deployment.

## Where to Find OpenMed Tutorials

All learning resources are self-contained within the repository and organized into two primary locations. You can run the Python examples immediately after installing the package using `pip install "openmed[hf]"` for Hugging Face backends or `pip install "openmed[mlx]"` for Apple Silicon acceleration.

### Documentation Guides (`docs/`)

The `docs/` folder contains narrative Markdown guides that explain concepts, API parameters, and configuration options:

- **[`docs/getting-started.md`](https://github.com/maziyarpanahi/openmed/blob/main/docs/getting-started.md)** – Installation, basic usage, and configuration profiles
- **[`docs/analyze-text.md`](https://github.com/maziyarpanahi/openmed/blob/main/docs/analyze-text.md)** – Deep dive into the `analyze_text` function and output formats
- **[`docs/pii-smart-merging.md`](https://github.com/maziyarpanahi/openmed/blob/main/docs/pii-smart-merging.md)** – Explains the smart merging feature that keeps dates and IDs as single entities
- **[`docs/batch-processing.md`](https://github.com/maziyarpanahi/openmed/blob/main/docs/batch-processing.md)** – High-throughput pipeline implementation with performance benchmarks
- **[`docs/rest-service.md`](https://github.com/maziyarpanahi/openmed/blob/main/docs/rest-service.md)** – FastAPI service deployment with `uvicorn` commands
- **[`docs/swift-openmedkit.md`](https://github.com/maziyarpanahi/openmed/blob/main/docs/swift-openmedkit.md)** – Native iOS and macOS integration using the OpenMedKit Swift package

### Runnable Examples (`examples/`)

The `examples/` folder contains executable scripts demonstrating specific use cases:

- **[`examples/pii_multilingual_new_languages.py`](https://github.com/maziyarpanahi/openmed/blob/main/examples/pii_multilingual_new_languages.py)** – PII detection across 12 languages including Portuguese, Arabic, and Hindi
- **[`examples/privacy_filter_unified.py`](https://github.com/maziyarpanahi/openmed/blob/main/examples/privacy_filter_unified.py)** – Unified `extract_pii` and `deidentify` API across MLX and PyTorch backends
- **[`examples/pii_batch_processing.py`](https://github.com/maziyarpanahi/openmed/blob/main/examples/pii_batch_processing.py)** – End-to-end batch PII workflow with performance benchmarks
- **[`examples/custom_tokenizer/custom_tokenize_alignment.py`](https://github.com/maziyarpanahi/openmed/blob/main/examples/custom_tokenizer/custom_tokenize_alignment.py)** – Building and comparing custom medical tokenizers against the built-in tokenizer

## Step-by-Step Tutorial Topics

### Basic Text Analysis and NER

The **[`docs/analyze-text.md`](https://github.com/maziyarpanahi/openmed/blob/main/docs/analyze-text.md)** tutorial covers one-line Named Entity Recognition (NER) extraction using the `analyze_text` function. This guide teaches you to call the analysis pipeline and inspect returned entities.

```python
from openmed import analyze_text

result = analyze_text(
    "Patient started on imatinib for chronic myeloid leukemia.",
    model_name="disease_detection_superclinical",
)

for entity in result.entities:
    print(f"{entity.label:<12} {entity.text:<30} {entity.confidence:.2f}")

```

This example is also referenced in the [`README.md`](https://github.com/maziyarpanahi/openmed/blob/main/README.md) file under the 30-second example section.

### PII Detection and De-identification

The **[`docs/pii-smart-merging.md`](https://github.com/maziyarpanahi/openmed/blob/main/docs/pii-smart-merging.md)** tutorial explains how to use `extract_pii` and `deidentify` with smart merging enabled. This functionality supports both PyTorch and MLX backends for privacy protection.

```python
from openmed import extract_pii, deidentify

text = "Paciente: Pedro Almeida, CPF 123.456.789-09, telefone +351 912 345 678."
pii = extract_pii(text, model_name="pii_superclinical_large", use_smart_merging=True)

print("Detected entities:", [(e.label, e.text) for e in pii.entities])

masked = deidentify(text, method="mask")
print("Masked:", masked.deidentified_text)

replaced = deidentify(text, method="replace", consistent=True, seed=42)
print("Replaced:", replaced.deidentified_text)

```

The full multilingual example is available in **[`examples/pii_multilingual_new_languages.py`](https://github.com/maziyarpanahi/openmed/blob/main/examples/pii_multilingual_new_languages.py)**.

### Batch Processing at Scale

The **[`docs/batch-processing.md`](https://github.com/maziyarpanahi/openmed/blob/main/docs/batch-processing.md)** guide demonstrates high-throughput processing using the `BatchProcessor` class. This tutorial handles automatic chunking and document grouping for production workloads.

```python
from openmed import BatchProcessor

processor = BatchProcessor(
    model_name="disease_detection_superclinical",
    group_entities=True,
)

texts = [
    "Patient presents with hypertension and diabetes.",
    "Administer 5 mg of lisinopril daily.",
]

batch_results = processor.process_texts(texts)

for i, result in enumerate(batch_results):
    print(f"--- Document {i+1} ---")
    for ent in result.entities:
        print(ent.label, ent.text, f"{ent.confidence:.2f}")

```

### Multilingual Support

OpenMed tutorials cover **12 languages** for PII detection. The **[`examples/pii_multilingual_new_languages.py`](https://github.com/maziyarpanahi/openmed/blob/main/examples/pii_multilingual_new_languages.py)** script demonstrates how language codes affect the pipeline and how to run the same API across Portuguese, Arabic, Hindi, and other languages.

### Custom Medical Tokenizers

The **[`examples/custom_tokenizer/custom_tokenize_alignment.py`](https://github.com/maziyarpanahi/openmed/blob/main/examples/custom_tokenizer/custom_tokenize_alignment.py)** tutorial guides you through building a custom tokenizer and comparing its alignment against the built-in medical tokenizer. This is essential for domain-specific preprocessing pipelines.

### REST API Deployment

The **[`docs/rest-service.md`](https://github.com/maziyarpanahi/openmed/blob/main/docs/rest-service.md)** tutorial provides step-by-step instructions for deploying OpenMed as a FastAPI service. You can spin up the production-ready REST service with a single `uvicorn` command.

### Swift Integration for iOS

The **[`docs/swift-openmedkit.md`](https://github.com/maziyarpanahi/openmed/blob/main/docs/swift-openmedkit.md)** tutorial covers on-device deployment for iOS and macOS applications using the `OpenMedKit` Swift package. This enables building native mobile healthcare apps with OpenMed models.

## Hands-On Code Examples from the Repository

All three code examples above are extracted directly from the official OpenMed tutorials. You can copy-paste them into a new Python file and execute them immediately after installing the package.

For the complete multilingual PII workflow, reference **[`examples/pii_multilingual_new_languages.py`](https://github.com/maziyarpanahi/openmed/blob/main/examples/pii_multilingual_new_languages.py)**. For backend comparisons between MLX and PyTorch, see **[`examples/privacy_filter_unified.py`](https://github.com/maziyarpanahi/openmed/blob/main/examples/privacy_filter_unified.py)**. For batch processing benchmarks, consult **[`examples/pii_batch_processing.py`](https://github.com/maziyarpanahi/openmed/blob/main/examples/pii_batch_processing.py)**.

## Summary

- **OpenMed tutorials** are located in the `docs/` (guides) and `examples/` (scripts) folders
- **Core functions** covered include `analyze_text`, `extract_pii`, `deidentify`, and `BatchProcessor.process_texts`
- **Installation** requires `pip install "openmed[hf]"` for Hugging Face or `pip install "openmed[mlx]"` for Apple Silicon
- **Key tutorials** span basic NER, multilingual PII detection, batch processing, custom tokenizers, REST API deployment, and Swift iOS integration
- **All tutorials** are self-contained and runnable without additional configuration

## Frequently Asked Questions

### Where are the official OpenMed tutorials located?

The official tutorials reside in two locations within the maziyarpanahi/openmed repository: the `docs/` folder contains Markdown guides explaining concepts and APIs, while the `examples/` folder contains runnable Python scripts. Key files include [`docs/getting-started.md`](https://github.com/maziyarpanahi/openmed/blob/main/docs/getting-started.md) for installation and [`docs/analyze-text.md`](https://github.com/maziyarpanahi/openmed/blob/main/docs/analyze-text.md) for basic usage.

### Do I need a GPU to follow the OpenMed tutorials?

No, the tutorials support both CPU and GPU backends. You can run [`examples/privacy_filter_unified.py`](https://github.com/maziyarpanahi/openmed/blob/main/examples/privacy_filter_unified.py) to see how the library auto-routes between PyTorch and MLX (Apple Silicon) backends. The tutorials include performance benchmarks so you can compare processing speeds across different hardware configurations.

### How do I run the multilingual PII tutorial?

Execute the [`examples/pii_multilingual_new_languages.py`](https://github.com/maziyarpanahi/openmed/blob/main/examples/pii_multilingual_new_languages.py) script after installing with `pip install "openmed[hf]"`. This tutorial demonstrates PII detection across 12 languages including Portuguese, Arabic, and Hindi, using the same `extract_pii` API with language-specific model configurations.

### Can I use OpenMed tutorials to build an iOS app?

Yes, the [`docs/swift-openmedkit.md`](https://github.com/maziyarpanahi/openmed/blob/main/docs/swift-openmedkit.md) tutorial specifically covers integrating OpenMed into native iOS and macOS applications using the OpenMedKit Swift package. This allows you to deploy medical NLP models on-device for privacy-compliant mobile healthcare applications.