Gemini ve Knowledge Catalog ile yapılandırılmamış karanlık verileri yönetme

1. Giriş

Kurumsal verilerin% 80'inden fazlası yapılandırılmamış biçimlerde (PDF mühendislik kılavuzları, standart operasyon prosedürleri (SOP'ler), uygunluk sertifikaları ve Cloud Storage'da depolanan ekipman şemaları) bulunur. Geleneksel kataloglar yalnızca ilişkisel tablo şemalarını dizine eklediğinden bu belgeler "Karanlık Veri" olarak kalır: kurumsal arama tarafından görünmez, yapılandırılmış envanter tablolarından bağlantısı kesilmiş ve düzenleyici kurumun belirlediği kurallara uygunluk açısından doğrulanmamış.

Bir denetçi veya yapay zeka aracısı "Hangi donanım SKU'ları UL-153 güvenlik sertifikası gerektiriyor ve bunların termal tehlike seviyeleri nelerdir?" diye sorduğunda yalnızca SQL tablolarını dizine ekleyen bir katalog yanıt veremez. Bilgiler, Cloud Storage'daki yapılandırılmamış PDF'lerde kilitlenmiştir.

Mimari çözüm: kod olarak çok formatlı üst veriler

Bu codelab'de, Google Cloud'da uçtan uca bir Metadata-as-Code ardışık düzeni oluşturacaksınız. Bu ardışık düzen, Gemini Enterprise Agent Platform (Google GenAI SDK, google-genai) kullanarak Cloud Storage'daki yapılandırılmamış PDF kılavuzlarını şema zorunlu Knowledge Catalog öğelerine dönüştürür:

Yapılandırılmamış Karanlık Veri Yönetimi Akışı

  1. Dosya kümesi kaydı (EntryGroup & Entry): Cloud Storage'daki yapılandırılmamış PDF'leri Knowledge Catalog'da yönetilen mantıksal dosya kümesi girişleri olarak gruplandırır.
  2. Çok Formatlı Gemini ile Ayıklama (Pydantic Şeması): response_schema doğrulamasıyla ham PDF baytlarında Gemini Enterprise Agent Platform'u çağırır.
  3. Kontrol düzlemi yönü bağlama: Doğrulanmış operasyonel ve uygunluk JSON yüklerini, katalog girişinde kesin olarak türlenmiş Aspect örnekleri olarak ekler.
  4. Birleşik Katalog Keşfi: Yapılandırılmamış PDF dosya kümelerinin ve ayıklanan meta verilerinin SearchEntriesRequest üzerinden keşfedilmesini sağlar.

Temel kavramlar: Bilgi Kataloğu kontrol düzlemi temel öğeleri

