Knowledge Catalog meta verileriyle veri temeli oluşturma

1. Giriş

Üretken yapay zeka modelleri güçlü muhakeme yeteneğine sahip olsa da kurumsal bağlamdan yoksundur. Bir yönetici, yapay zeka aracısına "1. çeyrek gelirimiz ne kadar?" diye sorarsa aracı, veri gölünüzde "gelir" adlı düzinelerce tablo bulabilir. Bazıları titizlikle hazırlanmış finansal raporlar, bazıları gerçek zamanlı pazarlama tahminleri, birçoğu ise muhtemelen desteği sonlandırılmış sanal alanlardır.

Açık temellendirme olmadan, yapay zeka aracısı basit ad benzerliğine dayalı olarak bir tablo seçer. Bu da doğrulanmamış verilerden elde edilen "inandırıcı bir şekilde yanlış" yanıtlara yol açar.

Bu codelab, yönetime uygun bir yapay zeka aracısı oluşturmanın nasıl yapılacağını ele alan iki bölümlük serinin bir parçasıdır.

Bu ilk bölümde bir veri temeli oluşturacaksınız. BigQuery'de gerçekçi ve "dağınık" bir veri gölü oluşturacak, geçerli verileri gürültüden ayırmak için katı meta veri etiketleri (Knowledge Catalog yönleri) uygulayacak ve aracının veri yönetimi kurallarınıza sıkı sıkıya uyup uymadığını yerel olarak test etmek için Antigravity (AGY) CLI'yi kullanacaksınız.

Bu serinin ikinci bölümünde, Model Bağlam Protokolü (MCP) ve Cloud Run kullanarak yerel ajan prototipini güvenli ve kurumsal sınıf bir web uygulamasına dağıtma hakkında bilgi edinebilirsiniz. 👉 2. Bölümü okuyun

Neler öğreneceksiniz?

• Kurulum komut dosyası kullanarak gerçekçi, çok katmanlı bir veri gölü dağıtın.
• Resmi veri ürünlerini ham özel korumalı alan tablolarından ayırt etmek için Knowledge Catalog'da özel meta veri şablonları (yön türleri) tasarlayın ve kaydedin.
• Uygulama kodu yazmadan önce AGY CLI'yı kullanarak veri yönetimi kurallarını yerel olarak doğrulayın.

İhtiyacınız olanlar

• Faturalandırmanın etkin olduğu bir Google Cloud projesi.
• Google Cloud Shell'e erişim (AGY CLI, Cloud Shell'de önceden yüklenmiştir).
• BigQuery ve Knowledge Catalog hakkında temel düzeyde bilgi sahibi olmak ve bu araçları kullanabilmek.

Temel kavramlar

• Knowledge Catalog: Birleştirilmiş meta veri yönetimi hizmeti. Bu bilgileri, teknik meta verileri (şemalar) iş bağlamıyla (yönetim) zenginleştirmek için kullanırız.
• Özellik Türü: Yapılandırılmış bir meta veri şablonu. Serbest metin etiketlerinin aksine, yönler güçlü türleri zorunlu kılar (numaralandırılmış türler, boole değerleri). Bu sayede, makine değerlendirmesi için güvenilir hale gelirler.

2. Kurulum ve şartlar

Cloud Shell'i Başlatma

Google Cloud, dizüstü bilgisayarınızdan uzaktan çalıştırılabilir ancak bu codelab'de Cloud'da çalışan bir komut satırı ortamı olan Google Cloud Shell'i kullanacaksınız.

Google Cloud Console'da sağ üstteki araç çubuğunda Cloud Shell simgesini tıklayın:

Ortamın temel hazırlığı ve bağlantı kurulması yalnızca birkaç dakikanızı alır. İşlem tamamlandığında aşağıdakine benzer bir sonuç görürsünüz:

Bu sanal makine, ihtiyaç duyacağınız tüm geliştirme araçlarıyla birlikte gelir. 5 GB boyutunda kalıcı bir ana dizin sunar ve Google Cloud üzerinde çalışır. Bu sayede ağ performansı ve kimlik doğrulama önemli ölçüde güçlenir. Bu codelab'deki tüm çalışmalarınızı tarayıcıda yapabilirsiniz. Herhangi bir şey yüklemeniz gerekmez.

Ortamı başlatma

Cloud Shell'i açın ve tüm komutların doğru altyapıyı hedeflediğinden emin olmak için proje değişkenlerinizi ayarlayın.

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

