34 Bundles e CI/CD (Visualização)

Os pacotes definem como os recursos do Oracle AI Data Platform Workbench são empacotados, com controle de versão, compartilhados e implantados em espaços de trabalho e ambientes.

Você pode criar bundles para jobs e agentes. Um bundle é criado em uma pasta Git para que os arquivos do bundle possam ser confirmados e enviados para um repositório Git. Os recursos que você inclui no pacote podem vir de qualquer local do espaço de trabalho. Se os recursos selecionados fizerem referência a arquivos ou dependências de suporte, como notebooks, scripts ou computação, essas referências serão incluídas no pacote para que os recursos possam ser implantados em outro ambiente sem recriar manualmente os mesmos componentes.

Você cria pacotes do seu espaço de trabalho e seleciona os recursos do Oracle AI Data Platform Workbench a serem incluídos no momento da criação. Os bundles existentes podem ser modificados para adicionar ou remover recursos. O agrupamento de recursos permite agrupar jobs e agentes relacionados e implantá-los em outros ambientes com suas dependências intactas.

Você pode fazer commit e enviar bundles para seu repositório Git por meio de suas pastas Git. Os usuários podem, então, puxar os pacotes para seus próprios ambientes e implantá-los. As alterações nos arquivos de pacote ficam disponíveis para outros ambientes depois que as alterações são confirmadas e enviadas para o repositório Git. Sempre que os usuários extraem o pacote atualizado do repositório Git, eles recebem os arquivos de recursos confirmados mais recentes.

Conceitos do Pacote

Conceito Definição Ação do Usuário
Pasta Git Uma pasta da Plataforma de Dados AI conectada a um repositório e uma ramificação Git. Os bundles só podem ser criados em pastas Git. Crie ou abra uma pasta Git antes de criar um bundle.
Pacote Um pacote implantável que define os recursos selecionados e suas dependências. Crie o pacote no espaço de trabalho e selecione recursos como jobs ou fluxos de agentes.
Conteúdo de bundle Arquivos gerados que descrevem recursos, variáveis, definições de destino e artefatos necessários para implantação. Revise o conteúdo gerado após criar ou sincronizar. Confirme e envie o pacote pelo Git quando estiver pronto.
Target Uma configuração de ambiente ou espaço de trabalho usada ao implantar o pacote fora do ambiente de origem. Forneça valores que devem ser alterados por ambiente, como chave do espaço de trabalho, nome da credencial, chave do token ou padrões de parâmetro.
Item implantado Um recurso criado ou atualizado por uma implantação de pacote no espaço de trabalho de destino. Use a guia Implantação para implantar, revisar itens implantados, executar jobs e expurgar recursos implantados quando necessário.
Sincronização Uma ação de bundle que atualiza recursos de bundle e dependências dos recursos de origem mais recentes. Execute a sincronização após alterar os recursos agrupados e, em seguida, confirme os arquivos de pacote atualizados no Git.

Antes de Começar

Marque esta lista para ter certeza de que você tem tudo o que precisa para começar a usar os pacotes Git no espaço de trabalho da AI Data Platform:
  • Crie credenciais Git e uma pasta Git que aponte para o repositório e a ramificação usados para arquivos de bundle.
  • Confirme se os recursos de origem estão no espaço de trabalho e são salvos antes de criar ou sincronizar o pacote.
  • Para implantação entre ambientes, confirme se o espaço de trabalho de destino tem permissões e capacidade de computação necessárias.
  • Para jobs ou notebooks que usam segredos, crie as credenciais nomeadas necessárias no armazenamento de credenciais de destino. Os arquivos de pacote devem fazer referência a credenciais por nome ou variável, sem conter valores secretos.
  • Faça commit e envie alterações no arquivo do bundle após criar ou sincronizar um bundle para que outros ambientes possam extrair a definição de bundle mais recente.

Caminhos de Publicação do Pacote

Os bundles podem publicar artefatos de runtime em uma pasta do espaço de trabalho que os usuários podem inspecionar. Os artefatos de runtime incluem arquivos como notebooks, scripts, bibliotecas e arquivos de fluxo do agente necessários aos recursos de pacote implantados. A pasta em que os artefatos são publicados é chamada de caminho de publicação. Os artefatos são armazenados em uma pasta de artefatos dentro do caminho de publicação.

