Usa la transferencia de datos con el motor de RAG de Agent Platform de Gemini Enterprise

En esta página, se explica cómo realizar la ingesta de datos con una fuente de datos compatible, como Cloud Storage, Google Drive, Slack, Jira o SharePoint, y cómo usar esos datos con el motor RAG de Gemini Enterprise Agent Platform. El ragFiles.import proporciona conectores de datos a estas fuentes de datos.

Fuentes de datos compatibles con RAG

Se admiten las siguientes fuentes de datos:

  • Sube un archivo local: Una carga de un solo archivo mediante upload_file (hasta 25 MB), que es una llamada síncrona.
  • Cloud Storage: Importa archivos desde Cloud Storage.

  • Google Drive: Importa un directorio desde Google Drive.

    Se deben otorgar los permisos correctos a la cuenta de servicio para importar archivos. De lo contrario, no se importarán archivos y no se mostrará ningún mensaje de error. Para obtener más información sobre los límites de tamaño de los archivos, consulta Tipos de documentos admitidos.

    Para autenticar y conceder permisos, haz lo siguiente:

    1. Ve a la página IAM de tu Google Cloud proyecto.
    2. Selecciona Incluir asignación de rol proporcionada por Google.
    3. Busca la cuenta de servicio del agente de servicio de datos de RAG de Agent Platform.
    4. Haz clic en compartir en la carpeta de la unidad, y compartir con la cuenta de servicio.
    5. Otorga permiso Viewer a la cuenta de servicio en tu carpeta o archivo de Google Drive. El ID del recurso de Google Drive se encuentra en la URL web.

  • Slack: Importa archivos de Slack con un conector de datos.

  • Jira: Importa archivos de Jira con un conector de datos .

Anulación de duplicación de datos

Si el mismo archivo se importa varias veces sin cambios, se omite porque ya existe. Por lo tanto, response.skipped_rag_files_count hace referencia a la cantidad de archivos que se omitieron durante el proceso de importación.

Se omite un archivo cuando se cumplen las siguientes condiciones:

  • El archivo se importó.
  • El archivo no cambió.
  • La configuración de fragmentación del archivo no cambió.

Información sobre las fallas de importación

Para comprender las fallas de importación, en esta sección, se explican los metadatos en una respuesta a una solicitud de importación y un receptor de datos, que es el destino de los datos que importas.

Metadatos de respuesta

Puedes usar response.metadata (un objeto de respuesta en el SDK) para ver los resultados de la importación, el tiempo de solicitud y el tiempo de respuesta.

Receptor de resultados de importación

En el SDK, import_result_sink es un parámetro de función opcional que se puede establecer en un valor de cadena válido.

Si se proporciona import_result_sink, los resultados de los archivos correctos y fallidos se escriben en el receptor. Tener todos los resultados escritos en el receptor facilita la comprensión de por qué algunos archivos no se pueden importar y qué archivos no se importaron.

import_result_sink debe ser una ruta de Cloud Storage o una tabla de BigQuery.

  • Si import_result_sink es una ruta de Cloud Storage, debe usar el formato gs://my-bucket/my/object.ndjson y el objeto no debe existir. Una vez que se completa el trabajo de importación, cada línea del objeto de Cloud Storage contiene un objeto JSON, que tiene un ID de operación, una marca de tiempo de creación, un nombre de archivo, un estado y un ID de archivo.

  • Si import_result_sink es una tabla de BigQuery, debe usar el formato bq://my-project.my-dataset.my-table. La tabla no tiene que existir. Si no existe, se crea. Si la tabla existe, se verifica el esquema. La primera vez que se proporciona el receptor de resultados de importación de BigQuery, proporcionarás una tabla inexistente; de lo contrario, puedes volver a usar la tabla existente.

Importa archivos desde Cloud Storage o Google Drive

Para importar archivos desde Cloud Storage o Google Drive a tu corpus, haz lo siguiente:

  1. Crea un corpus RAG. Para obtener más información, consulta Método: ragCorpora.create.

  2. Para importar tus archivos desde Cloud Storage o Google Drive, usa el ragFiles.import.

    El sistema verifica automáticamente la ruta de acceso, el nombre de archivo y el version_id del archivo. El version_id es un hash de archivo que se calcula con el contenido del archivo, lo que evita que se vuelva a indexar.

    Si un archivo con el mismo nombre y ruta de acceso tiene una actualización de contenido, se vuelve a indexar.

Importa archivos desde Slack

