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 C-CDA as fontes CSV e quando usá-lo.
+ [Perfis de transformação e controle de versão](#data-transformation-profiles)
+ [Agente de IA de transformação de dados](#data-transformation-ai-agent)
+ [Transformação e visualização síncronas (em tempo real)](#data-transformation-sync)
+ [Trabalhos de transformação em massa (assíncronos)](#data-transformation-bulk-jobs)
+ [Validação](#data-transformation-validation)
+ [OID-to-URI mapeamento](#data-transformation-oid-mapping)
+ [Proveniência](#data-transformation-provenance)
+ [Detecção de desvios](#data-transformation-drift-detection)
+ [Acesso MCP](#data-transformation-mcp)
## 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 depois 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:
+ A partir de um perfil inicial ou básico: comece com um perfil de trabalho em vez de um perfil em branco. Pois C-CDA, o AWS Starter Profile é um perfil pré-construído 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 do 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). [Introdução ao SDK e AWS CLI](data-transformation-getting-started-cli.md)
**Importante**
A criação de um perfil CSV com SampleData registra o local 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é a 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: 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 todas as versões publicadas são mantidas, você pode ver exatamente como a lógica de conversão mudou no 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 produzir uma saída inesperada e compare para confirmar o que uma 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 do Velocity para C-CDA, uma configuração de mapeamento YAML para CSV. O agente está incorporado no editor de perfil do 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
+ 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 de destino do FHIR, 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 alteração em linguagem simples e o agente atualizará o modelo ou mapeamento subjacente. Por exemplo:
+ “Adicione um mapeamento para o recurso de medicação.”
+ “Mapeie o idioma preferido do paciente na seção Comunicação de idiomas.”
+ “Defina o estado padrão como Washington para recursos do paciente.”
+ “Mapeie a coluna RACE\_CD para uma extensão FHIR.”
+ “Ignorar registros em que o status é inserido por engano.”
+ Explica e analisa 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 de forma iterativa. 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 do Velocity)
O agente edita os modelos do Velocity que definem como as C-CDA seções são mapeadas para os recursos do FHIR. Solicite 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 atualiza os modelos e retorna uma diferença. Você visualiza a conversão em C-CDA documentos de amostra antes da publicação.
### Fluxo de trabalho CSV (mapeamento YAML)
Quando você cria um perfil CSV com arquivos de amostra e, em seguida, invoca o agente, ele analisa os cabeçalhos, os valores de amostra e os padrões de dados dos seus arquivos e propõe uma configuração de mapeamento YAML que inclui:
+ Mapeamentos de campo de coluna a quinta,
+ detecção e reformatação de formato de data para formatos FHIR, date/time
+ traduções de valores (por exemplo, M → masculino, INPATIENT → IMP),
+ primary/foreign-relacionamentos-chave entre tabelas,
+ regras de agregação que dobram as linhas da tabela secundária em matrizes FHIR no recurso pai,
+ 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 mais ajustes ao agente. O agente infere o mapeamento 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 da conversão 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 do 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 um trabalho assíncrono 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
+ Você envia uma entrada (um C-CDA documento ou um conjunto de arquivos CSV) em relação a 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](data-transformation.md#data-transformation-accessing).
+ 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 ao iterar 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 aciona 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 que 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 relação a 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 armazenamento de dados. Consulte [esta página](https://docs.aws.amazon.com/healthlake/latest/devguide/getting-started-setting-up.html) para ver a configuração das permissões do IAM.
### Como funciona
+ 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 digitaliza 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
+ 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 consuma 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
Entradas malformadas são ignoradas e registradas em vez de falhar 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 analisá-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:
+ converted/: 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 escaneados, convertidos, com falha, recursos gerados).
+ tarefaLevelDriftResult.json: o relatório de desvio agregado da tarefa, se a detecção de desvio estiver ativada.
+ driftDetectionPerFileResults/: para C-CDA trabalhos com 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 trabalhos também estão disponíveis na Amazon CloudWatch.
## Validação
O Agente de Transformação de Dados é validado em vários pontos do ciclo de vida da conversão, para que os problemas sejam detectados antes que se tornem conversões com falhas ou resultados não compatíveis.
+ Validação da fonte: verifica se as C-CDA entradas estão bem formadas e estão em conformidade com a especificação. C-CDA Os erros incluem detalhes da localização e orientações de remediação, para que você possa corrigir os problemas de origem antes de executar um trabalho 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 FHIR de saída: verifica se os recursos gerados estão em conformidade com o FHIR R4, para que as APIs e os datastores FHIR downstream aceitem a saída.
Juntos, eles significam que um trabalho falha com menos frequência por motivos evitáveis: a validação da fonte captura 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 antigos, 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 resultantes do sistema não serão interoperáveis e as ferramentas FHIR posteriores não poderão resolver os códigos. O Data Transformation Agent mapeia entre eles durante a conversão.
+ **Pre-built mapeamentos: mapeamentos** para OIDs de assistência médica 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 resolvam 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 regulamentados da área de saúde precisam responder “de onde vieram esses dados e como foram produzidos?” para qualquer recurso. Quando a proveniência é ativada em uma tarefa, o Agente de Transformação de Dados gera um recurso de proveniência FHIR para cada conversão, dando 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 de origem 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 se baseia apenas no arquivo de origem, mas na 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 em nível de registro.
### Conformidade e uso
Os recursos de proveniência estão em conformidade com o perfil de proveniência principal dos EUA, portanto, eles 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 eliminar silenciosamente os dados de origem que um perfil ainda não mapeou. A detecção de deriva supera essa lacuna. É 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
+ 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.
+ Todos os 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 desvios está disponível nos dois modos de conversão, então você pode 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 obter 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íncrona): 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 variação por arquivo também são escritos na pasta driftDetectionPerFileResults/, para que você possa identificar lacunas de cobertura em um arquivo de origem individual.
## Acesso 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 com 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 perfil e gerenciamento de tarefas do Data Transformation Agent estão disponíveis como ferramentas MCP, para que você possa criar, editar, publicar e executar trabalhos 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 que os SDKs AWS CLI e os SDKs para operações de perfil e trabalho, não há lacuna de capacidade nesses fluxos de trabalho entre trabalhar em seu IDE e trabalhar com código ou o. Console de gerenciamento da AWS Consulte [Começando com o MCP](data-transformation-getting-started-mcp.md) a configuração e um exemplo de fluxo de trabalho.