Ekibinizin, yüzlerce PDF ürün kılavuzunu Cloud Storage'da sakladığını düşünün. Bu dosyaları Bilgi Kataloğu'nda kolayca bulup inceleyebilmek için beş yapı taşını, ofis dosya dolabında kağıt kılavuzları düzenlemeye benzetebilirsiniz:

  • EntryGroup (Bir ekip için kilitli dolap): Kilitli bir dolap. Yalnızca izni olan ekip arkadaşları (roles/dataplex.entryCreator) klasörleri içine yerleştirebilir. Dolabı kaldırabilmek için önce dolaptaki tüm klasörleri boşaltmanız gerekir.
  • EntryType (Klasör kategorisi etiketi): Klasörün ne türde bir öğeyi temsil ettiğini kullanıcılara bildiren etiket. Örneğin, "Veritabanı Tablosu" yerine "PDF Kılavuz Koleksiyonu".
  • Entry (Depolama bağlantısı içeren bir dosya klasörü): PDF kılavuzlarınızın bulunduğu katalog klasörü. Klasör, ağır kağıt kopyaları tutmak yerine gerçek PDF dosyalarının bulunduğu tam Cloud Storage paketine (gs://...) yönlendiren bir konum kartı içerir.
  • AspectType (Boş bir kontrol listesi formu): Önceden yazdırılmış kutular içeren, yeniden kullanılabilir boş bir form (örneğin, metin olarak operational_hazard_level ve 0.0 ile 1.0 arasında bir sayı olarak confidence_score isteyen bir "Güvenlik Kontrol Listesi"). Bu boş formu bir kez oluşturup binlerce klasörde yeniden kullanabilirsiniz.
  • Aspect (Bir klasöre eklenmiş, doldurulmuş bir kontrol listesi): Gemini Enterprise Agent Platform, PDF kılavuzu okuyup boşlukları doldurduktan sonra tamamlanan kontrol listesi Entry klasörüne eklenir. Her kontrol listesinin kendi anahtarı (aspect_keys) olduğundan mühendislik ekibi ve hukuk ekibi, birbirlerinin çalışmalarını üzerine yazmadan aynı klasöre kendi kontrol listelerini ekleyebilir.

Beş bölgesel kaynağın tümü projects/{project}/locations/{location}/ altında yer alır:

Temel ve Göreli Yol

Bilgi Kataloğu'ndaki rol

Silme ve IAM Kuralı

EntryGroup
.../entryGroups/{id}

Girişleri gruplandıran ve ekip erişimini kontrol eden mantıksal kapsayıcı (roles/dataplex.entryCreator).

Silme işleminden önce sıfır alt Entry kaynağı içermelidir.

EntryType
.../entryTypes/{id}

Bir varlık sınıfının (entry.entry_type, örneğin yapılandırılmamış PDF dosya kümeleri) kategori tanımı.

Yalnızca bu türü kullanan tüm girişler kaldırıldıktan sonra silin.

Entry (Dosya kümesi)
.../entries/{entry_id}

Fiziksel bir Cloud Storage URI'sini (entry_source.resource) mantıksal bir ada (gcs:{bucket}) bağlayan katalog kaydı.

EntryGroup içinde yer alır ve eklenmiş Aspect kayıtlarını içerir.

AspectType
.../aspectTypes/{id}

Yazılan record_fields (string, enum, double) ve 1 tabanlı alan numaralarını (index) tanımlayan, yeniden kullanılabilir şema şablonu.

Her bölge için bir kez oluşturulur ve girişler arasında paylaşılır.

Aspect
Entry.aspects[key]

AspectType ile eşleşen, doğrulanmış JSON meta verileri, UpdateEntryRequest aracılığıyla Entry'ye eklenmiş.

update_mask ve aspect_keys kullanılarak güncellendi. Böylece ayrı işlem hatları birbirinin üzerine yazılmaz.

Ne oluşturacaksınız?

codelabs/metadata-as-code-lab içindeki yardımcı komut dosyalarını kullanarak 7 aşamalı bir işlem hattını çalıştırıp inceleyeceksiniz:

  1. schemas.py: Bilgi Kataloğu AspectType şablonlarıyla 1:1 eşleştirilmiş BaseModel çift Pydantic şeması (DarkDataExtractedMetadata ve DocumentGovernanceMetadata).
  2. step2_provision.py — Özel EntryGroup, EntryType ve AspectType planlarının idempotent olarak sağlanması.
  3. step3_register_fileset.py — LUM-LIG-DES-8G8J_manual.pdf öğesinin Cloud Storage'a yüklenmesi ve yönetilen bir Fileset olarak kaydedilmesi Entry.
  4. step4_extract_metadata.py — google-genai kullanılarak dinamik amiral gemisi Gemini modeli keşfi ve çok formatlı PDF ayıklama.
  5. step5_attach_aspects.py, step6_search_catalog.py ve step7_verify_assertions.py: Cerrahi yön eki, üstel geri çekilme katalog araması ve uçtan uca kontrol düzlemi onayları.

Ön koşullar ve ihtiyacınız olanlar

  • Faturalandırmanın etkinleştirildiği bir Google Cloud projesi ve Google Cloud Shell (gcloud, git, python3 ve pip önceden yüklenmiş olmalıdır).
  • Knowledge Catalog kaynaklarını (roles/dataplex.admin) yönetmek, Cloud Storage paketlerini ve nesnelerini (roles/storage.admin) sağlamak ve Gemini Enterprise Agent Platform'u (roles/aiplatform.user) çağırmak için IAM izinleri.
  • Google Chrome gibi bir web tarayıcısı

2. Kurulum ve şartlar

Cloud Shell'de yardımcı depoyu klonlayın.

Google Cloud Console'u açın, Cloud Shell'i başlatın ve örnek PDF mühendislik kılavuzunu (LUM-LIG-DES-8G8J_manual.pdf) ve tüm Python komut dosyalarını içeren codelabs/metadata-as-code-lab için seyrek bir ödeme işlemi gerçekleştirin:

git clone --branch main --depth 1 --filter=blob:none --sparse \
  https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
git sparse-checkout set codelabs/metadata-as-code-lab
cd codelabs/metadata-as-code-lab
ls -la

Ortam değişkenlerini yapılandırma

Cloud Shell'de proje kimliğinizi, bölgesel kontrol düzlemi konumunuzu ve hedef Cloud Storage paketini ayarlayın:

export PROJECT_ID="${PROJECT_ID:-$(gcloud config get-value project)}"
gcloud config set project $PROJECT_ID

export REGION="us-central1"
export BUCKET_NAME="${PROJECT_ID}-dark-data-manuals"
export GEMINI_LOCATION="global"

echo "Configured Project ID        : $PROJECT_ID"
echo "Knowledge Catalog Region     : $REGION"
echo "Gemini Endpoint Location     : $GEMINI_LOCATION"
echo "Target Cloud Storage Bucket  : $BUCKET_NAME"

API'leri etkinleştirme ve bağımlıları yükleme

Gerekli Google Cloud API'lerini etkinleştirin ve requirements.txt adresinden Python bağımlılıklarını (google-genai, google-cloud-dataplex, pydantic ve pandas) yükleyin:

gcloud services enable \
  dataplex.googleapis.com \
  storage.googleapis.com \
  aiplatform.googleapis.com \
  --quiet

python3 -m pip install --upgrade --quiet --user --break-system-packages -r requirements.txt

3. Pydantic şemalarını ve yön şablonlarını tanımlama

schemas.py, istemci tarafı Pydantic doğrulamasını sunucu tarafı Knowledge Catalog AspectType şablonlarıyla eşleştiren iki tamamlayıcı sözleşme tanımlar:

  1. DarkDataExtractedMetadata: PDF'den (belge başlığı, alan ontolojisi, güvenlik tehlikesi düzeyi, yazarlık/sürüm kaynağı, yönetici özeti ve çıkarma güven puanı) çıkarılan operasyonel özellikler.
  2. DocumentGovernanceMetadata: Düzenleyici kurumun belirlediği kurallara uygunluk kodları (UL-153, FCC Part 15, CE-LVD, RoHS), gözetim sahibi, saklama politikası ve PDF kılavuzunu aşağı akış envanter tablolarına bağlamak için bir referans tablosu tanımlayıcı dizesi (lakehouse_cross_ref_table).

İncele schemas.py

First, DarkDataExtractedMetadata, Gemini Enterprise Agent Platform'un JSON çıkışını kısıtlamak için Field kısıtlamalarını (ge=0.0, le=1.0, yani confidence_score üzerinde büyüktür/küçüktür veya eşittir) kullanır:

class DarkDataExtractedMetadata(BaseModel):
    document_title: str = Field(
        description="Official document title or product model name extracted from the PDF manual."
    )
    # ... domain_ontology, operational_hazard_level, author_provenance ...
    version_provenance: str = Field(
        description="Document version, revision code, or publication standard identifier."
    )
    # ... document_summary ...
    confidence_score: float = Field(
        ge=0.0,
        le=1.0,
        description="AI extraction confidence metric between 0.0 and 1.0.",
    )

İkincisi, extracted_aspect_template bu alan adlarını tam olarak yansıtır ve Python'ın str ve float türlerini Knowledge Catalog'un string ve double record_fields türleriyle eşler. AspectType.MetadataTemplate protobuf sözleşmesinin, record_fields içindeki her alanın benzersiz, kesinlikle pozitif ve 1 tabanlı bir tam sayı index (1 ile 7 arasında) bildirmesini gerektirdiğini unutmayın. index değerinin atlanması veya yinelenmesi, create_aspect_type öğesinin 400 INVALID_ARGUMENT ile başarısız olmasına neden olur:

extracted_aspect_template = {
    "name": "DarkDataExtractedMetadata",
    "type": "record",
    "record_fields": [
        {
            "name": "document_title",
            "type": "string",
            "index": 1,
            "annotations": {"description": "Official document title or product model name."},
        },
        # ... fields 2 through 6 (string) ...
        {
            "name": "confidence_score",
            "type": "double",
            "index": 7,
            # ... annotations ...
        },
    ],
}

Şema modülünü doğrulama

Ortam yapılandırmanızı doğrulamak ve her iki şemayı da derlemek için schemas.py komutunu çalıştırın:

python3 schemas.py

Configured Project ID         : your-project-id
Knowledge Catalog Region      : us-central1
Gemini Endpoint Location      : global
Governed Fileset Storage URI  :
  gs://your-project-id-dark-data-manuals/sop-pdfs/LUM-LIG-DES-8G8J_manual.pdf
Target Fileset Entry ID       : sop-manuals-fileset-lum8g8j
✓ Defined DarkDataExtractedMetadata and DocumentGovernanceMetadata
  Pydantic schemas.
✓ Prepared Knowledge Catalog AspectType metadata templates.

4. Ad alanları ve özel görünüm türleri sağlama

Dosya grubu girişlerini kaydetmeden veya meta veri eklemeden önce step2_provision.py, Bilgi Kataloğu'nda üç kontrol düzlemi kaynağı sağlar:

  • EntryGroup: dark-data-fileset-group
  • EntryType: unstructured-pdf-fileset
  • AspectType Blueprint'ler: dark-data-extracted-metadata ve document-governance-aspect

step2_provision.py içinde idempotent temel hazırlık

step2_provision.py içindeki her oluşturma çağrısı, uzun süren işlemi (op.result()) bir try / except AlreadyExists bloğuna sarar. Böylece komut dosyası, mevcut kaynaklarda hata vermeden güvenli bir şekilde yeniden çalıştırılabilir:

# Provision AspectType 1: dark-data-extracted-metadata
try:
    at1_op = catalog_client.create_aspect_type(
        parent=parent_location,
        aspect_type_id=EXTRACTED_ASPECT_TYPE_ID,
        aspect_type=AspectType(
            name=extracted_aspect_type_name,
            display_name="Dark Data Multimodal Extracted Metadata",
            # ... description ...
            metadata_template=extracted_aspect_template,
        ),
    )
    if hasattr(at1_op, "result"):
        at1_op.result()
    print(f"Created AspectType: {extracted_aspect_type_name}")
except AlreadyExists:
    print(f"AspectType already exists; retrieving live resource: {extracted_aspect_type_name}")

live_extracted_aspect_type = catalog_client.get_aspect_type(name=extracted_aspect_type_name)

metadata_template=extracted_aspect_template kaydedildikten sonra Knowledge Catalog, API sınırında şemayı zorunlu kılar. confidence_score (double) öğesine dize ileten sonraki tüm update_entry() çağrıları reddedilir.

step2_provision.py çalıştırma

Hazırlama komut dosyasını çalıştırın ve özel yön türlerinin bölgenizde kaydedildiğini onaylayın:

python3 step2_provision.py
gcloud dataplex aspect-types list --location=$REGION

Created EntryGroup:
  projects/your-project-id/locations/us-central1/entryGroups/
  dark-data-fileset-group
Created EntryType :
  projects/your-project-id/locations/us-central1/entryTypes/
  unstructured-pdf-fileset
Created AspectType:
  projects/your-project-id/locations/us-central1/aspectTypes/
  dark-data-extracted-metadata
Created AspectType:
  projects/your-project-id/locations/us-central1/aspectTypes/
  document-governance-aspect
✓ All Knowledge Catalog namespaces and AspectType blueprints are active.

5. Yapılandırılmamış dosya grubu girişlerini kaydetme

Knowledge Catalog, kataloğu milyonlarca izole dosya işaretçisiyle doldurmak yerine Cloud Storage'daki (gs://YOUR_BUCKET/sop-pdfs/*.pdf) ilgili dokümanları otomatik keşif taramaları (DataScanServiceClient) veya doğrudan programatik kayıt (CatalogServiceClient.create_entry) aracılığıyla mantıksal Fileset Girişleri halinde gruplandırır.

step3_register_fileset.py, depolama alanını katalogla nasıl eşler?

step3_register_fileset.py, LUM-LIG-DES-8G8J_manual.pdfgs://${BUCKET_NAME}/sop-pdfs/LUM-LIG-DES-8G8J_manual.pdf'ye yükler ve yönetilen Entry'yi kaydeder:

fully_qualified_fileset_uri = f"gcs:{BUCKET_NAME}"
fileset_entry_spec = Entry(
    name=fileset_entry_name,
    entry_type=entry_type_resource_name,
    fully_qualified_name=fully_qualified_fileset_uri,
    entry_source=EntrySource(
        resource=VIRTUAL_STORAGE_URI,
        system="Cloud Storage",
        platform="Google Cloud",
        display_name="LUM-LIG-DES-8G8J Unstructured SOP & Technical Manual Fileset",
        # ... description ...
        location=REGION,
    ),
)

create_entry_op = catalog_client.create_entry(
    parent=entry_group_resource_name,
    entry_id=FILESET_ENTRY_ID,
    entry=fileset_entry_spec,
)

Entry üzerindeki iki URI alanının farklı rollerine dikkat edin:

  • fully_qualified_name=fully_qualified_fileset_uri (f"gcs:{BUCKET_NAME}"): Mantıksal katalog girişini temel alınan Cloud Storage paketiyle ilişkilendirmek için Knowledge Catalog tarafından gerekli olan standart gcs:{bucket_name} FQN şemasını kullanır.
  • entry_source.resource=VIRTUAL_STORAGE_URI: Aşağı akışta bulunan çıkarma çalışanları tarafından incelenen fiziksel gs:// nesne URI'sini depolar.

step3_register_fileset.py çalıştırma

python3 step3_register_fileset.py

Created Cloud Storage bucket:
  gs://your-project-id-dark-data-manuals in us-central1
Uploaded unstructured PDF manual to:
  gs://your-project-id-dark-data-manuals/sop-pdfs/LUM-LIG-DES-8G8J_manual.pdf
Registered governed Fileset Entry:
  projects/your-project-id/locations/us-central1/entryGroups/
  dark-data-fileset-group/entries/sop-manuals-fileset-lum8g8j
  -> Fully Qualified Name : gcs:your-project-id-dark-data-manuals
  -> Physical Resource URI:
  gs://your-project-id-dark-data-manuals/sop-pdfs/LUM-LIG-DES-8G8J_manual.pdf
  -> Source System        : Cloud Storage

6. Gemini ile doküman meta verilerini ayıklama

step4_extract_metadata.py, ham PDF baytlarını okur ve iki temel kalıbı kullanarak Gemini Enterprise Agent Platform'u (genai_client.models.generate_content) çağırır:

1. Dinamik amiral gemisi modeli keşfi

Komut dosyası, kırılgan model sürümü dizelerini sabit kodlamak yerine genai_client.models.list() sorgusu gönderir ve en yeni genel kullanıma sunulan (GA) flash modelini seçmek için etkin adayları (is_ga_channel, semantic_version_tuple) ile sıralar:

genai_client = genai.Client(
    vertexai=True,
    project=PROJECT_ID,
    location=GEMINI_LOCATION,
)

for model_obj in genai_client.models.list():
    raw_id = (model_obj.name or "").split("/")[-1]
    # Filter to flagship Gemini Flash models (version >= 3.0) and prioritize GA over preview
    ...
    discovered_candidates.append((is_ga_channel, ver_tuple, raw_id))

discovered_candidates.sort(key=lambda item: (item[0], item[1]), reverse=True)

2. Şemayla sınırlı çok formatlı çıkarma (Part.from_bytes + response_schema)

response_mime_type="application/json" ve response_schema=DarkDataExtractedMetadata (ardından DocumentGovernanceMetadata) iletildiğinde jeton kod çözme işlemi doğrudan Pydantic JSON şemasıyla sınırlandırılır:

with open(LOCAL_PDF_PATH, "rb") as pdf_file:
    raw_pdf_bytes = pdf_file.read()

extraction_response = genai_client.models.generate_content(
    model=candidate_model,
    contents=[
        types.Part.from_bytes(data=raw_pdf_bytes, mime_type="application/pdf"),
        extraction_prompt,
    ],
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=DarkDataExtractedMetadata,
        temperature=0.1,
    ),
)

