trustgraph/docs/tech-specs/tr/structured-diag-service.tr.md

layout	title	parent
default	Yapılandırılmış Veri Tanı Hizmeti Teknik Özellikleri	Turkish (Beta)

Yapılandırılmış Veri Tanı Hizmeti Teknik Özellikleri

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

Genel Bakış

Bu özellik, TrustGraph içinde yapılandırılmış verileri teşhis etmek ve analiz etmek için yeni bir kullanılabilir hizmeti tanımlar. Bu hizmet, mevcut tg-load-structured-data komut satırı aracından işlevleri ayırır ve bunları istek/yanıt hizmeti olarak sunar, böylece veri türü algılama ve tanımlayıcı oluşturma yeteneklerine programlı erişim sağlar.

Bu hizmet, üç birincil işlemi destekler:

1. Veri Türü Algılama: Bir veri örneğinin biçimini (CSV, JSON veya XML) belirlemek için analiz gerçekleştirin.
2. Tanımlayıcı Oluşturma: Verilen bir veri örneği ve tür için bir TrustGraph yapılandırılmış veri tanımlayıcısı oluşturun.
3. Birleşik Tanı: Hem tür algılama hem de tanımlayıcı oluşturmayı sırayla gerçekleştirin.

Hedefler

Veri Analizini Modülerleştirme: Veri teşhis mantığını CLI'dan yeniden kullanılabilir hizmet bileşenlerine ayırma. Programlı Erişimi Sağlama: Veri analiz yeteneklerine API tabanlı erişim sağlama. Çoklu Veri Biçimlerini Destekleme: CSV, JSON ve XML veri biçimlerini tutarlı bir şekilde işleme. Doğru Tanımlayıcılar Oluşturma: Kaynak verileri TrustGraph şemalarına doğru bir şekilde eşleyen yapılandırılmış veri tanımlayıcıları oluşturma. Geriye Dönük Uyumluluğu Koruma: Mevcut CLI işlevselliğinin çalışmaya devam etmesini sağlama. Hizmet Birleştirme İmkanı Sağlama: Diğer hizmetlerin veri teşhis yeteneklerinden yararlanmasına olanak sağlama. Test Edilebilirliği Artırma: İş mantığını CLI arayüzünden ayırarak daha iyi test imkanı sağlama. Akış Analizini Destekleme: Tüm dosyaları yüklemeden veri örneklerinin analizini yapma imkanı sağlama.

Arka Plan

Şu anda, tg-load-structured-data komutu, yapılandırılmış verileri analiz etmek ve tanımlayıcılar oluşturmak için kapsamlı işlevsellik sağlar. Ancak, bu işlevsellik CLI arayüzüne sıkı bir şekilde bağlıdır ve yeniden kullanılabilirliğini sınırlar.

Mevcut sınırlamalar şunlardır: Veri teşhis mantığının CLI kodunda yer alması. Tür algılama ve tanımlayıcı oluşturma için programlı erişimin olmaması. Teşhis yeteneklerinin diğer hizmetlere entegre edilmesinin zor olması. Veri analiz iş akışlarının birleştirme yeteneğinin sınırlı olması.

Bu özellik, yapılandırılmış veri teşhisi için özel bir hizmet oluşturarak bu boşlukları giderir. Bu yetenekleri bir hizmet olarak sunarak, TrustGraph şunları yapabilir: Diğer hizmetlerin verileri programlı olarak analiz etmesine olanak sağlama. Daha karmaşık veri işleme süreçlerini destekleme. Harici sistemlerle entegrasyonu kolaylaştırma. Endişelerin ayrılması yoluyla bakım kolaylığını artırma.

Teknik Tasarım

Mimari

Yapılandırılmış veri teşhis hizmeti, aşağıdaki teknik bileşenleri gerektirir:

1. Teşhis Hizmeti İşlemcisi Gelen teşhis isteklerini işler. Tür algılama ve tanımlayıcı oluşturmayı koordine eder. Teşhis sonuçlarıyla yapılandırılmış yanıtlar döndürür.

   Modül: trustgraph-flow/trustgraph/diagnosis/structured_data/service.py