Por exemplo, se o caminho de publicação for: /Workspace/Shared/customer_churn_bundle, os artefatos do pacote serão publicados em: /Workspace/Shared/customer_churn_bundle/artifacts.

O caminho de publicação não é a origem da verdade do pacote. Os arquivos de origem do bundle permanecem na pasta do bundle e devem ser confirmados com o Git. Os arquivos no caminho de publicação são arquivos de runtime usados pelos recursos implantados. Se você editar manualmente os arquivos no caminho de publicação, essas edições não serão gravadas de volta na origem do bundle. Uma implantação posterior pode substituir os artefatos publicados por arquivos do pacote.

Criar um bundle (visualização)

Você pode agrupar recursos de job e agente do Oracle AI Data Platform para criar um pacote que possa ser implantado em outra pasta do Git.

  1. Navegue até o seu espaço de trabalho.
  2. Clique em Ações e, em seguida, clique em Criar Pacote.
  3. Informe um nome e descrição para o seu pacote.
  4. Clique em Procurar e selecione a pasta Git no espaço de trabalho em que deseja criar o pacote.
  5. Selecione os recursos que deseja incluir no pacote entre as opções listadas.
  6. Clique em Criar.

    Observação:

    Os pacotes são criados em pastas Git. Se o local selecionado não estiver dentro de uma pasta Git, não será possível usar o Git para mover os arquivos de bundle gerados para outro ambiente.

    Observação:

    Quando um bundle é criado, a Plataforma de dados de IA pode incluir uma configuração de publicação padrão no manifesto do bundle. A configuração de publicação controla onde os artefatos de runtime são colocados quando o pacote é implantado.

O Que É Gerado Após a Criação do Pacote (Visualização)

Após a criação do bundle, o Oracle AI Data Platform grava seus arquivos gerados na pasta do bundle.

Os nomes exatos dos arquivos variam de acordo com o tipo de recurso, mas o pacote criado geralmente contém um manifesto de pacote de nível superior, definições de recurso, pastas de artefato e arquivos de substituição opcionais.

Item Gerado Descrição
aidp_workbench.yaml Manifesto do bundle. Identifica o pacote, recursos incluídos, variáveis e seções de destino usadas durante a implantação.
.aidp/resource_origins.yaml Definições de recurso. Descreva recursos como jobs, tarefas de notebook, referências de computação ou fluxos de agentes.
.aidp/overrides.yaml Substituir arquivos ou seções de destino. Mantenha valores diferentes por ambiente, como identificadores de espaço de trabalho, padrões de parâmetro, nomes de credenciais ou chaves de token.
.aidp/aidp.state.json Rastreia recursos implantados no pacote. Usado por futuras operações de implantação e expurgação.
jobs/ Descritores e dependências de cargo.
agentflows/ Descritores do agente e dependências do agente.
artifacts/ Pastas de artefato. Código copiado, notebooks e artefatos de arquivo de suporte.

Configuração do Caminho de Publicação (Visualização)

Você pode configurar o caminho de publicação de um bundle no arquivo de manifesto do bundle, aidp_workbench.yaml.

Para configurar o caminho de publicação para um arquivo de bundle, adicione um bloco de publicação em defaults no arquivo de manifesto aidp_workbench.yaml, como neste exemplo: 

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

Neste exemplo, quando o pacote é implantado, os artefatos são publicados em /Workspace/Shared/customer_churn_bundle/artifacts.

Tabela 34-1 Campos de Configuração do Caminho de Publicação

Campo Descrição
path Pasta do espaço de trabalho usada como raiz de publicação. Os artefatos são armazenados em <path>/artifacts.
overwrite_publish_artifacts Indica se a implantação pode substituir artefatos publicados existentes no caminho de publicação configurado.

Publicar Configuração de Caminho para Ambientes Diferentes

Você pode configurar diferentes caminhos de publicação para diferentes destinos de implantação, como neste exemplo:

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

Como alternativa, você pode usar .aidp/overrides.yaml para substituir o caminho de publicação localmente: 

publish:
  path: "/Workspace/Users/me/customer_churn_bundle"
  overwrite_publish_artifacts: true
Quando vários caminhos de publicação são configurados, o Oracle AI Data Platform resolve o caminho de publicação nesta ordem:
  1. defaults.publish.path em aidp_workbench.yaml
  2. Caminho de publicação do destino correspondente
  3. Caminho de publicação .aidp/overrides.yaml

