34 번들 및 CI/CD(미리보기)

번들은 Oracle AI Data Platform Workbench 리소스가 작업영역 및 환경 전반에서 패키지화, 버전 지정, 공유 및 배포되는 방식을 정의합니다.

작업 및 에이전트에 대한 번들을 생성할 수 있습니다. 번들 파일을 커밋하고 Git 저장소로 푸시할 수 있도록 번들이 Git 폴더에 생성됩니다. 번들에 포함하는 리소스는 작업영역의 모든 위치에서 가져올 수 있습니다. 선택한 리소스가 지원 파일 또는 종속성(예: 노트북, 스크립트 또는 컴퓨트)을 참조하는 경우 이러한 참조가 번들에 포함되므로 동일한 구성요소를 수동으로 다시 만들지 않고도 리소스를 다른 환경에 배치할 수 있습니다.

작업영역에서 번들을 생성하고 생성 시 포함할 Oracle AI Data Platform Workbench 리소스를 선택합니다. 기존 번들을 수정하여 리소스를 추가하거나 제거할 수 있습니다. 리소스를 번들링하면 관련 작업 및 에이전트를 함께 그룹화하고 종속성이 그대로 있는 다른 환경에 배치할 수 있습니다.

Git 폴더를 통해 Git 저장소에 번들을 커밋하고 푸시할 수 있습니다. 그런 다음 사용자는 번들을 자체 환경으로 가져와서 배포할 수 있습니다. 번들 파일에 대한 변경 사항은 변경 사항이 커밋되고 Git 저장소로 푸시된 후 다른 환경에서 사용할 수 있습니다. 사용자가 Git 저장소에서 업데이트된 번들을 가져올 때마다 커밋된 최신 리소스 파일을 받습니다.

번들 개념

개념 의미 사용자 작업
Git 폴더 Git 저장소 및 분기에 연결된 AI 데이터 플랫폼 폴더입니다. 번들은 Git 폴더에서만 생성할 수 있습니다. 번들을 생성하기 전에 Git 폴더를 생성하거나 엽니다.
집합 선택한 리소스 및 해당 종속성을 정의하는 배치 가능 패키지입니다. 작업영역에서 번들을 생성한 다음 작업 또는 에이전트 플로우와 같은 자원을 선택합니다.
번들 컨텐츠 배포에 필요한 리소스, 변수, 대상 설정 및 아티팩트를 설명하는 생성된 파일입니다. 생성 또는 동기화 후 생성된 콘텐츠를 검토합니다. 준비가 되면 Git을 통해 번들을 커밋하고 푸시합니다.
Target 소스 환경 외부에서 번들을 배포할 때 사용되는 환경 또는 작업영역 구성입니다. 작업영역 키, 인증서 이름, 토큰 키 또는 매개변수 기본값과 같이 환경별로 변경해야 하는 값을 제공합니다.
배포된 항목 대상 작업영역에서 번들 배포에 의해 생성 또는 업데이트된 자원입니다. 배치 탭을 사용하여 필요한 경우 배치된 항목을 배치, 검토, 작업 실행 및 배치된 리소스 비우기를 수행할 수 있습니다.
동기화 최신 소스 리소스에서 번들 리소스 및 종속성을 새로 고치는 번들 작업입니다. 번들된 리소스를 변경한 후 동기화를 실행한 다음 새로 고친 번들 파일을 Git에 커밋합니다.

시작하기 전에

