Usa la transferencia de datos con RAG Engine

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 RAG Engine. El método ragFiles.import 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 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:

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

Información sobre 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 con errores 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.

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. No es necesario que la tabla exista. 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, deberás proporcionar una tabla que no exista; de lo contrario, podrás 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. Crea un corpus de 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 método ragFiles.import.

    El sistema verifica automáticamente la ruta, el nombre del archivo y el version_id. El version_id es un hash del 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.

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. 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 RAG Engine.
    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 de Secret Manager Secret Accessor a la cuenta de servicio de 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.

curl

Si quieres recibir mensajes de un canal específico, cambia el valor de 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 recibir mensajes de 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 búsquedas personalizadas, consulta Cómo usar la búsqueda avanzada con el lenguaje de consultas de Jira (JQL).

    Cuando importas projects, projects se expande en 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 de RAG Engine 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 de SharePoint

Para importar archivos de 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 solo en este directorio de la organización.

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

    2. En la sección Overview, usa tu ID de 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 de RAG Engine 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 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.

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?