Mengambil konteks untuk aset data

Konteks yang mengelilingi data Anda melengkapi aplikasi AI dengan pemahaman mendalam tentang aset data Anda, sehingga meningkatkan akurasi dan relevansi respons yang dihasilkan LLM.

Metode lookupContext menjembatani kesenjangan konteks menggunakan satu permintaan API untuk mengambil paket metadata aset data yang telah diformat sebelumnya dan dioptimalkan untuk alur kerja agen interaktif. Anda dapat menggunakan konteks ringkas yang siap digunakan LLM ini untuk mendasarkan agen Anda dalam menilai dan menggunakan aset data.

Anda dapat menggunakan metode lookupContext untuk aset data apa pun yang disimpan di Knowledge Catalog, misalnya, tabel BigQuery, set data, atau entri lainnya.

Cara mengambil konteks untuk aset dengan metode lookupContext

  1. Agen mengambil aset data yang berpotensi relevan untuk pengambilan konteks, misalnya, dengan menggunakan penelusuran semantik Knowledge Catalog.
  2. Agen menggunakan metode lookupContext untuk melakukan satu panggilan API atau permintaan alat MCP yang mengambil konteks untuk aset tertentu.

  3. Metode ini menampilkan respons yang berisi blok teks yang telah diformat sebelumnya. Bergantung pada parameter format yang Anda tentukan dalam permintaan, dokumen dapat berformat YAML, XML, atau JSON.

    Respons berisi elemen konteks berikut:

    Elemen konteks Deskripsi
    Metadata teknis Skema resource dan konfigurasi fisik, seperti strategi partisi dan pengelompokan BigQuery.
    Metadata operasional Gabungan dan hubungan lainnya, berdasarkan log kueri historis dan insight data. Untuk mengetahui informasi selengkapnya, lihat Melihat hubungan data.
    Deskripsi bisnis Istilah bisnis terkait, ringkasan, anotasi katalog, deskripsi yang diambil dalam sistem sumber dan dibuat secara otomatis di Knowledge Catalog, serta panduan.

    Catatan: Anda dapat menggunakan aspek panduan pada aset data untuk mengambil konteks tambahan yang berguna bagi agen saat mereka menemukan, memeriksa, atau menggunakan aset data.
    Profil data Statistik distribusi, jumlah nilai unik, rasio null, dan nilai sampel.
    Kualitas data Output pemeriksaan kualitas data otomatis terhadap aturan yang telah ditentukan.
    Konteks pada aset data terkait Konteks pada aset data terkait, seperti istilah glosarium atau aset terkait lainnya, seperti tabel yang sering digabungkan. Konteks yang ditampilkan untuk aset terkait mencakup rentang elemen yang sama seperti untuk aset utama.

  4. Agen menggunakan respons ini untuk memandu pemilihan aset yang relevan atau penggunaannya.

Sebelum memulai

Sebelum menggunakan metode lookupContext, pastikan Anda memiliki peran yang diperlukan dan mengaktifkan API yang diperlukan.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk memanggil metode lookupContext, minta administrator Anda untuk memberi Anda peran IAM berikut di Google Cloud project iam.gserviceaccount.com:

  • Akses baca ke resource katalog, termasuk entri, grup entri, dan glosarium: Dataplex Catalog Viewer (roles/dataplex.catalogViewer)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Mengaktifkan API

Untuk menggunakan metode lookupContext, aktifkan API berikut di project Anda:

  • Knowledge Catalog API

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

Mengaktifkan API

Mengambil konteks untuk aset data

Untuk mengambil konteks untuk aset data, akses metode lookupContext secara langsung dengan Dataplex API atau gunakan server Model Context Protocol (MCP) jarak jauh Knowledge Catalog atau MCP Toolbox For Databases.

Metode lookupContext memfilter resource berdasarkan izin Anda. Respons hanya berisi data untuk aset yang memiliki izin Identity and Access Management (IAM) yang diperlukan untuk diakses oleh identitas Anda. Jika Anda tidak memiliki izin untuk resource yang diminta, metode ini akan menampilkan respons kosong.

REST

Untuk mengambil konteks untuk aset data, kirim permintaan berikut:

curl --request POST \
   'https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "resources": RESOURCES
  "options": OPTIONS
  }' \
--compressed

