18 搭售品與 CI/CD (預覽版)

搭售品會定義 Oracle AI Data Platform Workbench 資源在工作區與環境中進行封裝、啟動多版本功能、共用及部署的方式。

您可以建立工作和代理程式的組合。搭售品會建立在 Git 資料夾中，以便確認搭售品檔案並將其推送至 Git 儲存庫。您包含在組合中的資源可以來自工作區中的任何位置。如果選取的資源參照支援的檔案或相依性 (例如記事本、命令檔或運算)，這些參照就會包含在組合中，如此就可以在另一個環境中部署資源，而不需要手動重新建立相同的元件。

您可以從工作區建立組合，並選取要在建立時包含的 Oracle AI Data Platform Workbench 資源。您可以修改現有的組合以新增或移除資源。搭售資源可讓您將相關工作和代理程式分組，並將它們部署到其他沒有相依性的環境。

您可以透過 Git 資料夾，將組合確認並推送至 Git 儲存區域。然後，使用者可將搭售品提取至自己的環境並進行部署。變更確認並推送至 Git 儲存區域後，其他環境即可使用組合檔案變更。每當使用者從 Git 儲存區域提取更新的組合時，他們就會收到最新的確認資源檔案。

搭售品概念

概念 意義 使用者動作
Git 資料夾 連線至 Git 儲存區域和分支的 AI 資料平台資料夾。只能在 Git 資料夾中建立搭售品。 請先建立或開啟 Git 資料夾，再建立組合。
Bundle 定義所選資源及其相依性的可部署套裝程式。 從工作區建立組合，然後選取資源，例如工作或代理程式流程。
組合課程內容 產生的檔案，描述部署所需的資源、變數、目標設定值和使用者自建物件。 建立或同步後複查產生的內容。準備好時，透過 Git 確認並推送搭售品。
Target 在來源環境外部部署組合時所使用的環境或工作區組態。 提供必須依環境變更的值，例如工作區索引鍵、證明資料名稱、權杖索引鍵或參數預設值。
已部署項目 由目標工作區中的組合部署所建立或更新的資源。 您可以使用「建置」頁籤，視需要建置、複查建置的項目、執行工作以及永久清除建置的資源。
同步 此組合動作會重新整理最新來源資源的組合資源和相依性。 變更組合資源後執行同步，然後將重新整理過的組合檔案確認至 Git。

開始之前

請檢查此清單，確定您擁有開始使用 AI 資料平台工作區中 Git 組合所需的一切：
  • 建立 Git 證明資料和指向組合檔案所使用之儲存區域和分支的 Git 資料夾。
  • 請先確認來源資源位於工作區中，並且先儲存後再建立或同步組合。
  • 若要進行跨環境部署，請確認目標工作區具備必要的權限和運算能力。
  • 對於使用加密密碼的工作或記事本，請在目標證明資料存放區中建立必要的指定證明資料。組合檔案應依名稱或變數參照證明資料，不包含加密密碼值。
  • 請在建立或同步組合後確認並推送組合檔案變更，讓其他環境可以提取最新的組合定義。

建立組合 (預覽)

您可以組合 Oracle AI Data Platform 工作和代理程式資源，以建立可建置到另一個 Git 資料夾的套裝程式。

  1. 瀏覽至您的工作區。
  2. 按一下動作，然後按一下建立搭售品。
  3. 提供組合的名稱與描述。
  4. 按一下瀏覽，然後選取工作區中您要建立組合的 Git 資料夾。
  5. 從列出的選項，選取要包含在組合中的資源。
  6. 按一下建立。

    附註：

    搭售品是在 Git 資料夾中建立。如果選取的位置不在 Git 資料夾內，您就無法使用 Git 將產生的組合檔案移至其他環境。

建立搭售品之後產生的收益 (預覽)

搭售品建立之後，Oracle AI Data Platform 會將您產生的檔案寫入搭售品資料夾。

確切的檔案名稱因資源類型而異，但建立的組合通常包含最上層組合資訊清單、資源定義、使用者自建物件資料夾及選擇性的覆寫檔案。

產生的項目 描述
aidp_workbench.yaml 組合清單。識別建置期間所使用的組合、包含的資源、變數以及目標區段。
.aidp/resource_origins.yaml 資源定義。描述工作、記事本工作、運算參照或代理程式流程等資源。
.aidp/overrides.yaml 覆寫檔案或目標區段。保留不同環境的值，例如工作區識別碼、參數預設值、證明資料名稱或權杖索引鍵。
.aidp/aidp.state.json 追蹤從組合部署的資源。用於未來的部署和永久清除作業。
jobs/ 職務描述子與職務相依性。
agentflows/ 代理程式描述區和代理程式相依性。
artifacts/ 構件資料夾。複製的程式碼、記事本以及支援的檔案使用者自建物件。

