34 Paquetes e integración y despliegue continuos (vista previa)

Los paquetes definen cómo los recursos del área de trabajo de Oracle AI Data Platform se empaquetan, versionan, comparten y despliegan en espacios de trabajo y entornos.

Puede crear grupos para puestos y agentes. Un paquete se crea en una carpeta de Git para que los archivos del paquete se puedan confirmar y transferir a un repositorio de Git. Los recursos que incluya en el paquete pueden proceder de cualquier ubicación del espacio de trabajo. Si los recursos seleccionados hacen referencia a archivos de soporte o dependencias, como blocs de notas, scripts o recursos informáticos, esas referencias se incluyen en el paquete para que los recursos se puedan desplegar en otro entorno sin volver a crear manualmente los mismos componentes.

Puede crear paquetes desde su espacio de trabajo y seleccionar los recursos de Oracle AI Data Platform Workbench que se incluirán en el momento de la creación. Los paquetes existentes se pueden modificar para agregar o eliminar recursos. La agrupación de recursos permite agrupar trabajos y agentes relacionados y desplegarlos en otros entornos con sus dependencias intactas.

Puede confirmar y transferir paquetes a su repositorio de Git a través de sus carpetas de Git. A continuación, los usuarios pueden extraer los paquetes a sus propios entornos y desplegarlos. Los cambios en los paquetes de archivos están disponibles para otros entornos después de que los cambios se confirmen y se transfieran al repositorio de Git. Cada vez que los usuarios extraen el paquete actualizado del repositorio de Git, reciben los últimos archivos de recursos confirmados.

Conceptos de paquete

Concepto Significado Acción del Usuario
Carpeta Git Carpeta de AI Data Platform conectada a un repositorio y una rama de Git. Los paquetes solo se pueden crear en carpetas Git. Cree o abra una carpeta de Git antes de crear un paquete.
Bundle Paquete desplegable que define los recursos seleccionados y sus dependencias. Cree el paquete desde el espacio de trabajo y, a continuación, seleccione recursos como trabajos o flujos de agentes.
Contenido del paquete Archivos generados que describen los recursos, las variables, la configuración de destino y los artefactos necesarios para el despliegue. Revise el contenido generado después de crear o sincronizar. Confirme y empuje el paquete a través de Git cuando esté listo.
Objetivo Configuración de un entorno o espacio de trabajo que se utiliza al desplegar el paquete fuera del entorno de origen. Proporcione valores que deben cambiar por entorno, como clave de espacio de trabajo, nombre de credencial, clave de token o valores por defecto de parámetros.
Elemento desplegado Recurso creado o actualizado por un despliegue de grupo en el espacio de trabajo de destino. Utilice el separador Despliegue para desplegar, revisar elementos desplegados, ejecutar trabajos y depurar recursos desplegados cuando sea necesario.
Sincronización Acción de grupo que refresca los paquetes de recursos y dependencias desde los últimos recursos de origen. Ejecute la sincronización después de cambiar los recursos agrupados y, a continuación, confirme los archivos del paquete refrescados en Git.

Antes de empezar

Compruebe esta lista para asegurarse de que tiene todo lo que necesita para empezar a utilizar paquetes de Git en su espacio de trabajo de AI Data Platform:
  • Cree credenciales de Git y una carpeta de Git que apunte al repositorio y la rama que se utilizan para los archivos del paquete.
  • Confirme que los recursos de origen están en el espacio de trabajo y que se guardan antes de crear o sincronizar el paquete.
  • Para el despliegue en varios entornos, confirme que el espacio de trabajo de destino tiene los permisos y la capacidad informática necesarios.
  • Para los trabajos o blocs de notas que utilizan secretos, cree las credenciales con nombre necesarias en el almacén de credenciales de destino. Los archivos de grupo deben hacer referencia a las credenciales por nombre o variable, no contener valores secretos.
  • Confirmar y transferir cambios de archivo de paquete después de crear o sincronizar un paquete para que otros entornos puedan extraer la última definición de paquete.