Como os Artefatos do Pacote são Publicados (Visualização)

Quando você implanta um pacote, o Oracle AI Data Platform copia os artefatos do pacote da origem do pacote para o caminho de publicação resolvido.

O layout de artefato padrão é <publish.path>/artifacts. Por exemplo: 

/Workspace/Shared/customer_churn_bundle/artifacts

Os arquivos de descritor de pacote podem fazer referência a artefatos publicados usando ${publish.path}/artifacts/.... Por exemplo: 

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

Durante a implantação, o ${publish.path} é resolvido para o caminho de publicação configurado.

Implantar um Pacote (Visualização)

Você pode implantar pacotes de uma pasta Git para compartilhar recursos e dependências entre espaços de trabalho e ambientes.

  1. Navegue até o pacote que você deseja implantar no seu espaço de trabalho.
  2. Clique na guia Implantação.
  3. Opcional: Revise valores de destino e substituições, se aplicável.
  4. Clique em Disponibilizar. Você é notificado quando a implantação é concluída.

    Observação:

    Na primeira implantação, a guia Implantação pode não mostrar itens implantados até que a implantação seja bem-sucedida. Após uma implantação bem-sucedida, revise os recursos implantados, execute jobs ou agentes conforme necessário e confirme a saída de runtime.

    Observação:

    Durante a implantação, os artefatos de pacote são publicados no caminho de publicação configurado antes da implantação dos recursos. Se nenhum caminho de publicação personalizado for configurado, o Oracle AI Data Platform usará o local de publicação padrão para o pacote.

Como os Pacotes são Implantados em Caminhos Publicados (Visualização)

Quando um pacote tem um caminho de publicação configurado, a implantação executa um conjunto fixo de ações.

As ações que o Oracle AI Data Platform executa ao implantar um pacote com um caminho de publicação configurado ocorrem nesta ordem:

  1. Valide o caminho de publicação.
  2. Publique artefatos do pacote em <publish.path>/artifacts.
  3. Implante recursos de pacote, como jobs e fluxos de agentes, usando os caminhos de artefato publicados.
  4. Atualize o status da implantação após a conclusão da implantação.

Podem ocorrer diferentes ações se a Plataforma de Dados de IA encontrar qualquer problema com o caminho de publicação:

  • Se o caminho de publicação não existir, o AI Data Platform poderá criá-lo durante a implantação.
  • Se o caminho de publicação existir e estiver vazio, a implantação poderá usá-lo.
  • Se o caminho de publicação contiver artefatos gerenciados pelo mesmo pacote, a implantação poderá atualizá-los.
  • Se o caminho de publicação contiver dados que não pertencem ao pacote, a implantação poderá falhar, a menos que a substituição esteja ativada.

Sincronizar um bundle (visualização)

Você pode sincronizar um bundle para atualizar os recursos e as dependências no bundle com as alterações mais recentes.

O Sync usa os metadados de origem registrados do bundle para recriar o bundle dos jobs de origem e fluxos de agentes que foram capturados quando o bundle foi criado. Os metadados de origem são armazenados no .aidp/resource_origins.yaml e devem corresponder à instância e ao espaço de trabalho solicitados. A operação atualiza o conteúdo do bundle controlado pela origem, preservando a identidade do bundle e os metadados de runtime.

Durante a sincronização, o serviço prepara um snapshot de bundle atualizado no diretório .aidp do bundle, compara descritores existentes e preparados, preserva aliases de variáveis existentes e substitui referências quando possível, mescla variáveis padrão de manifesto existentes e, em seguida, promove os arquivos controlados por origem atualizados de volta para a raiz do bundle.

A sincronização preserva arquivos de runtime de implantação e específicos do ambiente, como .aidp/overrides.yaml e .aidp/aidp.state.json. Esses arquivos não são substituídos pelo snapshot de origem atualizado.

Você deve sincronizar seus bundles quando:
  • Um notebook, um job, um fluxo de agentes agrupados, uma referência de computação, um parâmetro ou uma dependência alterados no espaço de trabalho de origem.
  • Um job agrupado agora aponta para outro notebook ou atualizou parâmetros de tarefa.
  • Uma configuração de agente, um parâmetro de prompt, uma definição de modelo ou uma dependência de computação AI foi alterada.
  • Você precisa que a pasta Git contenha os arquivos de bundle mais recentes gerados antes de enviar para outro ambiente.
  1. Navegue até o pacote que deseja sincronizar no seu espaço de trabalho.
  2. Clique em Ações.
  3. Clique em Sincronizar. Você é notificado quando a sincronização é concluída.

