mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 00:46:22 +02:00
Feat: TrustGraph i18n & Documentation Translation Updates (#781)
Native CLI i18n: The TrustGraph CLI has built-in translation support that dynamically loads language strings. You can test and use different languages by simply passing the --lang flag (e.g., --lang es for Spanish, --lang ru for Russian) or by configuring your environment's LANG variable. Automated Docs Translations: This PR introduces autonomously translated Markdown documentation into several target languages, including Spanish, Swahili, Portuguese, Turkish, Hindi, Hebrew, Arabic, Simplified Chinese, and Russian.
This commit is contained in:
Alex Jenkins
GitHub
parent
19f73e4cdc
commit
f95fd4f052
560 changed files with 236300 additions and 99 deletions
281
docs/tech-specs/structured-diag-service.tr.md
Normal file
281
docs/tech-specs/structured-diag-service.tr.md
Normal file
|
|
@ -0,0 +1,281 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Yapılandırılmış Veri Tanı Hizmeti Teknik Özellikleri"
|
||||
parent: "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ı:
|
||||
|
||||
```python
|
||||
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ı:
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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](structured-data-descriptor.md)
|
||||
[Yapılandırılmış Veri Yükleme Dokümantasyonu](structured-data.md)
|
||||
`tg-load-structured-data` uygulaması: `trustgraph-cli/trustgraph/cli/load_structured_data.py`
|
||||
Loading…
Add table
Add a link
Reference in a new issue