AI Data Platform 작업영역에서 Git 번들 사용을 시작하는 데 필요한 모든 항목이 있는지 확인하려면 이 목록을 선택합니다.
  • 번들 파일에 사용되는 저장소 및 분기를 가리키는 Git 인증서 및 Git 폴더를 생성합니다.
  • 소스 리소스가 작업영역에 있으며 번들을 생성하거나 동기화하기 전에 저장되었는지 확인하십시오.
  • 환경 간 배치의 경우 대상 작업 영역에 필요한 권한과 컴퓨트 용량이 있는지 확인합니다.
  • 암호를 사용하는 작업이나 노트북의 경우 대상 인증서 저장소에 필요한 이름이 지정된 인증서를 만듭니다. 번들 파일은 암호 값을 포함하지 않고 이름 또는 변수로 인증서를 참조해야 합니다.
  • 번들을 생성하거나 동기화한 후 번들 파일 변경사항을 커밋 및 푸시하여 다른 환경에서 최신 번들 정의를 가져올 수 있도록 합니다.

번들 게시 경로

번들은 사용자가 검사할 수 있는 작업영역 폴더에 런타임 아티팩트를 게시할 수 있습니다. 런타임 아티팩트에는 배포된 번들 리소스에 필요한 노트북, 스크립트, 라이브러리 및 에이전트 흐름 파일과 같은 파일이 포함됩니다. 아티팩트가 게시되는 폴더를 게시 경로라고 합니다. 아티팩트는 게시 경로 내의 아티팩트 폴더 아래에 저장됩니다.

예를 들어, 게시 경로가 /Workspace/Shared/customer_churn_bundle인 경우 번들 아티팩트는 /Workspace/Shared/customer_churn_bundle/artifacts 아래에 게시됩니다.

게시 경로가 번들에 대한 정보 소스가 아닙니다. 번들 소스 파일은 번들 폴더에 남아 있으며 Git에 커밋되어야 합니다. 게시 경로 아래의 파일은 배포된 리소스에서 사용되는 런타임 파일입니다. 게시 경로에서 파일을 수동으로 편집하는 경우 이러한 편집 내용은 번들 소스에 다시 기록되지 않습니다. 이후 배포는 게시된 아티팩트를 번들의 파일로 대체할 수 있습니다.

번들 생성(미리보기)

Oracle AI Data Platform 작업 및 에이전트 리소스를 번들하여 다른 Git 폴더에 배포할 수 있는 패키지를 생성할 수 있습니다.

  1. 작업 영역으로 이동합니다.
  2. 작업을 누른 다음 번들 생성을 누릅니다.
  3. 번들에 대한 이름 및 설명을 제공하십시오.
  4. 찾아보기를 누르고 번들을 생성할 작업영역에서 Git 폴더를 선택합니다.
  5. 나열된 옵션에서 번들에 포함할 리소스를 선택합니다.
  6. 생성을 누릅니다.

    주:

    번들은 Git 폴더에 생성됩니다. 선택한 위치가 Git 폴더 내에 없는 경우 Git를 사용하여 생성된 번들 파일을 다른 환경으로 이동할 수 없습니다.

    주:

    번들이 생성되면 AI 데이터 플랫폼이 번들 매니페스트에 기본 게시 구성을 포함할 수 있습니다. 게시 구성은 번들이 배포될 때 런타임 아티팩트가 배치되는 위치를 제어합니다.

번들 생성 후 생성된 가져오기(미리보기)

번들 생성 후 Oracle AI Data Platform은 생성된 파일을 번들 폴더에 기록합니다.

정확한 파일 이름은 리소스 유형에 따라 다르지만, 생성된 번들에는 일반적으로 최상위 번들 매니페스트, 리소스 정의, 아티팩트 폴더 및 선택적 대체 파일이 포함됩니다.

생성된 항목 설명
aidp_workbench.yaml 번들 적하목록 배치 중 사용되는 번들, 포함된 리소스, 변수 및 대상 섹션을 식별합니다.
.aidp/resource_origins.yaml 리소스 정의입니다. 작업, 노트북 작업, 컴퓨팅 참조 또는 에이전트 흐름과 같은 리소스를 설명합니다.
.aidp/overrides.yaml 파일 또는 대상 섹션을 무효화합니다. 작업영역 식별자, 매개변수 기본값, 인증서 이름 또는 토큰 키와 같이 환경에 따라 다른 값을 보유합니다.
.aidp/aidp.state.json 번들에서 배치된 리소스를 추적합니다. 이후 배치 및 비우기 작업에 사용됩니다.
jobs/ 작업 기술자 및 작업 종속성
agentflows/ 에이전트 기술자 및 에이전트 종속성
artifacts/ 아티팩트 폴더입니다. 코드, 노트북 및 지원 파일 아티팩트를 복사했습니다.

