18 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.

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.

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.

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.

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

Recomendamos seguir um fluxo de trabalho de desenvolvimento, pacote, versão, extração, configuração, implantação e validação para pacotes Git na 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 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.

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.