--- { "title": "Motor de Terminología FHIR Híbrido: Local + Externo", "description": "Un motor de terminología FHIR híbrido que combina conjuntos de valores locales con servidores externos: ventajas, inconvenientes, ejemplos de ValueSet/$expand y configuración en Aidbox.", "date": "2025-09-18", "author": "Guillermo Rodríguez", "reading-time": "15 minutes", "tags": [ "Terminology", "Aidbox" ] } --- > For the complete documentation index, see [llms.txt](https://www.health-samurai.io/llms.txt). > Use it to discover all available pages before guessing URLs. --- ## ¿Qué es un Servicio de Terminología FHIR? Los servidores de [Terminology](/blog/two-phase-fhir-terminology) ([servidores TX](https://www.hl7.org/fhir/terminology-service.html)) son servicios FHIR especializados en la gestión de recursos de artefactos de conocimiento relacionados con la terminología y el vocabulario. Un único servidor TX puede proporcionar capacidades de operaciones de terminología para muchos servidores FHIR. Los servidores TX generalmente no gestionan recursos clínicos como pacientes, observaciones, medicamentos o informes de diagnóstico, sino recursos utilizados para integrar conocimiento en los sistemas de salud. Los servicios TX ayudan a resolver problemas como: - «¿Es `85354-9` un código LOINC válido?» ([`$validate-code`](https://build.fhir.org/valueset-operation-validate-code.html)) - «Dame todos los códigos para mediciones de signos vitales» ([`$expand`](https://build.fhir.org/valueset-operation-expand.html)) - «¿Cuál es el nombre de presentación del código ICD-10 S920?» ([`$lookup`](https://build.fhir.org/codesystem-operation-lookup.html)) - «¿Cuál es el equivalente en SNOMED de este diagnóstico ICD-10?» ([`$translate`](https://build.fhir.org/conceptmap-operation-translate.html)) Los servidores TX gestionan habitualmente terminologías estándar con gran volumen de contenido, también denominadas **terminologías externas**. Estas terminologías presentan enormes retos de almacenamiento y mantenimiento: - [**SNOMED CT International**](https://terminology.hl7.org/SNOMEDCT.html): Más de 365 000 conceptos activos con complejas relaciones jerárquicas - [**LOINC**](https://terminology.hl7.org/LOINC.html): Más de 100 000 códigos de observaciones clínicas y de laboratorio con extensas propiedades - [**RxNorm**](https://terminology.hl7.org/RxNorm.html): Más de 200 000 conceptos de medicamentos, incluidas variaciones históricas y de marca - [**ICD-10**](https://www.who.int/standards/classifications/classification-of-diseases/list-of-official-icd-10-updates): Más de 70 000 códigos de diagnóstico en múltiples variantes nacionales Los servidores TX también gestionan **terminologías comunitarias** incluidas en las Guías de Implementación (IGs), como [US Core](http://hl7.org/fhir/us/core/) (que contiene terminología adaptada a las prácticas sanitarias de Estados Unidos), así como **terminologías personalizadas** propias de cada organización, representadas como CodeSystems y ValueSets locales. ## El Problema Las organizaciones que implementan FHIR necesitan una cobertura integral de **terminologías externas** en combinación con **terminologías personalizadas** y **terminologías comunitarias**. Raramente utilizan terminologías de forma aislada. A esto lo denominaremos el problema de las **terminologías mixtas**. Un despliegue típico de una historia clínica electrónica podría requerir: ```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 ``` Este único ValueSet combina: - **Terminología externa** (LOINC) con requisitos de filtrado - **Terminología personalizada** para mediciones específicas de la organización - **Terminología comunitaria** de US Core para la interoperabilidad El enfoque tradicional para este requisito de **terminologías mixtas** consiste en gestionar los tres tipos de terminologías en el mismo servidor TX. ![](image-1.svg) ### Servidores de Terminología Exclusivamente Locales y las Terminologías de Gran Tamaño «Solo local» significa utilizar el servidor FHIR tanto para la gestión de recursos clínicos como de terminología. Este enfoque implica tratar los artefactos de conocimiento relacionados con terminologías de forma similar a los recursos clínicos, compartiendo el mismo motor, el mismo almacenamiento y la misma infraestructura. #### Ventajas - **Facilidad de uso**: Todo en un único lugar. No se necesitan integraciones externas ni orquestación. - **Control total**: Es posible modificar los recursos de terminología de inmediato, sin esperar a actualizaciones externas. #### Inconvenientes - **Gestión de datos**: La gestión de **terminologías externas** suele requerir gigabytes de almacenamiento para definiciones de conceptos, propiedades y relaciones, incluso cuando los clientes pueden depender únicamente de un pequeño subconjunto de los conceptos de la terminología. - **Gestión del ciclo de vida**: Requiere un mecanismo para mantener la terminología actualizada con las versiones oficiales. - **Escaso soporte para operaciones TX**: La mayoría de los servidores FHIR no admiten completamente las funcionalidades avanzadas que ofrecen los servidores TX, por ejemplo: ValueSets implícitos, soporte para lenguajes de consulta específicos de terminología (ECL), soporte para suplementos e idiomas adicionales. ### Servidores de Terminología Exclusivamente Externos y Terminologías Específicas del Contexto Los servidores de terminología externos son servicios TX alojados que proporcionan acceso a grandes terminologías estándar sin necesidad de almacenamiento local. Entre los ejemplos se incluyen servicios comunitarios como el [servidor tx](https://tx.fhir.org/r4) de HL7 y [Ontoserver](https://r4.ontoserver.csiro.au/fhir), así como ofertas SaaS comerciales como [Termbox](https://tx.health-samurai.io/fhir) de Health Samurai. Estos servicios destacan por ofrecer una cobertura completa de terminologías masivas como SNOMED CT y LOINC. Sin embargo, depender por completo de la delegación externa genera varios retos operativos, especialmente cuando una organización también necesita gestionar terminologías específicas del contexto, como las de las Guías de Implementación o los sistemas de códigos locales personalizados. #### Ventajas - **Servicios TX completos**: Amplia cobertura de operaciones de terminología. - **Gestión del ciclo de vida del contenido**: El contenido de las terminologías externas tiene garantizada su actualización. - **Sin almacenamiento local**: Use solo lo que necesite del servidor TX y de las terminologías externas, sin almacenar datos innecesarios. #### Inconvenientes - **Escaso control**: Los clientes no pueden aplicar actualizaciones a las terminologías; únicamente el propietario de la terminología puede ofrecer actualizaciones mediante nuevas versiones. - **Terminologías personalizadas**: Dado que las **terminologías mixtas** son un requisito constante, es necesario tomar decisiones sobre las **terminologías personalizadas**: bien publicándolas en el servicio externo (poniéndolas a disposición de todos los clientes del servidor TX) o bien estableciendo algún mecanismo inteligente de enrutamiento/coordinación de las solicitudes de terminología en función de sus características. - **Mayor fragilidad**: Delegar cada solicitud de terminología a un servidor TX externo hace que el sistema sea más frágil debido a la dependencia de la red y a posibles problemas de conectividad. Tanto el enfoque exclusivamente local como el exclusivamente externo resultan insuficientes para el escenario de **terminologías mixtas**, obligando a asumir compromisos en funcionalidad o rendimiento. *El problema central es que las terminologías con gran volumen de contenido como SNOMED CT, LOINC y RxNorm tienen una aplicabilidad amplia, mientras que las terminologías* ***comunitarias*** *y* ***personalizadas*** *son específicas del contexto y no deberían afectar a clientes de servicios de terminología no relacionados*. Resolver los retos de infraestructura de las terminologías masivas (almacenamiento, indexación, actualizaciones) requiere enfoques completamente distintos a los necesarios para gestionar vocabularios locales pequeños y en rápida evolución (agilidad, personalización, gobernanza). Los servicios TX tradicionales no pueden optimizar ambos escenarios de forma simultánea, lo que conduce a soluciones sobredimensionadas para terminología local simple o a una infraestructura inadecuada para grandes terminologías estándar. ## El Enfoque Híbrido El servicio de terminología híbrido resuelve este reto mediante el análisis inteligente de las solicitudes y la partición de las mismas. En lugar de forzar una elección binaria entre procesamiento local y externo, el motor híbrido examina cada solicitud para determinar qué recursos están disponibles localmente y cuáles requieren delegación externa, y posteriormente reensambla los resultados. ![](image-2.svg) Para ilustrar el algoritmo híbrido, considere una organización sanitaria con: - **CodeSystem local**: `http://hl7.org/fhir/test/CodeSystem/simple` - **CodeSystem remoto**: `http://hl7.org/fhir/sid/icd-10` **Definición del 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 ``` ### Ejemplo de Validación de Código Remoto Validemos un código ICD-10 que requiere delegación externa. **Solicitud**: ```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 ``` **Respuesta**: ```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' ``` El sistema detecta que `http://hl7.org/fhir/sid/icd-10` no está disponible localmente y delega la validación al servidor de terminología externo. ![](image-3.svg) ### ¿Cómo Funciona Este Motor? El motor híbrido procesa la solicitud `ValueSet/$validate-code` mediante las siguientes fases: ![](image-4.svg) #### 1. Resolución del ValueSet Local y sus Dependencias El ValueSet es el punto de entrada al contexto de ejecución de terminología. El motor híbrido resuelve el grafo completo de dependencias de forma local, incluyendo todos los CodeSystems referenciados y los ValueSets anidados. #### 2. Construcción del Mapa de Dependencias Se construye un mapa de dependencias a partir de las reglas de composición del ValueSet. La resolución de dependencias se apoya en el [algoritmo de resolución canónica](https://build.fhir.org/ig/FHIR/ig-guidance/branches/master/pinning.html#choosing-the-most-recent-version) de FHIR para seleccionar las versiones compatibles más recientes. #### 3. Análisis de Disponibilidad El motor híbrido analiza el contexto de ejecución de terminología para detectar los requisitos de recursos. Este análisis examina: - **Disponibilidad del contenido del CodeSystem**: Los sistemas marcados como `content: "not-present"` requieren procesamiento externo - **Dependencias de composición del ValueSet**: Reglas de inclusión/exclusión que hacen referencia a CodeSystems no disponibles - **Resolución de URL canónicas**: Recursos ausentes en el Registro de Artefactos FHIR local #### 4. Procesamiento con un Único Destino Si todo está disponible localmente o todo está en remoto, la solicitud se enruta a ese único destino y se devuelve el resultado. #### 5. Procesamiento Híbrido Cuando el análisis determina que partes del grafo de dependencias requieren procesamiento externo, la solicitud se ejecuta primero localmente. Si la validación local tiene éxito, el resultado se devuelve al cliente. Si falla, el motor híbrido elimina los componentes locales y delega la solicitud restante al servidor de terminología externo configurado. ### Un Escenario Más Complejo: la Operación ValueSet/$expand El algoritmo híbrido se aplica de forma similar a las operaciones `$expand`, con una diferencia clave: la capacidad de combinar resultados procedentes de distintas fuentes. Considere la expansión de un ValueSet que combina sistemas de terminología locales y remotos. **ValueSets disponibles localmente** ```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 ``` **Solicitud**: ```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 ``` **Respuesta**: ```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 ``` El motor híbrido procesa el concepto de administrative-gender localmente, mientras delega el filtrado de LOINC al servidor TX externo configurado. Mientras que las operaciones `$validate-code` requieren resultados de validación binarios, las operaciones `$expand` deben combinar listas de conceptos procedentes de fuentes tanto locales como remotas. ![](image-5.svg) El algoritmo híbrido para las operaciones $expand incluye dos pasos adicionales: ![](image-6.svg) #### 6. ¿Se Necesitan Más Elementos? Si la expansión local no puede satisfacer completamente la solicitud, el motor híbrido elimina los componentes locales de la solicitud original y delega las partes restantes al servidor de terminología externo configurado para resolver la expansión remota. #### 7. Combinación con el Resultado Local A continuación, el motor híbrido combina las expansiones local y remota, deduplica los conceptos y produce los metadatos de expansión final con las contribuciones de ambas fuentes. ## Motor de Terminología Híbrido en Aidbox Aidbox introdujo **el motor TX híbrido ([TX engine](/blog/automate-terminology-translation-with-aidbox-tx-engine))** en la versión [2507](https://www.health-samurai.io/docs/aidbox/reference/settings/fhir#terminology-engine-a-href-fhir-terminology-engine-id-fhir-terminology-engine-a), con soporte (en el momento de la publicación de este artículo) para: - [**CodeSystem**](https://www.health-samurai.io/docs/aidbox/terminology-module/fhir-terminology/codesystem): operaciones `$lookup` y `$validate-code` - [**ValueSet**](https://www.health-samurai.io/docs/aidbox/terminology-module/fhir-terminology/valueset): operaciones `$validate-code` y `$expand` - [**Operaciones ConceptMap**](https://www.health-samurai.io/docs/aidbox/terminology-module/fhir-terminology/conceptmap): operación `$translate` Consulte el [registro de capacidades](https://www.health-samurai.io/docs/aidbox/terminology-module/aidbox-terminology-module/capabilities) para más detalles. ### Habilitar el Motor Híbrido en v2507+ Ejecute Aidbox localmente siguiendo la guía [Ejecutar Aidbox localmente](https://www.health-samurai.io/docs/aidbox/getting-started/run-aidbox-locally). Observe que el archivo `docker-compose.yaml` descargado incluye variables de entorno para habilitar el modo híbrido: ```javascript services: aidbox: environment: BOX_FHIR_TERMINOLOGY_ENGINE: hybrid BOX_FHIR_TERMINOLOGY_ENGINE_HYBRID_EXTERNAL_TX_SERVER: https://tx.health-samurai.io/fhir ``` Para más detalles de configuración, consulte [Configuración del módulo de terminología de Aidbox](https://www.health-samurai.io/docs/aidbox/terminology-module/aidbox-terminology-module/setup). ### Preparar los Recursos FHIR Abra la [Consola REST](http://localhost:8080/ui/console#/rest) de Aidbox y envíe: ```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 ``` ### Ejecutar la Operación $expand de ValueSet Ahora expanda un ValueSet compuesto por terminologías locales y remotas. **Solicitud:** ```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 ``` **Respuesta:** ```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'} ``` Consulte la [documentación del módulo de terminología de Aidbox](https://www.health-samurai.io/docs/aidbox/terminology-module/overview) para más ejemplos. ## Conclusión El motor de terminología híbrido es una solución lista para producción que aborda lo que los servicios TX tradicionales tienen dificultades para lograr: proporcionar una amplia cobertura y control local al mismo tiempo. ### Principales Ventajas Frente a los Enfoques Tradicionales - **Reducción del uso de la API externa**: Solo los recursos externos generan solicitudes al servidor externo. - **Procesamiento paralelo**: Las consultas locales y externas pueden ejecutarse de forma concurrente. - **Caché inteligente**: Los recursos locales se benefician de las optimizaciones e indexación de la base de datos, así como del almacenamiento en caché de los resultados remotos. - **Migración gradual**: Mueva terminologías entre el entorno local y el externo a su propio ritmo. - **Control sobre la terminología personalizada**: La terminología sensible o propietaria permanece bajo control local. - **Acceso a terminología estándar**: Obtenga una cobertura integral de terminologías externas sin la carga del almacenamiento local. - **Soporte avanzado para operaciones de servidor TX**: El motor híbrido implementa la especificación del servicio TX cerca del 100 % con énfasis en las terminologías **personalizadas** y **comunitarias**. ### Véase también: - [Documentación del Módulo de Terminología de Aidbox](https://www.health-samurai.io/docs/aidbox/terminology-module/overview) - [Módulo de Terminología de Aidbox - Modo híbrido](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) - [Especificación del Servicio de Terminología FHIR](https://www.hl7.org/fhir/terminology-service.html)