Utilizzare l'importazione dati con RAG Engine

Questa pagina spiega come eseguire l'importazione dati utilizzando un'origine dati supportata, come Cloud Storage, Google Drive, Slack, Jira o SharePoint, e come utilizzare questi dati con RAG Engine. Il metodo ragFiles.import fornisce connettori dati a queste origini dati.

Origini dati supportate per RAG

Sono supportate le seguenti origini dati:

  • Carica un file locale: un caricamento di un singolo file utilizzando upload_file (fino a 25 MB), che è una chiamata sincrona.
  • Cloud Storage: importa i file da Cloud Storage.

  • Google Drive: importa una directory da Google Drive.

    Al service account devono essere concesse le autorizzazioni corrette per importare i file. In caso contrario, non viene importato alcun file e non viene visualizzato alcun messaggio di errore. Per ulteriori informazioni sui limiti delle dimensioni dei file, consulta Tipi di documenti supportati.

    Per autenticare e concedere le autorizzazioni, segui questi passaggi:

    1. Vai alla pagina IAM del tuo progettoGoogle Cloud .
    2. Seleziona Includi concessioni di ruoli fornite da Google.
    3. Cerca il account di servizio Agent Platform RAG Data Service Agent.
    4. Fai clic su Condividi nella cartella di Drive e condividi con il account di servizio.
    5. Concedi l'autorizzazione Viewer al account di servizio per la cartella o il file di Google Drive. L'ID risorsa di Google Drive è disponibile nell'URL web.

  • Slack: importa i file da Slack utilizzando un connettore dati.

  • Jira: importa i file da Jira utilizzando un connettore dati.

Deduplicazione dei dati

Se lo stesso file viene importato più volte senza modifiche, viene ignorato perché esiste già. Pertanto, response.skipped_rag_files_count si riferisce al numero di file che sono stati ignorati durante il processo di importazione.

Un file viene ignorato quando vengono soddisfatte le seguenti condizioni:

  • Il file è stato importato.
  • Il file non è stato modificato.
  • La configurazione del chunking per il file non è cambiata.

Informazioni sugli errori di importazione

Per comprendere gli errori di importazione, questa sezione spiega i metadati in una risposta a una richiesta di importazione e un sink di dati, ovvero la destinazione dei dati che stai importando.

Metadati della risposta

Puoi utilizzare response.metadata (un oggetto di risposta nell'SDK) per visualizzare i risultati dell'importazione, l'ora della richiesta e l'ora della risposta.

Sink dei risultati dell'importazione

Nell'SDK, import_result_sink è un parametro di funzione facoltativo che può essere impostato su un valore di stringa valido.

Se viene fornito import_result_sink, i risultati dei file caricati correttamente e non caricati vengono scritti nel sink. La scrittura di tutti i risultati nel sink semplifica la comprensione del motivo per cui l'importazione di alcuni file potrebbe non riuscire e di quali file non sono stati importati.

import_result_sink deve essere un percorso Cloud Storage o una tabella BigQuery.

  • Se import_result_sink è un percorso Cloud Storage, deve utilizzare il formato gs://my-bucket/my/object.ndjson e l'oggetto non deve esistere. Al termine del job di importazione, ogni riga dell'oggetto Cloud Storage contiene un oggetto JSON con un ID operazione, un timestamp di creazione, un nome file, uno stato e un ID file.

  • Se import_result_sink è una tabella BigQuery, deve utilizzare il formato bq://my-project.my-dataset.my-table. La tabella non deve esistere. Se la tabella non esiste, viene creata. Se la tabella esiste, lo schema viene verificato. La prima volta che viene fornito il sink dei risultati di importazione di BigQuery, devi fornire una tabella non esistente; altrimenti, puoi riutilizzare la tabella esistente.

Importa file da Cloud Storage o Google Drive

Per importare file da Cloud Storage o Google Drive nel corpus, segui questi passaggi:

  1. Crea un corpus RAG. Per saperne di più, consulta Metodo: ragCorpora.create.

  2. Per importare i file da Cloud Storage o Google Drive, utilizza il metodo ragFiles.import.

    Il sistema controlla automaticamente il percorso, il nome file e il version_id del file. version_id è un hash del file calcolato utilizzando i contenuti del file, che impedisce la reindicizzazione del file.

    Se un file con lo stesso nome file e percorso ha un aggiornamento dei contenuti, viene reindicizzato.

Importa i file da Slack

Per importare file da Slack nel corpus, segui questi passaggi:

  1. Crea un corpus, ovvero un indice che struttura e ottimizza i dati per la ricerca. Per saperne di più, consulta Metodo: ragCorpora.create.
  2. Recupera il tuo CHANNEL_ID dall'ID canale Slack.
  3. Crea e configura un'app da utilizzare con il motore RAG.
    1. Dalla UI di Slack, nella sezione Add features and functionality (Aggiungi caratteristiche e funzionalità), fai clic su Permissions (Autorizzazioni).
    2. Aggiungi le seguenti autorizzazioni:
      • channels:history
      • groups:history
      • im:history
      • mpim:history
    3. Fai clic su Installa nel workspace per installare l'app nel tuo workspace Slack.
  4. Fai clic su Copia per ottenere il token API, che autentica la tua identità e ti consente di accedere a un'API.
  5. Aggiungi il token API a Secret Manager.
  6. Per visualizzare il secret archiviato, concedi il ruolo Secret Manager Secret Accessor al account di servizio RAG Engine del tuo progetto.

I seguenti esempi di codice curl e Python mostrano come importare file dalle tue risorse Slack.

curl

Se vuoi ricevere messaggi da un canale specifico, modifica l'impostazione CHANNEL_ID.

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": {
    "slack_source": {
      "channels": [
        {
          "apiKeyConfig": {
            "apiKeySecretVersion": "API_KEY_SECRET_VERSION"
          },
          "channels": [
            {
              "channel_id": "CHANNEL_ID"
            }
          ]
        }
      ]
    }
  }
}'