extracted_dark_data = json.loads(extraction_response.text)
validated_extraction = DarkDataExtractedMetadata(**extracted_dark_data)

step4_extract_metadata.py çalıştırma

python3 step4_extract_metadata.py

Dynamically discovered active GA model currency :
  gemini-3.8-flash (version (3, 8))
Loaded unstructured PDF manual at: LUM-LIG-DES-8G8J_manual.pdf
Read unstructured PDF document (1184 bytes).
  Executing multimodal extraction with gemini-3.8-flash...
✓ Multimodal extraction completed using model: gemini-3.8-flash
✓ Governance classification completed using model: gemini-3.8-flash

--- Extracted Multimodal Operational Metadata ---
Extracted Attribute    Multimodal Value
document_title    LUM-LIG-DES-8G8J Contemporary Linen Desk Lamp
domain_ontology    Electrical Hardware & Lighting Systems
operational_hazard_level    MEDIUM
author_provenance    Global Hardware Safety & Lighting Systems Engin
version_provenance    Rev 4.2
document_summary    This document outlines standard operating proce
confidence_score    0.99

--- Extracted Governance & Inventory Cross-Reference Metadata ---
Governance Attribute    Classification Value
compliance_classifications    UL-153 Portable Luminaires, FCC Part 15, CE-LVD
stewardship_owner    Global Hardware Safety & Lighting Systems Engin
retention_policy    10-Year Active Product Lifecycle Archival
lakehouse_cross_ref_table    lakehouse.your-project-id.retail_hardware
governance_status    VERIFIED_PRODUCTION

