Importa, administra y ejecuta extensiones

Las extensiones son conexiones a APIs externas. Pueden procesar datos en tiempo real y conectarse a APIs externas para realizar acciones en el mundo real. Vertex AI proporciona un servicio de extensiones que puede importar, administrar y ejecutar extensiones.

Este servicio de extensión se puede vincular a una aplicación que procesa consultas de usuarios y se comunica con un LLM. El servicio de extensión puede proporcionar a la aplicación un conjunto de extensiones y las operaciones que estas pueden realizar. Cada vez que la aplicación recibe una consulta de usuario, proporciona esta información al LLM. Si el modelo determina que debe delegar el procesamiento de consultas a una extensión, proporciona una llamada de extensión solicitada y los valores de parámetros asociados. La aplicación retransmite esta solicitud al servicio de extensión, que luego ejecuta la extensión. Por último, el servicio de extensión envía el resultado de esta operación a la aplicación, que luego lo retransmite al modelo.

En este documento, se muestra la funcionalidad clave del servicio de extensión de Vertex AI:

Para obtener información sobre cómo importar y ejecutar una extensión proporcionada por Google, consulta los siguientes vínculos:

Crea e importa extensiones

En este documento, se supone que ya tienes un servicio de API en ejecución que puede respaldar una extensión. Para crear una extensión, debes definir su interfaz con una API externa en un archivo de especificación de API. Debes subir este archivo de especificación a un bucket de Cloud Storage o convertirlo en una cadena. Luego, debes definir un manifiesto de extensión, incluir el archivo de especificación y enviar una solicitud de registro al servicio de extensión.

Crea un archivo de especificación de API

Cualquiera puede crear una extensión a través de archivos que definen y describen los extremos de la API de las extensiones. Los extremos de la API pueden ser públicos o privados, y alojados en cualquier nube o de forma local.

Un archivo de especificación de API describe la interfaz de un servicio de API. Debes proporcionar un archivo de especificación de la API en formato YAML que sea compatible con OpenAPI 3.0. En este archivo de especificación, se debe definir lo siguiente:

  • Un objeto de servidor. Este objeto debe definir una URL de servidor de API. El servicio de extensión de Vertex AI no admite varios servidores.

    servers:
  - url: API_SERVICE_URL

  • Un objeto de ruta de acceso. Este objeto debe describir las diversas operaciones que proporciona el servicio de API y los parámetros de entrada que corresponden a cada operación. Cada operación debe tener un identificador único y una respuesta.

    paths:
  ...
    get:
      operationId: API_SERVICE_OPERATION_ID
      ...
      parameters:
        - name: API_SERVICE_INPUT_VAR
          ...
      responses:
      ...

  • Un objeto de componentes. Este objeto es opcional. Puedes usar el objeto de componentes para definir objetos reutilizables. Por ejemplo, puedes usar el objeto de componentes para proporcionar una definición de los esquemas de objetos que se definen en el objeto de rutas de acceso. También puedes usar el objeto de componentes para describir los parámetros de salida del servicio de API.

    components:
  schemas:
    Result:
      ...
      properties:
        API_SERVICE_OUTPUT_VAR:
        ...

Para obtener más información sobre OpenAPI, consulta Especificación de OpenAPI.

El siguiente ejemplo es un archivo de especificación de una API para un servicio de API que dice “hello” en el lenguaje solicitado:

  openapi: "3.0.0"
  info:
    version: 1.0.0
    title: Hello Extension
    description: Learn to build Vertex AI extensions
  servers:
    - url: [API_SERVICE_URL]
  paths:
    /hello:
      get:
        operationId: "say_hello"
        description: "Say hello in prompted language."
        parameters:
          - name: "apiServicePrompt"
            in: query
            description: "Language"
            required: true
            schema:
              type: string
        responses:
          '200':
            description: Successful operation.
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/Result"
  components:
    schemas:
      Result:
        description: "Hello in the requested language."
        properties:
          apiServiceOutput:
            type: string

Sube el archivo de especificación

Puedes subir el archivo de especificación a un bucket de Cloud Storage o convertirlo en una cadenas.

Si subes el archivo de especificación a un bucket de Cloud Storage, otorga a la cuenta de servicio Vertex AI Extension Service Agent (service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com) el rol de visualizador de objetos de almacenamiento. Para aprender a enumerar los buckets de tu proyecto, consulta Enumera buckets. Para obtener información sobre cómo copiar un objeto a un bucket de Cloud Storage, consulta Copia objetos, cambia su nombre y muévelos.

Define una solicitud de importación de extensión