Workflow de Promoção Recomendado para Pacotes de Descontos (Visualização)

Recomendamos seguir um fluxo de trabalho de desenvolvimento, pacote, versão, pull, configuração, implantação e validação para pacotes no Oracle AI Data Platform.

Fase Ação Resultado
Desenvolver Crie ou atualize notebooks, jobs, definições de computação ou fluxos de agentes no espaço de trabalho de origem. Os recursos de origem contêm o comportamento pretendido mais recente.
Pacote Crie o bundle ou execute o Sync em um bundle existente. Os arquivos de bundle gerados refletem os recursos e as dependências de origem atuais.
Version Revise, confirme e envie a pasta do bundle pela pasta Git. O repositório remoto contém a definição do pacote implantável.
Baixa Automática No espaço de trabalho de destino, extraia as alterações da pasta Git. O espaço de trabalho de destino tem os arquivos de pacote mais recentes.
Configurar Defina valores específicos do alvo, como chave do espaço de trabalho, padrões de parâmetro, nome da credencial, chave do token ou definições de runtime. O pacote está pronto para o ambiente de destino.
Implante Abra a guia Implantação do pacote e clique em Implantar. O Workbench cria ou atualiza os recursos implantados.
Validar Execute jobs implantados ou teste fluxos de agentes implantados e inspecione logs ou saída. O ambiente de destino é verificado antes da continuação da promoção.

Variáveis do Pacote (Visualização)

Use variáveis de pacote quando um pacote precisar de valores de tempo de implantação que possam ser alterados para cada ambiente de destino sem editar a definição de recurso.

Para começar a usar variáveis com bundles, você precisa definir os nomes das variáveis no arquivo aidp_workbench.yaml do bundle com valores padrão e, quando necessário, substituições específicas do ambiente. Em seguida, você faz referência a essas variáveis dos arquivos de definição gerados.

Exemplo de Workflow Variável

  1. Defina nomes de variáveis em defaults > variables em aidp_workbench.yaml.
  2. Opcionalmente, defina valores específicos do ambiente em targets > <environment> > variables no mesmo arquivo aidp_workbench.yaml.
  3. Use substituições de destino para definir valores de tempo de implantação, como uma região de desenvolvimento, região de QA, região de produção, nome do esquema, nome da credencial, chave de token ou parâmetro padrão.
  4. Quando nenhum ambiente de destino correspondente for encontrado, a Oracle AI Data Platform usará o valor de variável padrão de aidp_workbench.yaml.
  5. Use a variável em qualquer arquivo de definição gerado, como uma definição de job, definição de computação, definição de tarefa ou outro arquivo de definição YAML.
  6. Consulte a variável com ${var.<variable_name>>>}, substituindo <<variable_name>> pelo nome da variável real definido em aidp_workbench.yaml.
  7. Use a sintaxe de espaço reservado específica do recurso em locais como prompts de agente ou definições de ferramenta quando a IU esperar um espaço reservado nomeado.
  8. Para alterações temporárias somente de implantação, crie .aidp/overrides.yaml e defina valores de variáveis lá.

Sintaxe de Variável do Pacote

As definições de variável devem ser gravadas em aidp_workbench.yaml. Outros arquivos de definição de pacote só devem fazer referência ao nome da variável.

Definição Sintaxe Exemplo
Definição de variável em aidp_workbench.yaml 
defaults: 
  variables: 
    <<variable_name>>: <<default_value>> 
defaults: 
  variables: 
    deployment_region: "us-ashburn-1"
Substituição específica do alvo emaidp_workbench.yaml 
targets: 
  <<target_name>>: 
    variables: 
      <<variable_name>>: <<target_value>> 
targets: 
  qa: 

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

    variables: 
      deployment_region: "us-phoenix-1"
Referência de variável em um arquivo de definição ${var.<<variable_name>>} value: "${var.deployment_region}"
Marcador nomeado em um prompt de agente ou campo de ferramenta {{variable_name}} Generate a summary about {{topic}}.

Exemplo: Variável de Parâmetro do Job

O exemplo a seguir define uma variável e a transmite para um parâmetro de job. O recurso pode permanecer inalterado enquanto o valor da variável é alterado na configuração do pacote.
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}"

