18 捆绑包和 CI/CD（预览）
捆绑包定义如何在工作区和环境之间打包、版本化、共享和部署 Oracle AI Data Platform Workbench 资源。
您可以为作业和代理创建捆绑包。在 Git 文件夹中创建捆绑包，以便将捆绑包文件提交并推送到 Git 资源库。您包含在捆绑包中的资源可以来自工作区中的任何位置。如果所选资源引用支持文件或依赖项（例如记事本、脚本或计算），则这些引用将包含在捆绑包中，以便可以在其他环境中部署资源，而无需手动重新创建相同的组件。
您可以从工作区创建捆绑包，并选择创建时要包括的 Oracle AI Data Platform Workbench 资源。可以修改现有捆绑包以添加或删除资源。通过捆绑资源，您可以将相关作业和代理组合在一起，并将它们部署到其他环境中，其依赖项保持不变。
您可以通过 Git 文件夹将捆绑包提交并推送到 Git 资源库。然后，用户可以将捆绑包拉到自己的环境中并部署它们。在提交更改并将其推送到 Git 资源库之后，对捆绑包文件的更改可供其他环境使用。每当用户从 Git 资源库中提取更新的捆绑包时，他们都会收到最新的已提交资源文件。
捆绑包概念
| 概念 | 含义 | 用户操作 |
|---|---|---|
| Git 文件夹 | 连接到 Git 资料档案库和分支的 AI Data Platform 文件夹。只能在 Git 文件夹中创建捆绑包。 | 在创建捆绑包之前创建或打开 Git 文件夹。 |
| 捆绑包 | 定义所选资源及其依赖项的可部署程序包。 | 从工作区创建捆绑包，然后选择任务或代理流等资源。 |
| 捆绑内容 | 生成的文件描述了部署所需的资源、变量、目标设置和对象。 | 创建或同步后复查生成的内容。准备就绪时，提交并推送包通过 Git。 |
| 目标 | 在源环境之外部署捆绑包时使用的环境或工作区配置。 | 提供必须按环境更改的值，例如工作区密钥、身份证明名称、令牌密钥或参数默认值。 |
| 已部署项 | 由目标工作区中的捆绑包部署创建或更新的资源。 | 使用“部署”选项卡可以部署、查看已部署项、运行作业，并在需要时清除已部署的资源。 |
| 同步 | 用于从最新源资源刷新捆绑包资源和依赖项的捆绑包操作。 | 在更改捆绑资源后运行同步，然后将刷新的捆绑包文件提交到 Git。 |
准备工作
- 创建 Git 身份证明和指向用于捆绑包文件的资源库和分支的 Git 文件夹。
- 在创建或同步捆绑包之前，请确认源资源在工作区中并已保存。
- 对于跨环境部署，请确认目标工作区具有所需的权限和计算能力。
- 对于使用密钥的作业或记事本，请在目标身份证明存储中创建所需的命名身份证明。捆绑包文件应按名称或变量引用凭证，不包含密钥值。
- 在创建或同步捆绑包后提交和推送捆绑包文件更改，以便其他环境可以提取最新的捆绑包定义。
创建捆绑包后生成的内容（预览）
创建捆绑包后，Oracle AI Data Platform 会将生成的文件写入捆绑包文件夹。
确切的文件名因资源类型而异，但创建的包通常包含顶层包清单、资源定义、对象文件夹和可选覆盖文件。
| 生成的货品 | 说明 |
|---|---|
aidp_workbench.yaml |
捆绑包清单。标识部署期间使用的捆绑包、包括的资源、变量和目标部分。 |
.aidp/resource_origins.yaml |
资源定义描述作业、记事本任务、计算引用或代理流等资源。 |
.aidp/overrides.yaml |
覆盖文件或目标区段。保存因环境而异的值，例如工作区标识符、参数默认值、身份证明名称或令牌密钥。 |
.aidp/aidp.state.json |
跟踪从捆绑包部署的资源。由将来的部署和清除操作使用。 |
jobs/ |
作业描述符和作业相关性。 |
agentflows/ |
代理描述符和代理相关性。 |
artifacts/ |
对象文件夹。已复制代码、记事本和支持文件对象。 |
同步捆绑包（预览）
您可以同步捆绑包以使用最新更改更新捆绑包中的资源和依赖项。
同步使用捆绑包记录的源元数据从创建捆绑包时捕获的源作业和代理流中重建捆绑包。源元数据存储在 .aidp/resource_origins.yaml 中，必须与请求的实例和工作区匹配。此操作会刷新源控制的捆绑包内容，同时保留捆绑包身份和运行时元数据。
在同步期间，服务会在包 .aidp 目录下暂存已刷新的包快照，比较现有描述符和暂存描述符，保留现有变量别名并尽可能覆盖引用，合并现有清单缺省变量，然后将刷新后的源控制文件提升回包根。
同步会保留特定于环境的部署运行时文件，例如 .aidp/overrides.yaml 和 .aidp/aidp.state.json。这些文件不会替换为刷新的源快照。
- 在源工作区中更改了捆绑的记事本、作业、代理流、计算引用、参数或相关性。
- 捆绑作业现在指向其他记事本或已更新任务参数。
- 代理配置、提示参数、模型设置或 AI 计算相关性已更改。
- 在推送到其他环境之前，您需要使用 Git 文件夹来包含最新生成的捆绑包文件。
- 导航到要在工作区中同步的捆绑包。
- 单击操作。
- 单击 Sync 。同步完成时，系统会通知您。
捆绑包的建议促销工作流
我们建议您遵循 Oracle AI Data Platform 中 Git 捆绑包的开发、打包、版本、拉取、配置、部署和验证工作流。
| 阶段 | 操作 | 结果 |
|---|---|---|
| 开发 | 在源工作区中创建或更新记事本、作业、计算设置或代理流。 | 源资源包含最新的预期行为。 |
| 程序包 | 创建捆绑包，或对现有捆绑包运行同步。 | 生成的捆绑包文件反映当前源资源和依赖项。 |
| Version | 通过 Git 文件夹检查、提交和推送捆绑包文件夹。 | 远程资源库包含可部署的捆绑包定义。 |
| 拉入 | 在目标工作区中，拉取 Git 文件夹更改。 | 目标工作区具有最新的捆绑包文件。 |
| 配置 | 设置特定于目标的值，例如工作区密钥、参数默认值、身份证明名称、令牌密钥或运行时设置。 | 捆绑包已准备好用于目标环境。 |
| 部署 | 打开捆绑包“Deployment（部署）”选项卡并单击“Deploy（部署）”。 | 工作台创建或更新已部署的资源。 |
| 验证 | 运行部署的作业或测试部署的代理流，并检查日志或输出。 | 在继续提升之前，将验证目标环境。 |
捆绑包变量（预览）
当捆绑包需要可以针对每个目标环境更改的部署时间值而无需编辑资源定义时，请使用捆绑包变量。
要开始将变量与捆绑包一起使用，需要在捆绑包的 aidp_workbench.yaml 文件中定义变量名称，并根据需要定义特定于环境的覆盖。然后，从生成的定义文件中引用这些变量。
变量工作流示例
- 在
aidp_workbench.yaml的defaults > variables下定义变量名称。 - （可选）在同一
aidp_workbench.yaml文件的targets > <environment> > variables下定义特定于环境的值。 - 使用目标覆盖可以设置部署时间值，例如开发区域、QA 区域、生产区域、方案名称、身份证明名称、令牌密钥或参数默认值。
- 未找到匹配的目标环境时，Oracle AI Data Platform 将使用 helpp_workbench.yaml 中的默认变量值。
- 在任何生成的定义文件中使用该变量，例如作业定义、计算定义、任务定义或其他 YAML 定义文件。
- 使用 ${var.<<variable_name>>} 引用变量，将 <<variable_name>> 替换为 helpp_workbench.yaml 中定义的实际变量名称。
- 当 UI 需要指定占位符时，请在座席提示或工具定义等位置使用特定于资源的占位符语法。
- 对于仅临时部署的更改，创建 .aidp/overrides.yaml 并定义变量值。
捆绑包变量语法
变量定义必须写入 aidp_workbench.yaml。其他捆绑包定义文件应仅引用变量名称。
| 定义 | 语法 | 范例 |
|---|---|---|
aidp_workbench.yaml 中的变量定义
|
|
|
aidp_workbench.yaml 中特定于目标的覆盖 |
|
|
| 定义文件中的变量引用 | ${var.<<variable_name>>} |
value: "${var.deployment_region}" |
| 代理提示或工具字段中的命名占位符 | {{variable_name}} |
Generate a summary about {{topic}}. |
示例：作业参数变量
bundle:
name: namedVariableJobDemo
resources:
jobs:
- namedVariableJobDemo
defaults:
variables:
job_param_value_default: "cloud data governance"
jobs:
namedVariableJobDemo:
tasks:
- taskKey: Task_956691
parameters:
- name: param_key
value: "${var.job_param_value_default}" 记事本任务可以通过作业使用的参数名称读取解析的值：
param_value = odiUtils.parameters.getParameter("param_key", "fallback value")
print(param_value)示例：aidp_workbench.yaml 变量定义
aidp_workbench.yaml 中的变量 agent_topic_default。未找到匹配的目标环境，或者没有选定的环境或临时覆盖提供变量时，将应用默认值。每个目标可以覆盖该工作区的相同变量名称。defaults:
variables:
agent_topic_default: "Oracle AI Data Platform"
targets:
dev:
- aidp_ocid: "ocid1.aidataplatformdev.oc1.iad.exampledev"
workspace_key: "6271b138-6f2c-4e8c-a9e5-013e17079955"
variables:
agent_topic_default: "AIDP Dev Workspace"
qa:
- aidp_ocid: "ocid1.aidataplatformdev.oc1.iad.exampleqa"
workspace_key: "daa0e9b5-f8d7-4ae8-b728-2984e68a74c0"
variables:
agent_topic_default: "AIDP QA Workspace"
prod:
- aidp_ocid: "ocid1.aidataplatform.oc1.iad.exampleprod"
workspace_key: "83be5b8c-bb8d-4ec4-a8fb-16b50b0e4d4c"
variables:
agent_topic_default: "AIDP Production Workspace" 然后，支持捆绑包变量的任何捆绑包定义文件都可以引用相同的变量名称。例如：
tasks/agentTopic.task.yaml
parameters:
- name: topic
value: "${var.agent_topic_default}"示例：文件名和解决方法
testNamedVarBundleJob/
aidp_workbench.yaml
jobs/
namedVariableJobDemo.job.json
artifacts/
namedVarNotebookDemo.ipynb| 文件 | 它包含的内容 | 变量或解析值 |
|---|---|---|
aidp_workbench.yaml |
在缺省值 > 变量和可选目标覆盖下定义变量。 | 变量：job_param_value_default。
|
jobs/namedVariableJobDemo.job.json |
将变量用作作业参数 param_key 的值。 | 参考：${var.job_param_value_default}。
|
artifacts/namedVarNotebookDemo.ipynb |
在运行时读取解析的作业参数。 | Notebook 在解析后读取 param_key。
|
aidp_workbench.yaml 中定义缺省值和目标覆盖：defaults:
variables:
job_param_value_default: "cloud data governance"
targets:
dev:
variables:
job_param_value_default: "space tourism"
qa:
variables:
job_param_value_default: "data quality validation"
prod:
variables:
job_param_value_default: "customer operations"然后，作业定义可以在 job/namedVariableJobDemo.job.json 中使用该变量名称。可以在支持捆绑包变量的作业定义、计算定义、任务定义和其他生成的 YAML 定义文件中使用相同的语法：
"parameters": [
{
"name": "param_key",
"value": "${var.job_param_value_default}"
}
]| 部署目标 | 变量解决方案 | 笔记本接收 |
|---|---|---|
| 没有匹配的目标 | 使用 helpp_workbench.yaml 中的默认值。 | param_key = cloud data governance
|
| 开发 | 使用开发目标覆盖。 | param_key = space tourism
|
| qa | 使用 qa 目标覆盖。 | param_key = data quality validation |
| 产品 | 使用产品目标覆盖。 | param_key = customer operations |
解决顺序
当 .aidp/overrides.yaml 提供变量值时， AI Data Platform 会将该临时值用于下一个部署。否则， AI 数据平台将首先解析所选目标中的变量。如果未找到匹配的目标环境，或者所选目标未覆盖变量，则 AI Data Platform 将回退到 aidp_workbench.yaml 中的 defaults > variables。如果引用变量没有值可用，则在使用记事本回退值之前，部署或作业执行可能会失败。
下一个部署的临时覆盖
helpp_workbench.yaml 中的定义足以进行常规捆绑包促销。如果用户需要临时覆盖变量，请在 bundle 文件夹中创建 .aidp/overrides.yaml 并定义变量值。AI Data Platform 在下一次部署期间使用这些值。
.aidp/
overrides.yamlvariables:
agent_topic_default: "tuesday"| 文件 | 示例值 | 使用时 |
|---|---|---|
aidp_workbench.yaml defaults
|
Oracle AI Data Platform | 当没有匹配的目标或覆盖文件提供变量时使用。 |
aidp_workbench.yaml target dev |
AIDP 开发工作区 | 在部署到开发并且不存在临时覆盖时使用。 |
.aidp/overrides.yaml |
tuesday | 在下次部署期间用作临时值。 |
注意：
将.aidp/overrides.yaml 用于临时部署值。在 aidp_workbench.yaml 中保留持久的默认值和环境特定的值，以便包通过 Git 保持可重现。
示例：代理提示变量
对于支持命名占位符的代理流提示文本或工具定义，请在变量名称周围使用双括号。
Prompt text:
You are a demo assistant. For the given {{topic}}, generate 3 short bullet points explaining why it matters.
Tool parameter:
Name: /{{topic}}
Default value: sunday 注意：
作为最佳实践，您应该使用变量来表示预计在各个部署中发生变化的值。当变量可以携带值时，避免将特定于环境的值直接嵌入到记事本、作业或代理流文本中。示例：无计算的工作流
您可以为不会在部署过程中自动创建计算集群的工作流创建捆绑包。首先，在 aidp_workbench.yaml 中创建一个变量：
defaults:
variables:
job_compute_key: "select_compute"jobs/ 文件夹中，找到作业文件 <JobName>.job.json。编辑作业文件，将 "clusterKey" 值替换为新创建的变量："clusterKey" : "${var.job_compute_key}",捆绑变量和身份证明存储（预览）
当捆绑作业或记事本需要在运行时查找密钥时，可以将变量与身份证明存储一起使用。
变量应带有凭证名称和令牌密钥。实际密钥值必须保留在目标身份证明存储中，不应提交到 Git。
工作流示例：将变量与身份证明存储结合使用
- 在身份证明存储库中创建身份证明和令牌密钥。
- 定义身份证明名称和令牌密钥的变量。
- 将这些变量作为参数传递到作业或记事本中。
- 在运行时，记事本会读取参数并调用身份证明 API 以检索密钥。如果身份证明名称、令牌密钥或权限错误，则作业可能会失败，并显示身份证明查找错误。
注意：
请勿在捆绑包文件中记录或提交密钥值。捆绑包配置应引用身份证明名称、令牌密钥和目标变量；身份证明存储仍是密钥材料的源。示例：身份证明名称和标记键变量
bundle:
name: credentialVariableDemoBundle
resources:
jobs:
- credentialLookupJob
defaults:
variables:
cred_key: default_credential_name
token_key: default_token_key
targets:
dev:
workspace_key: dev_workspace
variables:
cred_key: dev_credential_store_entry
token_key: dev_token
qa:
workspace_key: qa_workspace
variables:
cred_key: qa_credential_store_entry
token_key: qa_token
prod:
workspace_key: prod_workspace
variables:
cred_key: prod_credential_store_entry
token_key: prod_token
jobs:
credentialLookupJob:
tasks:
- taskKey: Task_854239
parameters:
- name: cred_key
value: "${var.cred_key}"
- name: token_key
value: "${var.token_key}" 记事本读取参数值，然后使用它们从身份证明存储中查找密钥：
cred_name = odiUtils.parameters.getParameter("cred_key", "defaultCredValue")
token_name = odiUtils.parameters.getParameter("token_key", "defaultTokenValue")
secret = aidpUtils.secrets.get(name=cred_name, key=token_name)
if secret:
print("Credential lookup succeeded")
else:
raise Exception("Credential lookup failed")| 环境 | cred_key 值 | token_key 值 | 身份证明存储要求 |
|---|---|---|---|
| 开发 | dev_credential_store_entry | 开发令牌 | 使用关键字 dev_token 创建 dev_credential_store_entry。 |
| qa | qa_credential_store_entry | qa 令牌 | 使用关键字 qa_token 创建 qa_credential_store_entry。 |
| 产品 | prod_credential_store_entry | 产品令牌 | 使用关键字 prod_token 创建 prod_credential_store_entry。 |
捆绑包故障排除（预览）
如果您在创建和管理 Git 捆绑包时遇到问题，请查看以下问题列表以了解可能的解决方案。
| 症状 | 可能原因 | 建议的操作 |
|---|---|---|
| “创建捆绑包”不可用，或者无法创建捆绑包。 | 用户不在 Git 文件夹中，或者缺少所需的工作区权限。 | 导航到 Git 文件夹并确认用户可以创建工作区资源。 |
| 同步完成，但另一个环境看不到更新。 | 刷新的捆绑包文件未提交、推送或拉入目标 Git 文件夹。 | 从源 Git 文件夹提交和推送，然后在部署之前拉入目标工作区。 |
| “部署”选项卡未显示已部署项。 | 捆绑包尚未部署，或部署未成功完成。 | 单击“Deploy（部署）”并等待完成通知。如果部署失败，请查看日志。 |
| 部署的作业失败，出现身份证明查找错误。 | 目标身份证明名称、令牌密钥或访问权限与捆绑包配置不匹配。 | 在目标身份证明存储中创建身份证明或在重新部署之前更新目标变量。 |
| 代理流部署失败或从非活动计算开始。 | 目标环境可能没有兼容的 AI 计算、区域、模型或依赖项设置。 | 查看目标覆盖、计算状态、模型可用性和部署日志。 |
| 部署后不会反映对源记事本或代理流的更改。 | 已部署该捆绑包，但未首先从更新的源资源同步。 | 在捆绑包上运行同步，提交并推送刷新的捆绑包文件，将它们拉入目标，然后重新部署。 |