Para importar archivos de Slack a tu corpus, haz lo siguiente:

  1. Crea un corpus, que es un índice que estructura y optimiza tus datos para la búsqueda. Para obtener más información, consulta Método: ragCorpora.create.
  2. Obtén tu CHANNEL_ID del ID del canal de Slack.
  3. Crea y configura una app para usar con el motor RAG de Gemini Enterprise Agent Platform.
    1. En la IU de Slack, en la sección Add features and functionality, haz clic en Permissions.
    2. Agrega los siguientes permisos:
      • channels:history
      • groups:history
      • im:history
      • mpim:history
    3. Haz clic en Install to Workspace para instalar la app en tu lugar de trabajo de Slack.
  4. Haz clic en Copiar para obtener tu token de API, que autentica tu identidad y te otorga acceso a una API.
  5. Agrega tu token de API a Secret Manager.
  6. Para ver el secreto almacenado, otorga el rol Secret Manager Secret Accessor a la cuenta de servicio del motor RAG de Gemini Enterprise Agent Platform de tu proyecto.

En los siguientes ejemplos de código de curl y Python, se muestra cómo importar archivos de tus recursos de Slack.

curl

Si quieres obtener mensajes de un canal específico, cambia el CHANNEL_ID.

API_KEY_SECRET_VERSION=SLACK_API_KEY_SECRET_VERSION
CHANNEL_ID=SLACK_CHANNEL_ID
PROJECT_ID=us-central1

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ ENDPOINT }/v1beta1/projects/${ PROJECT_ID }/locations/${ PROJECT_ID }/ragCorpora/${ RAG_CORPUS_ID }/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "slack_source": {
      "channels": [
        {
          "apiKeyConfig": {
            "apiKeySecretVersion": "'"${ API_KEY_SECRET_VERSION }"'"
          },
          "channels": [
            {
              "channel_id": "'"${ CHANNEL_ID }"'"
            }
          ]
        }
      ]
    }
  }
}'

Python

Si quieres obtener mensajes para un período determinado o de un canal específico, cambia cualquiera de los siguientes campos:

  • START_TIME
  • END_TIME
  • CHANNEL1 o CHANNEL2
    # Slack example
    start_time = protobuf.timestamp_pb2.Timestamp()
    start_time.GetCurrentTime()
    end_time = protobuf.timestamp_pb2.Timestamp()
    end_time.GetCurrentTime()
    source = rag.SlackChannelsSource(
        channels = [
            SlackChannel("CHANNEL1", "api_key1"),
            SlackChannel("CHANNEL2", "api_key2", START_TIME, END_TIME)
        ],
    )

    response = rag.import_files(
        corpus_name="projects/my-project/locations/us-central1/ragCorpora/my-corpus-1",
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

Importa archivos desde Jira

Para importar archivos de Jira a tu corpus, haz lo siguiente:

  1. Crea un corpus, que es un índice que estructura y optimiza tus datos para la búsqueda. Para obtener más información, consulta Método: ragCorpora.create.

  2. Para crear un token de API, accede al sitio de Atlassian.

  3. Usa {YOUR_ORG_ID}.atlassian.net como SERVER_URI en la solicitud.

  4. Usa tu correo electrónico de Atlassian como EMAIL en la solicitud.

  5. Proporciona projects o customQueries con tu solicitud. Para obtener más información sobre las consultas personalizadas, consulta Usa la búsqueda avanzada con el lenguaje de consultas de Jira (JQL).

    Cuando importas projects, projects se expande a las consultas correspondientes para obtener todo el proyecto. Por ejemplo, MyProject se expande a project = MyProject.

  6. Haz clic en Copiar para obtener tu token de API, que autentica tu identidad y te otorga acceso a una API.

  7. Agrega tu token de API a Secret Manager.

  8. Otorga el rol Secret Manager Secret Accessor a la cuenta de servicio del motor RAG de Gemini Enterprise Agent Platform de tu proyecto.

curl

EMAIL=JIRA_EMAIL
API_KEY_SECRET_VERSION=JIRA_API_KEY_SECRET_VERSION
SERVER_URI=JIRA_SERVER_URI
CUSTOM_QUERY=JIRA_CUSTOM_QUERY
PROJECT_ID=JIRA_PROJECT
REGION= "us-central1"

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ ENDPOINT }/v1beta1/projects/${ PROJECT_ID }/locations/REGION>/ragCorpora/${ RAG_CORPUS_ID }/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "jiraSource": {
      "jiraQueries": [{
        "projects": ["'"${ PROJECT_ID }"'"],
        "customQueries": ["'"${ CUSTOM_QUERY }"'"],
        "email": "'"${ EMAIL }"'",
        "serverUri": "'"${ SERVER_URI }"'",
        "apiKeyConfig": {
          "apiKeySecretVersion": "'"${ API_KEY_SECRET_VERSION }"'"
        }
      }]
    }
  }
}'