게시 경로 구성(미리보기)

번들 매니페스트 파일 aidp_workbench.yaml에서 번들에 대한 게시 경로를 구성할 수 있습니다.

번들 파일에 대한 게시 경로를 구성하려면 다음 예제와 같이 aidp_workbench.yaml 매니페스트 파일의 defaults 아래에 게시 블록을 추가합니다. 

bundle:
  name: customer_churn_bundle
  description: Customer churn model workflow

resources:
  jobs:
    - train_churn_model
  agentflows:
    - explain_churn_predictions

defaults:
  publish:
    path: "/Workspace/Shared/customer_churn_bundle"
    overwrite_publish_artifacts: false

이 예에서 번들이 배포되면 아티팩트가 /Workspace/Shared/customer_churn_bundle/artifacts 아래에 게시됩니다.

표 34-1 게시 경로 구성 필드

필드 설명
path 게시 루트로 사용되는 작업영역 폴더입니다. 아티팩트는 <path>/artifacts 아래에 저장됩니다.
overwrite_publish_artifacts 배포가 구성된 게시 경로에서 기존 게시된 아티팩트를 대체할 수 있는지 여부를 나타냅니다.

다른 환경에 대한 게시 경로 구성

다음 예와 같이 여러 배치 대상에 대해 서로 다른 게시 경로를 구성할 수 있습니다.

bundle:
  name: customer_churn_bundle

resources:
  jobs:
    - train_churn_model

defaults:
  publish:
    path: "/Workspace/Shared/customer_churn_bundle"
    overwrite_publish_artifacts: false

targets:
  prod:
    - aidp_ocid: "ocid1.aidataplatform.oc1..example"
      workspace_key: "workspace-prod"
      publish:
        path: "/Workspace/Production/customer_churn_bundle"
        overwrite_publish_artifacts: true

또는 .aidp/overrides.yaml를 사용하여 로컬에서 게시 경로를 대체할 수 있습니다. 

publish:
  path: "/Workspace/Users/me/customer_churn_bundle"
  overwrite_publish_artifacts: true
여러 게시 경로가 구성된 경우 Oracle AI Data Platform은 다음 순서로 게시 경로를 확인합니다.
  1. aidp_workbench.yaml의 defaults.publish.path
  2. 일치하는 대상 게시 경로
  3. .aidp/overrides.yaml 게시 경로

번들 아티팩트의 게시 방법(미리보기)

번들을 배포할 때 Oracle AI Data Platform은 번들 소스의 번들 아티팩트를 해결된 게시 경로로 복사합니다.

기본 아티팩트 레이아웃은 <publish.path>/artifacts입니다. 예: 

/Workspace/Shared/customer_churn_bundle/artifacts

번들 기술자 파일은 ${publish.path}/artifacts/...를 사용하여 게시된 아티팩트를 참조할 수 있습니다. 예: 

${publish.path}/artifacts/Notebooks/train_model.ipynb

배치 중 ${publish.path}는 구성된 게시 경로로 분석됩니다.

번들 배포(미리보기)