7. Doğrulanmış yönleri katalog girişlerine ekleme

step5_attach_aspects.py, doğrulanmış JSON yüklerini (extracted_metadata.json ve governance_metadata.json) catalog_client.update_entry() aracılığıyla sop-manuals-fileset-lum8g8j girişine bağlar.

step5_attach_aspects.py bölgesinde cerrahi görünüm değişikliği

extracted_aspect_key = f"{PROJECT_ID}.{REGION}.{EXTRACTED_ASPECT_TYPE_ID}"
governance_aspect_key = f"{PROJECT_ID}.{REGION}.{GOVERNANCE_ASPECT_TYPE_ID}"

updated_entry_payload = Entry(
    name=fileset_entry_name,
    entry_type=entry_type_resource_name,
    fully_qualified_name=fully_qualified_fileset_uri,
    aspects={
        extracted_aspect_key: Aspect(
            aspect_type=extracted_aspect_type_name,
            data=extracted_data,
        ),
        governance_aspect_key: Aspect(
            aspect_type=governance_aspect_type_name,
            data=governance_data,
        ),
    },
)

update_op = catalog_client.update_entry(
    request=dataplex_v1.UpdateEntryRequest(
        entry=updated_entry_payload,
        update_mask={"paths": ["aspects"]},
        aspect_keys=[extracted_aspect_key, governance_aspect_key],
    )
)