Uma tarefa de notebook pode ler o valor resolvido por meio do nome do parâmetro usado pelo job:

param_value = odiUtils.parameters.getParameter("param_key", "fallback value") 
print(param_value)

Exemplo: Definição da Variável aidp_workbench.yaml

Este exemplo define a variável agent_topic_default no aidp_workbench.yaml. O valor padrão se aplica quando nenhum ambiente de destino correspondente é encontrado ou quando nenhum ambiente selecionado ou substituição temporária fornece a variável. Cada destino pode substituir o mesmo nome de variável para esse espaço de trabalho.
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"

Qualquer arquivo de definição de bundle que suporte variáveis de bundle pode então fazer referência ao mesmo nome de variável. Por exemplo:

tasks/agentTopic.task.yaml 

parameters: 
  - name: topic 
    value: "${var.agent_topic_default}"

Exemplo: Nomes de Arquivo e Resolução

Em um pacote gerado, a definição de variável e o recurso que usa a variável podem estar em arquivos diferentes. Quando você promove ou copia o exemplo através do Git, inclua toda a pasta do bundle para que o manifesto, a definição do job e os artefatos fiquem juntos. 
testNamedVarBundleJob/ 
  aidp_workbench.yaml 
  jobs/ 
    namedVariableJobDemo.job.json 
  artifacts/ 
    namedVarNotebookDemo.ipynb
Arquivo O Que Contém Valor Variável ou Resolvido
aidp_workbench.yaml Define a variável em padrões > variáveis e substituições de destino opcionais. Variável: job_param_value_default.
jobs/namedVariableJobDemo.job.json Usa a variável como o valor do parâmetro param_key do job. Referência: ${var.job_param_value_default}.
artifacts/namedVarNotebookDemo.ipynb Lê o parâmetro de job resolvido no runtime. O notebook lê param_key após a resolução.
Por exemplo, o manifesto do bundle pode definir as substituições padrão e de destino em 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"

A definição do job pode então usar o mesmo nome de variável em jobs/namedVariableJobDemo.job.json. A mesma sintaxe pode ser usada em definições de job, definições de computação, definições de tarefa e outros arquivos de definição YAML gerados que suportam variáveis de pacote:

"parameters": [ 
  { 
    "name": "param_key", 
    "value": "${var.job_param_value_default}" 
  } 
]
Destino da Implantação Resolução de variável Notebook Recebe
Nenhum destino correspondente Usa o padrão de aidp_workbench.yaml. param_key = cloud data governance
dev Utiliza a substituição do alvo de desenvolvimento. param_key = space tourism
qa Usa a substituição de destino de qa. param_key = data quality validation
produto Usa substituição de destino do produto. param_key = customer operations

Ordem de Resolução

Quando o .aidp/overrides.yaml fornece um valor de variável, o AI Data Platform usa esse valor temporário para a próxima implantação. Caso contrário, a Plataforma de Dados de IA resolve a variável do destino selecionado primeiro. Se nenhum ambiente de destino correspondente for encontrado ou o destino selecionado não substituir a variável, a Plataforma de Dados AI voltará a ser defaults > variables em aidp_workbench.yaml. Se nenhum valor estiver disponível para a variável referenciada, a implantação ou a execução do job poderá falhar antes que o valor de fallback do notebook seja usado.

Substituições Temporárias para a Próxima Implantação

As definições em aidp_workbench.yaml são suficientes para a promoção de pacote normal. Se um usuário precisar substituir uma variável temporariamente, crie .aidp/overrides.yaml na pasta do bundle e defina os valores das variáveis lá. A AI Data Platform usa esses valores durante a próxima implantação. 

.aidp/ 
  overrides.yaml
variables: 
  agent_topic_default: "tuesday"
Arquivo Exemplo de Valor Quando Usado
aidp_workbench.yaml defaults Oracle AI Data Platform Usado quando nenhum arquivo de destino ou substituição correspondente fornece a variável.
aidp_workbench.yaml target dev Espaço de Trabalho de Desenvolvimento AIDP Usado ao implantar no dev e nenhuma substituição temporária está presente.
.aidp/overrides.yaml terça-feira Usado como um valor temporário durante a próxima implantação.

Observação:

Use .aidp/overrides.yaml para valores de implantação temporários. Mantenha padrões duráveis e valores específicos do ambiente em aidp_workbench.yaml para que o pacote permaneça reproduzível por meio do Git.