Rutas de publicación de paquetes

Los paquetes pueden publicar artefactos de tiempo de ejecución en una carpeta del espacio de trabajo que los usuarios pueden inspeccionar. Los artefactos de tiempo de ejecución incluyen archivos como blocs de notas, scripts, bibliotecas y archivos de flujo de agente que necesitan los recursos de paquetes desplegados. La carpeta donde se publican los artefactos se denomina ruta de publicación. Los artefactos se almacenan en una carpeta de artefactos dentro de la ruta de publicación.

Por ejemplo, si la ruta de publicación es: /Workspace/Shared/customer_churn_bundle, los artefactos de grupo se publican en: /Workspace/Shared/customer_churn_bundle/artifacts.

La ruta de publicación no es la fuente de la verdad para el paquete. Los archivos de origen del paquete permanecen en la carpeta del paquete y se deben confirmar en Git. Los archivos de la ruta de publicación son archivos de tiempo de ejecución que utilizan los recursos desplegados. Si edita manualmente los archivos en la ruta de publicación, esas ediciones no se vuelven a escribir en el origen del paquete. Un despliegue posterior puede sustituir los artefactos publicados por archivos del grupo.

Crear un paquete (vista previa)

Puede agrupar recursos de agente y trabajo de Oracle AI Data Platform para crear un paquete que se pueda desplegar en otra carpeta de Git.

  1. Navegue hasta el espacio de trabajo.
  2. Haga clic en Acciones y, a continuación, en Crear grupo.
  3. Proporcione un nombre y la descripción para su paquete.
  4. Haga clic en Examinar y seleccione la carpeta Git en el espacio de trabajo en el que desea crear el grupo.
  5. Seleccione los recursos que desea incluir en el paquete de las opciones enumeradas.
  6. Haga clic en Create.

    Note:

    Los paquetes se crean en carpetas Git. Si la ubicación seleccionada no está dentro de una carpeta de Git, no puede usar Git para mover los archivos del paquete generados a otro entorno.

    Note:

    Cuando se crea un paquete, AI Data Platform puede incluir una configuración de publicación predeterminada en el manifiesto del paquete. La configuración de publicación controla dónde se colocan los artefactos de tiempo de ejecución cuando se despliega el grupo.

Qué se genera después de la creación del paquete (vista previa)

Después de la creación del paquete, Oracle AI Data Platform escribe los archivos generados en la carpeta del paquete.

Los nombres de archivo exactos varían según el tipo de recurso, pero el grupo creado suele contener un manifiesto de grupo de nivel superior, definiciones de recursos, carpetas de artefactos y archivos de sustitución opcionales.

Elemento generado Descripción
aidp_workbench.yaml Manifiesto del paquete. Identifica el grupo, los recursos incluidos, las variables y las secciones de destino que se utilizan durante el despliegue.
.aidp/resource_origins.yaml Definiciones de recursos. Describir recursos como trabajos, tareas de bloc de notas, referencias de recursos informáticos o flujos de agentes.
.aidp/overrides.yaml Sustituir archivos o secciones de destino. Mantenga valores que difieran por entorno, como identificadores de espacio de trabajo, valores por defecto de parámetros, nombres de credenciales o claves de token.
.aidp/aidp.state.json Realiza un seguimiento de los recursos desplegados desde el grupo. Utilizado por futuras operaciones de despliegue y depuración.
jobs/ Descriptores de trabajo y dependencias de trabajo.
agentflows/ Descriptores de agente y dependencias de agente.
artifacts/ Carpetas de artefactos. Código copiado, blocs de notas y artefactos de archivos de soporte.

Configuración de ruta de publicación (vista previa)

Puede configurar la ruta de publicación de un paquete en el archivo de manifiesto del paquete, aidp_workbench.yaml.

Para configurar la ruta de publicación de un archivo de paquete, agregue un bloque de publicación en defaults en el archivo de manifiesto aidp_workbench.yaml, como en este ejemplo: 

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