Git 폴더에서 번들을 배포하여 작업영역 및 환경 간에 리소스 및 종속성을 공유할 수 있습니다.

  1. 작업영역에 배포할 번들로 이동합니다.
  2. 배치 탭을 누르십시오.
  3. 선택 사항: 해당하는 경우 대상 값 및 재정의를 검토합니다.
  4. 배치를 누릅니다. 배치가 완료되면 통지를 받습니다.

    주:

    첫번째 배치 시 배치 탭에 배치가 성공할 때까지 배치된 항목이 표시되지 않을 수 있습니다. 성공적으로 배치한 후 배치된 리소스를 검토하고, 필요에 따라 작업 또는 에이전트를 실행하고, 런타임 출력을 확인합니다.

    주:

    배포 중 번들 아티팩트는 리소스가 배포되기 전에 구성된 게시 경로에 게시됩니다. 사용자정의 게시 경로가 구성되지 않은 경우 Oracle AI Data Platform은 번들에 대한 기본 게시 위치를 사용합니다.

게시된 경로에 번들을 배치하는 방법(미리보기)

번들에 게시 경로가 구성된 경우 배포는 고정된 작업 세트를 수행합니다.

구성된 게시 경로가 있는 번들을 배치할 때 Oracle AI Data Platform이 수행하는 작업은 다음 순서로 수행됩니다.

  1. 게시 경로를 검증합니다.
  2. <publish.path>/artifacts에 번들 아티팩트를 게시합니다.
  3. 게시된 아티팩트 경로를 사용하여 작업 및 에이전트 플로우와 같은 번들 리소스를 배치합니다.
  4. 배치가 완료된 후 배치 상태를 업데이트합니다.

AI 데이터 플랫폼에서 게시 경로와 관련된 문제가 발생할 경우 다음과 같이 다양한 작업이 수행될 수 있습니다.

  • 게시 경로가 없는 경우 AI 데이터 플랫폼에서 배포 중 생성할 수 있습니다.
  • 게시 경로가 있고 비어 있는 경우 배포에서 사용할 수 있습니다.
  • 게시 경로에 동일한 번들로 관리되는 아티팩트가 포함된 경우 배포에서 업데이트할 수 있습니다.
  • 게시 경로에 번들이 소유하지 않은 데이터가 포함된 경우 겹쳐쓰기가 사용으로 설정되지 않은 경우 배포가 실패할 수 있습니다.

번들 동기화(미리보기)

번들을 동기화하여 번들의 리소스 및 종속성을 최신 변경사항과 업데이트할 수 있습니다.

Sync는 번들의 기록된 원본 메타데이터를 사용하여 번들이 생성될 때 캡처된 소스 작업 및 에이전트 흐름에서 번들을 재구축합니다. 소스 메타데이터는 .aidp/resource_origins.yaml에 저장되며 요청된 인스턴스 및 작업영역과 일치해야 합니다. 이 작업은 번들 ID 및 런타임 메타데이터를 유지하면서 소스 제어 번들 콘텐츠를 새로 고칩니다.

동기화 중에 서비스는 번들 .aidp 디렉토리 아래에 새로 고친 번들 스냅샷을 스테이지하고, 기존 및 스테이지된 기술자를 비교하고, 기존 변수 별칭을 보존하고, 가능한 경우 참조를 대체하고, 기존 매니페스트 기본 변수를 병합한 다음 새로 고친 소스 제어 파일을 번들 루트로 다시 승격합니다.

동기화는 .aidp/overrides.yaml 및 .aidp/aidp.state.json와 같은 환경별 및 배포 런타임 파일을 보존합니다. 이러한 파일은 새로 고친 소스 스냅샷으로 대체되지 않습니다.

다음과 같은 경우 번들을 동기화해야 합니다.
  • 소스 작업 영역에서 번들 노트북, 작업, 에이전트 흐름, 컴퓨트 참조, 매개변수 또는 종속성이 변경되었습니다.
  • 이제 번들 작업이 다른 노트북을 가리키거나 업데이트된 작업 매개변수가 있습니다.
  • 에이전트 구성, 프롬프트 매개변수, 모델 설정 또는 AI 컴퓨트 종속성이 변경되었습니다.
  • 다른 환경으로 푸시하기 전에 생성된 최신 번들 파일을 포함하려면 Git 폴더가 필요합니다.
  1. 작업영역에서 동기화할 번들로 이동합니다.
  2. 작업을 누릅니다.
  3. 동기화를 누릅니다. 동기화가 완료되면 통지됩니다.

