本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
数据转换功能
以下每项功能都记录了它的本质、工作原理、与 CSV 源之间的 C-CDA 区别以及何时使用。
转换配置文件和版本控制
转换配置文件是源格式如何转换为 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 映射配置。代理嵌入在的配置文件编辑器中 AWS 管理控制台 ，也可以通过 UpdateProfileWithAgent API 和 MCP 工具使用，因此您可以从 AWS 管理控制台、代码或 MCP-compatible IDE 中使用代理。
代理做什么
-
根据您的数据生成转换逻辑。对于 CSV，代理会分析您在创建配置文件时提供的示例文件并生成基本配置文件：推断目标 FHIR 资源和字段，因此您可以从工作草稿而不是空白配置文件开始。因为 C-CDA，它会根据您的文档量身定制 AWS 入门配置文件。
-
编辑自然语言中的转换逻辑。用通俗易懂的语言描述更改，代理会更新底层模板或映射。例如：
-
“为药物资源添加映射。”
-
“从 “语言/交流” 部分映射患者的首选语言。”
-
“将患者资源的默认州设置为华盛顿。”
-
“将 RACE_CD 列映射到 FHIR 扩展名。”
-
“跳过状态输入错误的记录。”
-
-
申请前进行解释和审查。代理将建议的变更作为受影响模板或映射的差异呈现给您供您查看，并且只有在您接受后才会应用该变更。已发布的配置文件上没有任何静默更改，代理只对草稿版本进行更改。
-
反复细化。在多个回合中与代理一起调整映射，直到转换后的输出正确为止，使用同步转换 API 在回合之间根据样本数据预览结果。
C-CDA 工作流程（速度模板）
代理编辑 Velocity 模板，这些模板定义了 C-CDA 截面如何映射到 FHIR 资源。要求它添加资源映射、更改章节的解释方式、设置默认值或处理文档变体，然后它会更新模板并返回差异。在发布之前，您可以根据示例 C-CDA 文档预览转换。
CSV 工作流程（YAML 映射）
当您创建包含示例文件的 CSV 配置文件然后调用代理时，它会分析文件中的标题、样本值和数据模式，然后提出一个 YAML 映射配置，其中包括：
-
列到 fhir 的字段映射，
-
检测日期格式并重新格式化为 FHIR 格式， date/time
-
值转换（例如，M → 男性，住院患者 → IMP），
-
primary/foreign表之间的-key 关系，
-
将子表行折叠成父资源上的 FHIR 数组的聚合规则，
-
代理做出的任何假设以及对您的数据的任何疑问。
您接受、拒绝或完善每个建议的映射，并可以要求代理进行进一步的调整。代理会根据您的文件样本而不是完整数据集推断映射，因此请提供代表您的数据的样本并查看建议的映射，然后再进行大规模转换。
代理接受的输入
您可以使用自然语言输入与代理沟通。一些组合包括：
-
指令，
-
示例源数据（C-CDA 部分或 CSV 架构），
-
架构文档，
-
之前转换时出现的 FHIR 验证错误。
手动编辑
您无需使用代理。您可以随时直接编辑 Velocity 模板和 YAML 映射，也可以在同一个配置文件上将手动编辑与代理编写的更改混合在一起。
同步（实时）变换和预览
同步转换转换单个输入并立即返回 FHIR 结果，而不是通过 Amazon S3 运行异步作业。它的存在有两个目的：在创作配置文件时对其进行测试，以及在 request/response 流程中运行小型的交互式转换。
工作原理
-
您针对个人资料提交一个输入（一个 C-CDA 文档或一组 CSV 文件），然后在响应中以 FHIR 捆绑包的形式接收转换后的 FHIR 资源。
-
该操作仅可通过 REST API 使用：它不作为 AWS CLI 或 SDK 命令公开。请参阅访问数据转换代理。
-
您可以通过将配置文件设置为 true DriftDetectionEnabled 来在响应中查看配置文件尚未捕获哪些源元素，从而在同步调用上启用偏移检测：在迭代映射时很有用。
大小限制
同步转换每个请求最多可接受 C-CDA 1 MB 的输入和最大 1 MB 的 CSV 组合输入。对于较大的数据集，请使用批量转换作业。
在中预览 AWS 管理控制台
在中创作配置文件时 AWS 管理控制台，同步变换会为实时预览提供动力：你可以在一侧看到源，另一侧看到转换后的 FHIR 输出，当你调整映射时，预览会更新。在发布之前，使用它来确认输出是否正确。
何时使用同步与批量同步
使用同步转换可根据代表性文档验证配置文件，以及对延迟敏感的按请求进行转换，例如在文档到达时对其进行转换的实时馈送。使用批量转换作业（见下文）处理大型数据集并直接摄取到数据存储中。 HealthLake
批量（异步）转换作业
批量转换任务使用已发布的配置文件从 Amazon S3 转换大型数据集，在您监控进度的同时异步运行。这是迁移和将数据加载到数据 HealthLake 存储的生产路径。请参阅此页面，了解 IAM 权限设置。
工作原理
-
将任务指向源文件的 Amazon S3 前缀，选择已发布的配置文件，然后选择输出目标。该作业扫描输入，转换每个文件 (C-CDA) 或行集 (CSV)，然后写入结果。
-
无需配置基础设施：任务会自动扩展。
输出模式
-
独立版：将转换后的 FHIR 写入 Amazon S3 位置。使用 StartDataTransformationJob API。
-
复合（转换和提取）：只需一个步骤即可转换源文件并将生成的 FHIR 资源直接摄取到 HealthLake 数据存储中，因此数据可以立即查询。使用带有 ProfileId InputFormat、和可选 DriftDetectionEnabled参数的 StartFHIRImportJob API。数据存储必须处于活动状态。有关完整示例，请参阅步骤 7：转换并提取到 HealthLake 数据存储库。
优雅的故障处理
格式错误的输入会被跳过并记录下来，而不是批处理失败，因此单个错误的文件永远不会停止大型作业。失败的输入将写成带有输入文件路径和错误消息的 JSON 错误文件，因此您可以查看和重新处理它们。
输出布局
该服务使用任务 ID 在您的输出 Amazon S3 URI 下创建一个任务范围的文件夹。在那个文件夹里：
-
converted/: FHIR NDJSON 输出文件（每个输入文件一个，例如-record.ndjson）。 converted/patient
-
ERROR/：失败输入的错误详情（例如，带有 inputFile 和 ErrorMessage 字段的 JSON 文件）。 ERROR/bad-file.json
-
Manifest.json：包含汇总指标的任务摘要（文件已扫描、已转换、失败、生成的资源）。
-
jobLevelDriftResult.json：作业的汇总偏差报告（如果启用了偏差检测）。
-
driftDetectionPerFileResults/：对于启用了偏差检测的 C-CDA 作业，每个文件的偏差报告（例如， driftDetectionPerFileResults/patient-record_driftMetrics.json），因此您可以检查单个源文件的覆盖范围，而不仅仅是作业级别的聚合。
监控
通过任务详细信息页面或 DescribeDataTransformationJob API 跟踪正在运行的 AWS 管理控制台 作业：状态、已处理的文件（CSV 行数）、生成的资源和失败。Job 指标和日志也可在 Amazon 中找到 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 → 源文件。Provenance 资源引用 a DocumentReference，它记录了源文件的 Amazon S3 URI 和 SHA-1 校验和。校验和允许您证明输出来自特定的、未经更改的源文件。如果需要这些信息，还会提供将 AWS HealthLake 数据转换表示为一个实体的设备资源。
Record-level 定位器
Provenance 不仅可以解析到源文件，还可以解析到其中的确切位置，而且定位器因源格式而异：
-
C-CDA: 指向资源来源的源元素的 XPath。
-
CSV：源记录的表名、主键和行号。
捕获的田地
每个 Provenance 资源都记录源文件 URI 和校验和、用于转换的配置文件版本、时间戳和记录级别定位器。
一致性与使用
来源资源符合美国核心来源概况，因此它们可以与美国工具互操作。 Core-aware 当您需要可审计性以实现合规性时，或者需要将可疑的输出资源追溯到产生该资源的确切源元素时，启用来源。默认情况下，Provenance 处于启用状态；设置 ProvenanceEnabled 为 false 则将其禁用。
偏差检测
在静默删除配置文件尚未映射的源数据时，转换可以成功。漂移检测表面有间隙。它是一个报告：启用后，它会将来源包含的内容与配置文件的实际生成内容进行比较，并记录留下的内容。
报告包含的内容
-
转换的总体覆盖率。
-
未映射的源部分和元素的排名列表，因此您可以对影响最大的差距进行优先排序。
-
未产生的任何预期资源。
-
完全可追溯到源文件和元素位置（文件名和 OID 为 C-CDA，CSV 为行）。
如何使用漂移检测
两种转换模式均提供漂移检测，因此无论是迭代单个文件还是验证完整的数据集，您都可以使用它：
-
同步（实时）：在 TransformData 请求对单个文件运行偏差检测并在 API 响应中返回结果时设置 DriftDetectionEnabled 为 true。这是在创作个人资料时检查覆盖率的最快方法：转换一个代表性文档，准确查看配置文件遗漏了什么，完善映射，然后重试。
-
批量（异步）：在转换作业上启用漂移检测，以测量整个数据集的覆盖率。该报告以作业LevelDriftResult.json 形式写入任务的 Amazon S3 输出位置。对于 C-CDA 作业，每个文件的偏差报告也写在偏移 DetectionPerFileResults /文件夹下，因此您可以精确定位单个源文件中的覆盖差距。
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 入门有关设置和工作流程示例，请参阅。