Python 

    # Jira Example
    jira_query = rag.JiraQuery(
        email="xxx@yyy.com",
        jira_projects=["project1", "project2"],
        custom_queries=["query1", "query2"],
        api_key="api_key",
        server_uri="server.atlassian.net"
    )
    source = rag.JiraSource(
        queries=[jira_query],
    )

    response = rag.import_files(
        corpus_name="projects/my-project/locations/REGION/ragCorpora/my-corpus-1",
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

Importa archivos desde SharePoint

Para importar archivos desde tu sitio de SharePoint a tu corpus, haz lo siguiente:

  1. Crea un corpus, que es un índice que estructura y optimiza tus datos para la búsqueda. Para obtener más información, consulta Método: ragCorpora.create.

  2. Crea una app de Azure para acceder a tu sitio de SharePoint.

    1. Para crear un registro, ve a Registros de aplicaciones.

      1. Proporciona un nombre para la aplicación.

      2. Elige la opción Cuentas en este directorio de la organización solo.

      3. Verifica que los URIs de redireccionamiento estén vacíos.

    2. En la sección Descripción general , usa tu ID de aplicación (cliente) como el CLIENT_ID y tu "ID de directorio (inquilino)" como el TENANT_ID.

    3. En la sección Administrar, actualiza los permisos de la API de la siguiente manera:

      1. Agrega el permiso Sites.Read.All de SharePoint.

      2. Agrega los permisos Files.Read.All y Browser SiteLists.Read.All de Microsoft Graph.

      3. Otorga el consentimiento del administrador para que estos cambios de permisos surtan efecto.

    4. En la sección Administrar, haz lo siguiente:

      1. Actualiza Certificados y secretos con un nuevo secreto del cliente.

      2. Usa el API_KEY_SECRET_VERSION para agregar el valor secreto a Secret Manager.

  3. Otorga el rol Secret Manager Secret Accessor a la cuenta de servicio del motor RAG de Gemini Enterprise Agent Platform de tu proyecto.

  4. Usa {YOUR_ORG_ID}.sharepoint.com como el SHAREPOINT_SITE_NAME.

  5. Se debe especificar un nombre o ID de unidad en el sitio de SharePoint en la solicitud.

  6. Opcional: Se puede especificar una ruta de acceso o un ID de carpeta en la unidad. Si no se especifica la ruta de acceso o el ID de la carpeta, se importan todas las carpetas y los archivos de la unidad.

curl

CLIENT_ID=SHAREPOINT_CLIENT_ID
API_KEY_SECRET_VERSION=SHAREPOINT_API_KEY_SECRET_VERSION
TENANT_ID=SHAREPOINT_TENANT_ID
SITE_NAME=SHAREPOINT_SITE_NAME
FOLDER_PATH=SHAREPOINT_FOLDER_PATH
DRIVE_NAME=SHAREPOINT_DRIVE_NAME

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ ENDPOINT }/v1beta1/projects/${ PROJECT_ID }/locations/REGION>/ragCorpora/${ RAG_CORPUS_ID }/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "sharePointSources": {
      "sharePointSource": [{
        "clientId": "'"${ CLIENT_ID }"'",
        "apiKeyConfig": {
          "apiKeySecretVersion": "'"${ API_KEY_SECRET_VERSION }"'"
        },
        "tenantId": "'"${ TENANT_ID }"'",
        "sharepointSiteName": "'"${ SITE_NAME }"'",
        "sharepointFolderPath": "'"${ FOLDER_PATH }"'",
        "driveName": "'"${ DRIVE_NAME }"'"
      }]
    }
  }
}'

Python 

    from vertexai.preview import rag
    from vertexai.preview.rag.utils import resources

    CLIENT_ID="SHAREPOINT_CLIENT_ID"
    API_KEY_SECRET_VERSION="SHAREPOINT_API_KEY_SECRET_VERSION"
    TENANT_ID="SHAREPOINT_TENANT_ID"
    SITE_NAME="SHAREPOINT_SITE_NAME"
    FOLDER_PATH="SHAREPOINT_FOLDER_PATH"
    DRIVE_NAME="SHAREPOINT_DRIVE_NAME"

    # SharePoint Example.
    source = resources.SharePointSources(
        share_point_sources=[
            resources.SharePointSource(
                client_id=CLIENT_ID,
                client_secret=API_KEY_SECRET_VERSION,
                tenant_id=TENANT_ID,
                sharepoint_site_name=SITE_NAME,
                folder_path=FOLDER_PATH,
                drive_id=DRIVE_ID,
            )
        ]
    )

    response = rag.import_files(
        corpus_name="projects/my-project/locations/REGION/ragCorpora/my-corpus-1",
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

¿Qué sigue?