Python

Se vuoi ricevere messaggi per un determinato intervallo di tempo o da un canale specifico, modifica uno dei seguenti campi:

  • 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/PROJECT_ID/locations/"
            "REGION/ragCorpora/RAG_CORPUS_ID"
        ),
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

Importa i file da Jira

Per importare file da Jira nel tuo corpus, segui questi passaggi:

  1. Crea un corpus, ovvero un indice che struttura e ottimizza i dati per la ricerca. Per saperne di più, consulta Metodo: ragCorpora.create.

  2. Per creare un token API, accedi al sito Atlassian.

  3. Utilizza {YOUR_ORG_ID}.atlassian.net come SERVER_URI nella richiesta.

  4. Utilizza la tua email Atlassian come EMAIL nella richiesta.

  5. Fornisci projects o customQueries con la tua richiesta. Per scoprire di più sulle query personalizzate, consulta Utilizza la ricerca avanzata con Jira Query Language (JQL).

    Quando importi projects, projects viene espanso nelle query corrispondenti per ottenere l'intero progetto. Ad esempio, MyProject viene espanso in project = MyProject.

  6. Fai clic su Copia per ottenere il token API, che autentica la tua identità e ti consente di accedere a un'API.

  7. Aggiungi il token API a Secret Manager.

  8. Concedi il ruolo Secret Manager Secret Accessor al account di servizio RAG Engine del tuo progetto.

curl

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": ["JIRA_PROJECT"],
        "customQueries": ["CUSTOM_QUERY"],
        "email": "EMAIL",
        "serverUri": "SERVER_URI",
        "apiKeyConfig": {
          "apiKeySecretVersion": "API_KEY_SECRET_VERSION"
        }
      }]
    }
  }
}'