Hem update_mask={"paths": ["aspects"]} hem de aspect_keys=[extracted_aspect_key, governance_aspect_key] kapsamlarının iletilmesi, mutasyonu kesinlikle bu iki yön anahtarıyla sınırlandırır. Böylece entry_source ve diğer ekiplerin sahip olduğu yönler değiştirilmez.

step5_attach_aspects.py çalıştırma

python3 step5_attach_aspects.py

Successfully bound 2 Aspect(s) to Entry:
  projects/your-project-id/locations/us-central1/entryGroups/
  dark-data-fileset-group/entries/sop-manuals-fileset-lum8g8j

=== Live Attached Aspect: document-governance-aspect ===
Catalog Field    Authoritative Stored Value
compliance_classifications    UL-153 Portable Luminaires, FCC Part 15, CE-LVD
stewardship_owner    Global Hardware Safety & Lighting Systems Engin
retention_policy    10-Year Active Product Lifecycle Archival
lakehouse_cross_ref_table    lakehouse.your-project-id.retail_hardware
governance_status    VERIFIED_PRODUCTION

=== Live Attached Aspect: dark-data-extracted-metadata ===
Catalog Field    Authoritative Stored Value
document_title    LUM-LIG-DES-8G8J Contemporary Linen Desk Lamp
domain_ontology    Electrical Hardware & Lighting Systems
operational_hazard_level    MEDIUM
author_provenance    Global Hardware Safety & Lighting Systems Engin
version_provenance    Rev 4.2
document_summary    This document outlines standard operating proce
confidence_score    0.99

Çift kanallı doğrulama

  • 1. İz (KSA Doğrulaması): Girişi, gcloud aracılığıyla eklenen tüm yönleriyle inceleyin: 
    gcloud dataplex entries describe sop-manuals-fileset-lum8g8j \
  --entry-group=dark-data-fileset-group \
  --location=$REGION \
  --view=ALL
  • 2. Parça (Console Kullanıcı Arayüzü Denetimi):
    1. Knowledge Catalog Search Console'u açın, LUM-LIG-DES-8G8J Unstructured SOP & Technical Manual Fileset (sop-manuals-fileset-lum8g8j) ifadesini arayın ve sonuçlardan eşleşen girişi seçin.
    2. İsteğe bağlı etiketler ve yönler bölümünde hem Dark Data Multimodal Extracted Metadata hem de Document Governance & Inventory Cross-Reference Aspect'in, çıkarılan tehlike düzeyini (MEDIUM), uygunluk kodlarını (UL-153, FCC Part 15, CE-LVD, RoHS) ve çapraz referans tablosu dizesini (lakehouse_cross_ref_table) gösterdiğini doğrulayın.

