View a markdown version of this page

데이터 변환 기능 - AWS HealthLake
프로필 및 버전 관리AI 에이전트동기화 변환대량 작업검증OID-to-URI 매핑증명드리프트 감지MCP 액세스

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

데이터 변환 기능

아래 각 기능은 정의, 작동 방식, C-CDA와 CSV 소스 간의 차이점, 사용 시기와 함께 문서화됩니다.

변환 프로파일 및 버전 관리

변환 프로파일은 소스 형식이 FHIR R4로 변환되는 방법에 대한 재사용 가능한 정의입니다. 변환 로직(C-CDA용 속도 템플릿, CSV용 YAML 매핑 구성)을 보유하며 계정의 모든 데이터 스토어 및 변환 작업에서 한 번 생성되고 재사용됩니다. 실행(작업)에서 정의(프로파일)를 분리하면 변환을 한 번 작성 및 테스트한 다음 게시된 동일한 버전을 원하는 수의 작업에 적용할 수 있습니다.

프로필 생성

다음 세 가지 방법 중 하나로 프로필을 생성합니다.

  • 스타터 또는 기본 프로필에서: 빈 프로필이 아닌 작업 프로필에서 시작합니다. C-CDA의 경우 AWS Starter Profile은 일반적인 C-CDA 문서 형식을 즉시 처리하는 사전 구축된 AWS 정의 프로파일입니다. CSV의 경우 프로필을 생성할 때 Amazon S3에 샘플 파일을 제공한 다음 AI 에이전트를 호출하여 분석하고 YAML 매핑 구성을 생성합니다.

  • 복제: 기존 프로파일을 새 프로파일의 시작점으로 복제합니다.

  • 원시 매핑에서: 속도 템플릿(C-CDA) 또는 YAML 매핑(CSV)을 직접 제공합니다. 이는 CI/CD 파이프라인을 통해 버전 제어 프로파일을 배포하는 경로입니다( 참조SDK 및 시작하기 AWS CLI).

중요

SampleData로 CSV 프로파일을 생성하면 샘플 위치가 등록되지만 AI 에이전트는 실행되지 않습니다. YAML 매핑을 생성하려면 생성 후 UpdateProfileWithAgent를 호출해야 합니다. 에이전트는 해당 시점에서 샘플 파일을 분석하고 기본 프로파일을 생성합니다.

버전 수명 주기

프로필에는 최대 1개의 초안과 최대 99개의 게시된 버전이 있을 수 있습니다.

  • 새 프로필은 초안(버전 0)으로 시작됩니다. 자유롭게 편집할 수 있는 변경 가능한 작업 복사본입니다.

  • 초안을 게시하면 번호가 매겨진 변경 불가능한 버전(v1, v2 등, v99까지)이 생성됩니다. 게시된 버전은 변경되지 않습니다.

  • 변환 작업은 항상 게시된 최신 버전에 대해 실행됩니다. 초안은 별개이므로 프로덕션 작업이 마지막으로 게시된 버전에 대해 계속 실행되는 동안 편집을 계속할 수 있습니다. 진행 중인 편집은 실행 중인 변환에 영향을 주지 않습니다.

  • 게시된 버전과 최신 미게시 편집본이 있는 프로필은 게시되지 않은 변경 상태로, 게시된 버전은 다시 게시할 때까지 활성 상태로 유지됩니다.

비교 및 롤백

게시된 모든 버전이 유지되므로 버전 기록에서 변환 로직이 어떻게 변경되었는지 정확히 확인할 수 있습니다. 롤백은 어떤 것도 삭제하지 않습니다. 이전 스냅샷에서 새 버전을 생성하므로 전체 기록 및 감사 추적이 보존됩니다.

버전 관리를 사용해야 하는 경우

프로덕션 작업을 실행하기 전에 버전을 게시하여 검토된 로직에 작업이 고정되도록 합니다. 변경으로 인해 예기치 않은 출력이 생성될 때 롤백을 사용하고를 비교하여 실제로 변경된 변경 사항을 확인합니다.

데이터 변환 AI 에이전트

데이터 변환 AI 에이전트는 FHIR 매핑을 작성하고 유지 관리하는 수동 작업을 제거합니다. 변환 로직을 직접 작성하는 대신 원하는 결과를 설명하면 에이전트가 기본 로직인 CSV용 YAML 매핑 구성인 C-CDA용 Velocity 템플릿을 생성하거나 업데이트합니다. 에이전트는의 프로파일 편집기에 내장되어 AWS Management Console 있으며 UpdateProfileWithAgent API를 통해 MCP 도구로도 사용할 수 있으므로 , AWS Management Console코드 또는 MCP 호환 IDE에서 사용할 수 있습니다.

