--- { "title": "Moteur de terminologie FHIR hybride : local + externe", "description": "Un moteur de terminologie FHIR hybride qui combine des ensembles de valeurs locaux avec des serveurs externes — avantages, inconvénients, exemples ValueSet/$expand et configuration Aidbox.", "date": "2025-09-18", "author": "Guillermo Rodríguez", "reading-time": "15 minutes", "tags": [ "Terminology", "Aidbox" ] } --- ## Qu'est-ce qu'un service de terminologie FHIR? Les serveurs de [terminologie](/blog/two-phase-fhir-terminology) ([serveurs TX](https://www.hl7.org/fhir/terminology-service.html)) sont des services FHIR spécialisés dans la gestion des ressources d'artefacts de connaissance liées à la terminologie et au vocabulaire. Un seul serveur TX peut fournir des capacités d'opérations terminologiques pour de nombreux serveurs FHIR. Les serveurs TX ne gèrent généralement pas les ressources cliniques comme les patients, les observations, les médicaments ou les rapports diagnostiques, mais plutôt les ressources utilisées pour intégrer la connaissance dans les systèmes de santé. Les services TX aident à résoudre des problèmes tels que : - « `85354-9` est-il un code LOINC valide? » ([`$validate-code`](https://build.fhir.org/valueset-operation-validate-code.html)) - « Donnez-moi tous les codes pour les mesures de signes vitaux » ([`$expand`](https://build.fhir.org/valueset-operation-expand.html)) - « Quel est le nom d'affichage pour le code ICD-10 S920? » ([`$lookup`](https://build.fhir.org/codesystem-operation-lookup.html)) - « Quel est l'équivalent SNOMED de ce diagnostic ICD-10? » ([`$translate`](https://build.fhir.org/conceptmap-operation-translate.html)) Les serveurs TX gèrent couramment des terminologies standard à forte densité de contenu, aussi appelées **terminologies externes**. Ces terminologies posent d'importants défis de stockage et de maintenance : - [**SNOMED CT International**](https://terminology.hl7.org/SNOMEDCT.html) : Plus de 365 000 concepts actifs avec des relations hiérarchiques complexes - [**LOINC**](https://terminology.hl7.org/LOINC.html) : Plus de 100 000 codes d'observations de laboratoire et cliniques avec des propriétés étendues - [**RxNorm**](https://terminology.hl7.org/RxNorm.html) : Plus de 200 000 concepts de médicaments, y compris les variations historiques et commerciales - [**ICD-10**](https://www.who.int/standards/classifications/classification-of-diseases/list-of-official-icd-10-updates) : Plus de 70 000 codes diagnostiques couvrant de nombreuses variations nationales Les serveurs TX gèrent également des **terminologies communautaires** incluses dans des guides d'implémentation (IG), comme [US Core](http://hl7.org/fhir/us/core/) (qui contient des terminologies adaptées aux pratiques de santé des États-Unis), ainsi que des **terminologies personnalisées** propres à une organisation, représentées sous forme de CodeSystems et de ValueSets locaux. ## Le problème Les organisations qui mettent en œuvre FHIR ont besoin d'une couverture complète des **terminologies externes**, combinée aux **terminologies personnalisées** et aux **terminologies communautaires**. Elles utilisent rarement les terminologies de façon isolée. Appelons cela le problème des **terminologies mixtes**. Un déploiement type de dossier de santé électronique pourrait nécessiter : ```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 ``` Ce ValueSet unique combine : - Une **terminologie externe** (LOINC) avec des exigences de filtrage - Une **terminologie personnalisée** pour les mesures propres à l'organisation - Une **terminologie communautaire** provenant de US Core pour l'interopérabilité L'approche traditionnelle pour répondre à cette exigence de **terminologies mixtes** consiste à gérer les trois types de terminologies dans le même serveur TX. ![](image-1.svg) ### Serveurs de terminologie exclusivement locaux et les grandes terminologies Exclusivement local signifie utiliser le serveur FHIR pour gérer à la fois les ressources cliniques et les ressources terminologiques. Cette approche implique de traiter les artefacts de connaissance liés aux terminologies de façon similaire aux ressources cliniques, en partageant le même moteur, le même stockage et la même infrastructure. #### Avantages - **Facilité d'utilisation** : Tout se trouve au même endroit. Aucune intégration externe ni orchestration n'est requise. - **Contrôle total** : Vous pouvez modifier les ressources terminologiques immédiatement, sans attendre des mises à jour externes. #### Inconvénients - **Gestion des données** : La gestion des **terminologies externes** nécessite généralement des gigaoctets de stockage pour les définitions de concepts, les propriétés et les relations, même lorsque les clients ne dépendent que d'un petit sous-ensemble des concepts terminologiques. - **Gestion du cycle de vie** : Un mécanisme est requis pour maintenir la terminologie à jour avec les versions officielles. - **Prise en charge insuffisante des opérations TX** : La plupart des serveurs FHIR ne prennent pas entièrement en charge les fonctionnalités avancées que les serveurs TX offrent, par exemple : les ValueSets implicites - La prise en charge du langage de requête spécifique à la terminologie (ECL) - La prise en charge des suppléments - Les packs linguistiques ### Serveurs de terminologie exclusivement externes et les terminologies spécifiques au contexte Les serveurs de terminologie externes sont des services TX hébergés qui donnent accès aux grandes terminologies standard sans nécessiter de stockage local. On trouve notamment des services communautaires comme le [serveur tx](https://tx.fhir.org/r4) de HL7 et [Ontoserver](https://r4.ontoserver.csiro.au/fhir), ainsi que des offres SaaS commerciales comme [Termbox](https://tx.health-samurai.io/fhir) de Health Samurai. Ces services excellent dans la fourniture d'une couverture complète des terminologies massives comme SNOMED CT et LOINC. Cependant, s'appuyer entièrement sur la délégation externe crée plusieurs défis opérationnels, surtout lorsqu'une organisation doit également gérer des terminologies spécifiques au contexte, comme celles des guides d'implémentation ou des systèmes de codes locaux personnalisés. #### Avantages - **Services TX complets** : Large couverture des opérations terminologiques. - **Gestion du cycle de vie du contenu** : Le contenu des terminologies externes est garanti d'être à jour. - **Pas de stockage local** : Utilisez uniquement ce dont vous avez besoin du serveur TX et des terminologies externes, sans stocker de données inutiles. #### Inconvénients - **Peu de contrôle** : Les clients ne peuvent pas appliquer de mises à jour aux terminologies; seul le propriétaire de la terminologie peut fournir des mises à jour via des versions. - **Terminologies personnalisées** : Puisque les **terminologies mixtes** constituent une exigence constante, vous devez prendre une décision concernant vos **terminologies personnalisées** : soit les publier sur le service externe (les rendant ainsi disponibles à tous les clients du serveur TX), soit mettre en place un mécanisme intelligent de routage ou de coordination des requêtes terminologiques selon leurs caractéristiques. - **Fragilité accrue** : Déléguer chaque requête terminologique à un serveur TX externe rend le système plus fragile en raison de la dépendance au réseau et des problèmes potentiels de connectivité. Les approches exclusivement locales et exclusivement externes sont toutes deux insuffisantes pour le scénario des **terminologies mixtes**, imposant des compromis sur le plan des fonctionnalités ou des performances. *Le problème fondamental est que les terminologies à forte densité de contenu comme SNOMED CT, LOINC et RxNorm ont une applicabilité large, tandis que les terminologies* ***communautaires*** *et* ***personnalisées*** *sont spécifiques au contexte et ne devraient pas affecter les autres clients du service de terminologie*. La résolution des défis d'infrastructure liés aux terminologies massives (stockage, indexation, mises à jour) exige des approches entièrement différentes de celles requises pour gérer des vocabulaires locaux petits et en évolution rapide (agilité, personnalisation, gouvernance). Les services TX traditionnels ne peuvent pas optimiser simultanément pour les deux scénarios, ce qui conduit soit à des solutions surdimensionnées pour une terminologie locale simple, soit à une infrastructure inadéquate pour les grandes terminologies standard. ## L'approche hybride Le service de terminologie hybride résout ce défi grâce à une analyse et un partitionnement intelligents des requêtes. Plutôt que d'imposer un choix binaire entre traitement local et externe, le moteur hybride examine chaque requête pour déterminer quelles ressources sont disponibles localement et lesquelles nécessitent une délégation externe, puis il réassemble les résultats. ![](image-2.svg) Pour illustrer l'algorithme hybride, considérons une organisation de soins de santé avec : - **CodeSystem local** : `http://hl7.org/fhir/test/CodeSystem/simple` - **CodeSystem distant** : `http://hl7.org/fhir/sid/icd-10` **Définition du CodeSystem local** : ```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 ``` ### Exemple de validation d'un code distant Validons un code ICD-10 qui nécessite une délégation externe. **Requête** : ```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 ``` **Réponse** : ```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' ``` Le système détecte que `http://hl7.org/fhir/sid/icd-10` n'est pas disponible localement et délègue la validation au serveur de terminologie externe. ![](image-3.svg) ### Comment fonctionne ce moteur? Le moteur hybride traite la requête `ValueSet/$validate-code` en passant par les phases suivantes : ![](image-4.svg) #### 1. Résolution du ValueSet local et de ses dépendances Le ValueSet est le point d'entrée du contexte d'exécution terminologique. Le moteur hybride résout localement le graphe de dépendances complet, incluant tous les CodeSystems référencés et les ValueSets imbriqués. #### 2. Construction de la cartographie des dépendances Il construit une cartographie des dépendances à partir des règles de composition du ValueSet. La résolution des dépendances s'appuie sur l'[algorithme de résolution canonique](https://build.fhir.org/ig/FHIR/ig-guidance/branches/master/pinning.html#choosing-the-most-recent-version) de FHIR pour sélectionner les versions compatibles les plus récentes. #### 3. Analyse de la disponibilité Le moteur hybride analyse le contexte d'exécution terminologique pour détecter les exigences en matière de ressources. Cette analyse examine : - **La disponibilité du contenu du CodeSystem** : Les systèmes marqués `content: "not-present"` nécessitent un traitement externe - **Les dépendances de composition du ValueSet** : Les règles d'inclusion et d'exclusion faisant référence à des CodeSystems non disponibles - **La résolution des URL canoniques** : Les ressources absentes du registre local d'artefacts FHIR #### 4. Traitement vers une cible unique Si tout est local ou tout est distant, la requête est acheminée vers cette cible unique et le résultat est retourné. #### 5. Traitement hybride Lorsque l'analyse détermine que certaines portions du graphe de dépendances nécessitent un traitement externe, la requête est d'abord exécutée localement. Si la validation locale réussit, le résultat est retourné au client. En cas d'échec, le moteur hybride retire les composantes locales et délègue la requête restante au serveur de terminologie externe configuré. ### Un scénario plus complexe : l'opération ValueSet/$expand L'algorithme hybride s'applique de façon similaire aux opérations `$expand`, avec une différence clé : la capacité de fusionner les résultats provenant de différentes sources. Considérons l'expansion d'un ValueSet qui combine des systèmes de terminologie locaux et distants. **ValueSets disponibles localement** ```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 ``` **Requête** : ```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 ``` **Réponse** : ```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 ``` Le moteur hybride traite le concept administrative-gender localement tout en déléguant le filtrage LOINC au serveur TX externe configuré. Alors que les opérations `$validate-code` nécessitent des résultats de validation binaires, les opérations `$expand` doivent combiner des listes de concepts provenant de sources locales et distantes. ![](image-5.svg) L'algorithme hybride pour les opérations $expand comprend deux étapes supplémentaires : ![](image-6.svg) #### 6. Faut-il davantage d'éléments? Si l'expansion locale ne peut pas satisfaire entièrement la requête, le moteur hybride retire les composantes locales de la requête originale et délègue les parties restantes au serveur de terminologie externe configuré pour résoudre l'expansion distante. #### 7. Fusion avec le résultat local Le moteur hybride combine ensuite les expansions locale et distante, déduplique les concepts et produit les métadonnées d'expansion finale avec les contributions des deux sources. ## Moteur de terminologie hybride dans Aidbox Aidbox a introduit **le moteur [TX](/blog/automate-terminology-translation-with-aidbox-tx-engine) hybride** dans la version [2507](https://www.health-samurai.io/docs/aidbox/reference/settings/fhir#terminology-engine-a-href-fhir-terminology-engine-id-fhir-terminology-engine-a), avec une prise en charge (au moment de la publication de cet article) pour : - [**CodeSystem**](https://www.health-samurai.io/docs/aidbox/terminology-module/fhir-terminology/codesystem) : opérations `$lookup` et `$validate-code` - [**ValueSet**](https://www.health-samurai.io/docs/aidbox/terminology-module/fhir-terminology/valueset) : opérations `$validate-code` et `$expand` - [**Opérations ConceptMap**](https://www.health-samurai.io/docs/aidbox/terminology-module/fhir-terminology/conceptmap) : opération `$translate` Consultez le [registre des capacités](https://www.health-samurai.io/docs/aidbox/terminology-module/aidbox-terminology-module/capabilities) pour plus de détails. ### Activer le moteur hybride dans la version v2507+ Exécutez Aidbox localement en suivant le guide [Exécuter Aidbox localement](https://www.health-samurai.io/docs/aidbox/getting-started/run-aidbox-locally). Notez que le fichier `docker-compose.yaml` téléchargé comprend des variables d'environnement pour activer le mode hybride : ```javascript services: aidbox: environment: BOX_FHIR_TERMINOLOGY_ENGINE: hybrid BOX_FHIR_TERMINOLOGY_ENGINE_HYBRID_EXTERNAL_TX_SERVER: https://tx.health-samurai.io/fhir ``` Pour plus de détails sur la configuration, consultez la [configuration du module de terminologie Aidbox](https://www.health-samurai.io/docs/aidbox/terminology-module/aidbox-terminology-module/setup). ### Préparer les ressources FHIR Ouvrez la [console REST](http://localhost:8080/ui/console#/rest) d'Aidbox et envoyez : ```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 ``` ### Exécuter l'opération $expand sur un ValueSet Procédez maintenant à l'expansion d'un ValueSet composé de terminologies locales et distantes. **Requête :** ```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 ``` **Réponse :** ```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'} ``` Consultez la [documentation du module de terminologie d'Aidbox](https://www.health-samurai.io/docs/aidbox/terminology-module/overview) pour plus d'exemples. ## En résumé Le moteur de terminologie hybride est une solution prête pour la production qui répond à ce que les services TX traditionnels peinent à offrir : une large couverture et un contrôle local simultanément. ### Principaux avantages par rapport aux approches traditionnelles - **Réduction de l'utilisation des API externes** : Seules les ressources externes déclenchent des requêtes vers le serveur externe. - **Traitement parallèle** : Les requêtes locales et externes peuvent s'exécuter de façon simultanée. - **Mise en cache intelligente** : Les ressources locales bénéficient des optimisations et de l'indexation de la base de données, tout comme la mise en cache des résultats distants. - **Migration progressive** : Déplacez les terminologies entre local et externe à votre rythme. - **Contrôle des terminologies personnalisées** : Les terminologies sensibles ou propriétaires demeurent sous contrôle local. - **Accès aux terminologies standard** : Obtenez une couverture complète des terminologies externes sans le fardeau du stockage local. - **Prise en charge avancée des opérations du serveur TX** : Le moteur hybride implémente la spécification du service TX à près de 100 % avec un accent particulier sur les terminologies **personnalisées** et **communautaires**. ### Voir aussi : - [Documentation du module de terminologie Aidbox](https://www.health-samurai.io/docs/aidbox/terminology-module/overview) - [Module de terminologie Aidbox – Mode hybride](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) - [Spécification du service de terminologie FHIR](https://www.hl7.org/fhir/terminology-service.html)