Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Funzionalità di trasformazione dei dati
Ciascuna funzionalità riportata di seguito è documentata in cosa consiste, come funziona, le differenze tra C-CDA le fonti CSV e quando utilizzarla.
+ [Profili di trasformazione e controllo delle versioni](#data-transformation-profiles)
+ [Agente AI per la trasformazione dei dati](#data-transformation-ai-agent)
+ [Trasformazione e anteprima sincrone (in tempo reale)](#data-transformation-sync)
+ [Lavori di trasformazione in blocco (asincroni)](#data-transformation-bulk-jobs)
+ [Convalida](#data-transformation-validation)
+ [OID-to-URI mappatura](#data-transformation-oid-mapping)
+ [Provenienza](#data-transformation-provenance)
+ [Rilevamento delle deviazioni](#data-transformation-drift-detection)
+ [Accesso MCP](#data-transformation-mcp)
## Profili di trasformazione e controllo delle versioni
Un profilo di trasformazione è la definizione riutilizzabile di come un formato sorgente viene convertito in FHIR R4. Contiene la logica di conversione (modelli Velocity per C-CDA, una configurazione di mappatura YAML per CSV) e viene creato una sola volta e riutilizzato in tutti i datastore e i processi di trasformazione dell'account. Separare la definizione (profilo) dall'esecuzione (processo) significa creare e testare una conversione una sola volta, quindi applicare la stessa versione pubblicata a un numero qualsiasi di lavori.
### Creazione di un profilo
Puoi creare un profilo in tre modi:
+ Da un profilo iniziale o di base: inizia da un profilo di lavoro anziché da uno vuoto. Infatti C-CDA, lo AWS Starter Profile è un profilo predefinito che gestisce i AWS-defined formati di C-CDA documenti più comuni fin dall'inizio. Per CSV, fornisci file di esempio in Amazon S3 durante la creazione del profilo, quindi richiami l'agente AI per analizzarli e generare una configurazione di mappatura YAML.
+ Mediante clonazione: clona qualsiasi profilo esistente come punto di partenza per uno nuovo.
+ Da una mappatura grezza: fornisci direttamente i modelli Velocity (C-CDA) o una mappatura YAML (CSV). Questo è il percorso per distribuire i profili controllati dalla versione attraverso una pipeline (vedi). CI/CD [Guida introduttiva all'SDK e AWS CLI](data-transformation-getting-started-cli.md)
**Importante**
La creazione di un profilo CSV con SampleData registra la posizione del campione ma non esegue l'agente AI. Per generare la mappatura YAML, è necessario chiamare dopo la creazione. UpdateProfileWithAgent A quel punto, l'agente analizza i file di esempio e produce il profilo di base.
### Il ciclo di vita della versione
Un profilo può avere al massimo una bozza e fino a 99 versioni pubblicate:
+ Un nuovo profilo inizia come bozza (versione 0): una copia di lavoro mutabile che puoi modificare liberamente.
+ La pubblicazione della bozza crea una versione numerata e immutabile (v1, v2 e così via, fino alla v99). Le versioni pubblicate non cambiano mai.
+ I processi di trasformazione vengono sempre eseguiti sulla base dell'ultima versione pubblicata. Poiché la bozza è separata, puoi continuare a modificare mentre i lavori di produzione continuano a essere eseguiti sull'ultima versione pubblicata: le modifiche in corso non influiscono mai sulle conversioni in corso.
+ Un profilo con una versione pubblicata e nuove modifiche non pubblicate è in uno stato di modifiche non pubblicate; la versione pubblicata rimane attiva fino alla nuova pubblicazione.
### Confronto e ripristino
Poiché ogni versione pubblicata viene mantenuta, puoi vedere esattamente come è cambiata la logica di conversione nel corso della cronologia delle versioni. Il rollback non elimina nulla: crea una nuova versione da un'istantanea precedente, in modo da preservare la cronologia completa e l'audit trail.
### Quando utilizzare il controllo delle versioni
Pubblica una versione prima di eseguire un processo di produzione in modo che il lavoro venga bloccato sulla logica revisionata. Usa il rollback quando una modifica produce un output inaspettato e confronta per confermare quali modifiche hanno effettivamente alterato.
## Agente AI per la trasformazione dei dati
L'agente Data Transformation AI elimina lo sforzo manuale di creazione e manutenzione delle mappature FHIR. Invece di scrivere manualmente la logica di conversione, descrivi il risultato desiderato e l'agente produce o aggiorna la logica sottostante: modelli Velocity per C-CDA, una configurazione di mappatura YAML per CSV. L'agente è integrato nell'editor di profili Console di gestione AWS ed è disponibile anche tramite l' UpdateProfileWithAgent API e come strumento MCP, quindi puoi utilizzarlo da, dal Console di gestione AWS codice o da un IDE. MCP-compatible
### Cosa fa l'agente
+ Genera la logica di conversione dai tuoi dati. Per il formato CSV, l'agente analizza i file di esempio forniti durante la creazione del profilo e produce un profilo di base: deduce le risorse e i campi FHIR di destinazione, in modo da iniziare da una bozza di lavoro anziché da un profilo vuoto. Infatti C-CDA, adatta lo AWS Starter Profile ai tuoi documenti.
+ Modifica la logica di conversione dal linguaggio naturale. Descrivi una modifica in un linguaggio semplice e l'agente aggiorna il modello o la mappatura sottostanti. Ad esempio:
+ «Aggiungi una mappatura per la risorsa Medicinali».
+ «Mappa la lingua preferita del paziente dalla sezione Lingua/Comunicazione».
+ «Imposta lo stato predefinito su Washington for Patient Resources».
+ «Mappa la colonna RACE\_CD su un'estensione FHIR».
+ «Ignora i record in cui lo stato è inserito per errore».
+ Spiegazioni e recensioni prima di candidarti. L'agente presenta la modifica proposta come differenza del modello o della mappatura interessati affinché tu possa esaminarla e la applica solo dopo l'accettazione. Nulla cambia automaticamente sul profilo pubblicato, l'agente apporta modifiche solo alla versione bozza.
+ Perfeziona in modo iterativo. Collabora con l'agente su più turni per regolare una mappatura fino a quando l'output convertito non è corretto, visualizzando in anteprima i risultati rispetto ai dati di esempio tra un turno e l'altro con l'API sync Transform.
### C-CDA workflow (modelli Velocity)
L'agente modifica i modelli Velocity che definiscono il modo in cui le C-CDA sezioni vengono mappate alle risorse FHIR. Chiedigli di aggiungere una mappatura delle risorse, modificare il modo in cui una sezione viene interpretata, impostare valori predefiniti o gestire una variazione del documento, e aggiorna i modelli e restituisce una differenza. La conversione viene visualizzata in anteprima rispetto a C-CDA documenti di esempio prima della pubblicazione.
### Flusso di lavoro CSV (mappatura YAML)
Quando crei un profilo CSV con file di esempio e poi richiami l'agente, questo analizza le intestazioni, i valori di esempio e i modelli di dati dei file, quindi propone una configurazione di mappatura YAML che include:
+ mappature tra colonne e campi FHIR,
+ rilevamento del formato della data e riformattazione nei formati FHIR, date/time
+ traduzioni di valori (ad esempio, M → male, INPATIENT → IMP),
+ primary/foreign-relazioni chiave tra tabelle,
+ regole di aggregazione che raggruppano le righe della tabella secondaria in array FHIR sulla risorsa principale,
+ eventuali ipotesi formulate dall'agente ed eventuali domande sui dati dell'utente.
L'utente accetta, rifiuta o perfeziona ogni mappatura proposta e può chiedere all'agente ulteriori modifiche. L'agente deduce la mappatura da un campione dei tuoi file anziché dall'intero set di dati, quindi fornisci esempi rappresentativi dei tuoi dati ed esamina la mappatura proposta prima della conversione su larga scala.
### Input accettati dall'agente
È possibile comunicare con l'agente utilizzando input in linguaggio naturale. Alcune combinazioni includono:
+ istruzioni,
+ dati di origine di esempio (C-CDA sezioni o schemi CSV),
+ documentazione dello schema,
+ errori di convalida FHIR derivanti da una conversione precedente.
### Modifica manuale
Non è necessario utilizzare l'agente. È possibile modificare i modelli Velocity e le mappature YAML direttamente in qualsiasi momento e combinare modifiche manuali con modifiche create da agenti sullo stesso profilo.
## Trasformazione e anteprima sincrone (in tempo reale)
La trasformazione sincrona converte un singolo input e restituisce immediatamente il risultato FHIR, anziché eseguire un processo asincrono su Amazon S3. Esiste per due scopi: testare un profilo durante la creazione ed eseguire piccole trasformazioni interattive in un flusso. request/response
### Come funziona
+ Inviate un input (un C-CDA documento o un set di file CSV) per un profilo e nella risposta ricevete le risorse FHIR convertite come pacchetto FHIR.
+ L'operazione è disponibile solo tramite l'API REST: non è esposta come comando o SDK. AWS CLI Per informazioni, consulta [Accesso a Data Transformation Agent](data-transformation.md#data-transformation-accessing).
+ È possibile abilitare il rilevamento della deriva in una chiamata di sincronizzazione impostando su true DriftDetectionEnabled per vedere, nella risposta, quali elementi di origine non sono ancora stati acquisiti dal profilo: utile durante l'iterazione su una mappatura.
### Limiti di dimensione
La trasformazione sincrona accetta C-CDA input fino a 1 MB e input CSV combinati fino a 1 MB per richiesta. Per set di dati più grandi, utilizza un processo di trasformazione in blocco.
### Visualizza l'anteprima in Console di gestione AWS
Quando si crea un profilo in Console di gestione AWS, la trasformazione sincrona alimenta l'anteprima dal vivo: si vede la sorgente da un lato e l'output FHIR convertito dall'altro, e l'anteprima si aggiorna man mano che si perfeziona la mappatura. Utilizzatelo per confermare che l'output sia corretto prima della pubblicazione.
### Quando usare sync vs. bulk
Utilizza la trasformazione sincrona per convalidare un profilo rispetto a documenti rappresentativi e per conversioni per richiesta sensibili alla latenza, come un feed live che converte i documenti non appena arrivano. Utilizza un processo di trasformazione in blocco (di seguito) per set di dati di grandi dimensioni e per l'importazione diretta in un datastore. HealthLake
## Lavori di trasformazione in blocco (asincroni)
Un processo di trasformazione in blocco converte un set di dati di grandi dimensioni da Amazon S3 utilizzando un profilo pubblicato, eseguito in modo asincrono mentre controlli i progressi. Questo è il percorso di produzione per le migrazioni e per il caricamento dei dati in un datastore. HealthLake Fai riferimento a [questa pagina per la configurazione](https://docs.aws.amazon.com/healthlake/latest/devguide/getting-started-setting-up.html) delle autorizzazioni IAM.
### Come funziona
+ Indirizza un lavoro su un prefisso Amazon S3 dei file sorgente, scegli un profilo pubblicato e scegli una destinazione di output. Il job analizza l'input, converte ogni file (C-CDA) o set di righe (CSV) e scrive i risultati.
+ Non c'è alcuna infrastruttura da fornire: il lavoro si ridimensiona automaticamente.
### Modalità di output
+ Autonomo: scrivi FHIR convertito in una posizione Amazon S3. Usa l'API. StartDataTransformationJob
+ Composito (conversione e inserimento): converti i file sorgente e inserisci le risorse FHIR risultanti direttamente in un HealthLake datastore in un unico passaggio, in modo che i dati siano immediatamente interrogabili. Utilizza l' StartFHIRImportJob API con i parametri, e facoltativamente. ProfileId InputFormat DriftDetectionEnabled Il datastore deve essere in stato ATTIVO. Vedi Passaggio 7: Conversione e importazione in un HealthLake datastore per un esempio completo.
### Elegante gestione dei guasti
Gli input non validi vengono saltati e registrati anziché generare errori nel batch, quindi un singolo file danneggiato non interrompe mai un lavoro di grandi dimensioni. Gli input non riusciti vengono scritti come file di errore JSON con il percorso del file di input e il messaggio di errore, in modo da poterli rivedere e rielaborare.
### Layout di output
Il servizio crea una cartella con ambito di lavoro nell'URI di output di Amazon S3 utilizzando l'ID del lavoro. All'interno di quella cartella:
+ converted/: file di output FHIR NDJSON (uno per file di input, ad esempio -record.ndjson). converted/patient
+ ERROR/: dettagli dell'errore per gli input non riusciti (file JSON con campi InputFile ed errorMessage, ad esempio). ERROR/bad-file.json
+ Manifest.json: riepilogo del lavoro con metriche aggregate (file scansionati, convertiti, non riusciti, risorse generate).
+ jobLevelDriftResult.json: il rapporto aggregato sulla deriva del lavoro, se il rilevamento della deriva era abilitato.
+ driftDetectionPerFileResults/: per i C-CDA lavori con il rilevamento della deriva abilitato, riporta la deriva per file (ad esempio, driftDetectionPerFileResults/patient -record\_driftMetrics.json), in modo da poter controllare la copertura di un singolo file sorgente anziché solo dell'aggregato a livello di processo.
### Monitoraggio
Tieni traccia di un processo in esecuzione tramite la pagina dei dettagli del Console di gestione AWS lavoro o l' DescribeDataTransformationJob API: stato, file elaborati (righe per CSV), risorse generate e errori. Le metriche e i log dei lavori sono disponibili anche in Amazon. CloudWatch
## Convalida
Data Transformation Agent esegue la convalida in più punti del ciclo di vita della conversione, in modo che i problemi vengano individuati prima che si trasformino in conversioni non riuscite o in output non conforme.
+ Convalida dell'origine: verifica che gli input siano ben formati e conformi alle C-CDA specifiche. C-CDA Gli errori includono dettagli sulla posizione e linee guida per la correzione, in modo da poter risolvere i problemi all'origine prima di eseguire un lavoro di grandi dimensioni. L' ValidateSource operazione è disponibile tramite l'API REST per visualizzare gli input in anticipo.
+ Convalida del modello o della mappatura: convalida i modelli Velocity (C-CDA) o la mappatura YAML (CSV) di un profilo indipendentemente dai dati, in modo da poter confermare che la logica di conversione sia ben strutturata prima della pubblicazione o dell'esecuzione di un lavoro.
+ Convalida FHIR dell'output: verifica che le risorse generate siano conformi a FHIR R4, pertanto le API e i datastore FHIR a valle accettano l'output.
Insieme, ciò significa che un lavoro fallisce meno spesso per ragioni evitabili: la convalida della fonte rileva gli input errati, la convalida della mappatura rileva la logica errata e la convalida dell'output conferma che il risultato è conforme agli standard.
## OID-to-URI mappatura
C-CDA i documenti identificano i sistemi di codice utilizzando OID (Object Identifiers): identificatori numerici legacy come (LOINC). `2.16.840.1.113883.6.1` FHIR prevede URI di sistema moderni come. `http://loinc.org` Se gli OID vengono trasferiti in modalità non mappata, i valori di sistema risultanti non sono interoperabili e gli strumenti FHIR a valle non sono in grado di risolvere i codici. Data Transformation Agent esegue la mappatura tra di essi durante la conversione.
+ **Pre-built mappature: le** mappature per gli OID sanitari più comuni (ad esempio, LOINC, SNOMED CT,, RxNorm) vengono applicate automaticamente ICD-10, senza alcuna configurazione.
+ Mappature **personalizzate: aggiungi mappature** personalizzate per i sistemi di codice specifici OID-to-URI delle tue fonti, in modo che i sistemi proprietari o locali si risolvano correttamente.
Questo vale per le C-CDA fonti, in cui gli OID sono il modo nativo in cui i sistemi di codice vengono identificati.
## Provenienza
I flussi di lavoro regolamentati nel settore sanitario devono rispondere alla domanda «da dove provengono questi dati e come sono stati prodotti?» per qualsiasi risorsa. Quando la provenienza è abilitata su un processo, Data Transformation Agent genera una risorsa FHIR Provenance per ogni conversione, fornendo a ciascuna risorsa di output un collegamento completo e interrogabile alla sua origine.
### La catena di provenienza
Provenienza → DocumentReference → file sorgente. La risorsa Provenance fa riferimento a DocumentReference, che registra l'URI Amazon S3 del file sorgente e SHA-1 un checksum. Il checksum consente di dimostrare che l'output è stato derivato da un file sorgente specifico e inalterato. Se tali informazioni sono necessarie, viene fornita anche una risorsa del dispositivo che rappresenta AWS HealthLake Data Transformation come entità.
### Record-level localizzatori
La provenienza non si riferisce solo al file sorgente ma alla posizione esatta al suo interno, e il localizzatore differisce in base al formato sorgente:
+ **C-CDA**: un XPath che punta all'elemento sorgente da cui è derivata la risorsa.
+ **CSV**: nome della tabella, chiave primaria e numero di riga del record di origine.
### Campi catturati
Ogni risorsa Provenance registra l'URI e il checksum del file sorgente, la versione del profilo utilizzata per la conversione, un timestamp e il localizzatore a livello di record.
### Conformità e utilizzo
Le risorse Provenance sono conformi al profilo US Core Provenance, quindi interagiscono con gli strumenti statunitensi. Core-aware Abilita la provenienza quando hai bisogno di verificabilità per la conformità o quando devi ricondurre una risorsa di output discutibile all'esatto elemento di origine che l'ha prodotta. La provenienza è abilitata per impostazione predefinita; impostala su false ProvenanceEnabled per disabilitarla.
## Rilevamento delle deviazioni
Una conversione può avere successo eliminando silenziosamente i dati di origine che un profilo non ha ancora mappato. Le superfici di rilevamento della deriva sono quelle lacune. È un rapporto: se abilitato, confronta ciò che contiene la fonte con ciò che il profilo ha effettivamente prodotto e registra ciò che è rimasto.
### Cosa contiene il rapporto
+ Il tasso di copertura complessivo per la conversione.
+ Un elenco classificato di sezioni ed elementi di origine non mappati, in modo da poter dare priorità alle lacune con il maggiore impatto.
+ Tutte le risorse previste che non sono state prodotte.
+ Tracciabilità completa fino al file di origine e alla posizione dell'elemento (nome file e OID per C-CDA, riga per CSV).
### Come utilizzare il rilevamento della deriva
Il rilevamento della deriva è disponibile in entrambe le modalità di conversione, quindi puoi utilizzarlo sia che tu stia iterando su un singolo file o convalidando un set di dati completo:
+ Sincronizzazione (in tempo reale): impostata DriftDetectionEnabled su true su una TransformData richiesta per eseguire il rilevamento della deriva su un singolo file e ottenere i risultati nella risposta dell'API. Questo è il modo più veloce per verificare la copertura durante la creazione di un profilo: converti un documento rappresentativo, vedi esattamente cosa non ha visto nel profilo, perfeziona la mappatura e riprova.
+ In blocco (asincrono): abilita il rilevamento delle deviazioni in un processo di trasformazione per misurare la copertura dell'intero set di dati. Il report viene scritto come job LevelDriftResult.json nella posizione di output Amazon S3 del processo. Per i C-CDA lavori, i report sulle deviazioni per file vengono scritti anche nella cartella driftDetectionPerFileResults/, in modo da poter individuare le lacune di copertura in un singolo file sorgente.
## Accesso MCP
Il Model Context Protocol (MCP) espone Data Transformation Agent agli agenti IDE-based AI come strumenti richiamabili, in modo che uno sviluppatore possa creare profili, eseguire conversioni e indagare sugli errori da un assistente nel proprio IDE, senza passare a. Console di gestione AWS
+ API per la gestione dei profili e dei lavori: tutte le API di gestione dei profili e dei lavori di Data Transformation Agent sono disponibili come strumenti MCP, quindi puoi creare, modificare, pubblicare ed eseguire lavori da qualsiasi cliente. MCP-compatible
+ Qualsiasi client MCP: funziona con MCP-compatible IDE e assistenti, inclusi Kiro e Cursor.
+ Sessioni durature: supporta sessioni a più turni, quindi una conversazione di debug o di creazione ha un contesto.
**Nota**
L'operazione di conversione di sincronizzazione (TransformData) e la convalida del codice sorgente (ValidateSource) sono REST-only e potrebbero non apparire come strumenti MCP. Il tuo agente può costruire ed eseguire le chiamate REST per tuo conto: vedi Fase 3: Test con conversione di sincronizzazione per il formato della richiesta.
Poiché MCP condivide la stessa superficie API AWS CLI e gli SDK per le operazioni relative ai profili e alle mansioni, non vi è alcun divario di capacità per questi flussi di lavoro tra l'utilizzo dell'IDE e l'utilizzo del codice o del. Console di gestione AWS Vedi [Guida introduttiva a MCP](data-transformation-getting-started-mcp.md) per la configurazione e un esempio di flusso di lavoro.