部署搭售品 (預覽)

您可以從 Git 資料夾部署組合，以在工作區和環境之間共用資源和相依性。

  1. 瀏覽至您要在工作區中部署的搭售品。
  2. 按一下部署頁籤。
  3. 選擇性：複查目標值與置換 (如果適用)。
  4. 按一下部署。部署完成後會通知您。

    附註：

    在首次部署時，部署頁籤在部署成功前不會顯示任何已部署的項目。成功部署後，請複查已部署的資源、視需要執行工作或代理程式，並確認執行時期輸出。

同步搭售品 (預覽)

您可以同步組合來更新組合中的資源與相依性，並進行最新的變更。

同步會使用搭售品記錄的來源中繼資料，從建立搭售品時擷取的來源工作和代理程式流程重新建立搭售品。來源描述資料會儲存在 .aidp/resource_origins.yaml 中，而且必須符合要求的執行處理和工作區。此作業會重新整理來源控制的組合內容，同時保留組合識別和程式實際執行描述資料。

進行同步時，服務會在組合 .aidp 目錄下暫存重新整理過的組合快照、比較現有和暫存的描述區、保留現有的變數別名，並儘可能覆寫參照、合併現有的資訊清單預設變數，然後將重新整理過的來源控制檔案升級回組合根目錄。

Sync 會保留環境特定檔案和部署程式實際執行檔案，例如 .aidp/overrides.yaml 和 .aidp/aidp.state.json。這些檔案不會被重新整理的來源快照取代。

您應該在下列情況下同步搭售品：
  • 來源工作區中的隨附記事本、工作、代理程式流程、運算參照、參數或相依性已變更。
  • 組合工作現在會指向其他記事本或已更新任務參數。
  • 代理程式組態、提示參數、模型設定或 AI 運算相依性已變更。
  • 您需要 Git 資料夾包含最新產生的搭售品檔案，才能推送至其他環境。
  1. 瀏覽至您要在工作區中同步處理的搭售品。
  2. 按一下動作。
  3. 按一下同步。同步完成後會通知您。

建議的搭售品促銷工作流程

建議您依照 Oracle AI Data Platform 中 Git 組合的開發、封裝、版本、提取、設定、部署及驗證工作流程進行操作。

階段 動作 結果
開發 在來源工作區中建立或更新記事本、工作、運算設定值或代理程式流程。 來源資源包含最新的預期行為。
套裝程式 建立搭售品，或在現有搭售品上執行 Sync。 產生的組合包檔案反映目前的來源資源和相依性。
Version 透過 Git 資料夾複查、確認及推送組合資料夾。 遠端儲存區域包含可建置的組合定義。
提取 在目標工作區中，提取 Git 資料夾變更。 目標工作區包含最新的組合檔案。
設定 設定目標特定值，例如工作區索引鍵、參數預設值、證明資料名稱、權杖索引鍵或程式實際執行設定值。 此組合已可供目標環境使用。
部署 開啟「建置」組合頁籤，然後按一下「建置」。 維護作業會建立或更新已部署的資源。
驗證 執行已部署的工作或測試已部署的代理程式流程，並檢查日誌或輸出。 系統會先驗證目標環境，然後再繼續升級。

搭售品變數 (預覽)

當組合需要可針對每個目標環境變更的部署階段值，而不需要編輯資源定義時，請使用組合變數。

若要開始使用含有組合的變數，您必須在組合的 aidp_workbench.yaml 檔案中定義含有預設值的變數名稱，並在需要時定義環境特定的覆寫。然後，您可以從產生的定義檔中參照這些變數。

範例變數工作流程

  1. 在 aidp_workbench.yaml 的 defaults > variables 下定義變數名稱。
  2. 在相同的 aidp_workbench.yaml 檔案中，選擇性地定義 targets > <environment> > variables 下的環境特定值。
  3. 使用目標覆寫來設定建置階段值，例如開發區域、QA 區域、生產區域、綱要名稱、證明資料名稱、記號索引鍵或參數預設值。
  4. 找不到相符的目標環境時，Oracle AI Data Platform 會使用 aidp_workbench.yaml 的預設變數值。
  5. 在任何產生的定義檔中使用變數，例如工作定義、計算定義、工作定義或其他 YAML 定義檔。
  6. 使用 ${var.<variable_name>>} 參照變數，將 <<variable_name>> 取代為在 aidp_workbench.yaml 中定義的實際變數名稱。
  7. 當 UI 預期有指定的預留位置時，在如代理程式提示或工具定義等位置使用資源特定的預留位置語法。
  8. 若為僅限暫時部署的變更，請建立 .aidp/overrides.yaml，並在該處定義變數值。

組合變數語法

