Usar la ingestión de datos con el motor de RAG de Vertex AI

En esta página se explica cómo ingerir datos mediante una fuente de datos admitida, como Cloud Storage, Google Drive, Slack, Jira o SharePoint, y cómo usar esos datos con el motor RAG de Vertex AI. La API Import RagFiles proporciona conectores de datos a estas fuentes de datos.

Fuentes de datos admitidas para RAG

Se admiten las siguientes fuentes de datos:

• Subir un archivo local: se trata de una subida de un solo archivo mediante upload_file (hasta 25 MB), que es una llamada síncrona.
• Cloud Storage: importa archivos de Cloud Storage.

• Google Drive: importa un directorio de Google Drive.

  La cuenta de servicio debe tener los permisos correctos para importar archivos. De lo contrario, no se importará ningún archivo 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 autenticarte y conceder permisos, sigue estos pasos:

  1. Ve a la página de gestión de identidades y accesos de tu Google Cloud proyecto.
  2. Selecciona Incluir concesiones de roles proporcionadas por Google.
  3. Busca la cuenta de servicio Vertex AI RAG Data Service Agent.
  4. Haz clic en Compartir en la carpeta de la unidad y compártela con la cuenta de servicio.
  5. Concede permiso a Viewer en la cuenta de servicio de tu carpeta o archivo de Google Drive. El ID de recurso de Google Drive se encuentra en la URL web.

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

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

Para obtener más información, consulta la referencia de la API RAG.

Deduplicación de datos

Si se importa el mismo archivo varias veces sin realizar ningún cambio, se omitirá porque ya existe. Por lo tanto, response.skipped_rag_files_count hace referencia al número de archivos que se han omitido durante el proceso de importación.

Un archivo se omite cuando se cumplen las siguientes condiciones:

• El archivo se ha importado.
• El archivo no ha cambiado.
• La configuración de fragmentación del archivo no ha cambiado.

Información sobre los errores de importación

Para entender los fallos de importación, en esta sección se explica qué son los metadatos de una respuesta a una solicitud de importación y un receptor de datos, que es el destino de los datos que vas a importar.

Metadatos de respuesta

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

Receptor de resultados de importación

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

Si se proporciona el import_result_sink, los resultados de los archivos correctos y fallidos se escriben en el receptor. Si todos los resultados se escriben en el receptor, será más fácil entender por qué no se han podido importar algunos archivos y cuáles no se han importado.

El valor de 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 haya completado el trabajo de importación, cada línea del objeto de Cloud Storage contendrá un objeto JSON, que tendrá 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. No es necesario que la tabla exista. Si la tabla no existe, se crea. Si la tabla existe, se verifica el esquema. La primera vez que se proporcione el sumidero de resultados de importación de BigQuery, se proporcionará una tabla que no existe. De lo contrario, puede reutilizar la tabla.

Importar archivos de Cloud Storage o Google Drive

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

1. Crea un corpus siguiendo las instrucciones de Crear un corpus de RAG.

2. Para importar tus archivos de Cloud Storage o Google Drive, usa la plantilla.

   El sistema comprueba automáticamente la ruta, el nombre y la version_id del archivo. El version_id es un hash de archivo que se calcula a partir del contenido del archivo, lo que impide que se vuelva a indexar.

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

Importar archivos de 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 que se puedan buscar. Sigue las instrucciones que se indican en Crear un corpus de RAG.
2. Obtén tu CHANNEL_ID del ID del canal de Slack.
3. Crea y configura una aplicación para usarla con Vertex AI RAG Engine.
   1. En la interfaz de usuario de Slack, en la sección Añadir funciones, haz clic en Permisos.
   2. Añade los siguientes permisos:
      • channels:history
      • groups:history
      • im:history
      • mpim:history
   3. Haz clic en Instalar en Workspace para instalar la aplicación en tu espacio de trabajo de Slack.
4. Haz clic en Copiar para obtener tu token de API, que autentica tu identidad y te da acceso a una API.
5. Añade tu token de API a Secret Manager.
6. Para ver el secreto almacenado, asigna el rol Permiso para acceder a los recursos de Secret Manager a la cuenta de servicio del motor RAG de Vertex AI 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.

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

    # 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,
    )

Importar archivos de Jira

Para importar archivos de Jira a tu corpus, sigue estos pasos:

1. Crea un corpus, que es un índice que estructura y optimiza tus datos para que se puedan buscar. Sigue las instrucciones que se indican en Crear un corpus de RAG.
2. Para crear un token de API, inicia sesión en el sitio de Atlassian.
3. Usa {YOUR_ORG_ID}.atlassian.net como SERVER_URI en la solicitud.
4. Usa tu correo de Atlassian como EMAIL en la solicitud.
5. Proporciona projects o customQueries en tu solicitud. Para obtener más información sobre las consultas personalizadas, consulta Usar la búsqueda avanzada con el lenguaje de consulta de Jira (JQL).

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

6. Haz clic en Copiar para obtener tu token de API, que autentica tu identidad y te da acceso a una API.
7. Añade tu token de API a Secret Manager.
8. Asigna el rol Permiso para acceder a los recursos de Secret Manager a la cuenta de servicio del motor RAG de Vertex AI de tu proyecto.

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

    # 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,
    )

Importar archivos de SharePoint

Para importar archivos de tu sitio de SharePoint a tu corpus, sigue estos pasos:

1. Crea un corpus, que es un índice que estructura y optimiza tus datos para que se puedan buscar. Sigue las instrucciones que se indican en Crear un corpus de RAG.
2. Crea una aplicación de Azure para acceder a tu sitio de SharePoint.
   1. Para crear un registro, ve a Registros de aplicaciones.
      1. Asigna un nombre a la aplicación.
      2. Elige la opción Solo cuentas de este directorio de la empresa.
      3. Verifica que los URIs de redirección estén vacíos.
   2. En la sección Descripción general, usa tu ID de aplicación (cliente) como CLIENT_ID y tu ID de directorio (cliente) como TENANT_ID.
   3. En la sección Gestionar, actualiza los permisos de la API siguiendo estos pasos:
      1. Añade el permiso de SharePoint Sites.Read.All.
      2. Añade los permisos Files.Read.All y Browser SiteLists.Read.All de Microsoft Graph.
      3. Concede el consentimiento de administrador para que se apliquen estos cambios en los permisos.
   4. En la sección Gestionar, haga lo siguiente:
      1. Actualiza Certificados y secretos con un nuevo secreto de cliente.
      2. Usa API_KEY_SECRET_VERSION para añadir el valor del secreto a Secret Manager.
3. Asigna el rol Permiso para acceder a los recursos de Secret Manager a la cuenta de servicio del motor RAG de Vertex AI de tu proyecto.
4. Usa {YOUR_ORG_ID}.sharepoint.com como SHAREPOINT_SITE_NAME.
5. En la solicitud se debe especificar un nombre o un ID de unidad del sitio de SharePoint.
6. Opcional: se puede especificar una ruta de carpeta o un ID de carpeta en la unidad. Si no se especifica la ruta de la carpeta o el ID de la carpeta, se importarán todas las carpetas y los archivos de la unidad.

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

    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,
    )

Siguientes pasos

• Bases de datos de vectores disponibles en el motor de RAG de Vertex AI