As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
Recursos de transformação de dados
Cada recurso abaixo está documentado com o que é, como funciona, diferenças entre fontes C-CDA e fontes CSV e quando usá-lo.
Perfis de transformação e controle de versão
Um perfil de transformação é a definição reutilizável de como um formato de origem é convertido em FHIR R4. Ele contém a lógica de conversão (modelos Velocity para C-CDA, uma configuração de mapeamento YAML para CSV) e é criado uma vez e reutilizado em todos os armazenamentos de dados e trabalhos de transformação em sua conta. Separar a definição (perfil) da execução (trabalho) significa criar e testar uma conversão uma vez e, em seguida, aplicar a mesma versão publicada a qualquer número de trabalhos.
Criar um perfil
Você cria um perfil de uma das três maneiras:
-
De um perfil inicial ou básico: comece com um perfil de trabalho em vez de um em branco. Pois C-CDA, o Perfil AWS Inicial é um perfil pré-criado que lida AWS-defined com formatos de C-CDA documentos comuns prontos para uso. Para CSV, você fornece arquivos de amostra no Amazon S3 ao criar o perfil e, em seguida, invoca o agente de IA para analisá-los e gerar uma configuração de mapeamento YAML.
-
Clonando: clone qualquer perfil existente como ponto de partida para um novo.
-
A partir de um mapeamento bruto: forneça modelos Velocity (C-CDA) ou um mapeamento YAML (CSV) diretamente. Esse é o caminho para implantar perfis com controle de versão por meio de um CI/CD pipeline (consulte). Começando com o SDK e AWS CLI
Importante
A criação de um perfil CSV SampleData registra a localização da amostra, mas não executa o agente de IA. Para gerar o mapeamento YAML, você deve chamar UpdateProfileWithAgent após a criação. O agente analisa seus arquivos de amostra nesse ponto e produz o perfil básico.
O ciclo de vida da versão
Um perfil pode ter no máximo um rascunho e até 99 versões publicadas:
-
Um novo perfil começa como um rascunho (versão 0): uma cópia de trabalho mutável que você pode editar livremente.
-
A publicação do rascunho cria uma versão imutável e numerada (v1, v2 e assim por diante, até v99). As versões publicadas nunca mudam.
-
Os trabalhos de transformação sempre são executados com base na versão mais recente publicada. Como o rascunho é separado, você pode continuar editando enquanto os trabalhos de produção continuam sendo executados na última versão publicada: as edições em andamento nunca afetam as conversões em execução.
-
Um perfil com uma versão publicada e edições não publicadas mais recentes está em um estado de alterações não publicadas; a versão publicada permanece ativa até que você publique novamente.
Comparando e revertendo
Como cada versão publicada é mantida, você pode ver exatamente como a lógica de conversão mudou ao longo do histórico da versão. A reversão não exclui nada: ela cria uma nova versão a partir de um instantâneo anterior, para que o histórico completo e a trilha de auditoria sejam preservados.
Quando usar o controle de versão
Publique uma versão antes de executar um trabalho de produção para que o trabalho seja fixado na lógica revisada. Use a reversão quando uma alteração produz uma saída inesperada e compare para confirmar o que a alteração realmente alterou.
Agente de IA de transformação de dados
O agente de IA de transformação de dados elimina o esforço manual de criar e manter mapeamentos FHIR. Em vez de escrever a lógica de conversão manualmente, você descreve o resultado desejado e o agente produz ou atualiza a lógica subjacente: modelos Velocity para C-CDA, uma configuração de mapeamento YAML para CSV. O agente está incorporado ao editor de perfil no Console de gerenciamento da AWS e também está disponível por meio da UpdateProfileWithAgent API e como uma ferramenta MCP, para que você possa trabalhar com ele a partir do Console de gerenciamento da AWS, do código ou de um MCP-compatible IDE.
O que o agente faz
O agente de IA de transformação de dados executa as seguintes tarefas:
-
Gera lógica de conversão a partir de seus dados. Para CSV, o agente analisa os arquivos de amostra que você forneceu na criação do perfil e produz um perfil básico: inferindo os recursos e campos do FHIR de destino, para que você comece com um rascunho de trabalho em vez de um perfil em branco. Pois C-CDA, ele adapta o Perfil AWS Inicial aos seus documentos.
-
Edita a lógica de conversão da linguagem natural. Descreva uma mudança em linguagem simples e o agente atualizará o modelo ou mapeamento subjacente. Por exemplo:
-
“Adicione um mapeamento para o recurso de medicamentos.”
-
“Mapeie o idioma preferido do paciente na seção Idioma/Comunicação.”
-
“Defina o estado padrão como Washington para recursos do paciente.”
-
“Mapeie a coluna RACE_CD para uma extensão FHIR.”
-
“Ignore registros em que o status foi inserido por engano.”
-
-
Explica e revisa antes de se inscrever. O agente apresenta a alteração proposta como uma diferença do modelo ou mapeamento afetado para você revisar e a aplica somente após a aceitação. Nada muda silenciosamente no perfil publicado, o agente só faz alterações na versão preliminar.
-
Refina iterativamente. Trabalhe com o agente em vários turnos para ajustar um mapeamento até que a saída convertida esteja correta, visualizando os resultados em relação aos dados de amostra entre os turnos com a API de transformação de sincronização.
C-CDA fluxo de trabalho (modelos Velocity)
O agente edita os modelos do Velocity que definem como as C-CDA seções são mapeadas para os recursos do FHIR. Peça que ele adicione um mapeamento de recursos, altere a forma como uma seção é interpretada, defina valores padrão ou manipule uma variação do documento, e ele atualizará os modelos e retornará um diff. Você visualiza a conversão em C-CDA documentos de amostra antes de publicá-la.
Fluxo de trabalho CSV (mapeamento YAML)
Quando você cria um perfil CSV com arquivos de amostra e invoca o agente, ele analisa os cabeçalhos, valores de amostra e padrões de dados dos seus arquivos e propõe uma configuração de mapeamento YAML que inclui:
-
mapeamentos de coluna para campo,
-
detecção e reformatação do formato de data para formatos FHIR, date/time
-
traduções de valores (por exemplo, M → masculino, INPATIENT → IMP),
-
primary/foreign-principais relações entre tabelas,
-
regras de agregação que dobram as linhas da tabela secundária em matrizes FHIR no recurso principal,
-
quaisquer suposições feitas pelo agente e quaisquer dúvidas que ele tenha sobre seus dados.
Você aceita, rejeita ou refina cada mapeamento proposto e pode solicitar ajustes adicionais ao agente. O agente deduz o mapeamento a partir de uma amostra de seus arquivos em vez do conjunto de dados completo, portanto, forneça amostras representativas de seus dados e revise o mapeamento proposto antes de converter em grande escala.
Entradas que o agente aceita
Você pode se comunicar com o agente em entradas de linguagem natural. Algumas combinações incluem:
-
instruções,
-
dados de origem de amostra (C-CDA seções ou esquemas CSV),
-
documentação do esquema,
-
Erros de validação FHIR de uma conversão anterior.
Edição manual
Você não precisa usar o agente. Você pode editar modelos do Velocity e mapeamentos YAML diretamente a qualquer momento e combinar edições manuais com alterações criadas pelo agente no mesmo perfil.
Transformação e visualização síncronas (em tempo real)
A transformação síncrona converte uma única entrada e retorna o resultado do FHIR imediatamente, em vez de executar uma tarefa assíncrona no Amazon S3. Ele existe para duas finalidades: testar um perfil enquanto você o cria e executar pequenas transformações interativas em um request/response fluxo.
Como funciona
Uma transformação síncrona processa uma única entrada da seguinte forma:
-
Você envia uma entrada (um C-CDA documento ou um conjunto de arquivos CSV) em um perfil e recebe os recursos FHIR convertidos como um pacote FHIR na resposta.
-
A operação está disponível somente por meio da API REST: ela não é exposta como um comando AWS CLI ou SDK. Consulte Acessando o agente de transformação de dados.
-
Você pode ativar a detecção de desvio em uma chamada de sincronização definindo como true DriftDetectionEnabled para ver, na resposta, quais elementos de origem um perfil ainda não captura: útil durante a iteração em um mapeamento.
Limites de tamanho
A transformação C-CDA síncrona aceita entradas de até 1 MB e entradas CSV combinadas de até 1 MB por solicitação. Para conjuntos de dados maiores, use um trabalho de transformação em massa.
Pré-visualização no Console de gerenciamento da AWS
Ao criar um perfil no Console de gerenciamento da AWS, a transformação síncrona potencializa a visualização ao vivo: você vê a fonte de um lado e a saída FHIR convertida do outro, e a visualização é atualizada à medida que você refina o mapeamento. Use-o para confirmar se a saída está correta antes da publicação.
Quando usar sincronização versus em massa
Use a transformação síncrona para validar um perfil em documentos representativos e para conversões por solicitação sensíveis à latência, como um feed ao vivo que converte documentos à medida que eles chegam. Use um trabalho de transformação em massa (abaixo) para grandes conjuntos de dados e para ingestão direta em um HealthLake armazenamento de dados.
Trabalhos de transformação em massa (assíncronos)
Um trabalho de transformação em massa converte um grande conjunto de dados do Amazon S3 usando um perfil publicado, executado de forma assíncrona enquanto você monitora o progresso. Esse é o caminho de produção para migrações e carregamento de dados em um HealthLake datastore. Consulte esta página para ver a configuração das permissões do IAM.
Como funciona
Um trabalho de transformação em massa funciona da seguinte maneira:
-
Aponte um trabalho para um prefixo de arquivos de origem do Amazon S3, escolha um perfil publicado e escolha um destino de saída. O trabalho verifica a entrada, converte cada arquivo (C-CDA) ou conjunto de linhas (CSV) e grava os resultados.
-
Não há infraestrutura para provisionar: o trabalho é escalado automaticamente.
Modos de saída
Um trabalho em massa oferece suporte aos seguintes modos de saída:
-
Autônomo: grave o FHIR convertido em um local do Amazon S3. Use a StartDataTransformationJob API.
-
Composto (conversão e ingestão): converta arquivos de origem e ingira os recursos FHIR resultantes diretamente em um HealthLake armazenamento de dados em uma única etapa, para que os dados possam ser consultados imediatamente. Use a StartFHIRImportJob API com os DriftDetectionEnabled parâmetros ProfileId, InputFormat, e opcionalmente. O armazenamento de dados deve estar no estado ATIVO. Consulte a Etapa 7: converter e ingerir em um HealthLake armazenamento de dados para ver um exemplo completo.
Tratamento elegante de falhas
As entradas malformadas são ignoradas e registradas em vez de falharem no lote, portanto, um único arquivo incorreto nunca interrompe um trabalho grande. As entradas com falha são gravadas como arquivos de erro JSON com o caminho do arquivo de entrada e a mensagem de erro, para que você possa revisá-las e reprocessá-las.
Layout de saída
O serviço cria uma pasta com escopo de trabalho sob seu URI de saída do Amazon S3 usando o ID do trabalho. Dentro dessa pasta:
-
convertidos/: arquivos de saída FHIR NDJSON (um por arquivo de entrada, por exemplo, -record.ndjson). converted/patient
-
ERROR/: detalhe do erro para entradas com falha (arquivos JSON com os campos InputFile e ErrorMessage, por exemplo,). ERROR/bad-file.json
-
Manifest.json: resumo do trabalho com métricas agregadas (arquivos digitalizados, convertidos, com falha, recursos gerados).
-
trabalhoLevelDriftResult.json: o relatório de desvio agregado para o trabalho, se a detecção de desvio estiver ativada.
-
driftDetectionPerFileResults/: para C-CDA trabalhos com a detecção de desvio ativada, relatórios de desvio por arquivo (por exemplo, driftDetectionPerFileResults/patient -record_driftMetrics.json), para que você possa inspecionar a cobertura de um arquivo de origem individual em vez de apenas o agregado no nível do trabalho.
Monitoramento
Acompanhe um trabalho em execução por meio da página de detalhes do Console de gerenciamento da AWS trabalho ou da DescribeDataTransformationJob API: status, arquivos processados (linhas para CSV), recursos gerados e falhas. Métricas e registros de tarefas também estão disponíveis na Amazon CloudWatch.
Validação
O Data Transformation Agent valida em vários pontos do ciclo de vida da conversão, para que os problemas sejam detectados antes que se tornem conversões com falha ou saída não compatível.
-
Validação da fonte: verifica se as C-CDA entradas estão bem formadas e em conformidade com a especificação. C-CDA Os erros incluem detalhes de localização e diretrizes de remediação, para que você possa corrigir problemas de origem antes de executar uma tarefa grande. A ValidateSource operação está disponível por meio da API REST para filtrar as entradas antecipadamente.
-
Validação de modelo/mapeamento: valida os modelos Velocity (C-CDA) ou o mapeamento YAML (CSV) de um perfil independentemente de quaisquer dados, para que você possa confirmar se a lógica de conversão está bem formada antes de publicar ou executar um trabalho.
-
Validação do FHIR de saída: verifica se os recursos gerados estão em conformidade com o FHIR R4, para que as APIs e os armazenamentos de dados do FHIR downstream aceitem a saída.
Juntos, isso significa que um trabalho falha com menos frequência por motivos evitáveis: a validação da fonte detecta entradas incorretas, a validação do mapeamento detecta a lógica incorreta e a validação da saída confirma que o resultado está em conformidade com os padrões.
OID-to-URI mapeamento
C-CDA documentos identificam sistemas de código usando OIDs (Identificadores de Objetos): identificadores numéricos legados, como 2.16.840.1.113883.6.1 (LOINC). O FHIR espera URIs de sistema modernos, como. http://loinc.org Se os OIDs forem transportados sem mapeamento, os valores do sistema resultantes não serão interoperáveis e as ferramentas FHIR posteriores não poderão resolver os códigos. O Agente de Transformação de Dados mapeia entre eles durante a conversão.
-
Pre-built mapeamentos: os mapeamentos para OIDs de saúde comuns (por exemplo, LOINC, SNOMED CT,, RxNorm) são aplicados automaticamente ICD-10, sem configuração.
-
Mapeamentos personalizados: adicione seus próprios OID-to-URI mapeamentos para sistemas de código específicos de suas fontes, para que sistemas proprietários ou locais sejam resolvidos corretamente.
Isso se aplica às C-CDA fontes, nas quais os OIDs são a forma nativa pela qual os sistemas de código são identificados.
Proveniência
Os fluxos de trabalho de saúde regulamentados precisam responder “de onde vieram esses dados e como foram produzidos?” para qualquer recurso. Quando a proveniência é ativada em um trabalho, o Data Transformation Agent gera um recurso de proveniência FHIR para cada conversão, fornecendo a cada recurso de saída uma linhagem completa e consultável de volta à sua origem.
A cadeia de proveniência
Proveniência → DocumentReference → arquivo fonte. O recurso Provenance faz referência a DocumentReference, que registra o URI do Amazon S3 do arquivo de origem e uma soma de verificação. SHA-1 A soma de verificação permite provar que a saída foi derivada de um arquivo fonte específico e inalterado. Um recurso de dispositivo representando a transformação de AWS HealthLake dados como uma entidade também é fornecido caso essas informações sejam necessárias.
Record-level localizadores
A proveniência não depende apenas do arquivo de origem, mas também da localização exata dentro dele, e o localizador difere de acordo com o formato de origem:
-
C-CDA: um XPath apontando para o elemento de origem do qual o recurso foi derivado.
-
CSV: o nome da tabela, a chave primária e o número da linha do registro de origem.
Campos capturados
Cada recurso de proveniência registra o URI e a soma de verificação do arquivo de origem, a versão do perfil usada para a conversão, um carimbo de data/hora e o localizador no nível do registro.
Conformidade e uso
Os recursos de proveniência estão em conformidade com o perfil de proveniência central dos EUA, portanto, interoperam com as ferramentas dos EUA. Core-aware Ative a proveniência quando precisar de auditabilidade para fins de conformidade ou quando precisar rastrear um recurso de saída questionável até o elemento de origem exato que o produziu. A proveniência é ativada por padrão; ProvenanceEnabled defina como false para desativá-la.
Detecção de desvios
Uma conversão pode ser bem-sucedida ao descartar silenciosamente os dados de origem que um perfil ainda não mapeou. Superfícies de detecção de deriva que se separam. É um relatório: quando ativado, ele compara o que a fonte contém com o que o perfil realmente produziu e registra o que foi deixado para trás.
O que o relatório contém
O relatório de deriva contém as seguintes informações:
-
A taxa de cobertura geral da conversão.
-
Uma lista classificada de seções e elementos de origem não mapeados, para que você possa priorizar as lacunas de maior impacto.
-
Quaisquer recursos esperados que não foram produzidos.
-
Rastreabilidade total até o arquivo de origem e a localização do elemento (nome do arquivo e OID para C-CDA, linha para CSV).
Como usar a detecção de desvio
A detecção de desvio está disponível nos dois modos de conversão, para que você possa usá-la se estiver iterando em um único arquivo ou validando um conjunto de dados completo:
-
Sincronização (em tempo real): DriftDetectionEnabled defina como true em uma TransformData solicitação para executar a detecção de desvio em um único arquivo e recuperar os resultados na resposta da API. Essa é a maneira mais rápida de verificar a cobertura enquanto você cria um perfil: converta um documento representativo, veja exatamente o que o perfil perdeu, refine o mapeamento e tente novamente.
-
Em massa (assíncrono): habilite a detecção de desvios em um trabalho de transformação para medir a cobertura em todo o conjunto de dados. O relatório é escrito como trabalho LevelDriftResult.json no local de saída do Amazon S3 do trabalho. Para C-CDA trabalhos, os relatórios de desvio por arquivo também são gravados na pasta driftDetectionPerFileResults/, para que você possa identificar lacunas de cobertura em um arquivo de origem individual.
Acesso ao MCP
O Model Context Protocol (MCP) expõe o Agente de Transformação de Dados aos agentes de IDE-based IA como ferramentas que podem ser chamadas, para que um desenvolvedor possa criar perfis, executar conversões e investigar falhas de um assistente em seu IDE: sem mudar para o. Console de gerenciamento da AWS
-
APIs de gerenciamento de perfis e tarefas: todas as APIs de gerenciamento de tarefas e perfis do Data Transformation Agent estão disponíveis como ferramentas MCP, para que você possa criar, editar, publicar e executar trabalhos a partir de qualquer cliente. MCP-compatible
-
Qualquer cliente MCP: funciona com MCP-compatible IDEs e assistentes, incluindo Kiro e Cursor.
-
Sessões duráveis: suporta sessões de vários turnos, portanto, uma conversa de depuração ou criação mantém o contexto.
nota
A operação de conversão de sincronização (TransformData) e a validação da fonte (ValidateSource) são REST-only e podem não aparecer como ferramentas MCP. Seu agente pode criar e executar as chamadas REST em seu nome: consulte Etapa 3: Teste com conversão de sincronização para o formato da solicitação.
Como o MCP compartilha a mesma superfície de API do AWS CLI e dos SDKs para operações de perfil e trabalho, não há lacuna de capacidade para esses fluxos de trabalho entre trabalhar em seu IDE e trabalhar por meio de código ou o. Console de gerenciamento da AWS Consulte Começando com o MCP para ver a configuração e um exemplo de fluxo de trabalho.