8. Katalogdaki yönetilen karanlık verileri sorgulama

Özel yönler eklendikten sonra Cloud Storage'daki yapılandırılmamış PDF kılavuzları, Knowledge Catalog araması (catalog_client.search_entries()) aracılığıyla bulunabilir hale gelir.

step6_search_catalog.py içinde search_entries() anketine katılma

Eksponansiyel geri yüklemeyle step6_search_catalog.py search_entries() yoklaması yapar ve standartlaştırılmış yön anahtarlarını .endswith() üzerinden okur:

search_query = f"entrygroup={entry_group_resource_name} name:{FILESET_ENTRY_ID}"

while elapsed_seconds < max_wait_seconds:
    catalog_search_results = list(
        catalog_client.search_entries(
            request=dataplex_v1.SearchEntriesRequest(
                name=parent_location,
                query=search_query,
            )
        )
    )
    if catalog_search_results:
        break
    backoff_seconds = min(5 * (2 ** attempt), 30)
    time.sleep(backoff_seconds)
    ...

for k, asp in detailed_entry.aspects.items():
    if k.endswith(f".{REGION}.{EXTRACTED_ASPECT_TYPE_ID}"):
        print(f"    Domain Ontology     : {asp.data.get('domain_ontology')}")
        print(f"    Hazard Level        : {asp.data.get('operational_hazard_level')}")
    elif k.endswith(f".{REGION}.{GOVERNANCE_ASPECT_TYPE_ID}"):
        print(f"    Compliance Codes    : {asp.data.get('compliance_classifications')}")
        print(f"    Lakehouse Join Table: {asp.data.get('lakehouse_cross_ref_table')}")

step6_search_catalog.py çalıştırma

python3 step6_search_catalog.py

Executing Knowledge Catalog search query:
  'entrygroup=projects/your-project-id/locations/us-central1/entryGroups/
  dark-data-fileset-group name:sop-manuals-fileset-lum8g8j'...

✓ Discovered 1 governed asset(s) in Knowledge Catalog:

[1] Entry Resource Name :
    projects/your-project-id/locations/us-central1/entryGroups/
    dark-data-fileset-group/entries/sop-manuals-fileset-lum8g8j
    Fully Qualified Name: gcs:your-project-id-dark-data-manuals
    Entry Type :
    projects/your-project-id/locations/us-central1/entryTypes/
    unstructured-pdf-fileset
    Physical Storage URI:
    gs://your-project-id-dark-data-manuals/sop-pdfs/LUM-LIG-DES-8G8J_manual.pdf
    Domain Ontology     : Electrical Hardware & Lighting Systems
    Hazard Level        : MEDIUM
    Compliance Codes    : UL-153 Portable Luminaires, FCC Part 15, CE-LVD, RoHS
    Lakehouse Join Table:
    lakehouse.your-project-id.retail_hardware.luminaire_sku_inventory_iceberg

Çift kanallı doğrulama

  • 1. Parça (CLI Arama): Arama dizinini doğrudan gcloud üzerinden sorgulayın: 
    gcloud dataplex entries search "name:sop-manuals-fileset-lum8g8j" --project=$PROJECT_ID
  • 2. yol (Console kullanıcı arayüzünde doğal dil araması):
    1. Knowledge Catalog Search Console'u açın ve LUM-LIG-DES-8G8J veya UL-153 simgesini arayın.
    2. Knowledge Catalog'un, yönetilen Cloud Storage PDF dosyası kümesi girişini ve ekli meta veri yönlerini nasıl gösterdiğini inceleyin.

9. Uçtan uca yönetime ilişkin onayları doğrulama

step7_verify_assertions.py, EntryType, her ikisi de özel AspectType planları, bağlı EntryView.ALL yön yükleri (confidence_score sınırları ve lakehouse_cross_ref_table dizesi) ve arama dizini keşfinin başarılı olduğunu doğrulamak için canlı Bilgi Kataloğu kontrol düzlemi yanıtlarına karşı deterministik onaylamalar çalıştırır:EntryGroup

verify_eg = catalog_client.get_entry_group(name=entry_group_resource_name)
assert verify_eg.name == entry_group_resource_name, "EntryGroup resource name mismatch."

verify_entry = catalog_client.get_entry(
    request=dataplex_v1.GetEntryRequest(
        name=fileset_entry_name,
        view=dataplex_v1.EntryView.ALL,
    )
)
bound_extracted = next(
    (
        asp for k, asp in verify_entry.aspects.items()
        if k.endswith(f".{REGION}.{EXTRACTED_ASPECT_TYPE_ID}")
    ),
    None,
)
bound_governance = next(
    (
        asp for k, asp in verify_entry.aspects.items()
        if k.endswith(f".{REGION}.{GOVERNANCE_ASPECT_TYPE_ID}")
    ),
    None,
)