En este ejemplo, cuando se despliega el grupo, los artefactos se publican en /Workspace/Shared/customer_churn_bundle/artifacts.

Tabla 34-1 Campos de configuración de la ruta de publicación

Campo Descripción
path Carpeta del espacio de trabajo utilizada como raíz de publicación. Los artefactos se almacenan en <path>/artifacts.
overwrite_publish_artifacts Indica si el despliegue puede sustituir los artefactos publicados existentes en la ruta de publicación configurada.

Configuración de ruta de publicación para diferentes entornos

Puede configurar diferentes rutas de publicación para diferentes destinos de despliegue, como en este ejemplo:

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

También puede utilizar .aidp/overrides.yaml para sustituir la ruta de publicación localmente: 

publish:
  path: "/Workspace/Users/me/customer_churn_bundle"
  overwrite_publish_artifacts: true
Cuando se configuran varias rutas de publicación, Oracle AI Data Platform resuelve la ruta de publicación en este orden:
  1. defaults.publish.path en aidp_workbench.yaml
  2. Ruta de publicación de destino coincidente
  3. Ruta de publicación .aidp/overrides.yaml

Cómo se publican los artefactos del paquete (vista previa)

Al desplegar un grupo, Oracle AI Data Platform copia los artefactos del grupo del origen del grupo en la ruta de publicación resuelta.

El diseño de artefacto por defecto es <publish.path>/artifacts. Por ejemplo: 

/Workspace/Shared/customer_churn_bundle/artifacts

Los archivos descriptor de grupo pueden hacer referencia a artefactos publicados mediante ${publish.path}/artifacts/.... Por ejemplo: 

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

Durante el despliegue, ${publish.path} se resuelve en la ruta de publicación configurada.

Desplegar un paquete (vista previa)

Puede desplegar paquetes desde una carpeta de Git para compartir recursos y dependencias entre espacios de trabajo y entornos.

  1. Vaya al paquete que desea desplegar en el espacio de trabajo.
  2. Haga clic en el separador Despliegue.
  3. Opcional: revise los valores objetivo y las sustituciones, si procede.
  4. Haga clic en Desplegar. Recibirá una notificación cuando se complete el despliegue.

    Note:

    En el primer despliegue, el separador Despliegue puede no mostrar ningún elemento desplegado hasta que el despliegue se realice correctamente. Después de un despliegue correcto, revise los recursos desplegados, ejecute trabajos o agentes según sea necesario y confirme la salida en tiempo de ejecución.

    Note:

    Durante el despliegue, los artefactos de grupo se publican en la ruta de publicación configurada antes de desplegar los recursos. Si no se configura ninguna ruta de publicación personalizada, Oracle AI Data Platform utiliza la ubicación de publicación por defecto para el paquete.

Cómo se despliegan los paquetes en rutas publicadas (vista previa)

Cuando un grupo tiene configurada una ruta de publicación, el despliegue realiza un juego fijo de acciones.

Las acciones que realiza Oracle AI Data Platform al desplegar un grupo con una ruta de publicación configurada se realizan en este orden:

  1. Valide la ruta de publicación.
  2. Publique artefactos de grupo en <publish.path>/artifacts.
  3. Desplegar recursos de grupo, como trabajos y flujos de agente, mediante las rutas de artefacto publicadas.
  4. Actualizar el estado del despliegue una vez finalizado el despliegue.

Se pueden realizar diferentes acciones si AI Data Platform encuentra problemas con la ruta de publicación:

  • Si la ruta de publicación no existe, AI Data Platform puede crearla durante el despliegue.
  • Si la ruta de publicación existe y está vacía, el despliegue puede utilizarla.
  • Si la ruta de publicación contiene artefactos gestionados por el mismo grupo, el despliegue puede actualizarlos.
  • Si la ruta de publicación contiene datos que no son propiedad del grupo, el despliegue puede fallar a menos que la sobrescritura esté activada.

Sincronizar un paquete (vista previa)

