本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
数据转换功能
以下每个功能都记录了它的本质、工作原理、 C-CDA 和 CSV 源之间的区别以及何时使用。
转换配置文件和版本控制
转换配置文件是对源格式如何转换为 FHIR R4 的可重复使用的定义。它包含转换逻辑（的 Velocity 模板 C-CDA，CSV 的 YAML 映射配置），创建一次，即可在账户中的所有数据存储和转换任务中重复使用。将定义（配置文件）与执行（作业）分离意味着您编写和测试一次转换，然后将相同的已发布版本应用于任意数量的作业。
创建配置文件
您可以通过以下三种方式之一创建个人资料：
-
从初始配置文件或基本配置文件开始：从工作配置文件开始，而不是从空白配置文件开始。对于 C-CDA， AWS Starter Profile 是一个预先构建的 AWS-defined 配置文件，可以开箱即用地处理常见的 C-CDA 文档格式。对于 CSV，您在创建配置文件时在 Amazon S3 中提供示例文件，然后调用 AI 代理对其进行分析并生成 YAML 映射配置。
-
通过克隆：克隆任何现有的配置文件作为新配置文件的起点。
-
使用原始映射：直接提供 Velocity 模板 (C-CDA) 或 YAML 映射 (CSV)。这是通过 CI/CD 管道部署版本控制配置文件的路径（参见SDK 入门和 AWS CLI）。
重要
使用创建 CSV 配置文件会 SampleData 注册示例位置，但不运行 AI 代理。要生成 YAML 映射，必须 UpdateProfileWithAgent 在创建后调用。此时，代理会分析您的示例文件并生成基本配置文件。
版本生命周期
一个配置文件最多可以有一个草稿和最多 99 个已发布版本：
-
新的配置文件以草稿（版本 0）开始：一个可变的工作副本，你可以自由编辑。
-
发布草稿会创建不可变的编号版本（v1、v2 等，最高为 v99）。发布的版本永远不会改变。
-
转换作业始终针对最新发布的版本运行。由于草稿是独立的，因此您可以在生产作业继续针对上次发布的版本运行的同时继续进行编辑：正在进行的编辑永远不会影响正在进行的转换。
-
带有已发布版本和较新未发布编辑内容的配置文件处于未发布更改状态；在您再次发布之前，已发布版本将保持有效。
比较和回滚
由于每个已发布的版本都会被保留，因此您可以确切地看到转换逻辑在版本历史记录中的变化。回滚不会删除任何内容：它会从先前的快照创建新版本，因此保留了完整的历史记录和审计记录。
何时使用版本控制
在运行生产任务之前发布版本，以便将作业固定到经过审查的逻辑中。当更改产生意外输出时，使用回滚功能，然后进行比较以确认更改实际更改了什么。
数据转换 AI 代理
数据转换 AI 代理消除了创作和维护 FHIR 映射的手动工作。与其手动编写转换逻辑，不如描述所需的结果，然后代理生成或更新基础逻辑：Velocity 模板 C-CDA，CSV 的 YAML 映射配置。该代理嵌入在的配置文件编辑器中，也可以通过 UpdateProfileWithAgent API 和 MCP 工具使用，因此您可以通过 AWS 管理控制台、从代码或 MCP-compatible IDE 中使用它。 AWS 管理控制台
代理在做什么
数据转换 AI 代理执行以下任务：
-
根据您的数据生成转换逻辑。对于 CSV，代理会分析您在创建配置文件时提供的示例文件并生成基本配置文件：推断目标 FHIR 资源和字段，因此您可以从工作草稿而不是空白配置文件开始。因为 C-CDA，它会根据您的文档量身定制 AWS 初学者个人资料。
-
编辑自然语言中的转换逻辑。用通俗的语言描述变化，代理会更新基础模板或映射。例如：
-
“为药物资源添加映射。”
-
“从 “语言交流” 部分映射患者的首选语言。”
-
“将患者资源的默认州设置为华盛顿。”
-
“将 RACE_CD 列映射到 FHIR 扩展名。”
-
“跳过状态输入错误的记录。”
-
-
申请前进行解释和审查。代理将提议的变更作为受影响模板或映射的差异呈现供您查看，并且只有在您接受后才会应用该变更。已发布的配置文件中没有任何静默更改，代理仅对草稿版本进行更改。
-
反复精制。在多个回合中与代理一起调整映射，直到转换后的输出正确无误，使用同步转换 API 根据回合之间的样本数据预览结果。
C-CDA 工作流程（Velocity 模板）
代理编辑 Velocity 模板，这些模板定义了 C-CDA 各部分如何映射到 FHIR 资源。要求它添加资源映射、更改章节的解释方式、设置默认值或处理文档变体，它会更新模板并返回差异。在发布之前，您可以预览样本 C-CDA 文档的转换。
CSV 工作流程（YAML 映射）
当您使用示例文件创建 CSV 配置文件然后调用代理时，它会分析文件中的标题、样本值和数据模式，然后提出一个 YAML 映射配置，其中包括：
-
列到 FHIR 字段映射，
-
日期格式检测并重新格式化为 FHIR 格式， date/time
-
值转换（例如，M → 男性，住院 → IMP），
-
primary/foreign-表之间的密钥关系，
-
将子表行折叠成父资源上的 FHIR 数组的聚合规则，
-
代理做出的任何假设以及对您的数据的任何疑问。
您可以接受、拒绝或完善每项提议的映射，并可以要求代理进行进一步调整。代理根据您的文件样本而不是完整的数据集推断出映射，因此请提供代表您的数据的样本，并在大规模转换之前查看提议的映射。
代理接受的输入
您可以使用自然语言输入与代理通信。一些组合包括：
-
指令，
-
示例源数据（C-CDA 部分或 CSV 架构），
-
架构文档，
-
先前转换的 FHIR 验证错误。
手动编辑
您无需使用该代理。您可以随时直接编辑 Velocity 模板和 YAML 映射，并在同一配置文件上混合使用手动编辑和代理人创作的更改。
同步（实时）转换和预览
同步转换转换单个输入并立即返回 FHIR 结果，而不是通过 Amazon S3 运行异步任务。它的存在有两个目的：在创作配置文件时对其进行测试，以及在 request/response 流程中运行小型的交互式转换。
工作原理
同步变换按如下方式处理单个输入：
-
您根据配置文件提交一个输入（一个 C-CDA 文档或一组 CSV 文件），并在响应中以 FHIR 包的形式接收转换后的 FHIR 资源。
-
该操作只能通过 REST API 获得：它不作为 AWS CLI 或 SDK 命令公开。请参阅访问数据转换代理。
-
您可以通过设置为 true DriftDetectionEnabled 来启用同步调用的偏差检测，以便在响应中查看配置文件尚未捕获哪些源元素：在迭代映射时很有用。
大小限制
同步转换接受最大为 1 MB 的 C-CDA 输入，每个请求接受不超过 1 MB 的组合 CSV 输入。对于较大的数据集，使用批量转换作业。
在... 中预览 AWS 管理控制台
在中创作配置文件时 AWS 管理控制台，同步变换为实时预览提供动力：您在一侧看到源文件，在另一侧看到转换后的 FHIR 输出，随着您优化映射，预览会更新。在发布之前，使用它来确认输出正确。
何时使用同步与批量同步
使用同步转换根据代表性文档验证配置文件，并针对延迟敏感的按请求进行转换，例如在文档到达时进行转换的实时提要。使用批量转换作业（如下所示）来处理大型数据集并直接提取到 HealthLake 数据存储中。
批量（异步）转换任务
批量转换任务使用已发布的配置文件从 Amazon S3 转换大型数据集，在您监控进度的同时异步运行。这是迁移和将数据加载到数据 HealthLake 存储库的生产路径。请参阅此页面了解 I AM 权限设置。
工作原理
批量转换任务的工作原理如下：
-
将任务指向源文件的 Amazon S3 前缀，选择已发布的配置文件，然后选择输出目的地。该作业扫描输入，转换每个文件 (C-CDA) 或行集 (CSV)，然后写入结果。
-
无需预置基础架构：工作量会自动扩展。
输出模式
批量作业支持以下输出模式：
-
独立：将转换后的 FHIR 写入亚马逊 S3 位置。使用 StartDataTransformationJob API。
-
合成（转换和提取）：转换源文件并将生成的 FHIR 资源直接提取到 HealthLake 数据存储库中，因此可以立即查询数据。使用带有 ProfileId InputFormat、和可选 DriftDetectionEnabled参数的 StartFHIRImportJob API。数据存储必须处于活动状态。有关完整示例，请参见步骤 7：转换并提取到 HealthLake 数据存储中。
优雅的故障处理
格式错误的输入会被跳过并记录下来，而不是批处理失败，因此一个错误的文件永远不会停止大型作业。失败的输入以 JSON 错误文件形式写入，其中包含输入文件路径和错误消息，因此您可以查看和重新处理它们。
输出布局
该服务使用任务 ID 在您的输出 Amazon S3 URI 下创建一个任务范围文件夹。在那个文件夹里：
-
converted/: FHIR NDJSON 输出文件（每个输入文件一个，例如-record.ndjson）。 converted/patient
-
错误/：输入失败的错误详情（带有 InputFile 和 ErrorMessage 字段的 JSON 文件，例如）。 ERROR/bad-file.json
-
Manifest.json：包含聚合指标（文件已扫描、已转换、失败、资源生成）的任务摘要。
-
作业LevelDriftResult.json：如果启用了偏差检测，则任务的聚合偏差报告。
-
driftDetectionPerFileResults/：对于启用了偏移检测的 C-CDA 作业，每个文件的偏差报告（例如， driftDetectionPerFileResults/patient-record_driftMetrics.json），因此您可以检查单个源文件的覆盖范围，而不仅仅是任务级别的聚合。
监控
通过 AWS 管理控制台 作业详细信息页面或 DescribeDataTransformationJob API 跟踪正在运行的作业：状态、已处理的文件（CSV 行数）、生成的资源和失败。亚马逊也提供任务指标和日志 CloudWatch。
验证
Data Transformation Agent 会在转换生命周期的多个阶段进行验证，因此在问题变成转换失败或输出不合规之前，就会发现问题。
-
源代码验证：检查 C-CDA 输入的格式是否正确且符合 C-CDA 规范。错误包括位置详细信息和补救指南，因此您可以在运行大型任务之前修复源问题。该 ValidateSource 操作可通过 REST API 进行预先筛选输入。
-
模板/映射验证：独立于任何数据验证配置文件的 Velocity 模板 (C-CDA) 或 YAML 映射 (CSV)，因此您可以在发布或运行作业之前确认转换逻辑的格式正确。
-
输出 FHIR 验证：检查生成的资源是否符合 FHIR R4，因此下游 FHIR API 和数据存储区接受输出。
这些因素共同意味着任务由于可避免的原因而失败的频率降低：源验证捕获错误的输入，映射验证捕获错误的逻辑，输出验证确认结果符合标准。
OID-to-URI 映射
C-CDA 文档使用 OID（对象标识符）识别代码系统：传统数字标识符，例如 2.16.840.1.113883.6.1 (LOINC)。FHIR期望使用现代系统的URI，例如. http://loinc.org 如果 OID 未映射通过，则生成的系统值不可互操作，下游 FHIR 工具无法解析代码。转换期间，数据转换代理在它们之间映射。
-
Pre-built 映射：自动应用常见医疗保健 OID（例如 LOINC、SNOMED CT、 ICD-10、 RxNorm）的映射，无需配置。
-
自定义映射：为特定于源代码系统的 OID-to-URI 映射添加自己的映射，以便专有或本地系统可以正确解析。
这适用于 C-CDA 源代码，其中 OID 是识别代码系统的本机方式。
出处
受监管的医疗工作流程需要回答 “这些数据来自哪里，它是如何产生的？” 适用于任何资源。在作业上启用来源后，数据转换代理会为每次转换生成一个 FHIR Provenance 资源，从而为每个输出资源提供完整的、可查询的源代码谱系。
来源链
来源 → DocumentReference → 源文件。来源资源引用 a DocumentReference，它记录了源文件的 Amazon S3 URI 和 SHA-1 校验和。校验和允许您证明输出源自特定的、未更改的源文件。如果需要该信息，还会提供将 AWS HealthLake 数据转换表示为实体的设备资源。
Record-level 定位器
来源不仅解析为源文件，还解析为其中的确切位置，定位器因源格式而异：
-
C-CDA: 一个指向源元素的 XPath，指向该资源派生的源元素。
-
CSV：源记录的表名、主键和行号。
捕获的字段
每个 Provenance 资源都会记录源文件 URI 和校验和、用于转换的配置文件版本、时间戳和记录级定位器。
一致性和用途
来源资源符合美国核心来源概况，因此它们可以与美国工具互操作。 Core-aware 当您需要可审计性以保证合规性时，或者需要将可疑的输出资源追溯到产生该资源的确切来源元素时，请启用来源。默认情况下，来源处于启用状态；设置为 false 则 ProvenanceEnabled 将其禁用。
偏差检测
在静默删除配置文件尚未映射的源数据的同时，转换可以成功。偏移检测表面存在间隙。它是一份报告：启用后，它会将来源包含的内容与配置文件实际生成的内容进行比较，并记录留下的内容。
报告包含的内容
偏差报告包含以下信息：
-
转换的总体覆盖率。
-
未映射源部分和元素的排名列表，因此您可以对影响最大的差距进行优先排序。
-
任何未产生的预期资源。
-
完全可追溯到源文件和元素位置（文件名和 OID C-CDA，CSV 为行）。
如何使用漂移检测
漂移检测在两种转换模式下都可用，因此无论是迭代单个文件还是验证完整数据集，都可以使用它：
-
同步（实时）：在 TransformData 请求对单个文件运行偏移检测并在 API 响应中返回结果时设置 DriftDetectionEnabled 为 true。这是在撰写个人资料时检查覆盖率的最快方法：转换一份代表性文档，查看个人资料遗漏的确切内容，完善映射，然后重试。
-
批量（异步）：在转换作业上启用偏差检测，以测量整个数据集的覆盖范围。该报告LevelDriftResult.json 是在任务的 Amazon S3 输出位置作为任务编写的。对于 C-CDA 作业，每个文件的偏差报告也写在 drif DetectionPerFileResults t/ 文件夹下，因此您可以查明单个源文件中的覆盖差距。
MCP 访问权限
模型上下文协议 (MCP) 将数据转换代理作为可调用工具公开给 IDE-based AI 代理，因此开发人员可以在 IDE 中编写配置文件、运行转换并调查助手的故障：无需切换到. AWS 管理控制台
-
配置文件和任务管理 API：所有数据转换代理配置文件和任务管理 API 均作为 MCP 工具提供，因此您可以从任何 MCP-compatible 客户端创建、编辑、发布和运行作业。
-
任何 MCP 客户端：可与 MCP-compatible IDE 和助手一起使用，包括 Kiro 和 Cursor。
-
持久会话：支持多回合会话，因此调试或创作对话可以保存上下文。
注意
同步转换操作 (TransformData) 和源验证 (ValidateSource) 现在 REST-only 和可能不作为 MCP 工具出现。您的代理可以代表您构造和执行 REST 调用：有关请求格式，请参阅步骤 3：使用同步转换进行测试。
由于 MCP 与用于配置文件和作业操作的 AWS CLI 和 SDK 共享相同的 API 界面，因此这些工作流程在 IDE 中工作和处理代码之间没有能力差距。 AWS 管理控制台MCP 入门有关设置和示例工作流程，请参见。