API'leri etkinleştir

Aşağıdaki talimatı uygulamak için gerekli Google Cloud hizmetlerini etkinleştirin.

gcloud services enable \
  bigquery.googleapis.com \
  dataplex.googleapis.com

Depoyu klonlama

Altyapı kodunu ve otomasyon komut dosyalarını GitHub deposundan alın. Cloud Shell'de disk alanından tasarruf etmek için yalnızca bu laboratuvar için gereken klasörü indireceğiz.

# Perform a shallow clone to get only the latest repository structure without the full history
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
# Specify and download only the folder we need for this lab
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

"Dağınık" veri gölünü oluşturma

Gerçek dünyadaki veri ortamları nadiren temizdir. Gerçekliği simüle etmek için "resmi" veri pazarları ve güvenilmeyen "sandbox" tablolarının bir karışımına ihtiyacımız var.

BigQuery veri kümelerini ve tablolarını dağıtmak için bir kurulum komut dosyası kullanacağız.

1. Kurulum komut dosyasını çalıştırılabilir hale getirin ve çalıştırın. Bu işlem, üç BigQuery veri kümesi (finance_mart, marketing_prod, analyst_sandbox) oluşturur ve tablolarını örnek verilerle doldurur.

chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

Kontrol noktası: Artık tamamen doldurulmuş ancak tamamen yönetilmeyen bir veri gölünüz var. Yapay zeka için her tablo tamamen aynı görünür.

3. Veri yönetimi şablonunu (aspect türü) oluşturma

Şimdi bazı veri yönetimi kurallarını tanımlayacağız. Bilgi Kataloğu'nda bu işlem, yeniden kullanılabilir ve kesin olarak türü belirlenmiş bir meta veri şablonu olan aspect türü oluşturularak yapılır.

Bu şablonu gcloud KSA'yı kullanarak kaydedeceğiz. Böylece, şablonun nasıl tanımlandığını görebilirsiniz.

Yön şemasını inceleme

Şema tanımını görmek için aspect_template.json içeriğini çıktı olarak verin.

cat aspect_template.json

Aşağıdaki JSON yapısını gösterir:

{
  "name": "OfficialDataProductSpec",
  "type": "record",
  "recordFields": [
    {
      "name": "product_tier",
      "type": "enum",
      "enumValues": [
        { "name": "GOLD_CRITICAL", "index": 1 },
        { "name": "SILVER_STANDARD", "index": 2 },
        { "name": "BRONZE_ADHOC", "index": 3 }
      ],
      ...
    },
    {
      "name": "is_certified",
      "type": "bool",
      ...
    }
  ]
}

Bu şemanın, önem derecesi katmanı (GOLD_CRITICAL, SILVER_STANDARD, BRONZE_ADHOC) için enum ve is_certified için bool gibi katı veri türlerini nasıl zorunlu kıldığına dikkat edin. Bu sayede meta veriler yapılandırılmış ve makine tarafından okunabilir durumda kalır.

Görünüm türünü kaydetme

Bu şablonu Bilgi Kataloğu kayıt otoritesi kayıt defterinize kaydettirmek için aşağıdaki gcloud komutunu çalıştırın.

gcloud dataplex aspect-types create official-data-product-spec \
    --location="${REGION}" \
    --project="${PROJECT_ID}" \
    --description="Defines the comprehensive profile of a data product for governance agents." \
    --display-name="Official Data Product Spec" \
    --metadata-template-file-name="aspect_template.json"

4. Yönetişim uygulama

Bu, kritik mühendislik adımıdır. Şu anda finance_mart.fin_monthly_closing_internal ve analyst_sandbox.tmp_data_dump_v2_final_real tabloları, LLM için aynı görünüyor. Bunlar yalnızca sütunları olan nesnelerdir.

Yönetim mühendisi olarak, bu tabloları ayırt etmek için bunlara bir aspect (sertifikalı meta veri etiketi) eklemeniz gerekir. Gerçek bir işletmede bu işlemi CI/CD ardışık düzenleri aracılığıyla otomatikleştirirsiniz. Bu otomasyonu komut dosyalarıyla simüle edeceğiz.

Yönetim yükleri oluşturma

Bilgi Kataloğu yönü anahtarları genel olarak benzersiz olmalıdır (proje kimliğinizle öneklenmiş). ./generate_payloads.sh komut dosyası, YAML meta veri dosyalarını dinamik olarak oluşturur.

chmod +x ./generate_payloads.sh
./generate_payloads.sh