번들에 대한 권장 프로모션 워크플로우(미리보기)

Oracle AI Data Platform에서 번들에 대한 개발, 패키지, 버전, 풀링, 구성, 배포 및 검증 워크플로우를 따르는 것이 좋습니다.

단계 작업 결과
개발 소스 작업 영역에서 노트북, 작업, 컴퓨트 설정 또는 에이전트 플로우를 생성하거나 업데이트합니다. 소스 리소스에는 최신 의도된 동작이 포함됩니다.
패키지 번들을 만들거나 기존 번들에서 동기화를 실행합니다. 생성된 번들 파일은 현재 소스 리소스 및 종속성을 반영합니다.
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
파일 포함된 내용 변수 또는 해결된 값
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"

그러면 작업 정의에서 jobs/namedVariableJobDemo.job.json에 동일한 변수 이름을 사용할 수 있습니다. 번들 변수를 지원하는 작업 정의, 계산 정의, 작업 정의 및 기타 생성된 YAML 정의 파일에 동일한 구문을 사용할 수 있습니다.

"parameters": [ 
  { 
    "name": "param_key", 
    "value": "${var.job_param_value_default}" 
  } 
]
배치 대상 변수 지정 메모장 수신
일치하는 대상 없음 aidp_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 데이터 플랫폼은 다음 배포에 해당 임시 값을 사용합니다. 그렇지 않으면 AI 데이터 플랫폼이 먼저 선택된 대상에서 변수를 해결합니다. 일치하는 대상 환경을 찾을 수 없거나 선택한 대상이 변수를 대체하지 않을 경우 AI 데이터 플랫폼이 aidp_workbench.yaml의 defaults > variables으로 폴백됩니다. 참조된 변수에 사용할 수 있는 값이 없으면 노트북 폴백 값이 사용되기 전에 배치 또는 작업 실행이 실패할 수 있습니다.

다음 배치에 대한 임시 재정의

aidp_workbench.yaml의 정의는 정상적인 번들 프로모션을 위해 충분합니다. 사용자가 일시적으로 변수를 재정의해야 하는 경우 번들 폴더에 .aidp/overrides.yaml을 생성하고 여기에 변수 값을 정의합니다. AI 데이터 플랫폼은 다음 배포 시 해당 값을 사용합니다. 

.aidp/ 
  overrides.yaml
variables: 
  agent_topic_default: "tuesday"
파일 예시 값 사용 시
aidp_workbench.yaml defaults Oracle AI Data Platform 일치하는 대상 또는 대체 파일이 변수를 제공하지 않을 때 사용됩니다.
aidp_workbench.yaml target dev AIDP 개발 작업영역 개발로 배포할 때 사용되며 임시 대체가 없습니다.
.aidp/overrides.yaml 화요일 다음 배치 중 임시 값으로 사용됩니다.

주:

임시 배치 값에 .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 번들이 동일한 논리적 변수 이름을 유지하면서 각 환경이 자체 배포 시간 값을 제공할 수 있습니다.

개발 영역, QA 영역 및 운용 환경이 서로 다른 값을 가진 동일한 리소스 정의를 배치해야 하는 경우 이 패턴을 사용합니다.

명명된 변수 워크플로우 예

  1. aidp_workbench.yaml의 defaults > variables에서 변수를 한 번 정의합니다.
  2. 각 대상 환경에서 동일한 변수 이름을 무효화합니다.
  3. 변수 값이 대상 작업 영역과 일치하는 대상으로 배치합니다.
  4. 운용 전용 암호 또는 작업 영역별 식별자가 아닌 안전한 폴백 값에 기본값을 사용합니다.