assert bound_extracted is not None, f"Aspect '{EXTRACTED_ASPECT_TYPE_ID}' not found on live Entry."
assert bound_governance is not None, (
    f"Aspect '{GOVERNANCE_ASPECT_TYPE_ID}' not found on live Entry."
)
assert (
    bound_extracted.data.get("document_title") == expected_extraction["document_title"]
), "Extracted title mismatch."
assert (
    0.0 <= float(bound_extracted.data.get("confidence_score", -1.0)) <= 1.0
), "Invalid confidence score in catalog."
assert (
    "lakehouse" in str(bound_governance.data.get("lakehouse_cross_ref_table", "")).lower()
), "Missing Lakehouse cross-reference."
...
assert len(search_results) >= 1, "Expected at least 1 search result in Knowledge Catalog."

step7_verify_assertions.py çalıştırma

python3 step7_verify_assertions.py && echo "Verification exit code: $?"

Running substantive end-to-end verification assertions...
✓ All 5 substantive verification assertions passed
  against live Google Cloud control plane state!
Verification exit code: 0

10. Olay odaklı bir ardışık düzen tasarlama

Cloud Shell'de Python komut dosyalarını etkileşimli olarak çalıştırmak, yönetim sözleşmelerinizi oluşturup test etmek için ideal olsa da kurumsal ortamlar ERP, ürün yaşam döngüsü yönetimi (PLM) ve tedarikçi portallarından her gün binlerce yeni veya revize edilmiş PDF mühendislik kılavuzu, tedarikçi uygunluk sertifikası ve standart işlem prosedürü (SOP) belgesi alır. Toplu komut dosyalarını manuel olarak çalıştırmak, doküman yükleme ve katalog dizine ekleme arasında hızlı bir şekilde yönetim açısından kör noktalar oluşturur.

Üretimde, platform ekipleri 4. ve 5. adımlarda çalıştırdığınız kodu sıfır dokunuşlu, etkinliğe dayalı bir ardışık düzen olarak kullanıma sunar:

Etkinliğe Dayalı Gizli Veri İşlem Hattı

  1. Sürekli belge alımı (Cloud Storage → Eventarc): Yeni bir PDF kılavuzu yüklendiğinde veya yeni bir düzeltme, Cloud Storage'daki mevcut bir nesnenin üzerine yazıldığında paket, paket tanımlayıcıyı, nesne yolunu ve nesne oluşturma numarasını içeren bir google.cloud.storage.object.v1.finalized CloudEvent yayınlar.
  2. Durumsuz Çok Formatlı Çıkarma (Eventarc → Cloud Run → Gemini Enterprise Agent Platform): Eventarc, CloudEvent'i schemas.py, step4_extract_metadata.py ve step5_attach_aspects.py paketleyen sunucusuz bir Cloud Run çalışanına yönlendirir. Çalışan, PDF baytlarını response_schema zorunlu kılınarak Gemini Enterprise Agent Platform'a aktarır. Böylece, çıkarılan her özelliğin DarkDataExtractedMetadata ve DocumentGovernanceMetadata'ye uygunluğu garanti edilir.
  3. Cerrahi Kontrol Düzlemi Güncellemesi (Cloud Run → Knowledge Catalog): Çalışan, üst Fileset Entry öğesini çözer ve catalog_client.update_entry() öğesini update_mask={"paths": ["aspects"]} ve açık aspect_keys ile yürütür. Düzinelerce doküman aynı anda işleme tamamlanmış olsa bile her değişiklik yalnızca belirlenen yön anahtarlarını günceller.
  4. Güvenle Sınırlı Yönetici Karantinası: Taranan eski bir PDF, operasyonel eşiğinizin altında (örneğin, < 0.85) bir ayıklama confidence_score verirse çalışan, ekli yön için governance_status = "PENDING_STEWARD_REVIEW" değerini ayarlar. Böylece veri yöneticileri, insan incelemesi gerektiren düşük güven düzeyine sahip öğeler için Bilgi Kataloğu'nu sorgulayabilir.

Bu kalıbın işletmeler tarafından üretimde nasıl uygulandığı

Enterprise Kullanım Alanı

Kod olarak meta verilerin uygulamadaki işleyiş şekli

İşletme ve Operasyonel Etki

Otomatik Düzenleyici Denetimleri ve Geri Çağırmaya Hazırlık
(Üretim, Donanım ve Enerji)

Uygunluk sistemleri, BigQuery ve Lakehouse for Apache Iceberg'de yapılandırılmamış PDF güvenlik yönlerini (compliance_classifications, operational_hazard_level) yapılandırılmış SKU envanter tablolarıyla (lakehouse_cross_ref_table) birleştirir.

UL-153 veya CE-LVD gibi bir standart güncellendiğinde denetçiler, binlerce PDF klasörünü manuel olarak açmak yerine etkilenen her donanım SKU'sunu ve depo konumunu saniyeler içinde tanımlar.

Temellendirilmiş Yapay Zeka Aracıları ve RAG Ön Filtreleme
(Kurumsal Bilgi Asistanları)

Gemini Enterprise Agent Platform'daki veriyle artırılmış üretim (RAG) aracısı, saha mühendisinin sorusunu yanıtlamadan önce Knowledge Catalog girişlerini governance_status = "VERIFIED_PRODUCTION" ve version_provenance'ye göre filtreler.

Yapay zeka asistanlarının halüsinasyon görmesini veya kullanımdan kaldırılmış mühendislik taslaklarını, süresi dolmuş standart işlem prosedürlerini ya da doğrulanmamış üçüncü taraf kılavuzlarını alıntılamasını önler.

