Przejdź do treści
Biblioteka skilli
Medycyna i zdrowie · Budowanie i kod

serving-openmed-rest-api

/serving-openmed-rest-api

Uruchamia REST API w FastAPI do rozpoznawania encji w tekście klinicznym, wykrywania danych osobowych i deidentyfikacji, bez logowania danych pacjentów.

Repozytorium
openmed ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
4
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Uruchamia REST API w FastAPI do rozpoznawania encji w tekście klinicznym, wykrywania danych osobowych i deidentyfikacji, bez logowania danych pacjentów.

Oryginalny opis (EN)

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 en

Jak działa

  1. When to use this skill
  2. Quick start
  3. Endpoints (confirmed in openmed/service/app.py)
  4. Configuring the runtime (env vars)
  5. Workflow
  6. Containerizing
  7. Hand-off to / from OpenMed
  8. Edge cases & gotchas
  9. Standards & references
Sekcje z nagłówków SKILL.md, w oryginale · 172 linii, 920 słów
Podgląd SKILL.md
---
name: serving-openmed-rest-api
description: "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."
license: Apache-2.0
metadata:
  project: OpenMed
  category: deployment-ops
  pairs: adjacent
  version: "1.0"
---

# 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

```bash
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
```

```python
# Or build it in-process (e.g. to mount under a parent app / add middleware):
from openmed.service import create_app
app = create_app()
```

```bash
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) |

```bash
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

1. **Install + launch.** `pip install "openmed[service]"`, then run
   `python -m openmed.service.logging` (or build with `create_app()`).
2. **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.
3. **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.
4. **Health-check + warm.** Poll `GET /health`; preloaded models warm during
   the lifespan startup so the first real request isn't cold.
5. **Call the endpoints** (`/analyze`, `/pii/extract`, `/pii/deidentify`) with
   the strict JSON schemas; handle the `{"error": {...}}` envelope.
6. **Manage memory** with `GET /models/loaded` and `POST /models/unload` as
   traffic shifts between models.

## Containerizing

```dockerfile
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

- FastAPI: https://fastapi.tiangolo.com/
- Uvicorn (ASGI server): https://www.uvicorn.org/
- OpenAPI (the service auto-serves `/docs` and `/openapi.json`):
  https://www.openapis.org/
- HIPAA de-identification, 45 CFR 164.514(b):
  https://www.hhs.gov/hipaa/for-professionals/privacy/special-topics/de-identification/index.html
- OpenMed source: `openmed/service/app.py` (routes), `openmed/service/runtime.py`
  (`ServiceRuntime`), `openmed/service/schemas.py` (request models).

Wersje

W bazie nie ma innych skilli o nazwie serving-openmed-rest-api.

Migawka bazy z 13.11.2026 · wersja paczki 720aaf8e04b4 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100deploying-openmed-mcp
    Uruchamia serwer MCP OpenMed, aby agenci kodujący i klienty czatu wywoływały lokalnie narzędzia klinicznego NER, ekstrakcji PII i deidentyfikacji przez stdio lub Streamable HTTP.
  • 100batch-processing-clinical-text
    Przetwarza wsadowo duże zbiory notatek klinicznych lokalnie z OpenMed: NER, ekstrakcja PII i deidentyfikacja z shardingiem, checkpointami, wznawianiem i dopisywanym wyjściem JSONL.
  • 100deidentify
    Anonimizuje dane kliniczne z możliwymi PHI przed analizą z LLM lokalnym skryptem Pythona, który wykrywa identyfikatory w 12 pakietach krajowych, z interaktywnym przeglądem.
  • 100python-fastapi-ops
    Stosuje wzorce frameworka FastAPI: endpointy API, wstrzykiwanie zależności, modele Pydantic, OpenAPI, Starlette, asynchroniczne REST API i uvicorn.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.