Usa la transferencia de datos con el motor de RAG de Vertex AI

En esta página, se explica cómo realizar la transferencia 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 de RAG de Vertex AI. La API de Import RagFiles proporciona conectores de datos a estas fuentes de datos.

Fuentes de datos compatibles con la RAG

Se admiten las siguientes fuentes de datos:

• Carga un archivo local: Una carga de un solo archivo con 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 ni 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 de IAM de tu proyecto deGoogle Cloud .
  2. Selecciona Incluir asignación de rol proporcionada por Google.
  3. Busca la cuenta de servicio del agente de servicio de datos de Vertex AI RAG.
  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.

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

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:

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

Comprende los errores de importación

Para comprender los errores 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 la 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 cuáles no se importaron.

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

• Si import_result_sink es una ruta de acceso de Cloud Storage, debe usar el formato de 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 proporcione el receptor de resultados de importación de BigQuery, se proporcionará una tabla inexistente; de lo contrario, se puede volver a usar la tabla existente.

Importa archivos desde Cloud Storage o Google Drive

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

1. Para crear un corpus, sigue las instrucciones en Crea un corpus de RAG.

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

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

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

Cómo importar 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. Sigue las instrucciones en Crea un corpus RAG.
2. Obtén tu CHANNEL_ID del ID del canal de Slack.
3. Crea y configura una app para usarla con el motor de RAG de Vertex AI.
   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 Instalar en el lugar de trabajo 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 de Vertex AI RAG Engine de tu proyecto.

En los siguientes ejemplos de código de curl y Python, se muestra cómo importar archivos desde 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,
    )

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. Sigue las instrucciones en Crea un corpus RAG.
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 búsquedas personalizadas, consulta Usa la búsqueda avanzada con Jira Query Language (JQL).

   Cuando importas projects, este se expande en las consultas correspondientes para obtener todo el proyecto.projects 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 de 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,
    )

Cómo importar 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. Sigue las instrucciones en Crea un corpus RAG.
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 solo en este directorio de la organización.
      3. Verifica que los URIs de redireccionamiento estén vacíos.
   2. En la sección Descripción general, usa tu ID de la aplicación (cliente) como CLIENT_ID y tu "ID de directorio (inquilino)" como 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 consentimiento de administrador para que se apliquen estos cambios de permisos.
   4. En la sección Administrar, haz lo siguiente:
      1. Actualiza Certificados y secretos con un nuevo secreto del cliente.
      2. Usa API_KEY_SECRET_VERSION para agregar el valor del secreto a Secret Manager.
3. Otorga el rol Secret Manager Secret Accessor a la cuenta de servicio del motor de RAG de Vertex AI de tu proyecto.
4. Usa {YOUR_ORG_ID}.sharepoint.com como 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 a una carpeta o un ID de carpeta en la unidad. Si no se especifica la ruta de acceso 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,
    )

¿Qué sigue?

• Opciones de bases de datos vectoriales en el motor de RAG de Vertex AI