에이전트가 수행하는 작업

  • 데이터에서 변환 로직을 생성합니다. CSV의 경우 에이전트는 프로필 생성 시 제공한 샘플 파일을 분석하고 대상 FHIR 리소스 및 필드를 추론하는 기본 프로필을 생성하므로 빈 프로필이 아닌 규격 초안부터 시작합니다. C-CDA의 AWS 경우 스타터 프로파일을 문서에 맞게 조정합니다.

  • 자연어에서 변환 로직을 편집합니다. 일반 언어의 변경 사항을 설명하고 에이전트가 기본 템플릿 또는 매핑을 업데이트합니다. 예제:

    • “투약 리소스에 대한 매핑을 추가합니다.”

    • “ languageCommunication 섹션에서 환자의 기본 언어를 매핑합니다.”

    • “기본 상태를 환자 리소스용 워싱턴으로 설정합니다.”

    • “RDS_CD 열을 FHIR 확장에 매핑합니다.”

    • “상태가 entered-in-error 레코드를 건너뜁니다.”

  • 신청하기 전에 설명하고 검토합니다. 에이전트는 제안된 변경 사항을 사용자가 검토할 수 있도록 영향을 받는 템플릿 또는 매핑의 차이로 제시하고 수락한 후에만 적용합니다. 게시된 프로필에서 아무것도 변경되지 않으며 에이전트는 초안 버전만 변경합니다.

  • 반복적으로 구체화합니다. 변환된 출력이 올바를 때까지 에이전트와 여러 차례 협력하여 매핑을 조정하고 동기화 변환 API를 사용하여 턴 사이의 샘플 데이터에 대한 결과를 미리 봅니다.

C-CDA 워크플로(속도 템플릿)

에이전트는 C-CDA 섹션이 FHIR 리소스에 매핑되는 방식을 정의하는 Velocity 템플릿을 편집합니다. 리소스 매핑을 추가하거나, 섹션이 해석되는 방식을 변경하거나, 기본값을 설정하거나, 문서 변형을 처리하도록 요청하면 템플릿이 업데이트되고 diff가 반환됩니다. 게시하기 전에 샘플 C-CDA 문서에 대한 변환을 미리 봅니다.

CSV 워크플로(YAML 매핑)

샘플 파일로 CSV 프로파일을 생성한 다음 에이전트를 호출하면 파일에서 헤더, 샘플 값 및 데이터 패턴을 분석한 다음 다음을 포함하는 YAML 매핑 구성을 제안합니다.

  • column-to-FHIR 필드 매핑,

  • 날짜 형식 감지 및 FHIR 날짜/시간 형식으로 재구성,

  • 값 변환(예: M → 남성, INPATIENT → IMP),

  • 테이블 간 기본/외래 키 관계,

  • 하위 테이블 행을 상위 리소스의 FHIR 배열로 접는 집계 규칙

  • 에이전트가 한 모든 가정과 데이터에 대한 모든 질문.

제안된 각 매핑을 수락, 거부 또는 구체화하고 에이전트에게 추가 조정을 요청할 수 있습니다. 에이전트는 전체 데이터 세트가 아닌 파일 샘플에서 매핑을 유추하므로 데이터를 나타내는 샘플을 제공하고 대규모로 변환하기 전에 제안된 매핑을 검토합니다.

에이전트가 수락하는 입력

자연어 입력으로 에이전트와 통신할 수 있습니다. 일부 조합은 다음과 같습니다.

  • 지침,

  • 샘플 소스 데이터(C-CDA 섹션 또는 CSV 스키마),

  • 스키마 설명서,

  • 이전 변환의 FHIR 검증 오류입니다.

수동 편집

에이전트를 사용할 필요는 없습니다. 언제든지 Velocity 템플릿 및 YAML 매핑을 직접 편집하고 동일한 프로필에서 에이전트가 작성한 변경 사항과 수동 편집을 혼합할 수 있습니다.

동기식(실시간) 변환 및 미리 보기

동기 변환은 Amazon S3를 통해 비동기 작업을 실행하는 대신 단일 입력을 변환하고 FHIR 결과를 즉시 반환합니다. 프로필을 작성하는 동안 프로필을 테스트하고 요청/응답 흐름에서 작은 대화형 변환을 실행하는 두 가지 목적으로 존재합니다.