2. Veri Türü Algılayıcı Algoritmik algılama kullanarak veri biçimini (CSV, JSON, XML) belirler. Veri yapısını, ayırıcıları ve sözdizimi kalıplarını analiz eder. Algılanan biçimi ve güvenilirlik puanlarını döndürür.

   Modül: trustgraph-flow/trustgraph/diagnosis/structured_data/type_detector.py

3. Tanımlayıcı Oluşturucu Tanımlayıcılar oluşturmak için bir istem hizmetini kullanır. Biçime özgü istemleri (diagnose-csv, diagnose-json, diagnose-xml) çağırır. Veri alanlarını, istem yanıtları aracılığıyla TrustGraph şema alanlarına eşler.

   Modül: trustgraph-flow/trustgraph/diagnosis/structured_data/descriptor_generator.py

Veri Modelleri

StructuredDataDiagnosisRequest

Yapılandırılmış veri teşhis işlemleri için istek mesajı:

class StructuredDataDiagnosisRequest:
    operation: str  # "detect-type", "generate-descriptor", or "diagnose"
    sample: str     # Data sample to analyze (text content)
    type: Optional[str]  # Data type (csv, json, xml) - required for generate-descriptor
    schema_name: Optional[str]  # Target schema name for descriptor generation
    options: Dict[str, Any]  # Additional options (e.g., delimiter for CSV)

YapılandırılmışVeriTeşhisYanıtı

Teşhis sonuçlarını içeren yanıt mesajı:

class StructuredDataDiagnosisResponse:
    operation: str  # The operation that was performed
    detected_type: Optional[str]  # Detected data type (for detect-type/diagnose)
    confidence: Optional[float]  # Confidence score for type detection
    descriptor: Optional[Dict]  # Generated descriptor (for generate-descriptor/diagnose)
    error: Optional[str]  # Error message if operation failed
    metadata: Dict[str, Any]  # Additional metadata (e.g., field count, sample records)

Açıklayıcı Yapı

Oluşturulan açıklayıcı, mevcut yapılandırılmış veri açıklayıcı biçimini izler:

{
  "format": {
    "type": "csv",
    "encoding": "utf-8",
    "options": {
      "delimiter": ",",
      "has_header": true
    }
  },
  "mappings": [
    {
      "source_field": "customer_id",
      "target_field": "id",
      "transforms": [
        {"type": "trim"}
      ]
    }
  ],
  "output": {
    "schema_name": "customer",
    "options": {
      "batch_size": 1000,
      "confidence": 0.9
    }
  }
}

Hizmet Arayüzü

Hizmet, istek/yanıt kalıbı aracılığıyla aşağıdaki işlemleri sunacaktır:

1. Tip Algılama İşlemi Giriş: Veri örneği İşlem: Algoritmik algılama kullanarak veri yapısını analiz etme Çıkış: Belirlenen tip ve güvenilirlik skoru

2. Açıklayıcı Oluşturma İşlemi Giriş: Veri örneği, tip, hedef şema adı İşlem: Biçime özgü bir istem kimliği (diagnose-csv, diagnose-json veya diagnose-xml) ile istem hizmetini çağırın. Veri örneğini ve mevcut şemaları isteme iletin. İstem yanıtından oluşturulan açıklayıcıyı alın. Çıkış: Yapılandırılmış veri açıklayıcısı

3. Birleşik Tanılama İşlemi Giriş: Veri örneği, isteğe bağlı şema adı İşlem: Önce algoritmik algılama kullanarak biçimi belirleyin. Belirlenen tipe göre uygun biçime özgü istemi seçin. Açıklayıcı oluşturmak için istem hizmetini çağırın. Çıkış: Hem belirlenen tip hem de açıklayıcı

Uygulama Detayları

Hizmet, TrustGraph hizmeti geleneklerini takip edecektir:

1. Hizmet Kaydı structured-diag hizmet türü olarak kaydedin Standart istek/yanıt konularını kullanın FlowProcessor temel sınıfını uygulayın İstem hizmeti etkileşimi için PromptClientSpec'i kaydedin

2. Yapılandırma Yönetimi Şema yapılandırmalarına yapılandırma hizmeti aracılığıyla erişin Performans için şemaları önbelleğe alın Yapılandırma güncellemelerini dinamik olarak işleyin

