Menggunakan penyerapan data dengan RAG Engine

Halaman ini menjelaskan cara melakukan penyerapan data menggunakan sumber data yang didukung, seperti Cloud Storage, Google Drive, Slack, Jira, atau SharePoint, dan cara menggunakan data tersebut dengan RAG Engine. Metode ragFiles.import menyediakan konektor data ke sumber data ini.

Sumber data yang didukung untuk RAG

Sumber data berikut didukung:

  • Mengupload file lokal: Upload file tunggal menggunakan upload_file (hingga 25 MB), yang merupakan panggilan sinkron.
  • Cloud Storage: Mengimpor file dari Cloud Storage.

  • Google Drive: Mengimpor direktori dari Google Drive.

    Akun layanan harus diberi izin yang benar untuk mengimpor file. Jika tidak, tidak ada file yang diimpor dan tidak ada pesan error yang ditampilkan. Untuk mengetahui informasi selengkapnya tentang batas ukuran file, lihat Jenis dokumen yang didukung.

    Untuk mengautentikasi dan memberikan izin, lakukan hal berikut:

    1. Buka halaman IAM project Google Cloud Anda.
    2. Pilih Sertakan pemberian peran yang disediakan Google.
    3. Telusuri akun layanan Agen Layanan Data RAG Platform Agen.
    4. Klik Bagikan di folder Drive, lalu bagikan dengan akun layanan.
    5. Berikan izin Viewer ke akun layanan di folder atau file Google Drive Anda. ID resource Google Drive dapat ditemukan di URL web.

  • Slack: Mengimpor file dari Slack menggunakan konektor data.

  • Jira: Mengimpor file dari Jira menggunakan konektor data.

Penghapusan duplikat data

Jika file yang sama diimpor beberapa kali tanpa perubahan, file tersebut akan dilewati karena sudah ada. Oleh karena itu, response.skipped_rag_files_count mengacu pada jumlah file yang dilewati selama proses impor.

File dilewati jika kondisi berikut terpenuhi:

  • File telah diimpor.
  • File tidak berubah.
  • Konfigurasi chunking untuk file tidak berubah.

Memahami kegagalan impor

Untuk memahami kegagalan impor, bagian ini menjelaskan metadata dalam respons terhadap permintaan impor dan data sink, yang merupakan tujuan untuk data yang Anda impor.

Metadata respons

Anda dapat menggunakan response.metadata (objek respons di SDK) untuk melihat hasil impor, waktu permintaan, dan waktu respons.

Sink hasil impor

Di SDK, import_result_sink adalah parameter fungsi opsional yang dapat ditetapkan ke nilai string yang valid.

Jika import_result_sink disediakan, hasil file yang berhasil dan gagal akan ditulis ke sink. Dengan semua hasil yang ditulis ke sink, Anda dapat lebih mudah memahami alasan beberapa file mungkin gagal diimpor dan file mana yang tidak diimpor.

import_result_sink harus berupa jalur Cloud Storage atau tabel BigQuery.

  • Jika import_result_sink adalah jalur Cloud Storage, jalur tersebut harus menggunakan format gs://my-bucket/my/object.ndjson, dan objek tidak boleh ada. Setelah tugas impor selesai, setiap baris objek Cloud Storage berisi objek JSON, yang memiliki ID operasi, stempel waktu pembuatan, nama file, status, dan ID file.

  • Jika import_result_sink adalah tabel BigQuery, tabel tersebut harus menggunakan format bq://my-project.my-dataset.my-table. Tabel tidak harus ada. Jika tidak ada, tabel akan dibuat. Jika tabel ada, skemanya akan diverifikasi. Saat pertama kali sink hasil impor BigQuery disediakan, Anda akan menyediakan tabel yang tidak ada; jika tidak, Anda dapat menggunakan kembali tabel yang ada.

Mengimpor file dari Cloud Storage atau Google Drive

Untuk mengimpor file dari Cloud Storage atau Google Drive ke dalam korpus, lakukan hal berikut:

  1. Buat korpus RAG. Untuk mengetahui informasi selengkapnya, lihat Metode: ragCorpora.create.

  2. Untuk mengimpor file dari Cloud Storage atau Google Drive, gunakan metode ragFiles.import.

    Sistem akan otomatis memeriksa jalur, nama file, dan version_id file Anda. version_id adalah hash file yang dihitung menggunakan konten file, yang mencegah file diindeks ulang.

    Jika file dengan nama file dan jalur yang sama memiliki update konten, file tersebut akan diindeks ulang.

Mengimpor file dari Slack

Untuk mengimpor file dari Slack ke dalam korpus, lakukan hal berikut:

  1. Buat korpus, yang merupakan indeks yang menyusun dan mengoptimalkan data Anda untuk penelusuran. Untuk mengetahui informasi selengkapnya, lihat Metode: ragCorpora.create.
  2. Dapatkan CHANNEL_ID dari ID saluran Slack.
  3. Buat dan siapkan aplikasi untuk digunakan dengan RAG Engine.
    1. Dari UI Slack, di bagian Tambahkan fitur dan fungsi, klik Izin.
    2. Tambahkan izin berikut:
      • channels:history
      • groups:history
      • im:history
      • mpim:history
    3. Klik Instal ke Ruang Kerja untuk menginstal aplikasi ke ruang kerja Slack Anda.
  4. Klik Salin untuk mendapatkan token API, yang mengautentikasi identitas Anda dan memberi Anda akses ke API.
  5. Tambahkan token API ke Secret Manager Anda.
  6. Untuk melihat secret yang disimpan, berikan peran Secret Manager Secret Accessor ke akun layanan RAG Engine project Anda.