Después de crear un archivo de especificación de API, puedes definir una solicitud de importación de extensión en un archivo JSON. Una solicitud de importación de extensión debe contener una referencia a tu archivo de especificación de API (apiSpec) y la configuración de autenticación (authConfig). Para conectar la extensión a un modelo de lenguaje grande (LLM) a fin de ver cómo funciona, incluye el parámetro opcional toolUseExamples. Si solo deseas ejecutar la extensión, no incluyas el parámetro toolUseExamples.

Una solicitud de importación de extensión tiene el siguiente formato:

{
  "displayName":  "DISPLAY_NAME_HUMAN",
  "description": "DESCRIPTION_HUMAN",
  "manifest": {
    "name": "EXTENSION_NAME_LLM",
    "description": "DESCRIPTION_LLM",
    "apiSpec": { ... },
    "authConfig": { ... },
  }
  "toolUseExamples": [ ... ],
}
  • DISPLAY_NAME_HUMAN: El nombre de la extensión que se muestra a los usuarios.
  • DESCRIPTION_HUMAN: Es la descripción de la extensión que se muestra a los usuarios.
  • EXTENSION_NAME_LLM: El nombre de la extensión que usa el LLL para razonar.
  • DESCRIPTION_LLM: El nombre de la extensión que usa el LLM para razonar. Debes proporcionar una descripción significativa e informativa.

Haz referencia al archivo de especificación de la API

La solicitud de importación de extensión debe contener una referencia a tu archivo de especificación de API. Puedes proporcionar el archivo de especificación de dos maneras:

  • Usa openApiGcsUri para pasar el URI de Cloud Storage del archivo YAML.

    "apiSpec": {
  "openApiGcsUri": "gs://BUCKET_NAME/SPECIFICATION_FILE_NAME.yaml"
},
    • BUCKET_NAME: El nombre del bucket de Cloud Storage que almacena el archivo de especificación.
    • SPECIFICATION_FILE_NAME: El nombre del archivo de especificación de la API.

  • Usa openApiYaml para pasar el archivo YAML como una cadena.

Configuración de autenticación

Las extensiones pueden ser públicas, disponibles para cualquier usuario, o privadas, solo disponibles para usuarios autorizados dentro de una o más organizaciones.

Una solicitud de importación de extensión debe contener una configuración de autenticación. Puedes elegir entre los siguientes métodos de autenticación:

  • NO_AUTH: Sin autenticación
  • API_KEY_AUTH: Autenticación de la clave de API
  • HTTP_BASIC_AUTH: Autenticación básica HTTP
  • OAUTH: Autenticación de OAuth
  • OIDC_AUTH: Autenticación de OIDC

Para obtener más información sobre las configuraciones de autenticación, consulta Especifica una configuración de autenticación.

Ejemplos que demuestran cómo funciona la extensión

Para obtener mejores resultados, una solicitud de importación de extensión debe contener ejemplos que demuestran cómo funciona la extensión. Usa el parámetro toolUseExamples para proporcionar estos ejemplos.

En el siguiente código, se muestra el formato de toolUseExamples para un solo ejemplo, con un solo parámetro de entrada y un solo parámetro de salida. En este ejemplo, los parámetros de solicitud y respuesta son del tipo string.

"toolUseExamples": [
  {
      "extensionOperation": {
        "operationId": "API_SERVICE_OPERATION_ID",
      },
      "displayName": "EXAMPLE_DISPLAY_NAME",
      "query": "EXAMPLE_QUERY",
      "requestParams": {
        "fields": [
          {
            "key": "API_SERVICE_INPUT_VAR",
            "value": {
              "string_value": "EXAMPLE_INPUT",
            }
          }
        ]
      },
      "responseParams": {
        "fields": [
          {
            "key": "API_SERVICE_OUTPUT_VAR",
            "value": {
              "string_value": "EXAMPLE_OUTPUT",
            },
          }
        ],
      },
      "responseSummary": "EXAMPLE_SUMMARY"
    }
],
  • query: Un ejemplo de una consulta que puede aprovechar esta extensión. Usa EXAMPLE_QUERY para proporcionar el texto de la consulta.
  • extensionOperation: Una operación de extensión adecuada para responder a query. Usa API_SERVICE_OPERATION_ID para proporcionar el ID de una operación de extensión definida en el archivo de especificación de la API.
  • displayName: Un nombre visible para el ejemplo. Usa EXAMPLE_DISPLAY_NAME para proporcionar una descripción breve.
  • requestParams: Son los parámetros de solicitud necesarios para los extensionOperation y los valores de ejemplo, en formato de clave-valor. Usa API_SERVICE_INPUT_VAR para proporcionar un parámetro de entrada que se defina en el archivo de especificación de la API y que corresponda a API_SERVICE_OPERATION_ID. Usa EXAMPLE_INPUT para proporcionar un ejemplo de un valor de entrada que corresponda a EXAMPLE_QUERY.
  • responseParams: son los parámetros de respuesta de extensionOperation y los valores de ejemplo en formato de clave-valor. Usa API_SERVICE_OUTPUT_VAR para proporcionar un parámetro de salida definido en el archivo de especificación de la API y que corresponda al servicio de la API. Usa EXAMPLE_OUTPUT para proporcionar un ejemplo de un valor de salida que corresponda con EXAMPLE_INPUT.
  • responseSummary: Es un ejemplo de un resumen que la aplicación podría proporcionar en respuesta a query. Usa EXAMPLE_SUMMARY para proporcionar el texto del resumen.

