Serving OpenMed over REST
openmed.service is a hardened FastAPI app exposing OpenMed's NER, PII
extraction, and de-identification over HTTP. It is built to be self-hosted:
models run on-device, there's no telemetry, and the request schemas reject raw
PHI from spilling into errors. Use it when callers need request/response
inference; use batch-processing-clinical-text for corpora.
When to use this skill
To put OpenMed behind an HTTP endpoint your own apps call — an internal de-id
microservice, an NER backend, a containerized inference tier. For agent/tool
integration prefer the MCP server (deploying-openmed-mcp); for offline bulk
work use batch processing.
Quick start
pip install "openmed[service]" # FastAPI + uvicorn + pydantic
# Launch the ASGI app (factory create_app, or the module-level `app`)
python -m openmed.service.logging --host 127.0.0.1 --port 8000
# Or build it in-process (e.g. to mount under a parent app / add middleware):
from openmed.service import create_app
app = create_app()
curl -s localhost:8000/health
# {"status":"ok","service":"openmed-rest","version":"...","profile":"prod"}
curl -s localhost:8000/analyze -H 'content-type: application/json' -d '{
"text": "Patient received 75mg clopidogrel for NSTEMI.",
"model_name": "disease_detection_superclinical"
}'
curl -s localhost:8000/pii/deidentify -H 'content-type: application/json' -d '{
"text": "John Doe called 555-123-4567 on 01/15/2020.",
"method": "mask"
}'
Endpoints (confirmed in openmed/service/app.py)
| Method & path |
Purpose |
Request schema |
GET /health |
liveness + version + active profile |
— |
GET /models/loaded |
cache/keep-alive status of resident models |
— |
POST /models/unload |
unload one model or all inactive models |
ModelUnloadRequest (model_name or all=true) |
POST /analyze |
clinical NER |
AnalyzeRequest |
POST /pii/extract |
detect PII/PHI spans |
PIIExtractRequest |
POST /pii/deidentify |
mask/remove/replace/hash/shift-dates PHI |
PIIDeidentifyRequest |
Request fields (from openmed/service/schemas.py, strict — unknown fields are
rejected):
AnalyzeRequest: text (required), model_name
("disease_detection_superclinical"), confidence_threshold (0.0),
group_entities, aggregation_strategy (simple|first|average|max),
sentence_detection, sentence_language, sentence_clean,
use_fast_tokenizer, keep_alive.
PIIExtractRequest: text, model_name
(default OpenMed/OpenMed-PII-SuperClinical-Small-44M-v1),
confidence_threshold (0.5), use_smart_merging, lang
(en/fr/de/it/es/nl/hi/te/pt/ar/ja/tr), normalize_accents, keep_alive.
PIIDeidentifyRequest: same base plus method
(mask|remove|replace|hash|shift_dates, default mask),
confidence_threshold (0.7), keep_year, shift_dates, date_shift_days,
keep_mapping, policy, use_smart_merging, use_safety_sweep.
Responses are the OpenMed result to_dict() (e.g. {text, entities[...], ...}).
Errors use a stable envelope: {"error": {"code", "message", "details"}} with
422 validation_error, 400 bad_request, 504 timeout, 500 internal_error.
Configuring the runtime (env vars)
ServiceRuntime.from_env() reads the process environment at startup
(openmed/service/runtime.py):
| Env var |
Effect |
OPENMED_PROFILE |
config profile (prod default) |
OPENMED_SERVICE_PRELOAD_MODELS |
comma list of models to warm at startup |
OPENMED_SERVICE_KEEP_ALIVE |
default idle keep-alive before unload |
OPENMED_SERVICE_MAX_RESIDENT_MODELS |
cap resident models (warm pool) |
OPENMED_SERVICE_BATCHING_ENABLED |
enable dynamic request batching |
OPENMED_SERVICE_BATCH_MAX_SIZE |
max dynamic batch size (default 8) |
OPENMED_SERVICE_BATCH_MAX_WAIT_MS |
batch-collection window (default 5ms) |
OPENMED_SERVICE_PRELOAD_MODELS="disease_detection_superclinical" \
OPENMED_SERVICE_BATCHING_ENABLED=true \
python -m openmed.service.logging --host 0.0.0.0 --port 8000
Preloading avoids first-request latency; the warm pool keeps hot models resident
and idle-unloads the rest. /analyze and /pii/extract coalesce concurrent
requests when batching is enabled.
Workflow
- Install + launch.
pip install "openmed[service]", then run
python -m openmed.service.logging (or build with create_app()).
- Configure the runtime via env vars before start: set
OPENMED_PROFILE, preload your hot models, and decide keep-alive / max
resident / batching to fit the box.
- Front it with auth/TLS. Place a reverse proxy or gateway (API keys/mTLS,
CORS allow-list) ahead of the app — it has none built in.
- Health-check + warm. Poll
GET /health; preloaded models warm during
the lifespan startup so the first real request isn't cold.
- Call the endpoints (
/analyze, /pii/extract, /pii/deidentify) with
the strict JSON schemas; handle the {"error": {...}} envelope.
- Manage memory with
GET /models/loaded and POST /models/unload as
traffic shifts between models.
Containerizing
FROM python:3.11-slim
RUN pip install --no-cache-dir "openmed[service]"
ENV OPENMED_SERVICE_PRELOAD_MODELS="disease_detection_superclinical"
EXPOSE 8000
CMD ["python", "-m", "openmed.service.logging", "--host", "0.0.0.0", "--port", "8000"]
Bake/mount the model cache so containers don't re-download on every start; the
service runs offline after that.
Hand-off to / from OpenMed
- Same engine, different surface:
/analyze → openmed.analyze_text,
/pii/extract → openmed.extract_pii, /pii/deidentify →
openmed.deidentify. Results match the library exactly.
- Agents/tools: for Claude Code / Codex / chat clients, expose the same
capabilities as MCP tools instead (
deploying-openmed-mcp).
- Bulk: for corpora, call
batch-processing-clinical-text in a worker, not
per-request HTTP.
Edge cases & gotchas
- No built-in auth/CORS/TLS. The app ships hardened input validation but no
authentication. Put it behind your own reverse proxy / API gateway (mTLS,
API keys, CORS allow-list) before any real traffic. Bind
127.0.0.1 for
local use; only expose 0.0.0.0 behind that proxy.
- No-PHI logging. Don't add request/response body logging — that's PHI.
The error envelope is designed to avoid echoing input; keep it that way. Log
status codes, timings, and model names only.
- Strict schemas. Unknown JSON fields are rejected (
extra="forbid"); a bad
lang/method/model_name returns 422/400 with a field-level reason.
- Cold start vs memory. Preloading + a high
MAX_RESIDENT_MODELS trades RAM
for latency; tune to the box.
- Timeouts return
504 per the profile's configured timeout; long inputs
may need a larger profile or pre-chunking.
keep_mapping/policy outputs are sensitive. A de-id response with a
mapping re-identifies patients — only enable it for trusted callers and store
the mapping securely, never in service logs.
Standards & references
1---2name: serving-openmed-rest-api3description: "Stand up OpenMed's FastAPI REST service for clinical NER, PII extraction, and de-identification, with health checks, model keep-alive/unload, optional dynamic batching, and no-PHI logging. Use when the user wants to serve OpenMed over HTTP, deploy a de-id/NER REST API, run an inference endpoint for clinical text, add a /analyze or /pii/deidentify route, or containerize OpenMed as a service. Covers the service extra, launching create_app with uvicorn, the real endpoints (/health, /analyze, /pii/extract, /pii/deidentify, /models/loaded, /models/unload), request/response shapes, ServiceRuntime env-var configuration, and self-hosted auth/CORS/TLS notes."4license: Apache-2.05metadata:6 source: https://skillmd.com/skills/maziyarpanahi/serving-openmed-rest-api7 project: OpenMed8 category: deployment-ops9 pairs: adjacent10 version: "1.0"11---1213# Serving OpenMed over REST1415`openmed.service` is a hardened **FastAPI** app exposing OpenMed's NER, PII16extraction, and de-identification over HTTP. It is built to be **self-hosted**:17models run on-device, there's no telemetry, and the request schemas reject raw18PHI from spilling into errors. Use it when callers need request/response19inference; use `batch-processing-clinical-text` for corpora.2021## When to use this skill2223To put OpenMed behind an HTTP endpoint your own apps call — an internal de-id24microservice, an NER backend, a containerized inference tier. For agent/tool25integration prefer the MCP server (`deploying-openmed-mcp`); for offline bulk26work use batch processing.2728## Quick start2930```bash31pip install "openmed[service]" # FastAPI + uvicorn + pydantic3233# Launch the ASGI app (factory create_app, or the module-level `app`)34python -m openmed.service.logging --host 127.0.0.1 --port 800035```3637```python38# Or build it in-process (e.g. to mount under a parent app / add middleware):39from openmed.service import create_app40app = create_app()41```4243```bash44curl -s localhost:8000/health45# {"status":"ok","service":"openmed-rest","version":"...","profile":"prod"}4647curl -s localhost:8000/analyze -H 'content-type: application/json' -d '{48 "text": "Patient received 75mg clopidogrel for NSTEMI.",49 "model_name": "disease_detection_superclinical"50}'5152curl -s localhost:8000/pii/deidentify -H 'content-type: application/json' -d '{53 "text": "John Doe called 555-123-4567 on 01/15/2020.",54 "method": "mask"55}'56```5758## Endpoints (confirmed in `openmed/service/app.py`)5960| Method & path | Purpose | Request schema |61| --- | --- | --- |62| `GET /health` | liveness + version + active profile | — |63| `GET /models/loaded` | cache/keep-alive status of resident models | — |64| `POST /models/unload` | unload one model or all inactive models | `ModelUnloadRequest` (`model_name` or `all=true`) |65| `POST /analyze` | clinical NER | `AnalyzeRequest` |66| `POST /pii/extract` | detect PII/PHI spans | `PIIExtractRequest` |67| `POST /pii/deidentify` | mask/remove/replace/hash/shift-dates PHI | `PIIDeidentifyRequest` |6869Request fields (from `openmed/service/schemas.py`, strict — unknown fields are70rejected):7172- **`AnalyzeRequest`**: `text` (required), `model_name`73 (`"disease_detection_superclinical"`), `confidence_threshold` (0.0),74 `group_entities`, `aggregation_strategy` (`simple|first|average|max`),75 `sentence_detection`, `sentence_language`, `sentence_clean`,76 `use_fast_tokenizer`, `keep_alive`.77- **`PIIExtractRequest`**: `text`, `model_name`78 (default `OpenMed/OpenMed-PII-SuperClinical-Small-44M-v1`),79 `confidence_threshold` (0.5), `use_smart_merging`, `lang`80 (`en/fr/de/it/es/nl/hi/te/pt/ar/ja/tr`), `normalize_accents`, `keep_alive`.81- **`PIIDeidentifyRequest`**: same base plus `method`82 (`mask|remove|replace|hash|shift_dates`, default `mask`),83 `confidence_threshold` (0.7), `keep_year`, `shift_dates`, `date_shift_days`,84 `keep_mapping`, `policy`, `use_smart_merging`, `use_safety_sweep`.8586Responses are the OpenMed result `to_dict()` (e.g. `{text, entities[...], ...}`).87Errors use a stable envelope: `{"error": {"code", "message", "details"}}` with88`422` validation_error, `400` bad_request, `504` timeout, `500` internal_error.8990## Configuring the runtime (env vars)9192`ServiceRuntime.from_env()` reads the process environment at startup93(`openmed/service/runtime.py`):9495| Env var | Effect |96| --- | --- |97| `OPENMED_PROFILE` | config profile (`prod` default) |98| `OPENMED_SERVICE_PRELOAD_MODELS` | comma list of models to warm at startup |99| `OPENMED_SERVICE_KEEP_ALIVE` | default idle keep-alive before unload |100| `OPENMED_SERVICE_MAX_RESIDENT_MODELS` | cap resident models (warm pool) |101| `OPENMED_SERVICE_BATCHING_ENABLED` | enable dynamic request batching |102| `OPENMED_SERVICE_BATCH_MAX_SIZE` | max dynamic batch size (default 8) |103| `OPENMED_SERVICE_BATCH_MAX_WAIT_MS` | batch-collection window (default 5ms) |104105```bash106OPENMED_SERVICE_PRELOAD_MODELS="disease_detection_superclinical" \107OPENMED_SERVICE_BATCHING_ENABLED=true \108python -m openmed.service.logging --host 0.0.0.0 --port 8000109```110111Preloading avoids first-request latency; the warm pool keeps hot models resident112and idle-unloads the rest. `/analyze` and `/pii/extract` coalesce concurrent113requests when batching is enabled.114115## Workflow1161171. **Install + launch.** `pip install "openmed[service]"`, then run118 `python -m openmed.service.logging` (or build with `create_app()`).1192. **Configure the runtime** via env vars before start: set120 `OPENMED_PROFILE`, preload your hot models, and decide keep-alive / max121 resident / batching to fit the box.1223. **Front it with auth/TLS.** Place a reverse proxy or gateway (API keys/mTLS,123 CORS allow-list) ahead of the app — it has none built in.1244. **Health-check + warm.** Poll `GET /health`; preloaded models warm during125 the lifespan startup so the first real request isn't cold.1265. **Call the endpoints** (`/analyze`, `/pii/extract`, `/pii/deidentify`) with127 the strict JSON schemas; handle the `{"error": {...}}` envelope.1286. **Manage memory** with `GET /models/loaded` and `POST /models/unload` as129 traffic shifts between models.130131## Containerizing132133```dockerfile134FROM python:3.11-slim135RUN pip install --no-cache-dir "openmed[service]"136ENV OPENMED_SERVICE_PRELOAD_MODELS="disease_detection_superclinical"137EXPOSE 8000138CMD ["python", "-m", "openmed.service.logging", "--host", "0.0.0.0", "--port", "8000"]139```140141Bake/mount the model cache so containers don't re-download on every start; the142service runs offline after that.143144## Hand-off to / from OpenMed145146- **Same engine, different surface:** `/analyze` → `openmed.analyze_text`,147 `/pii/extract` → `openmed.extract_pii`, `/pii/deidentify` →148 `openmed.deidentify`. Results match the library exactly.149- **Agents/tools:** for Claude Code / Codex / chat clients, expose the same150 capabilities as MCP tools instead (`deploying-openmed-mcp`).151- **Bulk:** for corpora, call `batch-processing-clinical-text` in a worker, not152 per-request HTTP.153154## Edge cases & gotchas155156- **No built-in auth/CORS/TLS.** The app ships hardened input validation but no157 authentication. Put it behind your own reverse proxy / API gateway (mTLS,158 API keys, CORS allow-list) before any real traffic. Bind `127.0.0.1` for159 local use; only expose `0.0.0.0` behind that proxy.160- **No-PHI logging.** Don't add request/response body logging — that's PHI.161 The error envelope is designed to avoid echoing input; keep it that way. Log162 status codes, timings, and model names only.163- **Strict schemas.** Unknown JSON fields are rejected (`extra="forbid"`); a bad164 `lang`/`method`/`model_name` returns `422`/`400` with a field-level reason.165- **Cold start vs memory.** Preloading + a high `MAX_RESIDENT_MODELS` trades RAM166 for latency; tune to the box.167- **Timeouts return `504`** per the profile's configured `timeout`; long inputs168 may need a larger profile or pre-chunking.169- **`keep_mapping`/`policy` outputs are sensitive.** A de-id response with a170 mapping re-identifies patients — only enable it for trusted callers and store171 the mapping securely, never in service logs.172173## Standards & references174175- FastAPI: https://fastapi.tiangolo.com/176- Uvicorn (ASGI server): https://www.uvicorn.org/177- OpenAPI (the service auto-serves `/docs` and `/openapi.json`):178 https://www.openapis.org/179- HIPAA de-identification, 45 CFR 164.514(b):180 https://www.hhs.gov/hipaa/for-professionals/privacy/special-topics/de-identification/index.html181- OpenMed source: `openmed/service/app.py` (routes), `openmed/service/runtime.py`182 (`ServiceRuntime`), `openmed/service/schemas.py` (request models).