Contoh kode curl dan Python berikut menunjukkan cara mengimpor file dari resource Slack Anda.

curl

Jika Anda ingin mendapatkan pesan dari saluran tertentu, ubah 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

Jika Anda ingin mendapatkan pesan untuk rentang waktu tertentu atau dari saluran tertentu, ubah salah satu kolom berikut:

  • START_TIME
  • END_TIME
  • CHANNEL1 atau 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,
    )

Mengimpor file dari Jira

Untuk mengimpor file dari Jira ke dalam korpus, lakukan hal berikut:

  1. Buat korpus, yang merupakan indeks yang menyusun dan mengoptimalkan data Anda untuk penelusuran. Untuk mengetahui informasi selengkapnya, lihat Metode: ragCorpora.create.

  2. Untuk membuat token API, login ke situs Atlassian.

  3. Gunakan {YOUR_ORG_ID}.atlassian.net sebagai SERVER_URI dalam permintaan.

  4. Gunakan email Atlassian Anda sebagai EMAIL dalam permintaan.

  5. Berikan projects atau customQueries dengan permintaan Anda. Untuk mempelajari kueri kustom lebih lanjut, lihat Menggunakan penelusuran lanjutan dengan Jira Query Language (JQL).

    Saat Anda mengimpor projects, projects akan diperluas ke dalam kueri yang sesuai untuk mendapatkan seluruh project. Misalnya, MyProject diperluas menjadi project = MyProject.

  6. Klik Salin untuk mendapatkan token API, yang mengautentikasi identitas Anda dan memberi Anda akses ke API.

  7. Tambahkan token API ke Secret Manager Anda.

  8. Berikan peran Secret Manager Secret Accessor ke akun layanan RAG Engine project Anda.

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

Mengimpor file dari SharePoint

Untuk mengimpor file dari situs SharePoint ke dalam korpus, lakukan hal berikut:

  1. Buat korpus, yang merupakan indeks yang menyusun dan mengoptimalkan data Anda untuk penelusuran. Untuk mengetahui informasi selengkapnya, lihat Metode: ragCorpora.create.

  2. Buat aplikasi Azure untuk mengakses situs SharePoint Anda.

    1. Untuk membuat pendaftaran, buka Pendaftaran Aplikasi.

      1. Berikan nama untuk aplikasi.

      2. Pilih opsi, Akun di direktori organisasi ini saja.

      3. Pastikan URI pengalihan kosong.

    2. Di bagian Ringkasan, gunakan ID Aplikasi (klien) sebagai CLIENT_ID, dan gunakan "ID Direktori (tenant)" sebagai TENANT_ID.

    3. Di bagian Kelola, perbarui izin API dengan melakukan hal berikut:

      1. Tambahkan izin Sites.Read.All SharePoint.

      2. Tambahkan izin Files.Read.All dan Browser SiteLists.Read.All Microsoft Graph.

      3. Berikan izin admin agar perubahan izin ini diterapkan.

    4. Di bagian Kelola, lakukan hal berikut:

      1. Perbarui Sertifikat dan Secret dengan secret klien baru.

      2. Gunakan API_KEY_SECRET_VERSION untuk menambahkan secret nilai ke Secret Manager.

  3. Berikan peran Secret Manager Secret Accessor ke akun layanan RAG Engine project Anda.

  4. Gunakan {YOUR_ORG_ID}.sharepoint.com sebagai SHAREPOINT_SITE_NAME.

  5. Nama drive atau ID drive di situs SharePoint harus ditentukan dalam permintaan.

  6. Opsional: Jalur folder atau ID folder di drive dapat ditentukan. Jika jalur folder atau ID folder tidak ditentukan, semua folder dan file di drive akan diimpor.

Menemukan ID Situs

  1. Buka browser Anda dan buka URL situs SharePoint target Anda.

  2. Tambahkan /_api/site/id/ ke akhir URL tersebut.

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

    Halaman ini menampilkan payload XML. Perhatikan string setelah Edm.Guid. Ini adalah ID Situs Anda.

Menemukan ID Drive

Dengan ID Situs yang Anda kumpulkan, buat permintaan GET yang diautentikasi menggunakan Microsoft Graph Explorer atau klien API Anda:

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

Dapatkan SHAREPOINT_DRIVE_ID. Nilai ini tercantum di kolom id dalam respons JSON.

Menemukan ID Folder Tertentu

Gunakan ID Drive Anda untuk mencantumkan turunan direktori root:

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

  • Temukan objek yang cocok dengan nama folder yang Anda pilih dalam respons JSON dan salin string id yang sesuai. Ini adalah SHAREPOINT_FOLDER_ID Anda.

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

Langkah berikutnya