작동 방식

  • 프로필에 대해 하나의 입력(C-CDA 문서 또는 CSV 파일 세트)을 제출하고 응답에서 변환된 FHIR 리소스를 FHIR 번들로 수신합니다.

  • 작업은 REST API를 통해서만 사용할 수 있으며 AWS CLI 또는 SDK 명령으로 노출되지 않습니다. 데이터 변환 에이전트 액세스을(를) 참조하세요.

  • 응답에서 프로파일이 아직 캡처하지 않는 소스 요소를 보려면 DriftDetectionEnabled를 true로 설정하여 동기화 호출에서 드리프트 감지를 활성화할 수 있습니다. 매핑을 반복하는 동안 유용합니다.

크기 제한

동기 변환은 요청당 최대 1MB의 C-CDA 입력과 최대 1MB의 결합된 CSV 입력을 허용합니다. 대규모 데이터 세트의 경우 대량 변환 작업을 사용합니다.

의 미리 보기 AWS Management Console

에서 프로파일을 작성할 때 AWS Management Console동기 변환은 라이브 미리 보기를 활성화합니다. 한 쪽에는 소스가 표시되고 다른 쪽에는 변환된 FHIR 출력이 표시되며 매핑을 구체화할 때 미리 보기가 업데이트됩니다. 게시하기 전에 이를 사용하여 출력이 올바른지 확인합니다.

동기화와 대량 동기화를 사용해야 하는 경우

동기 변환을 사용하여 대표 문서와 비교하여 프로필을 검증하고 문서가 도착할 때 문서를 변환하는 라이브 피드와 같이 지연 시간에 민감한 요청별 변환을 검증합니다. 대규모 데이터 세트 및 HealthLake 데이터 스토어에 직접 수집하려면 대량 변환 작업(아래)을 사용합니다.

대량(비동기) 변환 작업

대량 변환 작업은 게시된 프로파일을 사용하여 Amazon S3에서 대규모 데이터 세트를 변환하며, 진행 상황을 모니터링하는 동안 비동기적으로 실행됩니다. 마이그레이션 및 HealthLake 데이터 스토어로 데이터를 로드하기 위한 프로덕션 경로입니다. IAM 권한 설정은 이 페이지를 참조하세요.

작동 방식

  • 소스 파일의 Amazon S3 접두사를 가리키고 게시된 프로필을 선택한 다음 출력 대상을 선택합니다. 작업은 입력을 스캔하고, 각 파일(C-CDA) 또는 행 세트(CSV)를 변환하고, 결과를 작성합니다.

  • 프로비저닝할 인프라는 없습니다. 작업은 자동으로 조정됩니다.

출력 모드

  • 독립 실행형: Amazon S3 위치에 변환된 FHIR을 작성합니다. StartDataTransformationJob API를 사용합니다.

  • 복합(변환 및 수집): 소스 파일을 변환하고 결과 FHIR 리소스를 단일 단계로 HealthLake 데이터 스토어로 직접 수집하므로 데이터를 즉시 쿼리할 수 있습니다. ProfileId, InputFormat 및 선택적으로 DriftDetectionEnabled 파라미터와 함께 StartFHIRImportJob API를 사용합니다. 데이터 스토어는 ACTIVE 상태여야 합니다. 전체 예제는 7단계: HealthLake 데이터 스토어로 변환 및 수집을 참조하세요.

정상적인 장애 처리

잘못된 형식의 입력은 배치에 실패하지 않고 건너뛰고 로깅되므로 하나의 잘못된 파일이 큰 작업을 중지하지 않습니다. 실패한 입력은 입력 파일 경로 및 오류 메시지와 함께 JSON 오류 파일로 기록되므로 검토하고 다시 처리할 수 있습니다.

출력 레이아웃

서비스는 작업 ID를 사용하여 출력 Amazon S3 URI 아래에 작업 범위 폴더를 생성합니다. 해당 폴더 내부:

  • converted/: FHIR NDJSON 출력 파일(입력 파일당 하나, 예: converted/patient-record.ndjson).

  • ERROR/: 실패한 입력에 대한 오류 세부 정보(inputFile 및 errorMessage 필드가 있는 JSON 파일, 예: ERROR/bad-file.json).

  • Manifest.json: 집계 지표(스캔, 변환, 실패, 생성된 리소스)가 포함된 작업 요약입니다.

  • jobLevelDriftResult.json: 드리프트 감지가 활성화된 경우 작업에 대한 집계 드리프트 보고서입니다.

  • driftDetectionPerFileResults/: 드리프트 감지가 활성화된 C-CDA 작업의 경우 파일별 드리프트 보고서(예: driftDetectionPerFileResults/patient-record_driftMetrics.json)이므로 작업 수준 집계만 아닌 개별 소스 파일의 적용 범위를 검사할 수 있습니다.