Ganti kode berikut:

  • PROJECT_ID: ID project Anda Google Cloud
  • LOCATION: region tempat aset berada (misalnya, us-central1)
  • RESOURCES: hingga sepuluh nama entri untuk mengambil konteks, yang diformat sebagai projects/{project}/locations/{location}/entryGroups/{entryGroup}/entries/{entry}. Untuk beberapa resource, API menetapkan hubungan antara resource yang diminta, seperti gabungan skema yang sering terjadi, dan menampilkan informasi hubungan dalam konteks.
  • OPTIONS: opsi yang memungkinkan Anda menentukan konteks:
    • format adalah format file konteks. Misalnya, yaml.
    • context_budget adalah jumlah karakter yang membatasi respons. Jika Anda menetapkan parameter all_schema_fields ke true, API akan menampilkan semua kolom skema, terlepas dari nilai context_budget.

Contoh permintaan yang mengambil konteks untuk tabel BigQuery terlihat sebagai berikut:

curl --request POST \
'https://dataplex.googleapis.com/v1/projects/test-project/locations/us:lookupContext?key=[YOUR_API_KEY]' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "resources":
    ["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
    "options":
    {
      "format":"yaml",
      "context_budget":"4000"
    }
  }' \
--compressed

Responsnya adalah blok teks yang telah diformat sebelumnya dan mirip dengan hal berikut:

{
"context": "resource: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/orders\"\ntechnical_metadata:\n  schema:\n    - name: order_id\n      type: STRING\n      description: \"Primary key for the order.\"\n    - name: customer_id\n      type: STRING\n    - name: total_amount\n      type: NUMERIC\n  partitioning:\n    type: TIMESTAMP\n    field: order_date\nbusiness_descriptions:\n  overview: \"Historical record of all customer transactions.\"\n  related_terms:\n    - \"Revenue\"\n    - \"Sales Transactions\"\n  guidelines: \"Always filter by 'order_date' to optimize query costs due to partitioning.\"\ndata_profile:\n  columns:\n    - name: total_amount\n      null_ratio: 0.001\n      distinct_values: 52340\n      sample_values: [45.99, 120.00, 15.50]\ndata_quality:\n  summary:\n    - rule: \"positive_amounts\"\n      status: PASSED\n      description: \"Ensures total_amount is greater than zero.\"\noperational_metadata:\n  frequent_joins:\n    - table: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/customers\"\n      join_key: \"customer_id\"\n"
}

Python

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di panduan memulai Knowledge Catalog menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Knowledge Catalog Python API dokumentasi referensi.

Untuk melakukan autentikasi ke Knowledge Catalog, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import dataplex_v1


def sample_lookup_context():
    # Create a client
    client = dataplex_v1.CatalogServiceClient()

    # Initialize request argument(s)
    request = dataplex_v1.LookupContextRequest(
        name="name_value",
        resources=["resources_value1", "resources_value2"],
    )

    # Make the request
    response = client.lookup_context(request=request)

    # Handle the response
    print(response)

Contoh berikut menunjukkan cara mengambil konteks untuk tabel BigQuery:

 from google.cloud import dataplex_v1

 # Initialize the client
 client = dataplex_v1.CatalogServiceClient()

 # Define the request with a seed resource
 request = dataplex_v1.LookupContextRequest(
     name="projects/test-project/locations/us",
     resources=["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
     options={"format": "yaml", "budget": "4000"}
 )

 # Retrieve the LLM-ready context
 response = client.lookup_context(request=request)
 context_yaml = response.context

 print(f"Retrieved Context: \n{context_yaml}")

Praktik terbaik untuk metode lookupContext

Untuk mengoptimalkan hasil saat menggunakan metode lookupContext, pertimbangkan praktik terbaik berikut:

  • Minta panjang konteks output yang dipilih dengan parameter context_budget. Metode lookupContext akan berupaya menyesuaikan konteks yang paling relevan ke dalam output sedekat mungkin dalam batas yang ditentukan oleh parameter.
  • Anda dapat mencantumkan hingga sepuluh aset data dalam daftar resources. Misalnya, menyertakan beberapa tabel dalam daftar resources akan membuat API memberikan konteks tidak hanya untuk tabel tersebut, tetapi juga untuk kemungkinan jalur gabungan di antara tabel tersebut, sehingga memberikan panduan yang diperlukan tentang cara menggunakan tabel ini bersama-sama.
  • Gunakan opsi format, seperti yaml atau json, yang paling sesuai dengan logika penguraian LLM atau agen untuk menghindari transformasi yang mahal.

Langkah berikutnya