Çıkış:

Bu işlem, yönetim senaryolarını (Altın/Dahili, Altın/Herkese Açık, Gümüş/Anlık, Bronz/Sandbox) tanımlayan 4 YAML dosyası içeren "./aspect_payloads" adlı bir klasör oluşturur.

KSA ile yönleri uygulama

Komut dosyasını çalıştırmadan önce, süreci netleştirmek için aslında ne uyguladığımıza bakalım. Dahili finans yükünün yapısını görmek için aşağıdaki komutu çalıştırın:

cat aspect_payloads/fin_internal.yaml

Aşağıdaki içerikler gösterilir.

your-project-id.us-central1.official-data-product-spec:
  data:
    product_tier: GOLD_CRITICAL
    data_domain: FINANCE
    usage_scope: INTERNAL_ONLY
    update_frequency: DAILY_BATCH
    is_certified: true

Bu YAML'nin, is_certified: true işaretini ayarlama ve GOLD_CRITICAL katmanını atama gibi işletme bağlamını nasıl açıkça tanımladığına dikkat edin. LLM'ye yalnızca tablo adlarına göre tahmin etmek yerine değerlendirebileceği net ve yapılandırılmış kurallar verilir.

Şimdi uygulama komut dosyasını çalıştırın. Bu, BigQuery tablolarında yinelenir ve bu katı meta verileri eklemek için gcloud dataplex entries update komutunu yürütür.

chmod +x ./apply_governance.sh
./apply_governance.sh

Doğrulama (isteğe bağlı)

Devam etmeden önce meta verilerin konsolda doğru şekilde uygulandığını doğrulayın.

1. Google Cloud Console'da Knowledge Catalog sayfasını açın. Sol gezinme menüsünde "Knowledge Catalog"u görmüyorsanız Google Cloud Console penceresinin üst kısmındaki arama çubuğunu kullanın, "Knowledge Catalog" yazın ve "En iyi sonuçlar" veya "Ürünler ve Sayfalar" bölümündeki sonucu seçin.
2. fin_monthly_closing_internal araması. Sonuçlarda BigQuery tablosunu görmeniz gerekir. Ayrıntılar sayfasına girmek için tablo adını tıklayın.

3. Tablonun ayrıntılar sayfasında, en alttaki "İsteğe bağlı etiketler ve yönler" bölümünü bulun.
4. official-data-product-spec yönünü bulabilirsiniz. Değerlerin, uyguladığımız "Gold Internal" senaryosuyla eşleştiğini doğrulayın.

Artık teknik olarak aynı olan BigQuery tablolarının (fin_monthly_closing_internal ve tmp_data_dump_v2_final_real) makine tarafından okunabilir meta verilerle mantıksal olarak farklılaştırıldığını onayladınız.

5. Aracıyı yapılandırma ve prototipini oluşturma