모니터링

작업 세부 정보 페이지 또는 DescribeDataTransformationJob API: 상태, 처리된 파일(CSV 행), 생성된 리소스 및 실패를 통해 실행 중인 AWS Management Console 작업을 추적합니다. 작업 지표 및 로그는 Amazon CloudWatch에서도 사용할 수 있습니다.

검증

Data Transformation Agent는 변환 수명 주기의 여러 지점에서 검증되므로 변환 실패 또는 규정 미준수 출력이 되기 전에 문제가 발견됩니다.

  • 소스 검증: C-CDA 입력이 올바른 형식이고 C-CDA 사양을 준수하는지 확인합니다. 오류에는 위치 세부 정보 및 수정 지침이 포함되므로 대규모 작업을 실행하기 전에 소스 문제를 해결할 수 있습니다. ValidateSource 작업은 REST API를 통해 입력을 미리 검사할 수 있습니다.

  • 템플릿/매핑 검증:는 모든 데이터와 독립적으로 프로필의 속도 템플릿(C-CDA) 또는 YAML 매핑(CSV)을 검증하므로 작업을 게시하거나 실행하기 전에 변환 로직이 잘 구성되어 있는지 확인할 수 있습니다.

  • 출력 FHIR 검증: 생성된 리소스가 FHIR R4를 준수하는지 확인하여 다운스트림 FHIR APIs 및 데이터 스토어가 출력을 수락합니다.

이렇게 하면 소스 검증이 잘못된 입력을 포착하고, 매핑 검증이 잘못된 로직을 포착하고, 출력 검증이 결과가 표준을 준수하는지 확인하는 등 피할 수 있는 이유로 작업이 실패하는 빈도가 줄어듭니다.

OID-to-URI 매핑

C-CDA 문서는 OIDs(객체 식별자): 2.16.840.1.113883.6.1 (LOINC)와 같은 레거시 숫자 식별자를 사용하여 코드 시스템을 식별합니다. FHIR에는와 같은 최신 시스템 URIs 필요합니다http://loinc.org. OIDs 매핑되지 않은 상태로 전달되는 경우 결과 시스템 값은 상호 운용할 수 없으며 다운스트림 FHIR 도구로는 코드를 확인할 수 없습니다. 데이터 변환 에이전트는 변환 중에 이들 간에 매핑됩니다.

  • 사전 구축된 매핑: 일반적인 의료 OIDs(예: LOINC, SNOMED CT, ICD-10, RxNorm)에 대한 매핑은 구성 없이 자동으로 적용됩니다.

  • 사용자 지정 매핑: 소스와 관련된 코드 시스템에 대한 자체 OID-to-URI 매핑을 추가하여 독점 또는 로컬 시스템이 올바르게 해결되도록 합니다.

이는 OIDs 코드 시스템을 식별하는 기본 방식인 C-CDA 소스에 적용됩니다.

증명

규제 대상 의료 워크플로는 “이 데이터는 어디에서 왔으며 어떻게 생성되었나요?”라고 답해야 합니다. 모든 리소스에 대한 입니다. 작업에서 출처가 활성화되면 Data Transformation Agent는 모든 변환에 대한 FHIR 출처 리소스를 생성하여 각 출력 리소스에 완전하고 쿼리 가능한 계보를 소스에 다시 제공합니다.

산지 체인

Provenance → DocumentReference → 소스 파일. Provenance 리소스는 소스 파일의 Amazon S3 URI와 SHA-1 체크섬을 기록하는 DocumentReference를 참조합니다. 체크섬을 사용하면 변경되지 않은 특정 소스 파일에서 출력이 파생되었음을 증명할 수 있습니다. 해당 정보가 필요한 경우 AWS HealthLake 데이터 변환을 엔터티로 나타내는 디바이스 리소스도 제공됩니다.

레코드 수준 로케이터

Provenance는 소스 파일뿐만 아니라 소스 파일 내의 정확한 위치로 확인되며 로케이터는 소스 형식에 따라 다릅니다.

  • C-CDA: 리소스가 파생된 소스 요소를 가리키는 XPath입니다.

  • CSV: 소스 레코드의 테이블 이름, 기본 키 및 행 번호입니다.