Exemplo: Variável de Prompt do Agente

Para definições de texto ou ferramenta de prompt de fluxo do agente que suportam placeholders nomeados, use colchetes duplos ao redor do nome da variável.

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

Observação:

Como prática recomendada, você deve usar variáveis para valores que devem ser alterados entre as implantações. Evite incorporar valores específicos do ambiente diretamente em notebooks, jobs ou texto do fluxo do agente quando uma variável puder transportar o valor.

Exemplo: Workflow sem Computação

Você pode criar um pacote para um workflow que não crie automaticamente um cluster de computação como parte da implantação. Primeiro, crie uma variável em aidp_workbench.yaml: 

defaults:
 variables:
  job_compute_key: "select_compute"
Em seguida, na pasta jobs/, localize o arquivo de job <JobName>.job.json. Edite o arquivo de job e substitua o valor "clusterKey" pela nova variável criada:
"clusterKey" : "${var.job_compute_key}",

Variáveis Nomeadas em Ambientes (Visualização)

As variáveis de ambiente nomeadas permitem que o seu pacote Git mantenha os mesmos nomes de variáveis lógicas enquanto cada ambiente fornece seus próprios valores de tempo de implantação.

Use esse padrão quando uma região de desenvolvimento, uma região de QA e um ambiente de produção tiverem que implantar as mesmas definições de recursos com valores diferentes.

Exemplo de Workflow de Variável Nomeada

  1. Defina a variável uma vez em defaults > variables em aidp_workbench.yaml.
  2. Substitua o mesmo nome de variável em cada ambiente de destino.
  3. Implante com o destino cujos valores de variável correspondem ao espaço de trabalho de destino.
  4. Use padrões para valores de fallback seguros, não para segredos somente de produção ou identificadores específicos do espaço de trabalho.

Exemplo: Desv, CQ e Substituições de Produto

O exemplo a seguir usa os mesmos nomes de variáveis em três destinos. O job ainda faz referência às variáveis uma vez, enquanto a região de desenvolvimento, a região de QA e o ambiente de produção fornecem diferentes valores de tempo de implantação. 

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 deployment_region job_param_value_default Resultado do Tempo de Execução
dev us-ashburn-1 turismo espacial O job é executado com valores de região e parâmetro de desenvolvimento.
qa us-phoenix-1 validação da qualidade de dados O job é executado com valores de parâmetros e região de QA.
produto eu-frankfurt-1 operações do cliente O job é executado com valores de ambiente de produção.

Observação:

Se nenhum ambiente de destino correspondente for encontrado ou se um destino não definir uma substituição, o Workbench usará o valor de variável padrão configurado quando houver um. Se não houver uma substituição nem um padrão válido disponível, a execução da implantação ou do runtime poderá falhar, dependendo de onde a variável ausente for usada.

Variáveis de Pacote e Armazenamento de Credenciais (Visualização)

Você pode usar variáveis com o armazenamento de credenciais quando um job ou notebook agrupado precisar procurar um segredo no runtime.

Suas variáveis devem conter o nome da credencial e a chave do token. O valor do segredo real deve permanecer no armazenamento de credenciais de destino e não deve ser submetido a commit no Git.

Workflow de Exemplo: Usando Variáveis com Armazenamento de Credenciais

  1. Crie a credencial e a chave de token no armazenamento de credencial.
  2. Defina variáveis para o nome da credencial e a chave do token.
  3. Passar essas variáveis para o job ou notebook como parâmetros.
  4. No runtime, o notebook lê os parâmetros e chama a API de credencial para recuperar o segredo. Se o nome da credencial, a chave do token ou as permissões estiverem errados, o job poderá falhar com um erro de pesquisa de credencial.

Observação:

Não documente ou confirme valores de segredo em arquivos de pacote. A configuração do bundle deve fazer referência a nomes de credenciais, chaves de token e variáveis de destino; o armazenamento de credenciais permanece a origem do material secreto.

Exemplo: Nome da Credencial e Variáveis da Chave de Token

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}"

O notebook lê os valores de parâmetro e os usa para procurar o segredo no armazenamento de credenciais: 

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")
Ambiente Valor cred_key Valor token_key Requisito de Armazenamento de Credenciais
dev dev_credential_store_entry token_dev Crie dev_credential_store_entry com a chave dev_token.
qa qa_credential_store_entry qa_token Crie qa_credential_store_entry com a chave qa_token.
produto prod_credential_store_entry token_prod Crie prod_credential_store_entry com a chave prod_token.

