Utilizzare l'importazione dei dati con il motore RAG di Vertex AI

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 Vertex AI RAG Engine. L'API Import RagFiles fornisce connettori di 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 vengono importati file e non viene visualizzato alcun messaggio di errore. Per ulteriori informazioni sui limiti di dimensioni dei file, vedi Tipi di documenti supportati.

  Per autenticarti e concedere le autorizzazioni:

  1. Vai alla pagina IAM del tuo progettoGoogle Cloud .
  2. Seleziona Includi concessione di ruoli fornita da Google.
  3. Cerca il account di servizio Vertex AI RAG Data Service Agent.
  4. Fai clic su Condividi nella cartella del drive e condividila con l'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 si trova nell'URL web.

• Slack: Importa file da Slack utilizzando un connettore dati.

• Jira: Importa file da Jira utilizzando un connettore dati.

Per ulteriori informazioni, consulta il riferimento API RAG.

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 si verificano le seguenti condizioni:

• Il file è stato importato.
• Il file non è cambiato.
• 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 data sink, 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 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 BigQuery, devi fornire una tabella inesistente; altrimenti, puoi riutilizzare la tabella esistente.

Importare file da Cloud Storage o Google Drive

Per importare file da Cloud Storage o Google Drive nel corpus, procedi nel seguente modo:

1. Crea un corpus seguendo le istruzioni riportate in Creare un corpus RAG.

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

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

   Se un file con lo stesso nome e percorso viene aggiornato, viene reindicizzato.

Importare file da Slack

Per importare file da Slack nel tuo corpus:

1. Crea un corpus, ovvero un indice che struttura e ottimizza i dati per la ricerca. Segui le istruzioni riportate in Creare un corpus RAG.
2. Recupera il tuo CHANNEL_ID dall'ID canale Slack.
3. Crea e configura un'app da utilizzare con il motore RAG di Vertex AI.
   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 in 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 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 Vertex AI RAG Engine del tuo progetto.

I seguenti esempi di codice curl e Python mostrano come importare file dalle risorse 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,
    )

Importare file da Jira

Per importare file da Jira nel tuo corpus, procedi nel seguente modo:

1. Crea un corpus, ovvero un indice che struttura e ottimizza i dati per la ricerca. Segui le istruzioni riportate in Creare un corpus RAG.
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, consulta 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 a project = MyProject.

6. Fai clic su Copia per ottenere 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 Vertex AI RAG Engine del tuo progetto.

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

Importare file da SharePoint

Per importare file dal tuo sito SharePoint nel corpus:

1. Crea un corpus, ovvero un indice che struttura e ottimizza i dati per la ricerca. Segui le istruzioni riportate in Creare un corpus RAG.
2. Crea un'app Azure per accedere al tuo sito SharePoint.
   1. Per creare una registrazione, vai a App Registrations (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 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 Vertex AI 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 della cartella o un ID cartella su Drive. Se non viene specificato il percorso della cartella o l'ID cartella, vengono importate tutte le cartelle e i file sull'unità.

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

Passaggi successivi

• Scelte di database vettoriale in Vertex AI RAG Engine