3. İstem Entegrasyonu Mevcut istem hizmeti altyapısını kullanın Biçime özgü istem kimlikleriyle istem hizmetini çağırın: diagnose-csv: CSV verisi analizi için diagnose-json: JSON verisi analizi için diagnose-xml: XML verisi analizi için İstemler, hizmette sabit kodlanmış olan istem yapılandırmasında yapılandırılmıştır. Şemaları ve veri örneklerini istem değişkenleri olarak iletin Açıklayıcıları çıkarmak için istem yanıtlarını ayrıştırın

4. Hata Yönetimi Giriş veri örneklerini doğrulayın Açıklayıcı hata mesajları sağlayın Hatalı verileri zarif bir şekilde işleyin İstem hizmeti hatalarını işleyin

5. Veri Örneklemesi Yapılandırılabilir örnek boyutlarını işleyin Eksik kayıtları uygun şekilde işleyin Örnekleme tutarlılığını koruyun

API Entegrasyonu

Hizmet, mevcut TrustGraph API'leriyle entegre olacaktır:

Değiştirilen Bileşenler: tg-load-structured-data CLI - Tanılama işlemleri için yeni hizmeti kullanmak üzere yeniden düzenlendi Flow API - Yapılandırılmış veri tanılama isteklerini desteklemek üzere genişletildi

Yeni Hizmet Uç Noktaları: /api/v1/flow/{flow}/diagnose/structured-data - Tanılama istekleri için WebSocket uç noktası /api/v1/diagnose/structured-data - Senkron tanılama için REST uç noktası

Mesaj Akışı

Client → Gateway → Structured Diag Service → Config Service (for schemas)
                                           ↓
                                    Type Detector (algorithmic)
                                           ↓
                                    Prompt Service (diagnose-csv/json/xml)
                                           ↓
                                 Descriptor Generator (parses prompt response)
                                           ↓
Client ← Gateway ← Structured Diag Service (response)

Güvenlik Hususları

Enjeksiyon saldırılarını önlemek için girdi doğrulama DoS saldırılarını önlemek için veri örnekleri üzerindeki boyut sınırlamaları Oluşturulan tanımlayıcıların temizlenmesi Mevcut TrustGraph kimlik doğrulama aracılığıyla erişim kontrolü

Performans Hususları

Yapılandırma hizmeti çağrılarını azaltmak için şema tanımlarını önbelleğe alın Duyarlı performansı korumak için örnek boyutlarını sınırlayın Büyük veri örnekleri için akış işleme kullanın Uzun süren analizler için zaman aşımı mekanizmaları uygulayın

Test Stratejisi

1. Birim Testleri Çeşitli veri formatları için tür tespiti Tanımlayıcı oluşturma doğruluğu Hata işleme senaryoları

2. Entegrasyon Testleri Hizmet istek/yanıt akışı Şema alma ve önbelleğe alma CLI entegrasyonu

3. Performans Testleri Büyük örnek işleme Eşzamanlı istek işleme Yük altında bellek kullanımı

Geçiş Planı

1. 1. Aşama: Temel işlevselliğe sahip hizmeti uygulayın
2. 2. Aşama: CLI'ı hizmeti kullanacak şekilde yeniden düzenleyin (geriye dönük uyumluluğu koruyun)
3. 3. Aşama: REST API uç noktaları ekleyin
4. 4. Aşama: Gömülü CLI mantığını kullanımdan kaldırın (bildirim süresiyle)

Zaman Çizelgesi

1-2. Hafta: Temel hizmeti ve tür tespitini uygulayın 3-4. Hafta: Tanımlayıcı oluşturmayı ve entegrasyonu ekleyin 5. Hafta: Test ve dokümantasyon 6. Hafta: CLI yeniden düzenlemesi ve geçiş

Açık Sorular

Hizmet, ek veri formatlarını (örneğin, Parquet, Avro) desteklemeli mi? Analiz için maksimum örnek boyutu ne olmalıdır? Teşhis sonuçları, tekrarlanan istekler için önbelleğe alınmalı mı? Hizmet, çoklu şema senaryolarını nasıl işlemelidir? İstek kimlikleri, hizmet için yapılandırılabilir parametreler olmalı mı?

Referanslar

Yapılandırılmış Veri Tanımlayıcı Özellikleri Yapılandırılmış Veri Yükleme Dokümantasyonu tg-load-structured-data uygulaması: trustgraph-cli/trustgraph/cli/load_structured_data.py