El siguiente es un ejemplo de toolUseExamples para un servicio de API que dice “hello” en el lenguaje solicitado:

"toolUseExamples": [
  {
      "extensionOperation": {
        "operationId": "say_hello",
      },
      "displayName": "Say hello in the requested language",
      "query": "Say hello in French",
      "requestParams": {
        "fields": [
          {
            "key": "apiServicePrompt",
            "value": {
              "string_value": "French",
            }
          }
        ]
      },
      "responseParams": {
        "fields": [
          {
            "key": "apiServiceOutput",
            "value": {
              "string_value": "bonjour",
            },
          }
        ],
      },
      "responseSummary": "Bonjour"
    }
],

Especifica una configuración de autenticación

Debes especificar una configuración de autenticación cuando definas una solicitud de importación de extensión.

Si la extensión no requiere autenticación, establece la variable authType en NO_AUTH:

"authConfig": {
  "authType": "NO_AUTH"
}

Si tu extensión requiere autenticación, debes establecer el tipo de autenticación en la variable authType y proporcionar una configuración de autenticación. Puedes elegir entre los siguientes métodos de autenticación:

Autenticación de la clave de API

Para ser compatible con la autenticación de clave de API, Vertex AI se integra en SecretManager para el almacenamiento y el acceso a los secretos. La plataforma de extensiones de Vertex AI no almacena los datos del Secret directamente. Tienes la responsabilidad de administrar el ciclo de vida del recurso SecretManager.

Especifica authConfig de la siguiente manera:

"authConfig": {
  "authType": "API_KEY_AUTH",
  "apiKeyConfig": {
    "name": "API_KEY_CONFIG_NAME",
    "apiKeySecret": "API_KEY_SECRET",
    "httpElementLocation": "HTTP_ELEMENT_LOCATION",
  },
}
  • API_KEY_CONFIG_NAME: El nombre de la clave de API. Por ejemplo, en la solicitud a la API https://example.com/act?api_key=<API KEY>, API_KEY_CONFIG_NAME corresponde a api_key.
  • API_KEY_SECRET: Es el recurso de la versión del secreto SecretManager que almacena la clave. Este parámetro tiene el siguiente formato: projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION.

  • HTTP_ELEMENT_LOCATION: La ubicación de la clave de API en la solicitud HTTP. Los valores posibles son:

    • HTTP_IN_QUERY
    • HTTP_IN_HEADER
    • HTTP_IN_PATH
    • HTTP_IN_BODY
    • HTTP_IN_COOKIE

    Para obtener más información, consulta Describe parámetros.

Autenticación básica HTTP

A fin de ser compatible con la autenticación básica HTTP, Vertex AI se integra en SecretManager para el almacenamiento y el acceso a los secretos. La plataforma de extensiones de Vertex AI no almacena los datos del Secret directamente. Debes administrar el ciclo de vida de tu recurso SecretManager por tu cuenta.

Especifica authConfig de la siguiente manera:

"authConfig": {
  "authType": "HTTP_BASIC_AUTH",
  "httpBasicAuthConfig": {
    "credentialSecret": "CREDENTIAL_SECRET"
  },
}
  • CREDENTIAL_SECRET: recurso de versión del secreto SecretManager que almacena la credencial codificada en base64. Este parámetro tiene el siguiente formato: projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION.

Autenticación de OAuth

Vertex AI admite dos métodos de autenticación de OAuth: el token de acceso y la cuenta de servicio.

Token de acceso

Especifica authConfig de la siguiente manera:

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {}
}