Puede sincronizar un grupo para actualizar los recursos y las dependencias del grupo con los cambios más recientes.

Sync utiliza los metadatos de origen registrados del grupo para volver a crear el grupo a partir de los trabajos de origen y los flujos de agente que se capturaron cuando se creó el grupo. Los metadatos de origen se almacenan en .aidp/resource_origins.yaml y deben coincidir con la instancia y el espacio de trabajo solicitados. La operación refresca el contenido del grupo controlado por origen al tiempo que conserva la identidad del grupo y los metadatos en tiempo de ejecución.

Durante la sincronización, el servicio almacena de forma provisional una instantánea de grupo refrescada en el directorio .aidp del grupo, compara descriptores existentes y almacenados en área temporal, conserva los alias de variables existentes y sustituye las referencias cuando es posible, fusiona las variables por defecto de manifiesto existentes y, a continuación, promueve los archivos controlados por origen refrescados de nuevo en la raíz del grupo.

Sync conserva los archivos de tiempo de ejecución de despliegue y específicos del entorno, como .aidp/overrides.yaml y .aidp/aidp.state.json. Estos archivos no se sustituyen por la instantánea de origen refrescada.

Debe sincronizar los paquetes cuando:
  • Se ha cambiado un bloc de notas, un trabajo, un flujo de agentes, una referencia de recursos informáticos, un parámetro o una dependencia en el espacio de trabajo de origen.
  • Un trabajo agrupado ahora apunta a un bloc de notas diferente o tiene parámetros de tarea actualizados.
  • Se ha cambiado una configuración de agente, un parámetro de petición de datos, un valor de modelo o una dependencia informática de AI.
  • Necesita que la carpeta Git contenga los últimos archivos de paquetes generados antes de transferirlos a otro entorno.
  1. Vaya al paquete que desea sincronizar en el espacio de trabajo.
  2. Haga clic en Acciones.
  3. Haga clic en Sincronizar. Recibirá una notificación cuando finalice la sincronización.

Flujo de trabajo de promoción recomendado para paquetes (vista previa)

Recomendamos seguir un flujo de trabajo de desarrollo, paquete, versión, extracción, configuración, despliegue y validación para paquetes en Oracle AI Data Platform.

Fase Acción Resultado
Desarrollo Cree o actualice blocs de notas, trabajos, configuración de recursos informáticos o flujos de agente en el espacio de trabajo de origen. Los recursos de origen contienen el comportamiento previsto más reciente.
Paquete Cree el paquete o ejecute la sincronización en un paquete existente. Los archivos de paquetes generados reflejan las dependencias y los recursos de origen actuales.
Version Revise, confirme y empuje la carpeta del paquete a través de la carpeta Git. El repositorio remoto contiene la definición del paquete desplegable.
Extraer En el espacio de trabajo de destino, extraiga los cambios de la carpeta Git. El espacio de trabajo de destino tiene los últimos archivos de grupo.
Configurar Defina valores específicos del destino, como clave de espacio de trabajo, valores por defecto de parámetros, nombre de credencial, clave de token o valores de tiempo de ejecución. El paquete está listo para el entorno de destino.
Despliegue Abra el separador Deployment del paquete y haga clic en Deploy. Workbench crea o actualiza los recursos desplegados.
Validar Ejecute trabajos desplegados o pruebe los flujos de agentes desplegados e inspeccione los logs o la salida. El entorno de destino se verifica antes de que continúe la promoción.

Variables de grupo (vista previa)

Utilice variables de grupo cuando un grupo necesite valores de tiempo de despliegue que puedan cambiar para cada entorno de destino sin editar la definición de recurso.

Para empezar a utilizar variables con paquetes, debe definir los nombres de variables en el archivo aidp_workbench.yaml del paquete con valores por defecto y, cuando sea necesario, sustituciones específicas del entorno. A continuación, haga referencia a esas variables a partir de los archivos de definición generados.