예: 개발, QA 및 제품 대체

다음 예에서는 세 대상에서 동일한 변수 이름을 사용합니다. 이 작업은 여전히 변수를 한 번 참조하지만 개발 영역, QA 지역 및 운영 환경은 다른 배포 시간 값을 제공합니다. 

bundle: 
  name: environmentVariableDemoBundle 
resources: 
  jobs: 
    - namedVariableJobDemo 
defaults: 
  variables: 
    job_param_value_default: "cloud data governance" 
    deployment_region: "us-ashburn-1" 
targets: 
  dev: 
    aidp_ocid: "ocid1.aidataplatformdev.oc1.iad.exampledev" 
    workspace_key: dev_workspace 
    variables: 
      job_param_value_default: "space tourism" 
      deployment_region: "us-ashburn-1" 
  qa: 
    aidp_ocid: "ocid1.aidataplatformdev.oc1.iad.exampleqa" 
    workspace_key: qa_workspace 
    variables: 
      job_param_value_default: "data quality validation" 
      deployment_region: "us-phoenix-1" 
  prod: 
    aidp_ocid: "ocid1.aidataplatformdev.oc1.iad.exampleprod" 
    workspace_key: prod_workspace 
    variables: 
      job_param_value_default: "customer operations" 
      deployment_region: "eu-frankfurt-1"
Target 배치_영역 작업_매개변수_값_기본값 런타임 결과
편차 us-ashburn-1 우주 관광 작업은 개발 영역 및 매개변수 값으로 실행됩니다.
QA us-phoenix-1 데이터 품질 검증 작업은 QA 영역 및 매개변수 값으로 실행됩니다.
제품 eu-frankfurt-1 고객 운영 작업은 운용 환경 값으로 실행됩니다.

주:

일치하는 대상 환경을 찾을 수 없거나 대상이 재정의를 정의하지 않는 경우 워크벤치는 구성된 기본 변수 값을 사용합니다. 무효화 또는 적합한 기본값을 사용할 수 없는 경우 누락된 변수가 사용되는 위치에 따라 배치 또는 런타임 실행이 실패할 수 있습니다.

번들 변수 및 인증서 저장소(미리보기)

번들 작업 또는 노트북에서 런타임 시 암호를 조회해야 하는 경우 인증서 저장소와 함께 변수를 사용할 수 있습니다.

변수는 인증서 이름과 토큰 키를 가져야 합니다. 실제 암호 값은 대상 인증서 저장소에 있어야 하며 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_credential_store_entry 개발자 토큰 dev_token 키를 사용하여 dev_credential_store_entry를 생성합니다.
QA qa_credential_store_entry 사이트맵 qa_token 키를 사용하여 qa_credential_store_entry를 생성합니다.
제품 prod_credential_store_entry 사이트맵 prod_token 키를 사용하여 prod_credential_store_entry를 생성합니다.

번들 비우기(미리보기)

배포된 번들을 제거하여 작업영역에서 번들 자원을 제거할 수 있습니다.

  1. 작업영역에서 자원을 비우려는 번들로 이동합니다.
  2. 배치 탭을 누르십시오.
  3. 비우기를 누릅니다.
  4. 프롬프트에 비우기를 입력합니다. 비우기를 누릅니다.

주:

번들을 비우면 배치된 리소스가 먼저 제거됩니다. 번들이 게시 경로를 사용하는 경우 Oracle AI Data Platform은 게시 경로 아래의 관리 아티팩트 폴더를 제거합니다. 게시 경로 아래의 다른 파일은 보존됩니다.

게시된 아티팩트에 대한 비우기 동작(미리보기)

배포된 번들을 비우면 Oracle AI Data Platform이 먼저 배포된 리소스를 제거합니다.

리소스가 제거된 후 AI 데이터 플랫폼은 관리되는 아티팩트 폴더(<publish.path>/artifacts)만 제거합니다.