Limpar um bundle (visualização)

Você pode expurgar um pacote implantado para remover os recursos do pacote do seu espaço de trabalho.

  1. Navegue até o pacote cujos recursos você deseja expurgar em seu espaço de trabalho.
  2. Clique na guia Implantação.
  3. Clique em Expurgar.
  4. Digite Expurgar no prompt. Clique em Expurgar.

Observação:

A limpeza de um pacote remove os recursos implantados primeiro. Se o pacote usar um caminho de publicação, o Oracle AI Data Platform removerá a pasta de artefatos gerenciados no caminho de publicação. Outros arquivos sob o caminho de publicação são preservados.

Comportamento de Expurgação para Artefatos Publicados (Visualização)

Quando você expurga um pacote implantado, o Oracle AI Data Platform remove os recursos implantados primeiro.

Após a remoção dos recursos, a AI Data Platform remove somente a pasta de artefatos gerenciados: <publish.path>/artifacts.

Outros arquivos ou pastas sob o caminho de publicação são preservados. Por exemplo, se o caminho de publicação for /Workspace/Shared/customer_churn_bundle, a expurgação removerá /Workspace/Shared/customer_churn_bundle/artifacts, mas preservará outros arquivos ou pastas em /Workspace/Shared/customer_churn_bundle.

Se a limpeza do artefato não puder ser concluída por causa de permissões ou acesso ao caminho, a exclusão do recurso ainda poderá ser concluída.

Pacotes Existentes e Caminhos de Publicação (Visualização)

Os bundles existentes que não têm um bloco de publicação continuam a usar o comportamento do artefato anterior até que sejam sincronizados ou atualizados manualmente.

Se você adicionar manualmente um bloco de publicação a um pacote existente, a implantação usará o caminho de publicação configurado. No entanto, os arquivos de descritor existentes não são alterados automaticamente durante a implantação. Se os descritores existentes ainda fizerem referência ao local do artefato anterior, esses recursos poderão continuar a usar o local anterior.

Se quiser que os recursos existentes usem o caminho de publicação, atualize as referências do descritor ou sincronize o pacote antes de adicionar manualmente um bloco de publicação personalizado. Por exemplo:

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

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

Quando a sincronização adiciona conteúdo de descritor novo ou atualizado para um pacote que já tem um bloco de publicação, as novas referências de descritor usam o formato de caminho de publicação.

Solucionando Problemas de Pacotes (Visualização)

Se você encontrar problemas ao criar e gerenciar pacotes Git, verifique a lista a seguir de problemas para possíveis soluções.

Sintoma Provável Causa Ação Recomendada
Criar bundle não está disponível ou o bundle não pode ser criado. O usuário não está em uma pasta Git ou não tem as permissões necessárias do espaço de trabalho. Navegue até uma pasta Git e confirme se o usuário pode criar recursos do espaço de trabalho.
A sincronização é concluída, mas outro ambiente não vê a atualização. Os arquivos de bundle atualizados não foram confirmados, enviados ou extraídos para a pasta Git de destino. Faça commit e push da pasta Git de origem e, em seguida, extraia o espaço de trabalho de destino antes de implantar.
A guia Implantação não mostra nenhum item implantado. O pacote ainda não foi implantado ou a implantação não foi concluída com sucesso. Clique em Implantar e aguarde a notificação de conclusão. Verifique os logs se a implantação falhar.
O job implantado falha com um erro de lookup de credencial. O nome da credencial de destino, a chave do token ou a permissão de acesso não correspondem à configuração do bundle. Crie a credencial no armazenamento de credenciais de destino ou atualize as variáveis de destino antes de reimplantar.
A implantação do fluxo do agente falha ou começa com a computação inativa. O ambiente de destino pode não ter definições compatíveis de computação, região, modelo ou dependência de IA. Revise as substituições de destino, o status de computação, a disponibilidade do modelo e os logs de implantação.
As alterações em um notebook de origem ou fluxo de agente não são refletidas após a implantação. O pacote foi implantado sem a primeira sincronização do recurso de origem atualizado. Execute a Sincronização no bundle, confirme e envie os arquivos de bundle atualizados, extraia-os no destino e implante novamente.