--- { "title": "Hybride FHIR Terminology Engine: Lokal + Extern", "description": "Eine hybride FHIR Terminology Engine, die lokale Value Sets mit externen Servern kombiniert – Vor- und Nachteile, ValueSet/$expand-Beispiele, Aidbox-Einrichtung.", "date": "2025-09-18", "author": "Guillermo Rodríguez", "reading-time": "15 minutes", "tags": [ "Terminology", "Aidbox" ] } --- ## Was ist ein FHIR Terminology Service? [Terminology](/blog/two-phase-fhir-terminology)-Server ([TX-Server](https://www.hl7.org/fhir/terminology-service.html)) sind FHIR-Dienste, die auf die Verwaltung von Wissensartefakt-Ressourcen im Bereich Terminologie und Vokabular spezialisiert sind. Ein einziger TX-Server kann Terminologieoperationen für viele FHIR-Server bereitstellen. TX-Server verwalten in der Regel keine klinischen Ressourcen wie Patienten, Beobachtungen, Medikamente oder Diagnosenberichte, sondern Ressourcen, die zur Integration von Wissen in Gesundheitssysteme dienen. TX-Dienste helfen dabei, Fragen wie die folgenden zu beantworten: - „Ist `85354-9` ein gültiger LOINC-Code?" ([`$validate-code`](https://build.fhir.org/valueset-operation-validate-code.html)) - „Gib mir alle Codes für Vitalzeichen-Messungen" ([`$expand`](https://build.fhir.org/valueset-operation-expand.html)) - „Wie lautet der Anzeigename für den ICD-10-Code S920?" ([`$lookup`](https://build.fhir.org/codesystem-operation-lookup.html)) - „Was ist das SNOMED-Äquivalent dieser ICD-10-Diagnose?" ([`$translate`](https://build.fhir.org/conceptmap-operation-translate.html)) TX-Server verwalten häufig inhaltsreiche Standardterminologien, auch **externe Terminologien** genannt. Diese Terminologien stellen erhebliche Herausforderungen in Bezug auf Speicherung und Wartung dar: - [**SNOMED CT International**](https://terminology.hl7.org/SNOMEDCT.html): Über 365.000 aktive Konzepte mit komplexen hierarchischen Beziehungen - [**LOINC**](https://terminology.hl7.org/LOINC.html): Über 100.000 Labor- und klinische Beobachtungscodes mit umfangreichen Eigenschaften - [**RxNorm**](https://terminology.hl7.org/RxNorm.html): Über 200.000 Arzneimittelkonzepte einschließlich historischer und markenbezogener Varianten - [**ICD-10**](https://www.who.int/standards/classifications/classification-of-diseases/list-of-official-icd-10-updates): Über 70.000 Diagnosecodes in mehreren nationalen Varianten TX-Server verwalten außerdem **Community-Terminologien**, die in Implementation Guides (IGs) enthalten sind, wie z. B. [US Core](http://hl7.org/fhir/us/core/) (das Terminologie enthält, die auf die Gesundheitsversorgung in den Vereinigten Staaten zugeschnitten ist), sowie organisationsspezifische **benutzerdefinierte Terminologien**, die als lokale CodeSystems und ValueSets abgebildet werden. ## Das Problem Organisationen, die FHIR implementieren, benötigen eine umfassende Abdeckung **externer Terminologien** in Kombination mit **benutzerdefinierten Terminologien** und **Community-Terminologien**. Terminologien werden selten isoliert verwendet. Nennen wir dies das Problem der **gemischten Terminologien**. Eine typische Implementierung einer elektronischen Patientenakte könnte Folgendes erfordern: ```javascript resourceType: ValueSet compose: include: - system: http://loinc.org filter: - property: SCALE_TYP op: "=" value: Qn - system: http://example.org/fhir/CodeSystem/custom-vitals concept: - code: pain-scale-1-10 - code: mobility-assessment - system: http://hl7.org/fhir/us/core/CodeSystem/us-core-category concept: - code: vital-signs ``` Dieses einzelne ValueSet kombiniert: - **Externe Terminologie** (LOINC) mit Filteranforderungen - **Benutzerdefinierte Terminologie** für organisationsspezifische Messungen - **Community-Terminologie** aus US Core für Interoperabilität Der traditionelle Ansatz für diese Anforderung an **gemischte Terminologien** besteht darin, alle drei Arten von Terminologien im selben TX-Server zu verwalten. ![](image-1.svg) ### Rein lokale Terminology-Server und große Terminologien Rein lokal bedeutet, den FHIR-Server sowohl für klinische als auch für Terminologieressourcen zu nutzen. Dieser Ansatz setzt voraus, dass Wissensartefakte im Zusammenhang mit Terminologien ähnlich wie klinische Ressourcen behandelt werden und dieselbe Engine, denselben Speicher und dieselbe Infrastruktur teilen. #### Vorteile - **Einfache Nutzung**: Alles an einem Ort. Es sind keine externen Integrationen oder Orchestrierungen erforderlich. - **Vollständige Kontrolle**: Terminologieressourcen können sofort geändert werden, ohne auf externe Aktualisierungen warten zu müssen. #### Nachteile - **Datenverwaltung**: Die Verwaltung **externer Terminologien** erfordert in der Regel Gigabytes an Speicherplatz für Konzeptdefinitionen, Eigenschaften und Beziehungen – auch wenn die Clients möglicherweise nur eine kleine Teilmenge der Terminologiekonzepte benötigen. - **Lifecycle-Management**: Es ist ein Mechanismus erforderlich, um die Terminologie mit offiziellen Releases aktuell zu halten. - **Mangelhafte Unterstützung von TX-Operationen**: Die meisten FHIR-Server unterstützen erweiterte Funktionen, die TX-Server bieten, nicht vollständig, zum Beispiel: Implizite ValueSets - Terminologiespezifische Abfragesprache (ECL) - Unterstützung von Supplements - Sprachpakete ### Rein externe Terminology-Server und kontextspezifische Terminologien Externe Terminology-Server sind gehostete TX-Dienste, die Zugang zu großen Standardterminologien bieten, ohne lokalen Speicherbedarf. Beispiele hierfür sind Community-Dienste wie HL7's [TX-Server](https://tx.fhir.org/r4) und [Ontoserver](https://r4.ontoserver.csiro.au/fhir) sowie kommerzielle SaaS-Angebote wie Health Samurai's [Termbox](https://tx.health-samurai.io/fhir). Diese Dienste sind hervorragend geeignet, umfassende Abdeckung für umfangreiche Terminologien wie SNOMED CT und LOINC bereitzustellen. Die vollständige Abhängigkeit von einer externen Delegierung schafft jedoch mehrere betriebliche Herausforderungen, insbesondere wenn eine Organisation auch kontextspezifische Terminologien verwalten muss, wie etwa solche aus Implementation Guides oder benutzerdefinierten lokalen Codesystemen. #### Vorteile - **Vollständige TX-Dienste**: Breite Abdeckung von Terminologieoperationen. - **Content-Lifecycle-Management**: Die Inhalte externer Terminologien sind garantiert aktuell. - **Kein lokaler Speicher**: Es werden nur die benötigten Daten vom TX-Server und den externen Terminologien genutzt, ohne unnötige Daten lokal zu speichern. #### Nachteile - **Wenig Kontrolle**: Clients können keine Aktualisierungen an Terminologien vornehmen; nur der Terminologieeigentümer kann Aktualisierungen über Releases bereitstellen. - **Benutzerdefinierte Terminologien**: Da **gemischte Terminologien** eine ständige Anforderung darstellen, muss entschieden werden, wie mit **benutzerdefinierten Terminologien** umgegangen wird – entweder durch deren Veröffentlichung auf dem externen Dienst (wodurch sie für alle TX-Server-Clients verfügbar werden) oder durch die Einrichtung eines intelligenten Mechanismus zur Weiterleitung bzw. Koordinierung von Terminologieanfragen basierend auf deren Eigenschaften. - **Erhöhte Anfälligkeit**: Die Delegierung jeder Terminologieanfrage an einen externen TX-Server macht das System anfälliger aufgrund der Netzwerkabhängigkeit und potenzieller Konnektivitätsprobleme. Sowohl der rein lokale als auch der rein externe Ansatz sind für das Szenario der **gemischten Terminologien** unzureichend und erzwingen Kompromisse bei Funktionalität oder Performance. *Das Kernproblem besteht darin, dass inhaltsreiche Terminologien wie SNOMED CT, LOINC und RxNorm breite Anwendbarkeit haben, während* ***Community-*** *und* ***benutzerdefinierte*** *Terminologien kontextspezifisch sind und andere TX-Server-Clients nicht beeinflussen sollten*. Die Lösung der Infrastrukturherausforderungen umfangreicher Terminologien (Speicherung, Indexierung, Aktualisierungen) erfordert völlig andere Ansätze als die Verwaltung kleiner, sich schnell ändernder lokaler Vokabulare (Agilität, Anpassung, Governance). Traditionelle TX-Dienste können nicht gleichzeitig für beide Szenarien optimiert werden, was entweder zu überdimensionierten Lösungen für einfache lokale Terminologien oder zu unzureichender Infrastruktur für große Standardterminologien führt. ## Der hybride Ansatz Der hybride Terminology-Dienst löst diese Herausforderung durch intelligente Anfragenanalyse und -partitionierung. Anstatt eine binäre Wahl zwischen lokaler und externer Verarbeitung zu erzwingen, untersucht die hybride Engine jede Anfrage, um zu bestimmen, welche Ressourcen lokal verfügbar sind und welche eine externe Delegierung erfordern, und setzt die Ergebnisse anschließend zusammen. ![](image-2.svg) Um den hybriden Algorithmus zu veranschaulichen, betrachten wir eine Gesundheitsorganisation mit: - **Lokalem CodeSystem**: `http://hl7.org/fhir/test/CodeSystem/simple` - **Entferntem CodeSystem**: `http://hl7.org/fhir/sid/icd-10` **Definition des lokalen CodeSystem**: ```javascript resourceType: CodeSystem language: en url: http://hl7.org/fhir/test/CodeSystem/simple version: 0.1.0 hierarchyMeaning: is-a content: complete concept: - code: code1 display: Display 1 ``` ### Beispiel für die Validierung eines Remote-Codes Validieren wir einen ICD-10-Code, der eine externe Delegierung erfordert. **Anfrage**: ```javascript POST /fhir/ValueSet/$validate-code ``` ```javascript resourceType: Parameters parameter: - name: code valueCode: S920 - name: system valueUri: http://hl7.org/fhir/sid/icd-10 - name: valueSet resource: resourceType: ValueSet url: http://example.org/fhir/ValueSet/vs1 compose: include: - system: http://hl7.org/fhir/test/CodeSystem/simple - system: http://hl7.org/fhir/sid/icd-10 ``` **Antwort**: ```javascript resourceType: Parameters parameter: - name: result valueBoolean: true - name: code valueCode: S920 - name: system valueUri: http://hl7.org/fhir/sid/icd-10 - name: version valueString: 2019-covid-expanded - name: display valueString: 'Fracture of foot, except ankle : closed' ``` Das System erkennt, dass `http://hl7.org/fhir/sid/icd-10` lokal nicht verfügbar ist, und delegiert die Validierung an den externen Terminology-Server. ![](image-3.svg) ### Wie funktioniert diese Engine? Die hybride Engine verarbeitet `ValueSet/$validate-code`-Anfragen in den folgenden Phasen: ![](image-4.svg) #### 1. Lokales ValueSet & Abhängigkeiten auflösen Das ValueSet ist der Einstiegspunkt in den Terminologieausführungskontext. Die hybride Engine löst den vollständigen Abhängigkeitsgraphen lokal auf, einschließlich aller referenzierten CodeSystems und verschachtelter ValueSets. #### 2. Abhängigkeiten-Map aufbauen Es wird eine Abhängigkeits-Map aus den Kompositionsregeln des ValueSet erstellt. Die Abhängigkeitsauflösung basiert auf dem [kanonischen Auflösungsalgorithmus](https://build.fhir.org/ig/FHIR/ig-guidance/branches/master/pinning.html#choosing-the-most-recent-version) von FHIR, um die aktuellsten kompatiblen Versionen auszuwählen. #### 3. Verfügbarkeit analysieren Die hybride Engine analysiert den Terminologieausführungskontext, um Ressourcenanforderungen zu erkennen. Diese Analyse umfasst: - **Verfügbarkeit von CodeSystem-Inhalten**: Systeme, die als `content: "not-present"` markiert sind, erfordern externe Verarbeitung - **Abhängigkeiten in der ValueSet-Komposition**: Include/Exclude-Regeln, die auf nicht verfügbare CodeSystems verweisen - **Kanonische URL-Auflösung**: Fehlende Ressourcen in der lokalen FHIR Artifact Registry #### 4. Verarbeitung mit einzelnem Ziel Wenn alles lokal oder alles remote ist, wird die Anfrage an dieses einzelne Ziel weitergeleitet und das Ergebnis zurückgegeben. #### 5. Hybride Verarbeitung Wenn die Analyse ergibt, dass Teile des Abhängigkeitsgraphen externe Verarbeitung erfordern, wird die Anfrage zunächst lokal ausgeführt. Wenn die lokale Validierung erfolgreich ist, wird das Ergebnis an den Client zurückgegeben. Schlägt sie fehl, entfernt die hybride Engine die lokalen Komponenten und delegiert die verbleibende Anfrage an den konfigurierten externen Terminology-Server. ### Ein komplexeres Szenario: die ValueSet/$expand-Operation Der hybride Algorithmus wird ähnlich auf `$expand`-Operationen angewendet, mit einem wesentlichen Unterschied: der Fähigkeit, Ergebnisse aus verschiedenen Quellen zusammenzuführen. Betrachten wir die Expansion eines ValueSet, das lokale und remote Terminologiesysteme kombiniert. **Lokal verfügbare ValueSets** ```javascript resourceType: ValueSet url: http://example.org/vs-local1 compose: include: - system: http://hl7.org/fhir/administrative-gender filter: - property: concept op: "=" value: female --- resourceType: ValueSet url: http://example.org/vs-remote1 compose: include: - system: http://loinc.org filter: - property: concept op: in value: 1751-7,2339-0 --- resourceType: ValueSet url: http://example.org/vs-remote2 compose: include: - system: http://loinc.org filter: - property: concept op: "=" value: 2339-0 ``` **Anfrage**: ```javascript POST /fhir/ValueSet/$expand ``` ```javascript resourceType: Parameters parameter: - name: valueSet resource: resourceType: ValueSet compose: include: - valueSet: - http://example.org/vs-local1 - valueSet: - http://example.org/vs-remote1 exclude: - valueSet: - http://example.org/vs-remote2 ``` **Antwort**: ```javascript resourceType: ValueSet expansion: total: 2 parameter: - name: used-valueset valueUri: http://example.org/vs-local1 - name: used-valueset valueUri: http://example.org/vs-remote1 - name: used-valueset valueUri: http://example.org/vs-remote2 - name: used-codesystem valueUri: http://hl7.org/fhir/administrative-gender|4.0.1 - name: used-codesystem valueUri: http://loinc.org|3.1.0 - name: used-codesystem valueUri: http://loinc.org|2.76 - name: version valueUri: http://loinc.org|2.76 contains: - code: female system: http://hl7.org/fhir/administrative-gender display: Female - system: http://loinc.org code: 1751-7 display: Albumin [Mass/volume] in Serum or Plasma ``` Die hybride Engine verarbeitet das administrative-gender-Konzept lokal, während die LOINC-Filterung an den konfigurierten externen TX-Server delegiert wird. Während `$validate-code`-Operationen binäre Validierungsergebnisse erfordern, müssen `$expand`-Operationen Konzeptlisten aus lokalen und Remote-Quellen kombinieren. ![](image-5.svg) Der hybride Algorithmus für $expand-Operationen umfasst zwei zusätzliche Schritte: ![](image-6.svg) #### 6. Werden weitere Einträge benötigt? Wenn die lokale Expansion die Anfrage nicht vollständig erfüllen kann, entfernt die hybride Engine die lokalen Komponenten aus der ursprünglichen Anfrage und delegiert die verbleibenden Teile an den konfigurierten externen Terminology-Server, um die Remote-Expansion aufzulösen. #### 7. Mit lokalem Ergebnis zusammenführen Die hybride Engine kombiniert anschließend die lokalen und Remote-Expansionen, dedupliziert Konzepte und erstellt die abschließenden Expansionsmetadaten mit Beiträgen aus beiden Quellen. ## Hybride Terminology Engine in Aidbox Aidbox hat die **Hybride [TX-Engine](/blog/automate-terminology-translation-with-aidbox-tx-engine)** im Release [2507](https://www.health-samurai.io/docs/aidbox/reference/settings/fhir#terminology-engine-a-href-fhir-terminology-engine-id-fhir-terminology-engine-a) eingeführt, mit Unterstützung (zum Zeitpunkt der Veröffentlichung dieses Artikels) für: - [**CodeSystem**](https://www.health-samurai.io/docs/aidbox/terminology-module/fhir-terminology/codesystem): Operationen `$lookup` und `$validate-code` - [**ValueSet**](https://www.health-samurai.io/docs/aidbox/terminology-module/fhir-terminology/valueset): Operationen `$validate-code` und `$expand` - [**ConceptMap-Operationen**](https://www.health-samurai.io/docs/aidbox/terminology-module/fhir-terminology/conceptmap): Operation `$translate` Weitere Details finden Sie im [Capabilities-Register](https://www.health-samurai.io/docs/aidbox/terminology-module/aidbox-terminology-module/capabilities). ### Hybride Engine in v2507+ aktivieren Starten Sie Aidbox lokal gemäß der Anleitung [Aidbox lokal ausführen](https://www.health-samurai.io/docs/aidbox/getting-started/run-aidbox-locally). Die heruntergeladene `docker-compose.yaml`-Datei enthält Umgebungsvariablen zur Aktivierung des Hybrid-Modus: ```javascript services: aidbox: environment: BOX_FHIR_TERMINOLOGY_ENGINE: hybrid BOX_FHIR_TERMINOLOGY_ENGINE_HYBRID_EXTERNAL_TX_SERVER: https://tx.health-samurai.io/fhir ``` Weitere Konfigurationsdetails finden Sie unter [Einrichtung des Aidbox Terminology-Moduls](https://www.health-samurai.io/docs/aidbox/terminology-module/aidbox-terminology-module/setup). ### FHIR-Ressourcen vorbereiten Öffnen Sie Aidbox's [REST Console](http://localhost:8080/ui/console#/rest) und senden Sie: ```javascript POST /fhir/ValueSet resourceType: ValueSet status: active url: http://example.org/vs-local1 compose: include: - system: http://hl7.org/fhir/administrative-gender filter: - property: concept op: "=" value: female ``` ```javascript POST /fhir/ValueSet resourceType: ValueSet status: active url: http://example.org/vs-remote1 compose: include: - system: http://loinc.org filter: - property: concept op: in value: 1751-7,2339-0 ``` ```javascript POST /fhir/ValueSet resourceType: ValueSet status: active url: http://example.org/vs-remote2 compose: include: - system: http://loinc.org filter: - property: concept op: "=" value: 2339-0 ``` ### ValueSet $expand-Operation ausführen Erweitern Sie nun ein ValueSet, das aus lokalen und Remote-Terminologien zusammengesetzt ist. **Anfrage:** ```javascript POST /fhir/ValueSet/$expand resourceType: Parameters parameter: - name: valueSet resource: resourceType: ValueSet compose: include: - valueSet: - http://example.org/vs-local1 - valueSet: - http://example.org/vs-remote1 exclude: - valueSet: - http://example.org/vs-remote2 ``` **Antwort:** ```javascript resourceType: ValueSet expansion: identifier: urn:uuid:f087ced0-b9b7-4277-a4d7-e97d23ff44fe timestamp: '2025-09-05T14:27:07.118905554Z' total: 2 parameter: - {name: used-valueset, valueUri: 'http://example.org/vs-local1'} - {name: used-valueset, valueUri: 'http://example.org/vs-remote1'} - {name: used-valueset, valueUri: 'http://example.org/vs-remote2'} - {name: used-codesystem, valueUri: 'http://hl7.org/fhir/administrative-gender|4.0.1'} - {name: used-codesystem, valueUri: 'http://loinc.org|2.76'} - {name: version, valueUri: 'http://loinc.org|2.76'} contains: - {code: female, system: 'http://hl7.org/fhir/administrative-gender', display: Female} - {system: 'http://loinc.org', code: 1751-7, display: 'Albumin [Mass/volume] in Serum or Plasma'} ``` Weitere Beispiele finden Sie in der [Dokumentation des Aidbox Terminology-Moduls](https://www.health-samurai.io/docs/aidbox/terminology-module/overview). ## Zusammenfassung Die hybride Terminology Engine ist ein produktionsreifer Ansatz, um das zu bewältigen, womit traditionelle TX-Dienste Schwierigkeiten haben: breite Abdeckung und lokale Kontrolle gleichzeitig zu bieten. ### Wesentliche Vorteile gegenüber traditionellen Ansätzen - **Reduzierte externe API-Nutzung**: Nur externe Ressourcen lösen Anfragen an den externen Server aus. - **Parallele Verarbeitung**: Lokale und externe Abfragen können gleichzeitig ausgeführt werden. - **Intelligentes Caching**: Lokale Ressourcen profitieren von Datenbankoptimierungen und Indexierung sowie vom Caching von Remote-Ergebnissen. - **Schrittweise Migration**: Terminologien können in eigenem Tempo zwischen lokal und extern verschoben werden. - **Kontrolle über benutzerdefinierte Terminologien**: Sensible oder proprietäre Terminologie verbleibt unter lokaler Kontrolle. - **Zugang zu Standard-Terminologien**: Umfassende Abdeckung externer Terminologien ohne lokale Speicherlast. - **Erweiterte Unterstützung von TX-Server-Operationen**: Die hybride Engine implementiert die TX-Dienstspezifikation nahezu zu 100 % mit Schwerpunkt auf **benutzerdefinierten** und **Community**-Terminologien. ### Siehe auch: - [Dokumentation des Aidbox Terminology-Moduls](https://www.health-samurai.io/docs/aidbox/terminology-module/overview) - [Aidbox Terminology-Modul – Hybrid-Modus](https://www.health-samurai.io/docs/aidbox/terminology-module/aidbox-terminology-module/hybrid) - [Aidbox FAR – CodeSystem](https://www.health-samurai.io/docs/aidbox/terminology-module/fhir-terminology/codesystem) - [Aidbox FAR – ValueSet](https://www.health-samurai.io/docs/aidbox/terminology-module/fhir-terminology/valueset) - [Aidbox FAR – ConceptMap](https://www.health-samurai.io/docs/aidbox/terminology-module/fhir-terminology/conceptmap) - [FHIR Terminology Service Spezifikation](https://www.hl7.org/fhir/terminology-service.html)