게시 경로 아래의 다른 파일이나 폴더는 보존됩니다. 예를 들어 게시 경로가 /Workspace/Shared/customer_churn_bundle인 경우 비우기는 /Workspace/Shared/customer_churn_bundle/artifacts를 제거하지만 /Workspace/Shared/customer_churn_bundle 아래의 다른 파일이나 폴더는 보존합니다.

권한 또는 경로 액세스로 인해 아티팩트 정리를 완료할 수 없는 경우에도 리소스 삭제를 완료할 수 있습니다.

기존 번들 및 게시 경로(미리보기)

게시 블록이 없는 기존 번들은 동기화되거나 수동으로 업데이트될 때까지 이전 아티팩트 동작을 계속 사용합니다.

기존 번들에 게시 블록을 수동으로 추가하는 경우 배포에는 구성된 게시 경로가 사용됩니다. 그러나 기존 기술자 파일은 배치 중에 자동으로 변경되지 않습니다. 기존 기술자가 여전히 이전 아티팩트 위치를 참조하는 경우 해당 리소스가 이전 위치를 계속 사용할 수 있습니다.

기존 자원이 게시 경로를 사용하도록 하려면 사용자정의 게시 블록을 수동으로 추가하기 전에 기술자 참조를 업데이트하거나 번들을 동기화하십시오. 예:

Old:
${bundle.root}/.aidp/artifacts/Shared/task1.py

New:
${publish.path}/artifacts/Shared/task1.py

동기화가 이미 게시 블록이 있는 번들에 대해 새 설명자 콘텐츠 또는 새로 고쳐진 설명자 콘텐츠를 추가하는 경우 새 설명자 참조는 게시 경로 형식을 사용합니다.

번들 문제 해결(미리보기)

Git 번들을 만들고 관리할 때 문제가 발생하면 다음 문제 목록에서 잠재적 해결 방법을 확인하십시오.

증상 가능성 있는 원인 권장되는 작업
번들 생성을 사용할 수 없거나 번들을 생성할 수 없습니다. 사용자가 Git 폴더에 없거나 필요한 작업 영역 권한이 없습니다. Git 폴더로 이동하고 사용자가 작업 영역 리소스를 생성할 수 있는지 확인합니다.
동기화가 완료되었으나 업데이트를 볼 수 없는 환경입니다. 새로 고친 번들 파일은 대상 Git 폴더로 커밋, 푸시 또는 풀링되지 않았습니다. 소스 Git 폴더에서 커밋하고 푸시한 다음 배치하기 전에 대상 작업 영역을 가져옵니다.
배포 탭에 배포된 항목이 표시되지 않습니다. 번들이 아직 배포되지 않았거나 배포가 성공적으로 완료되지 않았습니다. Deploy를 누르고 완료 통지가 나타날 때까지 기다립니다. 배포 실패 시 로그를 검토합니다.
인증서 조회 오류로 인해 배치된 작업이 실패했습니다. 대상 인증서 이름, 토큰 키 또는 액세스 권한이 번들 구성과 일치하지 않습니다. 재배치하기 전에 대상 인증서 저장소에 인증서를 생성하거나 대상 변수를 업데이트하십시오.
에이전트 플로우 배치가 실패하거나 비활성 컴퓨트로 시작합니다. 대상 환경에 호환되는 AI 컴퓨트, 영역, 모델 또는 종속성 설정이 없을 수 있습니다. 대상 우선 적용, 계산 상태, 모델 가용성 및 배포 로그를 검토합니다.
소스 노트북 또는 에이전트 플로우에 대한 변경사항은 배치 후 반영되지 않습니다. 업데이트된 소스 리소스에서 먼저 동기화하지 않고 번들이 배포되었습니다. 번들에서 동기화를 실행하고 새로 고친 번들 파일을 커밋 및 푸시하고 대상에서 풀링한 다음 다시 배포합니다.