Çoklu Ekip Eşzamanlı Zenginleştirme
(Merkezi Olmayan Veri Ağı)

Aynı dosya kümesini birden fazla bağımsız ardışık düzen zenginleştirir Entry: Yapay zeka mühendisliği çalışanı dark-data-extracted-metadata güncellemesini yapar, hukuk departmanı document-governance-aspect aracılığıyla saklama politikalarını ekler ve güvenlik departmanı DLP hassasiyet yönlerini ekler.

UpdateEntryRequest, değişiklikleri aspect_keys üzerinden kapsamlandırdığı için her alan ekibi, diğer ekiplerin yönetim verilerinin üzerine yazmadan meta veri ardışık düzenini bağımsız olarak dağıtır ve günceller.

GitOps aracılığıyla CI/CD şema evrimi
(Platform ve Veri Mühendisliği)

Platform ekipleri, schemas.py öğesini Git'teki Terraform google_dataplex_aspect_type tanımlarıyla birlikte depolar. Çekme istekleri, dağıtımdan önce yeni Pydantic alanının AspectType şablonunda 1 tabanlı bir index ile eşleştiğini doğrular.

dev, staging ve prod projelerinde uygulama ayıklama kodu ile Knowledge Catalog kontrol düzlemi arasındaki şema kaymasını ortadan kaldırır.

11. Ortamınızı temizleme

Bilgi Kataloğu'nda, alt girişler hâlâ bunlara referans veriyorken üst kapsayıcılar ve şema şablonları silinemez. cleanup.py, kaynakları kesin ters bağımlılık sırasına göre siler (Entry → EntryGroup → EntryType → AspectTypes → Cloud Storage paket nesneleri → geçici JSON dosyaları):

# 1. Delete Fileset Entry first
catalog_client.delete_entry(name=target_entry_path)

# 2. Delete EntryGroup container
del_eg_op = catalog_client.delete_entry_group(name=target_eg_path)
if hasattr(del_eg_op, "result"):
    del_eg_op.result()

# 3. Delete EntryType and Custom AspectTypes
del_et_op = catalog_client.delete_entry_type(name=target_et_path)
if hasattr(del_et_op, "result"):
    del_et_op.result()
for aspect_id_val in (EXTRACTED_ASPECT_TYPE_ID, GOVERNANCE_ASPECT_TYPE_ID):
    target_at_path = f"{active_parent}/aspectTypes/{aspect_id_val}"
    del_at_op = catalog_client.delete_aspect_type(name=target_at_path)
    if hasattr(del_at_op, "result"):
        del_at_op.result()

cleanup.py çalıştırma

python3 cleanup.py

Starting reverse-dependency resource cleanup in Knowledge Catalog...
Deleted Fileset Entry:
  projects/your-project-id/locations/us-central1/entryGroups/
  dark-data-fileset-group/entries/sop-manuals-fileset-lum8g8j
Deleted EntryGroup   :
  projects/your-project-id/locations/us-central1/entryGroups/
  dark-data-fileset-group
Deleted EntryType    :
  projects/your-project-id/locations/us-central1/entryTypes/
  unstructured-pdf-fileset
Deleted AspectType   :
  projects/your-project-id/locations/us-central1/aspectTypes/
  dark-data-extracted-metadata
Deleted AspectType   :
  projects/your-project-id/locations/us-central1/aspectTypes/
  document-governance-aspect
Deleted Cloud Storage object :
  gs://your-project-id-dark-data-manuals/sop-pdfs/LUM-LIG-DES-8G8J_manual.pdf
Deleted Cloud Storage bucket : gs://your-project-id-dark-data-manuals
Removed local temporary file : extracted_metadata.json
Removed local temporary file : governance_metadata.json
✓ Standalone teardown complete. Environment cleanly reset.

Klonlanmış depo dizinini kaldırma

cleanup.py, bulut kaynaklarını silme işlemini tamamladıktan sonra ana dizininize dönün ve klonlanmış devrel-demos depo klasörünü Cloud Shell'den kaldırın:

cd ~
rm -rf ~/devrel-demos

12. Tebrikler!

Gemini Enterprise Agent Platform'u kullanarak Cloud Storage'daki yapılandırılmamış PDF'leri bulunabilir, şeması zorunlu kılınmış Knowledge Catalog varlıklarına dönüştüren uçtan uca Metadata-as-Code yönetim hattı oluşturup doğruladınız.

Sırada ne var?

  • Terraform ile otomasyon: CI/CD ardışık düzenlerinde google_dataplex_aspect_type ve google_dataplex_entry_group kaynaklarını bildirimsel olarak yönetin.
  • Eventarc + Cloud Run işçilerini dağıtma: step4_extract_metadata.py ve step5_attach_aspects.py öğelerini etkinliğe dayalı bir Cloud Run hizmeti olarak container'a alın.
  • BigQuery'de aşağı akış envanter birleştirme işlemleri: Yapılandırılmamış belge uyumluluğu özelliklerini yapılandırılmış SKU envanter tablolarıyla birleştirmek için çıkarılan yönetim meta verilerini (lakehouse_cross_ref_table) dışa aktarın.

Referans belgeleri