Deja el campo oauthConfig en blanco cuando importes la extensión. Si decides ejecutar una extensión registrada, debes proporcionar un token de acceso en el campo oauthConfig de la solicitud de verificación. Para obtener más información, consulta Ejecuta la extensión.

Cuenta de servicio

Especifica authConfig de la siguiente manera:

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
  • SERVICE_ACCOUNT_NAME: Vertex AI usa esta cuenta de servicio para generar tokens de acceso.

Realiza los siguientes pasos para permitir que Vertex AI Extension Service Agent obtenga tokens de acceso de SERVICE_ACCOUNT_NAME.

  1. Ir a la página IAM.

    Ir a IAM

  2. Selecciona la pestaña Cuentas de servicio.

  3. Haz clic en tu cuenta de servicio. El valor de SERVICE_ACCOUNT_NAME en authConfig debe corresponder con el nombre de tu cuenta de servicio.

  4. Haz clic en la pestaña Permisos.

  5. Haz clic en Otorgar acceso.

  6. En la sección Agregar principales, en el campo Principales nuevas, ingresa service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com. Esta principal corresponde a la cuenta de servicio Vertex AI Extension Service Agent.

  7. En la sección Asignar roles, busca y selecciona el rol Service Account Token Creator. Este rol incluye el permiso iam.serviceAccounts.getAccessToken.

  8. Haz clic en el botón Save.

Autenticación de OIDC

Vertex AI admite dos métodos de autenticación de OIDC: token de ID y cuenta de servicio.

Token de ID

Especifica authConfig de la siguiente manera:

"authConfig": {
  "authType": "OIDC_AUTH",
  "oidcConfig": {}
}

Deja el campo oidcConfig en blanco cuando importes la extensión. Si decides ejecutar una extensión registrada, debes proporcionar un token de ID en el campo oidcConfig de la solicitud de verificación. Para obtener más información, consulta Ejecuta la extensión.

Cuenta de servicio

Especifica authConfig de la siguiente manera:

"authConfig": {
  "authType": "OIDC_AUTH",
  "oidcConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
  • SERVICE_ACCOUNT_NAME: Vertex AI usa esta cuenta de servicio para generar tokens de OpenID Connect (OIDC). Vertex AI establece el público del token en API_SERVICE_URL, como se define en el archivo de especificación de la API.

Realiza los siguientes pasos para permitir que Vertex AI Extension Service Agent obtenga tokens de acceso de SERVICE_ACCOUNT_NAME.

  1. Ir a la página IAM.

    Ir a IAM

  2. Selecciona la pestaña Cuentas de servicio.

  3. Haz clic en tu cuenta de servicio. El valor de SERVICE_ACCOUNT_NAME en authConfig debe corresponder con el nombre de tu cuenta de servicio.

  4. Haz clic en la pestaña Permisos.

  5. Haz clic en Otorgar acceso.

  6. En la sección Agregar principales, en el campo Principales nuevas, ingresa service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com. Esta principal corresponde a la cuenta de servicio Vertex AI Extension Service Agent.

  7. En la sección Asignar roles, busca y selecciona el rol Service Account Token Creator. Esta función incluye el permiso iam.serviceAccounts.getOpenIdToken.

  8. Haz clic en el botón Save.

Importa la extensión con Vertex AI

Después de definir una solicitud de importación de extensión, puedes importarla con Vertex AI.

  1. Configura las siguientes variables de shell:

    ENDPOINT="LOCATION-aiplatform.googleapis.com"
URL="https://${ENDPOINT}/v1beta1/projects/PROJECT_ID/locations/LOCATION"
    • PROJECT_ID: Tu proyecto.
    • LOCATION: Una región que elijas. Si tienes dudas con la región, elige us-central1.

  2. Ejecuta el siguiente comando curl para enviar la solicitud de importación:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @IMPORT_REQUEST.json "${URL}/extensions:import"

    La respuesta tiene el siguiente formato:

    {
  "name": "projects/[PROJECT_NUMBER]/locations/[LOCATION]/extensions/[EXTENSION_ID]/operations/[IMPORT_OPERATION_ID]",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.ImportExtensionOperationMetadata",
    "genericMetadata": {
      "createTime": "[CREATE_TIME]",
      "updateTime": "[UPDATE_TIME]"
    }
  }
}

  3. Configura las variables de shell según el resultado de la solicitud de importación:

    EXTENSION_ID=EXTENSION_ID
IMPORT_OPERATION_ID=IMPORT_OPERATION_ID

  4. Para verificar el estado de la importación, ejecuta el siguiente comando de curl:

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
"${URL}/operations/${IMPORT_OPERATION_ID}"

Administrar extensiones

Para enumerar todas las extensiones registradas, ejecuta el siguiente comando de curl:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
"${URL}/extensions"

Para obtener una extensión, ejecuta el siguiente comando de curl:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
"${URL}/extensions/${EXTENSION_ID}"

Puedes actualizar displayName, description o toolUseExamples de la extensión. Si especificas toolUseExamples cuando actualizas una extensión, la actualización reemplazará los ejemplos. Por ejemplo, si tienes ejemplos a y b, actualiza la extensión con el ejemplo c, entonces la extensión actualizada solo contiene el ejemplo c. Para actualizar una descripción de extensión, ejecuta el siguiente comando de curl:

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
${URL}/extensions/${EXTENSION_ID}?update_mask="description" \
-d '{
  "description": "A nice tool.",
}'

Para borrar una extensión, ejecuta el siguiente comando de curl:

curl \
 -X DELETE \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
${URL}/extensions/${EXTENSION_ID}

Ejecuta una extensión

Si tu extensión usa la autenticación de OAuth y un token de acceso, consulta Ejecuta una extensión con autenticación de OAuth y un token de acceso.

Si tu extensión usa la autenticación de OIDC y un token de ID, consulta Ejecuta una extensión con autenticación de OIDC y un token de ID.

De lo contrario, puedes ejecutarlo mediante los siguientes pasos:

  1. Crea un archivo llamado execute-extension.json con el siguiente contenido:

    {
  "operation_id": "API_SERVICE_OPERATION_ID",
  "operation_params": {
    "API_SERVICE_INPUT_VAR": "API_SERVICE_INPUT_VALUE"
  }
}
    • API_SERVICE_OPERATION_ID: El ID de la operación del servicio de API que deseas ejecutar. Las operaciones de servicio de API se definen en el archivo de especificación de API.
    • API_SERVICE_INPUT_VAR: Es una variable de entrada que corresponde a API_SERVICE_OPERATION_ID y se define en el archivo de especificación de la API.
    • API_SERVICE_INPUT_VALUE: Un valor de entrada para la extensión.

  2. Ejecuta el siguiente comando curl:

    curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
"${URL}/extensions/${EXTENSION_ID}:execute"

    La respuesta tiene el siguiente formato:

    {
  "output": {
    "content": "{\"API_SERVICE_OUTPUT_VAR\": \"API_SERVICE_OUTPUT_VALUE\"}"
  }
}
    • API_SERVICE_OUTPUT_VAR: un parámetro de salida que se define en el archivo de especificación de API y que corresponde al servicio de API.
    • API_SERVICE_OUTPUT_VALUE: Un valor de cadena que es una serialización del objeto de respuesta. Si tu archivo de especificación de la API define un esquema de respuesta JSON, debes analizar esta cadena de salida en JSON por tu cuenta.

Ejecuta una extensión con autenticación de OAuth y un token de acceso

Si la extensión usa la autenticación de OAuth y un token de acceso, puedes ejecutarla mediante los siguientes pasos:

  1. Crea un archivo llamado execute-extension.json con el siguiente contenido:

    {
  "operation_id": "API_SERVICE_OPERATION_ID",
  "operation_params": {...},
  "runtime_auth_config": {
    "authType": "OAUTH",
    "oauth_config": {"access_token": "'$(gcloud auth print-access-token)'"}
  }
}
    • API_SERVICE_OPERATION_ID: El ID de la operación del servicio de API que deseas ejecutar. Las operaciones de servicio de API se definen en el archivo de especificación de API.

  2. Ejecuta el siguiente comando curl:

    curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
"${URL}/extensions/${EXTENSION_ID}:execute"

Ejecuta una extensión con autenticación de OIDC y un token de ID

Si tu extensión usa autenticación de OIDC y un token de ID, puedes ejecutarla mediante los siguientes pasos:

  1. Crea un archivo llamado execute-extension.json con el siguiente contenido:

    {
  "operation_id": "API_SERVICE_OPERATION_ID",
  "operation_params": {...},
  "runtime_auth_config": {
    "authType": "OIDC_AUTH",
    "oidc_config": {"id_token": "$(gcloud auth print-identity-token)"}
  }
}
    • API_SERVICE_OPERATION_ID: El ID de la operación del servicio de API que deseas ejecutar. Las operaciones de servicio de API se definen en el archivo de especificación de API.

  2. Ejecuta el siguiente comando curl:

    curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
"${URL}/extensions/${EXTENSION_ID}:execute"

¿Qué sigue?