變數定義必須以 aidp_workbench.yaml 撰寫。其他組合定義檔只能參照變數名稱。

定義 語法 範例
aidp_workbench.yaml 中的變數定義 
defaults: 
  variables: 
    <<variable_name>>: <<default_value>> 
defaults: 
  variables: 
    deployment_region: "us-ashburn-1"
aidp_workbench.yaml 中的目標特定覆寫 
targets: 
  <<target_name>>: 
    variables: 
      <<variable_name>>: <<target_value>> 
targets: 
  qa: 

   “workbenchid”: “ocid” 
   “workspaceKey”: “key” 

    variables: 
      deployment_region: "us-phoenix-1"
定義檔案中的變數參考 ${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}"

範例：檔案名稱與解析度

在產生的組合中，變數定義與使用變數的資源可以位於不同的檔案中。當您透過 Git 升級或複製範例時，請包含整個組合資料夾，以便資訊清單、工作定義及物件保持在一起。 
testNamedVarBundleJob/ 
  aidp_workbench.yaml 
  jobs/ 
    namedVariableJobDemo.job.json 
  artifacts/ 
    namedVarNotebookDemo.ipynb
File 包含的內容 變數或解析值
aidp_workbench.yaml 定義預設值 > 變數和選擇性目標覆寫下的變數。 變數：job_param_value_default。
jobs/namedVariableJobDemo.job.json 使用變數作為工作參數 param_key 的值。 參考資料：${var.job_param_value_default}。
artifacts/namedVarNotebookDemo.ipynb 在執行時期讀取解析的工作參數。 筆記本在解析後會讀取 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}" 
  } 
]
部署目標 變數解決方法 筆記本接收
沒有符合的目標 使用 aidp_workbench.yaml 的預設值。 param_key = cloud data governance
裝置 使用 dev 目標覆寫。 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。如果參照的變數沒有可用的值，則在使用記事本備用值之前，部署或工作執行可能會失敗。

下一個部署的暫時覆寫

aidp_workbench.yaml 中的定義足以進行一般搭售品促銷。如果使用者需要暫時覆寫變數，請在組合資料夾中建立 .aidp/overrides.yaml，並在該處定義變數值。AI 資料平台在下一個部署期間使用這些值。 

.aidp/ 
  overrides.yaml
variables: 
  agent_topic_default: "tuesday"
File 範例值 使用時
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。

範例工作流程：使用變數搭配證明資料存放區

  1. 在證明資料存放區中建立證明資料和權杖金鑰。
  2. 定義證明資料名稱和權杖索引鍵的變數。
  3. 將這些變數當作參數傳送至工作或記事本。
  4. 在程式實際執行時，記事本會讀取參數並呼叫證明資料 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_token 建立 dev_credential_store_entry。
qa 中文 _ English 繁體中文 使用金鑰 qa_token 建立 qa_credential_store_entry。
產品 產品證明資料存放區項目 產品權杖 使用金鑰 prod_token 建立 prod_credential_store_entry。

清除搭售品 (預覽)

您可以永久清除已部署的組合，以從您的工作區移除組合資源。

  1. 瀏覽至您要清除工作區中資源的組合。
  2. 按一下部署頁籤。
  3. 按一下永久清除。
  4. 在提示中輸入清除。按一下永久清除。

疑難排解搭售品 (預覽)

如果您在建立和管理 Git 組合時發生問題，請查看下列潛在解決方案問題清單。

徵兆 可能的原因 建議的動作
「建立搭售品」無法使用，或無法建立搭售品。 使用者不在 Git 資料夾中，或沒有必要的工作區權限。 瀏覽至 Git 資料夾並確認使用者可以建立工作區資源。
同步完成，但另一個環境看不到更新。 重新整理的組合檔案未確認、推送或提取至目標 Git 資料夾中。 確認並從來源 Git 資料夾推送，然後在部署之前提取目標工作區。
「部署」頁籤未顯示任何已部署的項目。 尚未部署搭售品，或部署未順利完成。 按一下「部署」並等待完成通知。如果部署失敗，請複查日誌。
部署的工作因證明資料查尋錯誤而失敗。 目標證明資料名稱、記號索引鍵或存取權限與組合組態不符。 重新部署之前，請先在目標證明資料存放區中建立證明資料或更新目標變數。
代理程式流程部署失敗或以非作用中運算開始。 目標環境可能沒有相容的 AI 運算、區域、模型或相依性設定值。 複查目標覆寫、運算狀態、模型可用性及部署日誌。
部署後不會反映來源記事本或代理程式流程的變更。 已部署搭售品，但未先從更新的來源資源進行同步。 在搭售品上執行 Sync、確認並發送重新整理過的搭售品檔案、將它們提取到目標中，然後再次部署。