Python 

    # Jira Example
    jira_query = rag.JiraQuery(
        email="EMAIL",
        jira_projects=["JIRA_PROJECT"],
        custom_queries=["CUSTOM_QUERY"],
        api_key="API_KEY_SECRET_VERSION",
        server_uri="SERVER_URI"
    )
    source = rag.JiraSource(
        queries=[jira_query],
    )

    response = rag.import_files(
        corpus_name=(
            "projects/PROJECT_ID/locations/"
            "REGION/ragCorpora/RAG_CORPUS_ID"
        ),
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

Importa i file da SharePoint

Per importare i file dal tuo sito SharePoint nel corpus, segui questi passaggi:

  1. Crea un corpus, ovvero un indice che struttura e ottimizza i dati per la ricerca. Per saperne di più, consulta Metodo: ragCorpora.create.

  2. Crea un'app Azure per accedere al tuo sito SharePoint.

    1. Per creare una registrazione, vai a Registrazioni app.

      1. Specifica un nome per l'applicazione.

      2. Scegli l'opzione Solo account in questa directory dell'organizzazione.

      3. Verifica che gli URI di reindirizzamento siano vuoti.

    2. Nella sezione Panoramica, utilizza l'ID applicazione (client) come CLIENT_ID e l'"ID directory (tenant)" come TENANT_ID.

    3. Nella sezione Gestisci, aggiorna le autorizzazioni API nel seguente modo:

      1. Aggiungi l'autorizzazione SharePoint Sites.Read.All.

      2. Aggiungi le autorizzazioni di Microsoft Graph Files.Read.All e Browser SiteLists.Read.All.

      3. Concedi il consenso amministratore per rendere effettive queste modifiche alle autorizzazioni.

    4. Nella sezione Gestisci, segui questi passaggi:

      1. Aggiorna Certificati e secret con un nuovo client secret.

      2. Utilizza API_KEY_SECRET_VERSION per aggiungere il valore del secret a Secret Manager.

  3. Concedi il ruolo Secret Manager Secret Accessor al account di servizio RAG Engine del tuo progetto.

  4. Utilizza {YOUR_ORG_ID}.sharepoint.com come SHAREPOINT_SITE_NAME.

  5. Nella richiesta deve essere specificato un nome o un ID del Drive nel sito SharePoint.

  6. (Facoltativo) È possibile specificare un percorso o un ID cartella sul Drive. Se il percorso o l'ID della cartella non sono specificati, vengono importati tutti i file e le cartelle del Drive.

Individua l'ID sito

  1. Apri il browser e vai all'URL del sito SharePoint di destinazione.

  2. Aggiungi /_api/site/id/ alla fine dell'URL.

    Esempio: https://example-sp.sharepoint.com/sites/example-site/_api/site/id/

    La pagina restituisce un payload XML. Prendi nota della stringa dopo Edm.Guid. Questo è il tuo ID sito.

Individua l'ID Drive

Con l'ID sito che hai raccolto, effettua una richiesta GET autenticata utilizzando Microsoft Graph Explorer o il tuo client API:

GET https://graph.microsoft.com/v1.0/sites/SITE_ID/drive

Ottieni il valore SHAREPOINT_DRIVE_ID. Il valore è elencato nel campo id della risposta JSON.

Individua un ID cartella specifico

Utilizza l'ID Drive per elencare gli elementi secondari della directory principale:

GET https://graph.microsoft.com/v1.0/drives/SHAREPOINT_DRIVE_ID/root/children

  • Nella risposta JSON, trova l'oggetto corrispondente al nome della cartella selezionata e copia la stringa id corrispondente. Questo è il tuo SHAREPOINT_FOLDER_ID.

curl

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": "SHAREPOINT_TENANT_ID",
        "sharepointSiteName": "SHAREPOINT_SITE_NAME",
        "sharepointFolderId": "SHAREPOINT_FOLDER_ID",
        "driveId": "SHAREPOINT_DRIVE_ID"
      }]
    }
  }
}'

Python 

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

    vertexai.init(
        project="PROJECT_ID",
        location="REGION",
    )

    # SharePoint Example.
    source = resources.SharePointSources(
        share_point_sources=[
            resources.SharePointSource(
                client_id="CLIENT_ID",
                client_secret="API_KEY_SECRET_VERSION",
                tenant_id="SHAREPOINT_TENANT_ID",
                sharepoint_site_name="SHAREPOINT_SITE_NAME",
                sharepoint_folder_id="SHAREPOINT_FOLDER_ID",
                drive_id="SHAREPOINT_DRIVE_ID",
            )
        ]
    )

    response = rag.import_files(
        corpus_name=(
            "projects/PROJECT_ID/locations/"
            "REGION/ragCorpora/RAG_CORPUS_ID"
        ),
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

Passaggi successivi