Bir uygulama oluşturmadan önce (Bölüm 2'de yapacağız) veri yönetimi mantığımızı yerel olarak doğrulayacağız. Knowledge Catalog eklentisini yüklememiz ve Agent Skill'i yapılandırmamız gerekiyor.

Uzantıyı yükleme

Cloud Shell'de Knowledge Catalog eklentisini yükleyin. Onayınızı ve kurulum ayrıntılarınızı ister.

export DATAPLEX_PROJECT="${PROJECT_ID}"

agy plugin install https://github.com/gemini-cli-extensions/dataplex

Ajan becerisini inceleme

Müşteri temsilcisi becerisi, .agents/skills/knowledge_catalog_governance/SKILL.md konumunda bulunan statik ve yeniden kullanılabilir bir tanım dosyasıdır. Soyut insan kurallarını (ör. "Güvenli verilere ihtiyacım var") katı teknik aramalara çeviren mantığı içerir.

Yapay zekaya öğrettiğimiz algoritmayı anlamak için dosyayı inceleyin:

cat .agents/skills/knowledge_catalog_governance/SKILL.md

Bu istemin, modele kesinlikle 1. Aşama (Meta Veri Doğrulaması) ve 2. Aşama (Sorgu Yürütme) döngüsünü izlemesi talimatını verdiğini unutmayın. Model, herhangi bir SQL oluşturmadan önce meta verileri bulmalı ve doğrulamalıdır.

Aracıyı başlatma ve senaryoları test etme

AGY KSA oturumunu başlatın. Bu işlem, beceriyi .agents/skills dizininden otomatik olarak bulup yükler.

agy

Not: Birden fazla bağlam dosyasının yüklendiğini görebilirsiniz. Normal bir durumdur. CLI, bu projenin belirli kuralları için yerel beceriyi ve Bilgi Kataloğu eklentisinin varsayılan talimatlarını yükler.

Yüklemeyi doğrula

Bilgi Kataloğu eklentisinin etkin olduğunu onaylamak için /mcp yazın. knowledge-catalog, kullanılabilir araçlarıyla birlikte etkin bir eklenti olarak listelenir.

/mcp

Beklenen çıkış:

MCP Servers
...
>  ✓ knowledge-catalog  Tools: search_entries, lookup_context, lookup_entry

Test senaryoları (prototip oluşturma)

Kurallarınıza uyduğunu doğrulamak için aşağıdaki istemleri çalışan aracı oturumuna tek tek yapıştırın.

💡 İpucu: İstenirse "2. Evet ve sorunsuz test için "knowledge-catalog/search_entries"nin bu görüşmede her zaman kullanılmasına izin verin.

• A senaryosu (CFO'nun verilerini onaylama):

"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"

Beklenen: Temsilci, araçlarından etkin projenizi ve bölgenizi otomatik olarak keşfeder, fin_monthly_closing_internal sorgusunu gönderir çünkü GOLD_CRITICAL (doğru) ve INTERNAL_ONLY (toplantı) ile Anlam (Aspect) açısından eşleşir ve bunu önerir.

• B senaryosu (herkese açık ifşa):

"I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?"

Beklenen: Ajan, aylık dahili tabloyu atlamalı ve fin_quarterly_public_report'yi kesinlikle seçmelidir. Çünkü EXTERNAL_READY ile etiketlenen tek öğe budur.

• C senaryosu (operasyonel ihtiyaçlar):

"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"

Beklenen: Temsilci, mkt_realtime_campaign_performance seçeneğini belirler. Çünkü bu seçenek, REALTIME_STREAMING güncelleme sıklığını tanımlar ve finans verilerinin GOLD_CRITICAL katmanına göre önceliklendirir.

• D senaryosu (korumalı alan denemesi):

"I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment."

Beklenen: Ajan, tmp_data_dump_v2_final_real seçeneğini belirler. Çünkü bu seçenek, Aspect'teki BRONZE_ADHOC (ham veriler) ve is_certified: false (sandbox ortamı) ile anlamsal olarak eşleşir.

(AGY oturumundan çıkmak için /exit veya /quit yazın)

6. Tebrikler! Sırada ne var?

Yönetilen bir veri temeli oluşturmayı başardınız ve yerel bir CLI prototipi kullanarak yapay zekanın meta veri kurallarınıza sıkı sıkıya uyabileceğini kanıtladınız.

Artık bir kontrol noktasına ulaştınız. Lütfen sonraki adımınızı seçin:

A seçeneği: Hemen 2. Bölüm'e geçmek istiyorum.

Bu yerel prototipi Model Bağlam Protokolü (MCP) ve Cloud Run kullanarak güvenli, üretime hazır bir web uygulamasına dönüştürmeye hazırsanız:

👉 2. Bölüm Codelab'inin bağlantısı

⚠️ DURDUR: Aşağıdaki temizleme adımlarını çalıştırmayın. 2. bölüm için mevcut verilerinize ve Bilgi Kataloğu ayarlarınıza ihtiyacınız var.

B seçeneği: 2. bölümü daha sonra yapacağım veya yalnızca 1. bölümü tamamlamak istiyordum.

Bugün durmak ve bulut maliyetlerinden kaçınmak istiyorsanız kaynaklarınızı temizlemeniz gerekir.

Merak etmeyin! 2. bölümde, 1. bölümdeki ortamı yalnızca 2 dakikada tamamen yeniden oluşturacak bir "Hızlı İzleme Komut Dosyası" sunacağız. Böylece tam olarak kaldığınız yerden devam edebilirsiniz.

👉 Temizleme bölümüne gidin.

7. Temizleme (yalnızca B seçeneği için)

Burada duruyorsanız ücretlendirilmemek için kaynakları yok edin.

Veri gölünü kaldırma

Şu anda AGY CLI oturumundaysanız Ctrl+C tuşuna iki kez basarak veya /quit yazarak oturumdan çıkın. Ardından, aşağıdaki komutları çalıştırın:

chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh

AGY CLI eklentisini kaldırın ve yerel dosyaları silin

agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos