Funciones de transformación de datos

Cada una de las siguientes funciones está documentada con información sobre qué es, cómo funciona, las diferencias entre las fuentes CSV C-CDA y cuándo utilizarlas.

• Perfiles de transformación y control de versiones

• Agente de IA para la transformación de datos

• Transformación y previsualización sincrónicas (en tiempo real)

• Trabajos de transformación masiva (asincrónica)

• Validación

• OID-to-URI mapeo

• Procedencia

• Detección de desviaciones

• Acceso a MCP

Perfiles de transformación y control de versiones

Un perfil de transformación es la definición reutilizable de cómo un formato fuente se convierte a FHIR R4. Contiene la lógica de conversión (plantillas de Velocity C-CDA, una configuración de mapeo de YAML para CSV) y se crea una vez y se reutiliza en todos los almacenes de datos y tareas de transformación de su cuenta. Separar la definición (perfil) de la ejecución (trabajo) significa crear y probar una conversión una vez y, a continuación, aplicar la misma versión publicada a cualquier número de trabajos.

Crear un perfil

Puede crear un perfil de tres maneras:

• A partir de un perfil inicial o base: comience con un perfil de trabajo en lugar de uno en blanco. C-CDAEn efecto, el perfil de AWS inicio es un AWS-defined perfil prediseñado que gestiona los formatos de C-CDA documentos habituales de forma inmediata. En el caso de CSV, debe proporcionar archivos de muestra en Amazon S3 al crear el perfil y, a continuación, invocar al agente de IA para analizarlos y generar una configuración de mapeo de YAML.

• Por clonación: clona cualquier perfil existente como punto de partida para uno nuevo.

• A partir de un mapeo sin procesar: suministra directamente plantillas de Velocity (C-CDA) o un mapeo YAML (CSV). Esta es la ruta para implementar perfiles controlados por versiones a través de una CI/CD canalización (consulte). Cómo empezar con el SDK y AWS CLI

importante

Al crear un perfil CSV, SampleData se registra la ubicación de la muestra, pero no se ejecuta el agente de IA. Para generar el mapeo YAML, debes llamar UpdateProfileWithAgent después de crearlo. El agente analiza los archivos de muestra en ese punto y genera el perfil base.

El ciclo de vida de la versión

Un perfil puede tener como máximo un borrador y hasta 99 versiones publicadas:

• Un perfil nuevo comienza como un borrador (versión 0): una copia de trabajo mutable que se puede editar libremente.

• Al publicar el borrador, se crea una versión numerada e inmutable (v1, v2, etc., hasta la v99). Las versiones publicadas nunca cambian.

• Los trabajos de transformación siempre se comparan con la última versión publicada. Como el borrador es independiente, puede seguir editándolo mientras los trabajos de producción siguen ejecutándose con la última versión publicada: las ediciones en curso nunca afectan a las conversiones en curso.

• Un perfil con una versión publicada y ediciones inéditas más recientes se encuentra en un estado sin publicar cambios; la versión publicada permanece activa hasta que se vuelva a publicar.

Comparación y retroceso

Como todas las versiones publicadas se conservan, puedes ver exactamente cómo ha cambiado la lógica de conversión a lo largo del historial de versiones. La reversión no elimina nada: crea una nueva versión a partir de una instantánea anterior, por lo que se conserva el historial completo y la pista de auditoría.

¿Cuándo usar el control de versiones

Publique una versión antes de ejecutar un trabajo de producción para que el trabajo quede anclado a la lógica revisada. Utilice la reversión cuando un cambio produzca resultados inesperados y compare para confirmar qué es lo que realmente ha modificado el cambio.

Agente de IA para la transformación de datos

El agente de IA de transformación de datos elimina el esfuerzo manual de crear y mantener los mapeos del FHIR. En lugar de escribir la lógica de conversión a mano, se describe el resultado que se desea obtener y el agente crea o actualiza la lógica subyacente: plantillas de Velocity para una configuración de mapeo de YAML para C-CDA CSV. El agente está integrado en el editor de perfiles AWS Management Console y también está disponible a través de la UpdateProfileWithAgent API y como herramienta de MCP, por lo que puede trabajar con él desde AWS Management Console, desde el código o desde un MCP-compatible IDE.

Qué hace el agente

• Genera una lógica de conversión a partir de sus datos. En el caso del formato CSV, el agente analiza los archivos de muestra que usted proporcionó al crear el perfil y crea un perfil base: deduce los recursos y campos objetivo del FHIR, de modo que se parte de un borrador de trabajo y no de un perfil en blanco. Por lo C-CDA tanto, adapta el perfil de AWS inicio a sus documentos.

• Edita la lógica de conversión a partir del lenguaje natural. Describa un cambio en un lenguaje sencillo y el agente actualizará la plantilla o el mapeo subyacente. Por ejemplo:

  • «Añada un mapa para el recurso sobre medicamentos».

  • «Haga un mapa del idioma preferido del paciente en la sección Idioma/Comunicación».

  • «Establezca el estado predeterminado en Washington para los recursos para pacientes».

  • «Asigne la columna RACE_CD a una extensión del FHIR».

  • «Omita los registros en los que el estado se haya introducido por error».

• Explica y revisa antes de presentar la solicitud. El agente presenta el cambio propuesto como una diferencia de la plantilla o mapeo afectado para que usted lo revise y lo aplica solo después de que usted lo acepte. Nada cambia de forma silenciosa en el perfil publicado, el agente solo realiza cambios en la versión preliminar.

• Refina de forma iterativa. Trabaje con el agente durante varios turnos para ajustar un mapeo hasta que el resultado convertido sea correcto, previsualizando los resultados comparándolos con los datos de muestra entre turnos con la API de transformación de sincronización.

C-CDA flujo de trabajo (plantillas de Velocity)

El agente edita las plantillas de Velocity que definen cómo se asignan C-CDA las secciones a los recursos del FHIR. Si se le pide que añada un mapeo de recursos, que cambie la forma en que se interpreta una sección, que establezca valores predeterminados o que gestione una variante del documento, actualizará las plantillas y devolverá una diferencia. Antes de publicarla, se obtiene una vista previa de la conversión comparándola con C-CDA los documentos de muestra.

Flujo de trabajo CSV (mapeo YAML)

Al crear un perfil CSV con archivos de ejemplo y, a continuación, invocar el agente, este analiza los encabezados, los valores de muestra y los patrones de datos de los archivos y, a continuación, propone una configuración de mapeo de YAML que incluye:

• mapeos de campos de columna a FHIR,

• detección del formato de fecha y reformateo a formatos FHIR, date/time

• traducciones de valores (por ejemplo, M → masculino, INPATIENT → IMP),

• primary/foreign-relaciones clave entre tablas,

• reglas de agregación que agrupan las filas de las tablas secundarias en matrices FHIR en el recurso principal,

• cualquier suposición que haya hecho el agente y cualquier duda que tenga sobre sus datos.

Usted acepta, rechaza o perfecciona cada mapeo propuesto y puede solicitar al agente que realice más ajustes. El agente deduce el mapeo a partir de una muestra de sus archivos y no del conjunto de datos completo, así que proporcione muestras que sean representativas de sus datos y revise el mapeo propuesto antes de convertirlo a escala.

Entradas que el agente acepta

Puede comunicarse con el agente mediante entradas en lenguaje natural. Algunas combinaciones incluyen:

• instrucciones,

• ejemplos de datos fuente (C-CDA secciones o esquemas CSV),

• documentación del esquema,

• Errores de validación del FHIR de una conversión anterior.

Edición manual

No es necesario que utilice el agente. Puede editar las plantillas de Velocity y las asignaciones de YAML directamente en cualquier momento, y combinar las ediciones manuales con los cambios creados por el agente en el mismo perfil.

Transformación y previsualización sincrónicas (en tiempo real)

La transformación sincrónica convierte una sola entrada y devuelve el resultado del FHIR inmediatamente, en lugar de ejecutar un trabajo asíncrono en Amazon S3. Existe para dos propósitos: probar un perfil mientras lo crea y ejecutar pequeñas transformaciones interactivas en un flujo. request/response

Funcionamiento

• Usted envía una entrada (un C-CDA documento o un conjunto de archivos CSV) en relación con un perfil y, en la respuesta, recibe los recursos del FHIR convertidos en un paquete del FHIR.

• La operación solo está disponible a través de la API REST: no se expone como un comando AWS CLI o un comando del SDK. Consulte Acceso al agente de transformación de datos.

• Para activar la detección de desviaciones en una llamada sincronizada, DriftDetectionEnabled selecciona true para ver, en la respuesta, qué elementos fuente aún no captura un perfil, lo que resulta útil al realizar iteraciones en un mapeo.

Límites de tamaño

La transformación sincrónica acepta C-CDA entradas de hasta 1 MB y entradas CSV combinadas de hasta 1 MB por solicitud. Para conjuntos de datos más grandes, utilice un trabajo de transformación masiva.

Obtenga una vista previa en AWS Management Console

Al crear un perfil en el AWS Management Console, la transformación sincrónica activa la vista previa en vivo: se ve la fuente por un lado y la salida FHIR convertida por el otro, y la vista previa se actualiza a medida que se va afinando el mapeo. Úsala para confirmar que el resultado es correcto antes de publicarlo.

Cuándo usar la sincronización o la masiva

Utilice la transformación sincrónica para validar un perfil comparándolo con los documentos representativos y para realizar conversiones por solicitud que dependan de la latencia, como una transmisión en vivo que convierte los documentos a medida que llegan. Utilice un trabajo de transformación masiva (a continuación) para conjuntos de datos grandes y para incorporarlos directamente a un almacén de datos. HealthLake

Trabajos de transformación masiva (asincrónica)

Un trabajo de transformación masiva convierte un gran conjunto de datos de Amazon S3 mediante un perfil publicado y se ejecuta de forma asíncrona mientras usted supervisa el progreso. Esta es la ruta de producción para las migraciones y para cargar datos en un almacén de datos. HealthLake Consulte esta página para ver la configuración de los permisos de IAM.

Funcionamiento

• Apunte un trabajo a un prefijo de Amazon S3 de los archivos fuente, elija un perfil publicado y elija un destino de salida. El trabajo escanea la entrada, convierte cada archivo (C-CDA) o conjunto de filas (CSV) y escribe los resultados.

• No hay ninguna infraestructura que aprovisionar: el trabajo se escala automáticamente.

Modos de salida

• Independiente: escriba el FHIR convertido en una ubicación de Amazon S3. Utilice la API. StartDataTransformationJob

• Compuesto (convertir e ingerir): convierte los archivos fuente e ingiere los recursos del FHIR resultantes directamente en un HealthLake almacén de datos en un solo paso, de modo que los datos se puedan consultar inmediatamente. Utilice la StartFHIRImportJob API con los parámetros,, y opcionalmente. ProfileId InputFormat DriftDetectionEnabled El almacén de datos debe estar en estado ACTIVO. Consulte el paso 7: Convertir e ingerir en un HealthLake almacén de datos para ver un ejemplo completo.

Gestión eficiente de los fallos

Las entradas con formato incorrecto se omiten y se registran en lugar de fallar en el lote, por lo que un solo archivo defectuoso nunca detiene un trabajo grande. Las entradas fallidas se escriben como archivos de error JSON con la ruta del archivo de entrada y el mensaje de error, para que puedas revisarlas y volver a procesarlas.

Diseño de salida

El servicio crea una carpeta con el ámbito del trabajo en la URI de Amazon S3 de salida utilizando el ID del trabajo. Dentro de esa carpeta:

• converted/: archivos de salida FHIR NDJSON (uno por archivo de entrada, por ejemplo, -record.ndjson). converted/patient

• ERROR/: detalle del error de las entradas fallidas (archivos JSON con los campos InputFile y ErrorMessage, por ejemplo). ERROR/bad-file.json

• Manifest.json: resumen del trabajo con métricas agregadas (archivos escaneados, convertidos, errores, recursos generados).

• trabajoLevelDriftResult.json: el informe de desviación agregado del trabajo, si la detección de desviaciones estaba habilitada.

• driftDetectionPerFileResults/: para C-CDA trabajos con detección de desviaciones activada, informes de desviación por archivo (p. ej., driftDetectionPerFileResults/patient -record_driftMetrics.json), de forma que pueda inspeccionar la cobertura de un archivo fuente individual en lugar de solo el agregado a nivel de trabajo.

Supervisión

Realice un seguimiento de un trabajo en ejecución a través de la página de detalles del AWS Management Console trabajo o la DescribeDataTransformationJob API: estado, archivos procesados (filas para CSV), recursos generados y errores. Las estadísticas y los registros de trabajos también están disponibles en Amazon CloudWatch.

Validación

El agente de transformación de datos se valida en varios puntos del ciclo de vida de la conversión, de modo que los problemas se detectan antes de que se conviertan en conversiones fallidas o en resultados no conformes.

• Validación de la fuente: comprueba que C-CDA las entradas estén bien formadas y se ajusten a la especificación. C-CDA Los errores incluyen detalles de la ubicación y una guía de corrección, para que pueda corregir los problemas de origen antes de ejecutar un trabajo de gran envergadura. La ValidateSource operación está disponible a través de la API REST para filtrar las entradas por adelantado.

• Validación de plantillas o mapas: valida las plantillas de Velocity (C-CDA) o el mapeo de YAML (CSV) de un perfil independientemente de cualquier dato, de forma que puedas confirmar que la lógica de conversión está bien formada antes de publicar o ejecutar un trabajo.

• Validación del FHIR de salida: comprueba que los recursos generados se ajustan al FHIR R4, de modo que las API y los almacenes de datos del FHIR posteriores acepten el resultado.

En conjunto, esto significa que un trabajo falla con menos frecuencia por motivos evitables: la validación de la fuente detecta las entradas incorrectas, la validación cartográfica detecta una lógica incorrecta y la validación de la salida confirma que el resultado cumple con los estándares.

OID-to-URI mapeo

C-CDA los documentos identifican los sistemas de códigos mediante OID (identificadores de objetos): identificadores numéricos antiguos, como 2.16.840.1.113883.6.1 (LOINC). El FHIR espera URIs de sistemas modernos como. http://loinc.org Si los OID se almacenan sin mapear, los valores del sistema resultantes no son interoperables y las herramientas posteriores del FHIR no pueden resolver los códigos. El agente de transformación de datos mapea entre ellos durante la conversión.

• Pre-built mapeos: los mapeos de los OID de atención médica más comunes (por ejemplo, LOINC, SNOMED CT RxNorm) se aplican automáticamente ICD-10, sin configuración.

• Mapeos personalizados: añada sus propios OID-to-URI mapeos para los sistemas de código específicos de sus fuentes, de forma que los sistemas propietarios o locales se resuelvan correctamente.

Esto se aplica a C-CDA las fuentes, donde los OID son la forma nativa en que se identifican los sistemas de códigos.

Procedencia

Los flujos de trabajo sanitarios regulados deben responder a la pregunta «¿de dónde provienen estos datos y cómo se produjeron?» para cualquier recurso. Cuando la procedencia está habilitada en un trabajo, Data Transformation Agent genera un recurso de procedencia FHIR para cada conversión, lo que proporciona a cada recurso de salida un linaje completo y consultable hasta su origen.

La cadena de procedencia

Procedencia → DocumentReference → archivo fuente. El recurso Provenance hace referencia a a DocumentReference, que registra el URI de Amazon S3 del archivo fuente y una suma de SHA-1 comprobación. La suma de comprobación le permite demostrar que el resultado se derivó de un archivo fuente específico e inalterado. También se proporciona un recurso de dispositivo que representa la transformación de AWS HealthLake datos como una entidad en caso de que esa información sea necesaria.

Record-level localizadores

La procedencia se determina no solo en el archivo de origen, sino también en su ubicación exacta, y el localizador varía según el formato de origen:

• C-CDA: un XPath que apunta al elemento fuente del que se deriva el recurso.

• CSV: el nombre de la tabla, la clave principal y el número de fila del registro de origen.

Campos capturados

Cada recurso de procedencia registra el URI y la suma de comprobación del archivo fuente, la versión del perfil utilizada para la conversión, una marca de tiempo y el localizador a nivel de registro.

Conformidad y uso

Los recursos de procedencia se ajustan al perfil de procedencia principal de EE. UU., por lo que interoperan con las herramientas estadounidenses. Core-aware Habilite la procedencia cuando necesite auditabilidad para garantizar su conformidad o cuando necesite rastrear un recurso de salida cuestionable hasta el elemento fuente exacto que lo generó. La procedencia está habilitada de forma predeterminada; establézcala en false ProvenanceEnabled para inhabilitarla.

Detección de desviaciones

Una conversión se puede realizar correctamente y, al mismo tiempo, eliminar silenciosamente datos de origen que un perfil aún no ha mapeado. Superficies de detección de deriva que están separadas. Se trata de un informe: cuando está activado, compara lo que contiene la fuente con lo que realmente produjo el perfil y registra lo que queda.

Qué contiene el informe

• La tasa de cobertura general de la conversión.

• Una lista ordenada de secciones y elementos de fuentes no mapeados, para que puedas priorizar las brechas de mayor impacto.

• Cualquier recurso esperado que no se haya producido.

• Trazabilidad completa hasta el archivo fuente y la ubicación del elemento (nombre de archivo y OID en el caso de CSV C-CDA, fila en el caso de CSV).

¿Cómo utilizar la detección de deriva

La detección de desviaciones está disponible en ambos modos de conversión, por lo que puede usarla tanto si está iterando en un solo archivo como si valida un conjunto de datos completo:

• Sincronización (en tiempo real): se establece DriftDetectionEnabled en true cuando se TransformData solicita ejecutar la detección de desviaciones en un solo archivo y obtener los resultados en la respuesta de la API. Esta es la forma más rápida de comprobar la cobertura al crear un perfil: convierte un documento representativo, ve exactamente lo que el perfil ha omitido, afina el mapeo y vuelve a intentarlo.

• Masivo (asíncrono): habilite la detección de desviaciones en un trabajo de transformación para medir la cobertura en todo el conjunto de datos. El informe se escribe como trabajo LevelDriftResult.json en la ubicación de salida de Amazon S3 del trabajo. En el caso de los C-CDA trabajos, los informes de desviación por archivo también se escriben en la carpetaDetectionPerFileResults/, para que pueda identificar las brechas de cobertura en un archivo fuente individual.

Acceso a MCP

El Model Context Protocol (MCP) expone el agente de transformación de datos a los agentes de IDE-based IA como herramientas a las que se puede recurrir, de modo que un desarrollador puede crear perfiles, ejecutar conversiones e investigar los fallos desde un asistente de su IDE, sin tener que cambiar al. AWS Management Console

• API de gestión de perfiles y trabajos: todas las API de gestión de perfiles y trabajos de Data Transformation Agent están disponibles como herramientas de MCP, por lo que puede crear, editar, publicar y ejecutar trabajos desde cualquier cliente. MCP-compatible

• Cualquier cliente de MCP: funciona con MCP-compatible IDE y asistentes, incluidos Kiro y Cursor.

• Sesiones duraderas: admite sesiones de varios turnos, por lo que una conversación sobre depuración o creación tiene contexto.

nota

La operación de conversión de sincronización (TransformData) y la validación de la fuente (ValidateSource) son herramientas de MCP REST-only y pueden no aparecer como herramientas de MCP. Su agente puede crear y ejecutar las llamadas REST en su nombre: consulte el paso 3: Pruebe el formato de solicitud con la conversión sincronizada.

Como el MCP comparte la misma superficie de API que los AWS CLI SDK para las operaciones de perfil y trabajo, esos flujos de trabajo no tienen ninguna brecha de capacidad entre trabajar en su IDE y trabajar con código o con el. AWS Management Console Consulte Cómo empezar con MCP la configuración y un ejemplo de flujo de trabajo.