캡처된 필드

각 Provenance 리소스는 소스 파일 URI 및 체크섬, 변환에 사용되는 프로파일 버전, 타임스탬프 및 레코드 수준 로케이터를 기록합니다.

적합성 및 사용

Provenance 리소스는 US Core Provenance 프로파일을 준수하므로 US Core 인식 도구와 상호 작용합니다. 규정 준수를 위해 감사가 필요하거나 의심스러운 출력 리소스를 생성한 정확한 소스 요소로 다시 추적해야 하는 경우 출처를 활성화합니다. Provenance는 기본적으로 활성화되어 있습니다. ProvenanceEnabled를 false로 설정하여 비활성화합니다.

드리프트 감지

프로필이 아직 매핑되지 않은 소스 데이터를 자동으로 삭제하는 동안 변환이 성공할 수 있습니다. 갭이 있는 드리프트 감지 표면. 보고서입니다. 활성화하면 소스에 포함된 내용을 프로파일이 실제로 생성한 내용과 비교하고 남은 내용을 기록합니다.

보고서에 포함된 내용

  • 변환에 대한 전체 적용률입니다.

  • 매핑되지 않은 소스 섹션 및 요소의 순위 목록으로, 가장 큰 영향 격차의 우선순위를 지정할 수 있습니다.

  • 생성되지 않은 예상 리소스.

  • 소스 파일 및 요소 위치(C-CDA의 경우 파일 이름 및 OID, CSV의 경우 행)까지 완전히 추적할 수 있습니다.

드리프트 감지를 사용하는 방법

드리프트 감지는 두 변환 모드에서 모두 사용할 수 있으므로 단일 파일에서 반복하든 전체 데이터 세트를 검증하든 상관없이 사용할 수 있습니다.

  • 동기화(실시간): 단일 파일에서 드리프트 감지를 실행하고 API 응답에서 결과를 다시 가져오려면 TransformData 요청에서 DriftDetectionEnabled를 true로 설정합니다. 프로필을 작성하는 동안 적용 범위를 확인하는 가장 빠른 방법입니다. 대표 문서 하나를 변환하고, 프로필이 놓친 내용을 정확히 확인하고, 매핑을 구체화하고, 다시 시도하세요.

  • 대량(비동기): 변환 작업에서 드리프트 감지를 활성화하여 전체 데이터 세트의 적용 범위를 측정합니다. 보고서는 작업의 Amazon S3 출력 위치에 jobLevelDriftResult.json으로 기록됩니다. C-CDA 작업의 경우 파일별 드리프트 보고서도 driftDetectionPerFileResults/ 폴더 아래에 기록되므로 개별 소스 파일에서 적용 범위 격차를 정확히 찾아낼 수 있습니다.

MCP 액세스

모델 컨텍스트 프로토콜(MCP)은 데이터 변환 에이전트를 IDE 기반 AI 에이전트에 호출 가능한 도구로 노출하므로 개발자는 로 전환하지 않고도 IDE에서 프로필을 작성하고, 변환을 실행하고, 어시스턴트의 실패를 조사할 수 있습니다 AWS Management Console.

  • 프로파일 및 작업 관리 APIs: 모든 Data Transformation Agent 프로파일 및 작업 관리 APIs MCP 도구로 사용할 수 있으므로 모든 MCP 호환 클라이언트에서 작업을 생성, 편집, 게시 및 실행할 수 있습니다.

  • 모든 MCP 클라이언트:는 Kiro 및 Cursor를 포함한 MCP 호환 IDEs 및 어시스턴트와 함께 작동합니다.

  • 내구성 있는 세션:는 멀티턴 세션을 지원하므로 디버깅 또는 작성 대화에는 컨텍스트가 포함됩니다.

참고

동기화 변환 작업(TransformData) 및 소스 검증(ValidateSource)은 REST 전용이며 MCP 도구로 표시되지 않을 수 있습니다. 에이전트는 사용자를 대신하여 REST 호출을 구성하고 실행할 수 있습니다. 요청 형식에 대한 3단계: 동기화 변환으로 테스트를 참조하세요.

MCP는 프로파일 및 작업 작업을 위해 AWS CLI 및 SDKs와 동일한 API 표면을 공유하므로 IDE에서 작업하는 것과 코드 또는를 통해 작업하는 간에 이러한 워크플로에 대한 기능 격차가 없습니다 AWS Management Console. 설정 및 워크플로 예제는 MCP 시작하기 단원을 참조하십시오.