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 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 file da Cloud Storage.

  • Google Drive: importa una directory da Google Drive.

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

    Per autenticare e concedere le autorizzazioni:

    1. Vai alla pagina IAM del tuo Google Cloud progetto.
    2. Seleziona Includi concessione di ruoli fornita da Google.
    3. Cerca il account di servizio Agente di servizio dati RAG di Agent Platform.
    4. Fai clic su Condividi nella cartella di Drive e condividila con il account di servizio.
    5. Concedi l'autorizzazione Viewer al account di servizio nella cartella o nel 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 ignorati durante il processo di importazione.

Un file viene ignorato quando sono soddisfatte le seguenti condizioni:

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

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 di 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 di importazione

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

Se viene fornito import_result_sink, i risultati dei file riusciti e non riusciti vengono scritti nel sink. Se tutti i risultati vengono scritti nel sink, è più facile capire perché alcuni file potrebbero non essere importati e 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, che ha 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, dovrai fornire una tabella inesistente; in caso contrario, puoi riutilizzare la tabella esistente.

Importare file da Cloud Storage o Google Drive

Per importare file da Cloud Storage o Google Drive nel corpus:

  1. Crea un corpus RAG. Per ulteriori informazioni, vedi Metodo: ragCorpora.create.

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

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

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

Importare file da Slack

Per importare file da Slack nel corpus:

  1. Crea un corpus, ovvero un indice che struttura e ottimizza i dati per la ricerca. Per ulteriori informazioni, vedi Metodo: ragCorpora.create.
  2. Recupera CHANNEL_ID dall'ID canale Slack.
  3. Crea e configura un'app da utilizzare con RAG Engine.
    1. Nell'interfaccia utente di Slack, nella sezione Aggiungi funzionalità, fai clic su Autorizzazioni.
    2. Aggiungi le seguenti autorizzazioni:
      • channels:history
      • groups:history
      • im:history
      • mpim:history
    3. Fai clic su Installa nell'area di lavoro per installare l'app nell'area di lavoro di Slack.
  4. Fai clic su Copia per recuperare il token API, che autentica la tua identità e ti concede l'accesso 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 risorse di Slack.

curl

Se vuoi ricevere messaggi da un canale specifico, modifica 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,
    )

Importare file da Jira

Per importare file da Jira nel corpus:

  1. Crea un corpus, ovvero un indice che struttura e ottimizza i dati per la ricerca. Per ulteriori informazioni, vedi 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 saperne di più sulle query personalizzate, vedi Utilizzare 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 recuperare il token API, che autentica la tua identità e ti concede l'accesso 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,
    )

Importare file da SharePoint

Per importare file dal sito SharePoint nel corpus:

  1. Crea un corpus, ovvero un indice che struttura e ottimizza i dati per la ricerca. Per ulteriori informazioni, vedi Metodo: ragCorpora.create.

  2. Crea un'app Azure per accedere al 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 il tuo ID applicazione (client) come CLIENT_ID e il tuo "ID directory (tenant)" come TENANT_ID.

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

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

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

      3. Concedi il consenso dell'amministratore affinché le modifiche alle autorizzazioni abbiano effetto.

    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 secret valore 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 unità nel sito SharePoint.

  6. (Facoltativo) È possibile specificare un percorso o un ID cartella nell'unità. Se non viene specificato il percorso o l'ID della cartella, vengono importate tutte le cartelle e i file dell'unità.

Individuare 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.

Individuare l'ID unità

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

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

Recupera SHAREPOINT_DRIVE_ID. Il valore è elencato nel campo id nella risposta JSON.

Individuare l'ID di una cartella specifica

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

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

  • Trova l'oggetto che corrisponde al nome della cartella selezionata nella risposta JSON 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