Flujo de trabajo de variable de ejemplo

  1. Defina los nombres de variables en defaults > variables en aidp_workbench.yaml.
  2. Opcionalmente, defina los valores específicos del entorno en targets > <environment> > variables en el mismo archivo aidp_workbench.yaml.
  3. Utilice sustituciones de destino para definir valores de tiempo de despliegue como una región de desarrollo, una región de QA, una región de producción, un nombre de esquema, un nombre de credencial, una clave de token o un valor por defecto de parámetro.
  4. Cuando no se encuentra ningún entorno de destino coincidente, Oracle AI Data Platform utiliza el valor de variable por defecto de helpp_workbench.yaml.
  5. Utilice la variable en cualquier archivo de definición generado, como una definición de trabajo, una definición de cálculo, una definición de tarea u otro archivo de definición YAML.
  6. Haga referencia a la variable con ${var.<<variable_name>>>}, sustituyendo <<variable_name>> por el nombre de variable real definido en helpp_workbench.yaml.
  7. Utilice la sintaxis de marcador de posición específica del recurso en lugares como peticiones de datos de agente o definiciones de herramientas cuando la interfaz de usuario espera un marcador de posición con nombre.
  8. Para los cambios temporales de solo despliegue, cree .aidp/overrides.yaml y defina allí los valores de las variables.

Sintaxis de las variables del paquete

Las definiciones de variables se deben escribir en aidp_workbench.yaml. Otros archivos de definición de grupo solo deben hacer referencia al nombre de variable.

Definición Sintaxis Ejemplo
Definición de variable en aidp_workbench.yaml 
defaults: 
  variables: 
    <<variable_name>>: <<default_value>> 
defaults: 
  variables: 
    deployment_region: "us-ashburn-1"
Sustitución específica del destino enaidp_workbench.yaml 
targets: 
  <<target_name>>: 
    variables: 
      <<variable_name>>: <<target_value>> 
targets: 
  qa: 

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

    variables: 
      deployment_region: "us-phoenix-1"
Referencia de variable en un archivo de definición ${var.<<variable_name>>} value: "${var.deployment_region}"
Marcador de posición con nombre en un campo de herramienta o petición de datos de agente {{variable_name}} Generate a summary about {{topic}}.

Ejemplo: variable de parámetro de trabajo

El siguiente ejemplo define una variable y la transfiere a un parámetro de trabajo. El recurso puede permanecer sin cambios mientras el valor de la variable cambia en la configuración del paquete.
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}"

Una tarea de bloc de notas puede leer el valor resuelto mediante el nombre de parámetro que utiliza el trabajo:

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

Ejemplo: aidp_workbench.yaml Definición de variable

En este ejemplo se define la variable agent_topic_default en aidp_workbench.yaml. El valor por defecto se aplica cuando no se encuentra ningún entorno de destino coincidente o cuando no hay ningún entorno seleccionado o sustitución temporal que proporcione la variable. Cada destino puede sustituir el mismo nombre de variable para ese espacio de trabajo.
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"

Cualquier archivo de definición de grupo que admita variables de grupo puede hacer referencia al mismo nombre de variable. Por ejemplo:

tasks/agentTopic.task.yaml 

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

Ejemplo: nombres de archivos y resolución

En un grupo generado, la definición de variable y el recurso que utiliza la variable pueden estar en archivos diferentes. Al promocionar o copiar el ejemplo a través de Git, incluya toda la carpeta del paquete para que el manifiesto, la definición del trabajo y los artefactos permanezcan juntos. 
testNamedVarBundleJob/ 
  aidp_workbench.yaml 
  jobs/ 
    namedVariableJobDemo.job.json 
  artifacts/ 
    namedVarNotebookDemo.ipynb
Archivo Lo que contiene Valor variable o resuelto
aidp_workbench.yaml Define la variable en default > variables y las sustituciones de destino opcionales. Variable: job_param_value_default.
jobs/namedVariableJobDemo.job.json Utiliza la variable como valor para el parámetro de trabajo param_key. Referencia: ${var.job_param_value_default}.
artifacts/namedVarNotebookDemo.ipynb Lee el parámetro de trabajo resuelto en tiempo de ejecución. El bloc de notas lee param_key después de la resolución.
Por ejemplo, el manifiesto del paquete puede definir el valor predeterminado y las sustituciones de destino en 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 continuación, la definición de trabajo puede utilizar el mismo nombre de variable en jobs/namedVariableJobDemo.job.json. La misma sintaxis se puede utilizar en definiciones de trabajos, definiciones de recursos informáticos, definiciones de tareas y otros archivos de definición de YAML generados que soportan variables de grupo:

"parameters": [ 
  { 
    "name": "param_key", 
    "value": "${var.job_param_value_default}" 
  } 
]
Destino de Despliegue Resolución de variables Recibe el bloc de notas
No hay ningún destino coincidente Utiliza el valor por defecto de helpp_workbench.yaml. param_key = cloud data governance
desviación Utiliza la sustitución de destino de desarrollo. param_key = space tourism
QA Utiliza la sustitución de destino de control de calidad. param_key = data quality validation
producto Utiliza la sustitución de destino de producto. param_key = customer operations

Orden de resolución

Cuando .aidp/overrides.yaml proporciona un valor de variable, AI Data Platform utiliza ese valor temporal para el siguiente despliegue. De lo contrario, AI Data Platform resuelve la variable del destino seleccionado en primer lugar. Si no se encuentra ningún entorno de destino coincidente o el destino seleccionado no sustituye la variable, AI Data Platform vuelve a defaults > variables en aidp_workbench.yaml. Si no hay ningún valor disponible para la variable a la que se hace referencia, el despliegue o la ejecución del trabajo pueden fallar antes de utilizar el valor de reserva de bloc de notas.

Sustituciones temporales para el siguiente despliegue

Las definiciones de helpp_workbench.yaml son suficientes para la promoción normal de paquetes. Si un usuario necesita sustituir una variable temporalmente, cree .aidp/overrides.yaml en la carpeta del paquete y defina los valores de la variable allí. AI Data Platform utiliza esos valores durante el siguiente despliegue. 

.aidp/ 
  overrides.yaml
variables: 
  agent_topic_default: "tuesday"
Archivo Valor de ejemplo Cuando se utiliza
aidp_workbench.yaml defaults Oracle AI Data Platform Se utiliza cuando no hay ningún archivo de sustitución o destino coincidente que proporcione la variable.
aidp_workbench.yaml target dev Espacio de trabajo de desarrollo de AIDP Se utiliza cuando se despliega para desarrollo y no hay ninguna sustitución temporal.
.aidp/overrides.yaml martes Se utiliza como valor temporal durante el siguiente despliegue.

Note:

Utilice .aidp/overrides.yaml para valores de despliegue temporales. Mantenga los valores por defecto duraderos y los valores específicos del entorno en aidp_workbench.yaml para que el paquete se pueda reproducir mediante Git.

Ejemplo: variable de petición de datos de agente

Para las definiciones de herramientas o texto de petición de datos de flujo de agente que admiten marcadores de posición con nombre, utilice llaves dobles alrededor del nombre de la variable.

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

Note:

Como mejor práctica, debe utilizar variables para los valores que se espera que cambien en los despliegues. Evite embeber valores específicos del entorno directamente en blocs de notas, trabajos o texto de flujo de agente cuando una variable pueda incluir el valor en su lugar.

Ejemplo: flujo de trabajo sin recursos informáticos

Puede crear un paquete para un flujo de trabajo que no cree automáticamente un cluster de recursos informáticos como parte del despliegue. En primer lugar, cree una variable en aidp_workbench.yaml: 

defaults:
 variables:
  job_compute_key: "select_compute"
A continuación, en la carpeta jobs/, busque el archivo de trabajo <JobName>.job.json. Edite el archivo de trabajo para sustituir el valor "clusterKey" por la nueva variable creada:
"clusterKey" : "${var.job_compute_key}",

Variables con nombre en entornos (vista previa)

Las variables de entorno con nombre permiten que el grupo de Git mantenga los mismos nombres de variables lógicas, mientras que cada entorno proporciona sus propios valores de tiempo de despliegue.

Utilice este patrón cuando una región de desarrollo, una región de control de calidad y un entorno de producción deban desplegar las mismas definiciones de recursos con valores diferentes.

Ejemplo de flujo de trabajo de variable con nombre

  1. Defina la variable una vez en defaults > variables en aidp_workbench.yaml.
  2. Sustituya el mismo nombre de variable en cada entorno de destino.
  3. Desplegar con el destino cuyos valores de variable coincidan con el espacio de trabajo de destino.
  4. Utilice los valores por defecto para valores de reserva seguros, no para secretos solo de producción ni identificadores específicos del espacio de trabajo.

Ejemplo: sustituciones de desarrollo, control de calidad y productos

En el siguiente ejemplo, se utilizan los mismos nombres de variable en tres destinos. El trabajo sigue haciendo referencia a las variables una vez, mientras que la región de desarrollo, la región de control de calidad y el entorno de producción proporcionan diferentes valores de tiempo de despliegue. 

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"
Objetivo deployment_region job_param_value_default Resultado de tiempo de ejecución
desviación us-ashburn-1 turismo espacial El trabajo se ejecuta con valores de región y parámetro de desarrollo.
QA us-phoenix-1 validación de calidad de datos El trabajo se ejecuta con valores de región y parámetro de QA.
producto eu-frankfurt-1 operaciones de clientes El trabajo se ejecuta con valores de entorno de producción.

Note:

Si no se encuentra ningún entorno de destino coincidente o si un destino no define una sustitución, el área de trabajo utiliza el valor de variable por defecto configurado cuando existe uno. Si no hay disponible una sustitución ni un valor por defecto válido, el despliegue o la ejecución en tiempo de ejecución pueden fallar según dónde se utilice la variable que falta.

Variables de grupo y almacén de credenciales (vista previa)

Puede utilizar variables con el almacén de credenciales cuando un trabajo o bloc de notas agrupados necesita buscar un secreto en tiempo de ejecución.

Las variables deben llevar el nombre de credencial y la clave de token. El valor del secreto real debe permanecer en el almacén de credenciales de destino y no se debe confirmar en Git.

Ejemplo de flujo de trabajo: uso de variables con almacén de credenciales

  1. Cree la clave de credencial y de token en el almacén.
  2. Defina variables para el nombre de credencial y la clave de token.
  3. Transfiera esas variables al trabajo o al bloc de notas como parámetros.
  4. En tiempo de ejecución, el bloc de notas lee los parámetros y llama a la API de credenciales para recuperar el secreto. Si el nombre de credencial, la clave de token o los permisos son incorrectos, el trabajo puede fallar con un error de consulta de credenciales.

Note:

No documente ni confirme valores secretos en archivos de grupo. La configuración del paquete debe hacer referencia a nombres de credenciales, claves de token y variables de destino; el almacén de credenciales sigue siendo el origen del material secreto.

Ejemplo: Variables de clave de token y nombre de credencial

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

El bloc de notas lee los valores de parámetros y los utiliza para buscar el secreto del almacén de credenciales: 

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")
Entorno Valor cred_key valor token_key Requisito de Almacén de Credenciales
desviación dev_credential_store_entry dev_token Crear dev_credential_store_entry con la clave dev_token.
QA qa_credential_store_entry qa_token Cree qa_credential_store_entry con la clave qa_token.
producto prod_credential_store_entry prod_token Cree prod_credential_store_entry con la clave prod_token.

Depurar un paquete (vista previa)

Puede depurar un paquete desplegado para eliminar los recursos del paquete de su espacio de trabajo.

  1. Desplácese al grupo para el que desea depurar recursos en el espacio de trabajo.
  2. Haga clic en el separador Despliegue.
  3. Haga clic en Depurar.
  4. Introduzca Depurar en la petición de datos. Haga clic en Depurar.

Note:

Al depurar un grupo, se eliminan primero los recursos desplegados. Si el grupo utiliza una ruta de publicación, Oracle AI Data Platform elimina la carpeta de artefactos gestionados en la ruta de publicación. Se conservan otros archivos de la ruta de publicación.

Comportamiento de depuración de artefactos publicados (vista previa)

Al depurar un paquete desplegado, Oracle AI Data Platform elimina primero los recursos desplegados.

Después de eliminar los recursos, AI Data Platform elimina solo la carpeta de artefacto gestionada: <publish.path>/artifacts.

Se conservan otros archivos o carpetas de la ruta de publicación. Por ejemplo, si la ruta de publicación es /Workspace/Shared/customer_churn_bundle, la depuración elimina /Workspace/Shared/customer_churn_bundle/artifacts, pero conserva otros archivos o carpetas en /Workspace/Shared/customer_churn_bundle.

Si la limpieza del artefacto no se puede completar debido a permisos o acceso a la ruta de acceso, la supresión del recurso aún se puede completar.

Paquetes y rutas de publicación existentes (vista previa)

Los paquetes existentes que no tienen un bloque de publicación siguen utilizando el comportamiento del artefacto anterior hasta que se sincronizan o actualizan manualmente.

Si agrega manualmente un bloque de publicación a un paquete existente, el despliegue utiliza la ruta de publicación configurada. Sin embargo, los archivos descriptor existentes no se cambian automáticamente durante el despliegue. Si los descriptores existentes siguen haciendo referencia a la ubicación del artefacto anterior, es posible que esos recursos sigan utilizando la ubicación anterior.

Si desea que los recursos existentes utilicen la ruta de publicación, actualice las referencias de descriptor o sincronice el paquete antes de agregar manualmente un bloque de publicación personalizado. Por ejemplo:

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

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

Cuando la sincronización agrega contenido de descriptor nuevo o refrescado para un grupo que ya tiene un bloque de publicación, las referencias de descriptor nuevo utilizan el formato de ruta de publicación.

Solución de problemas de paquetes (vista previa)

Si tiene problemas al crear y gestionar paquetes de Git, consulte la siguiente lista de problemas para encontrar posibles soluciones.

Síntoma Causa probable Acción Recomendada
La creación de paquete no está disponible o no se puede crear el paquete. El usuario no está en una carpeta de Git o carece de los permisos de espacio de trabajo necesarios. Vaya a una carpeta de Git y confirme que el usuario puede crear recursos del espacio de trabajo.
La sincronización finaliza, pero otro entorno no ve la actualización. Los archivos del paquete refrescados no se han confirmado, transferido ni extraído en la carpeta Git de destino. Confirme y transfiera desde la carpeta Git de origen y, a continuación, extraiga el espacio de trabajo de destino antes del despliegue.
El separador Despliegue no muestra ningún elemento desplegado. El paquete aún no se ha desplegado o el despliegue no se ha completado correctamente. Haga clic en Deploy y espere a la notificación de finalización. Revise los logs si falla el despliegue.
El trabajo desplegado falla con un error de consulta de credenciales. El nombre de credencial de destino, la clave de token o el permiso de acceso no coinciden con la configuración del grupo. Cree la credencial en el almacén de credenciales de destino o actualice las variables de destino antes de volver a desplegar.
El despliegue del flujo de agente falla o se inicia con recursos informáticos inactivos. Es posible que el entorno de destino no tenga una configuración de recursos informáticos, región, modelo o dependencia de AI compatible. Revise las sustituciones de destino, el estado de los recursos informáticos, la disponibilidad del modelo y los logs de despliegue.
Los cambios en un bloc de notas de origen o flujo de agente no se reflejan después del despliegue. El paquete se desplegó sin sincronizar primero el recurso de origen actualizado. Ejecute Sync en el paquete, confirme y transfiera los archivos del paquete refrescados, tire de ellos en el destino y, a continuación, vuelva a desplegar.