mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-27 17:36:23 +02:00
Structure the tech specs directory (#836)
Tech spec some subdirectories for different languages
This commit is contained in:
cybermaggedon
GitHub
parent
48da6c5f8b
commit
e7efb673ef
423 changed files with 0 additions and 0 deletions
135
docs/tech-specs/tr/__TEMPLATE.tr.md
Normal file
135
docs/tech-specs/tr/__TEMPLATE.tr.md
Normal file
|
|
@ -0,0 +1,135 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Komut Satırı ile Bilgi Yükleme Teknik Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Komut Satırı ile Bilgi Yükleme 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 teknik özellik, TrustGraph'a bilgi yüklemek için komut satırı arayüzlerini tanımlar ve kullanıcıların komut satırı araçları aracılığıyla çeşitli kaynaklardan veri almasını sağlar. Bu entegrasyon, dört ana kullanım senaryosunu destekler:
|
||||
|
||||
1. **[Kullanım Senaryosu 1]**: [Açıklama]
|
||||
2. **[Kullanım Senaryosu 2]**: [Açıklama]
|
||||
3. **[Kullanım Senaryosu 3]**: [Açıklama]
|
||||
4. **[Kullanım Senaryosu 4]**: [Açıklama]
|
||||
|
||||
## Hedefler
|
||||
|
||||
- **[Hedef 1]**: [Açıklama]
|
||||
- **[Hedef 2]**: [Açıklama]
|
||||
- **[Hedef 3]**: [Açıklama]
|
||||
- **[Hedef 4]**: [Açıklama]
|
||||
- **[Hedef 5]**: [Açıklama]
|
||||
- **[Hedef 6]**: [Açıklama]
|
||||
- **[Hedef 7]**: [Açıklama]
|
||||
- **[Hedef 8]**: [Açıklama]
|
||||
|
||||
## Arka Plan
|
||||
|
||||
[Mevcut durumu ve bu teknik özelliğin ele aldığı sınırlamaları açıklayın]
|
||||
|
||||
Mevcut sınırlamalar şunlardır:
|
||||
- [Sınırlama 1]
|
||||
- [Sınırlama 2]
|
||||
- [Sınırlama 3]
|
||||
- [Sınırlama 4]
|
||||
|
||||
Bu teknik özellik, bu eksiklikleri [açıklama] ile giderir. [Yeteneği] sayesinde, TrustGraph şunları yapabilir:
|
||||
- [Fayda 1]
|
||||
- [Fayda 2]
|
||||
- [Fayda 3]
|
||||
- [Fayda 4]
|
||||
|
||||
## Teknik Tasarım
|
||||
|
||||
### Mimari
|
||||
|
||||
Komut satırı ile bilgi yükleme, aşağıdaki teknik bileşenleri gerektirir:
|
||||
|
||||
1. **[Bileşen 1]**
|
||||
- [Bileşenin işlevselliğinin açıklaması]
|
||||
- [Temel özellikler]
|
||||
- [Entegrasyon noktaları]
|
||||
|
||||
Modül: [modül-yolu]
|
||||
|
||||
2. **[Bileşen 2]**
|
||||
- [Bileşenin işlevselliğinin açıklaması]
|
||||
- [Temel özellikler]
|
||||
- [Entegrasyon noktaları]
|
||||
|
||||
Modül: [modül-yolu]
|
||||
|
||||
3. **[Bileşen 3]**
|
||||
- [Bileşenin işlevselliğinin açıklaması]
|
||||
- [Temel özellikler]
|
||||
- [Entegrasyon noktaları]
|
||||
|
||||
Modül: [modül-yolu]
|
||||
|
||||
### Veri Modelleri
|
||||
|
||||
#### [Veri Modeli 1]
|
||||
|
||||
[Veri modelinin ve yapısının açıklaması]
|
||||
|
||||
Örnek:
|
||||
```
|
||||
[Example data structure]
|
||||
```
|
||||
|
||||
Bu yaklaşım şunları sağlar:
|
||||
- [Fayda 1]
|
||||
- [Fayda 2]
|
||||
- [Fayda 3]
|
||||
- [Fayda 4]
|
||||
|
||||
### API'ler
|
||||
|
||||
Yeni API'ler:
|
||||
- [API açıklaması 1]
|
||||
- [API açıklaması 2]
|
||||
- [API açıklaması 3]
|
||||
|
||||
Değiştirilen API'ler:
|
||||
- [Değiştirilen API 1] - [Değişikliklerin açıklaması]
|
||||
- [Değiştirilen API 2] - [Değişikliklerin açıklaması]
|
||||
|
||||
### Uygulama Detayları
|
||||
|
||||
[Uygulama yaklaşımı ve kurallar]
|
||||
|
||||
[Ek uygulama notları]
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
[Bu uygulamanın özel güvenlik hususları]
|
||||
|
||||
## Performans Hususları
|
||||
|
||||
[Performans hususları ve olası darboğazlar]
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
[Test yaklaşımı ve stratejisi]
|
||||
|
||||
## Geçiş Planı
|
||||
|
||||
[Gerekliyse geçiş stratejisi]
|
||||
|
||||
## Zaman Çizelgesi
|
||||
|
||||
[Belirtilmişse zaman çizelgesi bilgileri]
|
||||
|
||||
## Açık Sorular
|
||||
|
||||
- [Açık soru 1]
|
||||
- [Açık soru 2]
|
||||
|
||||
## Referanslar
|
||||
|
||||
[Gerekliyse referanslar]
|
||||
280
docs/tech-specs/tr/agent-explainability.tr.md
Normal file
280
docs/tech-specs/tr/agent-explainability.tr.md
Normal file
|
|
@ -0,0 +1,280 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Ajan Açıklanabilirliği: Kaynak Kaydı"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Ajan Açıklanabilirliği: Kaynak Kaydı
|
||||
|
||||
> **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ış
|
||||
|
||||
Ajan oturumlarının izlenebilmesi ve GraphRAG ile aynı açıklanabilirlik altyapısı kullanılarak hata ayıklanabilmesi için, React ajan döngüsüne kaynak kaydı ekleyin.
|
||||
|
||||
**Tasarım Kararları:**
|
||||
- `urn:graph:retrieval`'a yazın (genel açıklanabilirlik grafiği)
|
||||
- Şu anda doğrusal bağımlılık zinciri (analiz N → wasDerivedFrom → analiz N-1)
|
||||
- Araçlar, kayıt alınmayan, opak kara kutulardır (sadece girdi/çıktı kaydedilir)
|
||||
- DAG desteği, gelecekteki bir yinelemeye ertelenmiştir
|
||||
|
||||
## Varlık Türleri
|
||||
|
||||
Hem GraphRAG hem de Agent, TrustGraph'e özgü alt türlere sahip olan PROV-O'yu temel ontoloji olarak kullanır:
|
||||
|
||||
### GraphRAG Türleri
|
||||
| Varlık | PROV-O Türü | TG Türleri | Açıklama |
|
||||
|--------|-------------|----------|-------------|
|
||||
| Soru | `prov:Activity` | `tg:Question`, `tg:GraphRagQuestion` | Kullanıcının sorgusu |
|
||||
| Keşif | `prov:Entity` | `tg:Exploration` | Bilgi grafiğinden alınan kenarlar |
|
||||
| Odak | `prov:Entity` | `tg:Focus` | Akıl yürütmeyle seçilen kenarlar |
|
||||
| Sentez | `prov:Entity` | `tg:Synthesis` | Sonuç |
|
||||
|
||||
### Ajan Türleri
|
||||
| Varlık | PROV-O Türü | TG Türleri | Açıklama |
|
||||
|--------|-------------|----------|-------------|
|
||||
| Soru | `prov:Activity` | `tg:Question`, `tg:AgentQuestion` | Kullanıcının sorgusu |
|
||||
| Analiz | `prov:Entity` | `tg:Analysis` | Her düşünme/eylem/gözlem döngüsü |
|
||||
| Sonuç | `prov:Entity` | `tg:Conclusion` | Sonuç |
|
||||
|
||||
### Belge RAG Türleri
|
||||
| Varlık | PROV-O Türü | TG Türleri | Açıklama |
|
||||
|--------|-------------|----------|-------------|
|
||||
| Soru | `prov:Activity` | `tg:Question`, `tg:DocRagQuestion` | Kullanıcının sorgusu |
|
||||
| Keşif | `prov:Entity` | `tg:Exploration` | Belge deposundan alınan parçalar |
|
||||
| Sentez | `prov:Entity` | `tg:Synthesis` | Sonuç |
|
||||
|
||||
**Not:** Belge RAG, GraphRAG'ın türlerinin bir alt kümesini kullanır (kenar seçimi/akıl yürütme aşaması olmadığından Odak adımı yoktur).
|
||||
|
||||
### Soru Alt Türleri
|
||||
|
||||
Tüm Soru varlıkları `tg:Question`'ı temel tür olarak paylaşır, ancak geri alma mekanizmasını tanımlamak için özel bir alt türe sahiptir:
|
||||
|
||||
| Alt Tür | URI Kalıbı | Mekanizma |
|
||||
|---------|-------------|-----------|
|
||||
| `tg:GraphRagQuestion` | `urn:trustgraph:question:{uuid}` | Bilgi grafiği RAG |
|
||||
| `tg:DocRagQuestion` | `urn:trustgraph:docrag:{uuid}` | Belge/parça RAG |
|
||||
| `tg:AgentQuestion` | `urn:trustgraph:agent:{uuid}` | ReAct ajanı |
|
||||
|
||||
Bu, tüm soruların `tg:Question` aracılığıyla sorgulanabilmesini sağlarken, alt tür aracılığıyla belirli bir mekanizma ile filtrelenmesini sağlar.
|
||||
|
||||
## Kaynak Modeli
|
||||
|
||||
```
|
||||
Question (urn:trustgraph:agent:{uuid})
|
||||
│
|
||||
│ tg:query = "User's question"
|
||||
│ prov:startedAtTime = timestamp
|
||||
│ rdf:type = prov:Activity, tg:Question
|
||||
│
|
||||
↓ prov:wasDerivedFrom
|
||||
│
|
||||
Analysis1 (urn:trustgraph:agent:{uuid}/i1)
|
||||
│
|
||||
│ tg:thought = "I need to query the knowledge base..."
|
||||
│ tg:action = "knowledge-query"
|
||||
│ tg:arguments = {"question": "..."}
|
||||
│ tg:observation = "Result from tool..."
|
||||
│ rdf:type = prov:Entity, tg:Analysis
|
||||
│
|
||||
↓ prov:wasDerivedFrom
|
||||
│
|
||||
Analysis2 (urn:trustgraph:agent:{uuid}/i2)
|
||||
│ ...
|
||||
↓ prov:wasDerivedFrom
|
||||
│
|
||||
Conclusion (urn:trustgraph:agent:{uuid}/final)
|
||||
│
|
||||
│ tg:answer = "The final response..."
|
||||
│ rdf:type = prov:Entity, tg:Conclusion
|
||||
```
|
||||
|
||||
### Belge RAG (Retrieval-Augmented Generation) Kaynak Modeli
|
||||
|
||||
```
|
||||
Question (urn:trustgraph:docrag:{uuid})
|
||||
│
|
||||
│ tg:query = "User's question"
|
||||
│ prov:startedAtTime = timestamp
|
||||
│ rdf:type = prov:Activity, tg:Question
|
||||
│
|
||||
↓ prov:wasGeneratedBy
|
||||
│
|
||||
Exploration (urn:trustgraph:docrag:{uuid}/exploration)
|
||||
│
|
||||
│ tg:chunkCount = 5
|
||||
│ tg:selectedChunk = "chunk-id-1"
|
||||
│ tg:selectedChunk = "chunk-id-2"
|
||||
│ ...
|
||||
│ rdf:type = prov:Entity, tg:Exploration
|
||||
│
|
||||
↓ prov:wasDerivedFrom
|
||||
│
|
||||
Synthesis (urn:trustgraph:docrag:{uuid}/synthesis)
|
||||
│
|
||||
│ tg:content = "The synthesized answer..."
|
||||
│ rdf:type = prov:Entity, tg:Synthesis
|
||||
```
|
||||
|
||||
## Gerekli Değişiklikler
|
||||
|
||||
### 1. Şema Değişiklikleri
|
||||
|
||||
**Dosya:** `trustgraph-base/trustgraph/schema/services/agent.py`
|
||||
|
||||
`AgentRequest`'ye `session_id` ve `collection` alanlarını ekleyin:
|
||||
```python
|
||||
@dataclass
|
||||
class AgentRequest:
|
||||
question: str = ""
|
||||
state: str = ""
|
||||
group: list[str] | None = None
|
||||
history: list[AgentStep] = field(default_factory=list)
|
||||
user: str = ""
|
||||
collection: str = "default" # NEW: Collection for provenance traces
|
||||
streaming: bool = False
|
||||
session_id: str = "" # NEW: For provenance tracking across iterations
|
||||
```
|
||||
|
||||
**Dosya:** `trustgraph-base/trustgraph/messaging/translators/agent.py`
|
||||
|
||||
Çeviriciyi, `session_id` ve `collection`'i hem `to_pulsar()` hem de `from_pulsar()` içinde işleyebilecek şekilde güncelleyin.
|
||||
|
||||
### 2. Ajan Hizmetine Açıklanabilirlik Üreticisini Ekle
|
||||
|
||||
**Dosya:** `trustgraph-flow/trustgraph/agent/react/service.py`
|
||||
|
||||
Bir "açıklanabilirlik" üreticisi kaydedin (GraphRAG ile aynı yapı):
|
||||
```python
|
||||
from ... base import ProducerSpec
|
||||
from ... schema import Triples
|
||||
|
||||
# In __init__:
|
||||
self.register_specification(
|
||||
ProducerSpec(
|
||||
name = "explainability",
|
||||
schema = Triples,
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
### 3. Kaynak Üçlü Oluşturma
|
||||
|
||||
**Dosya:** `trustgraph-base/trustgraph/provenance/agent.py`
|
||||
|
||||
Yardımcı fonksiyonlar oluşturun (GraphRAG'in `question_triples`, `exploration_triples`, vb. gibi):
|
||||
```python
|
||||
def agent_session_triples(session_uri, query, timestamp):
|
||||
"""Generate triples for agent Question."""
|
||||
return [
|
||||
Triple(s=session_uri, p=RDF_TYPE, o=PROV_ACTIVITY),
|
||||
Triple(s=session_uri, p=RDF_TYPE, o=TG_QUESTION),
|
||||
Triple(s=session_uri, p=TG_QUERY, o=query),
|
||||
Triple(s=session_uri, p=PROV_STARTED_AT_TIME, o=timestamp),
|
||||
]
|
||||
|
||||
def agent_iteration_triples(iteration_uri, parent_uri, thought, action, arguments, observation):
|
||||
"""Generate triples for one Analysis step."""
|
||||
return [
|
||||
Triple(s=iteration_uri, p=RDF_TYPE, o=PROV_ENTITY),
|
||||
Triple(s=iteration_uri, p=RDF_TYPE, o=TG_ANALYSIS),
|
||||
Triple(s=iteration_uri, p=TG_THOUGHT, o=thought),
|
||||
Triple(s=iteration_uri, p=TG_ACTION, o=action),
|
||||
Triple(s=iteration_uri, p=TG_ARGUMENTS, o=json.dumps(arguments)),
|
||||
Triple(s=iteration_uri, p=TG_OBSERVATION, o=observation),
|
||||
Triple(s=iteration_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
|
||||
]
|
||||
|
||||
def agent_final_triples(final_uri, parent_uri, answer):
|
||||
"""Generate triples for Conclusion."""
|
||||
return [
|
||||
Triple(s=final_uri, p=RDF_TYPE, o=PROV_ENTITY),
|
||||
Triple(s=final_uri, p=RDF_TYPE, o=TG_CONCLUSION),
|
||||
Triple(s=final_uri, p=TG_ANSWER, o=answer),
|
||||
Triple(s=final_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
|
||||
]
|
||||
```
|
||||
|
||||
### 4. Tür Tanımları
|
||||
|
||||
**Dosya:** `trustgraph-base/trustgraph/provenance/namespaces.py`
|
||||
|
||||
Açıklanabilirlik varlık türlerini ve ajan özniteliklerini ekleyin:
|
||||
```python
|
||||
# Explainability entity types (used by both GraphRAG and Agent)
|
||||
TG_QUESTION = TG + "Question"
|
||||
TG_EXPLORATION = TG + "Exploration"
|
||||
TG_FOCUS = TG + "Focus"
|
||||
TG_SYNTHESIS = TG + "Synthesis"
|
||||
TG_ANALYSIS = TG + "Analysis"
|
||||
TG_CONCLUSION = TG + "Conclusion"
|
||||
|
||||
# Agent predicates
|
||||
TG_THOUGHT = TG + "thought"
|
||||
TG_ACTION = TG + "action"
|
||||
TG_ARGUMENTS = TG + "arguments"
|
||||
TG_OBSERVATION = TG + "observation"
|
||||
TG_ANSWER = TG + "answer"
|
||||
```
|
||||
|
||||
## Değiştirilen Dosyalar
|
||||
|
||||
| Dosya | Değişiklik |
|
||||
|------|--------|
|
||||
| `trustgraph-base/trustgraph/schema/services/agent.py` | AgentRequest'e session_id ve collection eklendi |
|
||||
| `trustgraph-base/trustgraph/messaging/translators/agent.py` | Yeni alanlar için çevirici güncellendi |
|
||||
| `trustgraph-base/trustgraph/provenance/namespaces.py` | Varlık türleri, ajan önişlemleri ve Document RAG önişlemleri eklendi |
|
||||
| `trustgraph-base/trustgraph/provenance/triples.py` | GraphRAG üçlü oluşturucularına TG türleri eklendi, Document RAG üçlü oluşturucuları eklendi |
|
||||
| `trustgraph-base/trustgraph/provenance/uris.py` | Document RAG URI oluşturucuları eklendi |
|
||||
| `trustgraph-base/trustgraph/provenance/__init__.py` | Yeni türler, önişlemler ve Document RAG fonksiyonları dışa aktarıldı |
|
||||
| `trustgraph-base/trustgraph/schema/services/retrieval.py` | DocumentRagResponse'a explain_id ve explain_graph eklendi |
|
||||
| `trustgraph-base/trustgraph/messaging/translators/retrieval.py` | Açıklanabilirlik alanları için DocumentRagResponseTranslator güncellendi |
|
||||
| `trustgraph-flow/trustgraph/agent/react/service.py` | Açıklanabilirlik üretici + kayıt mantığı eklendi |
|
||||
| `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` | Açıklanabilirlik geri çağırması eklendi ve kaynak üçlüleri yayıldı |
|
||||
| `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` | Açıklanabilirlik üretici eklendi ve geri çağırma ile bağlandı |
|
||||
| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | Ajan izleme türleri işlendi |
|
||||
| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | Ajan oturumları, GraphRAG ile birlikte listelendi |
|
||||
|
||||
## Oluşturulan Dosyalar
|
||||
|
||||
| Dosya | Amaç |
|
||||
|------|---------|
|
||||
| `trustgraph-base/trustgraph/provenance/agent.py` | Ajan özel üçlü oluşturucuları |
|
||||
|
||||
## CLI Güncellemeleri
|
||||
|
||||
**Algılama:** Hem GraphRAG hem de Ajan Soruları `tg:Question` türündedir. Aşağıdakilerle ayırt edilir:
|
||||
1. URI kalıbı: `urn:trustgraph:agent:` vs `urn:trustgraph:question:`
|
||||
2. Türetilen varlıklar: `tg:Analysis` (ajan) vs `tg:Exploration` (GraphRAG)
|
||||
|
||||
**`list_explain_traces.py`:**
|
||||
- Tür sütununu (Ajan vs GraphRAG) gösterir
|
||||
|
||||
**`show_explain_trace.py`:**
|
||||
- İzleme türünü otomatik olarak algılar
|
||||
- Ajan işleme, şu öğeleri gösterir: Soru → Analiz adımı(ları) → Sonuç
|
||||
|
||||
## Geriye Dönük Uyumluluk
|
||||
|
||||
- `session_id` varsayılan olarak `""`'dir - eski istekler çalışır, ancak kaynak bilgisi olmayacaktır
|
||||
- `collection` varsayılan olarak `"default"`'dir - makul bir yedekleme
|
||||
- CLI, her iki izleme türünü de sorunsuz bir şekilde işler
|
||||
|
||||
## Doğrulama
|
||||
|
||||
```bash
|
||||
# Run an agent query
|
||||
tg-invoke-agent -q "What is the capital of France?"
|
||||
|
||||
# List traces (should show agent sessions with Type column)
|
||||
tg-list-explain-traces -U trustgraph -C default
|
||||
|
||||
# Show agent trace
|
||||
tg-show-explain-trace "urn:trustgraph:agent:xxx"
|
||||
```
|
||||
|
||||
## Gelecek Çalışmalar (Bu PR'de Değil)
|
||||
|
||||
- DAG bağımlılıkları (analiz N, birden fazla önceki analizden sonuçları kullandığında)
|
||||
- Araçlara özel köken bağlantısı (KnowledgeQuery → GraphRAG izi)
|
||||
- Akışlı köken yayını (sonunda toplu olarak değil, işlem sırasında yayınla)
|
||||
113
docs/tech-specs/tr/architecture-principles.tr.md
Normal file
113
docs/tech-specs/tr/architecture-principles.tr.md
Normal file
|
|
@ -0,0 +1,113 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Bilgi Grafiği Mimarisi Temelleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Bilgi Grafiği Mimarisi Temelleri
|
||||
|
||||
> **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.
|
||||
|
||||
## Temel 1: Özne-Yüklem-Nesne (ÖYY) Grafik Modeli
|
||||
**Karar**: Çekirdek bilgi gösterim modeli olarak SPO/RDF'yi benimse
|
||||
|
||||
**Gerekçe**:
|
||||
- Mevcut grafik teknolojileriyle maksimum esneklik ve uyumluluk sağlar
|
||||
- Diğer grafik sorgu dillerine (örneğin, SPO → Cypher, ancak tersi değil) sorunsuz çeviri sağlar
|
||||
- "Birçok" sonraki yeteneği "açığa çıkaran" bir temel oluşturur
|
||||
- Hem düğüm-düğüm ilişkilerini (ÖYY) hem de düğüm-literal ilişkilerini (RDF) destekler
|
||||
|
||||
**Uygulama**:
|
||||
- Temel veri yapısı: `node → edge → {node | literal}`
|
||||
- RDF standartlarıyla uyumluluğu korurken, gelişmiş SPO işlemlerini destekler
|
||||
|
||||
## Temel 2: LLM-Yerel Bilgi Grafiği Entegrasyonu
|
||||
**Karar**: Bilgi grafiği yapısını ve işlemlerini LLM etkileşimi için optimize et
|
||||
|
||||
**Gerekçe**:
|
||||
- Birincil kullanım durumu, LLM'lerin bilgi grafikleriyle etkileşimini içerir
|
||||
- Grafik teknolojisi seçimleri, diğer hususlara kıyasla LLM uyumluluğuna öncelik vermelidir
|
||||
- Yapılandırılmış bilgiyi kullanan doğal dil işleme iş akışlarını sağlar
|
||||
|
||||
**Uygulama**:
|
||||
- LLM'lerin etkili bir şekilde akıl yürütebileceği grafik şemalarını tasarla
|
||||
- Yaygın LLM etkileşim kalıpları için optimize et
|
||||
|
||||
## Temel 3: Gömme Tabanlı Grafik Navigasyonu
|
||||
**Karar**: Doğal dil sorgularını, gömmeler aracılığıyla doğrudan grafik düğümlerine eşleyin
|
||||
|
||||
**Gerekçe**:
|
||||
- NLP sorgusundan grafik navigasyonuna en basit yolu sağlar
|
||||
- Karmaşık ara sorgu oluşturma adımlarından kaçının
|
||||
- Grafik yapısı içinde verimli semantik arama yetenekleri sağlar
|
||||
|
||||
**Uygulama**:
|
||||
- `NLP Query → Graph Embeddings → Graph Nodes`
|
||||
- Tüm grafik varlıkları için gömme gösterimlerini koru
|
||||
- Sorgu çözümlemesi için doğrudan semantik benzerlik eşleştirmesini destekle
|
||||
|
||||
## Temel 4: Dağıtılmış Varlık Çözümlemesi ve Belirleyici Tanımlayıcılar
|
||||
**Karar**: Paralel bilgi çıkarma işlemini, deterministik varlık tanımlamasıyla (80% kuralı) destekle
|
||||
|
||||
**Gerekçe**:
|
||||
- **İdeal**: Tam durum görünürlüğü sağlayan tek işlem çıkarma, mükemmel varlık çözümlemesine olanak tanır
|
||||
- **Gerçeklik**: Ölçeklenebilirlik gereksinimleri, paralel işleme yetenekleri gerektirir
|
||||
- **Uzlaşma**: Dağıtılmış işlemler arasında deterministik varlık tanımlaması için tasarla
|
||||
|
||||
**Uygulama**:
|
||||
- Farklı bilgi çıkarıcılar arasında tutarlı, benzersiz tanımlayıcılar oluşturmak için mekanizmalar geliştir
|
||||
- Farklı işlemlerde bahsedilen aynı varlık, aynı tanımlayıcıya çözümlenmelidir
|
||||
- Yaklaşık olarak %20'lik bir oranın, alternatif işleme modelleri gerektirebilecek uç durumlara karşılık geldiğinin farkında olun
|
||||
- Karmaşık varlık çözümleme senaryoları için yedek mekanizmalar tasarla
|
||||
|
||||
## Temel 5: Yayın-Abonelik ile Olay Odaklı Mimari
|
||||
**Karar**: Sistem koordinasyonu için bir yayın-abone mesajlaşma sistemi uygula
|
||||
|
||||
**Gerekçe**:
|
||||
- Bilgi çıkarma, depolama ve sorgu bileşenleri arasında gevşek bir bağlama olanak tanır
|
||||
- Sistem genelinde gerçek zamanlı güncellemeleri ve bildirimleri destekler
|
||||
- Ölçeklenebilir, dağıtılmış iş akışlarını kolaylaştırır
|
||||
|
||||
**Uygulama**:
|
||||
- Sistem bileşenleri arasındaki mesaj odaklı koordinasyon
|
||||
- Bilgi güncellemeleri, çıkarma tamamlama ve sorgu sonuçları için olay akışları
|
||||
|
||||
## Temel 6: Geri Çağrılabilir Ajan İletişimi
|
||||
**Karar**: Ajan tabanlı işleme için geri çağrılabilir yayın-abone işlemlerini destekle
|
||||
|
||||
**Gerekçe**:
|
||||
- Ajanların birbirini tetikleyebildiği ve yanıtlayabildiği gelişmiş ajan iş akışlarına olanak tanır
|
||||
- Karmaşık, çok aşamalı bilgi işleme boru hatlarını destekler
|
||||
- Yinelemeli ve yinelemeli işleme kalıplarına izin verir
|
||||
|
||||
**Uygulama**:
|
||||
- Yayın-abone sistemi, geri çağrılabilir çağrıları güvenli bir şekilde işlemelidir
|
||||
- Sonsuz döngüleri önleyen ajan koordinasyon mekanizmaları
|
||||
- Ajan iş akışı orkestrasyonu desteği
|
||||
|
||||
## Temel 7: Sütun Veri Depolama Entegrasyonu
|
||||
**Karar**: Sorgu uyumluluğunun, sütunlu depolama sistemleriyle sağlanması.
|
||||
|
||||
**Gerekçe**:
|
||||
- Büyük bilgi veri kümeleri üzerinde verimli analitik sorgulara olanak tanır.
|
||||
- İş zekası ve raporlama kullanım senaryolarını destekler.
|
||||
- Grafik tabanlı bilgi gösterimini geleneksel analitik iş akışlarıyla birleştirir.
|
||||
|
||||
**Uygulama**:
|
||||
- Sorgu çevirme katmanı: Grafik sorguları → Sütunlu sorgular.
|
||||
- Hem grafik işlemlerini hem de analitik iş yüklerini destekleyen hibrit depolama stratejisi.
|
||||
- Her iki paradigma için de sorgu performansını koruyun.
|
||||
|
||||
---
|
||||
|
||||
## Mimari İlkeler Özeti
|
||||
|
||||
1. **Öncelikli Olarak Esneklik**: SPO/RDF modeli, maksimum uyarlanabilirlik sağlar.
|
||||
2. **LLM Optimizasyonu**: Tüm tasarım kararları, LLM etkileşim gereksinimlerini dikkate alır.
|
||||
3. **Anlamsal Verimlilik**: Optimum sorgu performansı için doğrudan gömülü-düğüm eşlemesi.
|
||||
4. **Pratik Ölçeklenebilirlik**: Mükemmel doğruluğu, pratik dağıtılmış işleme ile dengeleyin.
|
||||
5. **Olay Odaklı Koordinasyon**: Yayın-abone, gevşek bağlama ve ölçeklenebilirliğe olanak tanır.
|
||||
6. **Ajan Dostu**: Karmaşık, çoklu ajan iş akışlarını destekler.
|
||||
7. **Analitik Uyumluluk**: Kapsamlı sorgulama için grafik ve sütunlu paradigmaları birleştirir.
|
||||
|
||||
Bu temeller, teorik titizliği pratik ölçeklenebilirlik gereksinimleriyle dengeleyen, LLM entegrasyonu ve dağıtılmış işleme için optimize edilmiş bir bilgi grafiği mimarisi oluşturur.
|
||||
339
docs/tech-specs/tr/cassandra-consolidation.tr.md
Normal file
339
docs/tech-specs/tr/cassandra-consolidation.tr.md
Normal file
|
|
@ -0,0 +1,339 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Cassandra Yapılandırma Birleştirme: Teknik Özellikler"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Cassandra Yapılandırma Birleştirme: Teknik Özellikler
|
||||
|
||||
> **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.
|
||||
|
||||
**Durum:** Taslak
|
||||
**Yazar:** Yardımcı
|
||||
**Tarih:** 2024-09-03
|
||||
|
||||
## Genel Bakış
|
||||
|
||||
Bu özellik, TrustGraph kod tabanındaki Cassandra bağlantı parametreleri için tutarsız adlandırma ve yapılandırma kalıplarını ele almaktadır. Şu anda, iki farklı parametre adlandırma şeması bulunmaktadır (`cassandra_*` ve `graph_*`), bu da kafa karışıklığına ve bakım karmaşıklığına yol açmaktadır.
|
||||
|
||||
## Sorun Tanımı
|
||||
|
||||
Kod tabanı şu anda iki farklı Cassandra yapılandırma parametre seti kullanmaktadır:
|
||||
|
||||
1. **Bilgi/Yapılandırma/Kütüphane modülleri** aşağıdaki parametreleri kullanır:
|
||||
`cassandra_host` (sunucu listesi)
|
||||
`cassandra_user`
|
||||
`cassandra_password`
|
||||
|
||||
2. **Grafik/Depolama modülleri** aşağıdaki parametreleri kullanır:
|
||||
`graph_host` (tek bir sunucu, bazen listeye dönüştürülür)
|
||||
`graph_username`
|
||||
`graph_password`
|
||||
|
||||
3. **Tutarsız komut satırı kullanımı**:
|
||||
Bazı işleme birimleri (örneğin, `kg-store`), Cassandra ayarlarını komut satırı argümanları olarak sunmaz
|
||||
Diğer işleme birimleri bunları farklı adlar ve formatlarla sunar
|
||||
Yardım metni, ortam değişkeni varsayılanlarını yansıtmaz
|
||||
|
||||
Her iki parametre seti de aynı Cassandra kümesine bağlanır, ancak farklı adlandırma kuralları kullanır, bu da şunlara neden olur:
|
||||
Kullanıcılar için yapılandırma karışıklığı
|
||||
Artan bakım yükü
|
||||
Tutarsız dokümantasyon
|
||||
Yanlış yapılandırma riski
|
||||
Bazı işleme birimlerinde ayarları komut satırı aracılığıyla geçersiz kılma imkansızlığı
|
||||
|
||||
## Önerilen Çözüm
|
||||
|
||||
### 1. Parametre Adlarını Standartlaştırın
|
||||
|
||||
Tüm modüller, tutarlı `cassandra_*` parametre adlarını kullanacaktır:
|
||||
`cassandra_host` - Sunucu listesi (içeride liste olarak saklanır)
|
||||
`cassandra_username` - Kimlik doğrulama için kullanıcı adı
|
||||
`cassandra_password` - Kimlik doğrulama için parola
|
||||
|
||||
### 2. Komut Satırı Argümanları
|
||||
|
||||
TÜM işleme birimleri, Cassandra yapılandırmasını komut satırı argümanları aracılığıyla sunmalıdır:
|
||||
`--cassandra-host` - Virgülle ayrılmış sunucu listesi
|
||||
`--cassandra-username` - Kimlik doğrulama için kullanıcı adı
|
||||
`--cassandra-password` - Kimlik doğrulama için parola
|
||||
|
||||
### 3. Ortam Değişkeni Geri Düşüşü
|
||||
|
||||
Komut satırı parametreleri açıkça sağlanmadığında, sistem ortam değişkenlerini kontrol edecektir:
|
||||
`CASSANDRA_HOST` - Virgülle ayrılmış sunucu listesi
|
||||
`CASSANDRA_USERNAME` - Kimlik doğrulama için kullanıcı adı
|
||||
`CASSANDRA_PASSWORD` - Kimlik doğrulama için parola
|
||||
|
||||
### 4. Varsayılan Değerler
|
||||
|
||||
Ne komut satırı parametreleri ne de ortam değişkenleri belirtilmediğinde:
|
||||
`cassandra_host`, `["cassandra"]`'e varsayılan olarak ayarlanır
|
||||
`cassandra_username`, `None`'e (kimlik doğrulama yok) varsayılan olarak ayarlanır
|
||||
`cassandra_password`, `None`'e (kimlik doğrulama yok) varsayılan olarak ayarlanır
|
||||
|
||||
### 5. Yardım Metni Gereksinimleri
|
||||
|
||||
`--help` çıktısı şunları içermelidir:
|
||||
Ortam değişkeni değerleri ayarlandığında, bunları varsayılan değerler olarak göstermelidir
|
||||
Parola değerlerini asla göstermemelidir (bunun yerine `****` veya `<set>` göstermelidir)
|
||||
Çözüm sırasını yardım metninde açıkça belirtmelidir
|
||||
|
||||
Örnek yardım çıktısı:
|
||||
```
|
||||
--cassandra-host HOST
|
||||
Cassandra host list, comma-separated (default: prod-cluster-1,prod-cluster-2)
|
||||
[from CASSANDRA_HOST environment variable]
|
||||
|
||||
--cassandra-username USERNAME
|
||||
Cassandra username (default: cassandra_user)
|
||||
[from CASSANDRA_USERNAME environment variable]
|
||||
|
||||
--cassandra-password PASSWORD
|
||||
Cassandra password (default: <set from environment>)
|
||||
```
|
||||
|
||||
## Uygulama Detayları
|
||||
|
||||
### Parametre Çözümleme Sırası
|
||||
|
||||
Her Cassandra parametresi için, çözümleme sırası aşağıdaki olacaktır:
|
||||
1. Komut satırı argümanı değeri
|
||||
2. Ortam değişkeni (`CASSANDRA_*`)
|
||||
3. Varsayılan değer
|
||||
|
||||
### Ana Bilgisayar Parametreleri Yönetimi
|
||||
|
||||
`cassandra_host` parametresi:
|
||||
Komut satırı, virgülle ayrılmış bir dize kabul eder: `--cassandra-host "host1,host2,host3"`
|
||||
Ortam değişkeni, virgülle ayrılmış bir dize kabul eder: `CASSANDRA_HOST="host1,host2,host3"`
|
||||
İçeride her zaman bir liste olarak saklanır: `["host1", "host2", "host3"]`
|
||||
Tek bir ana bilgisayar: `"localhost"` → `["localhost"]`'e dönüştürülür
|
||||
Zaten bir liste: `["host1", "host2"]` → olduğu gibi kullanılır
|
||||
|
||||
### Kimlik Doğrulama Mantığı
|
||||
|
||||
Kimlik doğrulama, hem `cassandra_username` hem de `cassandra_password` sağlandığında kullanılacaktır:
|
||||
```python
|
||||
if cassandra_username and cassandra_password:
|
||||
# Use SSL context and PlainTextAuthProvider
|
||||
else:
|
||||
# Connect without authentication
|
||||
```
|
||||
|
||||
## Değiştirilecek Dosyalar
|
||||
|
||||
### `graph_*` parametrelerini kullanan modüller (değiştirilecek):
|
||||
`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/objects/cassandra/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/rows/cassandra/write.py`
|
||||
`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
|
||||
|
||||
### `cassandra_*` parametrelerini kullanan modüller (ortam değişkeni geri dönüşü ile güncellenecek):
|
||||
`trustgraph-flow/trustgraph/tables/config.py`
|
||||
`trustgraph-flow/trustgraph/tables/knowledge.py`
|
||||
`trustgraph-flow/trustgraph/tables/library.py`
|
||||
`trustgraph-flow/trustgraph/storage/knowledge/store.py`
|
||||
`trustgraph-flow/trustgraph/cores/knowledge.py`
|
||||
`trustgraph-flow/trustgraph/librarian/librarian.py`
|
||||
`trustgraph-flow/trustgraph/librarian/service.py`
|
||||
`trustgraph-flow/trustgraph/config/service/service.py`
|
||||
`trustgraph-flow/trustgraph/cores/service.py`
|
||||
|
||||
### Güncellenecek Test Dosyaları:
|
||||
`tests/unit/test_cores/test_knowledge_manager.py`
|
||||
`tests/unit/test_storage/test_triples_cassandra_storage.py`
|
||||
`tests/unit/test_query/test_triples_cassandra_query.py`
|
||||
`tests/integration/test_objects_cassandra_integration.py`
|
||||
|
||||
## Uygulama Stratejisi
|
||||
|
||||
### Aşama 1: Ortak Yapılandırma Yardımcı Programı Oluşturma
|
||||
Tüm işlemcilerde Cassandra yapılandırmasını standartlaştırmak için yardımcı işlevler oluşturun:
|
||||
|
||||
```python
|
||||
import os
|
||||
import argparse
|
||||
|
||||
def get_cassandra_defaults():
|
||||
"""Get default values from environment variables or fallback."""
|
||||
return {
|
||||
'host': os.getenv('CASSANDRA_HOST', 'cassandra'),
|
||||
'username': os.getenv('CASSANDRA_USERNAME'),
|
||||
'password': os.getenv('CASSANDRA_PASSWORD')
|
||||
}
|
||||
|
||||
def add_cassandra_args(parser: argparse.ArgumentParser):
|
||||
"""
|
||||
Add standardized Cassandra arguments to an argument parser.
|
||||
Shows environment variable values in help text.
|
||||
"""
|
||||
defaults = get_cassandra_defaults()
|
||||
|
||||
# Format help text with env var indication
|
||||
host_help = f"Cassandra host list, comma-separated (default: {defaults['host']})"
|
||||
if 'CASSANDRA_HOST' in os.environ:
|
||||
host_help += " [from CASSANDRA_HOST]"
|
||||
|
||||
username_help = f"Cassandra username"
|
||||
if defaults['username']:
|
||||
username_help += f" (default: {defaults['username']})"
|
||||
if 'CASSANDRA_USERNAME' in os.environ:
|
||||
username_help += " [from CASSANDRA_USERNAME]"
|
||||
|
||||
password_help = "Cassandra password"
|
||||
if defaults['password']:
|
||||
password_help += " (default: <set>)"
|
||||
if 'CASSANDRA_PASSWORD' in os.environ:
|
||||
password_help += " [from CASSANDRA_PASSWORD]"
|
||||
|
||||
parser.add_argument(
|
||||
'--cassandra-host',
|
||||
default=defaults['host'],
|
||||
help=host_help
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--cassandra-username',
|
||||
default=defaults['username'],
|
||||
help=username_help
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--cassandra-password',
|
||||
default=defaults['password'],
|
||||
help=password_help
|
||||
)
|
||||
|
||||
def resolve_cassandra_config(args) -> tuple[list[str], str|None, str|None]:
|
||||
"""
|
||||
Convert argparse args to Cassandra configuration.
|
||||
|
||||
Returns:
|
||||
tuple: (hosts_list, username, password)
|
||||
"""
|
||||
# Convert host string to list
|
||||
if isinstance(args.cassandra_host, str):
|
||||
hosts = [h.strip() for h in args.cassandra_host.split(',')]
|
||||
else:
|
||||
hosts = args.cassandra_host
|
||||
|
||||
return hosts, args.cassandra_username, args.cassandra_password
|
||||
```
|
||||
|
||||
### 2. Aşama: `graph_*` Parametrelerini Kullanan Modülleri Güncelleme
|
||||
1. Parametre adlarını `graph_*`'dan `cassandra_*`'e değiştirin.
|
||||
2. Özel `add_args()` yöntemlerini standart `add_cassandra_args()` yöntemleriyle değiştirin.
|
||||
3. Ortak yapılandırma yardımcı fonksiyonlarını kullanın.
|
||||
4. Dokümantasyon metinlerini güncelleyin.
|
||||
|
||||
Örnek dönüşüm:
|
||||
```python
|
||||
# OLD CODE
|
||||
@staticmethod
|
||||
def add_args(parser):
|
||||
parser.add_argument(
|
||||
'-g', '--graph-host',
|
||||
default="localhost",
|
||||
help=f'Graph host (default: localhost)'
|
||||
)
|
||||
parser.add_argument(
|
||||
'--graph-username',
|
||||
default=None,
|
||||
help=f'Cassandra username'
|
||||
)
|
||||
|
||||
# NEW CODE
|
||||
@staticmethod
|
||||
def add_args(parser):
|
||||
FlowProcessor.add_args(parser)
|
||||
add_cassandra_args(parser) # Use standard helper
|
||||
```
|
||||
|
||||
### 3. Aşama: `cassandra_*` Parametrelerini Kullanarak Modülleri Güncelleme
|
||||
1. Eksik olan yerlerde komut satırı argümanı desteğini ekleyin (örneğin, `kg-store`)
|
||||
2. Mevcut argüman tanımlarını `add_cassandra_args()` ile değiştirin
|
||||
3. Tutarlı çözümleme için `resolve_cassandra_config()`'ı kullanın
|
||||
4. Tutarlı ana bilgisayar listesi işleme sağlayın
|
||||
|
||||
### 4. Aşama: Testleri ve Belgeleri Güncelleme
|
||||
1. Tüm test dosyalarını yeni parametre adlarını kullanacak şekilde güncelleyin
|
||||
2. Komut satırı (CLI) belgelerini güncelleyin
|
||||
3. API belgelerini güncelleyin
|
||||
4. Ortam değişkeni belgelerini ekleyin
|
||||
|
||||
## Geriye Dönük Uyumluluk
|
||||
|
||||
Geçiş sırasında geriye dönük uyumluluğu korumak için:
|
||||
|
||||
1. `graph_*` parametreleri için **kullanımdan kaldırma uyarıları**
|
||||
2. **Parametre takma adları** - başlangıçta hem eski hem de yeni adları kabul edin
|
||||
3. **Aşamalı dağıtım** birden fazla sürümde
|
||||
4. **Belge güncellemeleri** ve geçiş kılavuzu
|
||||
|
||||
Örnek geriye dönük uyumluluk kodu:
|
||||
```python
|
||||
def __init__(self, **params):
|
||||
# Handle deprecated graph_* parameters
|
||||
if 'graph_host' in params:
|
||||
warnings.warn("graph_host is deprecated, use cassandra_host", DeprecationWarning)
|
||||
params.setdefault('cassandra_host', params.pop('graph_host'))
|
||||
|
||||
if 'graph_username' in params:
|
||||
warnings.warn("graph_username is deprecated, use cassandra_username", DeprecationWarning)
|
||||
params.setdefault('cassandra_username', params.pop('graph_username'))
|
||||
|
||||
# ... continue with standard resolution
|
||||
```
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
1. **Birim testleri**, yapılandırma çözümleme mantığı için
|
||||
2. **Entegrasyon testleri**, çeşitli yapılandırma kombinasyonlarıyla
|
||||
3. **Ortam değişkeni testleri**
|
||||
4. **Geriye dönük uyumluluk testleri**, kullanımdan kaldırılmış parametrelerle
|
||||
5. **Docker compose testleri**, ortam değişkenleriyle
|
||||
|
||||
## Dokümantasyon Güncellemeleri
|
||||
|
||||
1. Tüm CLI komutu dokümantasyonunu güncelleyin
|
||||
2. API dokümantasyonunu güncelleyin
|
||||
3. Geçiş kılavuzu oluşturun
|
||||
4. Docker compose örneklerini güncelleyin
|
||||
5. Yapılandırma referans dokümantasyonunu güncelleyin
|
||||
|
||||
## Riskler ve Azaltma
|
||||
|
||||
| Risk | Etki | Azaltma |
|
||||
|------|--------|------------|
|
||||
| Kullanıcılar için bozucu değişiklikler | Yüksek | Geriye dönük uyumluluk süresi uygulayın |
|
||||
| Geçiş sırasında yapılandırma karışıklığı | Orta | Açık dokümantasyon ve kullanımdan kaldırma uyarıları |
|
||||
| Test hataları | Orta | Kapsamlı test güncellemeleri |
|
||||
| Docker dağıtım sorunları | Yüksek | Tüm Docker compose örneklerini güncelleyin |
|
||||
|
||||
## Başarı Kriterleri
|
||||
|
||||
[ ] Tüm modüller, tutarlı `cassandra_*` parametre adlarını kullanır
|
||||
[ ] Tüm işlemciler, Cassandra ayarlarını komut satırı argümanları aracılığıyla sunar
|
||||
[ ] Komut satırı yardım metni, ortam değişkeni varsayılanlarını gösterir
|
||||
[ ] Parola değerleri, yardım metninde asla görüntülenmez
|
||||
[ ] Ortam değişkeni yedeklemesi doğru şekilde çalışır
|
||||
[ ] `cassandra_host`, dahili olarak tutarlı bir şekilde bir liste olarak işlenir
|
||||
[ ] Geriye dönüştürülebilirlik, en az 2 sürüm için korunur
|
||||
[ ] Tüm testler, yeni yapılandırma sistemiyle geçer
|
||||
[ ] Dokümantasyon tamamen güncellenmiştir
|
||||
[ ] Docker compose örnekleri, ortam değişkenleriyle çalışır
|
||||
|
||||
## Zaman Çizelgesi
|
||||
|
||||
**1. Hafta:** Ortak yapılandırma yardımcı programını uygulayın ve `graph_*` modüllerini güncelleyin
|
||||
**2. Hafta:** Mevcut `cassandra_*` modüllerine ortam değişkeni desteği ekleyin
|
||||
**3. Hafta:** Testleri ve dokümantasyonu güncelleyin
|
||||
**4. Hafta:** Entegrasyon testi ve hata düzeltmeleri
|
||||
|
||||
## Gelecek Hususlar
|
||||
|
||||
Bu kalıbı diğer veritabanı yapılandırmalarına (örneğin, Elasticsearch) genişletmeyi düşünün
|
||||
Yapılandırma doğrulama ve daha iyi hata mesajları uygulayın
|
||||
Cassandra bağlantı havuzu yapılandırması desteği ekleyin
|
||||
Yapılandırma dosyası desteği eklemeyi düşünün (.env dosyaları)
|
||||
687
docs/tech-specs/tr/cassandra-performance-refactor.tr.md
Normal file
687
docs/tech-specs/tr/cassandra-performance-refactor.tr.md
Normal file
|
|
@ -0,0 +1,687 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Teknik Özellikler: Cassandra Bilgi Tabanı Performans Yenilemesi"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Teknik Özellikler: Cassandra Bilgi Tabanı Performans Yenilemesi
|
||||
|
||||
> **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.
|
||||
|
||||
**Durum:** Taslak
|
||||
**Yazar:** Yardımcı
|
||||
**Tarih:** 2025-09-18
|
||||
|
||||
## Genel Bakış
|
||||
|
||||
Bu özellik, TrustGraph Cassandra bilgi tabanı uygulamasındaki performans sorunlarına değinmekte ve RDF üçlü depolama ve sorgulama için optimizasyonlar önermektedir.
|
||||
|
||||
## Mevcut Uygulama
|
||||
|
||||
### Şema Tasarımı
|
||||
|
||||
Mevcut uygulama, `trustgraph-flow/trustgraph/direct/cassandra_kg.py`'da tek bir tablo tasarımı kullanmaktadır:
|
||||
|
||||
```sql
|
||||
CREATE TABLE triples (
|
||||
collection text,
|
||||
s text,
|
||||
p text,
|
||||
o text,
|
||||
PRIMARY KEY (collection, s, p, o)
|
||||
);
|
||||
```
|
||||
|
||||
**İkincil İndeksler:**
|
||||
`triples_s` ON `s` (özne)
|
||||
`triples_p` ON `p` (yüklem)
|
||||
`triples_o` ON `o` (nesne)
|
||||
|
||||
### Sorgu Desenleri
|
||||
|
||||
Mevcut uygulama, 8 farklı sorgu desenini desteklemektedir:
|
||||
|
||||
1. **get_all(collection, limit=50)** - Bir koleksiyon için tüm üçlüleri getirir.
|
||||
```sql
|
||||
SELECT s, p, o FROM triples WHERE collection = ? LIMIT 50
|
||||
```
|
||||
|
||||
2. **get_s(collection, s, limit=10)** - Konuya göre sorgulama
|
||||
```sql
|
||||
SELECT p, o FROM triples WHERE collection = ? AND s = ? LIMIT 10
|
||||
```
|
||||
|
||||
3. **get_p(collection, p, limit=10)** - Öznitelik kullanarak sorgulama
|
||||
```sql
|
||||
SELECT s, o FROM triples WHERE collection = ? AND p = ? LIMIT 10
|
||||
```
|
||||
|
||||
4. **get_o(collection, o, limit=10)** - Nesneye göre sorgulama
|
||||
```sql
|
||||
SELECT s, p FROM triples WHERE collection = ? AND o = ? LIMIT 10
|
||||
```
|
||||
|
||||
5. **get_sp(collection, s, p, limit=10)** - Konu + yüklem ile sorgulama
|
||||
```sql
|
||||
SELECT o FROM triples WHERE collection = ? AND s = ? AND p = ? LIMIT 10
|
||||
```
|
||||
|
||||
6. **get_po(collection, p, o, limit=10)** - Öznitelik + nesneye göre sorgulama ⚠️
|
||||
```sql
|
||||
SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
|
||||
```
|
||||
|
||||
7. **get_os(collection, o, s, limit=10)** - Nesne + konu ile sorgulama ⚠️
|
||||
```sql
|
||||
SELECT p FROM triples WHERE collection = ? AND o = ? AND s = ? LIMIT 10 ALLOW FILTERING
|
||||
```
|
||||
|
||||
8. **get_spo(collection, s, p, o, limit=10)** - Tam üçlü eşleşme
|
||||
```sql
|
||||
SELECT s as x FROM triples WHERE collection = ? AND s = ? AND p = ? AND o = ? LIMIT 10
|
||||
```
|
||||
|
||||
### Mevcut Mimari
|
||||
|
||||
**Dosya: `trustgraph-flow/trustgraph/direct/cassandra_kg.py`**
|
||||
Tüm işlemleri yöneten tek `KnowledgeGraph` sınıfı
|
||||
Küresel `_active_clusters` listesi aracılığıyla bağlantı havuzu
|
||||
Sabit tablo adı: `"triples"`
|
||||
Kullanıcı modeli başına keyspace
|
||||
Faktörü 1 olan SimpleStrategy replikasyonu
|
||||
|
||||
**Entegrasyon Noktaları:**
|
||||
**Yazma Yolu:** `trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
|
||||
**Sorgu Yolu:** `trustgraph-flow/trustgraph/query/triples/cassandra/service.py`
|
||||
**Bilgi Deposu:** `trustgraph-flow/trustgraph/tables/knowledge.py`
|
||||
|
||||
## Tespit Edilen Performans Sorunları
|
||||
|
||||
### Şema Seviyesi Sorunlar
|
||||
|
||||
1. **Verimsiz Birincil Anahtar Tasarımı**
|
||||
Mevcut: `PRIMARY KEY (collection, s, p, o)`
|
||||
Sık erişim kalıpları için zayıf kümelenmeye neden olur
|
||||
Pahalı ikincil indeks kullanımını zorlar
|
||||
|
||||
2. **İkincil İndeks Aşırı Kullanımı** ⚠️
|
||||
Yüksek kardinaliteli sütunlarda (s, p, o) üç ikincil indeks
|
||||
Cassandra'daki ikincil indeksler pahalıdır ve iyi ölçeklenmez
|
||||
6 ve 7 numaralı sorgular `ALLOW FILTERING` gerektirir, bu da zayıf veri modellemesini gösterir
|
||||
|
||||
3. **Sıcak Bölüm Riski**
|
||||
Tek bölüm anahtarı `collection`, sıcak bölümlere neden olabilir
|
||||
Büyük koleksiyonlar tek düğümlere yoğunlaşacaktır
|
||||
Yük dengeleme için dağıtım stratejisi yoktur
|
||||
|
||||
### Sorgu Seviyesi Sorunlar
|
||||
|
||||
1. **ALLOW FILTERING Kullanımı** ⚠️
|
||||
İki sorgu türü (get_po, get_os) `ALLOW FILTERING` gerektirir
|
||||
Bu sorgular birden fazla bölümü tarar ve son derece pahalıdır
|
||||
Performans, veri boyutuyla doğrusal olarak düşer
|
||||
|
||||
2. **Verimsiz Erişim Kalıpları**
|
||||
Yaygın RDF sorgu kalıpları için optimizasyon yoktur
|
||||
Sık sorgu kombinasyonları için bileşik indeksler eksiktir
|
||||
Grafik geçiş kalıpları dikkate alınmamıştır
|
||||
|
||||
3. **Sorgu Optimizasyonu Eksikliği**
|
||||
Hazırlanmış ifade önbelleği yok
|
||||
Sorgu ipuçları veya optimizasyon stratejileri yok
|
||||
Basit LIMIT'in ötesinde sayfalama dikkate alınmamıştır
|
||||
|
||||
## Problem Tanımı
|
||||
|
||||
Mevcut Cassandra bilgi tabanı uygulaması, iki kritik performans darboğazına sahiptir:
|
||||
|
||||
### 1. Verimsiz get_po Sorgusu Performansı
|
||||
|
||||
`get_po(collection, p, o)` sorgusu, `ALLOW FILTERING` gerektirdiği için son derece verimsizdir:
|
||||
|
||||
```sql
|
||||
SELECT s FROM triples WHERE collection = ? AND p = ? AND o = ? LIMIT 10 ALLOW FILTERING
|
||||
```
|
||||
|
||||
**Neden bunun sorunlu olduğu:**
|
||||
`ALLOW FILTERING`, Cassandra'nın koleksiyon içindeki tüm bölümleri taramasını zorlar.
|
||||
Performans, veri boyutuyla doğrusal olarak düşer.
|
||||
Bu, yaygın bir RDF sorgu desenidir (belirli bir öznelik-nesne ilişkisine sahip konuları bulmak).
|
||||
Veri büyüdükçe kümede önemli bir yük oluşturur.
|
||||
|
||||
### 2. Kötü Kümeleme Stratejisi
|
||||
|
||||
Mevcut birincil anahtar `PRIMARY KEY (collection, s, p, o)`, minimum kümeleme faydası sağlar:
|
||||
|
||||
**Mevcut kümeleme ile ilgili sorunlar:**
|
||||
Bölüm anahtarı olarak `collection`, verileri etkili bir şekilde dağıtmaz.
|
||||
Çoğu koleksiyon, kümelemeyi etkisiz hale getiren çeşitli veriler içerir.
|
||||
RDF sorgularındaki yaygın erişim kalıpları dikkate alınmamıştır.
|
||||
Büyük koleksiyonlar, tek düğümlerde "sıcak" bölümler oluşturur.
|
||||
Kümeleme sütunları (s, p, o), tipik grafik geçiş kalıpları için optimize edilmemiştir.
|
||||
|
||||
**Etkisi:**
|
||||
Sorgular, veri yerelliğinden faydalanmaz.
|
||||
Kötü önbellek kullanımı.
|
||||
Küme düğümleri arasında düzensiz yük dağılımı.
|
||||
Koleksiyonlar büyüdükçe ölçeklenebilirlik darboğazları.
|
||||
|
||||
## Önerilen Çözüm: 4-Tablolu Normalizasyon Stratejisi
|
||||
|
||||
### Genel Bakış
|
||||
|
||||
Tek `triples` tablosunu, belirli sorgu kalıpları için optimize edilmiş dört özel amaçlı tabloyla değiştirin. Bu, ikincil dizinlere ve ALLOW FILTERING'e olan ihtiyacı ortadan kaldırırken, tüm sorgu türleri için optimum performans sağlar. Dördüncü tablo, bileşik bölüm anahtarlarına rağmen verimli koleksiyon silme olanağı sağlar.
|
||||
|
||||
### Yeni Şema Tasarımı
|
||||
|
||||
**Tablo 1: Konu Odaklı Sorgular (triples_s)**
|
||||
```sql
|
||||
CREATE TABLE triples_s (
|
||||
collection text,
|
||||
s text,
|
||||
p text,
|
||||
o text,
|
||||
PRIMARY KEY ((collection, s), p, o)
|
||||
);
|
||||
```
|
||||
**Optimize eder:** get_s, get_sp, get_os
|
||||
**Bölüm Anahtarı:** (collection, s) - Yalnızca collection'dan daha iyi dağılım sağlar
|
||||
**Kümeleme:** (p, o) - Bir konu için verimli öznelik/nesne aramalarını sağlar
|
||||
|
||||
**Tablo 2: Öznelik-Nesne Sorguları (triples_p)**
|
||||
```sql
|
||||
CREATE TABLE triples_p (
|
||||
collection text,
|
||||
p text,
|
||||
o text,
|
||||
s text,
|
||||
PRIMARY KEY ((collection, p), o, s)
|
||||
);
|
||||
```
|
||||
**Optimize eder:** get_p, get_po (ALLOW FILTERING özelliğini ortadan kaldırır!)
|
||||
**Bölüm Anahtarı:** (collection, p) - Öznitelik yoluyla doğrudan erişim
|
||||
**Kümeleme:** (o, s) - Verimli nesne-özne geçişi
|
||||
|
||||
**Tablo 3: Nesne Odaklı Sorgular (triples_o)**
|
||||
```sql
|
||||
CREATE TABLE triples_o (
|
||||
collection text,
|
||||
o text,
|
||||
s text,
|
||||
p text,
|
||||
PRIMARY KEY ((collection, o), s, p)
|
||||
);
|
||||
```
|
||||
**Optimize eder:** get_o
|
||||
**Bölüm Anahtarı:** (collection, o) - Nesneye doğrudan erişim
|
||||
**Kümeleme:** (s, p) - Verimli özne-yüklem geçişi
|
||||
|
||||
**Tablo 4: Koleksiyon Yönetimi ve SPO Sorguları (triples_collection)**
|
||||
```sql
|
||||
CREATE TABLE triples_collection (
|
||||
collection text,
|
||||
s text,
|
||||
p text,
|
||||
o text,
|
||||
PRIMARY KEY (collection, s, p, o)
|
||||
);
|
||||
```
|
||||
**Optimize eder:** get_spo, delete_collection
|
||||
**Bölüm Anahtarı:** sadece koleksiyon - Verimli koleksiyon seviyesindeki işlemleri sağlar.
|
||||
**Kümeleme:** (s, p, o) - Standart üçlü sıralama
|
||||
**Amaç:** Hem tam SPO aramaları için hem de silme indeksi olarak çift amaçlı kullanım.
|
||||
|
||||
### Sorgu Eşlemesi
|
||||
|
||||
| Orijinal Sorgu | Hedef Tablo | Performans İyileştirmesi |
|
||||
|----------------|-------------|------------------------|
|
||||
| get_all(collection) | triples_s | FİLTRELEME İZNİ VERİLEBİLİR (taramaya uygun) |
|
||||
| get_s(collection, s) | triples_s | Doğrudan bölüm erişimi |
|
||||
| get_p(collection, p) | triples_p | Doğrudan bölüm erişimi |
|
||||
| get_o(collection, o) | triples_o | Doğrudan bölüm erişimi |
|
||||
| get_sp(collection, s, p) | triples_s | Bölüm + kümeleme |
|
||||
| get_po(collection, p, o) | triples_p | **Artık FİLTRELEME İZNİ YOK!** |
|
||||
| get_os(collection, o, s) | triples_o | Bölüm + kümeleme |
|
||||
| get_spo(collection, s, p, o) | triples_collection | Tam anahtar araması |
|
||||
| delete_collection(collection) | triples_collection | İndeksi oku, tümünü toplu olarak sil |
|
||||
|
||||
### Koleksiyon Silme Stratejisi
|
||||
|
||||
Birleşik bölüm anahtarlarıyla, `DELETE FROM table WHERE collection = ?`'ı doğrudan çalıştıramayız. Bunun yerine:
|
||||
|
||||
1. **Okuma Aşaması:** Tüm üçlüleri saymak için `triples_collection` sorgusunu kullanın:
|
||||
```sql
|
||||
SELECT s, p, o FROM triples_collection WHERE collection = ?
|
||||
```
|
||||
Bu, `collection`'ın bu tablo için bölümleme anahtarı olması nedeniyle verimlidir.
|
||||
|
||||
2. **Silme Aşaması:** Her (s, p, o) üçlüsü için, tüm 4 tablodan, tam bölümleme anahtarlarını kullanarak silin:
|
||||
```sql
|
||||
DELETE FROM triples_s WHERE collection = ? AND s = ? AND p = ? AND o = ?
|
||||
DELETE FROM triples_p WHERE collection = ? AND p = ? AND o = ? AND s = ?
|
||||
DELETE FROM triples_o WHERE collection = ? AND o = ? AND s = ? AND p = ?
|
||||
DELETE FROM triples_collection WHERE collection = ? AND s = ? AND p = ? AND o = ?
|
||||
```
|
||||
Verimlilik için 100'lük gruplar halinde işlenir.
|
||||
|
||||
**Ayrılık Analizi:**
|
||||
✅ Dağıtılmış bölümlerle optimum sorgu performansını korur.
|
||||
✅ Büyük koleksiyonlar için "sıcak" bölümler yoktur.
|
||||
❌ Daha karmaşık silme mantığı (okuyup sonra sil).
|
||||
❌ Silme süresi, koleksiyon boyutuna orantılıdır.
|
||||
|
||||
### Avantajlar
|
||||
|
||||
1. **ALLOW FILTERING'i ortadan kaldırır** - Her sorgunun optimum bir erişim yolu vardır (get_all taraması hariç).
|
||||
2. **İkincil İndeks Yok** - Her tablo, kendi sorgu deseninin indeksidir.
|
||||
3. **Daha İyi Veri Dağılımı** - Bileşik bölüm anahtarları, yükü etkili bir şekilde dağıtır.
|
||||
4. **Öngörülebilir Performans** - Sorgu süresi, toplam veriye değil, sonuç boyutuna orantılıdır.
|
||||
5. **Cassandra'nın Güçlerinden Yararlanır** - Cassandra'nın mimarisi için tasarlanmıştır.
|
||||
6. **Koleksiyon Silme İşlemini Etkinleştirir** - triples_collection, silme indeksi olarak hizmet eder.
|
||||
|
||||
## Uygulama Planı
|
||||
|
||||
### Değiştirilmesi Gereken Dosyalar
|
||||
|
||||
#### Birincil Uygulama Dosyası
|
||||
|
||||
**`trustgraph-flow/trustgraph/direct/cassandra_kg.py`** - Tamamen yeniden yazılması gerekir.
|
||||
|
||||
**Yeniden Düzenlenmesi Gereken Mevcut Yöntemler:**
|
||||
```python
|
||||
# Schema initialization
|
||||
def init(self) -> None # Replace single table with three tables
|
||||
|
||||
# Insert operations
|
||||
def insert(self, collection, s, p, o) -> None # Write to all three tables
|
||||
|
||||
# Query operations (API unchanged, implementation optimized)
|
||||
def get_all(self, collection, limit=50) # Use triples_by_subject
|
||||
def get_s(self, collection, s, limit=10) # Use triples_by_subject
|
||||
def get_p(self, collection, p, limit=10) # Use triples_by_po
|
||||
def get_o(self, collection, o, limit=10) # Use triples_by_object
|
||||
def get_sp(self, collection, s, p, limit=10) # Use triples_by_subject
|
||||
def get_po(self, collection, p, o, limit=10) # Use triples_by_po (NO ALLOW FILTERING!)
|
||||
def get_os(self, collection, o, s, limit=10) # Use triples_by_subject
|
||||
def get_spo(self, collection, s, p, o, limit=10) # Use triples_by_subject
|
||||
|
||||
# Collection management
|
||||
def delete_collection(self, collection) -> None # Delete from all three tables
|
||||
```
|
||||
|
||||
#### Entegrasyon Dosyaları (Herhangi Bir Mantıksal Değişiklik Gerekmiyor)
|
||||
|
||||
**`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`**
|
||||
Herhangi bir değişiklik gerekmiyor - mevcut KnowledgeGraph API'sini kullanır.
|
||||
Performans iyileştirmelerinden otomatik olarak faydalanır.
|
||||
|
||||
**`trustgraph-flow/trustgraph/query/triples/cassandra/service.py`**
|
||||
Herhangi bir değişiklik gerekmiyor - mevcut KnowledgeGraph API'sini kullanır.
|
||||
Performans iyileştirmelerinden otomatik olarak faydalanır.
|
||||
|
||||
### Güncelleme Gerektiren Test Dosyaları
|
||||
|
||||
#### Birim Testleri
|
||||
**`tests/unit/test_storage/test_triples_cassandra_storage.py`**
|
||||
Şema değişiklikleri için test beklentilerini güncelleyin.
|
||||
Çok tablolu tutarlılık için testler ekleyin.
|
||||
Sorgu planlarında ALLOW FILTERING kullanımını doğrulayın.
|
||||
|
||||
**`tests/unit/test_query/test_triples_cassandra_query.py`**
|
||||
Performans doğrulama ifadelerini güncelleyin.
|
||||
Tüm 8 sorgu desenini yeni tablolara karşı test edin.
|
||||
Sorgu yönlendirmesinin doğru tablolara yapıldığını doğrulayın.
|
||||
|
||||
#### Entegrasyon Testleri
|
||||
**`tests/integration/test_cassandra_integration.py`**
|
||||
Yeni şemayla uçtan uca testler.
|
||||
Performans karşılaştırma ölçümleri.
|
||||
Tablolar arasındaki veri tutarlılığının doğrulanması.
|
||||
|
||||
**`tests/unit/test_storage/test_cassandra_config_integration.py`**
|
||||
Şema doğrulama testlerini güncelleyin.
|
||||
Geçiş senaryolarını test edin.
|
||||
|
||||
### Uygulama Stratejisi
|
||||
|
||||
#### 1. Aşama: Şema ve Temel Yöntemler
|
||||
1. **`init()` yöntemini yeniden yazın** - Dört tablo oluşturun, bir yerine.
|
||||
2. **`insert()` yöntemini yeniden yazın** - Tüm dört tabloya toplu yazma işlemleri.
|
||||
3. **Hazırlanmış ifadeleri uygulayın** - Optimum performans için.
|
||||
4. **Tablo yönlendirme mantığını ekleyin** - Sorguları en uygun tablolara yönlendirin.
|
||||
5. **Toplu silme işlemini uygulayın** - triples_collection'dan okuyun, tüm tablolardan toplu olarak silin.
|
||||
|
||||
#### 2. Aşama: Sorgu Yöntemi Optimizasyonu
|
||||
1. **Her get_* yöntemini yeniden yazın** - En uygun tabloyu kullanmak için.
|
||||
2. **Tüm ALLOW FILTERING kullanımını kaldırın**.
|
||||
3. **Verimli kümeleme anahtar kullanımı uygulayın**.
|
||||
4. **Sorgu performansını kaydetme özelliğini ekleyin**.
|
||||
|
||||
#### 3. Aşama: Koleksiyon Yönetimi
|
||||
1. **`delete_collection()`'ı güncelleyin** - Tüm üç tablodan kaldırın.
|
||||
2. **Tutarlılık doğrulamasını ekleyin** - Tüm tabloların senkronize kalmasını sağlayın.
|
||||
3. **Toplu işlemleri uygulayın** - Atomik çok tablolu işlemler için.
|
||||
|
||||
### Önemli Uygulama Detayları
|
||||
|
||||
#### Toplu Yazma Stratejisi
|
||||
```python
|
||||
def insert(self, collection, s, p, o):
|
||||
batch = BatchStatement()
|
||||
|
||||
# Insert into all four tables
|
||||
batch.add(self.insert_subject_stmt, (collection, s, p, o))
|
||||
batch.add(self.insert_po_stmt, (collection, p, o, s))
|
||||
batch.add(self.insert_object_stmt, (collection, o, s, p))
|
||||
batch.add(self.insert_collection_stmt, (collection, s, p, o))
|
||||
|
||||
self.session.execute(batch)
|
||||
```
|
||||
|
||||
#### Sorgu Yönlendirme Mantığı
|
||||
```python
|
||||
def get_po(self, collection, p, o, limit=10):
|
||||
# Route to triples_p table - NO ALLOW FILTERING!
|
||||
return self.session.execute(
|
||||
self.get_po_stmt,
|
||||
(collection, p, o, limit)
|
||||
)
|
||||
|
||||
def get_spo(self, collection, s, p, o, limit=10):
|
||||
# Route to triples_collection table for exact SPO lookup
|
||||
return self.session.execute(
|
||||
self.get_spo_stmt,
|
||||
(collection, s, p, o, limit)
|
||||
)
|
||||
```
|
||||
|
||||
#### Koleksiyon Silme Mantığı
|
||||
```python
|
||||
def delete_collection(self, collection):
|
||||
# Step 1: Read all triples from collection table
|
||||
rows = self.session.execute(
|
||||
f"SELECT s, p, o FROM {self.collection_table} WHERE collection = %s",
|
||||
(collection,)
|
||||
)
|
||||
|
||||
# Step 2: Batch delete from all 4 tables
|
||||
batch = BatchStatement()
|
||||
count = 0
|
||||
|
||||
for row in rows:
|
||||
s, p, o = row.s, row.p, row.o
|
||||
|
||||
# Delete using full partition keys for each table
|
||||
batch.add(SimpleStatement(
|
||||
f"DELETE FROM {self.subject_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
|
||||
), (collection, s, p, o))
|
||||
|
||||
batch.add(SimpleStatement(
|
||||
f"DELETE FROM {self.po_table} WHERE collection = ? AND p = ? AND o = ? AND s = ?"
|
||||
), (collection, p, o, s))
|
||||
|
||||
batch.add(SimpleStatement(
|
||||
f"DELETE FROM {self.object_table} WHERE collection = ? AND o = ? AND s = ? AND p = ?"
|
||||
), (collection, o, s, p))
|
||||
|
||||
batch.add(SimpleStatement(
|
||||
f"DELETE FROM {self.collection_table} WHERE collection = ? AND s = ? AND p = ? AND o = ?"
|
||||
), (collection, s, p, o))
|
||||
|
||||
count += 1
|
||||
|
||||
# Execute every 100 triples to avoid oversized batches
|
||||
if count % 100 == 0:
|
||||
self.session.execute(batch)
|
||||
batch = BatchStatement()
|
||||
|
||||
# Execute remaining deletions
|
||||
if count % 100 != 0:
|
||||
self.session.execute(batch)
|
||||
|
||||
logger.info(f"Deleted {count} triples from collection {collection}")
|
||||
```
|
||||
|
||||
#### Hazırlanmış İfade Optimizasyonu
|
||||
```python
|
||||
def prepare_statements(self):
|
||||
# Cache prepared statements for better performance
|
||||
self.insert_subject_stmt = self.session.prepare(
|
||||
f"INSERT INTO {self.subject_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
|
||||
)
|
||||
self.insert_po_stmt = self.session.prepare(
|
||||
f"INSERT INTO {self.po_table} (collection, p, o, s) VALUES (?, ?, ?, ?)"
|
||||
)
|
||||
self.insert_object_stmt = self.session.prepare(
|
||||
f"INSERT INTO {self.object_table} (collection, o, s, p) VALUES (?, ?, ?, ?)"
|
||||
)
|
||||
self.insert_collection_stmt = self.session.prepare(
|
||||
f"INSERT INTO {self.collection_table} (collection, s, p, o) VALUES (?, ?, ?, ?)"
|
||||
)
|
||||
# ... query statements
|
||||
```
|
||||
|
||||
## Göç Stratejisi
|
||||
|
||||
### Veri Göç Yaklaşımı
|
||||
|
||||
#### Seçenek 1: Mavi-Yeşil Dağıtım (Önerilen)
|
||||
1. **Yeni şemayı mevcut olanın yanında dağıtın** - Geçici olarak farklı tablo adları kullanın
|
||||
2. **Çift yazma dönemi** - Geçiş sırasında hem eski hem de yeni şemalara yazın
|
||||
3. **Arka planda veri taşıma** - Mevcut verileri yeni tablolara kopyalayın
|
||||
4. **Okuma yönlendirmesini değiştirin** - Veriler taşındıktan sonra sorguları yeni tablolara yönlendirin
|
||||
5. **Eski tabloları kaldırın** - Doğrulama süresinden sonra
|
||||
|
||||
#### Seçenek 2: Yerinde Göç
|
||||
1. **Şema ekleme** - Yeni tabloları mevcut anahtar uzayında oluşturun
|
||||
2. **Veri taşıma betiği** - Eski tablodan yeni tablolara toplu olarak veri kopyalayın
|
||||
3. **Uygulama güncellemesi** - Göç tamamlandıktan sonra yeni kodu dağıtın
|
||||
4. **Eski tablo temizliği** - Eski tabloyu ve indeksleri kaldırın
|
||||
|
||||
### Geriye Dönük Uyumluluk
|
||||
|
||||
#### Dağıtım Stratejisi
|
||||
```python
|
||||
# Environment variable to control table usage during migration
|
||||
USE_LEGACY_TABLES = os.getenv('CASSANDRA_USE_LEGACY', 'false').lower() == 'true'
|
||||
|
||||
class KnowledgeGraph:
|
||||
def __init__(self, ...):
|
||||
if USE_LEGACY_TABLES:
|
||||
self.init_legacy_schema()
|
||||
else:
|
||||
self.init_optimized_schema()
|
||||
```
|
||||
|
||||
#### Göç Script'i
|
||||
```python
|
||||
def migrate_data():
|
||||
# Read from old table
|
||||
old_triples = session.execute("SELECT collection, s, p, o FROM triples")
|
||||
|
||||
# Batch write to new tables
|
||||
for batch in batched(old_triples, 100):
|
||||
batch_stmt = BatchStatement()
|
||||
for row in batch:
|
||||
# Add to all three new tables
|
||||
batch_stmt.add(insert_subject_stmt, row)
|
||||
batch_stmt.add(insert_po_stmt, (row.collection, row.p, row.o, row.s))
|
||||
batch_stmt.add(insert_object_stmt, (row.collection, row.o, row.s, row.p))
|
||||
session.execute(batch_stmt)
|
||||
```
|
||||
|
||||
### Doğrulama Stratejisi
|
||||
|
||||
#### Veri Tutarlılık Kontrolleri
|
||||
```python
|
||||
def validate_migration():
|
||||
# Count total records in old vs new tables
|
||||
old_count = session.execute("SELECT COUNT(*) FROM triples WHERE collection = ?", (collection,))
|
||||
new_count = session.execute("SELECT COUNT(*) FROM triples_by_subject WHERE collection = ?", (collection,))
|
||||
|
||||
assert old_count == new_count, f"Record count mismatch: {old_count} vs {new_count}"
|
||||
|
||||
# Spot check random samples
|
||||
sample_queries = generate_test_queries()
|
||||
for query in sample_queries:
|
||||
old_result = execute_legacy_query(query)
|
||||
new_result = execute_optimized_query(query)
|
||||
assert old_result == new_result, f"Query results differ for {query}"
|
||||
```
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
### Performans Testi
|
||||
|
||||
#### Benchmark Senaryoları
|
||||
1. **Sorgu Performansı Karşılaştırması**
|
||||
Tüm 8 sorgu türü için performans metrikleri (önce/sonra)
|
||||
get_po performans iyileştirmesine odaklanın (ALLOW FILTERING'i kaldırın)
|
||||
Çeşitli veri boyutları altında sorgu gecikmesini ölçün
|
||||
|
||||
2. **Yük Testi**
|
||||
Eşzamanlı sorgu yürütme
|
||||
Toplu işlemlerle yazma hızı
|
||||
Bellek ve CPU kullanımı
|
||||
|
||||
3. **Ölçeklenebilirlik Testi**
|
||||
Artan koleksiyon boyutlarıyla performans
|
||||
Çoklu koleksiyon sorgu dağıtımı
|
||||
Küme düğümü kullanımı
|
||||
|
||||
#### Test Veri Kümeleri
|
||||
**Küçük:** Koleksiyon başına 10K üçlü
|
||||
**Orta:** Koleksiyon başına 100K üçlü
|
||||
**Büyük:** Koleksiyon başına 1M+ üçlü
|
||||
**Çoklu koleksiyonlar:** Test bölüm dağıtımı
|
||||
|
||||
### Fonksiyonel Test
|
||||
|
||||
#### Birim Testi Güncellemeleri
|
||||
```python
|
||||
# Example test structure for new implementation
|
||||
class TestCassandraKGPerformance:
|
||||
def test_get_po_no_allow_filtering(self):
|
||||
# Verify get_po queries don't use ALLOW FILTERING
|
||||
with patch('cassandra.cluster.Session.execute') as mock_execute:
|
||||
kg.get_po('test_collection', 'predicate', 'object')
|
||||
executed_query = mock_execute.call_args[0][0]
|
||||
assert 'ALLOW FILTERING' not in executed_query
|
||||
|
||||
def test_multi_table_consistency(self):
|
||||
# Verify all tables stay in sync
|
||||
kg.insert('test', 's1', 'p1', 'o1')
|
||||
|
||||
# Check all tables contain the triple
|
||||
assert_triple_exists('triples_by_subject', 'test', 's1', 'p1', 'o1')
|
||||
assert_triple_exists('triples_by_po', 'test', 'p1', 'o1', 's1')
|
||||
assert_triple_exists('triples_by_object', 'test', 'o1', 's1', 'p1')
|
||||
```
|
||||
|
||||
#### Entegrasyon Testi Güncellemeleri
|
||||
```python
|
||||
class TestCassandraIntegration:
|
||||
def test_query_performance_regression(self):
|
||||
# Ensure new implementation is faster than old
|
||||
old_time = benchmark_legacy_get_po()
|
||||
new_time = benchmark_optimized_get_po()
|
||||
assert new_time < old_time * 0.5 # At least 50% improvement
|
||||
|
||||
def test_end_to_end_workflow(self):
|
||||
# Test complete write -> query -> delete cycle
|
||||
# Verify no performance degradation in integration
|
||||
```
|
||||
|
||||
### Geri Alma Planı
|
||||
|
||||
#### Hızlı Geri Alma Stratejisi
|
||||
1. **Ortam değişkeni geçişi** - Eski tablolara hemen geri dönün.
|
||||
2. **Eski tablolara devam edin** - Performans kanıtlanana kadar silmeyin.
|
||||
3. **İzleme uyarıları** - Hata oranlarına/gecikmelere göre otomatik geri alma tetikleyicileri.
|
||||
|
||||
#### Geri Alma Doğrulama
|
||||
```python
|
||||
def rollback_to_legacy():
|
||||
# Set environment variable
|
||||
os.environ['CASSANDRA_USE_LEGACY'] = 'true'
|
||||
|
||||
# Restart services to pick up change
|
||||
restart_cassandra_services()
|
||||
|
||||
# Validate functionality
|
||||
run_smoke_tests()
|
||||
```
|
||||
|
||||
## Riskler ve Dikkat Edilmesi Gerekenler
|
||||
|
||||
### Performans Riskleri
|
||||
**Yazma gecikmesi artışı** - Her eklemeye 4 yazma işlemi (3 tablolu yaklaşıma göre %33 daha fazla)
|
||||
**Depolama alanı kullanımı** - 4 kat daha fazla depolama alanı gereksinimi (3 tablolu yaklaşıma göre %33 daha fazla)
|
||||
**Toplu yazma hataları** - Uygun hata yönetimi gereklidir
|
||||
**Silme karmaşıklığı** - Koleksiyon silme işlemi, okuma-sonra-silme döngüsü gerektirir
|
||||
|
||||
### İşletim Riskleri
|
||||
**Geçiş karmaşıklığı** - Büyük veri kümeleri için veri geçişi
|
||||
**Tutarlılık sorunları** - Tüm tabloların senkronize olduğundan emin olmak
|
||||
**İzleme eksiklikleri** - Çok tablolu işlemler için yeni metrikler gereklidir
|
||||
|
||||
### Azaltma Stratejileri
|
||||
1. **Aşamalı dağıtım** - Küçük koleksiyonlarla başlayın
|
||||
2. **Kapsamlı izleme** - Tüm performans metriklerini takip edin
|
||||
3. **Otomatik doğrulama** - Sürekli tutarlılık kontrolü
|
||||
4. **Hızlı geri alma yeteneği** - Ortam tabanlı tablo seçimi
|
||||
|
||||
## Başarı Kriterleri
|
||||
|
||||
### Performans İyileştirmeleri
|
||||
[ ] **ALLOW FILTERING'i ortadan kaldırın** - get_po ve get_os sorguları filtreleme olmadan çalışır
|
||||
[ ] **Sorgu gecikmesi azaltma** - Sorgu yanıt sürelerinde %50 veya daha fazla iyileşme
|
||||
[ ] **Daha iyi yük dağılımı** - Hiçbir "sıcak" bölüm yok, küme düğümleri arasında eşit yük dağılımı
|
||||
[ ] **Ölçeklenebilir performans** - Sorgu süresi, toplam veri miktarı yerine sonuç büyüklüğüne orantılı
|
||||
|
||||
### Fonksiyonel Gereksinimler
|
||||
[ ] **API uyumluluğu** - Tüm mevcut kod, herhangi bir değişiklik olmadan çalışmaya devam eder
|
||||
[ ] **Veri tutarlılığı** - Tüm üç tablo senkronize kalır
|
||||
[ ] **Sıfır veri kaybı** - Geçiş, tüm mevcut üçlüleri korur
|
||||
[ ] **Geriye dönme uyumluluğu** - Eski şemaya geri dönme yeteneği
|
||||
|
||||
### İşletim Gereksinimleri
|
||||
[ ] **Güvenli geçiş** - Geri alma yeteneği olan mavi-yeşil dağıtım
|
||||
[ ] **İzleme kapsamı** - Çok tablolu işlemler için kapsamlı metrikler
|
||||
[ ] **Test kapsamı** - Tüm sorgu kalıpları, performans kıyaslamalarıyla test edilmiştir
|
||||
[ ] **Belgeleme** - Güncellenmiş dağıtım ve işletim prosedürleri
|
||||
|
||||
## Zaman Çizelgesi
|
||||
|
||||
### 1. Aşama: Uygulama
|
||||
[ ] `cassandra_kg.py`'ı çok tablolu şemayla yeniden yazın
|
||||
[ ] Toplu yazma işlemlerini uygulayın
|
||||
[ ] Hazırlanmış ifade optimizasyonunu ekleyin
|
||||
[ ] Birim testlerini güncelleyin
|
||||
|
||||
### 2. Aşama: Entegrasyon Testi
|
||||
[ ] Entegrasyon testlerini güncelleyin
|
||||
[ ] Performans kıyaslaması
|
||||
[ ] Gerçekçi veri hacimleriyle yük testi
|
||||
[ ] Veri tutarlılığı için doğrulama betikleri
|
||||
|
||||
### 3. Aşama: Geçiş Planlaması
|
||||
[ ] Mavi-yeşil dağıtım betikleri
|
||||
[ ] Veri geçiş araçları
|
||||
[ ] İzleme panosu güncellemeleri
|
||||
[ ] Geri alma prosedürleri
|
||||
|
||||
### 4. Aşama: Üretim Dağıtımı
|
||||
[ ] Üretime aşamalı dağıtım
|
||||
[ ] Performans izleme ve doğrulama
|
||||
[ ] Eski tabloların temizlenmesi
|
||||
[ ] Belgeleme güncellemeleri
|
||||
|
||||
## Sonuç
|
||||
|
||||
Bu çok tablolu normalleştirme stratejisi, doğrudan iki kritik performans darboğazını ele almaktadır:
|
||||
|
||||
1. **Pahalı ALLOW FILTERING'i ortadan kaldırır** ve her sorgu kalıbı için optimum tablo yapıları sağlar.
|
||||
2. **Kompozit bölüm anahtarları aracılığıyla kümeleme etkinliğini artırır** ve yükü düzgün bir şekilde dağıtır.
|
||||
|
||||
Bu yaklaşım, Cassandra'nın güçlü yönlerinden yararlanırken, mevcut kodun performans iyileştirmelerinden otomatik olarak yararlanmasını sağlayan tam API uyumluluğunu korur.
|
||||
410
docs/tech-specs/tr/collection-management.tr.md
Normal file
410
docs/tech-specs/tr/collection-management.tr.md
Normal file
|
|
@ -0,0 +1,410 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Koleksiyon Yönetimi Teknik Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Koleksiyon Yönetimi 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çin koleksiyon yönetimi yeteneklerini tanımlar ve açık koleksiyon oluşturulmasını gerektirir ve koleksiyon yaşam döngüsü üzerinde doğrudan kontrol sağlar. Koleksiyonlar, uygun veri ambarı ve tüm depolama arka uçları arasındaki senkronizasyonu sağlamak için kullanmadan önce açıkça oluşturulmalıdır. Bu özellik, dört birincil kullanım senaryosunu destekler:
|
||||
|
||||
1. **Koleksiyon Oluşturma**: Veri depolamadan önce koleksiyonları açıkça oluşturun
|
||||
2. **Koleksiyon Listeleme**: Sistemdeki mevcut tüm koleksiyonları görüntüleyin
|
||||
3. **Koleksiyon Meta Veri Yönetimi**: Koleksiyon adlarını, açıklamalarını ve etiketlerini güncelleyin
|
||||
4. **Koleksiyon Silme**: Koleksiyonları ve bunlara bağlı verileri tüm depolama türlerinden kaldırın
|
||||
|
||||
## Hedefler
|
||||
|
||||
**Açık Koleksiyon Oluşturma**: Verilerin depolanabilmesi için koleksiyonların oluşturulmasını gerektirir
|
||||
**Depolama Senkronizasyonu**: Koleksiyonların tüm depolama arka uçlarında (vektörler, nesneler, üçlüler) mevcut olduğundan emin olun
|
||||
**Koleksiyon Görünürlüğü**: Kullanıcıların ortamlarındaki tüm koleksiyonları listelemesini ve incelemesini sağlayın
|
||||
**Koleksiyon Temizleme**: Artık gerekli olmayan koleksiyonların silinmesine izin verin
|
||||
**Koleksiyon Organizasyonu**: Daha iyi koleksiyon takibi ve keşfi için etiketleri ve kategorileri destekleyin
|
||||
**Meta Veri Yönetimi**: İşletimsel açıklık için koleksiyonlarla anlamlı meta verileri ilişkilendirin
|
||||
**Koleksiyon Keşfi**: Filtreleme ve arama yoluyla belirli koleksiyonları bulmayı kolaylaştırın
|
||||
**İşletim Şeffaflığı**: Koleksiyon yaşam döngüsü ve kullanımı hakkında net görünürlük sağlayın
|
||||
**Kaynak Yönetimi**: Kullanılmayan koleksiyonları temizleyerek kaynak kullanımını optimize etmeyi sağlayın
|
||||
**Veri Bütünlüğü**: Meta veri takibi olmadan depolamada yetim koleksiyonların oluşmasını önleyin
|
||||
|
||||
## Arka Plan
|
||||
|
||||
Geçmişte, TrustGraph'taki koleksiyonlar, veri yükleme işlemleri sırasında örtülü olarak oluşturuluyordu ve bu da koleksiyonların depolama arka uçlarında, ancak kütüphanecide ilgili meta verilere sahip olmadan var olabileceği senkronizasyon sorunlarına yol açıyordu. Bu durum, yönetim zorlukları ve potansiyel olarak yetim veri sorunları yaratmıştır.
|
||||
|
||||
Açık koleksiyon oluşturma modeli, bu sorunları aşağıdaki şekilde ele alır:
|
||||
Koleksiyonların `tg-set-collection` aracılığıyla kullanmadan önce oluşturulmasını gerektirir
|
||||
Koleksiyon oluşturmayı tüm depolama arka uçlarına yayınlar
|
||||
Kütüphaneci meta verileri ile depolama arasındaki senkronize durumu korur
|
||||
Var olmayan koleksiyonlara yazmayı engeller
|
||||
Açık koleksiyon yaşam döngüsü yönetimi sağlar
|
||||
|
||||
Bu özellik, açık koleksiyon yönetimi modelini tanımlar. Açık koleksiyon oluşturmayı gerektirerek, TrustGraph şunları sağlar:
|
||||
Koleksiyonlar, oluşturulmadan itibaren kütüphaneci meta verilerinde takip edilir
|
||||
Tüm depolama arka uçları, verileri almadan önce koleksiyonların varlığından haberdardır
|
||||
Depolamada yetim koleksiyonların oluşması engellenir
|
||||
Koleksiyon yaşam döngüsü üzerinde açık işletimsel görünürlük ve kontrol sağlanır
|
||||
Var olmayan koleksiyonlara yapılan işlemlerde tutarlı hata işleme sağlanır
|
||||
|
||||
## Teknik Tasarım
|
||||
|
||||
### Mimari
|
||||
|
||||
Koleksiyon yönetimi sistemi, mevcut TrustGraph altyapısının içinde uygulanacaktır:
|
||||
|
||||
1. **Kütüphaneci Hizmeti Entegrasyonu**
|
||||
Koleksiyon yönetimi işlemleri, mevcut kütüphaneci hizmetine eklenecektir
|
||||
Yeni bir hizmet gerektirmez - mevcut kimlik doğrulama ve erişim kalıplarından yararlanır
|
||||
Koleksiyon listeleme, silme ve meta veri yönetimi işlemlerini işler
|
||||
|
||||
Modül: trustgraph-librarian
|
||||
|
||||
2. **Cassandra Koleksiyon Meta Veri Tablosu**
|
||||
Mevcut kütüphaneci anahtar alanındaki yeni bir tablo
|
||||
Kullanıcı kapsamlı erişim ile koleksiyon meta verilerini depolar
|
||||
Birincil anahtar: Doğru çoklu kiracılık için (user_id, collection_id)
|
||||
|
||||
Modül: trustgraph-librarian
|
||||
|
||||
3. **Koleksiyon Yönetimi CLI**
|
||||
Koleksiyon işlemleri için komut satırı arayüzü
|
||||
Listeleme, silme, etiketleme ve etiket yönetimi komutları sağlar
|
||||
Mevcut CLI çerçevesiyle entegre olur
|
||||
|
||||
Modül: trustgraph-cli
|
||||
|
||||
### Veri Modelleri
|
||||
|
||||
#### Cassandra Koleksiyon Meta Veri Tablosu
|
||||
|
||||
Koleksiyon meta verileri, kütüphaneci anahtar alanındaki yapılandırılmış bir Cassandra tablosunda saklanacaktır:
|
||||
|
||||
```sql
|
||||
CREATE TABLE collections (
|
||||
user text,
|
||||
collection text,
|
||||
name text,
|
||||
description text,
|
||||
tags set<text>,
|
||||
created_at timestamp,
|
||||
updated_at timestamp,
|
||||
PRIMARY KEY (user, collection)
|
||||
);
|
||||
```
|
||||
|
||||
Tablo yapısı:
|
||||
**user**: **collection**: Birincil bileşik anahtar, kullanıcı yalıtımını sağlar
|
||||
**name**: İnsan tarafından okunabilir koleksiyon adı
|
||||
**description**: Koleksiyonun amacının ayrıntılı açıklaması
|
||||
**tags**: Kategorizasyon ve filtreleme için etiket kümesi
|
||||
**created_at**: Koleksiyon oluşturma zaman damgası
|
||||
**updated_at**: Son değişiklik zaman damgası
|
||||
|
||||
Bu yaklaşım şunları sağlar:
|
||||
Kullanıcı yalıtımı ile çoklu kiracılı koleksiyon yönetimi
|
||||
Kullanıcı ve koleksiyon bazında verimli sorgulama
|
||||
Düzenleme için esnek etiketleme sistemi
|
||||
İşletimsel bilgiler için yaşam döngüsü takibi
|
||||
|
||||
#### Koleksiyon Yaşam Döngüsü
|
||||
|
||||
Koleksiyonlar, veri işlemlerine başlamadan önce kütüphanede açıkça oluşturulmalıdır:
|
||||
|
||||
1. **Koleksiyon Oluşturma** (İki Yol):
|
||||
|
||||
**Yol A: Kullanıcı Tarafından Başlatılan Oluşturma** `tg-set-collection` aracılığıyla:
|
||||
Kullanıcı, koleksiyon kimliği, adı, açıklaması ve etiketleri sağlar
|
||||
Kütüphane, `collections` tablosunda bir meta veri kaydı oluşturur
|
||||
Kütüphane, tüm depolama arka uçlarına "create-collection" mesajını gönderir
|
||||
Tüm depolama işlemcileri, koleksiyonu oluşturur ve başarıyı onaylar
|
||||
Koleksiyon artık veri işlemleri için hazırdır
|
||||
|
||||
**Yol B: Belge Gönderimi Üzerinde Otomatik Oluşturma**:
|
||||
Kullanıcı, bir koleksiyon kimliği belirten bir belge gönderir
|
||||
Kütüphane, koleksiyonun meta veri tablosunda mevcut olup olmadığını kontrol eder
|
||||
Yoksa: Kütüphane, varsayılanlarla (ad=koleksiyon_kimliği, boş açıklama/etiketler) bir meta veri oluşturur
|
||||
Kütüphane, tüm depolama arka uçlarına "create-collection" mesajını gönderir
|
||||
Tüm depolama işlemcileri, koleksiyonu oluşturur ve başarıyı onaylar
|
||||
Belge işleme, koleksiyonun artık oluşturulduğu şekilde devam eder
|
||||
|
||||
Her iki yol da, veri işlemlerine izin verilmeden önce koleksiyonun kütüphane meta verilerinde VE tüm depolama arka uçlarında mevcut olmasını sağlar.
|
||||
|
||||
2. **Depolama Doğrulama**: Yazma işlemleri, koleksiyonun mevcut olup olmadığını doğrular:
|
||||
Depolama işlemcileri, yazmayı kabul etmeden önce koleksiyonun durumunu kontrol eder
|
||||
Mevcut olmayan koleksiyonlara yapılan yazılar hata döndürür
|
||||
Bu, doğrudan yazmaların kütüphanenin koleksiyon oluşturma mantığını atlamasını engeller
|
||||
|
||||
3. **Sorgu Davranışı**: Sorgu işlemleri, mevcut olmayan koleksiyonları zarif bir şekilde işler:
|
||||
Mevcut olmayan koleksiyonlara yapılan sorgular boş sonuçlar döndürür
|
||||
Sorgu işlemleri için hata oluşmaz
|
||||
Koleksiyonun mevcut olması gerekmeksizin keşfetmeye olanak tanır
|
||||
|
||||
4. **Meta Veri Güncellemeleri**: Kullanıcılar, koleksiyon oluşturulduktan sonra koleksiyon meta verilerini güncelleyebilir:
|
||||
Adı, açıklamasını ve etiketleri `tg-set-collection` aracılığıyla güncelleyin
|
||||
Güncellemeler yalnızca kütüphane meta verilerine uygulanır
|
||||
Depolama arka uçları koleksiyonu korur, ancak meta veri güncellemeleri yayılmaz
|
||||
|
||||
5. **Açık Silme**: Kullanıcılar, koleksiyonları `tg-delete-collection` aracılığıyla siler:
|
||||
Kütüphane, tüm depolama arka uçlarına "delete-collection" mesajını gönderir
|
||||
Tüm depolama işlemcilerinden onay bekler
|
||||
Depolama temizliği tamamlandıktan SONRA yalnızca kütüphane meta veri kaydını siler
|
||||
Depoda hiçbir verinin kaybolmamasını sağlar
|
||||
|
||||
**Temel İlke**: Kütüphane, koleksiyon oluşturma için tek kontrol noktasıdır. Kullanıcı komutu veya belge gönderimi ile başlatılıp başlatılmadığına bakılmaksızın, kütüphane, veri işlemlerine izin vermeden önce uygun meta veri takibi ve depolama arka uç senkronizasyonunu sağlar.
|
||||
|
||||
Gerekli işlemler:
|
||||
**Koleksiyon Oluşturma**: `tg-set-collection` aracılığıyla kullanıcı işlemi VEYA belge gönderimi üzerine otomatik
|
||||
**Koleksiyon Meta Verilerini Güncelleme**: Adı, açıklaması ve etiketleri değiştirmek için kullanıcı işlemi
|
||||
**Koleksiyonu Silme**: Koleksiyonu ve tüm depolarda verilerini kaldırmak için kullanıcı işlemi
|
||||
**Koleksiyonları Listeleme**: Etiketlere göre filtreleme ile koleksiyonları görüntülemek için kullanıcı işlemi
|
||||
|
||||
#### Çoklu Depo Koleksiyon Yönetimi
|
||||
|
||||
Koleksiyonlar, TrustGraph'ta birden çok depolama arka uçunda bulunur:
|
||||
**Vektör Depoları** (Qdrant, Milvus, Pinecone): Gömme ve vektör verilerini depolar
|
||||
**Nesne Depoları** (Cassandra): Belge ve dosya verilerini depolar
|
||||
**Üçlü Depolar** (Cassandra, Neo4j, Memgraph, FalkorDB): Grafik/RDF verilerini depolar
|
||||
|
||||
Her bir mağaza türü aşağıdaki işlemleri uygular:
|
||||
**Koleksiyon Durumu Takibi**: Hangi koleksiyonların mevcut olduğunu takip etme
|
||||
**Koleksiyon Oluşturma**: "koleksiyon oluştur" işlemlerini kabul etme ve işleme alma
|
||||
**Koleksiyon Doğrulama**: Yazma işlemlerini kabul etmeden önce koleksiyonun varlığını kontrol etme
|
||||
**Koleksiyon Silme**: Belirtilen koleksiyon için tüm verileri silme
|
||||
|
||||
Kütüphaneci hizmeti, tüm mağaza türleri arasında koleksiyon işlemlerini koordine ederek şunları sağlar:
|
||||
Koleksiyonlar, kullanmadan önce tüm arka uçlarda oluşturulur
|
||||
Tüm arka uçlar, oluşturma işleminden sonra başarıyı doğrular
|
||||
Depolama türleri arasında senkronize koleksiyon yaşam döngüsü
|
||||
Koleksiyonlar mevcut olmadığında tutarlı hata işleme
|
||||
|
||||
#### Depolama Türüne Göre Koleksiyon Durumu Takibi
|
||||
|
||||
Her depolama arka ucu, yeteneklerine bağlı olarak koleksiyon durumunu farklı şekilde takip eder:
|
||||
|
||||
**Cassandra Üçlü Deposu:**
|
||||
Mevcut `triples_collection` tablosunu kullanır
|
||||
Koleksiyon oluşturulduğunda sistem işaretleyici üçlüsü oluşturur
|
||||
Sorgu: `SELECT collection FROM triples_collection WHERE collection = ? LIMIT 1`
|
||||
Koleksiyonun varlığı için verimli tek bölüm kontrolü
|
||||
|
||||
**Qdrant/Milvus/Pinecone Vektör Depoları:**
|
||||
Yerel koleksiyon API'leri, varlık kontrolü sağlar
|
||||
Koleksiyonlar, uygun vektör yapılandırmasıyla oluşturulur
|
||||
`collection_exists()` yöntemi, depolama API'sini kullanır
|
||||
Koleksiyon oluşturma, boyut gereksinimlerini doğrular
|
||||
|
||||
**Neo4j/Memgraph/FalkorDB Grafik Depoları:**
|
||||
Koleksiyonları takip etmek için `:CollectionMetadata` düğümlerini kullanır
|
||||
Düğüm özellikleri: `{user, collection, created_at}`
|
||||
Sorgu: `MATCH (c:CollectionMetadata {user: $user, collection: $collection})`
|
||||
Veri düğümlerinden ayrı olarak, temiz bir ayrım sağlar
|
||||
Koleksiyon listeleme ve doğrulama için verimli bir yol sağlar
|
||||
|
||||
**Cassandra Nesne Deposu:**
|
||||
Koleksiyon meta veri tablosunu veya işaretçi satırlarını kullanır
|
||||
Üçlü depoya benzer bir desen
|
||||
Veri yazmadan önce koleksiyonu doğrular
|
||||
|
||||
### API'ler
|
||||
|
||||
Koleksiyon Yönetimi API'leri (Kütüphaneci):
|
||||
**Koleksiyon Oluşturma/Güncelleme**: Yeni bir koleksiyon oluşturma veya mevcut meta verileri `tg-set-collection` aracılığıyla güncelleme
|
||||
**Koleksiyonları Listeleme**: İsteğe bağlı etiket filtrelemesiyle bir kullanıcı için koleksiyonları alma
|
||||
**Koleksiyon Silme**: Koleksiyonu ve ilişkili verileri silme, tüm mağaza türlerine kadar yayılma
|
||||
|
||||
Depolama Yönetimi API'leri (Tüm Depolama İşlemcileri):
|
||||
**Koleksiyon Oluşturma**: "koleksiyon oluştur" işlemini işleme, depolamada koleksiyonu oluşturma
|
||||
**Koleksiyon Silme**: "koleksiyon sil" işlemini işleme, tüm koleksiyon verilerini silme
|
||||
**Koleksiyon Varlığı Kontrolü**: Yazma işlemlerini kabul etmeden önce iç doğrulama
|
||||
|
||||
Veri İşlemleri API'leri (Değiştirilmiş Davranış):
|
||||
**Yazma API'leri**: Veriyi kabul etmeden önce koleksiyonun varlığını doğrulama, mevcut değilse hata döndürme
|
||||
**Sorgu API'leri**: Hata olmadan mevcut olmayan koleksiyonlar için boş sonuçlar döndürme
|
||||
|
||||
### Uygulama Ayrıntıları
|
||||
|
||||
Uygulama, hizmet entegrasyonu ve CLI komut yapısı için mevcut TrustGraph desenlerini takip edecektir.
|
||||
|
||||
#### Koleksiyon Silme Yayılımı
|
||||
|
||||
Bir kullanıcı, kütüphaneci hizmeti aracılığıyla koleksiyon silme işlemini başlattığında:
|
||||
|
||||
1. **Meta Veri Doğrulama**: Koleksiyonun var olduğunu ve kullanıcının silme izni olup olmadığını doğrulayın
|
||||
2. **Depolama Yayılımı**: Kütüphaneci, tüm depolama yazıcıları arasında silme işlemini koordine eder:
|
||||
Vektör depolama yazıcısı: Kullanıcı ve koleksiyon için gömülmeleri ve vektör indekslerini kaldırır
|
||||
Nesne depolama yazıcısı: Kullanıcı ve koleksiyon için belgeleri ve dosyaları kaldırır
|
||||
Üçlü depolama yazıcısı: Kullanıcı ve koleksiyon için grafik verilerini ve üçlüleri kaldırır
|
||||
3. **Meta Veri Temizleme**: Cassandra'dan koleksiyon meta veri kaydını kaldırır
|
||||
4. **Hata İşleme**: Herhangi bir depolama silme işlemi başarısız olursa, geri alma veya yeniden deneme mekanizmaları aracılığıyla tutarlılığı koruyun
|
||||
|
||||
#### Koleksiyon Yönetimi Arayüzü
|
||||
|
||||
**⚠️ ESKİ YAKLAŞIM - YAPILANDIRMA TEMELLİ DESENE DEĞİŞTİRİLDİ**
|
||||
|
||||
Aşağıda açıklanan kuyruk tabanlı mimari, `CollectionConfigHandler` kullanarak bir yapılandırma tabanlı yaklaşımla değiştirilmiştir. Tüm depolama arka uçları artık özel yönetim kuyrukları yerine yapılandırma itme mesajları aracılığıyla koleksiyon güncellemeleri alır.
|
||||
|
||||
~~Tüm depolama yazıcıları, ortak bir şemaya sahip standart bir koleksiyon yönetimi arayüzü uygular:~~
|
||||
|
||||
~~**Mesaj Şeması (`StorageManagementRequest`):**~~
|
||||
```json
|
||||
{
|
||||
"operation": "create-collection" | "delete-collection",
|
||||
"user": "user123",
|
||||
"collection": "documents-2024"
|
||||
}
|
||||
```
|
||||
|
||||
~~**Sıra Mimarisi:**~~
|
||||
~~**Vektör Depolama Yönetimi Kuyruğu** (`vector-storage-management`): Vektör/gömme depoları~~
|
||||
~~**Nesne Depolama Yönetimi Kuyruğu** (`object-storage-management`): Nesne/belge depoları~~
|
||||
~~**Üçlü Depolama Yönetimi Kuyruğu** (`triples-storage-management`): Grafik/RDF depoları~~
|
||||
~~**Depolama Yanıt Kuyruğu** (`storage-management-response`): Tüm yanıtlar buraya gönderilir~~
|
||||
|
||||
**Mevcut Uygulama:**
|
||||
|
||||
Tüm depolama arka uçları artık `CollectionConfigHandler` kullanır:
|
||||
**Yapılandırma İtme Entegrasyonu**: Depolama hizmetleri, yapılandırma itme bildirimleri için kayıt yaptırır
|
||||
**Otomatik Senkronizasyon**: Koleksiyonlar, yapılandırma değişikliklerine göre oluşturulur/silinir
|
||||
**Bildirimsel Model**: Koleksiyonlar, yapılandırma hizmetinde tanımlanır, arka uçlar eşleşmesi için senkronize olur
|
||||
**İstek/Yanıt Yok**: Koordinasyon yükünü ve yanıt takibini ortadan kaldırır
|
||||
**Koleksiyon Durumu Takibi**: `known_collections` önbelleği aracılığıyla sürdürülür
|
||||
**İdeolojik İşlemler**: Aynı yapılandırmayı birden çok kez işlemek güvenlidir
|
||||
|
||||
Her depolama arka ucu şunları uygular:
|
||||
`create_collection(user: str, collection: str, metadata: dict)` - Koleksiyon yapılarını oluşturur
|
||||
`delete_collection(user: str, collection: str)` - Tüm koleksiyon verilerini kaldırır
|
||||
`collection_exists(user: str, collection: str) -> bool` - Yazmadan önce doğrular
|
||||
|
||||
#### Cassandra Üçlü Depolama Yeniden Düzenlemesi
|
||||
|
||||
Bu uygulamanın bir parçası olarak, Cassandra üçlü depolama, bir koleksiyon başına tablo modelinden tek bir tablo modeline yeniden düzenlenecektir:
|
||||
|
||||
**Mevcut Mimari:**
|
||||
Kullanıcı başına bir anahtar alanı, her koleksiyon için ayrı bir tablo
|
||||
Şema: `(s, p, o)` ile `PRIMARY KEY (s, p, o)`
|
||||
Tablo adları: Kullanıcı koleksiyonları, ayrı Cassandra tabloları haline gelir
|
||||
|
||||
**Yeni Mimari:**
|
||||
Kullanıcı başına bir anahtar alanı, tüm koleksiyonlar için tek bir "üçlüler" tablosu
|
||||
Şema: `(collection, s, p, o)` ile `PRIMARY KEY (collection, s, p, o)`
|
||||
Koleksiyon izolasyonu, koleksiyon bölümlendirmesi yoluyla sağlanır
|
||||
|
||||
**Gerekli Değişiklikler:**
|
||||
|
||||
1. **TrustGraph Sınıfı Yeniden Düzenlemesi** (`trustgraph/direct/cassandra.py`):
|
||||
Oluşturucudan `table` parametresini kaldırın, sabit "üçlüler" tablosunu kullanın
|
||||
Tüm yöntemlere `collection` parametresini ekleyin
|
||||
Koleksiyonu ilk sütun olarak içeren şemayı güncelleyin
|
||||
**Dizin Güncellemeleri**: Tüm 8 sorgu desenini desteklemek için yeni dizinler oluşturulacaktır:
|
||||
`(s)` üzerine dizin, konu tabanlı sorgular için
|
||||
`(p)` üzerine dizin, öznelik tabanlı sorgular için
|
||||
`(o)` üzerine dizin, nesne tabanlı sorgular için
|
||||
Not: Cassandra, çok sütunlu ikincil dizinleri desteklemez, bu nedenle bunlar tek sütunlu dizinlerdir
|
||||
|
||||
**Sorgu Deseni Performansı:**
|
||||
✅ `get_all()` - `collection` üzerinde bölüm taraması
|
||||
✅ `get_s(s)` - birincil anahtarı verimli kullanır (`collection, s`)
|
||||
✅ `get_p(p)` - `idx_p` ile `collection` filtrelemesini kullanır
|
||||
✅ `get_o(o)` - `idx_o` ile `collection` filtrelemesini kullanır
|
||||
✅ `get_sp(s, p)` - birincil anahtarı verimli kullanır (`collection, s, p`)
|
||||
⚠️ `get_po(p, o)` - `ALLOW FILTERING` gerektirir (ya `idx_p` veya `idx_o` artı filtreleme kullanır)
|
||||
✅ `get_os(o, s)` - `idx_o` ile ek filtreleme `s` üzerinde kullanır
|
||||
✅ `get_spo(s, p, o)` - tüm birincil anahtarı verimli kullanır
|
||||
|
||||
**ALLOW FILTERING Notu:** `get_po` sorgu deseni, uygun bir birleşik dizin olmadan hem öznitelik hem de nesne kısıtlamalarına ihtiyaç duyduğu için `ALLOW FILTERING` gerektirir. Bu kabul edilebilir çünkü bu sorgu deseni, tipik üçlü depolama kullanımında konu tabanlı sorgulara göre daha az yaygındır
|
||||
|
||||
2. **Depolama Yazarı Güncellemeleri** (`trustgraph/storage/triples/cassandra/write.py`):
|
||||
(kullanıcı, koleksiyon) başına bir bağlantı yerine, kullanıcı başına tek bir TrustGraph bağlantısı sürdürün
|
||||
Ekleme işlemlerine koleksiyonu iletin
|
||||
Daha az bağlantıyla daha verimli kaynak kullanımı
|
||||
|
||||
3. **Sorgu Hizmeti Güncellemeleri** (`trustgraph/query/triples/cassandra/service.py`):
|
||||
Kullanıcı başına tek bir TrustGraph bağlantısı
|
||||
Tüm sorgu işlemlerine koleksiyonu iletin
|
||||
Koleksiyon parametresiyle aynı sorgu mantığını koruyun
|
||||
|
||||
**Faydaları:**
|
||||
**Basitleştirilmiş Koleksiyon Silme:** Tüm 4 tablo üzerinde `collection` bölüm anahtarını kullanarak silme
|
||||
**Kaynak Verimliliği:** Daha az veritabanı bağlantısı ve tablo nesnesi
|
||||
**Çoklu Koleksiyon İşlemleri:** Birden çok koleksiyonu kapsayan işlemleri uygulamak daha kolaydır
|
||||
**Tutarlı Mimari:** Birleşik koleksiyon meta veri yaklaşımıyla uyumludur
|
||||
**Koleksiyon Doğrulama:** `triples_collection` tablosu aracılığıyla koleksiyonun varlığını kontrol etmek kolaydır
|
||||
|
||||
Koleksiyon işlemleri, mümkün olduğunda atomik olacak ve uygun hata yönetimi ve doğrulama sağlayacaktır.
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
Koleksiyon yönetimi işlemleri, yetkisiz erişimi veya koleksiyonların silinmesini önlemek için uygun yetkilendirme gerektirir. Erişim kontrolü, mevcut TrustGraph güvenlik modelleriyle uyumlu olacaktır.
|
||||
|
||||
## Performans Hususları
|
||||
|
||||
Koleksiyon listeleme işlemleri, çok sayıda koleksiyon içeren ortamlarda sayfalama gerektirebilir. Meta veri sorguları, yaygın filtreleme kalıpları için optimize edilmelidir.
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
Kapsamlı testler şunları kapsayacaktır:
|
||||
Koleksiyon oluşturma iş akışı, uçtan uca
|
||||
Depolama arka uç senkronizasyonu
|
||||
Var olmayan koleksiyonlar için yazma doğrulaması
|
||||
Var olmayan koleksiyonların sorgu işlenmesi
|
||||
Koleksiyon silme işleminin tüm depolama alanlarında yayılması
|
||||
Hata yönetimi ve kurtarma senaryoları
|
||||
Her depolama arka ucu için birim testleri
|
||||
Çapraz depolama işlemleri için entegrasyon testleri
|
||||
|
||||
## Uygulama Durumu
|
||||
|
||||
### ✅ Tamamlanmış Bileşenler
|
||||
|
||||
1. **Librarian Koleksiyon Yönetimi Hizmeti** (`trustgraph-flow/trustgraph/librarian/collection_manager.py`)
|
||||
Koleksiyon meta veri CRUD işlemleri (listeleme, güncelleme, silme)
|
||||
`LibraryTableStore` aracılığıyla Cassandra koleksiyon meta veri tablosu entegrasyonu
|
||||
Koleksiyon silme işleminin tüm depolama türleri arasında koordinasyonu
|
||||
Uygun hata yönetimi ile asenkron istek/yanıt işleme
|
||||
|
||||
2. **Koleksiyon Meta Veri Şeması** (`trustgraph-base/trustgraph/schema/services/collection.py`)
|
||||
`CollectionManagementRequest` ve `CollectionManagementResponse` şemaları
|
||||
Koleksiyon kayıtları için `CollectionMetadata` şeması
|
||||
Koleksiyon istek/yanıt kuyruğu konu tanımları
|
||||
|
||||
3. **Depolama Yönetimi Şeması** (`trustgraph-base/trustgraph/schema/services/storage.py`)
|
||||
`StorageManagementRequest` ve `StorageManagementResponse` şemaları
|
||||
Depolama yönetimi kuyruğu konuları tanımlandı
|
||||
Depolama seviyesindeki koleksiyon işlemleri için mesaj formatı
|
||||
|
||||
4. **Cassandra 4-Tablo Şeması** (`trustgraph-flow/trustgraph/direct/cassandra_kg.py`)
|
||||
Sorgu performansı için birleşik bölüm anahtarları
|
||||
SPO sorguları ve silme takibi için `triples_collection` tablosu
|
||||
Koleksiyon silme işlemi, okuyup sonra silme kalıbıyla uygulandı
|
||||
|
||||
### ✅ Yapılandırma Tabanlı Kalıba Geçiş - TAMAMLANDI
|
||||
|
||||
**Tüm depolama arka uçları, kuyruk tabanlı kalıptan yapılandırma tabanlı `CollectionConfigHandler` kalıbına geçirildi.**
|
||||
|
||||
Tamamlanan geçişler:
|
||||
✅ `trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/triples/neo4j/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/triples/memgraph/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/triples/falkordb/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/doc_embeddings/qdrant/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/graph_embeddings/qdrant/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/doc_embeddings/milvus/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/graph_embeddings/milvus/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/doc_embeddings/pinecone/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/graph_embeddings/pinecone/write.py`
|
||||
✅ `trustgraph-flow/trustgraph/storage/objects/cassandra/write.py`
|
||||
|
||||
Tüm arka uçlar artık:
|
||||
`CollectionConfigHandler`'dan miras almaktadır
|
||||
`self.register_config_handler(self.on_collection_config)` aracılığıyla yapılandırma itme bildirimleri için kayıtlıdır
|
||||
`create_collection(user, collection, metadata)` ve `delete_collection(user, collection)`'i uygulamaktadır
|
||||
Yazmadan önce `collection_exists(user, collection)` ile doğrulamaktadır
|
||||
Otomatik olarak yapılandırma hizmeti değişiklikleriyle senkronize olmaktadır
|
||||
|
||||
Eski kuyruk tabanlı altyapı kaldırıldı:
|
||||
✅ `StorageManagementRequest` ve `StorageManagementResponse` şemaları kaldırıldı
|
||||
✅ Depolama yönetimi kuyruğu konu tanımları kaldırıldı
|
||||
✅ Tüm arka uçlardan depolama yönetimi tüketici/üretici kaldırıldı
|
||||
✅ Tüm arka uçlardan `on_storage_management` işleyicileri kaldırıldı
|
||||
144
docs/tech-specs/tr/document-embeddings-chunk-id.tr.md
Normal file
144
docs/tech-specs/tr/document-embeddings-chunk-id.tr.md
Normal file
|
|
@ -0,0 +1,144 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Belge Gömme Parçası Kimliği"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Belge Gömme Parçası Kimliği
|
||||
|
||||
> **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ış
|
||||
|
||||
Belge gömme depolaması şu anda parça metnini doğrudan vektör deposu yüküne kaydederek, Garage'da bulunan verilerin çoğaltılmasına neden oluyor. Bu özellik, parça metni depolamasını `chunk_id` referanslarıyla değiştirmektedir.
|
||||
|
||||
## Mevcut Durum
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ChunkEmbeddings:
|
||||
chunk: bytes = b""
|
||||
vectors: list[list[float]] = field(default_factory=list)
|
||||
|
||||
@dataclass
|
||||
class DocumentEmbeddingsResponse:
|
||||
error: Error | None = None
|
||||
chunks: list[str] = field(default_factory=list)
|
||||
```
|
||||
|
||||
Vektör depolama yükü:
|
||||
```python
|
||||
payload={"doc": chunk} # Duplicates Garage content
|
||||
```
|
||||
|
||||
## Tasarım
|
||||
|
||||
### Şema Değişiklikleri
|
||||
|
||||
**ChunkEmbeddings** - chunk'ı chunk_id ile değiştirin:
|
||||
```python
|
||||
@dataclass
|
||||
class ChunkEmbeddings:
|
||||
chunk_id: str = ""
|
||||
vectors: list[list[float]] = field(default_factory=list)
|
||||
```
|
||||
|
||||
**DocumentEmbeddingsResponse** - parçalar yerine chunk_id'leri döndür:
|
||||
```python
|
||||
@dataclass
|
||||
class DocumentEmbeddingsResponse:
|
||||
error: Error | None = None
|
||||
chunk_ids: list[str] = field(default_factory=list)
|
||||
```
|
||||
|
||||
### Vektör Depolama Veri Yapısı
|
||||
|
||||
Tüm depolar (Qdrant, Milvus, Pinecone):
|
||||
```python
|
||||
payload={"chunk_id": chunk_id}
|
||||
```
|
||||
|
||||
### Belge RAG Değişiklikleri
|
||||
|
||||
Belge RAG işlemcisi, parça içeriğini Garage'dan alır:
|
||||
|
||||
```python
|
||||
# Get chunk_ids from embeddings store
|
||||
chunk_ids = await self.rag.doc_embeddings_client.query(...)
|
||||
|
||||
# Fetch chunk content from Garage
|
||||
docs = []
|
||||
for chunk_id in chunk_ids:
|
||||
content = await self.rag.librarian_client.get_document_content(
|
||||
chunk_id, self.user
|
||||
)
|
||||
docs.append(content)
|
||||
```
|
||||
|
||||
### API/SDK Değişiklikleri
|
||||
|
||||
**DocumentEmbeddingsClient**, `chunk_ids` değerini döndürür:
|
||||
```python
|
||||
return resp.chunk_ids # Changed from resp.chunks
|
||||
```
|
||||
|
||||
**Kablolu format** (DocumentEmbeddingsResponseTranslator):
|
||||
```python
|
||||
result["chunk_ids"] = obj.chunk_ids # Changed from chunks
|
||||
```
|
||||
|
||||
### CLI Değişiklikleri
|
||||
|
||||
CLI aracı, chunk_id'leri gösterir (çağrıcılar, gerekirse içeriği ayrı olarak alabilir).
|
||||
|
||||
## Değiştirilecek Dosyalar
|
||||
|
||||
### Şema
|
||||
`trustgraph-base/trustgraph/schema/knowledge/embeddings.py` - ChunkEmbeddings
|
||||
`trustgraph-base/trustgraph/schema/services/query.py` - DocumentEmbeddingsResponse
|
||||
|
||||
### Mesajlaşma/Çeviriciler
|
||||
`trustgraph-base/trustgraph/messaging/translators/embeddings_query.py` - DocumentEmbeddingsResponseTranslator
|
||||
|
||||
### İstemci
|
||||
`trustgraph-base/trustgraph/base/document_embeddings_client.py` - chunk_id'leri döndür
|
||||
|
||||
### Python SDK/API
|
||||
`trustgraph-base/trustgraph/api/flow.py` - document_embeddings_query
|
||||
`trustgraph-base/trustgraph/api/socket_client.py` - document_embeddings_query
|
||||
`trustgraph-base/trustgraph/api/async_flow.py` - eğer uygunsa
|
||||
`trustgraph-base/trustgraph/api/bulk_client.py` - belge gömülerinin içe/dışa aktarımı
|
||||
`trustgraph-base/trustgraph/api/async_bulk_client.py` - belge gömülerinin içe/dışa aktarımı
|
||||
|
||||
### Gömme Hizmeti
|
||||
`trustgraph-flow/trustgraph/embeddings/document_embeddings/embeddings.py` - chunk_id'yi ilet
|
||||
|
||||
### Depolama Yazıcıları
|
||||
`trustgraph-flow/trustgraph/storage/doc_embeddings/qdrant/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/doc_embeddings/milvus/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/doc_embeddings/pinecone/write.py`
|
||||
|
||||
### Sorgu Hizmetleri
|
||||
`trustgraph-flow/trustgraph/query/doc_embeddings/qdrant/service.py`
|
||||
`trustgraph-flow/trustgraph/query/doc_embeddings/milvus/service.py`
|
||||
`trustgraph-flow/trustgraph/query/doc_embeddings/pinecone/service.py`
|
||||
|
||||
### Ağ Geçidi
|
||||
`trustgraph-flow/trustgraph/gateway/dispatch/document_embeddings_query.py`
|
||||
`trustgraph-flow/trustgraph/gateway/dispatch/document_embeddings_export.py`
|
||||
`trustgraph-flow/trustgraph/gateway/dispatch/document_embeddings_import.py`
|
||||
|
||||
### Belge RAG
|
||||
`trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` - librarian istemcisini ekle
|
||||
`trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` - Garage'dan al
|
||||
|
||||
### CLI
|
||||
`trustgraph-cli/trustgraph/cli/invoke_document_embeddings.py`
|
||||
`trustgraph-cli/trustgraph/cli/save_doc_embeds.py`
|
||||
`trustgraph-cli/trustgraph/cli/load_doc_embeds.py`
|
||||
|
||||
## Faydalar
|
||||
|
||||
1. Tek kaynaklı doğruluk - chunk metni yalnızca Garage'da bulunur.
|
||||
2. Vektör depolama alanında azalma.
|
||||
3. chunk_id aracılığıyla sorgu zamanı köken bilgisini sağlar.
|
||||
675
docs/tech-specs/tr/embeddings-batch-processing.tr.md
Normal file
675
docs/tech-specs/tr/embeddings-batch-processing.tr.md
Normal file
|
|
@ -0,0 +1,675 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Gömme İşlemleri Toplu İşleme Teknik Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Gömme İşlemleri Toplu İşleme 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 teknik özellik, gömme hizmeti için, tek bir istekte birden fazla metni toplu olarak işleyebilmeyi desteklemek amacıyla yapılan optimizasyonları açıklamaktadır. Mevcut uygulama, her seferinde tek bir metni işlemektedir ve bu durum, gömme modellerinin toplu işlemler sırasında sağladığı önemli performans avantajlarından yararlanılmamasına neden olmaktadır.
|
||||
|
||||
1. **Tek Metin İşleme Verimsizliği**: Mevcut uygulama, tek metinleri bir liste içinde kullanarak, FastEmbed'in toplu işleme yeteneklerini tam olarak kullanamamaktadır.
|
||||
2. **Metin Başına İstek Yükü**: Her metin için ayrı bir Pulsar mesajı gönderilip alınması gerekmektedir.
|
||||
3. **Model Çıkarım Verimsizliği**: Gömme modellerinin sabit bir toplu işleme yükü vardır; küçük toplu işlemler GPU/CPU kaynaklarının israfına yol açar.
|
||||
4. **Çağıran Tarafında Seri İşleme**: Önemli hizmetler, öğeler üzerinde döngü yaparak gömme işlemlerini tek tek gerçekleştirmektedir.
|
||||
|
||||
## Hedefler
|
||||
|
||||
**Toplu API Desteği**: Tek bir istekte birden fazla metni işleyebilmeyi destekleyin.
|
||||
**Geriye Dönük Uyumluluk**: Tek metin isteklerine olan desteği koruyun.
|
||||
**Önemli Verimlilik Artışı**: Toplu işlemler için 5-10 kat verimlilik artışı hedefleyin.
|
||||
**Metin Başına Azaltılmış Gecikme**: Birden fazla metni gömme işlemi sırasında amortize gecikmeyi azaltın.
|
||||
**Bellek Verimliliği**: Aşırı bellek tüketimi olmadan toplu işlemleri gerçekleştirin.
|
||||
**Sağlayıcıdan Bağımsızlık**: FastEmbed, Ollama ve diğer sağlayıcılar arasında toplu işleme desteğini sağlayın.
|
||||
**Çağıran Taraf Güncellemesi**: Toplu API'nin faydalı olduğu durumlarda tüm gömme işlemlerini kullanan hizmetleri güncelleyin.
|
||||
|
||||
## Arka Plan
|
||||
|
||||
### Mevcut Uygulama - Gömme Hizmeti
|
||||
|
||||
`trustgraph-flow/trustgraph/embeddings/fastembed/processor.py` içindeki gömme uygulamasında önemli bir performans verimsizliği bulunmaktadır:
|
||||
|
||||
```python
|
||||
# fastembed/processor.py line 56
|
||||
async def on_embeddings(self, text, model=None):
|
||||
use_model = model or self.default_model
|
||||
self._load_model(use_model)
|
||||
|
||||
vecs = self.embeddings.embed([text]) # Single text wrapped in list
|
||||
|
||||
return [v.tolist() for v in vecs]
|
||||
```
|
||||
|
||||
**Sorunlar:**
|
||||
|
||||
1. **Batch Boyutu 1:** FastEmbed'in `embed()` yöntemi, toplu işleme için optimize edilmiştir, ancak bunu her zaman `[text]` - 1 boyutlu bir toplu işleme ile çağırıyoruz.
|
||||
|
||||
2. **İstek Başına Ek Yük:** Her gömme isteği aşağıdaki ek yükleri içerir:
|
||||
Pulsar mesajı serileştirme/deserileştirme
|
||||
Ağ gidiş-dönüş gecikmesi
|
||||
Model çıkarım başlatma ek yükü
|
||||
Python asenkron planlama ek yükü
|
||||
|
||||
3. **Şema Sınırlaması:** `EmbeddingsRequest` şeması yalnızca tek bir metni destekler:
|
||||
```python
|
||||
@dataclass
|
||||
class EmbeddingsRequest:
|
||||
text: str = "" # Single text only
|
||||
```
|
||||
|
||||
### Mevcut Çağrılar - Seri İşleme
|
||||
|
||||
#### 1. API Ağ Geçidi
|
||||
|
||||
**Dosya:** `trustgraph-flow/trustgraph/gateway/dispatch/embeddings.py`
|
||||
|
||||
Ağ geçidi, HTTP/WebSocket üzerinden tek metin gömme isteklerini kabul eder ve bunları gömme hizmetine yönlendirir. Şu anda toplu işlem için bir uç nokta bulunmamaktadır.
|
||||
|
||||
```python
|
||||
class EmbeddingsRequestor(ServiceRequestor):
|
||||
# Handles single EmbeddingsRequest -> EmbeddingsResponse
|
||||
request_schema=EmbeddingsRequest, # Single text only
|
||||
response_schema=EmbeddingsResponse,
|
||||
```
|
||||
|
||||
**Etki:** Harici müşteriler (web uygulamaları, betikler), N metni yerleştirmek için N adet HTTP isteği yapmalıdır.
|
||||
|
||||
#### 2. Belge Gömme Hizmeti
|
||||
|
||||
**Dosya:** `trustgraph-flow/trustgraph/embeddings/document_embeddings/embeddings.py`
|
||||
|
||||
Belgeleri tek tek parçalar halinde işler:
|
||||
|
||||
```python
|
||||
async def on_message(self, msg, consumer, flow):
|
||||
v = msg.value()
|
||||
|
||||
# Single chunk per request
|
||||
resp = await flow("embeddings-request").request(
|
||||
EmbeddingsRequest(text=v.chunk)
|
||||
)
|
||||
vectors = resp.vectors
|
||||
```
|
||||
|
||||
**Etki:** Her belge parçası için ayrı bir gömme (embedding) çağrısı gereklidir. 100 parçadan oluşan bir belge = 100 gömme isteği.
|
||||
|
||||
#### 3. Grafik Gömme Hizmeti
|
||||
|
||||
**Dosya:** `trustgraph-flow/trustgraph/embeddings/graph_embeddings/embeddings.py`
|
||||
|
||||
Varlıklar üzerinde döngü yapar ve her birini sırayla gömer:
|
||||
|
||||
```python
|
||||
async def on_message(self, msg, consumer, flow):
|
||||
for entity in v.entities:
|
||||
# Serial embedding - one entity at a time
|
||||
vectors = await flow("embeddings-request").embed(
|
||||
text=entity.context
|
||||
)
|
||||
entities.append(EntityEmbeddings(
|
||||
entity=entity.entity,
|
||||
vectors=vectors,
|
||||
chunk_id=entity.chunk_id,
|
||||
))
|
||||
```
|
||||
|
||||
**Etki:** 50 varlık içeren bir mesaj, 50 adet ardışık gömme (embedding) isteği anlamına gelir. Bu, bilgi grafiği oluşturma sırasında büyük bir darboğazdır.
|
||||
|
||||
#### 4. Satır Gömme Hizmeti
|
||||
|
||||
**Dosya:** `trustgraph-flow/trustgraph/embeddings/row_embeddings/embeddings.py`
|
||||
|
||||
Benzersiz metinler üzerinde döngü yapar ve her birini sırayla gömer:
|
||||
|
||||
```python
|
||||
async def on_message(self, msg, consumer, flow):
|
||||
for text, (index_name, index_value) in texts_to_embed.items():
|
||||
# Serial embedding - one text at a time
|
||||
vectors = await flow("embeddings-request").embed(text=text)
|
||||
|
||||
embeddings_list.append(RowIndexEmbedding(
|
||||
index_name=index_name,
|
||||
index_value=index_value,
|
||||
text=text,
|
||||
vectors=vectors
|
||||
))
|
||||
```
|
||||
|
||||
**Etki:** 100 benzersiz indeksli değere sahip bir tabloyu işlemek = 100 ardışık gömme isteği.
|
||||
|
||||
#### 5. EmbeddingsClient (Temel İstemci)
|
||||
|
||||
**Dosya:** `trustgraph-base/trustgraph/base/embeddings_client.py`
|
||||
|
||||
Tüm iş akışı işleyicileri tarafından kullanılan istemci, yalnızca tek metin gömmesini destekler:
|
||||
|
||||
```python
|
||||
class EmbeddingsClient(RequestResponse):
|
||||
async def embed(self, text, timeout=30):
|
||||
resp = await self.request(
|
||||
EmbeddingsRequest(text=text), # Single text
|
||||
timeout=timeout
|
||||
)
|
||||
return resp.vectors
|
||||
```
|
||||
|
||||
**Etki:** Bu istemciyi kullanan tüm uygulamalar, yalnızca tek metin işlemleriyle sınırlıdır.
|
||||
|
||||
#### 6. Komut Satırı Araçları
|
||||
|
||||
**Dosya:** `trustgraph-cli/trustgraph/cli/invoke_embeddings.py`
|
||||
|
||||
CLI aracı, tek bir metin argümanı alır:
|
||||
|
||||
```python
|
||||
def query(url, flow_id, text, token=None):
|
||||
result = flow.embeddings(text=text) # Single text
|
||||
vectors = result.get("vectors", [])
|
||||
```
|
||||
|
||||
**Etki:** Kullanıcılar, komut satırından toplu gömme işlemi yapamaz. Bir metin dosyasını işlemek, N sayıda çağrı gerektirir.
|
||||
|
||||
#### 7. Python SDK
|
||||
|
||||
Python SDK, TrustGraph hizmetleriyle etkileşim kurmak için iki istemci sınıfı sağlar. Her ikisi de yalnızca tek metin gömme işlemini destekler.
|
||||
|
||||
**Dosya:** `trustgraph-base/trustgraph/api/flow.py`
|
||||
|
||||
```python
|
||||
class FlowInstance:
|
||||
def embeddings(self, text):
|
||||
"""Get embeddings for a single text"""
|
||||
input = {"text": text}
|
||||
return self.request("service/embeddings", input)["vectors"]
|
||||
```
|
||||
|
||||
**Dosya:** `trustgraph-base/trustgraph/api/socket_client.py`
|
||||
|
||||
```python
|
||||
class SocketFlowInstance:
|
||||
def embeddings(self, text: str, **kwargs: Any) -> Dict[str, Any]:
|
||||
"""Get embeddings for a single text via WebSocket"""
|
||||
request = {"text": text}
|
||||
return self.client._send_request_sync(
|
||||
"embeddings", self.flow_id, request, False
|
||||
)
|
||||
```
|
||||
|
||||
**Etki:** SDK'yı kullanan Python geliştiricilerinin, metinler üzerinde döngü yapması ve N adet API çağrısı yapması gerekir. SDK kullanıcıları için toplu gömme desteği mevcut değildir.
|
||||
|
||||
### Performans Etkisi
|
||||
|
||||
Tipik belge yükleme için (1000 metin parçası):
|
||||
**Mevcut:** 1000 ayrı istek, 1000 model çıkarım çağrısı
|
||||
**Toplu (batch_size=32):** 32 istek, 32 model çıkarım çağrısı (%96,8 azalma)
|
||||
|
||||
Grafik gömme için (50 varlığa sahip mesaj):
|
||||
**Mevcut:** 50 ardışık bekletme çağrısı, ~5-10 saniye
|
||||
**Toplu:** 1-2 toplu çağrı, ~0,5-1 saniye (5-10 kat iyileşme)
|
||||
|
||||
FastEmbed ve benzeri kütüphaneler, toplu boyutun donanım sınırlarına kadar ulaştığı durumlarda, yaklaşık doğrusal bir verim ölçeklemesi sağlar (tipik olarak toplu boyutta 32-128 metin).
|
||||
|
||||
## Teknik Tasarım
|
||||
|
||||
### Mimari
|
||||
|
||||
Gömme toplu işleme optimizasyonu, aşağıdaki bileşenlerde değişiklikler gerektirir:
|
||||
|
||||
#### 1. **Şema Geliştirme**
|
||||
`EmbeddingsRequest`'ı, birden fazla metni destekleyecek şekilde genişletin
|
||||
`EmbeddingsResponse`'ı, birden fazla vektör kümesini döndürecek şekilde genişletin
|
||||
Tek metin istekleriyle uyumluluğu koruyun
|
||||
|
||||
Modül: `trustgraph-base/trustgraph/schema/services/llm.py`
|
||||
|
||||
#### 2. **Temel Servis Geliştirme**
|
||||
`EmbeddingsService`'ı, toplu istekleri işleyebilecek şekilde güncelleyin
|
||||
Toplu boyut yapılandırması ekleyin
|
||||
Toplu işleme duyarlı istek işleme uygulayın
|
||||
|
||||
Modül: `trustgraph-base/trustgraph/base/embeddings_service.py`
|
||||
|
||||
#### 3. **Sağlayıcı İşlemcisi Güncellemeleri**
|
||||
FastEmbed işlemcisini güncelleyin, böylece tam toplu iş yükünü `embed()`'a iletebilir
|
||||
Ollama işlemcisini güncelleyin, böylece toplu işlemleri işleyebilir (destekleniyorsa)
|
||||
Toplu işlemeyi desteklemeyen sağlayıcılar için yedek sıralı işlemeyi ekleyin
|
||||
|
||||
Modüller:
|
||||
`trustgraph-flow/trustgraph/embeddings/fastembed/processor.py`
|
||||
`trustgraph-flow/trustgraph/embeddings/ollama/processor.py`
|
||||
|
||||
#### 4. **İstemci Geliştirme**
|
||||
`EmbeddingsClient`'a toplu gömme yöntemini ekleyin
|
||||
Hem tek hem de toplu API'leri destekleyin
|
||||
Büyük girdiler için otomatik toplu işlemeyi ekleyin
|
||||
|
||||
Modül: `trustgraph-base/trustgraph/base/embeddings_client.py`
|
||||
|
||||
#### 5. **Çağrı Güncellemeleri - Akış İşlemcileri**
|
||||
`graph_embeddings`'ı, varlık bağlamlarını toplu hale getirecek şekilde güncelleyin
|
||||
`row_embeddings`'ı, indeks metinlerini toplu hale getirecek şekilde güncelleyin
|
||||
Mesaj toplu işlemesi mümkünse, `document_embeddings`'ı güncelleyin
|
||||
|
||||
Modüller:
|
||||
`trustgraph-flow/trustgraph/embeddings/graph_embeddings/embeddings.py`
|
||||
`trustgraph-flow/trustgraph/embeddings/row_embeddings/embeddings.py`
|
||||
`trustgraph-flow/trustgraph/embeddings/document_embeddings/embeddings.py`
|
||||
|
||||
#### 6. **API Ağ Geçidi Geliştirme**
|
||||
Toplu gömme uç noktası ekleyin
|
||||
İstek gövdesinde metin dizisini destekleyin
|
||||
|
||||
Modül: `trustgraph-flow/trustgraph/gateway/dispatch/embeddings.py`
|
||||
|
||||
#### 7. **CLI Aracı Geliştirme**
|
||||
Birden fazla metin veya dosya girişi desteği ekleyin
|
||||
Toplu boyut parametresi ekleyin
|
||||
|
||||
Modül: `trustgraph-cli/trustgraph/cli/invoke_embeddings.py`
|
||||
|
||||
#### 8. **Python SDK Geliştirme**
|
||||
`embeddings_batch()` yöntemini `FlowInstance`'e ekleyin
|
||||
`embeddings_batch()` yöntemini `SocketFlowInstance`'e ekleyin
|
||||
SDK kullanıcıları için hem tek hem de toplu API'leri destekleyin
|
||||
|
||||
Modüller:
|
||||
`trustgraph-base/trustgraph/api/flow.py`
|
||||
`trustgraph-base/trustgraph/api/socket_client.py`
|
||||
|
||||
### Veri Modelleri
|
||||
|
||||
#### EmbeddingsRequest
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class EmbeddingsRequest:
|
||||
texts: list[str] = field(default_factory=list)
|
||||
```
|
||||
|
||||
Kullanım:
|
||||
Tek metin: `EmbeddingsRequest(texts=["hello world"])`
|
||||
Toplu işlem: `EmbeddingsRequest(texts=["text1", "text2", "text3"])`
|
||||
|
||||
#### EmbeddingsResponse
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class EmbeddingsResponse:
|
||||
error: Error | None = None
|
||||
vectors: list[list[list[float]]] = field(default_factory=list)
|
||||
```
|
||||
|
||||
Yanıt yapısı:
|
||||
`vectors[i]`, `texts[i]` için vektör kümesini içerir.
|
||||
Her vektör kümesi `list[list[float]]`'dır (modeller, her metin için birden fazla vektör döndürebilir).
|
||||
Örnek: 3 metin → `vectors`, 3 giriş içerir ve her giriş, o metnin gömülme değerlerini içerir.
|
||||
|
||||
### API'ler
|
||||
|
||||
#### EmbeddingsClient
|
||||
|
||||
```python
|
||||
class EmbeddingsClient(RequestResponse):
|
||||
async def embed(
|
||||
self,
|
||||
texts: list[str],
|
||||
timeout: float = 300,
|
||||
) -> list[list[list[float]]]:
|
||||
"""
|
||||
Embed one or more texts in a single request.
|
||||
|
||||
Args:
|
||||
texts: List of texts to embed
|
||||
timeout: Timeout for the operation
|
||||
|
||||
Returns:
|
||||
List of vector sets, one per input text
|
||||
"""
|
||||
resp = await self.request(
|
||||
EmbeddingsRequest(texts=texts),
|
||||
timeout=timeout
|
||||
)
|
||||
if resp.error:
|
||||
raise RuntimeError(resp.error.message)
|
||||
return resp.vectors
|
||||
```
|
||||
|
||||
#### API Gateway Gömülü Veri (Embeddings) Uç Noktası
|
||||
|
||||
Tek bir veya toplu gömülü veri desteğini sağlayan güncellenmiş uç nokta:
|
||||
|
||||
```
|
||||
POST /api/v1/embeddings
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"texts": ["text1", "text2", "text3"],
|
||||
"flow_id": "default"
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"vectors": [
|
||||
[[0.1, 0.2, ...]],
|
||||
[[0.3, 0.4, ...]],
|
||||
[[0.5, 0.6, ...]]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Uygulama Detayları
|
||||
|
||||
#### Aşama 1: Şema Değişiklikleri
|
||||
|
||||
**EmbeddingsRequest:**
|
||||
```python
|
||||
@dataclass
|
||||
class EmbeddingsRequest:
|
||||
texts: list[str] = field(default_factory=list)
|
||||
```
|
||||
|
||||
**Gömme Yanıtı:**
|
||||
```python
|
||||
@dataclass
|
||||
class EmbeddingsResponse:
|
||||
error: Error | None = None
|
||||
vectors: list[list[list[float]]] = field(default_factory=list)
|
||||
```
|
||||
|
||||
**Güncellenmiş EmbeddingsService.on_request:**
|
||||
```python
|
||||
async def on_request(self, msg, consumer, flow):
|
||||
request = msg.value()
|
||||
id = msg.properties()["id"]
|
||||
model = flow("model")
|
||||
|
||||
vectors = await self.on_embeddings(request.texts, model=model)
|
||||
response = EmbeddingsResponse(error=None, vectors=vectors)
|
||||
|
||||
await flow("response").send(response, properties={"id": id})
|
||||
```
|
||||
|
||||
#### 2. Aşama: FastEmbed İşlemci Güncellemesi
|
||||
|
||||
**Mevcut (Verimsiz):**
|
||||
```python
|
||||
async def on_embeddings(self, text, model=None):
|
||||
use_model = model or self.default_model
|
||||
self._load_model(use_model)
|
||||
vecs = self.embeddings.embed([text]) # Batch of 1
|
||||
return [v.tolist() for v in vecs]
|
||||
```
|
||||
|
||||
**Güncellendi:**
|
||||
```python
|
||||
async def on_embeddings(self, texts: list[str], model=None):
|
||||
"""Embed texts - processes all texts in single model call"""
|
||||
if not texts:
|
||||
return []
|
||||
|
||||
use_model = model or self.default_model
|
||||
self._load_model(use_model)
|
||||
|
||||
# FastEmbed handles the full batch efficiently
|
||||
all_vecs = list(self.embeddings.embed(texts))
|
||||
|
||||
# Return list of vector sets, one per input text
|
||||
return [[v.tolist()] for v in all_vecs]
|
||||
```
|
||||
|
||||
#### 3. Aşama: Grafik Gömme Hizmeti Güncellemesi
|
||||
|
||||
**Mevcut (Sıralı):**
|
||||
```python
|
||||
async def on_message(self, msg, consumer, flow):
|
||||
entities = []
|
||||
for entity in v.entities:
|
||||
vectors = await flow("embeddings-request").embed(text=entity.context)
|
||||
entities.append(EntityEmbeddings(...))
|
||||
```
|
||||
|
||||
**Güncellendi (Toplu İşlem):**
|
||||
```python
|
||||
async def on_message(self, msg, consumer, flow):
|
||||
# Collect all contexts
|
||||
contexts = [entity.context for entity in v.entities]
|
||||
|
||||
# Single batch embedding call
|
||||
all_vectors = await flow("embeddings-request").embed(texts=contexts)
|
||||
|
||||
# Pair results with entities
|
||||
entities = [
|
||||
EntityEmbeddings(
|
||||
entity=entity.entity,
|
||||
vectors=vectors[0], # First vector from the set
|
||||
chunk_id=entity.chunk_id,
|
||||
)
|
||||
for entity, vectors in zip(v.entities, all_vectors)
|
||||
]
|
||||
```
|
||||
|
||||
#### 4. Aşama: Satır Gömme Hizmeti Güncellemesi
|
||||
|
||||
**Mevcut (Sıralı):**
|
||||
```python
|
||||
for text, (index_name, index_value) in texts_to_embed.items():
|
||||
vectors = await flow("embeddings-request").embed(text=text)
|
||||
embeddings_list.append(RowIndexEmbedding(...))
|
||||
```
|
||||
|
||||
**Güncellendi (Toplu İşlem):**
|
||||
```python
|
||||
# Collect texts and metadata
|
||||
texts = list(texts_to_embed.keys())
|
||||
metadata = list(texts_to_embed.values())
|
||||
|
||||
# Single batch embedding call
|
||||
all_vectors = await flow("embeddings-request").embed(texts=texts)
|
||||
|
||||
# Pair results
|
||||
embeddings_list = [
|
||||
RowIndexEmbedding(
|
||||
index_name=meta[0],
|
||||
index_value=meta[1],
|
||||
text=text,
|
||||
vectors=vectors[0] # First vector from the set
|
||||
)
|
||||
for text, meta, vectors in zip(texts, metadata, all_vectors)
|
||||
]
|
||||
```
|
||||
|
||||
#### 5. Aşama: Komut Satırı Arama Aracı Geliştirme
|
||||
|
||||
**Güncellenmiş Komut Satırı:**
|
||||
```python
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(...)
|
||||
|
||||
parser.add_argument(
|
||||
'text',
|
||||
nargs='*', # Zero or more texts
|
||||
help='Text(s) to convert to embedding vectors',
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'-f', '--file',
|
||||
help='File containing texts (one per line)',
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--batch-size',
|
||||
type=int,
|
||||
default=32,
|
||||
help='Batch size for processing (default: 32)',
|
||||
)
|
||||
```
|
||||
|
||||
Kullanım:
|
||||
```bash
|
||||
# Single text (existing)
|
||||
tg-invoke-embeddings "hello world"
|
||||
|
||||
# Multiple texts
|
||||
tg-invoke-embeddings "text one" "text two" "text three"
|
||||
|
||||
# From file
|
||||
tg-invoke-embeddings -f texts.txt --batch-size 64
|
||||
```
|
||||
|
||||
#### 6. Aşama: Python SDK Geliştirme
|
||||
|
||||
**FlowInstance (HTTP istemcisi):**
|
||||
|
||||
```python
|
||||
class FlowInstance:
|
||||
def embeddings(self, texts: list[str]) -> list[list[list[float]]]:
|
||||
"""
|
||||
Get embeddings for one or more texts.
|
||||
|
||||
Args:
|
||||
texts: List of texts to embed
|
||||
|
||||
Returns:
|
||||
List of vector sets, one per input text
|
||||
"""
|
||||
input = {"texts": texts}
|
||||
return self.request("service/embeddings", input)["vectors"]
|
||||
```
|
||||
|
||||
**SocketFlowInstance (WebSocket istemcisi):**
|
||||
|
||||
```python
|
||||
class SocketFlowInstance:
|
||||
def embeddings(self, texts: list[str], **kwargs: Any) -> list[list[list[float]]]:
|
||||
"""
|
||||
Get embeddings for one or more texts via WebSocket.
|
||||
|
||||
Args:
|
||||
texts: List of texts to embed
|
||||
|
||||
Returns:
|
||||
List of vector sets, one per input text
|
||||
"""
|
||||
request = {"texts": texts}
|
||||
response = self.client._send_request_sync(
|
||||
"embeddings", self.flow_id, request, False
|
||||
)
|
||||
return response["vectors"]
|
||||
```
|
||||
|
||||
**SDK Kullanım Örnekleri:**
|
||||
|
||||
```python
|
||||
# Single text
|
||||
vectors = flow.embeddings(["hello world"])
|
||||
print(f"Dimensions: {len(vectors[0][0])}")
|
||||
|
||||
# Batch embedding
|
||||
texts = ["text one", "text two", "text three"]
|
||||
all_vectors = flow.embeddings(texts)
|
||||
|
||||
# Process results
|
||||
for text, vecs in zip(texts, all_vectors):
|
||||
print(f"{text}: {len(vecs[0])} dimensions")
|
||||
```
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
**İstek Boyutu Sınırları**: Kaynak tükenmesini önlemek için maksimum toplu işlem boyutunu zorlayın.
|
||||
**Zaman Aşımı İşleme**: Toplu işlem boyutu için zaman aşımını uygun şekilde ayarlayın.
|
||||
**Bellek Sınırları**: Büyük toplu işlemler için bellek kullanımını izleyin.
|
||||
**Giriş Doğrulama**: İşleme yapmadan önce toplu işlemdeki tüm metinleri doğrulayın.
|
||||
|
||||
## Performans Hususları
|
||||
|
||||
### Beklenen İyileştirmeler
|
||||
|
||||
**Verim:**
|
||||
Tek metin: ~10-50 metin/saniye (modele bağlı olarak)
|
||||
Toplu işlem (boyut 32): ~200-500 metin/saniye (5-10 kat iyileşme)
|
||||
|
||||
**Metin Başına Gecikme:**
|
||||
Tek metin: metin başına 50-200 ms
|
||||
Toplu işlem (boyut 32): metin başına 5-20 ms (ortalama)
|
||||
|
||||
**Hizmete Özel İyileştirmeler:**
|
||||
|
||||
| Hizmet | Mevcut | Toplu | İyileşme |
|
||||
|---------|---------|---------|-------------|
|
||||
| Grafik Gömme (50 varlık) | 5-10 saniye | 0,5-1 saniye | 5-10 kat |
|
||||
| Satır Gömme (100 metin) | 10-20 saniye | 1-2 saniye | 5-10 kat |
|
||||
| Belge Alma (1000 parça) | 100-200 saniye | 10-30 saniye | 5-10 kat |
|
||||
|
||||
### Yapılandırma Parametreleri
|
||||
|
||||
```python
|
||||
# Recommended defaults
|
||||
DEFAULT_BATCH_SIZE = 32
|
||||
MAX_BATCH_SIZE = 128
|
||||
BATCH_TIMEOUT_MULTIPLIER = 2.0
|
||||
```
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
### Birim Testleri
|
||||
Tek metin gömülmesi (geriye dönük uyumluluk)
|
||||
Boş toplu iş işleme
|
||||
Maksimum toplu iş boyutu zorlaması
|
||||
Kısmi toplu iş hataları için hata işleme
|
||||
|
||||
### Entegrasyon Testleri
|
||||
Pulsar üzerinden uçtan uca toplu iş gömülmesi
|
||||
Grafik gömme hizmeti toplu iş işleme
|
||||
Satır gömme hizmeti toplu iş işleme
|
||||
API ağ geçidi toplu iş uç noktası
|
||||
|
||||
### Performans Testleri
|
||||
Tek ve toplu iş verimini karşılaştırma
|
||||
Farklı toplu iş boyutları altındaki bellek kullanımı
|
||||
Gecikme dağılımı analizi
|
||||
|
||||
## Geçiş Planı
|
||||
|
||||
Bu, önemli değişikliklere neden olan bir sürümdür. Tüm fazlar birlikte uygulanır.
|
||||
|
||||
### 1. Aşama: Şema Değişiklikleri
|
||||
EmbeddingsRequest'teki `text: str`'ı `texts: list[str]` ile değiştirin
|
||||
EmbeddingsResponse'taki `vectors` türünü `list[list[list[float]]]` olarak değiştirin
|
||||
|
||||
### 2. Aşama: İşlemci Güncellemeleri
|
||||
FastEmbed ve Ollama işlemcilerindeki `on_embeddings` imzasını güncelleyin
|
||||
Tam toplu işi tek bir model çağrısında işleyin
|
||||
|
||||
### 3. Aşama: İstemci Güncellemeleri
|
||||
`EmbeddingsClient.embed()`'ı `texts: list[str]`'i kabul edecek şekilde güncelleyin
|
||||
|
||||
### 4. Aşama: Çağıran Güncellemeleri
|
||||
graph_embeddings'i toplu iş varlık bağlamlarını kullanacak şekilde güncelleyin
|
||||
row_embeddings'i toplu iş indeks metinlerini kullanacak şekilde güncelleyin
|
||||
document_embeddings'i yeni şemayı kullanacak şekilde güncelleyin
|
||||
CLI aracını güncelleyin
|
||||
|
||||
### 5. Aşama: API Ağ Geçidi
|
||||
Yeni şema için gömme uç noktasını güncelleyin
|
||||
|
||||
### 6. Aşama: Python SDK
|
||||
`FlowInstance.embeddings()` imzasını güncelleyin
|
||||
`SocketFlowInstance.embeddings()` imzasını güncelleyin
|
||||
|
||||
## Açık Sorular
|
||||
|
||||
**Büyük Toplu İşlerin Akışı**: Çok büyük toplu işler (>100 metin) için sonuçları akış olarak desteklemeli miyiz?
|
||||
**Sağlayıcıya Özel Sınırlar**: Farklı maksimum toplu iş boyutlarına sahip sağlayıcıları nasıl ele almalıyız?
|
||||
**Kısmi Hata İşleme**: Bir toplu işteki bir metin başarısız olursa, tüm toplu işi mi başarısız etmeliyiz yoksa kısmi sonuçları mı döndürmeliyiz?
|
||||
**Belge Gömme Toplu İşleme**: Çoklu Chunk mesajları arasında toplu işlemeyi mi yapmalıyız yoksa her mesaj için ayrı ayrı işlemeyi mi korumalıyız?
|
||||
|
||||
## Referanslar
|
||||
|
||||
[FastEmbed Belgeleri](https://github.com/qdrant/fastembed)
|
||||
[Ollama Gömme API'si](https://github.com/ollama/ollama)
|
||||
[EmbeddingsService Uygulaması](trustgraph-base/trustgraph/base/embeddings_service.py)
|
||||
[GraphRAG Performans Optimizasyonu](graphrag-performance-optimization.md)
|
||||
269
docs/tech-specs/tr/entity-centric-graph.tr.md
Normal file
269
docs/tech-specs/tr/entity-centric-graph.tr.md
Normal file
|
|
@ -0,0 +1,269 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Cassandra'da Varlık Odaklı Bilgi Grafiği Depolama"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Cassandra'da Varlık Odaklı Bilgi Grafiği Depolama
|
||||
|
||||
> **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 belge, Apache Cassandra üzerindeki RDF tarzı bilgi grafiklerinin depolanması için bir model tanımlamaktadır. Model, her varlığın katıldığı her dörtlü hakkında bilgi sahibi olduğu ve oynadığı rolün bilindiği, **varlık odaklı** bir yaklaşım kullanır. Bu, geleneksel çok tablolu SPO permütasyon yaklaşımının yerini sadece iki tabloyla alır.
|
||||
|
||||
## Arka Plan ve Motivasyon
|
||||
|
||||
### Geleneksel Yaklaşım
|
||||
|
||||
Cassandra'daki standart bir RDF dörtlü deposu, sorgu kalıplarını kapsamak için birden fazla denormalize edilmiş tablo gerektirir; tipik olarak, Konu, Özne, Nesne ve Veri Kümesi (SPOD) permütasyonlarının farklı temsillerini içeren 6 veya daha fazla tablo. Her dörtlü, her tabloya yazılır, bu da önemli bir yazma çoğaltmasına, operasyonel yüke ve şema karmaşıklığına yol açar.
|
||||
|
||||
Ek olarak, etiket çözümü (varlıklar için okunabilir adların alınması), ayrı gidiş-dönüş sorguları gerektirir ve bu da, etiketlerin LLM bağlamı için önemli olduğu yapay zeka ve GraphRAG kullanım durumlarında özellikle maliyetlidir.
|
||||
|
||||
### Varlık Odaklı İçgörü
|
||||
|
||||
Her bir dörtlü `(D, S, P, O)`, en fazla 4 varlığı içerir. Her bir varlığın dörtlüdeki katılımını bir satırla belirterek, **en az bir bilinen öğesi olan her sorgunun bir bölüm anahtarını hedefleyeceğinden emin oluruz**. Bu, tek bir veri tablosuyla tüm 16 sorgu desenini kapsar.
|
||||
|
||||
Temel avantajlar:
|
||||
|
||||
**7'den fazla yerine 2 tablo**
|
||||
**6'dan fazla yerine, her dörtlü için 4 yazma işlemi**
|
||||
**Etiket çözümlemesi ücretsiz** — bir varlığın etiketleri, ilişkileriyle birlikte bulunur ve bu da uygulama önbelleğini doğal olarak önceden doldurur.
|
||||
**Tüm 16 sorgu deseni**, tek bölüm okumalarıyla sağlanır.
|
||||
**Daha basit işlemler** — ayarlanması, sıkıştırılması ve onarılması gereken tek bir veri tablosu.
|
||||
|
||||
## Şema
|
||||
|
||||
### Tablo 1: quads_by_entity
|
||||
|
||||
Birincil veri tablosu. Her varlığın, katıldığı tüm dörtlüleri içeren bir bölümü vardır. Sorgu desenini yansıtacak şekilde adlandırılmıştır (varlık bazında arama).
|
||||
|
||||
```sql
|
||||
CREATE TABLE quads_by_entity (
|
||||
collection text, -- Collection/tenant scope (always specified)
|
||||
entity text, -- The entity this row is about
|
||||
role text, -- 'S', 'P', 'O', 'G' — how this entity participates
|
||||
p text, -- Predicate of the quad
|
||||
otype text, -- 'U' (URI), 'L' (literal), 'T' (triple/reification)
|
||||
s text, -- Subject of the quad
|
||||
o text, -- Object of the quad
|
||||
d text, -- Dataset/graph of the quad
|
||||
dtype text, -- XSD datatype (when otype = 'L'), e.g. 'xsd:string'
|
||||
lang text, -- Language tag (when otype = 'L'), e.g. 'en', 'fr'
|
||||
PRIMARY KEY ((collection, entity), role, p, otype, s, o, d, dtype, lang)
|
||||
);
|
||||
```
|
||||
|
||||
**Bölüm anahtarı**: `(collection, entity)` — koleksiyona özel, her varlık için bir bölüm.
|
||||
|
||||
**Kümeleme sütun sıralama gerekçesi**:
|
||||
|
||||
1. **role** — çoğu sorgu, "bu varlık bir konu mu/nesne mi" şeklinde başlar.
|
||||
2. **p** — en yaygın filtrelerden ikincisi, "bana tüm `knows` ilişkilerini ver".
|
||||
3. **otype** — URI değeri olan ilişkileri, literal değeri olan ilişkilerden ayırmayı sağlar.
|
||||
4. **s, o, d** — benzersizlik için kalan sütunlar.
|
||||
5. **dtype, lang** — aynı değere sahip ancak farklı tür meta verilerine sahip literal değerleri ayırt eder (örneğin, `"thing"` vs `"thing"@en` vs `"thing"^^xsd:string`).
|
||||
|
||||
### Tablo 2: quads_by_collection
|
||||
|
||||
Koleksiyon seviyesindeki sorguları ve silme işlemlerini destekler. Bir koleksiyona ait olan tüm dörtlülerin bir listesini sağlar. Sorgu desenini yansıtacak şekilde adlandırılmıştır (koleksiyona göre arama).
|
||||
|
||||
```sql
|
||||
CREATE TABLE quads_by_collection (
|
||||
collection text,
|
||||
d text, -- Dataset/graph of the quad
|
||||
s text, -- Subject of the quad
|
||||
p text, -- Predicate of the quad
|
||||
o text, -- Object of the quad
|
||||
otype text, -- 'U' (URI), 'L' (literal), 'T' (triple/reification)
|
||||
dtype text, -- XSD datatype (when otype = 'L')
|
||||
lang text, -- Language tag (when otype = 'L')
|
||||
PRIMARY KEY (collection, d, s, p, o, otype, dtype, lang)
|
||||
);
|
||||
```
|
||||
|
||||
İlk olarak veri kümesi bazında gruplandırılır, bu da silme işleminin ya koleksiyon düzeyinde ya da veri kümesi düzeyinde yapılabilmesini sağlar. `otype`, `dtype` ve `lang` sütunları, aynı değere sahip ancak farklı tür meta verilerine sahip literal değerleri ayırt etmek için kümeleme anahtarına dahil edilmiştir; RDF'de, `"thing"`, `"thing"@en` ve `"thing"^^xsd:string` semantik olarak farklı değerlerdir.
|
||||
|
||||
## Yazma Yolu
|
||||
|
||||
Her bir koleksiyon içindeki `C` içinde gelen `(D, S, P, O)` dörtlüsü için, **4 satır** `quads_by_entity`'ye ve **1 satır** `quads_by_collection`'e yazın.
|
||||
|
||||
### Örnek
|
||||
|
||||
Koleksiyon içindeki `tenant1` dörtgeni verildiğinde:
|
||||
|
||||
```
|
||||
Dataset: https://example.org/graph1
|
||||
Subject: https://example.org/Alice
|
||||
Predicate: https://example.org/knows
|
||||
Object: https://example.org/Bob
|
||||
```
|
||||
|
||||
`quads_by_entity`'e 4 satır yazın:
|
||||
|
||||
| collection | entity | role | p | otype | s | o | d |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| tenant1 | https://example.org/graph1 | G | https://example.org/knows | U | https://example.org/Alice | https://example.org/Bob | https://example.org/graph1 |
|
||||
| tenant1 | https://example.org/Alice | S | https://example.org/knows | U | https://example.org/Alice | https://example.org/Bob | https://example.org/graph1 |
|
||||
| tenant1 | https://example.org/knows | P | https://example.org/knows | U | https://example.org/Alice | https://example.org/Bob | https://example.org/graph1 |
|
||||
| tenant1 | https://example.org/Bob | O | https://example.org/knows | U | https://example.org/Alice | https://example.org/Bob | https://example.org/graph1 |
|
||||
|
||||
`quads_by_collection`'e 1 satır yazın:
|
||||
|
||||
| collection | d | s | p | o | otype | dtype | lang |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| tenant1 | https://example.org/graph1 | https://example.org/Alice | https://example.org/knows | https://example.org/Bob | U | | |
|
||||
|
||||
### Literal Example
|
||||
|
||||
Bir etiket üçlüsü için:
|
||||
|
||||
```
|
||||
Dataset: https://example.org/graph1
|
||||
Subject: https://example.org/Alice
|
||||
Predicate: http://www.w3.org/2000/01/rdf-schema#label
|
||||
Object: "Alice Smith" (lang: en)
|
||||
```
|
||||
|
||||
`otype` değeri `'L'`, `dtype` değeri `'xsd:string'` ve `lang` değeri `'en'`'tir. Literal değer olan `"Alice Smith"`, `o` içinde saklanır. `quads_by_entity`'de yalnızca 3 satır gereklidir; literal, bir varlık olarak bağımsız olarak sorgulanamayan bir şey olduğu için, literal için herhangi bir satır yazılmaz.
|
||||
|
||||
## Sorgu Desenleri
|
||||
|
||||
### Tüm 16 DSPO Deseni
|
||||
|
||||
Aşağıdaki tabloda, "Mükemmel önek", sorgunun kümeleme sütunlarının ardışık bir önekini kullandığı anlamına gelir. "Bölüm taraması + filtre", Cassandra'nın bir bölümün bir dilimini okuduğu ve bellekte filtreleme yaptığı anlamına gelir; bu, verimli olsa da, saf bir önek eşleşmesi değildir.
|
||||
|
||||
| # | Bilinen | Varlık | Kümeleme öneki | Verimlilik |
|
||||
|---|---|---|---|---|
|
||||
| 1 | D,S,P,O | entity=S, role='S', p=P | Tam eşleşme | Mükemmel önek |
|
||||
| 2 | D,S,P,? | entity=S, role='S', p=P | D üzerinde filtreleme | Bölüm taraması + filtre |
|
||||
| 3 | D,S,?,O | entity=S, role='S' | D, O üzerinde filtreleme | Bölüm taraması + filtre |
|
||||
| 4 | D,?,P,O | entity=O, role='O', p=P | D üzerinde filtreleme | Bölüm taraması + filtre |
|
||||
| 5 | ?,S,P,O | entity=S, role='S', p=P | O üzerinde filtreleme | Bölüm taraması + filtre |
|
||||
| 6 | D,S,?,? | entity=S, role='S' | D üzerinde filtreleme | Bölüm taraması + filtre |
|
||||
| 7 | D,?,P,? | entity=P, role='P' | D üzerinde filtreleme | Bölüm taraması + filtre |
|
||||
| 8 | D,?,?,O | entity=O, role='O' | D üzerinde filtreleme | Bölüm taraması + filtre |
|
||||
| 9 | ?,S,P,? | entity=S, role='S', p=P | — | **Mükemmel önek** |
|
||||
| 10 | ?,S,?,O | entity=S, role='S' | O üzerinde filtreleme | Bölüm taraması + filtre |
|
||||
| 11 | ?,?,P,O | entity=O, role='O', p=P | — | **Mükemmel önek** |
|
||||
| 12 | D,?,?,? | entity=D, role='G' | — | **Mükemmel önek** |
|
||||
| 13 | ?,S,?,? | entity=S, role='S' | — | **Mükemmel önek** |
|
||||
| 14 | ?,?,P,? | entity=P, role='P' | — | **Mükemmel önek** |
|
||||
| 15 | ?,?,?,O | entity=O, role='O' | — | **Mükemmel önek** |
|
||||
| 16 | ?,?,?,? | — | Tam tarama | Yalnızca keşif |
|
||||
|
||||
**Önemli sonuç**: 15 önemsiz desenden 7'si mükemmel kümeleme önek eşleşmesidir. Kalan 8 tanesi, bölüm içi filtrelemeyle birlikte tek bölümlü okumalardır. En az bir bilinen öğeye sahip her sorgu, bir bölüm anahtarını etkiler.
|
||||
|
||||
Desen 16 (?,?,?,?) pratikte oluşmaz, çünkü koleksiyon her zaman belirtilir ve bu da onu desen 12'ye indirger.
|
||||
|
||||
### Yaygın Sorgu Örnekleri
|
||||
|
||||
**Bir varlık hakkında her şey:**
|
||||
|
||||
```sql
|
||||
SELECT * FROM quads_by_entity
|
||||
WHERE collection = 'tenant1' AND entity = 'https://example.org/Alice';
|
||||
```
|
||||
|
||||
**Bir varlık için tüm dış ilişkiler:**
|
||||
|
||||
```sql
|
||||
SELECT * FROM quads_by_entity
|
||||
WHERE collection = 'tenant1' AND entity = 'https://example.org/Alice'
|
||||
AND role = 'S';
|
||||
```
|
||||
|
||||
**Bir varlık için özel koşul:**
|
||||
|
||||
```sql
|
||||
SELECT * FROM quads_by_entity
|
||||
WHERE collection = 'tenant1' AND entity = 'https://example.org/Alice'
|
||||
AND role = 'S' AND p = 'https://example.org/knows';
|
||||
```
|
||||
|
||||
**Bir varlık için etiket (belirli bir dil):**
|
||||
|
||||
```sql
|
||||
SELECT * FROM quads_by_entity
|
||||
WHERE collection = 'tenant1' AND entity = 'https://example.org/Alice'
|
||||
AND role = 'S' AND p = 'http://www.w3.org/2000/01/rdf-schema#label'
|
||||
AND otype = 'L';
|
||||
```
|
||||
|
||||
Gerekirse, `lang = 'en'` uygulamasının tarafında filtreleme yapın.
|
||||
|
||||
**Sadece URI değerine sahip ilişkiler (varlıklar arası bağlantılar):**
|
||||
|
||||
```sql
|
||||
SELECT * FROM quads_by_entity
|
||||
WHERE collection = 'tenant1' AND entity = 'https://example.org/Alice'
|
||||
AND role = 'S' AND p = 'https://example.org/knows' AND otype = 'U';
|
||||
```
|
||||
|
||||
**Ters sorgulama — bu varlığa neyin işaret ettiği:**
|
||||
|
||||
```sql
|
||||
SELECT * FROM quads_by_entity
|
||||
WHERE collection = 'tenant1' AND entity = 'https://example.org/Bob'
|
||||
AND role = 'O';
|
||||
```
|
||||
|
||||
## Etiket Çözümleme ve Önbellek Isıtma
|
||||
|
||||
Varlık odaklı modelin en önemli avantajlarından biri, **etiket çözümlemenin ücretsiz bir yan etki olmasıdır**.
|
||||
|
||||
Geleneksel çok tablolu modelde, etiketleri almak ayrı sorgu istekleri gerektirir: üçlüleri alın, sonuçlardaki varlık URI'larını belirleyin ve ardından her biri için `rdfs:label` alın. Bu N+1 deseni maliyetlidir.
|
||||
|
||||
Varlık odaklı modelde, bir varlığı sorgulamak, etiketleri, türleri ve diğer özellikleri de içeren **tüm** dörtlülerini döndürür. Uygulama sorgu sonuçlarını önbelleğe aldığında, etiketler herhangi bir şey onlardan istekte bulunmadan önce önceden ısıtılır.
|
||||
|
||||
İki kullanım rejimi, bunun pratikte iyi çalıştığını doğrulamaktadır:
|
||||
|
||||
**Kullanıcı arayüzüne yönelik sorgular**: doğal olarak küçük sonuç kümeleri, etiketler önemlidir. Varlık okumaları önbelleği önceden ısıtır.
|
||||
**AI/toplu sorgular**: büyük sonuç kümeleri ve sıkı sınırlar. Etiketler ya gereksizdir ya da önceden önbelleğe alınmış olan varlıkların yalnızca seçilmiş bir alt kümesi için gereklidir.
|
||||
|
||||
Çok büyük sonuç kümeleri (örneğin, 30.000 varlık) için etiketleri çözme konusundaki teorik endişe, hiçbir insan veya yapay zeka tüketicisinin o kadar çok etiketi faydalı bir şekilde işlemediği pratik gözlemiyle giderilir. Uygulama düzeyindeki sorgu sınırları, önbellek üzerindeki baskının yönetilebilir kalmasını sağlar.
|
||||
|
||||
## Geniş Bölümler ve Somutlaştırma
|
||||
|
||||
Somutlaştırma (RDF-star tarzı, ifadeler hakkında ifadeler), kaynak belge gibi merkez varlıkları oluşturur; bu belge, çıkarılan binlerce olguyu destekler. Bu, geniş bölümlere yol açabilir.
|
||||
|
||||
Hafifletici faktörler:
|
||||
|
||||
**Uygulama düzeyindeki sorgu sınırları**: tüm GraphRAG ve kullanıcı arayüzüne yönelik sorgular, geniş bölümlerin sıcak okuma yolunda asla tamamen taranmamasını sağlayan sıkı sınırlar uygular.
|
||||
**Cassandra, kısmi okumaları verimli bir şekilde işler**: erken durdurma ile bir küme sütunu taraması, büyük bölümlerde bile hızlıdır.
|
||||
**Koleksiyon silme** (sadece tüm bölümleri geçebilecek bir işlem), kabul edilebilir bir arka plan işlemidir.
|
||||
|
||||
## Koleksiyon Silme
|
||||
|
||||
API çağrısı tarafından tetiklenir, arka planda çalışır (eventually consistent).
|
||||
|
||||
1. Hedef koleksiyon için `quads_by_collection`'ı okuyun ve tüm dörtlüleri alın.
|
||||
2. Dörtlülerden benzersiz varlıkları çıkarın (s, p, o, d değerleri).
|
||||
3. Her benzersiz varlık için, `quads_by_entity`'dan ilgili bölümü silin.
|
||||
4. `quads_by_collection`'dan satırları silin.
|
||||
|
||||
`quads_by_collection` tablosu, tüm varlık bölümlerini tam tablo taraması olmadan bulmak için gereken dizini sağlar. Bölüm düzeyindeki silmeler verimlidir çünkü `(collection, entity)` bölüm anahtarıdır.
|
||||
|
||||
## Çok Tablolu Modelden Geçiş Yolu
|
||||
|
||||
Varlık odaklı model, geçiş sırasında mevcut çok tablolu modelle birlikte var olabilir:
|
||||
|
||||
1. `quads_by_entity` ve `quads_by_collection` tablolarını mevcut tablolara ek olarak dağıtın.
|
||||
2. Yeni dörtlüleri hem eski hem de yeni tablolara çift yazın.
|
||||
3. Mevcut verileri yeni tablolara geri yükleyin.
|
||||
4. Okuma yollarını bir sorgu deseni bir seferinde geçirin.
|
||||
5. Tüm okumalar geçirildikten sonra eski tabloları devre dışı bırakın.
|
||||
|
||||
## Özet
|
||||
|
||||
| Yön | Geleneksel (6 tablo) | Varlık odaklı (2 tablo) |
|
||||
|---|---|---|
|
||||
| Tablolar | 7+ | 2 |
|
||||
| Dörtlü başına yazma | 6+ | 5 (4 veri + 1 manifest) |
|
||||
| Etiket çözümleme | Ayrı sorgu istekleri | Önbellek ısıtma yoluyla ücretsiz |
|
||||
| Sorgu desenleri | 6 tabloda 16 | 1 tabloda 16 |
|
||||
| Şema karmaşıklığı | Yüksek | Düşük |
|
||||
| İşletimsel yük | Ayarlanması/onarılması gereken 6 tablo | 1 veri tablosu |
|
||||
| Somutlaştırma desteği | Ek karmaşıklık | Doğal uyum |
|
||||
| Nesne türü filtreleme | Kullanılamaz | Yerel (o tür kümeleme yoluyla) |
|
||||
ÇIKTI SÖZLEŞMESİ (tam olarak aşağıdaki formatı takip etmelidir):
|
||||
228
docs/tech-specs/tr/explainability-cli.tr.md
Normal file
228
docs/tech-specs/tr/explainability-cli.tr.md
Normal file
|
|
@ -0,0 +1,228 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Açıklanabilirlik CLI Teknik Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Açıklanabilirlik CLI 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.
|
||||
|
||||
## Durum
|
||||
|
||||
Taslak
|
||||
|
||||
## Genel Bakış
|
||||
|
||||
Bu özellik, TrustGraph'ta açıklanabilirlik verilerini hata ayıklamak ve incelemek için kullanılan CLI araçlarını tanımlar. Bu araçlar, kullanıcıların cevapların nasıl elde edildiğini izlemesini ve kenarlardan kaynak belgelere kadar olan köken zincirini hata ayıklamasını sağlar.
|
||||
|
||||
Üç CLI aracı:
|
||||
|
||||
1. **`tg-show-document-hierarchy`** - Belge → sayfa → parça → kenar hiyerarşisini gösterir
|
||||
2. **`tg-list-explain-traces`** - Tüm GraphRAG oturumlarını sorularla birlikte listeler
|
||||
3. **`tg-show-explain-trace`** - Bir oturum için tam açıklanabilirlik izini gösterir
|
||||
|
||||
## Hedefler
|
||||
|
||||
**Hata Ayıklama**: Geliştiricilerin belge işleme sonuçlarını incelemesini sağlar
|
||||
**Denetlenebilirlik**: Herhangi bir çıkarılan gerçeği kaynak belgesine kadar izleme
|
||||
**Şeffaflık**: GraphRAG'ın bir cevabı tam olarak nasıl elde ettiğini gösterme
|
||||
**Kullanılabilirlik**: Akıllı varsayılanlarla basit bir CLI arayüzü
|
||||
|
||||
## Arka Plan
|
||||
|
||||
TrustGraph'un iki köken sistemi vardır:
|
||||
|
||||
1. **Çıkarma zamanı kökeni** (bkz. `extraction-time-provenance.md`): Yükleme sırasında belge → sayfa → parça → kenar ilişkilerini kaydeder. `urn:graph:source` adlı grafte saklanır ve `prov:wasDerivedFrom` kullanılarak oluşturulur.
|
||||
|
||||
2. **Sorgu zamanı açıklanabilirliği** (bkz. `query-time-explainability.md`): GraphRAG sorguları sırasında soru → keşif → odak → sentez zincirini kaydeder. `urn:graph:retrieval` adlı grafte saklanır.
|
||||
|
||||
Mevcut sınırlamalar:
|
||||
İşleme sonrası belge hiyerarşisini görselleştirmenin kolay bir yolu yok
|
||||
Açıklanabilirlik verilerini görmek için üçlüleri manuel olarak sorgulamak gerekiyor
|
||||
Bir GraphRAG oturumunun konsolide bir görünümü yok
|
||||
|
||||
## Teknik Tasarım
|
||||
|
||||
### Araç 1: tg-show-document-hierarchy
|
||||
|
||||
**Amaç**: Bir belge kimliği verildiğinde, türetilen tüm varlıkları gezinerek ve görüntüleyerek.
|
||||
|
||||
**Kullanım**:
|
||||
```bash
|
||||
tg-show-document-hierarchy "urn:trustgraph:doc:abc123"
|
||||
tg-show-document-hierarchy --show-content --max-content 500 "urn:trustgraph:doc:abc123"
|
||||
```
|
||||
|
||||
**Argümanlar**:
|
||||
| Arg | Açıklama |
|
||||
|-----|-------------|
|
||||
| `document_id` | Belge URI'si (konumsal) |
|
||||
| `-u/--api-url` | Ağ geçidi URL'si (varsayılan: `$TRUSTGRAPH_URL`) |
|
||||
| `-t/--token` | Kimlik doğrulama belirteci (varsayılan: `$TRUSTGRAPH_TOKEN`) |
|
||||
| `-U/--user` | Kullanıcı Kimliği (varsayılan: `trustgraph`) |
|
||||
| `-C/--collection` | Koleksiyon (varsayılan: `default`) |
|
||||
| `--show-content` | Blob/belge içeriğini dahil et |
|
||||
| `--max-content` | Blob başına maksimum karakter sayısı (varsayılan: 200) |
|
||||
| `--format` | Çıktı: `tree` (varsayılan), `json` |
|
||||
|
||||
**Uygulama**:
|
||||
1. Üçlüleri sorgula: `?child prov:wasDerivedFrom <document_id>` içinde `urn:graph:source`
|
||||
2. Her sonucun çocuklarını yinelemeli olarak sorgula
|
||||
3. Ağaç yapısını oluştur: Belge → Sayfalar → Parçalar
|
||||
4. Eğer `--show-content` ise, içeriği kütüphaneci API'sinden al
|
||||
5. Girintili bir ağaç veya JSON olarak göster
|
||||
|
||||
**Çıktı Örneği**:
|
||||
```
|
||||
Document: urn:trustgraph:doc:abc123
|
||||
Title: "Sample PDF"
|
||||
Type: application/pdf
|
||||
|
||||
└── Page 1: urn:trustgraph:doc:abc123/p1
|
||||
├── Chunk 0: urn:trustgraph:doc:abc123/p1/c0
|
||||
│ Content: "The quick brown fox..." [truncated]
|
||||
└── Chunk 1: urn:trustgraph:doc:abc123/p1/c1
|
||||
Content: "Machine learning is..." [truncated]
|
||||
```
|
||||
|
||||
### Araç 2: tg-list-explain-traces
|
||||
|
||||
**Amaç**: Bir koleksiyondaki tüm GraphRAG oturumlarını (soruları) listelemek.
|
||||
|
||||
**Kullanım**:
|
||||
```bash
|
||||
tg-list-explain-traces
|
||||
tg-list-explain-traces --limit 20 --format json
|
||||
```
|
||||
|
||||
**Argümanlar**:
|
||||
| Arg | Açıklama |
|
||||
|-----|-------------|
|
||||
| `-u/--api-url` | Ağ geçidi URL'si |
|
||||
| `-t/--token` | Yetkilendirme belirteci |
|
||||
| `-U/--user` | Kullanıcı Kimliği |
|
||||
| `-C/--collection` | Koleksiyon |
|
||||
| `--limit` | Maksimum sonuç sayısı (varsayılan: 50) |
|
||||
| `--format` | Çıktı: `table` (varsayılan), `json` |
|
||||
|
||||
**Uygulama**:
|
||||
1. Sorgu: `?session tg:query ?text` içinde `urn:graph:retrieval`
|
||||
2. Sorgu zaman damgaları: `?session prov:startedAtTime ?time`
|
||||
3. Tablo olarak göster
|
||||
|
||||
**Çıktı Örneği**:
|
||||
```
|
||||
Session ID | Question | Time
|
||||
----------------------------------------------|--------------------------------|---------------------
|
||||
urn:trustgraph:question:abc123 | What was the War on Terror? | 2024-01-15 10:30:00
|
||||
urn:trustgraph:question:def456 | Who founded OpenAI? | 2024-01-15 09:15:00
|
||||
```
|
||||
|
||||
### Araç 3: tg-show-explain-trace
|
||||
|
||||
**Amaç**: Bir GraphRAG oturumu için tam açıklanabilirlik zincirini gösterir.
|
||||
|
||||
**Kullanım**:
|
||||
```bash
|
||||
tg-show-explain-trace "urn:trustgraph:question:abc123"
|
||||
tg-show-explain-trace --max-answer 1000 --show-provenance "urn:trustgraph:question:abc123"
|
||||
```
|
||||
|
||||
**Argümanlar**:
|
||||
| Arg | Açıklama |
|
||||
|-----|-------------|
|
||||
| `question_id` | Soru URI'si (konumsal) |
|
||||
| `-u/--api-url` | Ağ geçidi URL'si |
|
||||
| `-t/--token` | Kimlik doğrulama belirteci |
|
||||
| `-U/--user` | Kullanıcı Kimliği |
|
||||
| `-C/--collection` | Koleksiyon |
|
||||
| `--max-answer` | Cevap için maksimum karakter sayısı (varsayılan: 500) |
|
||||
| `--show-provenance` | Kaynak belgelere kadar kenarları izle |
|
||||
| `--format` | Çıktı: `text` (varsayılan), `json` |
|
||||
|
||||
**Uygulama**:
|
||||
1. `tg:query` özniteliğinden soru metnini al.
|
||||
2. Keşfi bul: `?exp prov:wasGeneratedBy <question_id>`
|
||||
3. Odak noktasını bul: `?focus prov:wasDerivedFrom <exploration_id>`
|
||||
4. Seçilen kenarları al: `<focus_id> tg:selectedEdge ?edge`
|
||||
5. Her kenar için, `tg:edge` (alıntılanmış üçlü) ve `tg:reasoning`'i al.
|
||||
6. Sentezi bul: `?synth prov:wasDerivedFrom <focus_id>`
|
||||
7. Cevabı `tg:document` aracılığıyla kütüphaneciden al.
|
||||
8. Eğer `--show-provenance` ise, kaynak belgelere kadar kenarları izle.
|
||||
|
||||
**Çıktı Örneği**:
|
||||
```
|
||||
=== GraphRAG Session: urn:trustgraph:question:abc123 ===
|
||||
|
||||
Question: What was the War on Terror?
|
||||
Time: 2024-01-15 10:30:00
|
||||
|
||||
--- Exploration ---
|
||||
Retrieved 50 edges from knowledge graph
|
||||
|
||||
--- Focus (Edge Selection) ---
|
||||
Selected 12 edges:
|
||||
|
||||
1. (War on Terror, definition, "A military campaign...")
|
||||
Reasoning: Directly defines the subject of the query
|
||||
Source: chunk → page 2 → "Beyond the Vigilant State"
|
||||
|
||||
2. (Guantanamo Bay, part_of, War on Terror)
|
||||
Reasoning: Shows key component of the campaign
|
||||
|
||||
--- Synthesis ---
|
||||
Answer:
|
||||
The War on Terror was a military campaign initiated...
|
||||
[truncated at 500 chars]
|
||||
```
|
||||
|
||||
## Oluşturulacak Dosyalar
|
||||
|
||||
| Dosya | Amaç |
|
||||
|------|---------|
|
||||
| `trustgraph-cli/trustgraph/cli/show_document_hierarchy.py` | Araç 1 |
|
||||
| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | Araç 2 |
|
||||
| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | Araç 3 |
|
||||
|
||||
## Değiştirilecek Dosyalar
|
||||
|
||||
| Dosya | Değişiklik |
|
||||
|------|--------|
|
||||
| `trustgraph-cli/setup.py` | console_scripts girişlerini ekle |
|
||||
|
||||
## Uygulama Notları
|
||||
|
||||
1. **İkili içerik güvenliği**: UTF-8 ile çözmeyi deneyin; başarısız olursa `[Binary: {size} bytes]` gösterin.
|
||||
2. **Kısaltma**: `--max-content`/`--max-answer` ile `[truncated]` göstergesine saygı gösterin.
|
||||
3. **Tırnak işaretli üçlüler**: `tg:edge` önekinden RDF-star formatını ayrıştırın.
|
||||
4. **Desenler**: `query_graph.py`'dan mevcut CLI desenlerini izleyin.
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
Tüm sorgular, kullanıcı/koleksiyon sınırlarına saygı gösterir.
|
||||
`--token` veya `$TRUSTGRAPH_TOKEN` aracılığıyla token kimlik doğrulaması desteklenir.
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
Örnek verilerle manuel doğrulama:
|
||||
```bash
|
||||
# Load a test document
|
||||
tg-load-pdf -f test.pdf -c test-collection
|
||||
|
||||
# Verify hierarchy
|
||||
tg-show-document-hierarchy "urn:trustgraph:doc:test"
|
||||
|
||||
# Run a GraphRAG query with explainability
|
||||
tg-invoke-graph-rag --explainable -q "Test question"
|
||||
|
||||
# List and inspect traces
|
||||
tg-list-explain-traces
|
||||
tg-show-explain-trace "urn:trustgraph:question:xxx"
|
||||
```
|
||||
|
||||
## Referanslar
|
||||
|
||||
Sorgu zamanı açıklanabilirlik: `docs/tech-specs/query-time-explainability.md`
|
||||
Çıkarım zamanı köken bilgisi: `docs/tech-specs/extraction-time-provenance.md`
|
||||
Mevcut komut satırı örneği: `trustgraph-cli/trustgraph/cli/invoke_graph_rag.py`
|
||||
355
docs/tech-specs/tr/extraction-flows.tr.md
Normal file
355
docs/tech-specs/tr/extraction-flows.tr.md
Normal file
|
|
@ -0,0 +1,355 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Veri Çıkarma Akışları"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Veri Çıkarma Akışları
|
||||
|
||||
> **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.
|
||||
|
||||
Bu belge, verilerin TrustGraph veri çıkarma işlem hattı üzerinden nasıl aktığını, belge gönderiminden başlayarak bilgi depolarına kaydedilmesine kadar olan süreci açıklamaktadır.
|
||||
|
||||
## Genel Bakış
|
||||
|
||||
```
|
||||
┌──────────┐ ┌─────────────┐ ┌─────────┐ ┌────────────────────┐
|
||||
│ Librarian│────▶│ PDF Decoder │────▶│ Chunker │────▶│ Knowledge │
|
||||
│ │ │ (PDF only) │ │ │ │ Extraction │
|
||||
│ │────────────────────────▶│ │ │ │
|
||||
└──────────┘ └─────────────┘ └─────────┘ └────────────────────┘
|
||||
│ │
|
||||
│ ├──▶ Triples
|
||||
│ ├──▶ Entity Contexts
|
||||
│ └──▶ Rows
|
||||
│
|
||||
└──▶ Document Embeddings
|
||||
```
|
||||
|
||||
## İçerik Depolama
|
||||
|
||||
### Blob Depolama (S3/Minio)
|
||||
|
||||
Belge içeriği, S3 uyumlu blob depolama alanında saklanır:
|
||||
Yol formatı: `doc/{object_id}`, burada object_id bir UUID'dir.
|
||||
Tüm belge türleri burada saklanır: kaynak belgeler, sayfalar, parçalar.
|
||||
|
||||
### Metaveri Depolama (Cassandra)
|
||||
|
||||
Cassandra'da saklanan belge metaverileri şunları içerir:
|
||||
Belge ID'si, başlık, tür (MIME türü).
|
||||
Blob depolama alanına `object_id` referansı.
|
||||
Alt belgelere (sayfalar, parçalar) ait `parent_id`.
|
||||
`document_type`: "kaynak", "sayfa", "parça", "cevap".
|
||||
|
||||
### İçerik vs. Akış Eşiği
|
||||
|
||||
İçerik iletimi, boyuta dayalı bir strateji kullanır:
|
||||
**< 2MB**: İçerik, mesaj içinde (base64 ile kodlanmış) yer alır.
|
||||
**≥ 2MB**: Yalnızca `document_id` gönderilir; işlemci, kütüphaneci API'si aracılığıyla içeriği alır.
|
||||
|
||||
## 1. Aşama: Belge Gönderimi (Kütüphaneci)
|
||||
|
||||
### Giriş Noktası
|
||||
|
||||
Belgeler, kütüphanecinin `add-document` işlemi aracılığıyla sisteme girer:
|
||||
1. İçerik, blob depolama alanına yüklenir.
|
||||
2. Cassandra'da bir metaveri kaydı oluşturulur.
|
||||
3. Belge ID'si döndürülür.
|
||||
|
||||
### Çıkarım Tetikleme
|
||||
|
||||
`add-processing` işlemi, çıkarımı tetikler:
|
||||
`document_id`, `flow` (işlem hattı ID'si) ve `collection` (hedef depolama alanı) belirtir.
|
||||
Kütüphanecinin `load_document()` işlemi, içeriği alır ve akış giriş kuyruğuna yayınlar.
|
||||
|
||||
### Şema: Belge
|
||||
|
||||
```
|
||||
Document
|
||||
├── metadata: Metadata
|
||||
│ ├── id: str # Document identifier
|
||||
│ ├── user: str # Tenant/user ID
|
||||
│ ├── collection: str # Target collection
|
||||
│ └── metadata: list[Triple] # (largely unused, historical)
|
||||
├── data: bytes # PDF content (base64, if inline)
|
||||
└── document_id: str # Librarian reference (if streaming)
|
||||
```
|
||||
|
||||
**Yönlendirme**: `kind` alanına göre:
|
||||
`application/pdf` → `document-load` kuyruğu → PDF Kod Çözücü
|
||||
`text/plain` → `text-load` kuyruğu → Parçalayıcı
|
||||
|
||||
## 2. Aşama: PDF Kod Çözücü
|
||||
|
||||
PDF belgelerini metin sayfalarına dönüştürür.
|
||||
|
||||
### İşlem
|
||||
|
||||
1. İçeriği al (doğrudan `data` veya `document_id` üzerinden kütüphaneciden)
|
||||
2. Sayfaları PyPDF kullanarak çıkar
|
||||
3. Her sayfa için:
|
||||
Kütüphanecide alt belge olarak kaydet (`{doc_id}/p{page_num}`)
|
||||
Kaynak üçlülerini yayınla (sayfa, belgeden türetilmiştir)
|
||||
Parçalayıcıya ilet
|
||||
|
||||
### Şema: TextDocument
|
||||
|
||||
```
|
||||
TextDocument
|
||||
├── metadata: Metadata
|
||||
│ ├── id: str # Page URI (e.g., https://trustgraph.ai/doc/xxx/p1)
|
||||
│ ├── user: str
|
||||
│ ├── collection: str
|
||||
│ └── metadata: list[Triple]
|
||||
├── text: bytes # Page text content (if inline)
|
||||
└── document_id: str # Librarian reference (e.g., "doc123/p1")
|
||||
```
|
||||
|
||||
## 3. Aşama: Parçalayıcı (Chunker)
|
||||
|
||||
Metni, yapılandırılmış boyutta parçalara ayırır.
|
||||
|
||||
### Parametreler (akışa bağımlı olarak yapılandırılabilir)
|
||||
|
||||
`chunk_size`: Karakter cinsinden hedef parça boyutu (varsayılan: 2000)
|
||||
`chunk_overlap`: Parçalar arasındaki örtüşme (varsayılan: 100)
|
||||
|
||||
### İşlem
|
||||
|
||||
1. Metin içeriğini alın (doğrudan veya kütüphaneci aracılığıyla)
|
||||
2. Özyinelemeli karakter ayırıcı kullanarak parçalara ayırın
|
||||
3. Her parça için:
|
||||
Kütüphanecide alt belge olarak kaydedin (`{parent_id}/c{index}`)
|
||||
Kaynak bilgilerini yayınlayın (parça, sayfadan/belgeden türetilmiştir)
|
||||
Çıkarma işleme modüllerine yönlendirin
|
||||
|
||||
### Şema: Parça (Chunk)
|
||||
|
||||
```
|
||||
Chunk
|
||||
├── metadata: Metadata
|
||||
│ ├── id: str # Chunk URI
|
||||
│ ├── user: str
|
||||
│ ├── collection: str
|
||||
│ └── metadata: list[Triple]
|
||||
├── chunk: bytes # Chunk text content
|
||||
└── document_id: str # Librarian chunk ID (e.g., "doc123/p1/c3")
|
||||
```
|
||||
|
||||
### Belge Kimlik Hiyerarşisi
|
||||
|
||||
Alt belgeler, kimlik içinde kendi kökenlerini kodlar:
|
||||
Kaynak: `doc123`
|
||||
Sayfa: `doc123/p5`
|
||||
Sayfadan parça: `doc123/p5/c2`
|
||||
Metinden parça: `doc123/c2`
|
||||
|
||||
## 4. Aşama: Bilgi Çıkarımı
|
||||
|
||||
Kullanılabilir çoklu çıkarma kalıpları, akış yapılandırması tarafından seçilir.
|
||||
|
||||
### Kalıp A: Temel GraphRAG
|
||||
|
||||
İki paralel işlemci:
|
||||
|
||||
**kg-extract-definitions**
|
||||
Giriş: Parça
|
||||
Çıkış: Üçlüler (varlık tanımları), Varlık Bağlamları
|
||||
Çıkarır: varlık etiketleri, tanımlar
|
||||
|
||||
**kg-extract-relationships**
|
||||
Giriş: Parça
|
||||
Çıkış: Üçlüler (ilişkiler), Varlık Bağlamları
|
||||
Çıkarır: özne-yüklem-nesne ilişkileri
|
||||
|
||||
### Kalıp B: Ontoloji Odaklı (kg-extract-ontology)
|
||||
|
||||
Giriş: Parça
|
||||
Çıkış: Üçlüler, Varlık Bağlamları
|
||||
Çıkarımı yönlendirmek için yapılandırılmış bir ontoloji kullanır
|
||||
|
||||
### Kalıp C: Ajan Tabanlı (kg-extract-agent)
|
||||
|
||||
Giriş: Parça
|
||||
Çıkış: Üçlüler, Varlık Bağlamları
|
||||
Çıkarım için ajan çerçevesini kullanır
|
||||
|
||||
### Kalıp D: Satır Çıkarımı (kg-extract-rows)
|
||||
|
||||
Giriş: Parça
|
||||
Çıkış: Satırlar (üçlüler değil, yapılandırılmış veri)
|
||||
Yapılandırılmış kayıtları çıkarmak için şema tanımını kullanır
|
||||
|
||||
### Şema: Üçlüler
|
||||
|
||||
```
|
||||
Triples
|
||||
├── metadata: Metadata
|
||||
│ ├── id: str
|
||||
│ ├── user: str
|
||||
│ ├── collection: str
|
||||
│ └── metadata: list[Triple] # (set to [] by extractors)
|
||||
└── triples: list[Triple]
|
||||
└── Triple
|
||||
├── s: Term # Subject
|
||||
├── p: Term # Predicate
|
||||
├── o: Term # Object
|
||||
└── g: str | None # Named graph
|
||||
```
|
||||
|
||||
### Şema: Varlık Bağlamları
|
||||
|
||||
```
|
||||
EntityContexts
|
||||
├── metadata: Metadata
|
||||
└── entities: list[EntityContext]
|
||||
└── EntityContext
|
||||
├── entity: Term # Entity identifier (IRI)
|
||||
├── context: str # Textual description for embedding
|
||||
└── chunk_id: str # Source chunk ID (provenance)
|
||||
```
|
||||
|
||||
### Şema: Satırlar
|
||||
|
||||
```
|
||||
Rows
|
||||
├── metadata: Metadata
|
||||
├── row_schema: RowSchema
|
||||
│ ├── name: str
|
||||
│ ├── description: str
|
||||
│ └── fields: list[Field]
|
||||
└── rows: list[dict[str, str]] # Extracted records
|
||||
```
|
||||
|
||||
## 5. Aşama: Gömme (Embedding) Oluşturma
|
||||
|
||||
### Grafik Gömme (Graph Embeddings)
|
||||
|
||||
Varlık bağlamlarını vektör gömmelerine dönüştürür.
|
||||
|
||||
**Süreç:**
|
||||
1. Varlık Bağlamlarını Alın
|
||||
2. Bağlam metniyle gömme hizmetini çağırın
|
||||
3. GrafikGömme'leri Çıktılayın (varlık → vektör eşlemesi)
|
||||
|
||||
**Şema: GrafikGömme (GraphEmbeddings)**
|
||||
|
||||
```
|
||||
GraphEmbeddings
|
||||
├── metadata: Metadata
|
||||
└── entities: list[EntityEmbeddings]
|
||||
└── EntityEmbeddings
|
||||
├── entity: Term # Entity identifier
|
||||
├── vector: list[float] # Embedding vector
|
||||
└── chunk_id: str # Source chunk (provenance)
|
||||
```
|
||||
|
||||
### Belge Gömme (Document Embeddings)
|
||||
|
||||
Parça metnini doğrudan vektör gömmelerine dönüştürür.
|
||||
|
||||
**Süreç:**
|
||||
1. Parçayı Al
|
||||
2. Parça metniyle gömme hizmetini çağır
|
||||
3. DocumentEmbeddings çıktısını ver
|
||||
|
||||
**Şema: DocumentEmbeddings**
|
||||
|
||||
```
|
||||
DocumentEmbeddings
|
||||
├── metadata: Metadata
|
||||
└── chunks: list[ChunkEmbeddings]
|
||||
└── ChunkEmbeddings
|
||||
├── chunk_id: str # Chunk identifier
|
||||
└── vector: list[float] # Embedding vector
|
||||
```
|
||||
|
||||
### Satır Gömme (Row Embeddings)
|
||||
|
||||
Satır indeks alanlarını vektör gömmelerine dönüştürür.
|
||||
|
||||
**İşlem:**
|
||||
1. Satırları Al
|
||||
2. Yapılandırılmış indeks alanlarını göm
|
||||
3. Satır vektör deposuna çıktı ver
|
||||
|
||||
## 6. Aşama: Depolama
|
||||
|
||||
### Üçlü Depo (Triple Store)
|
||||
|
||||
Gelen: Üçlüler
|
||||
Depolama: Cassandra (varlık odaklı tablolar)
|
||||
İsimlendirilmiş grafikler, temel bilgiyi köken bilgisinden ayırır:
|
||||
`""` (varsayılan): Temel bilgi gerçekleri
|
||||
`urn:graph:source`: Çıkarma kökeni
|
||||
`urn:graph:retrieval`: Sorgu zamanı açıklanabilirliği
|
||||
|
||||
### Vektör Deposu (Grafik Gömme)
|
||||
|
||||
Gelen: GrafikGömme (GraphEmbeddings)
|
||||
Depolama: Qdrant, Milvus veya Pinecone
|
||||
Dizin: Varlık IRI'si ile
|
||||
Metaveri: Köken için chunk_id
|
||||
|
||||
### Vektör Deposu (Belge Gömme)
|
||||
|
||||
Gelen: BelgeGömme (DocumentEmbeddings)
|
||||
Depolama: Qdrant, Milvus veya Pinecone
|
||||
Dizin: chunk_id ile
|
||||
|
||||
### Satır Deposu (Row Store)
|
||||
|
||||
Gelen: Satırlar
|
||||
Depolama: Cassandra
|
||||
Şema odaklı tablo yapısı
|
||||
|
||||
### Satır Vektör Deposu
|
||||
|
||||
Gelen: Satır gömmeleri
|
||||
Depolama: Vektör Veritabanı
|
||||
Dizin: Satır indeks alanları ile
|
||||
|
||||
## Metaveri Alanı Analizi
|
||||
|
||||
### Aktif Olarak Kullanılan Alanlar
|
||||
|
||||
| Alan | Kullanım |
|
||||
|-------|-------|
|
||||
| `metadata.id` | Belge/parça tanımlayıcı, günlükleme, köken |
|
||||
| `metadata.user` | Çoklu kiracılık, depolama yönlendirme |
|
||||
| `metadata.collection` | Hedef koleksiyon seçimi |
|
||||
| `document_id` | Kütüphaneci referansı, köken bağlantısı |
|
||||
| `chunk_id` | İşlem hattı boyunca köken takibi |
|
||||
|
||||
<<<<<<< HEAD
|
||||
### Potansiyel Olarak Gereksiz Alanlar
|
||||
|
||||
| Alan | Durum |
|
||||
|-------|--------|
|
||||
| `metadata.metadata` | Tüm çıkarıcılar tarafından `[]` olarak ayarlanır; belge düzeyindeki metaveri artık gönderim zamanında kütüphaneci tarafından işlenir |
|
||||
=======
|
||||
### Kaldırılan Alanlar
|
||||
|
||||
| Alan | Durum |
|
||||
|-------|--------|
|
||||
| `metadata.metadata` | `Metadata` sınıfından kaldırıldı. Belge düzeyindeki metaveri üçlüleri artık kütüphaneci tarafından doğrudan üçlü depoya gönderim zamanında gönderilir, çıkarma hattı üzerinden taşınmaz. |
|
||||
>>>>>>> e3bcbf73 (The metadata field (list of triples) in the pipeline Metadata class)
|
||||
|
||||
### Bayt Alanı Modeli
|
||||
|
||||
Tüm içerik alanları (`data`, `text`, `chunk`) `bytes`'tür, ancak tüm işlemciler tarafından hemen UTF-8 dizelerine kod çözülür. İşlemci tarafından ham bayt kullanılmaz.
|
||||
|
||||
## Akış Yapılandırması
|
||||
|
||||
Akışlar harici olarak tanımlanır ve kütüphaneci aracılığıyla yapılandırma hizmetinden sağlanır. Her akış şunları belirtir:
|
||||
|
||||
Giriş kuyrukları (`text-load`, `document-load`)
|
||||
İşlemci zinciri
|
||||
Parametreler (parça boyutu, çıkarma yöntemi, vb.)
|
||||
|
||||
Örnek akış modelleri:
|
||||
`pdf-graphrag`: PDF → Kod Çözücü → Parçalayıcı → Tanımlar + İlişkiler → Gömme
|
||||
`text-graphrag`: Metin → Parçalayıcı → Tanımlar + İlişkiler → Gömme
|
||||
`pdf-ontology`: PDF → Kod Çözücü → Parçalayıcı → Ontoloji Çıkarma → Gömme
|
||||
`text-rows`: Metin → Parçalayıcı → Satır Çıkarma → Satır Deposu
|
||||
275
docs/tech-specs/tr/extraction-provenance-subgraph.tr.md
Normal file
275
docs/tech-specs/tr/extraction-provenance-subgraph.tr.md
Normal file
|
|
@ -0,0 +1,275 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Çıkarma Kaynağı: Alt Grafik Modeli"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Çıkarma Kaynağı: Alt Grafik Modeli
|
||||
|
||||
> **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.
|
||||
|
||||
## Sorun
|
||||
|
||||
Çıkarma zamanı köken bilgisi şu anda her
|
||||
çıkarılan üçlü için tam bir somutlaştırma oluşturur: benzersiz bir `stmt_uri`, `activity_uri` ve ilgili
|
||||
PROV-O meta verileri, her bir bilgi parçası için. Bir parça işlenirken
|
||||
<<<<<<< HEAD
|
||||
ve bu parça 20 ilişki üretiyorsa, yaklaşık 220 köken bilgisi üçlüsü, bunun üzerine
|
||||
yaklaşık 20 bilgi üçlüsü bulunur; bu da yaklaşık 10:1'lik bir ek yük demektir.
|
||||
|
||||
Bu hem pahalıdır (depolama, indeksleme, iletim) hem de anlamsal olarak
|
||||
yanlıştır. Her bir parça, tek bir LLM çağrısı ile işlenir ve bu çağrı,
|
||||
tüm üçlemelerini tek bir işlemde üretir. Mevcut üçleme bazlı model,
|
||||
20 bağımsız çıkarma olayının yanılsamasını yaratarak bunu gizler.
|
||||
=======
|
||||
ve bu parça 20 ilişki üretiyorsa, yaklaşık 220 köken bilgisi üçlüsü,
|
||||
yaklaşık 20 bilgi üçlüsünün üzerine eklenir; bu da yaklaşık 10:1'lik bir ek yük demektir.
|
||||
|
||||
Bu hem pahalıdır (depolama, indeksleme, iletim) hem de anlamsal olarak
|
||||
yanlıştır. Her bir parça, tek bir LLM çağrısı ile işlenir ve bu çağrı,
|
||||
tüm üçlülerini tek bir işlemde üretir. Mevcut üçlü bazlı model,
|
||||
bu durumu 20 bağımsız çıkarma olayının yanılsamasını yaratarak gizler.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
|
||||
Ayrıca, dört çıkarma işlemcisinden ikisi (kg-extract-ontology,
|
||||
kg-extract-agent), hiçbir kaynak bilgisini içermemektedir, bu da denetim
|
||||
izinde boşluklara neden olmaktadır.
|
||||
|
||||
## Çözüm
|
||||
|
||||
<<<<<<< HEAD
|
||||
Her üçlü için yapılan somutlaştırmayı, **bir alt grafik modeli** ile değiştirin: her bir parça çıkarımı için bir köken kaydı, bu parçadan üretilen tüm üçlüler arasında paylaşılan.
|
||||
|
||||
=======
|
||||
Her üçlü için yapılan somutlaştırmayı, **alt grafik modeli** ile değiştirin: bir veri kaynağı
|
||||
kaydı, o parçadan üretilen tüm üçlüler için ortak kullanılan bir parça çıkarımı için.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
|
||||
### Terminoloji Değişikliği
|
||||
|
||||
| Eski | Yeni |
|
||||
|-----|-----|
|
||||
| `stmt_uri` (`https://trustgraph.ai/stmt/{uuid}`) | `subgraph_uri` (`https://trustgraph.ai/subgraph/{uuid}`) |
|
||||
| `statement_uri()` | `subgraph_uri()` |
|
||||
<<<<<<< HEAD
|
||||
| `tg:reifies` (1:1, eşlik) | `tg:contains` (1:çok, içerik) |
|
||||
|
||||
### Hedef Yapı
|
||||
|
||||
Tüm köken bilgisi üçlüleri, `urn:graph:source` adlı grafikte yer alır.
|
||||
=======
|
||||
| `tg:reifies` (1:1, özdeşlik) | `tg:contains` (1:çok, içerik) |
|
||||
|
||||
### Hedef Yapı
|
||||
|
||||
Tüm veri kaynağı üçlüleri, `urn:graph:source` adlı grafiğe yerleştirilir.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
```
|
||||
# Subgraph contains each extracted triple (RDF-star quoted triples)
|
||||
<subgraph> tg:contains <<s1 p1 o1>> .
|
||||
<subgraph> tg:contains <<s2 p2 o2>> .
|
||||
<subgraph> tg:contains <<s3 p3 o3>> .
|
||||
|
||||
# Derivation from source chunk
|
||||
<subgraph> prov:wasDerivedFrom <chunk_uri> .
|
||||
<subgraph> prov:wasGeneratedBy <activity> .
|
||||
|
||||
# Activity: one per chunk extraction
|
||||
<activity> rdf:type prov:Activity .
|
||||
<activity> rdfs:label "{component_name} extraction" .
|
||||
<activity> prov:used <chunk_uri> .
|
||||
<activity> prov:wasAssociatedWith <agent> .
|
||||
<activity> prov:startedAtTime "2026-03-13T10:00:00Z" .
|
||||
<activity> tg:componentVersion "0.25.0" .
|
||||
<activity> tg:llmModel "gpt-4" . # if available
|
||||
<activity> tg:ontology <ontology_uri> . # if available
|
||||
|
||||
# Agent: stable per component
|
||||
<agent> rdf:type prov:Agent .
|
||||
<agent> rdfs:label "{component_name}" .
|
||||
```
|
||||
|
||||
### Hacim Karşılaştırması
|
||||
|
||||
N sayıda çıkarılan üçlü üreten bir parça için:
|
||||
|
||||
| | Eski (üçlü başına) | Yeni (alt grafik) |
|
||||
|---|---|---|
|
||||
| `tg:contains` / `tg:reifies` | N | N |
|
||||
| Aktivite üçlüleri | ~9 x N | ~9 |
|
||||
| Ajan üçlüleri | 2 x N | 2 |
|
||||
| İfade/alt grafik meta verileri | 2 x N | 2 |
|
||||
<<<<<<< HEAD
|
||||
| **Toplam kaynak üçlüleri** | **~13N** | **N + 13** |
|
||||
=======
|
||||
| **Toplam köken üçlüleri** | **~13N** | **N + 13** |
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
| **Örnek (N=20)** | **~260** | **33** |
|
||||
|
||||
## Kapsam
|
||||
|
||||
<<<<<<< HEAD
|
||||
### Güncellenecek İşlemciler (mevcut kaynak, üçlü başına)
|
||||
=======
|
||||
### Güncellenecek İşlemciler (mevcut köken, üçlü başına)
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**kg-extract-definitions**
|
||||
(`trustgraph-flow/trustgraph/extract/kg/definitions/extract.py`)
|
||||
|
||||
Şu anda her bir tanım döngüsü içinde `statement_uri()` + `triple_provenance_triples()`'i çağırıyor.
|
||||
|
||||
|
||||
Değişiklikler:
|
||||
`subgraph_uri()` ve `activity_uri()` oluşturmayı döngüden önce taşıyın
|
||||
`tg:contains` üçlülerini döngü içinde toplayın
|
||||
Paylaşılan aktivite/ajan/türetme bloğunu döngüden sonra bir kez yayınlayın
|
||||
|
||||
**kg-extract-relationships**
|
||||
(`trustgraph-flow/trustgraph/extract/kg/relationships/extract.py`)
|
||||
|
||||
Tanımlarla aynı desen. Aynı değişiklikler.
|
||||
|
||||
<<<<<<< HEAD
|
||||
### Kaynak Eklenmesi Gereken İşlemciler (şu anda eksik)
|
||||
=======
|
||||
### Köken Eklenmesi Gereken İşlemciler (şu anda eksik)
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**kg-extract-ontology**
|
||||
(`trustgraph-flow/trustgraph/extract/kg/ontology/extract.py`)
|
||||
|
||||
<<<<<<< HEAD
|
||||
Şu anda, herhangi bir kaynak bilgisi olmadan üçlüler oluşturuluyor. Alt grafik kaynak bilgisini ekleyin.
|
||||
=======
|
||||
Şu anda, herhangi bir köken bilgisi olmadan üçlüler oluşturuluyor. Alt grafik köken bilgisini ekleyin.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Aynı kalıbı kullanarak: her parça için bir alt grafik, her çıkarılan üçlü için `tg:contains`.
|
||||
|
||||
|
||||
**kg-extract-agent**
|
||||
(`trustgraph-flow/trustgraph/extract/kg/agent/extract.py`)
|
||||
|
||||
<<<<<<< HEAD
|
||||
Şu anda, herhangi bir kaynak bilgisi olmadan üçlüler oluşturuluyor. Alt grafik kaynak bilgisini aynı kalıbı kullanarak ekleyin.
|
||||
|
||||
|
||||
### Paylaşılan Kaynak Bilgisi Kütüphanesi Değişiklikleri
|
||||
=======
|
||||
Şu anda, herhangi bir köken bilgisi olmadan üçlüler oluşturuluyor. Alt grafik köken bilgisini aynı kalıbı kullanarak ekleyin.
|
||||
|
||||
|
||||
### Paylaşılan Köken Bilgisi Kütüphanesi Değişiklikleri
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**`trustgraph-base/trustgraph/provenance/triples.py`**
|
||||
|
||||
`triple_provenance_triples()`'ı `subgraph_provenance_triples()` ile değiştirin.
|
||||
Yeni fonksiyon, tek bir üçlü yerine çıkarılan üçlülerin bir listesini kabul ediyor.
|
||||
<<<<<<< HEAD
|
||||
Her üçlü için bir `tg:contains` oluşturuyor, paylaşılan etkinlik/ajan bloğu.
|
||||
=======
|
||||
Her üçlü için bir `tg:contains` oluşturuyor, paylaşılan aktivite/ajan bloğu.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Eski `triple_provenance_triples()`'ı kaldırın.
|
||||
|
||||
**`trustgraph-base/trustgraph/provenance/uris.py`**
|
||||
|
||||
`statement_uri()`'ı `subgraph_uri()` ile değiştirin.
|
||||
|
||||
**`trustgraph-base/trustgraph/provenance/namespaces.py`**
|
||||
|
||||
`TG_REIFIES`'ı `TG_CONTAINS` ile değiştirin.
|
||||
|
||||
<<<<<<< HEAD
|
||||
### Kapsam Dışında
|
||||
=======
|
||||
### Kapsam Dışı
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**kg-extract-topics**: eski tip işlemci, şu anda standart akışlarda kullanılmıyor.
|
||||
**kg-extract-rows**: satırlar üretiyor, üçlüler değil, farklı bir köken modeline sahip.
|
||||
**Çalışma zamanı köken bilgisi** (⟦CODE_0⟧): ayrı bir konu.
|
||||
model
|
||||
<<<<<<< HEAD
|
||||
**Çalışma zamanı veri kaynağı bilgisi** (`urn:graph:retrieval`): ayrı bir konu,
|
||||
zaten farklı bir kalıp kullanıyor (soru/keşif/odaklanma/sentez).
|
||||
**Belge/sayfa/parça kaynağı** (PDF çözücü, parçalayıcı): zaten kullanılıyor.
|
||||
`derived_entity_triples()` ki bu, her bir varlık için, her bir üçlü için değil; yani bir sorun yok.
|
||||
gereksiz veri sorunu yok.
|
||||
=======
|
||||
**Çalışma zamanı köken bilgisi** (`urn:graph:retrieval`): ayrı bir konu,
|
||||
zaten farklı bir kalıp kullanıyor (soru/keşif/odaklanma/sentez).
|
||||
**Belge/sayfa/parça kaynağı** (PDF çözücü, parçalayıcı): zaten kullanılıyor.
|
||||
`derived_entity_triples()` ki bu, her bir varlık için, her bir üçlü için değil; yani hayır.
|
||||
tekrar sorun yok.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Uygulama Notları
|
||||
|
||||
### İşlemci Döngüsü Yeniden Yapılandırması
|
||||
|
||||
Önce (her üçlü için, ilişkilerde):
|
||||
```python
|
||||
for rel in rels:
|
||||
# ... build relationship_triple ...
|
||||
stmt_uri = statement_uri()
|
||||
prov_triples = triple_provenance_triples(
|
||||
stmt_uri=stmt_uri,
|
||||
extracted_triple=relationship_triple,
|
||||
...
|
||||
)
|
||||
triples.extend(set_graph(prov_triples, GRAPH_SOURCE))
|
||||
```
|
||||
|
||||
(Alt grafik):
|
||||
```python
|
||||
sg_uri = subgraph_uri()
|
||||
|
||||
for rel in rels:
|
||||
# ... build relationship_triple ...
|
||||
extracted_triples.append(relationship_triple)
|
||||
|
||||
prov_triples = subgraph_provenance_triples(
|
||||
subgraph_uri=sg_uri,
|
||||
extracted_triples=extracted_triples,
|
||||
chunk_uri=chunk_uri,
|
||||
component_name=default_ident,
|
||||
component_version=COMPONENT_VERSION,
|
||||
llm_model=llm_model,
|
||||
ontology_uri=ontology_uri,
|
||||
)
|
||||
triples.extend(set_graph(prov_triples, GRAPH_SOURCE))
|
||||
```
|
||||
|
||||
### Yeni Yardımcı İmza
|
||||
|
||||
```python
|
||||
def subgraph_provenance_triples(
|
||||
subgraph_uri: str,
|
||||
extracted_triples: List[Triple],
|
||||
chunk_uri: str,
|
||||
component_name: str,
|
||||
component_version: str,
|
||||
llm_model: Optional[str] = None,
|
||||
ontology_uri: Optional[str] = None,
|
||||
timestamp: Optional[str] = None,
|
||||
) -> List[Triple]:
|
||||
"""
|
||||
Build provenance triples for a subgraph of extracted knowledge.
|
||||
|
||||
Creates:
|
||||
- tg:contains link for each extracted triple (RDF-star quoted)
|
||||
- One prov:wasDerivedFrom link to source chunk
|
||||
- One activity with agent metadata
|
||||
"""
|
||||
```
|
||||
|
||||
### Önemli Değişiklik
|
||||
|
||||
Bu, köken modeli için önemli bir değişikliktir. Köken henüz yayınlanmadığı için, herhangi bir geçiş işlemine gerek yoktur. Eski ⟦CODE_0⟧ /
|
||||
`tg:reifies` kodu tamamen kaldırılabilir.
|
||||
`statement_uri` kodu tamamen kaldırılabilir.
|
||||
797
docs/tech-specs/tr/extraction-time-provenance.tr.md
Normal file
797
docs/tech-specs/tr/extraction-time-provenance.tr.md
Normal file
|
|
@ -0,0 +1,797 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Çıkarma Zamanı Köken Bilgisi: Kaynak Katmanı"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Çıkarma Zamanı Köken Bilgisi: Kaynak Katmanı
|
||||
|
||||
> **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ış
|
||||
|
||||
<<<<<<< HEAD
|
||||
Bu belge, gelecekteki özelliklendirme çalışmaları için çıkarma zamanı köken bilgisi üzerine notları içermektedir. Çıkarma zamanı köken bilgisi kayıtları, verilerin başlangıçta nereden geldiğini, nasıl çıkarıldığını ve dönüştürüldüğünü gösteren "kaynak katmanını" kaydeder.
|
||||
|
||||
Bu, ajan muhakemesini kaydeden sorgu zamanı köken bilgisinden (bkz. `query-time-provenance.md`) farklıdır.
|
||||
=======
|
||||
Bu belge, gelecekteki özellik tanımlama çalışmaları için çıkarma zamanı köken bilgisi üzerine notları içermektedir. Çıkarma zamanı köken bilgisi kayıtları, verilerin başlangıçta nereden geldiğini, nasıl çıkarıldığını ve dönüştürüldüğünü gösteren "kaynak katmanını" kaydeder.
|
||||
|
||||
Bu, ajan muhakemesini kaydeden sorgu zamanı köken bilgisinden (`query-time-provenance.md`'a bakın) farklıdır.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Problem Tanımı
|
||||
|
||||
### Mevcut Uygulama
|
||||
|
||||
Şu anda köken bilgisi aşağıdaki şekilde çalışmaktadır:
|
||||
Belge meta verileri, bilgi grafiğinde RDF üçlüleri olarak saklanır.
|
||||
Bir belge kimliği, meta verileri belgeyle ilişkilendirir, böylece belge grafikte bir düğüm olarak görünür.
|
||||
Belgelerden kenarlar (ilişkiler/gerçekler) çıkarıldığında, çıkarılan kenarı kaynak belgeye bağlayan bir `subjectOf` ilişkisi bulunur.
|
||||
|
||||
### Mevcut Yaklaşımla İlgili Sorunlar
|
||||
|
||||
<<<<<<< HEAD
|
||||
1. **Tekrarlayan meta veri yüklemesi:** Belge meta verileri, o belgeden çıkarılan her üçlü grubuyla birlikte tekrar tekrar paketlenir ve yüklenir. Bu, israf ve gereksizdir - aynı meta veriler her çıkarma çıktısıyla birlikte yük taşımacılığı yapar.
|
||||
|
||||
2. **Yüzeysel köken bilgisi:** Mevcut `subjectOf` ilişkisi yalnızca gerçekleri doğrudan en üst düzey belgeyle ilişkilendirir. Dönüşüm zinciri hakkında hiçbir görünürlük yoktur - gerçek hangi sayfadan geldi, hangi parçadan, hangi çıkarma yöntemi kullanıldı.
|
||||
=======
|
||||
1. **Tekrarlayan meta veri yüklemesi:** Belge meta verileri, o belgeden çıkarılan her üçlü grubuyla birlikte tekrar tekrar paketlenir ve yüklenir. Bu, israf ve gereksizdir - aynı meta veriler, her çıkarma çıktısıyla birlikte yük olarak taşınır.
|
||||
|
||||
2. **Yüzeysel köken bilgisi:** Mevcut `subjectOf` ilişkisi yalnızca gerçekleri doğrudan en üst düzey belgeyle ilişkilendirir. Dönüşüm zinciri hakkında hiçbir görünürlük yoktur - gerçek hangi sayfadan, hangi bölümden geldi, hangi çıkarma yöntemi kullanıldı.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
### İstediğimiz Durum
|
||||
|
||||
1. **Meta verileri yalnızca bir kez yükleyin:** Belge meta verileri, her üçlü grubuyla tekrarlanmak yerine, yalnızca bir kez yüklenmeli ve en üst düzey belge düğümüne eklenmelidir.
|
||||
|
||||
<<<<<<< HEAD
|
||||
2. **Zengin köken bilgisi DAG'ı:** Kaynak belgeden başlayarak tüm ara öğeler aracılığıyla çıkarılan gerçeklere kadar olan tüm dönüşüm zincirini yakalayın. Örneğin, bir PDF belgesi dönüşümü:
|
||||
=======
|
||||
2. **Zengin köken bilgisi DAG'ı:** Kaynak belgeden başlayarak, tüm ara öğeler aracılığıyla çıkarılan gerçeklere kadar olan tüm dönüşüm zincirini yakalayın. Örneğin, bir PDF belgesi dönüşümü:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
```
|
||||
PDF file (source document with metadata)
|
||||
→ Page 1 (decoded text)
|
||||
→ Chunk 1
|
||||
→ Extracted edge/fact (via subjectOf)
|
||||
→ Extracted edge/fact
|
||||
→ Chunk 2
|
||||
→ Extracted edge/fact
|
||||
→ Page 2
|
||||
→ Chunk 3
|
||||
→ ...
|
||||
```
|
||||
|
||||
3. **Birleşik depolama:** Kaynak bilgisi DAG'ı, çıkarılan bilgiyle aynı bilgi grafiğinde saklanır. Bu, kaynak bilgisinin, herhangi bir gerçeğin tam kaynak konumuna doğru zincir boyunca geri izlenerek, bilgi gibi aynı şekilde sorgulanabilmesini sağlar.
|
||||
|
||||
4. **Sabit Kimlikler:** Her ara öğe (sayfa, parça) grafikte bir düğüm olarak sabit bir kimliğe sahiptir.
|
||||
|
||||
5. **Ebeveyn-çocuk bağlantısı:** Türetilmiş belgeler, tutarlı ilişki türleri kullanılarak, en üst düzey kaynak belgeye kadar ebeveynlerine bağlanır.
|
||||
|
||||
6. **Hassas gerçek ataması:** Çıkarılan kenarlardaki `subjectOf` ilişkisi, doğrudan ebeveyne (parçaya), en üst düzey belgeye değil, işaret eder. Tam kaynak bilgisi, DAG boyunca yukarı doğru gezilerek elde edilir.
|
||||
|
||||
## Kullanım Senaryoları
|
||||
|
||||
### KS1: GraphRAG Yanıtlarında Kaynak Ataması
|
||||
|
||||
**Senaryo:** Bir kullanıcı bir GraphRAG sorgusu çalıştırır ve ajandan bir yanıt alır.
|
||||
|
||||
**Süreç:**
|
||||
<<<<<<< HEAD
|
||||
1. Kullanıcı, GraphRAG ajanıyla bir sorgu gönderir.
|
||||
2. Ajan, bir yanıt oluşturmak için ilgili gerçekleri bilgi grafiğinden alır.
|
||||
3. Sorgu zamanı kaynak bilgisi spesifikasyonuna göre, ajan yanıtı oluşturan gerçekleri bildirir.
|
||||
=======
|
||||
1. Kullanıcı, GraphRAG ajanına bir sorgu gönderir.
|
||||
2. Ajan, bir yanıt oluşturmak için bilgi grafiğinden ilgili gerçekleri alır.
|
||||
3. Sorgu zamanı kaynak bilgisi spesifikasyonuna göre, ajan, yanıta hangi gerçeklerin katkıda bulunduğunu bildirir.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
4. Her gerçek, kaynak bilgisi DAG'ı aracılığıyla kaynak parçasına bağlanır.
|
||||
5. Parçalar, sayfalara bağlanır, sayfalar kaynak belgelere bağlanır.
|
||||
|
||||
**Kullanıcı Deneyimi Sonucu:** Arayüz, LLM yanıtını kaynak atamasıyla birlikte gösterir. Kullanıcı şunları yapabilir:
|
||||
Yanıtı destekleyen gerçekleri görebilir.
|
||||
Gerçeklerden → parçalara → sayfalara → belgelere kadar ayrıntılara inebilir.
|
||||
İddiaları doğrulamak için orijinal kaynak belgelerine göz atabilir.
|
||||
<<<<<<< HEAD
|
||||
Bir gerçekin tam olarak bir belgenin (hangi sayfa, hangi bölüm) neresinden geldiğini anlayabilir.
|
||||
|
||||
**Değer:** Kullanıcılar, yapay zeka tarafından oluşturulan yanıtlara birincil kaynaklara göre doğrulama yaparak güven oluşturabilir ve doğrulama yapabilir.
|
||||
=======
|
||||
Bir gerçekin bir belgenin neresinden (hangi sayfa, hangi bölüm) geldiğini tam olarak anlayabilir.
|
||||
|
||||
**Değer:** Kullanıcılar, yapay zeka tarafından oluşturulan yanıtlara birincil kaynaklara karşı doğrulama yaparak güven oluşturabilir ve doğruluk kontrolünü sağlayabilir.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
### KS2: Çıkarma Kalitesinin Hata Ayıklaması
|
||||
|
||||
Bir gerçek yanlış görünüyor. Orijinal metni görmek için parça → sayfa → belge yoluyla geriye doğru izleyin. Bu kötü bir çıkarma mıydı, yoksa kaynak mı yanlıştı?
|
||||
|
||||
### KS3: Artımlı Yeniden Çıkarma
|
||||
|
||||
<<<<<<< HEAD
|
||||
Kaynak belge güncellendi. Bu belgeden hangi parçalar/gerçekler türetildi? Sadece bunları geçersiz kılın ve yeniden oluşturun, her şeyi yeniden işlemek yerine.
|
||||
|
||||
### KS4: Veri Silme / Bilinme Hakkı
|
||||
|
||||
Bir kaynak belge kaldırılmalıdır (GDPR, yasal, vb.). Türetilmiş tüm gerçekleri bulmak ve kaldırmak için DAG'ı izleyin.
|
||||
=======
|
||||
Kaynak belge güncellenir. Bu belgeden hangi parçalar/gerçekler türetildi? Sadece bunları geçersiz kılın ve yeniden oluşturun, her şeyi yeniden işlemek yerine.
|
||||
|
||||
### KS4: Veri Silme / Bilinme Hakkı
|
||||
|
||||
Bir kaynak belge kaldırılmalıdır (GDPR, yasal, vb.). Tüm türetilmiş gerçekleri bulmak ve kaldırmak için DAG'ı geçin.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
### KS5: Çatışma Çözümü
|
||||
|
||||
İki gerçek birbiriyle çelişiyor. Nedenini anlamak ve hangisine güveneceğe karar vermek için her ikisini de kaynaklarına kadar izleyin (daha yetkili kaynak, daha yeni, vb.).
|
||||
|
||||
### KS6: Kaynak Yetki Ağırlığı
|
||||
|
||||
Bazı kaynaklar diğerlerinden daha yetkilidir. Gerçekler, kaynak belgelerinin yetki/kalitesine göre ağırlıklandırılabilir veya filtrelenebilir.
|
||||
|
||||
### KS7: Çıkarma Boru Hattı Karşılaştırması
|
||||
|
||||
<<<<<<< HEAD
|
||||
Farklı çıkarma yöntemlerinin/sürümlerinin çıktılarını karşılaştırın. Aynı kaynaktan daha iyi gerçekler üreten hangi çıkarıcıydı?
|
||||
=======
|
||||
Farklı çıkarma yöntemlerinin/sürümlerinin çıktılarını karşılaştırın. Aynı kaynaktan hangi çıkarıcı daha iyi gerçekler üretti?
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Entegrasyon Noktaları
|
||||
|
||||
### Kütüphaneci
|
||||
|
||||
<<<<<<< HEAD
|
||||
Kütüphaneci bileşeni, zaten benzersiz belge kimlikleriyle belge depolama imkanı sunmaktadır. Kaynak sistemi, bu mevcut altyapıyla entegre olmaktadır.
|
||||
=======
|
||||
Kütüphaneci bileşeni, zaten benzersiz belge kimlikleriyle belge depolama imkanı sunmaktadır. Kaynak sistemi, bu mevcut altyapıyla entegre edilmektedir.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### Mevcut Yetenekler (zaten uygulanan)
|
||||
|
||||
**Ebeveyn-Çocuk Belge Bağlantısı:**
|
||||
`parent_id` alanı - `DocumentMetadata` içinde - çocuk belgeyi ebeveyn belgeye bağlar
|
||||
`document_type` alanı - değerler: `"source"` (orijinal) veya `"extracted"` (türetilmiş)
|
||||
`add-child-document` API'si - otomatik `document_type = "extracted"` ile çocuk belge oluşturur
|
||||
`list-children` API'si - bir ebeveyn belgenin tüm çocuklarını alır
|
||||
Zincirleme silme - bir ebeveynin silinmesi, otomatik olarak tüm çocuk belgelerin silinmesine neden olur
|
||||
|
||||
**Belge Tanımlama:**
|
||||
Belge kimlikleri, istemci tarafından belirtilir (otomatik olarak oluşturulmaz)
|
||||
Belgeler, Cassandra'da bileşik `(user, document_id)` ile indekslenir
|
||||
Nesne kimlikleri (UUID'ler), blob depolama için dahili olarak oluşturulur
|
||||
|
||||
**Meta Veri Desteği:**
|
||||
`metadata: list[Triple]` alanı - yapılandırılmış meta veriler için RDF üçlüleri
|
||||
`title`, `comments`, `tags` - temel belge meta verileri
|
||||
`time` - zaman damgası, `kind` - MIME türü
|
||||
|
||||
**Depolama Mimarisi:**
|
||||
<<<<<<< HEAD
|
||||
Meta veriler, Cassandra'da saklanır (`librarian` anahtar alanı, `document` tablo)
|
||||
İçerik, MinIO/S3 blob depolamasında saklanır (`library` bucket)
|
||||
=======
|
||||
Meta veriler, Cassandra'da depolanır (`librarian` anahtar alanı, `document` tablo)
|
||||
İçerik, MinIO/S3 blob depolamada depolanır (`library` bucket)
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Akıllı içerik dağıtımı: 2 MB'den küçük belgeler yerleştirilir, daha büyük belgeler akışla iletilir
|
||||
|
||||
#### Önemli Dosyalar
|
||||
|
||||
`trustgraph-flow/trustgraph/librarian/librarian.py` - Temel kütüphaneci işlemleri
|
||||
`trustgraph-flow/trustgraph/librarian/service.py` - Hizmet işlemcisi, belge yükleme
|
||||
`trustgraph-flow/trustgraph/tables/library.py` - Cassandra tablo deposu
|
||||
`trustgraph-base/trustgraph/schema/services/library.py` - Şema tanımları
|
||||
|
||||
#### Giderilmesi Gereken Eksiklikler
|
||||
|
||||
Kütüphaneci, temel yapı taşlarına sahip olmasına rağmen şu anda:
|
||||
1. Ebeveyn-çocuk bağlantısı tek düzeylidir - çok düzeyli DAG (Yönlendirilmiş Döngüsel Grafik) gezinme yardımcıları yoktur
|
||||
2. Standart bir ilişki türü sözlüğü yoktur (örneğin, `derivedFrom`, `extractedFrom`)
|
||||
3. Kaynak meta verileri (çıkarma yöntemi, güven, parça konumu) standartlaştırılmamıştır
|
||||
<<<<<<< HEAD
|
||||
4. Bir gerçeğe geri dönen kaynaklara kadar tüm kaynak zincirini izlemek için bir sorgu API'si yoktur
|
||||
=======
|
||||
4. Bir gerçeğe geri dönen tam kaynak zincirini izlemek için bir sorgu API'si yoktur
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Uçtan Uca Akış Tasarımı
|
||||
|
||||
Boru hattındaki her işlemci, tutarlı bir kalıbı izler:
|
||||
<<<<<<< HEAD
|
||||
Yukarı akıştan belge kimliğini alır
|
||||
Kütüphaneciden içeriği alır
|
||||
Çocuk öğeler oluşturur
|
||||
Her çocuk için: kütüphaneciye kaydeder, grafiğe bir kenar yollar, kimliği aşağı akışa iletir
|
||||
=======
|
||||
Yukarıdan bir belge kimliği alınır
|
||||
İçerik, kütüphaneciden alınır
|
||||
Çocuk öğeler oluşturulur
|
||||
Her çocuk için: kütüphaneciye kaydedilir, grafiğe bir kenar yollanır, kimlik aşağı akışa iletilir
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
### İşlem Akışları
|
||||
|
||||
Belge türüne bağlı olarak iki akış vardır:
|
||||
|
||||
#### PDF Belge Akışı
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Librarian (initiate processing) │
|
||||
│ 1. Emit root document metadata to knowledge graph (once) │
|
||||
│ 2. Send root document ID to PDF extractor │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ PDF Extractor (per page) │
|
||||
│ 1. Fetch PDF content from librarian using document ID │
|
||||
│ 2. Extract pages as text │
|
||||
│ 3. For each page: │
|
||||
│ a. Save page as child document in librarian (parent = root doc) │
|
||||
│ b. Emit parent-child edge to knowledge graph │
|
||||
│ c. Send page document ID to chunker │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Chunker (per chunk) │
|
||||
│ 1. Fetch page content from librarian using document ID │
|
||||
│ 2. Split text into chunks │
|
||||
│ 3. For each chunk: │
|
||||
│ a. Save chunk as child document in librarian (parent = page) │
|
||||
│ b. Emit parent-child edge to knowledge graph │
|
||||
│ c. Send chunk document ID + chunk content to next processor │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
|
||||
Post-chunker optimization: messages carry both
|
||||
chunk ID (for provenance) and content (to avoid
|
||||
librarian round-trip). Chunks are small (2-4KB).
|
||||
─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Knowledge Extractor (per chunk) │
|
||||
│ 1. Receive chunk ID + content directly (no librarian fetch needed) │
|
||||
│ 2. Extract facts/triples and embeddings from chunk content │
|
||||
│ 3. For each triple: │
|
||||
│ a. Emit triple to knowledge graph │
|
||||
│ b. Emit reified edge linking triple → chunk ID (edge pointing │
|
||||
│ to edge - first use of reification support) │
|
||||
│ 4. For each embedding: │
|
||||
│ a. Emit embedding with its entity ID │
|
||||
│ b. Link entity ID → chunk ID in knowledge graph │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### Metin Belgesi Akışı
|
||||
|
||||
Metin belgeleri, PDF ayıklayıcıyı atlayarak doğrudan parçalayıcıya (chunker) gider:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Librarian (initiate processing) │
|
||||
│ 1. Emit root document metadata to knowledge graph (once) │
|
||||
│ 2. Send root document ID directly to chunker (skip PDF extractor) │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Chunker (per chunk) │
|
||||
│ 1. Fetch text content from librarian using document ID │
|
||||
│ 2. Split text into chunks │
|
||||
│ 3. For each chunk: │
|
||||
│ a. Save chunk as child document in librarian (parent = root doc) │
|
||||
│ b. Emit parent-child edge to knowledge graph │
|
||||
│ c. Send chunk document ID + chunk content to next processor │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Knowledge Extractor │
|
||||
│ (same as PDF flow) │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
Elde edilen DAG, bir seviye daha kısadır:
|
||||
|
||||
```
|
||||
PDF: Document → Pages → Chunks → Triples/Embeddings
|
||||
Text: Document → Chunks → Triples/Embeddings
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
Tasarım, her iki durumu da destekler çünkü parçalayıcı (chunker), girdisini genel olarak işler; aldığı belge kimliği, kaynak belge mi yoksa bir sayfa mı olduğunu dikkate almadan, bunu üst belge olarak kullanır.
|
||||
|
||||
### Metaveri Şeması (PROV-O)
|
||||
|
||||
Kaynak metaverileri, W3C PROV-O ontolojisini kullanır. Bu, standart bir sözlük sağlar ve çıkarılan verilerin gelecekteki imzalanmasını/doğrulanmasını mümkün kılar.
|
||||
=======
|
||||
Tasarım, her iki durumu da destekler çünkü parçalayıcı (chunker), girdisini genel olarak işler; aldığı belge kimliğini, bunun kaynak belge olup olmadığını veya bir sayfa olup olmadığını dikkate almadan, üst belge olarak kullanır.
|
||||
|
||||
### Metaveri Şeması (PROV-O)
|
||||
|
||||
Kaynak metaverileri, W3C PROV-O ontolojisini kullanır. Bu, standart bir kelime dağarcığı sağlar ve çıkarılan verilerin gelecekteki imzalama/kimlik doğrulamasını mümkün kılar.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### PROV-O Temel Kavramları
|
||||
|
||||
| PROV-O Tipi | TrustGraph Kullanımı |
|
||||
|-------------|------------------|
|
||||
| `prov:Entity` | Belge, Sayfa, Parça, Üçlü, Gömme |
|
||||
| `prov:Activity` | Çıkarma işlemlerinin örnekleri |
|
||||
| `prov:Agent` | TG bileşenleri (PDF ayıklayıcı, parçalayıcı, vb.) ve versiyonları |
|
||||
|
||||
#### PROV-O İlişkileri
|
||||
|
||||
| Özne | Anlamı | Örnek |
|
||||
|-----------|---------|---------|
|
||||
| `prov:wasDerivedFrom` | Başka bir varlıktan türetilen varlık | Sayfa, Belgeden Türetildi |
|
||||
| `prov:wasGeneratedBy` | Bir etkinlik tarafından oluşturulan varlık | Sayfa, PDFÇıkarmaEtkinliği Tarafından Oluşturuldu |
|
||||
| `prov:used` | Bir etkinliğin bir varlığı girdi olarak kullandığı | PDFÇıkarmaEtkinliği, Belgeyi Kullandı |
|
||||
| `prov:wasAssociatedWith` | Bir etkinliğin bir ajan tarafından gerçekleştirildiği | PDFÇıkarmaEtkinliği, tg:PDFÇıkarıcı ile İlişkiliydi |
|
||||
|
||||
#### Her Seviyedeki Metaveriler
|
||||
|
||||
**Kaynak Belge (Librarian tarafından oluşturulan):**
|
||||
```
|
||||
doc:123 a prov:Entity .
|
||||
doc:123 dc:title "Research Paper" .
|
||||
doc:123 dc:source <https://example.com/paper.pdf> .
|
||||
doc:123 dc:date "2024-01-15" .
|
||||
doc:123 dc:creator "Author Name" .
|
||||
doc:123 tg:pageCount 42 .
|
||||
doc:123 tg:mimeType "application/pdf" .
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
**Sayfa (PDF Çıkarıcı tarafından oluşturulmuştur):**
|
||||
=======
|
||||
**Sayfa (PDF Çıkarma Aracı tarafından oluşturulmuştur):**
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
```
|
||||
page:123-1 a prov:Entity .
|
||||
page:123-1 prov:wasDerivedFrom doc:123 .
|
||||
page:123-1 prov:wasGeneratedBy activity:pdf-extract-456 .
|
||||
page:123-1 tg:pageNumber 1 .
|
||||
|
||||
activity:pdf-extract-456 a prov:Activity .
|
||||
activity:pdf-extract-456 prov:used doc:123 .
|
||||
activity:pdf-extract-456 prov:wasAssociatedWith tg:PDFExtractor .
|
||||
activity:pdf-extract-456 tg:componentVersion "1.2.3" .
|
||||
activity:pdf-extract-456 prov:startedAtTime "2024-01-15T10:30:00Z" .
|
||||
```
|
||||
|
||||
**Parça (Chunker tarafından üretilen):**
|
||||
```
|
||||
chunk:123-1-1 a prov:Entity .
|
||||
chunk:123-1-1 prov:wasDerivedFrom page:123-1 .
|
||||
chunk:123-1-1 prov:wasGeneratedBy activity:chunk-789 .
|
||||
chunk:123-1-1 tg:chunkIndex 1 .
|
||||
chunk:123-1-1 tg:charOffset 0 .
|
||||
chunk:123-1-1 tg:charLength 2048 .
|
||||
|
||||
activity:chunk-789 a prov:Activity .
|
||||
activity:chunk-789 prov:used page:123-1 .
|
||||
activity:chunk-789 prov:wasAssociatedWith tg:Chunker .
|
||||
activity:chunk-789 tg:componentVersion "1.0.0" .
|
||||
activity:chunk-789 tg:chunkSize 2048 .
|
||||
activity:chunk-789 tg:chunkOverlap 200 .
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
**Üçlü (Knowledge Extractor tarafından üretildi):**
|
||||
=======
|
||||
**Üçlü (Bilgi Çıkarıcı tarafından üretildi):**
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
```
|
||||
# The extracted triple (edge)
|
||||
entity:JohnSmith rel:worksAt entity:AcmeCorp .
|
||||
|
||||
# Subgraph containing the extracted triples
|
||||
subgraph:001 tg:contains <<entity:JohnSmith rel:worksAt entity:AcmeCorp>> .
|
||||
subgraph:001 prov:wasDerivedFrom chunk:123-1-1 .
|
||||
subgraph:001 prov:wasGeneratedBy activity:extract-999 .
|
||||
|
||||
activity:extract-999 a prov:Activity .
|
||||
activity:extract-999 prov:used chunk:123-1-1 .
|
||||
activity:extract-999 prov:wasAssociatedWith tg:KnowledgeExtractor .
|
||||
activity:extract-999 tg:componentVersion "2.1.0" .
|
||||
activity:extract-999 tg:llmModel "claude-3" .
|
||||
activity:extract-999 tg:ontology <http://example.org/ontologies/business-v1> .
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
**Gömme (vektör deposunda saklanır, üçlü depolamada değil):**
|
||||
|
||||
Gömme verileri, RDF üçlüleri olarak değil, meta verilerle birlikte vektör deposunda saklanır. Her gömme kaydı şunları içerir:
|
||||
=======
|
||||
**Gömme (vektör depolama alanında saklanır, üçlü depolama alanında değil):**
|
||||
|
||||
Gömme verileri, RDF üçlüleri olarak değil, meta verilerle birlikte vektör depolama alanında saklanır. Her gömme kaydı şunları içerir:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
| Alan | Açıklama | Örnek |
|
||||
|-------|-------------|---------|
|
||||
| vektör | Gömme vektörü | [0.123, -0.456, ...] |
|
||||
| varlık | Gömmenin temsil ettiği düğüm URI'si | `entity:JohnSmith` |
|
||||
| chunk_id | Kaynak parça (kaynak) | `chunk:123-1-1` |
|
||||
| model | Kullanılan gömme modeli | `text-embedding-ada-002` |
|
||||
| component_version | TG gömme sürümü | `1.0.0` |
|
||||
|
||||
<<<<<<< HEAD
|
||||
`entity` alanı, gömmeyi bilgi grafiğine (düğüm URI'si) bağlar. `chunk_id` alanı, orijinal belgeye kadar DAG üzerinde izlemeyi sağlayarak, kaynak parçaya ilişkin bilgileri sağlar.
|
||||
|
||||
#### TrustGraph İsim Alanı Genişletmeleri
|
||||
|
||||
Çıkarma ile ilgili meta veriler için `tg:` isim alanı altındaki özel önekler:
|
||||
|
||||
| Önek | Alan | Açıklama |
|
||||
|-----------|--------|-------------|
|
||||
| `tg:contains` | Alt Grafik | Bu çıkarma alt grafiğindeki bir üçlüye işaret eder |
|
||||
=======
|
||||
`entity` alanı, gömmeyi bilgi grafiğine (düğüm URI'si) bağlar. `chunk_id` alanı, orijinal belgeye kadar DAG üzerinde gezinmeyi sağlayan, kaynak parçaya ilişkin bilgileri sağlar.
|
||||
|
||||
#### TrustGraph Ad Alanı Genişletmeleri
|
||||
|
||||
Çıkarma ile ilgili meta veriler için `tg:` ad alanının altındaki özel önekler:
|
||||
|
||||
| Önek | Alan | Açıklama |
|
||||
|-----------|--------|-------------|
|
||||
| `tg:contains` | Alt Grafik | Bu çıkarma alt grafiğinde bulunan bir üçlüye işaret eder |
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
| `tg:pageCount` | Belge | Kaynak belgedeki toplam sayfa sayısı |
|
||||
| `tg:mimeType` | Belge | Kaynak belgenin MIME türü |
|
||||
| `tg:pageNumber` | Sayfa | Kaynak belgedeki sayfa numarası |
|
||||
| `tg:chunkIndex` | Parça | Ebeveyn içindeki parçanın indeksi |
|
||||
| `tg:charOffset` | Parça | Ebeveyn metnindeki karakter ofseti |
|
||||
| `tg:charLength` | Parça | Parçanın karakter cinsinden uzunluğu |
|
||||
| `tg:chunkSize` | Etkinlik | Yapılandırılmış parça boyutu |
|
||||
| `tg:chunkOverlap` | Etkinlik | Parçalar arasındaki yapılandırılmış örtüşme |
|
||||
| `tg:componentVersion` | Etkinlik | TG bileşeninin sürümü |
|
||||
| `tg:llmModel` | Etkinlik | Çıkarma için kullanılan LLM |
|
||||
| `tg:ontology` | Etkinlik | Çıkarma için kullanılan ontoloji URI'si |
|
||||
| `tg:embeddingModel` | Etkinlik | Gömme için kullanılan model |
|
||||
| `tg:sourceText` | İfade | Bir üçlünün çıkarıldığı tam metin |
|
||||
| `tg:sourceCharOffset` | İfade | Kaynak metnin başladığı parça içindeki karakter ofseti |
|
||||
| `tg:sourceCharLength` | İfade | Kaynak metnin karakter cinsinden uzunluğu |
|
||||
|
||||
#### Sözlük Başlatma (Her Koleksiyon İçin)
|
||||
|
||||
<<<<<<< HEAD
|
||||
Bilgi grafiği, ontolojiye bağımlı olmayan ve başlangıçta boş olan bir yapıdır. Bir koleksiyona PROV-O kaynak verilerini ilk kez yazarken, tüm sınıflar ve önekler için RDF etiketleriyle sözlük başlatılmalıdır. Bu, sorgularda ve kullanıcı arayüzünde okunabilir bir görüntüleme sağlar.
|
||||
=======
|
||||
Bilgi grafiği, ontolojiye bağımlı olmayan ve başlangıçta boş durumdadır. Bir koleksiyona PROV-O kaynak verilerini ilk kez yazarken, tüm sınıflar ve önekler için RDF etiketleriyle sözlük başlatılmalıdır. Bu, sorgularda ve kullanıcı arayüzünde okunabilir bir görüntüleme sağlar.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**PROV-O Sınıfları:**
|
||||
```
|
||||
prov:Entity rdfs:label "Entity" .
|
||||
prov:Activity rdfs:label "Activity" .
|
||||
prov:Agent rdfs:label "Agent" .
|
||||
```
|
||||
|
||||
**PROV-O Yüklemleri:**
|
||||
```
|
||||
prov:wasDerivedFrom rdfs:label "was derived from" .
|
||||
prov:wasGeneratedBy rdfs:label "was generated by" .
|
||||
prov:used rdfs:label "used" .
|
||||
prov:wasAssociatedWith rdfs:label "was associated with" .
|
||||
prov:startedAtTime rdfs:label "started at" .
|
||||
```
|
||||
|
||||
**TrustGraph Önermeleri:**
|
||||
```
|
||||
tg:contains rdfs:label "contains" .
|
||||
tg:pageCount rdfs:label "page count" .
|
||||
tg:mimeType rdfs:label "MIME type" .
|
||||
tg:pageNumber rdfs:label "page number" .
|
||||
tg:chunkIndex rdfs:label "chunk index" .
|
||||
tg:charOffset rdfs:label "character offset" .
|
||||
tg:charLength rdfs:label "character length" .
|
||||
tg:chunkSize rdfs:label "chunk size" .
|
||||
tg:chunkOverlap rdfs:label "chunk overlap" .
|
||||
tg:componentVersion rdfs:label "component version" .
|
||||
tg:llmModel rdfs:label "LLM model" .
|
||||
tg:ontology rdfs:label "ontology" .
|
||||
tg:embeddingModel rdfs:label "embedding model" .
|
||||
tg:sourceText rdfs:label "source text" .
|
||||
tg:sourceCharOffset rdfs:label "source character offset" .
|
||||
tg:sourceCharLength rdfs:label "source character length" .
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
**Uygulama notu:** Bu sözlük başlatma işleminin idempotent olması gerekir - yani, çoğaltmalar oluşturmadan birden çok kez çalıştırılabilir. Bu işlem, bir koleksiyondaki ilk belge işleme sırasında veya ayrı bir koleksiyon başlatma adımı olarak tetiklenebilir.
|
||||
=======
|
||||
**Uygulama notu:** Bu sözlük başlatma işleminin idempotent olması gerekir - yani, çoğaltmalar oluşturmadan birden çok kez çalıştırılabilir. Koleksiyon içindeki ilk belge işleme sırasında veya ayrı bir koleksiyon başlatma adımı olarak tetiklenebilir.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### Alt Parça Kaynağı (İdeal)
|
||||
|
||||
Daha ayrıntılı bir kaynak bilgisi için, bir üçlemenin bir parça içinde tam olarak nereden çıkarıldığı kaydedilmesi değerli olacaktır. Bu, şunları sağlar:
|
||||
|
||||
Kullanıcı arayüzünde (UI) tam kaynak metninin vurgulanması
|
||||
Çıkarma doğruluğunun kaynağa göre doğrulanması
|
||||
Çıkarma kalitesinin cümle düzeyinde hata ayıklanması
|
||||
|
||||
**Konum takibi ile örnek:**
|
||||
```
|
||||
# The extracted triple
|
||||
entity:JohnSmith rel:worksAt entity:AcmeCorp .
|
||||
|
||||
# Subgraph with sub-chunk provenance
|
||||
subgraph:001 tg:contains <<entity:JohnSmith rel:worksAt entity:AcmeCorp>> .
|
||||
subgraph:001 prov:wasDerivedFrom chunk:123-1-1 .
|
||||
subgraph:001 tg:sourceText "John Smith has worked at Acme Corp since 2019" .
|
||||
subgraph:001 tg:sourceCharOffset 1547 .
|
||||
subgraph:001 tg:sourceCharLength 46 .
|
||||
```
|
||||
|
||||
**Metin aralığı içeren örnek (alternatif):**
|
||||
```
|
||||
subgraph:001 tg:contains <<entity:JohnSmith rel:worksAt entity:AcmeCorp>> .
|
||||
subgraph:001 prov:wasDerivedFrom chunk:123-1-1 .
|
||||
subgraph:001 tg:sourceRange "1547-1593" .
|
||||
subgraph:001 tg:sourceText "John Smith has worked at Acme Corp since 2019" .
|
||||
```
|
||||
|
||||
**Uygulama hususları:**
|
||||
|
||||
LLM tabanlı çıkarma, doğal olarak karakter konumlarını sağlamayabilir.
|
||||
LLM'den çıkarılan üçlülerin yanı sıra kaynak cümleyi/ifadeyi de döndürmesi istenebilir.
|
||||
Alternatif olarak, çıkarılan varlıkları kaynak metne geri eşleştirmek için bir işlem sonrası adımı uygulanabilir.
|
||||
Çıkarma karmaşıklığı ile kaynak doğruluğu arasındaki denge.
|
||||
<<<<<<< HEAD
|
||||
Yapılandırılmış çıkarma yöntemleriyle serbest biçimli LLM çıkarma yöntemlerinden daha kolay uygulanabilir olabilir.
|
||||
=======
|
||||
Serbest biçimli LLM çıkarma yöntemlerine kıyasla yapılandırılmış çıkarma yöntemleriyle elde edilmesi daha kolay olabilir.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
Bu, iddialı bir hedef olarak işaretlenmiştir - temel parça düzeyindeki kaynak bilgisi öncelikle uygulanmalı, alt parça takibi ise uygulanabilirse gelecekteki bir iyileştirme olarak düşünülmelidir.
|
||||
|
||||
### Çift Depolama Modeli
|
||||
|
||||
Kaynak bilgisi DAG'ı, belgeler boru hattından geçerken kademeli olarak oluşturulur:
|
||||
|
||||
<<<<<<< HEAD
|
||||
| Depo | Neler Saklanır | Amaç |
|
||||
|-------|---------------|---------|
|
||||
| Kütüphaneci | Belge içeriği + ebeveyn-çocuk bağlantıları | İçerik alma, kaskad silme |
|
||||
| Bilgi Grafiği | Ebeveyn-çocuk kenarları + meta veri | Kaynak bilgisi sorguları, gerçek ataması |
|
||||
|
||||
Her iki depo da aynı DAG yapısını korur. Kütüphaneci içeriği saklar; grafik ilişkileri saklar ve gezinme sorgularını sağlar.
|
||||
|
||||
### Temel Tasarım Prensipleri
|
||||
=======
|
||||
| Depolama | Neler Depolanır | Amaç |
|
||||
|-------|---------------|---------|
|
||||
| Kütüphaneci | Belge içeriği + ebeveyn-çocuk bağlantıları | İçerik alma, zincirleme silme |
|
||||
| Bilgi Grafiği | Ebeveyn-çocuk kenarları + meta veri | Kaynak bilgisi sorguları, gerçek ataması |
|
||||
|
||||
Her iki depolama birimi de aynı DAG yapısını korur. Kütüphaneci içeriği tutarken, grafik ilişkileri tutar ve gezinme sorgularını sağlar.
|
||||
|
||||
### Temel Tasarım İlkeleri
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
1. **Belge Kimliği akış birimi olarak** - İşleyiciler içeriği değil, kimlikleri iletir. İçerik gerektiğinde kütüphaneciden alınır.
|
||||
|
||||
2. **Kaynakta bir kez yayınla** - Meta veri, işleme başladığında grafiğe bir kez yazılır, aşağı akışta tekrarlanmaz.
|
||||
|
||||
3. **Tutarlı işlemci kalıbı** - Her işlemci aynı alım/alma/üretme/kaydetme/yayınlama/ileri gönderme kalıbını izler.
|
||||
|
||||
<<<<<<< HEAD
|
||||
4. **Kademeli DAG oluşturma** - Her işlemci DAG'a kendi seviyesini ekler. Tam kaynak bilgisi zinciri kademeli olarak oluşturulur.
|
||||
|
||||
5. **Parça sonrasındaki optimizasyon** - Parçalama işleminden sonra, mesajlar hem kimliği hem de içeriği taşır. Parçalar küçüktür (2-4KB), bu nedenle içeriği dahil etmek, kütüphaneciye yapılan gereksiz geri dönüşleri önlerken kimlik yoluyla kaynak bilgisini korur.
|
||||
=======
|
||||
4. **Kademeli DAG oluşturma** - Her işlemci, DAG'a kendi seviyesini ekler. Tam kaynak bilgisi zinciri kademeli olarak oluşturulur.
|
||||
|
||||
5. **Parça sonrasındaki optimizasyon** - Parçalama işleminden sonra, mesajlar hem kimliği hem de içeriği taşır. Parçalar küçüktür (2-4KB), bu nedenle içeriği dahil etmek, kütüphaneci ile gereksiz geri dönüşleri önlerken, kimlik aracılığıyla kaynak bilgisini korur.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Uygulama Görevleri
|
||||
|
||||
### Kütüphaneci Değişiklikleri
|
||||
|
||||
#### Mevcut Durum
|
||||
|
||||
Belge işleme işlemini başlatarak belge kimliğini ilk işlemciye gönderir.
|
||||
<<<<<<< HEAD
|
||||
Üçlü depoyla bağlantı yok - meta veri, çıkarma çıktılarıyla birlikte paketlenir.
|
||||
`add-child-document` tek seviyeli ebeveyn-çocuk bağlantıları oluşturur.
|
||||
=======
|
||||
Üçlü depolamaya bağlantı yok - meta veri, çıkarma çıktılarıyla birlikte paketlenir.
|
||||
`add-child-document` tek düzeyli ebeveyn-çocuk bağlantıları oluşturur.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
`list-children` yalnızca hemen alt öğeleri döndürür.
|
||||
|
||||
#### Gerekli Değişiklikler
|
||||
|
||||
<<<<<<< HEAD
|
||||
**1. Yeni arayüz: Üçlü depo bağlantısı**
|
||||
|
||||
Kütüphaneci, işleme başlatıldığında belge meta veri kenarlarını doğrudan bilgi grafiğine yayınlamalıdır.
|
||||
Kütüphaneci hizmetine üçlü depo istemci/yayınlayıcısı ekleyin.
|
||||
=======
|
||||
**1. Yeni arayüz: Üçlü depolama bağlantısı**
|
||||
|
||||
Kütüphaneci, işleme başlatıldığında belge meta veri kenarlarını doğrudan bilgi grafiğine yayınlamalıdır.
|
||||
Kütüphaneci hizmetine üçlü depolama istemci/yayınlayıcısı ekleyin.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
İşleme başlatıldığında: kök belge meta verilerini grafik kenarları olarak (tek seferlik) yayınlayın.
|
||||
|
||||
**2. Belge türü sözlüğü**
|
||||
|
||||
<<<<<<< HEAD
|
||||
Alt belgeler için `document_type` değerlerini standartlaştırın:
|
||||
=======
|
||||
Çocuk belgeler için `document_type` değerlerini standartlaştırın:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
`source` - orijinal olarak yüklenen belge
|
||||
`page` - kaynaktan (PDF, vb.) çıkarılan sayfa
|
||||
`chunk` - sayfadan veya kaynaktan türetilen metin parçası
|
||||
|
||||
#### Arayüz Değişiklikleri Özeti
|
||||
|
||||
| Arayüz | Değişiklik |
|
||||
|-----------|--------|
|
||||
<<<<<<< HEAD
|
||||
| Üçlü depo | Yeni dışa dönük bağlantı - belge meta veri kenarlarını yayınlayın |
|
||||
| İşleme başlatma | Meta veriyi grafiğe yayınlayın, belge kimliğini iletmeden önce |
|
||||
=======
|
||||
| Üçlü depolama | Yeni dışa dönük bağlantı - belge meta veri kenarlarını yayınlayın |
|
||||
| İşleme başlatma | Meta veriyi grafiğe yayınlayın, belge kimliğini iletmeye devam etmeden önce |
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
### PDF Çıkarma Değişiklikleri
|
||||
|
||||
#### Mevcut Durum
|
||||
|
||||
<<<<<<< HEAD
|
||||
Belge içeriğini alır (veya büyük belgeleri akış halinde alır)
|
||||
PDF sayfalarından metin çıkarır
|
||||
Sayfa içeriğini parçalayıcıya iletir
|
||||
Kütüphaneci veya üçlü depo ile etkileşimde bulunmaz
|
||||
=======
|
||||
Belge içeriğini alır (veya büyük belgeleri akış halinde alır).
|
||||
PDF sayfalarından metin çıkarır.
|
||||
Sayfa içeriğini parçalayıcıya iletir.
|
||||
Kütüphaneci veya üçlü depolamayla etkileşimde bulunmaz.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### Gerekli Değişiklikler
|
||||
|
||||
**1. Yeni arayüz: Kütüphaneci istemcisi**
|
||||
|
||||
<<<<<<< HEAD
|
||||
PDF çıkarıcı, her sayfayı kütüphanecide bir alt belge olarak kaydetmelidir.
|
||||
PDF çıkarıcı hizmetine kütüphaneci istemcisi ekleyin
|
||||
Her sayfa için: ebeveyn = kök belge kimliği ile `add-child-document`'yi çağırın
|
||||
|
||||
**2. Yeni arayüz: Üçlü depo bağlantısı**
|
||||
|
||||
PDF çıkarıcı, ebeveyn-çocuk kenarlarını bilgi grafiğine yayınlamalıdır.
|
||||
Üçlü depo istemci/yayınlayıcısı ekleyin
|
||||
Her sayfa için: sayfa belgesini ebeveyn belgeyle ilişkilendiren bir kenar yayınlayın
|
||||
=======
|
||||
PDF çıkarıcı, her sayfayı kütüphanecide bir çocuk belge olarak kaydetmelidir.
|
||||
PDF çıkarıcı hizmetine kütüphaneci istemcisi ekleyin.
|
||||
Her sayfa için: `add-child-document`'ı ebeveyn = kök belge kimliği ile çağırın.
|
||||
|
||||
**2. Yeni arayüz: Üçlü depolama bağlantısı**
|
||||
|
||||
PDF çıkarıcı, ebeveyn-çocuk kenarlarını bilgi grafiğine yayınlamalıdır.
|
||||
Üçlü depolama istemci/yayınlayıcısı ekleyin.
|
||||
Her sayfa için: sayfa belgesini ebeveyn belgeye bağlayan bir kenar yayınlayın.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**3. Çıktı biçimini değiştirin**
|
||||
|
||||
Sayfa içeriğini doğrudan iletmek yerine, sayfa belge kimliğini iletin.
|
||||
Chunker, içeriği kütüphaneden kimliği kullanarak alacaktır.
|
||||
|
||||
#### Arayüz Değişiklikleri Özeti
|
||||
|
||||
| Arayüz | Değişiklik |
|
||||
|-----------|--------|
|
||||
| Kütüphane | Yeni dışa aktarma - alt belgeleri kaydet |
|
||||
| Üçlü depolama | Yeni dışa aktarma - ebeveyn-çocuk kenarlarını yayınla |
|
||||
| Çıkış mesajı | İçerikten belge kimliğine geçiş |
|
||||
|
||||
### Chunker Değişiklikleri
|
||||
|
||||
#### Mevcut Durum
|
||||
|
||||
Sayfa/metin içeriğini alır
|
||||
Parçalara böler
|
||||
Parça içeriğini sonraki işleme birimlerine iletir
|
||||
Kütüphane veya üçlü depolamayla etkileşimde bulunmaz
|
||||
|
||||
#### Gerekli Değişiklikler
|
||||
|
||||
**1. Giriş işleme şeklini değiştirin**
|
||||
|
||||
İçerik yerine belge kimliğini alın, kütüphaneden alın.
|
||||
Chunker hizmetine kütüphane istemcisini ekleyin
|
||||
Belge kimliğini kullanarak sayfa içeriğini alın
|
||||
|
||||
**2. Yeni arayüz: Kütüphane istemcisi (yazma)**
|
||||
|
||||
Her parçayı kütüphanede bir alt belge olarak kaydedin.
|
||||
Her parça için: ebeveyn = sayfa belge kimliği ile `add-child-document`'ı çağırın
|
||||
|
||||
**3. Yeni arayüz: Üçlü depolama bağlantısı**
|
||||
|
||||
Ebeveyn-çocuk kenarlarını bilgi grafiğine yayınlayın.
|
||||
Üçlü depolama istemcisini/yayınlayıcısını ekleyin
|
||||
Her parça için: parça belgesini sayfa belgesine bağlayan kenarı yayınlayın
|
||||
|
||||
**4. Çıkış biçimini değiştirin**
|
||||
|
||||
Hem parça belge kimliğini hem de parça içeriğini iletin (parça işleminden sonraki optimizasyon).
|
||||
Sonraki işleme birimleri, köken bilgisi için kimliği ve çalışmak için içeriği alır
|
||||
|
||||
#### Arayüz Değişiklikleri Özeti
|
||||
|
||||
| Arayüz | Değişiklik |
|
||||
|-----------|--------|
|
||||
| Giriş mesajı | İçerikten belge kimliğine geçiş |
|
||||
| Kütüphane | Yeni dışa aktarma (okuma + yazma) - içeriği alın, alt belgeleri kaydedin |
|
||||
| Üçlü depolama | Yeni dışa aktarma - ebeveyn-çocuk kenarlarını yayınla |
|
||||
| Çıkış mesajı | İçerikten kimliğe + içeriğe geçiş |
|
||||
|
||||
### Bilgi Çıkarıcı Değişiklikleri
|
||||
|
||||
#### Mevcut Durum
|
||||
|
||||
Parça içeriğini alır
|
||||
Üçlüleri ve gömme değerlerini çıkarır
|
||||
Üçlü depolamaya ve gömme depolamaya yayınlar
|
||||
`subjectOf` ilişkisi, en üst düzey belgeye (parçaya değil) işaret eder
|
||||
|
||||
#### Gerekli Değişiklikler
|
||||
|
||||
**1. Giriş işleme şeklini değiştirin**
|
||||
|
||||
<<<<<<< HEAD
|
||||
Parça belge kimliğini içeriğin yanında alın.
|
||||
Köken bağlama için parça kimliğini kullanın (içerik zaten optimizasyon kapsamında dahil edilmiştir)
|
||||
|
||||
**2. Üçlü kökeni güncelleyin**
|
||||
=======
|
||||
Parça belge kimliğini içeriğin yanı sıra alın.
|
||||
Köken bağlantısı için parça kimliğini kullanın (içerik zaten optimizasyon kapsamında dahil edilmiştir)
|
||||
|
||||
**2. Üçlü kökenini güncelleyin**
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
Çıkarılan üçlüleri parçaya (en üst düzey belgeye değil) bağlayın.
|
||||
Kenara işaret eden bir kenar oluşturmak için yeniden tanımlama kullanın
|
||||
`subjectOf` ilişkisi: üçlü → parça belge kimliği
|
||||
Mevcut yeniden tanımlama desteğinin ilk kullanımı
|
||||
|
||||
**3. Gömme kökenini güncelleyin**
|
||||
|
||||
Gömme varlık kimliklerini parçaya bağlayın.
|
||||
Kenar yayınlayın: gömme varlık kimliği → parça belge kimliği
|
||||
|
||||
#### Arayüz Değişiklikleri Özeti
|
||||
|
||||
| Arayüz | Değişiklik |
|
||||
|-----------|--------|
|
||||
| Giriş mesajı | Parça kimliğini + içeriği bekleyin (sadece içeriği değil) |
|
||||
| Üçlü depolama | Üçlü → parça kökeni için yeniden tanımlamayı kullanın |
|
||||
| Gömme kökeni | Varlık kimliğini → parça kimliğine bağlayın |
|
||||
|
||||
## Referanslar
|
||||
|
||||
Sorgu zamanı kökeni: `docs/tech-specs/query-time-provenance.md`
|
||||
Köken modellemesi için PROV-O standardı
|
||||
Bilgi grafiğindeki mevcut kaynak meta verileri (denetlenmesi gerekir)
|
||||
326
docs/tech-specs/tr/flow-class-definition.tr.md
Normal file
326
docs/tech-specs/tr/flow-class-definition.tr.md
Normal file
|
|
@ -0,0 +1,326 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Akış Şeması Tanım Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Akış Şeması Tanım Ö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ış
|
||||
|
||||
<<<<<<< HEAD
|
||||
Bir akış şeması, TrustGraph sisteminde eksiksiz bir veri akışı kalıbı şablonunu tanımlar. Örneklenildiğinde, verilerin alınması, işlenmesi, depolanması ve sorgulanması işlemlerini tek bir sistem olarak ele alan, birbirine bağlı bir işlemci ağı oluşturur.
|
||||
=======
|
||||
Bir akış şeması, TrustGraph sisteminde eksiksiz bir veri akışı kalıbı şablonunu tanımlar. Örneklenildiğinde, veri alımı, işleme, depolama ve sorgulamayı birleşik bir sistem olarak ele alan birbirine bağlı işlemci ağları oluşturur.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Yapı
|
||||
|
||||
Bir akış şeması tanımı, beş ana bölümden oluşur:
|
||||
|
||||
### 1. Sınıf Bölümü
|
||||
Her akış şeması için yalnızca bir kez örneklendirilen, paylaşılan hizmet işlemcilerini tanımlar. Bu işlemciler, bu sınıfın tüm akış örneklerinden gelen istekleri işler.
|
||||
|
||||
```json
|
||||
"class": {
|
||||
"service-name:{class}": {
|
||||
"request": "queue-pattern:{class}",
|
||||
"response": "queue-pattern:{class}",
|
||||
"settings": {
|
||||
"setting-name": "fixed-value",
|
||||
"parameterized-setting": "{parameter-name}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Özellikler:**
|
||||
Aynı sınıftaki tüm akış örnekleri arasında paylaşılır.
|
||||
Genellikle maliyetli veya durumsuz hizmetlerdir (LLM'ler, gömme modelleri).
|
||||
Kuyruk adlandırması için `{class}` şablon değişkenini kullanın.
|
||||
Ayarlar, sabit değerler olabilir veya `{parameter-name}` sözdizimi ile parametrelendirilebilir.
|
||||
Örnekler: `embeddings:{class}`, `text-completion:{class}`, `graph-rag:{class}`
|
||||
|
||||
### 2. Akış Bölümü
|
||||
Her bir bireysel akış örneği için örneklenen, akışa özgü işlemcileri tanımlar. Her akışın kendi izole edilmiş işlemci kümesi vardır.
|
||||
|
||||
```json
|
||||
"flow": {
|
||||
"processor-name:{id}": {
|
||||
"input": "queue-pattern:{id}",
|
||||
"output": "queue-pattern:{id}",
|
||||
"settings": {
|
||||
"setting-name": "fixed-value",
|
||||
"parameterized-setting": "{parameter-name}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Özellikler:**
|
||||
Her akış için benzersiz bir örnek
|
||||
Akışa özgü verileri ve durumu yönetir
|
||||
<<<<<<< HEAD
|
||||
Kuyruğu adlandırmak için `{id}` şablon değişkenini kullanın
|
||||
=======
|
||||
Kuyruğa adlandırma için `{id}` şablon değişkenini kullanın
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Ayarlar, sabit değerler olabilir veya `{parameter-name}` sözdizimi ile parametrelendirilebilir
|
||||
Örnekler: `chunker:{id}`, `pdf-decoder:{id}`, `kg-extract-relationships:{id}`
|
||||
|
||||
### 3. Arayüzler Bölümü
|
||||
Akış için giriş noktalarını ve etkileşim sözleşmelerini tanımlar. Bunlar, harici sistemler ve dahili bileşen iletişimi için API yüzeyini oluşturur.
|
||||
|
||||
Arayüzler iki formda olabilir:
|
||||
|
||||
**Ateşle ve Unut (Fire-and-Forget) Modeli** (tek kuyruk):
|
||||
```json
|
||||
"interfaces": {
|
||||
"document-load": "persistent://tg/flow/document-load:{id}",
|
||||
"triples-store": "persistent://tg/flow/triples-store:{id}"
|
||||
}
|
||||
```
|
||||
|
||||
**İstek/Yanıt Modeli** (istek/yanıt alanlarına sahip nesne):
|
||||
```json
|
||||
"interfaces": {
|
||||
"embeddings": {
|
||||
"request": "non-persistent://tg/request/embeddings:{class}",
|
||||
"response": "non-persistent://tg/response/embeddings:{class}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Arayüz Türleri:**
|
||||
**Giriş Noktaları:** Dış sistemlerin veri enjekte ettiği yerler (`document-load`, `agent`)
|
||||
<<<<<<< HEAD
|
||||
**Servis Arayüzleri:** Servisler için istek/yanıt kalıpları (`embeddings`, `text-completion`)
|
||||
=======
|
||||
**Hizmet Arayüzleri:** Hizmetler için istek/yanıt kalıpları (`embeddings`, `text-completion`)
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**Veri Arayüzleri:** Ateşle-ve-unut veri akışı bağlantı noktaları (`triples-store`, `entity-contexts-load`)
|
||||
|
||||
### 4. Parametreler Bölümü
|
||||
Akışa özgü parametre adlarını, merkezi olarak saklanan parametre tanımlarına eşler:
|
||||
|
||||
```json
|
||||
"parameters": {
|
||||
"model": "llm-model",
|
||||
"temp": "temperature",
|
||||
"chunk": "chunk-size"
|
||||
}
|
||||
```
|
||||
|
||||
**Özellikler:**
|
||||
Anahtarlar, işlemci ayarlarında kullanılan parametre adlarıdır (örneğin, `{model}`).
|
||||
Değerler, şema/yapılandırmada saklanan parametre tanımlarına referans verir.
|
||||
Akışlar arasında ortak parametre tanımlarının yeniden kullanılmasını sağlar.
|
||||
Parametre şemalarının çoğaltılmasını azaltır.
|
||||
|
||||
### 5. Meta Veriler
|
||||
Akış şeması hakkında ek bilgiler:
|
||||
|
||||
```json
|
||||
"description": "Human-readable description",
|
||||
"tags": ["capability-1", "capability-2"]
|
||||
```
|
||||
|
||||
## Şablon Değişkenleri
|
||||
|
||||
### Sistem Değişkenleri
|
||||
|
||||
#### {id}
|
||||
Her akış örneği için benzersiz tanımlayıcı ile değiştirilir.
|
||||
Her akış için izole kaynaklar oluşturur.
|
||||
Örnek: `flow-123`, `customer-A-flow`
|
||||
|
||||
#### {class}
|
||||
Akış şablonu adıyla değiştirilir.
|
||||
Aynı sınıftaki akışlar arasında paylaşılan kaynaklar oluşturur.
|
||||
Örnek: `standard-rag`, `enterprise-rag`
|
||||
|
||||
### Parametre Değişkenleri
|
||||
|
||||
#### {parametre-adı}
|
||||
Akış başlatma zamanında tanımlanan özel parametrelerdir.
|
||||
Parametre adları, akışın `parameters` bölümündeki anahtarlarla eşleşir.
|
||||
İşlemci ayarlarında davranışı özelleştirmek için kullanılır.
|
||||
Örnekler: `{model}`, `{temp}`, `{chunk}`
|
||||
Akışı başlattığınızda sağlanan değerlerle değiştirilir.
|
||||
Merkezi olarak saklanan parametre tanımlarına göre doğrulanır.
|
||||
|
||||
## İşlemci Ayarları
|
||||
|
||||
Ayarlar, işlemcilerin başlatma zamanındaki yapılandırma değerlerini sağlar. Bunlar şunlar olabilir:
|
||||
|
||||
### Sabit Ayarlar
|
||||
Değişmeyen doğrudan değerler:
|
||||
```json
|
||||
"settings": {
|
||||
"model": "gemma3:12b",
|
||||
"temperature": 0.7,
|
||||
"max_retries": 3
|
||||
}
|
||||
```
|
||||
|
||||
### Parametreleştirilmiş Ayarlar
|
||||
Akış başlatılırken sağlanan parametreleri kullanan değerler:
|
||||
```json
|
||||
"settings": {
|
||||
"model": "{model}",
|
||||
"temperature": "{temp}",
|
||||
"endpoint": "https://{region}.api.example.com"
|
||||
}
|
||||
```
|
||||
|
||||
Ayarlardaki parametre adları, akışın `parameters` bölümündeki anahtarlara karşılık gelir.
|
||||
|
||||
### Ayar Örnekleri
|
||||
|
||||
**Parametrelerle LLM İşlemcisi:**
|
||||
```json
|
||||
// In parameters section:
|
||||
"parameters": {
|
||||
"model": "llm-model",
|
||||
"temp": "temperature",
|
||||
"tokens": "max-tokens",
|
||||
"key": "openai-api-key"
|
||||
}
|
||||
|
||||
// In processor definition:
|
||||
"text-completion:{class}": {
|
||||
"request": "non-persistent://tg/request/text-completion:{class}",
|
||||
"response": "non-persistent://tg/response/text-completion:{class}",
|
||||
"settings": {
|
||||
"model": "{model}",
|
||||
"temperature": "{temp}",
|
||||
"max_tokens": "{tokens}",
|
||||
"api_key": "{key}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Sabit ve Parametreize Ayarlara Sahip Parçalayıcı:**
|
||||
```json
|
||||
// In parameters section:
|
||||
"parameters": {
|
||||
"chunk": "chunk-size"
|
||||
}
|
||||
|
||||
// In processor definition:
|
||||
"chunker:{id}": {
|
||||
"input": "persistent://tg/flow/chunk:{id}",
|
||||
"output": "persistent://tg/flow/chunk-load:{id}",
|
||||
"settings": {
|
||||
"chunk_size": "{chunk}",
|
||||
"chunk_overlap": 100,
|
||||
"encoding": "utf-8"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Kuyruk Desenleri (Pulsar)
|
||||
|
||||
Akış şemaları, mesajlaşma için Apache Pulsar'ı kullanır. Kuyruk adları, Pulsar formatını izler:
|
||||
```
|
||||
<persistence>://<tenant>/<namespace>/<topic>
|
||||
```
|
||||
|
||||
### Bileşenler:
|
||||
**kalıcılık**: `persistent` veya `non-persistent` (Pulsar kalıcılık modu)
|
||||
**kiracı**: TrustGraph tarafından sağlanan akış tanım şablonları için `tg`
|
||||
<<<<<<< HEAD
|
||||
**isim alanı**: Mesajlaşma desenini belirtir
|
||||
=======
|
||||
**isim alanı**: Mesajlaşma kalıbını gösterir
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
`flow`: Ateşle ve unut hizmetleri
|
||||
`request`: İstek/yanıt hizmetlerinin istek kısmı
|
||||
`response`: İstek/yanıt hizmetlerinin yanıt kısmı
|
||||
**konu**: Şablon değişkenleriyle belirli kuyruk/konu adı
|
||||
|
||||
### Kalıcı Kuyruklar
|
||||
<<<<<<< HEAD
|
||||
Desen: `persistent://tg/flow/<topic>:{id}`
|
||||
=======
|
||||
Kalıp: `persistent://tg/flow/<topic>:{id}`
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Ateşle ve unut hizmetleri ve dayanıklı veri akışı için kullanılır
|
||||
Veri, yeniden başlatmalarda Pulsar depolama alanında kalıcıdır
|
||||
Örnek: `persistent://tg/flow/chunk-load:{id}`
|
||||
|
||||
### Kalıcı Olmayan Kuyruklar
|
||||
<<<<<<< HEAD
|
||||
Desen: `non-persistent://tg/request/<topic>:{class}` veya `non-persistent://tg/response/<topic>:{class}`
|
||||
İstek/yanıt mesajlaşma desenleri için kullanılır
|
||||
=======
|
||||
Kalıp: `non-persistent://tg/request/<topic>:{class}` veya `non-persistent://tg/response/<topic>:{class}`
|
||||
İstek/yanıt mesajlaşma kalıpları için kullanılır
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Pulsar tarafından diske kalıcı hale getirilmez, geçicidir
|
||||
Daha düşük gecikme süresi, RPC tarzı iletişim için uygundur
|
||||
Örnek: `non-persistent://tg/request/embeddings:{class}`
|
||||
|
||||
## Veri Akışı Mimarisi
|
||||
|
||||
<<<<<<< HEAD
|
||||
Akış tanımı, aşağıdaki gibi birleşik bir veri akışı oluşturur:
|
||||
=======
|
||||
Akış tanımı, aşağıdaki unsurları içeren birleşik bir veri akışı oluşturur:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
1. **Belge İşleme Hattı**: Alımdan dönüşüme ve depolamaya kadar olan akış
|
||||
2. **Sorgu Hizmetleri**: Aynı veri depolarını ve hizmetlerini sorgulayan entegre işlemciler
|
||||
3. **Paylaşımlı Hizmetler**: Tüm akışların kullanabileceği merkezi işlemciler
|
||||
4. **Depolama Yazıcıları**: İşlenmiş verileri uygun depolama alanlarına kaydeder
|
||||
|
||||
Tüm işlemciler (hem `{id}` hem de `{class}`), ayrı sistemler olarak değil, uyumlu bir veri akışı grafiği olarak birlikte çalışır.
|
||||
|
||||
## Örnek Akış Oluşturma
|
||||
|
||||
Verilenler:
|
||||
Akış Örneği Kimliği: `customer-A-flow`
|
||||
Akış Tanımı: `standard-rag`
|
||||
Akış parametre eşlemeleri:
|
||||
`"model": "llm-model"`
|
||||
`"temp": "temperature"`
|
||||
`"chunk": "chunk-size"`
|
||||
Kullanıcı tarafından sağlanan parametreler:
|
||||
`model`: `gpt-4`
|
||||
`temp`: `0.5`
|
||||
`chunk`: `512`
|
||||
|
||||
Şablon genişletmeleri:
|
||||
`persistent://tg/flow/chunk-load:{id}` → `persistent://tg/flow/chunk-load:customer-A-flow`
|
||||
`non-persistent://tg/request/embeddings:{class}` → `non-persistent://tg/request/embeddings:standard-rag`
|
||||
`"model": "{model}"` → `"model": "gpt-4"`
|
||||
`"temperature": "{temp}"` → `"temperature": "0.5"`
|
||||
`"chunk_size": "{chunk}"` → `"chunk_size": "512"`
|
||||
|
||||
Bu, aşağıdaki öğeleri oluşturur:
|
||||
`customer-A-flow` için izole edilmiş belge işleme hattı
|
||||
<<<<<<< HEAD
|
||||
Tüm `standard-rag` akışları için paylaşımlı gömme hizmeti
|
||||
Belge alımından sorgulamaya kadar olan eksiksiz veri akışı
|
||||
İşlemciler, sağlanan parametre değerleriyle yapılandırılmıştır
|
||||
=======
|
||||
tüm `standard-rag` akışları için paylaşımlı gömme hizmeti
|
||||
Belge alımından sorgulamaya kadar olan eksiksiz veri akışı
|
||||
İşlemcilerin sağlanan parametre değerleriyle yapılandırılması
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Avantajlar
|
||||
|
||||
1. **Kaynak Verimliliği**: Pahalı hizmetler, akışlar arasında paylaşılır
|
||||
2. **Akış İzolasyonu**: Her akışın kendi veri işleme hattı vardır
|
||||
<<<<<<< HEAD
|
||||
3. **Ölçeklenebilirlik**: Aynı şablondan birden fazla akış oluşturulabilir
|
||||
4. **Modülerlik**: Paylaşılan ve akışa özgü bileşenler arasında net bir ayrım
|
||||
5. **Bütünleşik Mimari**: Sorgu ve işleme, aynı veri akışının bir parçasıdır
|
||||
=======
|
||||
3. **Ölçeklenebilirlik**: Aynı şablondan çok sayıda akış oluşturulabilir
|
||||
4. **Modülerlik**: Paylaşılan ve akışa özgü bileşenler arasında net bir ayrım
|
||||
5. **Birleşik Mimari**: Sorgu ve işleme, aynı veri akışının bir parçasıdır
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
633
docs/tech-specs/tr/flow-configurable-parameters.tr.md
Normal file
633
docs/tech-specs/tr/flow-configurable-parameters.tr.md
Normal file
|
|
@ -0,0 +1,633 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Akış Şeması Yapılandırılabilir Parametreler Teknik Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Akış Şeması Yapılandırılabilir Parametreler 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'taki akış şemaları için yapılandırılabilir parametrelerin uygulanmasını açıklamaktadır. Parametreler, kullanıcıların akış başlatma zamanında işlemci parametrelerini, akış şeması tanımındaki parametre yer tutucularını değiştiren değerler sağlayarak özelleştirmesini sağlar.
|
||||
|
||||
<<<<<<< HEAD
|
||||
Parametreler, işlemci parametrelerinde şablon değişken yerleştirmesi yoluyla çalışır, tıpkı `{id}` ve `{class}` değişkenlerinin nasıl çalıştığı gibi, ancak kullanıcı tarafından sağlanan değerlerle.
|
||||
=======
|
||||
Parametreler, `{id}` ve `{class}` değişkenlerinin nasıl çalıştığına benzer şekilde, işlemci parametrelerinde şablon değişken yerleştirmesi yoluyla çalışır, ancak kullanıcı tarafından sağlanan değerlerle.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
Bu entegrasyon, dört birincil kullanım senaryosunu destekler:
|
||||
|
||||
1. **Model Seçimi**: Kullanıcıların farklı LLM modellerini (örneğin, `gemma3:8b`, `gpt-4`, `claude-3`) işlemciler için seçmesine izin verme.
|
||||
2. **Kaynak Yapılandırması**: Parça boyutları, toplu boyutlar ve eşzamanlılık limitleri gibi işlemci parametrelerini ayarlama.
|
||||
3. **Davranış Ayarı**: Sıcaklık, maksimum-token veya alma eşikleri gibi parametreler aracılığıyla işlemci davranışını değiştirme.
|
||||
4. **Ortama Özgü Parametreler**: Dağıtım başına uç noktaları, API anahtarlarını veya bölgeye özgü URL'leri yapılandırma.
|
||||
|
||||
## Hedefler
|
||||
|
||||
**Dinamik İşlemci Yapılandırması**: Parametre yerleştirmesi yoluyla işlemci parametrelerinin çalışma zamanı yapılandırmasını etkinleştirme.
|
||||
**Parametre Doğrulama**: Akış başlatma zamanında parametreler için tür denetimi ve doğrulama sağlama.
|
||||
<<<<<<< HEAD
|
||||
**Varsayılan Değerler**: Akıllı varsayılan değerleri destekleme ve aynı zamanda gelişmiş kullanıcılar için geçersiz kılmalara izin verme.
|
||||
**Şablon Yerleştirmesi**: İşlemci parametrelerindeki parametre yer tutucularını sorunsuz bir şekilde değiştirme.
|
||||
**Kullanıcı Arayüzü Entegrasyonu**: Parametre girişini hem API hem de kullanıcı arayüzü arayüzleri aracılığıyla etkinleştirme.
|
||||
**Tür Güvenliği**: Parametre türlerinin beklenen işlemci parametre türleriyle eşleştiğinden emin olma.
|
||||
**Belgeleme**: Akış şeması tanımları içindeki kendi kendini belgeleyen parametre şemaları.
|
||||
**Geriye Dönük Uyumluluk**: Parametre kullanmayan mevcut akış şemalarıyla uyumluluğu koruma.
|
||||
=======
|
||||
**Varsayılan Değerler**: Gelişmiş kullanıcılar için geçersiz kılmaları desteklerken anlamlı varsayılan değerleri destekleme.
|
||||
**Şablon Yerleştirmesi**: İşlemci parametrelerindeki parametre yer tutucularını sorunsuz bir şekilde değiştirme.
|
||||
**Kullanıcı Arayüzü Entegrasyonu**: Hem API hem de kullanıcı arayüzü arayüzleri aracılığıyla parametre girişi sağlama.
|
||||
**Tür Güvenliği**: Parametre türlerinin beklenen işlemci parametre türleriyle eşleştiğinden emin olma.
|
||||
**Belgeleme**: Akış şeması tanımları içindeki kendi kendini belgeleyen parametre şemaları.
|
||||
**Geriye Dönük Uyumluluk**: Parametreleri kullanmayan mevcut akış şemalarıyla uyumluluğu koruma.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Arka Plan
|
||||
|
||||
TrustGraph'taki akış şemaları artık, sabit değerler veya parametre yer tutucuları içerebilen işlemci parametrelerini desteklemektedir. Bu, çalışma zamanı özelleştirmesi için bir fırsat yaratır.
|
||||
|
||||
<<<<<<< HEAD
|
||||
Mevcut işlemci parametreleri şunları desteklemektedir:
|
||||
Sabit değerler: `"model": "gemma3:12b"`
|
||||
Parametre yer tutucuları: `"model": "gemma3:{model-size}"`
|
||||
|
||||
Bu özellik, parametrelerin nasıl olduğu tanımlamaktadır:
|
||||
Akış şeması tanımlarında beyan edilmesi
|
||||
Akışların başlatıldığı zaman doğrulanması
|
||||
İşlemci parametrelerinde yerleştirilmesi
|
||||
API'ler ve kullanıcı arayüzü aracılığıyla açığa çıkarılması
|
||||
|
||||
Parametreli işlemci parametrelerini kullanarak, TrustGraph şunları yapabilir:
|
||||
Varyasyonlar için parametreleri kullanarak akış şeması çoğaltmasını azaltma.
|
||||
Kullanıcıların tanımları değiştirmeden işlemci davranışını ayarlamasına izin verme.
|
||||
Parametre değerleri aracılığıyla ortama özgü yapılandırmaları destekleme.
|
||||
Parametre şema doğrulaması yoluyla tür güvenliğini sağlama.
|
||||
=======
|
||||
Mevcut işlemci parametreleri şunları destekler:
|
||||
Sabit değerler: `"model": "gemma3:12b"`
|
||||
Parametre yer tutucuları: `"model": "gemma3:{model-size}"`
|
||||
|
||||
Bu özellik, parametrelerin nasıl olduğu tanımlar:
|
||||
Akış şeması tanımlarında beyan edilir
|
||||
Akışlar başlatıldığında doğrulanır
|
||||
İşlemci parametrelerinde yerleştirilir
|
||||
API'ler ve kullanıcı arayüzleri aracılığıyla açığa çıkarılır
|
||||
|
||||
Parametreli işlemci parametrelerini kullanarak, TrustGraph şunları yapabilir:
|
||||
Varyasyonlar için parametreleri kullanarak akış şeması çoğaltmasını azaltma
|
||||
Kullanıcıların tanımları değiştirmeden işlemci davranışını ayarlamasına izin verme
|
||||
Parametre değerleri aracılığıyla ortama özgü yapılandırmaları destekleme
|
||||
Parametre şema doğrulaması yoluyla tür güvenliğini sağlama
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Teknik Tasarım
|
||||
|
||||
### Mimari
|
||||
|
||||
<<<<<<< HEAD
|
||||
Yapılandırılabilir parametreler sistemi, aşağıdaki teknik bileşenleri gerektirmektedir:
|
||||
|
||||
1. **Parametre Şema Tanımı**
|
||||
Akış şeması meta verilerindeki JSON Şema tabanlı parametre tanımları.
|
||||
Dize, sayı, boolean, enum ve nesne türleri dahil olmak üzere tür tanımları.
|
||||
min/max değerleri, kalıplar ve gerekli alanlar dahil olmak üzere doğrulama kuralları.
|
||||
|
||||
Modül: trustgraph-flow/trustgraph/flow/definition.py
|
||||
|
||||
2. **Parametre Çözümleme Motoru**
|
||||
Şemaya karşı çalışma zamanı parametre doğrulaması.
|
||||
Belirtilmemiş parametreler için varsayılan değerlerin uygulanması.
|
||||
Parametrelerin akış yürütme bağlamına enjekte edilmesi.
|
||||
Gerekli olduğu gibi tür dönüştürme ve dönüştürme.
|
||||
=======
|
||||
Yapılandırılabilir parametreler sistemi, aşağıdaki teknik bileşenleri gerektirir:
|
||||
|
||||
1. **Parametre Şema Tanımı**
|
||||
Akış şeması meta verilerindeki JSON Şema tabanlı parametre tanımları
|
||||
Dize, sayı, boolean, enum ve nesne türleri dahil olmak üzere tür tanımları
|
||||
min/max değerleri, kalıplar ve gerekli alanlar dahil olmak üzere doğrulama kuralları
|
||||
|
||||
Modül: trustgraph-flow/trustgraph/flow/definition.py
|
||||
|
||||
2. **Parametre Çözümleyici Motoru**
|
||||
Şemaya karşı çalışma zamanı parametre doğrulaması
|
||||
Belirtilmemiş parametreler için varsayılan değer uygulaması
|
||||
Parametreleri akış yürütme bağlamına enjekte etme
|
||||
Gerekli olduğu gibi tür dönüştürme ve dönüştürme
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
Modül: trustgraph-flow/trustgraph/flow/parameter_resolver.py
|
||||
|
||||
3. **Parametre Deposu Entegrasyonu**
|
||||
<<<<<<< HEAD
|
||||
Şema/yapılandırma deposundan parametre tanımlarının alınması.
|
||||
Sık kullanılan parametre tanımlarının önbelleğe alınması.
|
||||
Merkezi olarak depolanan şemalara karşı doğrulama.
|
||||
=======
|
||||
Şema/yapılandırma deposundan parametre tanımlarının alınması
|
||||
Sık kullanılan parametre tanımlarının önbelleğe alınması
|
||||
Merkezi olarak depolanan şemalara karşı doğrulama
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
Modül: trustgraph-flow/trustgraph/flow/parameter_store.py
|
||||
|
||||
4. **Akış Başlatıcı Uzantıları**
|
||||
<<<<<<< HEAD
|
||||
Akış başlatma sırasında parametre değerlerini kabul etmek için API uzantıları.
|
||||
Parametre eşleme çözümü (akış adlarının tanım adlarına eşlenmesi).
|
||||
Geçersiz parametre kombinasyonları için hata işleme.
|
||||
=======
|
||||
Akış başlatma sırasında parametre değerlerini kabul etmek için API uzantıları
|
||||
Parametre eşleme çözümü (akış adlarının tanım adlarına eşlenmesi)
|
||||
Geçersiz parametre kombinasyonları için hata işleme
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
Modül: trustgraph-flow/trustgraph/flow/launcher.py
|
||||
|
||||
5. **Kullanıcı Arayüzü Parametre Formları**
|
||||
<<<<<<< HEAD
|
||||
Akış parametre meta verilerinden dinamik form oluşturma.
|
||||
`order` alanı kullanarak sıralı parametre görüntüleme.
|
||||
`description` alanı kullanarak açıklayıcı parametre etiketleri.
|
||||
Parametre türü tanımlarına karşı giriş doğrulaması.
|
||||
Parametre ön ayarları ve şablonları.
|
||||
=======
|
||||
Akış parametre meta verilerinden dinamik form oluşturma
|
||||
`order` alanı kullanarak sıralı parametre görüntüleme
|
||||
`description` alanı kullanarak açıklayıcı parametre etiketleri
|
||||
Parametre türü tanımlarına karşı giriş doğrulaması
|
||||
Parametre ön ayarları ve şablonları
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
Modül: trustgraph-ui/components/flow-parameters/
|
||||
|
||||
### Veri Modelleri
|
||||
|
||||
#### Parametre Tanımları (Şema/Yapılandırmada Saklanır)
|
||||
|
||||
Parametre tanımları, "parameter-type" türüyle şema ve yapılandırma sisteminde merkezi olarak saklanır:
|
||||
|
||||
```json
|
||||
{
|
||||
"llm-model": {
|
||||
"type": "string",
|
||||
"description": "LLM model to use",
|
||||
"default": "gpt-4",
|
||||
"enum": [
|
||||
{
|
||||
"id": "gpt-4",
|
||||
"description": "OpenAI GPT-4 (Most Capable)"
|
||||
},
|
||||
{
|
||||
"id": "gpt-3.5-turbo",
|
||||
"description": "OpenAI GPT-3.5 Turbo (Fast & Efficient)"
|
||||
},
|
||||
{
|
||||
"id": "claude-3",
|
||||
"description": "Anthropic Claude 3 (Thoughtful & Safe)"
|
||||
},
|
||||
{
|
||||
"id": "gemma3:8b",
|
||||
"description": "Google Gemma 3 8B (Open Source)"
|
||||
}
|
||||
],
|
||||
"required": false
|
||||
},
|
||||
"model-size": {
|
||||
"type": "string",
|
||||
"description": "Model size variant",
|
||||
"default": "8b",
|
||||
"enum": ["2b", "8b", "12b", "70b"],
|
||||
"required": false
|
||||
},
|
||||
"temperature": {
|
||||
"type": "number",
|
||||
"description": "Model temperature for generation",
|
||||
"default": 0.7,
|
||||
"minimum": 0.0,
|
||||
"maximum": 2.0,
|
||||
"required": false
|
||||
},
|
||||
"chunk-size": {
|
||||
"type": "integer",
|
||||
"description": "Document chunk size",
|
||||
"default": 512,
|
||||
"minimum": 128,
|
||||
"maximum": 2048,
|
||||
"required": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Parametre Referanslarıyla Akış Şeması
|
||||
|
||||
Akış şemaları, tür referansları, açıklamalar ve sıralama ile parametre meta verilerini tanımlar:
|
||||
|
||||
```json
|
||||
{
|
||||
"flow_class": "document-analysis",
|
||||
"parameters": {
|
||||
"llm-model": {
|
||||
"type": "llm-model",
|
||||
"description": "Primary LLM model for text completion",
|
||||
"order": 1
|
||||
},
|
||||
"llm-rag-model": {
|
||||
"type": "llm-model",
|
||||
"description": "LLM model for RAG operations",
|
||||
"order": 2,
|
||||
"advanced": true,
|
||||
"controlled-by": "llm-model"
|
||||
},
|
||||
"llm-temperature": {
|
||||
"type": "temperature",
|
||||
"description": "Generation temperature for creativity control",
|
||||
"order": 3,
|
||||
"advanced": true
|
||||
},
|
||||
"chunk-size": {
|
||||
"type": "chunk-size",
|
||||
"description": "Document chunk size for processing",
|
||||
"order": 4,
|
||||
"advanced": true
|
||||
},
|
||||
"chunk-overlap": {
|
||||
"type": "integer",
|
||||
"description": "Overlap between document chunks",
|
||||
"order": 5,
|
||||
"advanced": true,
|
||||
"controlled-by": "chunk-size"
|
||||
}
|
||||
},
|
||||
"class": {
|
||||
"text-completion:{class}": {
|
||||
"request": "non-persistent://tg/request/text-completion:{class}",
|
||||
"response": "non-persistent://tg/response/text-completion:{class}",
|
||||
"parameters": {
|
||||
"model": "{llm-model}",
|
||||
"temperature": "{llm-temperature}"
|
||||
}
|
||||
},
|
||||
"rag-completion:{class}": {
|
||||
"request": "non-persistent://tg/request/rag-completion:{class}",
|
||||
"response": "non-persistent://tg/response/rag-completion:{class}",
|
||||
"parameters": {
|
||||
"model": "{llm-rag-model}",
|
||||
"temperature": "{llm-temperature}"
|
||||
}
|
||||
}
|
||||
},
|
||||
"flow": {
|
||||
"chunker:{id}": {
|
||||
"input": "persistent://tg/flow/chunk:{id}",
|
||||
"output": "persistent://tg/flow/chunk-load:{id}",
|
||||
"parameters": {
|
||||
"chunk_size": "{chunk-size}",
|
||||
"chunk_overlap": "{chunk-overlap}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`parameters` bölümü, akışa özgü parametre adlarını (anahtarları), parametre meta veri nesnelerine eşler ve bu nesneler şunları içerir:
|
||||
`type`: Merkezi olarak tanımlanmış parametre tanımına referans (örneğin, "llm-model")
|
||||
`description`: Kullanıcı arayüzünde (UI) görüntülenmesi için insan tarafından okunabilir açıklama
|
||||
`order`: Parametre formları için görüntüleme sırası (daha düşük sayılar önce görüntülenir)
|
||||
<<<<<<< HEAD
|
||||
`advanced` (isteğe bağlı): Bu parametrenin gelişmiş bir parametre olup olmadığını gösteren bir boolean bayrak (varsayılan: false). "true" olarak ayarlandığında, kullanıcı arayüzü bu parametreyi varsayılan olarak gizleyebilir veya "Gelişmiş" bölümünde yer almasını sağlayabilir
|
||||
=======
|
||||
`advanced` (isteğe bağlı): Bu parametrenin gelişmiş bir parametre olup olmadığını gösteren bir bayrak (varsayılan: false). "true" olarak ayarlandığında, kullanıcı arayüzü bu parametreyi varsayılan olarak gizleyebilir veya "Gelişmiş" bölümünde yer almasını sağlayabilir
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
`controlled-by` (isteğe bağlı): Basit moddayken bu parametrenin değerini kontrol eden başka bir parametrenin adı. Belirtildiğinde, bu parametre açıkça geçersiz kılmadığı sürece, kontrol eden parametreden değerini alır
|
||||
|
||||
Bu yaklaşım şunları sağlar:
|
||||
Birden çok akış şablonu arasında yeniden kullanılabilir parametre türü tanımları
|
||||
Merkezi parametre türü yönetimi ve doğrulaması
|
||||
Akışa özgü parametre açıklamaları ve sıralaması
|
||||
Açıklayıcı parametre formlarıyla geliştirilmiş kullanıcı arayüzü deneyimi
|
||||
Akışlar genelinde tutarlı parametre doğrulaması
|
||||
Yeni standart parametre türlerinin kolayca eklenmesi
|
||||
Temel/gelişmiş mod ayrımıyla basitleştirilmiş kullanıcı arayüzü
|
||||
İlgili ayarlar için parametre değeri devralımı
|
||||
|
||||
#### Akış Başlatma İsteği
|
||||
|
||||
Akış başlatma API'si, parametreleri akışın parametre adlarını kullanarak alır:
|
||||
|
||||
```json
|
||||
{
|
||||
"flow_class": "document-analysis",
|
||||
"flow_id": "customer-A-flow",
|
||||
"parameters": {
|
||||
"llm-model": "claude-3",
|
||||
"llm-temperature": 0.5,
|
||||
"chunk-size": 1024
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
Not: Bu örnekte, `llm-rag-model` açıkça belirtilmemiştir, ancak `controlled-by` ilişkisi nedeniyle `llm-model`'den "claude-3" değerini miras alacaktır. Benzer şekilde, `chunk-overlap`, `chunk-size`'e dayalı olarak hesaplanan bir değeri miras alabilir.
|
||||
=======
|
||||
Not: Bu örnekte, `llm-rag-model` açıkça belirtilmemiştir, ancak `controlled-by` ilişkisi nedeniyle `llm-model`'den "claude-3" değerini alacaktır. Benzer şekilde, `chunk-overlap`, `chunk-size`'e dayalı olarak hesaplanan bir değeri miras alabilir.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
Sistem şunları yapacaktır:
|
||||
1. Akış tanımından parametre meta verilerini çıkarın
|
||||
2. Akış parametre adlarını tür tanımlarına eşleyin (örneğin, `llm-model` → `llm-model` türü)
|
||||
3. "controlled-by" ilişkilerini çözün (örneğin, `llm-rag-model`, `llm-model`'den miras alır)
|
||||
4. Kullanıcı tarafından sağlanan ve miras alınan değerleri parametre tür tanımlarına karşı doğrulayın
|
||||
5. Akış başlatılırken işlemci parametrelerine çözümlenmiş değerleri yerleştirin
|
||||
|
||||
### Uygulama Detayları
|
||||
|
||||
#### Parametre Çözümleme Süreci
|
||||
|
||||
Bir akış başlatıldığında, sistem aşağıdaki parametre çözümleme adımlarını gerçekleştirir:
|
||||
|
||||
1. **Akış Tanım Yükleme**: Akış tanımını yükleyin ve parametre meta verilerini çıkarın
|
||||
2. **Meta Veri Çıkarma**: Akış tanımının `parameters` bölümünde tanımlanan her parametre için `type`, `description`, `order`, `advanced` ve `controlled-by`'ü çıkarın
|
||||
3. **Tür Tanımı Arama**: Akış tanımındaki her parametre için:
|
||||
`type` alanı kullanılarak şema/yapılandırma deposundan parametre tür tanımını alın
|
||||
<<<<<<< HEAD
|
||||
Tür tanımları, yapılandırma sisteminde "parameter-type" türüyle saklanır
|
||||
=======
|
||||
Tür tanımları, yapılandırma sisteminde "parameter-type" türü ile saklanır
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Her tür tanımı, parametrenin şemasını, varsayılan değerini ve doğrulama kurallarını içerir
|
||||
4. **Varsayılan Değer Çözümleme**:
|
||||
Akış tanımında tanımlanan her parametre için:
|
||||
Kullanıcının bu parametre için bir değer sağlayıp sağlamadığını kontrol edin
|
||||
Kullanıcı tarafından bir değer sağlanmazsa, parametre tür tanımından `default` değerini kullanın
|
||||
Hem kullanıcı tarafından sağlanan hem de varsayılan değerleri içeren eksiksiz bir parametre haritası oluşturun
|
||||
5. **Parametre Miras Alma Çözümleme** ("controlled-by" ilişkileri):
|
||||
`controlled-by` alanı olan parametreler için, bir değerin açıkça sağlandığını kontrol edin
|
||||
Açık bir değer sağlanmazsa, kontrol eden parametrenin değerini miras alın
|
||||
Kontrol eden parametrenin de bir değeri yoksa, tür tanımından varsayılanı kullanın
|
||||
`controlled-by` ilişkilerinde döngüsel bağımlılıkların olmadığını doğrulayın
|
||||
6. **Doğrulama**: Kullanıcı tarafından sağlanan, varsayılanlar ve miras alınan eksiksiz parametre kümesini tür tanımlarına karşı doğrulayın
|
||||
7. **Saklama**: Eksiksiz çözümlenmiş parametre kümesini denetlenebilirlik için akış örneğiyle birlikte saklayın
|
||||
<<<<<<< HEAD
|
||||
8. **Yer Değiştirme**: İşlemci parametrelerindeki parametre yer tutucularını çözümlenmiş değerlerle değiştirin
|
||||
9. **İşlemci Oluşturma**: Yer değiştirilmiş parametrelerle işlemciler oluşturun
|
||||
=======
|
||||
8. **Şablon Yerine Koyma**: İşlemci parametrelerindeki parametre yer tutucularını çözümlenmiş değerlerle değiştirin
|
||||
9. **İşlemci Oluşturma**: Yerine konulan parametrelerle işlemcileri oluşturun
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**Önemli Uygulama Notları:**
|
||||
Akış hizmeti, kullanıcı tarafından sağlanan parametreleri parametre tür tanımlarından gelen varsayılanlarla birleştirmelidir
|
||||
Uygulanan varsayılanlar dahil eksiksiz parametre kümesi, izlenebilirlik için akışla birlikte saklanmalıdır
|
||||
Parametre çözümlemesi, akış başlatma zamanında değil, işlemci oluşturma zamanında gerçekleşir
|
||||
<<<<<<< HEAD
|
||||
Varsayılanları olmayan gerekli parametrelerin eksik olması, akışın başlatılmasını açık bir hata mesajıyla başarısız olmasına neden olmalıdır
|
||||
|
||||
#### "controlled-by" ile Parametre Miras Alma
|
||||
|
||||
`controlled-by` alanı, parametre değerlerinin miras alınmasını sağlar; bu, kullanıcı arayüzlerini basitleştirirken esnekliği korumak için özellikle kullanışlıdır:
|
||||
=======
|
||||
Varsayılanları olmayan gerekli parametrelerin eksik olması, akışın başlatılmasını açık bir hata mesajıyla başarısız yapmasına neden olmalıdır
|
||||
|
||||
#### "controlled-by" ile Parametre Miras Alma
|
||||
|
||||
`controlled-by` alanı, parametre değerlerinin miras alınmasını sağlar ve kullanıcı arayüzlerini basitleştirirken esnekliği korumak için özellikle kullanışlıdır:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**Örnek Senaryo**:
|
||||
`llm-model` parametresi birincil LLM modelini kontrol eder
|
||||
`llm-rag-model` parametresi `"controlled-by": "llm-model"`'e sahiptir
|
||||
Basit modda, `llm-model`'ı "gpt-4" olarak ayarlamak, otomatik olarak `llm-rag-model`'i de "gpt-4" olarak ayarlar
|
||||
Gelişmiş modda, kullanıcılar `llm-rag-model`'ı farklı bir değerle geçersiz kılabilir
|
||||
|
||||
**Çözüm Kuralları**:
|
||||
1. Bir parametrenin açıkça sağlanan bir değeri varsa, o değeri kullanın
|
||||
2. Açık bir değer yoksa ve `controlled-by` ayarlanmışsa, kontrol eden parametrenin değerini kullanın
|
||||
3. Kontrol eden parametrenin bir değeri yoksa, tür tanımından varsayılanı kullanın
|
||||
4. `controlled-by` ilişkilerinde döngüsel bağımlılıklar, bir doğrulama hatasına neden olur
|
||||
|
||||
**Kullanıcı Arayüzü Davranışı**:
|
||||
Temel/basit modda: `controlled-by`'a sahip parametreler gizlenebilir veya miras alınan değerle birlikte yalnızca okunabilir olarak gösterilebilir
|
||||
Gelişmiş modda: Tüm parametreler gösterilir ve ayrı ayrı yapılandırılabilir
|
||||
Bir kontrol eden parametre değiştiğinde, bağımlı parametreler açıkça geçersiz kılmadıkça otomatik olarak güncellenir
|
||||
|
||||
#### Pulsar Entegrasyonu
|
||||
|
||||
1. **Akışı Başlatma İşlemi**
|
||||
Pulsar akışı başlatma işlemi, parametre değerlerinin bir haritasını içeren bir `parameters` alanı almalıdır
|
||||
<<<<<<< HEAD
|
||||
Pulsar için akış başlatma isteği şeması, isteğe bağlı `parameters` alanını içerecek şekilde güncellenmelidir
|
||||
=======
|
||||
Pulsar'ın akışı başlatma isteği şeması, isteğe bağlı `parameters` alanını içerecek şekilde güncellenmelidir
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Örnek istek:
|
||||
```json
|
||||
{
|
||||
"flow_class": "document-analysis",
|
||||
"flow_id": "customer-A-flow",
|
||||
"parameters": {
|
||||
"model": "claude-3",
|
||||
"size": "12b",
|
||||
"temp": 0.5,
|
||||
"chunk": 1024
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Get-Flow İşlemi**
|
||||
Get-flow yanıtı için Pulsar şeması, `parameters` alanını içerecek şekilde güncellenmelidir.
|
||||
Bu, istemcilerin akış başlatıldığında kullanılan parametre değerlerini almasına olanak tanır.
|
||||
Örnek yanıt:
|
||||
```json
|
||||
{
|
||||
"flow_id": "customer-A-flow",
|
||||
"flow_class": "document-analysis",
|
||||
"status": "running",
|
||||
"parameters": {
|
||||
"model": "claude-3",
|
||||
"size": "12b",
|
||||
"temp": 0.5,
|
||||
"chunk": 1024
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Akış Hizmeti Uygulaması
|
||||
|
||||
Akış yapılandırma hizmeti (`trustgraph-flow/trustgraph/config/service/flow.py`), aşağıdaki geliştirmeleri gerektirmektedir:
|
||||
|
||||
1. **Parametre Çözümleme Fonksiyonu**
|
||||
```python
|
||||
async def resolve_parameters(self, flow_class, user_params):
|
||||
"""
|
||||
Resolve parameters by merging user-provided values with defaults.
|
||||
|
||||
Args:
|
||||
flow_class: The flow blueprint definition dict
|
||||
user_params: User-provided parameters dict
|
||||
|
||||
Returns:
|
||||
Complete parameter dict with user values and defaults merged
|
||||
"""
|
||||
```
|
||||
|
||||
Bu fonksiyonun yapması gerekenler:
|
||||
Akış şemasının `parameters` bölümünden parametre meta verilerini çıkarın
|
||||
Her parametre için, yapılandırma deposundan tür tanımını alın
|
||||
Kullanıcı tarafından sağlanmayan parametreler için varsayılan değerleri uygulayın
|
||||
`controlled-by` miras ilişkilerini işleyin
|
||||
Tam parametre kümesini döndürün
|
||||
|
||||
2. **Değiştirilen `handle_start_flow` Metodu**
|
||||
Akış şemasını yükledikten sonra `resolve_parameters`'ı çağırın
|
||||
<<<<<<< HEAD
|
||||
Şablon yerleştirmesi için tam olarak çözülmüş parametre kümesini kullanın
|
||||
Tam parametre kümesini (yalnızca kullanıcı tarafından sağlananları değil) akışla birlikte kaydedin
|
||||
=======
|
||||
Şablon yerleştirmesi için eksiksiz çözülmüş parametre kümesini kullanın
|
||||
Eksiksiz parametre kümesini (yalnızca kullanıcı tarafından sağlananları değil) akışla birlikte kaydedin
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Tüm gerekli parametrelerin değerlere sahip olduğundan emin olun
|
||||
|
||||
3. **Parametre Türü Alma**
|
||||
Parametre tür tanımları, "parameter-type" türüyle yapılandırmada saklanır
|
||||
Her tür tanımı, şema, varsayılan değer ve doğrulama kurallarını içerir
|
||||
Sık kullanılan parametre türlerini önbelleğe alın, böylece yapılandırma aramaları azalır
|
||||
|
||||
#### Yapılandırma Sistemi Entegrasyonu
|
||||
|
||||
<<<<<<< HEAD
|
||||
3. **Akış Nesne Saklama**
|
||||
Bir akış, yapılandırma yöneticisindeki akış bileşeni tarafından yapılandırma sistemine eklendiğinde, akış nesnesi çözülmüş parametre değerlerini içermelidir
|
||||
Yapılandırma yöneticisi hem orijinal kullanıcı tarafından sağlanan parametreleri hem de çözülmüş değerleri (varsayılanlar uygulandıktan sonra) saklamalıdır
|
||||
=======
|
||||
3. **Akış Nesnesi Depolama**
|
||||
Bir akış, yapılandırma yöneticisindeki akış bileşeni tarafından yapılandırma sistemine eklendiğinde, akış nesnesi çözülmüş parametre değerlerini içermelidir
|
||||
Yapılandırma yöneticisi hem orijinal kullanıcı tarafından sağlanan parametreleri hem de çözülmüş değerleri (varsayılanlar uygulandıktan sonra) depolamalıdır
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Yapılandırma sistemindeki akış nesneleri şunları içermelidir:
|
||||
`parameters`: Akış için kullanılan son çözülmüş parametre değerleri
|
||||
|
||||
#### CLI Entegrasyonu
|
||||
|
||||
4. **Kütüphane CLI Komutları**
|
||||
Akışları başlatan CLI komutları parametre desteğine sahip olmalıdır:
|
||||
<<<<<<< HEAD
|
||||
Parametre değerlerini komut satırı bayrakları veya yapılandırma dosyaları aracılığıyla alın
|
||||
=======
|
||||
Parametre değerlerini komut satırı bayrakları veya yapılandırma dosyaları aracılığıyla kabul edin
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Parametreleri göndermeden önce akış şema tanımlarına göre doğrulayın
|
||||
Karmaşık parametre kümeleri için parametre dosyası girişini (JSON/YAML) destekleyin
|
||||
|
||||
Akışları gösteren CLI komutları parametre bilgilerini görüntülemelidir:
|
||||
Akış başlatıldığında kullanılan parametre değerlerini gösterin
|
||||
Bir akış şeması için mevcut parametreleri görüntüleyin
|
||||
Parametre doğrulama şemalarını ve varsayılanları gösterin
|
||||
|
||||
#### İşlemci Temel Sınıf Entegrasyonu
|
||||
|
||||
5. **ParameterSpec Desteği**
|
||||
İşlemci temel sınıfları, mevcut ParametersSpec mekanizması aracılığıyla parametre yerleştirmesini desteklemelidir
|
||||
<<<<<<< HEAD
|
||||
ParametersSpec sınıfı (ConsumerSpec ve ProducerSpec ile aynı modülde bulunur), parametre şablonu yerleştirmesini desteklemek için gerekirse geliştirilmelidir
|
||||
İşlemciler, parametre değerlerini akış başlatma zamanında çözerek parametrelerini yapılandırmak için ParametersSpec'i çağırabilmelidir
|
||||
=======
|
||||
ParameterSpec sınıfı (ConsumerSpec ve ProducerSpec ile aynı modülde bulunur), parametre şablonu yerleştirmesini desteklemek için gerekirse geliştirilmelidir
|
||||
İşlemciler, parametre değerlerini akış başlatma zamanında çözülmüş olarak parametreleriyle yapılandırmak için ParametersSpec'i çağırmalıdır
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
ParametersSpec uygulaması şunları yapmalıdır:
|
||||
Parametre yer tutucuları (örneğin, `{model}`, `{temperature}`) içeren parametre yapılandırmalarını kabul edin
|
||||
İşlemci örneklendiğinde çalışma zamanında parametre yerleştirmesini destekleyin
|
||||
Yerleştirilen değerlerin beklenen türlere ve kısıtlamalara uyduğunu doğrulayın
|
||||
Eksik veya geçersiz parametre başvuruları için hata işleme sağlayın
|
||||
|
||||
#### Yerleştirme Kuralları
|
||||
|
||||
Parametreler, işlemci parametrelerinde `{parameter-name}` biçimini kullanır
|
||||
Parametrelerdeki parametre adları, akışın `parameters` bölümündeki anahtarlarla eşleşir
|
||||
Yerleştirme, `{id}` ve `{class}` değiştirme ile birlikte gerçekleşir
|
||||
Geçersiz parametre başvuruları, başlatma zamanı hatalarına neden olur
|
||||
Tür doğrulama, merkezi olarak depolanan parametre tanımına göre yapılır
|
||||
**ÖNEMLİ**: Tüm parametre değerleri dize olarak saklanır ve iletilir
|
||||
<<<<<<< HEAD
|
||||
Sayılar dizeye dönüştürülür (örneğin, `0.7` `"0.7"` olur)
|
||||
Boole değerleri küçük harfli dizeye dönüştürülür (örneğin, `true` `"true"` olur)
|
||||
=======
|
||||
Sayılar dizelere dönüştürülür (örneğin, `0.7` `"0.7"` olur)
|
||||
Boolean değerler küçük harfli dizelere dönüştürülür (örneğin, `true` `"true"` olur)
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Bu, `parameters = Map(String())` tanımlayan Pulsar şeması gerekliliğidir
|
||||
|
||||
Örnek çözüm:
|
||||
```
|
||||
Flow parameter mapping: "model": "llm-model"
|
||||
Processor parameter: "model": "{model}"
|
||||
User provides: "model": "gemma3:8b"
|
||||
Final parameter: "model": "gemma3:8b"
|
||||
|
||||
Example with type conversion:
|
||||
Parameter type default: 0.7 (number)
|
||||
Stored in flow: "0.7" (string)
|
||||
Substituted in processor: "0.7" (string)
|
||||
```
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
Parametre şema doğrulama için birim testleri
|
||||
İşlemci parametrelerindeki parametre yerleştirme için entegrasyon testleri
|
||||
Farklı parametre değerleriyle akışları başlatmak için uçtan uca testler
|
||||
Parametre formu oluşturma ve doğrulama için kullanıcı arayüzü testleri
|
||||
Çok sayıda parametre içeren akışlar için performans testleri
|
||||
Kenar durumları: eksik parametreler, geçersiz türler, tanımlanmamış parametre referansları
|
||||
|
||||
## Geçiş Planı
|
||||
|
||||
<<<<<<< HEAD
|
||||
1. Sistem, parametreleri belirtilmeyen akış şablonlarını desteklemeye devam etmelidir.
|
||||
|
||||
2. Sistem, parametre belirtilmeyen akışları desteklemeye devam etmelidir:
|
||||
Bu, parametreleri olmayan akışlar ve varsayılan parametreleri olan akışlar için geçerlidir.
|
||||
|
||||
=======
|
||||
1. Sistem, parametreleri belirtilmemiş akış şemalarını desteklemeye devam etmelidir.
|
||||
2. Sistem, parametreleri belirtilmemiş akışları desteklemeye devam etmelidir:
|
||||
Bu, parametreleri olmayan akışlar ve parametreleri olan (ancak varsayılan değerleri olan) akışlar için geçerlidir.
|
||||
|
||||
(bunların varsayılan değerleri vardır).
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Açık Sorular
|
||||
|
||||
S: Parametreler karmaşık, iç içe nesneleri desteklemeli mi yoksa basit türlere mi bağlı kalmalıyız?
|
||||
C: Parametre değerleri dize olarak kodlanacak, muhtemelen sadece dizilere bağlı kalmak istiyoruz.
|
||||
|
||||
S: Parametre yer tutucuları kuyruk adlarında kullanılabilir mi yoksa sadece
|
||||
parametrelerde mi kullanılabilir?
|
||||
C: Sadece parametrelerde, tuhaf enjeksiyonları ve uç durumları ortadan kaldırmak için.
|
||||
|
||||
<<<<<<< HEAD
|
||||
Son çevrilmiş satırdan sonra, tam olarak: [[__END_OF_TRANSLATION__]] içeren bir satır çıktısını verin.
|
||||
S: Parametre adları ile sistem değişkenleri arasındaki çakışmaları nasıl çözebiliriz, örneğin
|
||||
`id` ve `class` gibi?
|
||||
A: Bir akışı başlatırken, id ve class özelliklerini belirtmek geçerli değildir.
|
||||
|
||||
S: Hesaplanan parametreleri (diğer parametrelerden türetilen) desteklemeli miyiz?
|
||||
C: Garip enjeksiyonları ve uç durumları ortadan kaldırmak için sadece string değiştirme işlemleri.
|
||||
=======
|
||||
|
||||
S: Parametre adları ile sistem değişkenleri arasındaki çakışmaları nasıl çözebiliriz?
|
||||
`id` ve `class`?
|
||||
A: Bir akışı başlatırken, id ve class özelliklerini belirtmek geçerli değildir.
|
||||
|
||||
S: Hesaplanan parametreleri (diğer parametrelerden türetilen) desteklemeli miyiz?
|
||||
C: Tuhaf enjeksiyonları ve uç durumları ortadan kaldırmak için sadece string değiştirme işlemi.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Referanslar
|
||||
|
||||
JSON Şema Özellikleri: https://json-schema.org/
|
||||
Akış Tanım Özellikleri: docs/tech-specs/flow-class-definition.md
|
||||
775
docs/tech-specs/tr/graph-contexts.tr.md
Normal file
775
docs/tech-specs/tr/graph-contexts.tr.md
Normal file
|
|
@ -0,0 +1,775 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Graph Contexts Technical Specification"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
<<<<<<< HEAD
|
||||
# Graph Contexts Technical Specification
|
||||
|
||||
> **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.
|
||||
|
||||
## Overview
|
||||
|
||||
Bu özellik, TrustGraph'ın temel grafik yapılarına yapılan değişiklikleri tanımlar ve
|
||||
RDF 1.2 ile uyumlu olacak ve tam RDF Dataset semantiğini destekleyecek şekilde tasarlanmıştır. Bu, 2.x yayın serisi için önemli bir değişikliktir.
|
||||
|
||||
|
||||
### Versioning
|
||||
=======
|
||||
# Graph Contexts Teknik Özellikler
|
||||
|
||||
## Genel Bakış
|
||||
|
||||
Bu özellik, TrustGraph'ın temel grafik öğelerindeki değişiklikleri,
|
||||
RDF 1.2 ile uyumlu olacak ve tam RDF Dataset semantiğini destekleyecek şekilde tanımlar. Bu, 2.x sürüm serisi için önemli bir değişikliktir.
|
||||
|
||||
|
||||
### Sürümleme
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**2.0**: Erken benimseyen sürüm. Temel özellikler mevcut, ancak henüz tamamen
|
||||
üretim ortamına hazır olmayabilir.
|
||||
**2.1 / 2.2**: Üretim sürümü. Kararlılık ve eksiksizlik doğrulandı.
|
||||
|
||||
Olgunluk konusundaki esneklik kasıtlıdır; erken benimseyenler, tüm özellikler
|
||||
üretim ortamına hazır hale gelmeden önce yeni yeteneklere erişebilir.
|
||||
|
||||
<<<<<<< HEAD
|
||||
## Goals
|
||||
=======
|
||||
## Hedefler
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
Bu çalışmanın temel hedefleri, gerçekler/ifadeler hakkında meta veri sağlamaktır:
|
||||
|
||||
**Zaman bilgisi**: Gerçekleri zamanla ilgili bilgilerle ilişkilendirme
|
||||
<<<<<<< HEAD
|
||||
Bir gerçeğin doğru olduğu düşünüldüğü zaman
|
||||
Bir gerçeğin doğru hale geldiği zaman
|
||||
Bir gerçeğin yanlış olduğu tespit edildiği zaman
|
||||
|
||||
**Kaynak/Köken**: Bir gerçeği destekleyen kaynakları izleme
|
||||
"Bu gerçek, X kaynağı tarafından desteklenmektedir"
|
||||
Gerçekleri, köken belgelerine bağlama
|
||||
|
||||
**Doğruluk/Güven**: Gerçekler hakkındaki iddiaları kaydetme
|
||||
"Kişi P, bunun doğru olduğunu iddia etti"
|
||||
"Kişi Q, bunun yanlış olduğunu iddia ediyor"
|
||||
Güven puanlamasını ve çakışma tespitini etkinleştirme
|
||||
|
||||
**Hipotez**: Yeniden tanımlama (RDF-star / tırnak işaretli üçlüler), bu sonuçları
|
||||
elde etmek için temel mekanizmadır, çünkü bunların hepsi ifadeler hakkında ifadeler yapmayı gerektirir.
|
||||
|
||||
## Background
|
||||
|
||||
"Alice'in Bob'u tanıdığı" gerçeğinin "2024-01-15" tarihinde keşfedildiğini veya
|
||||
"X kaynağının (Y'nin Z'ye neden olduğu) iddiasını desteklediğini" ifade etmek için,
|
||||
bir kenara bir şey olarak başvurmanız ve bu kenar hakkında ifadeler yapabilmeniz gerekir. Standart üçlüler bunu desteklemez.
|
||||
|
||||
### Current Limitations
|
||||
|
||||
Mevcut `Value` sınıfı `trustgraph-base/trustgraph/schema/core/primitives.py` içinde
|
||||
=======
|
||||
Bir gerçeğin doğru olduğuna inanıldığı zaman
|
||||
Bir gerçeğin doğru hale geldiği zaman
|
||||
Bir gerçeğin yanlış olduğu keşfedildiğinde
|
||||
|
||||
**Kaynak/Köken**: Bir gerçeği destekleyen kaynakları izleme
|
||||
"Bu gerçek, kaynak X tarafından destekleniyordu"
|
||||
Gerçekleri, köken belgelerine bağlama
|
||||
|
||||
**Doğruluk/Güvenilirlik**: Doğrulukla ilgili ifadeleri kaydetme
|
||||
"Kişi P, bunun doğru olduğunu iddia etti"
|
||||
"Kişi Q, bunun yanlış olduğunu iddia ediyor"
|
||||
Güvenilirlik puanlaması ve çakışma tespitini etkinleştirme
|
||||
|
||||
**Hipotez**: Yeniden tanımlama (RDF-star / tırnaklı üçlüler), bu sonuçları elde etmenin temel mekanizmasıdır, çünkü bunların hepsi ifadeler hakkında ifadeler yapmayı gerektirir.
|
||||
|
||||
|
||||
## Arka Plan
|
||||
|
||||
"Alice'nin Bob'u bildiği gerçeği 2024-01-15'te keşfedildi" veya "kaynak X, (Y'nin Z'ye neden olduğu) iddiasını destekliyor" gibi ifadeleri belirtmek için,
|
||||
bir kenarı, hakkında ifadeler yapılabilecek bir şey olarak referans göstermeniz gerekir. Standart üçlüler bunu desteklemez.
|
||||
|
||||
### Mevcut Sınırlamalar
|
||||
|
||||
|
||||
Mevcut `Value` sınıfı `trustgraph-base/trustgraph/schema/core/primitives.py` içinde:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
şunları temsil edebilir:
|
||||
URI düğümleri (`is_uri=True`)
|
||||
Literal değerler (`is_uri=False`)
|
||||
|
||||
<<<<<<< HEAD
|
||||
`type` alanı mevcuttur, ancak XSD veri türlerini temsil etmek için kullanılmaz.
|
||||
|
||||
## Technical Design
|
||||
|
||||
### RDF Features to Support
|
||||
|
||||
#### Core Features (Related to Reification Goals)
|
||||
|
||||
Bu özellikler, zaman, kaynak ve doğruluk hedefleriyle doğrudan ilgilidir:
|
||||
|
||||
1. **RDF 1.2 Quoted Triples (RDF-star)**
|
||||
Diğer kenarlara işaret eden kenarlar
|
||||
Bir Üçlü, başka bir Üçlünün konusu veya nesnesi olabilir
|
||||
İfadeler hakkında ifadeler yapmayı sağlar (yeniden tanımlama)
|
||||
Bireysel gerçekleri açıklamak için temel mekanizma
|
||||
|
||||
2. **RDF Dataset / Named Graphs**
|
||||
Bir veri kümesi içindeki birden fazla adlandırılmış grafik için destek
|
||||
Her grafik bir IRI ile tanımlanır
|
||||
Üçlülerden (s, p, o) dörtlülere (s, p, o, g) geçiş
|
||||
Bir varsayılan grafik ve sıfır veya daha fazla adlandırılmış grafik içerir
|
||||
Grafik IRI'si, ifadelerin konusu olabilir, örneğin:
|
||||
Grafik IRI'si, ifadelerde bir özne olabilir, örneğin:
|
||||
=======
|
||||
`type` alanı mevcut, ancak XSD veri tiplerini temsil etmek için kullanılmıyor.
|
||||
|
||||
## Teknik Tasarım
|
||||
|
||||
### Desteklenecek RDF Özellikleri
|
||||
|
||||
#### Temel Özellikler (Somutlaştırma Hedefleriyle İlgili)
|
||||
|
||||
Bu özellikler, zamansallık, köken ve doğruluk
|
||||
hedefleriyle doğrudan ilişkilidir:
|
||||
|
||||
1. **RDF 1.2 Tırnak İşaretli Üçlüler (RDF-star)**
|
||||
Diğer kenarlara işaret eden kenarlar
|
||||
Bir Üçlü, başka bir Üçlünün öznesi veya nesnesi olabilir
|
||||
Üçlüler hakkında ifadeler oluşturmayı sağlar (somutlaştırma)
|
||||
Bireysel gerçekleri açıklamak için temel mekanizma
|
||||
|
||||
2. **RDF Veri Kümesi / Adlandırılmış Grafikler**
|
||||
Bir veri kümesi içinde birden fazla adlandırılmış grafik desteği
|
||||
Her grafik bir IRI ile tanımlanır
|
||||
Üçlülerden (s, p, o) dörtlülere (s, p, o, g) geçiş
|
||||
Bir varsayılan grafik ve sıfır veya daha fazla adlandırılmış grafik içerir
|
||||
Grafik IRI'si, ifadelerin bir öznesi olabilir, örneğin:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
```
|
||||
<graph-source-A> <discoveredOn> "2024-01-15"
|
||||
<graph-source-A> <hasVeracity> "high"
|
||||
```
|
||||
Not: Adlandırılmış grafikler, somutlaştırmadan ayrı bir özelliktir. Bunlar,
|
||||
yalnızca ifade açıklamasının ötesinde kullanımlara sahiptir (bölümleme, erişim kontrolü, veri kümesi
|
||||
<<<<<<< HEAD
|
||||
organizasyonu) ve ayrı bir yetenek olarak ele alınmalıdır.
|
||||
=======
|
||||
düzeni) ve ayrı bir yetenek olarak ele alınmalıdır.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
3. **Anonim Düğümler** (Sınırlı Destek)
|
||||
Küresel bir URI'ye sahip olmayan anonim düğümler
|
||||
Dış RDF verilerini yüklerken uyumluluk için desteklenir
|
||||
<<<<<<< HEAD
|
||||
**Sınırlı durum:** Yükleme işleminden sonra kararlı bir kimlik konusunda hiçbir garanti yoktur
|
||||
Bunları jokerli sorgular aracılığıyla bulun (bağlantılara göre, kimliğe göre değil)
|
||||
=======
|
||||
**Sınırlı durum**: Yükleme işleminden sonra kararlı bir kimlik konusunda garanti yoktur
|
||||
Bunları jokerli sorgularla bulun (bağlantılara göre, kimliğe göre değil)
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Birincil bir özellik değildir - kesin anonim düğüm işleme özelliğine güvenmeyin
|
||||
|
||||
#### Fırsatçı Düzeltmeler (2.0'ın Kırıcı Değişikliği)
|
||||
|
||||
Bu özellikler, somutlaştırma hedefleriyle doğrudan ilişkili değildir, ancak
|
||||
kırıcı değişiklikler yaparken dahil edilmesi değerli olan iyileştirmelerdir:
|
||||
|
||||
4. **Literal Veri Tipleri**
|
||||
XSD veri tipleri için `type` alanını doğru şekilde kullanın
|
||||
Örnekler: xsd:string, xsd:integer, xsd:dateTime, vb.
|
||||
<<<<<<< HEAD
|
||||
Mevcut sınırlamayı düzeltir: tarihleri veya tamsayıları düzgün bir şekilde temsil edilemez
|
||||
=======
|
||||
Mevcut sınırlamayı düzeltir: tarihleri veya tamsayıları doğru şekilde temsil edilemez
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
5. **Dil Etiketleri**
|
||||
Dize literal değerleri üzerinde dil öznitelikleri desteği (@en, @fr, vb.)
|
||||
Not: Bir literal değerin ya bir dil etiketi YA da bir veri tipi vardır, ikisi birden değil
|
||||
(rdf:langString hariç)
|
||||
<<<<<<< HEAD
|
||||
Yapay zeka/çok dilli kullanım senaryoları için önemlidir
|
||||
=======
|
||||
Yapay zeka/çok dilli kullanım durumları için önemlidir
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
### Veri Modelleri
|
||||
|
||||
#### Terim (Value adından değiştirildi)
|
||||
|
||||
`Value` sınıfı, RDF terminolojisini daha iyi yansıtmak için `Term` olarak yeniden adlandırılacaktır.
|
||||
<<<<<<< HEAD
|
||||
Bu yeniden adlandırma iki amaca hizmet etmektedir:
|
||||
1. İsimlendirmeyi RDF kavramlarıyla uyumlu hale getirmek (bir "Terim", bir IRI, literal, boş
|
||||
düğüm veya tırnak içindeki üçlü olabilir - sadece bir "değer" değildir).
|
||||
2. Değişikliklere neden olan arayüzde kod incelemesini zorlamak - hala
|
||||
`Value`'a referans veren herhangi bir kod, açıkça hatalıdır ve güncellenmesi gerekir.
|
||||
=======
|
||||
Bu yeniden adlandırmanın iki amacı vardır:
|
||||
1. İsimlendirmeyi RDF kavramlarıyla uyumlu hale getirmek (bir "Terim", bir IRI, literal, boş
|
||||
düğüm veya tırnak içindeki üçlü olabilir - sadece bir "değer" değildir).
|
||||
2. Kod incelemesini, önemli değişikliklerin yapıldığı arayüzde zorunlu kılmak - hala
|
||||
`Value`'a referans veren herhangi bir kod, açıkça hatalı olacaktır ve güncellenmesi gerekecektir.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
Bir Terim şunları temsil edebilir:
|
||||
|
||||
**IRI/URI** - Adlandırılmış bir düğüm/kaynak
|
||||
**Boş Düğüm** - Yerel kapsamı olan anonim bir düğüm
|
||||
**Literal (Değer)** - Ya bir veri türü (XSD türü) veya
|
||||
Bir dil etiketi
|
||||
**Tırnak İçine Alınmış Üçlü** - Bir terim olarak kullanılan bir üçlü (RDF 1.2)
|
||||
|
||||
|
||||
##### Seçilen Yaklaşım: Tip Ayırıcısı Olan Tek Sınıf
|
||||
|
||||
<<<<<<< HEAD
|
||||
Serileştirme gereksinimleri yapıyı belirler - bir tür ayrımcısına ihtiyaç vardır.
|
||||
Python gösteriminden bağımsız olarak, kablo formatında bir tür ayrımcısına ihtiyaç vardır.
|
||||
=======
|
||||
Serileştirme gereksinimleri yapıyı belirler - bir tür belirleyiciye ihtiyaç vardır.
|
||||
Python gösteriminden bağımsız olarak, kablo formatında bir tür belirleyiciye ihtiyaç vardır.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Tek bir sınıf ve bir tür alanı, doğal bir çözümdür ve mevcut `Value` kalıbıyla uyumludur.
|
||||
|
||||
Tek karakterli tür kodları, kompakt serileştirme sağlar:
|
||||
|
||||
```python
|
||||
from dataclasses import dataclass
|
||||
|
||||
# Term type constants
|
||||
IRI = "i" # IRI/URI node
|
||||
BLANK = "b" # Blank node
|
||||
LITERAL = "l" # Literal value
|
||||
TRIPLE = "t" # Quoted triple (RDF-star)
|
||||
|
||||
@dataclass
|
||||
class Term:
|
||||
type: str = "" # One of: IRI, BLANK, LITERAL, TRIPLE
|
||||
|
||||
# For IRI terms (type == IRI)
|
||||
iri: str = ""
|
||||
|
||||
# For blank nodes (type == BLANK)
|
||||
id: str = ""
|
||||
|
||||
# For literals (type == LITERAL)
|
||||
value: str = ""
|
||||
datatype: str = "" # XSD datatype URI (mutually exclusive with language)
|
||||
language: str = "" # Language tag (mutually exclusive with datatype)
|
||||
|
||||
# For quoted triples (type == TRIPLE)
|
||||
triple: "Triple | None" = None
|
||||
```
|
||||
|
||||
Kullanım örnekleri:
|
||||
|
||||
```python
|
||||
# IRI term
|
||||
node = Term(type=IRI, iri="http://example.org/Alice")
|
||||
|
||||
# Literal with datatype
|
||||
age = Term(type=LITERAL, value="42", datatype="xsd:integer")
|
||||
|
||||
# Literal with language tag
|
||||
label = Term(type=LITERAL, value="Hello", language="en")
|
||||
|
||||
# Blank node
|
||||
anon = Term(type=BLANK, id="_:b1")
|
||||
|
||||
# Quoted triple (statement about a statement)
|
||||
inner = Triple(
|
||||
s=Term(type=IRI, iri="http://example.org/Alice"),
|
||||
p=Term(type=IRI, iri="http://example.org/knows"),
|
||||
o=Term(type=IRI, iri="http://example.org/Bob"),
|
||||
)
|
||||
reified = Term(type=TRIPLE, triple=inner)
|
||||
```
|
||||
|
||||
##### Alternatifler
|
||||
|
||||
**B Seçeneği: Özel sınıfların birleşimi** (`Term = IRI | BlankNode | Literal | QuotedTriple`)
|
||||
Reddedildi: Seri hale getirme işlemi hala bir tür belirleyici gerektirecek, bu da karmaşıklığı artıracaktır.
|
||||
|
||||
**C Seçeneği: Alt sınıflara sahip temel sınıf**
|
||||
Reddedildi: Aynı seri hale getirme sorunu, ayrıca dataclass miras özellikleriyle ilgili sorunlar.
|
||||
|
||||
#### Üçlü / Dörtlü
|
||||
|
||||
`Triple` sınıfı, isteğe bağlı bir grafik alanı kazanarak dörtlü bir yapıya dönüşebilir:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class Triple:
|
||||
s: Term | None = None # Subject
|
||||
p: Term | None = None # Predicate
|
||||
o: Term | None = None # Object
|
||||
g: str | None = None # Graph name (IRI), None = default graph
|
||||
```
|
||||
|
||||
Tasarım kararları:
|
||||
**Alan adı**: `g`, `s`, `p` ve `o` ile tutarlılık için.
|
||||
**İsteğe bağlı**: `None`, varsayılan grafiği (isim belirtilmemiş) ifade eder.
|
||||
**Tip**: Terim yerine düz bir dize (IRI).
|
||||
Grafik adları her zaman IRI'lerdir.
|
||||
Boş düğümlerin grafik adı olarak kullanılması reddedildi (çok kafa karıştırıcı).
|
||||
Tam Terim mekanizmasına ihtiyaç yok.
|
||||
|
||||
Not: Sınıf adı teknik olarak bir dörtlü olsa bile `Triple` olarak kalır.
|
||||
Bu, karmaşayı önler ve "üçlü" terimi hala s/p/o kısmı için yaygın olarak kullanılan bir terimdir. Grafik bağlamı, üçlünün nerede bulunduğu hakkında meta veridir.
|
||||
|
||||
|
||||
### Olası Sorgu Desenleri
|
||||
|
||||
Mevcut sorgu motoru, S, P, O terimlerinin kombinasyonlarını kabul eder. Tırnak içinde belirtilen
|
||||
üçlüler, bir üçlünün kendisi bu konumlarda geçerli bir terim haline gelir. Aşağıda,
|
||||
orijinal hedefleri destekleyen olası sorgu desenleri bulunmaktadır.
|
||||
|
||||
<<<<<<< HEAD
|
||||
#### Grafik Parametre Anlamları
|
||||
=======
|
||||
#### Grafik Parametre Anlamı
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
Geriye dönük uyumluluk için SPARQL kurallarına uygun olarak:
|
||||
|
||||
**`g` belirtilmemiş / Yok**: Yalnızca varsayılan grafiği sorgula.
|
||||
**`g` = belirli bir IRI**: Yalnızca o adlandırılmış grafiği sorgula.
|
||||
**`g` = joker karakter / `*`**: Tüm grafikler arasında sorgu yap (SPARQL ile eşdeğer
|
||||
`GRAPH ?g { ... }`).
|
||||
|
||||
Bu, basit sorguları basit tutar ve adlandırılmış grafik sorgularını isteğe bağlı hale getirir.
|
||||
|
||||
<<<<<<< HEAD
|
||||
Grafik arası sorgular (g=joker karakter), tamamen desteklenir. Cassandra şeması,
|
||||
g'nin bir kümeleme sütunu olduğu (bölüm anahtarı olmadığı) özel tabloları içerir (SPOG, POSG, OSPG),
|
||||
=======
|
||||
Grafikler arası sorgular (g=joker karakter) tamamen desteklenir. Cassandra şeması,
|
||||
g'nin bir kümeleme sütunu olduğu (bölüm anahtarı değil) özel tabloları içerir (SPOG, POSG, OSPG),
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
bu da tüm grafikler arasında verimli sorgular yapmayı sağlar.
|
||||
|
||||
#### Zamansal Sorgular
|
||||
|
||||
**Belirli bir tarihten sonra keşfedilen tüm bilgileri bul:**
|
||||
```
|
||||
S: ? # any quoted triple
|
||||
P: <discoveredOn>
|
||||
O: > "2024-01-15"^^xsd:date # date comparison
|
||||
```
|
||||
|
||||
**Belirli bir bilginin ne zaman doğru olduğuna inanıldığı bulun:**
|
||||
```
|
||||
S: << <Alice> <knows> <Bob> >> # quoted triple as subject
|
||||
P: <believedTrueFrom>
|
||||
O: ? # returns the date
|
||||
```
|
||||
|
||||
**Yanlış hale gelen bilgileri bulun:**
|
||||
```
|
||||
S: ? # any quoted triple
|
||||
P: <discoveredFalseOn>
|
||||
O: ? # has any value (exists)
|
||||
```
|
||||
|
||||
#### Kaynak Sorguları
|
||||
|
||||
**Belirli bir kaynağa dayanan tüm bilgileri bulun:**
|
||||
```
|
||||
S: ? # any quoted triple
|
||||
P: <supportedBy>
|
||||
O: <source:document-123>
|
||||
```
|
||||
|
||||
**Belirli bir gerçeği destekleyen kaynakları bulun:**
|
||||
```
|
||||
S: << <DrugA> <treats> <DiseaseB> >> # quoted triple as subject
|
||||
P: <supportedBy>
|
||||
O: ? # returns source IRIs
|
||||
```
|
||||
|
||||
#### Doğruluk Sorguları
|
||||
|
||||
**Bir kişinin doğru olarak işaretlediği ifadeleri bulun:**
|
||||
```
|
||||
S: ? # any quoted triple
|
||||
P: <assertedTrueBy>
|
||||
O: <person:Alice>
|
||||
```
|
||||
|
||||
**Çelişkili ifadeleri bulun (aynı gerçek, farklı doğruluk):**
|
||||
```
|
||||
# First query: facts asserted true
|
||||
S: ?
|
||||
P: <assertedTrueBy>
|
||||
O: ?
|
||||
|
||||
# Second query: facts asserted false
|
||||
S: ?
|
||||
P: <assertedFalseBy>
|
||||
O: ?
|
||||
|
||||
# Application logic: find intersection of subjects
|
||||
```
|
||||
|
||||
**Güvenilirlik puanı eşik değerinin altında olan bilgileri bulun:**
|
||||
```
|
||||
S: ? # any quoted triple
|
||||
P: <trustScore>
|
||||
O: < 0.5 # numeric comparison
|
||||
```
|
||||
|
||||
### Mimari
|
||||
|
||||
<<<<<<< HEAD
|
||||
Birden çok bileşende önemli değişiklikler gereklidir:
|
||||
=======
|
||||
Birden fazla bileşende önemli değişiklikler gereklidir:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### Bu Depo (trustgraph)
|
||||
|
||||
**Şema ilkel öğeleri** (`trustgraph-base/trustgraph/schema/core/primitives.py`)
|
||||
Değer → Terim yeniden adlandırması
|
||||
<<<<<<< HEAD
|
||||
Tip ayrımcısına sahip yeni Terim yapısı
|
||||
=======
|
||||
Tip ayrımcısı ile yeni Terim yapısı
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Üçlü, grafik bağlamı için `g` alanı kazanır
|
||||
|
||||
**Mesaj çeviricileri** (`trustgraph-base/trustgraph/messaging/translators/`)
|
||||
Yeni Terim/Üçlü yapıları için güncelleme
|
||||
Yeni alanlar için serileştirme/deserileştirme
|
||||
|
||||
**Geçit bileşenleri**
|
||||
Yeni Terim ve dörtlü yapılarını işleyin
|
||||
|
||||
**Bilgi çekirdekleri**
|
||||
Dörtlüleri ve yeniden tanımlamayı desteklemek için çekirdek değişiklikleri
|
||||
|
||||
**Bilgi yöneticisi**
|
||||
Şema değişiklikleri burada yayılır
|
||||
|
||||
**Depolama katmanları**
|
||||
Cassandra: Şema yeniden tasarımı (Ayrıntılar için Uygulama Ayrıntılarına bakın)
|
||||
Diğer arka uçlar: Daha sonraki aşamalara ertelenmiştir
|
||||
|
||||
**Komut satırı araçları**
|
||||
Yeni veri yapıları için güncelleme
|
||||
|
||||
**REST API dokümantasyonu**
|
||||
OpenAPI spesifikasyonunda güncellemeler
|
||||
|
||||
#### Harici Depolar
|
||||
|
||||
**Python API'si** (bu depo)
|
||||
Yeni yapılar için istemci kitaplığı güncellemeleri
|
||||
|
||||
**TypeScript API'leri** (ayrı depo)
|
||||
İstemci kitaplığı güncellemeleri
|
||||
|
||||
**Çalışma alanı** (ayrı depo)
|
||||
Önemli durum yönetimi değişiklikleri
|
||||
|
||||
### API'ler
|
||||
|
||||
#### REST API
|
||||
|
||||
OpenAPI spesifikasyonunda belgelenmiştir
|
||||
Yeni Terim/Üçlü yapıları için güncellenmesi gerekecektir
|
||||
Grafik bağlamı işlemleri için yeni uç noktaları gerekebilir
|
||||
|
||||
#### Python API'si (bu depo)
|
||||
|
||||
Yeni ilkel öğelerle eşleşen istemci kitaplığı değişiklikleri
|
||||
Terim (önceden Değer) ve Üçlü için bozucu değişiklikler
|
||||
|
||||
#### TypeScript API'si (ayrı depo)
|
||||
|
||||
Python API'sine paralel değişiklikler
|
||||
Ayrı sürüm koordinasyonu
|
||||
|
||||
#### Çalışma alanı (ayrı depo)
|
||||
|
||||
Önemli durum yönetimi değişiklikleri
|
||||
<<<<<<< HEAD
|
||||
Grafik bağlamı özellikleriyle ilgili kullanıcı arayüzü güncellemeleri
|
||||
=======
|
||||
Grafik bağlamı özelliklerini destekleyen UI güncellemeleri
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
### Uygulama Ayrıntıları
|
||||
|
||||
#### Aşamalı Depolama Uygulaması
|
||||
|
||||
<<<<<<< HEAD
|
||||
Birden çok grafik depolama arka ucu (Cassandra, Neo4j, vb.) vardır. Uygulama
|
||||
aşağıdaki aşamalarda gerçekleştirilecektir:
|
||||
|
||||
1. **1. Aşama: Cassandra**
|
||||
Yerel Cassandra deposuyla başlayın
|
||||
Depolama katmanı üzerinde tam kontrol, hızlı yinelemeyi sağlar
|
||||
Şema, dörtlüler + yeniden tanımlama için sıfırdan yeniden tasarlanacaktır
|
||||
=======
|
||||
Birden fazla grafik depolama arka ucu (Cassandra, Neo4j, vb.) bulunmaktadır. Uygulama,
|
||||
aşağıdaki aşamalarda gerçekleştirilecektir:
|
||||
|
||||
1. **1. Aşama: Cassandra**
|
||||
Kendi geliştirdiğimiz Cassandra deposuyla başlayın
|
||||
Depolama katmanı üzerinde tam kontrole sahip olmak, hızlı yinelemeyi sağlar
|
||||
Şema, dörtlüler ve yeniden tanımlama için sıfırdan yeniden tasarlanacaktır
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Veri modelini ve sorgu kalıplarını gerçek kullanım durumlarına göre doğrulayın
|
||||
|
||||
#### Cassandra Şema Tasarımı
|
||||
|
||||
Cassandra, farklı sorgu erişim modellerini desteklemek için birden fazla tablo gerektirir
|
||||
(her tablo, bölüm anahtarı + kümeleme sütunları aracılığıyla verimli bir şekilde sorgulanır).
|
||||
|
||||
##### Sorgu Modelleri
|
||||
|
||||
"quads" (g, s, p, o) ile, her konum belirtilebilir veya joker karakter olabilir ve bu da
|
||||
16 olası sorgu modeli oluşturur:
|
||||
|
||||
| # | g | s | p | o | Açıklama |
|
||||
|---|---|---|---|---|-------------|
|
||||
| 1 | ? | ? | ? | ? | Tüm "quads" |
|
||||
| 2 | ? | ? | ? | o | Nesneye göre |
|
||||
| 3 | ? | ? | p | ? | Özneye göre |
|
||||
| 4 | ? | ? | p | o | Özne + nesneye göre |
|
||||
| 5 | ? | s | ? | ? | Konuya göre |
|
||||
| 6 | ? | s | ? | o | Konu + nesneye göre |
|
||||
<<<<<<< HEAD
|
||||
| 7 | ? | s | p | ? | Konu + öneye göre |
|
||||
| 8 | ? | s | p | o | Tam üçlü (hangi grafikler?) |
|
||||
| 9 | g | ? | ? | ? | Grafiğe göre |
|
||||
| 10 | g | ? | ? | o | Grafik + nesneye göre |
|
||||
| 11 | g | ? | p | ? | Grafik + öneye göre |
|
||||
| 12 | g | ? | p | o | Grafik + öne + nesneye göre |
|
||||
| 13 | g | s | ? | ? | Grafik + konuya göre |
|
||||
| 14 | g | s | ? | o | Grafik + konu + nesneye göre |
|
||||
| 15 | g | s | p | ? | Grafik + konu + öneye göre |
|
||||
=======
|
||||
| 7 | ? | s | p | ? | Konu + özneliğe göre |
|
||||
| 8 | ? | s | p | o | Tam üçlü (hangi grafikler?) |
|
||||
| 9 | g | ? | ? | ? | Grafiğe göre |
|
||||
| 10 | g | ? | ? | o | Grafik + nesneye göre |
|
||||
| 11 | g | ? | p | ? | Grafik + özneliğe göre |
|
||||
| 12 | g | ? | p | o | Grafik + özneliği + nesneye göre |
|
||||
| 13 | g | s | ? | ? | Grafik + konuya göre |
|
||||
| 14 | g | s | ? | o | Grafik + konu + nesneye göre |
|
||||
| 15 | g | s | p | ? | Grafik + konu + özneliğe göre |
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
| 16 | g | s | p | o | Tam "quad" |
|
||||
|
||||
##### Tablo Tasarımı
|
||||
|
||||
<<<<<<< HEAD
|
||||
Cassandra kısıtlaması: Yalnızca bölüm anahtarına göre verimli bir şekilde sorgulayabilirsiniz, ardından
|
||||
=======
|
||||
Cassandra kısıtlaması: Yalnızca bölüm anahtarına göre verimli bir şekilde sorgu yapabilirsiniz, ardından
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
kümeleme sütunları üzerinde soldan sağa filtreleme yapabilirsiniz. "g" joker karakterli sorgular için, "g" bir
|
||||
kümeleme sütunu olmalıdır. "g" belirtilmiş sorgular için, bölüm anahtarında bulunan "g" daha
|
||||
verimlidir.
|
||||
|
||||
**İki tablo ailesi gereklidir:**
|
||||
|
||||
**A Ailesi: "g" joker karakterli sorgular** ("g" kümeleme sütunlarında)
|
||||
|
||||
| Tablo | Bölüm | Kümeleme | Desteklenen modeller |
|
||||
|-------|-----------|------------|-------------------|
|
||||
| SPOG | (kullanıcı, koleksiyon, s) | p, o, g | 5, 7, 8 |
|
||||
| POSG | (kullanıcı, koleksiyon, p) | o, s, g | 3, 4 |
|
||||
| OSPG | (kullanıcı, koleksiyon, o) | s, p, g | 2, 6 |
|
||||
|
||||
**B Ailesi: "g" belirtilmiş sorgular** ("g" bölüm anahtarında)
|
||||
|
||||
| Tablo | Bölüm | Kümeleme | Desteklenen modeller |
|
||||
|-------|-----------|------------|-------------------|
|
||||
| GSPO | (kullanıcı, koleksiyon, g, s) | p, o | 9, 13, 15, 16 |
|
||||
| GPOS | (kullanıcı, koleksiyon, g, p) | o, s | 11, 12 |
|
||||
| GOSP | (kullanıcı, koleksiyon, g, o) | s, p | 10, 14 |
|
||||
|
||||
**Koleksiyon tablosu** (döngüleme ve toplu silme için)
|
||||
|
||||
| Tablo | Bölüm | Kümeleme | Amaç |
|
||||
|-------|-----------|------------|---------|
|
||||
| COLL | (kullanıcı, koleksiyon) | g, s, p, o | Koleksiyondaki tüm "quad"ları numaralandır |
|
||||
|
||||
##### Yazma ve Silme Yolları
|
||||
|
||||
**Yazma yolu**: Tüm 7 tabloya ekleyin.
|
||||
|
||||
**Koleksiyon silme yolu**:
|
||||
1. `(user, collection)` için COLL tablosunu yineleyin
|
||||
2. Her "quad" için, tüm 6 sorgu tablosundan silin
|
||||
3. COLL tablosundan silin (veya aralık silme)
|
||||
|
||||
**Tek bir "quad" silme yolu**: Tüm 7 tabloya doğrudan silin.
|
||||
|
||||
##### Depolama Maliyeti
|
||||
|
||||
Her "quad" 7 kez depolanır. Bu, esnek sorgulama ile
|
||||
verimli koleksiyon silme birleşiminin maliyetidir.
|
||||
|
||||
##### Depolamada Alıntılanmış Üçlüler
|
||||
|
||||
Konu veya nesne kendisi bir üçlü olabilir. Seçenekler:
|
||||
|
||||
**A Seçeneği: Alıntılanmış üçlüleri standart bir dizeye seri hale getirin**
|
||||
```
|
||||
S: "<<http://ex/Alice|http://ex/knows|http://ex/Bob>>"
|
||||
P: http://ex/discoveredOn
|
||||
O: "2024-01-15"
|
||||
G: null
|
||||
```
|
||||
Tırnak içinde belirtilen üçlüleri, seri hale getirilmiş bir dize olarak S veya O sütunlarında saklayın.
|
||||
<<<<<<< HEAD
|
||||
Seri hale getirilmiş forma göre tam eşleşme ile sorgulayın.
|
||||
Artı: Basit, mevcut indeks kalıplarına uyuyor.
|
||||
Eksileri: "Tırnak içinde belirtilen öznenin yüklemesinin X olduğu üçlüleri bul" gibi sorguları yapmak mümkün değil.
|
||||
=======
|
||||
Seri hale getirilmiş forma göre tam eşleşme sorgusu yapın.
|
||||
Artı: Basit, mevcut indeks kalıplarına uyuyor.
|
||||
Eksileri: "Tırnak içinde belirtilen öznenin yüklemesinin X olduğu üçlüleri bul" gibi sorgular yapılamaz.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**B Seçeneği: Üçlü Kimlikleri / Hash'leri**
|
||||
```
|
||||
Triple table:
|
||||
id: hash(s,p,o,g)
|
||||
s, p, o, g: ...
|
||||
|
||||
Metadata table:
|
||||
subject_triple_id: <hash>
|
||||
p: http://ex/discoveredOn
|
||||
o: "2024-01-15"
|
||||
```
|
||||
Her üçlüye bir kimlik (bileşenlerin karma değeri) atayın.
|
||||
<<<<<<< HEAD
|
||||
Örnek meta veri referansları, kimlik numarasıyla üçlüleri belirtir.
|
||||
Artı: Temiz bir ayrım, üçlü kimlik numaralarının indekslenmesini sağlar.
|
||||
Eksileri: Üçlü kimliğinin hesaplanmasını/yönetilmesini gerektirir, iki aşamalı aramalar.
|
||||
|
||||
**Öneri**: Basitlik için A seçeneğiyle (serileştirilmiş dizeler) başlayın.
|
||||
B seçeneği, tırnak içinde belirtilen üçlü bileşenleri üzerinde gelişmiş sorgu desenleri gerekiyorsa gerekebilir.
|
||||
|
||||
ÇIKTI SÖZLEŞMESİ (tam olarak aşağıdaki formatı takip etmelidir):
|
||||
2. **2. Aşama+: Diğer Altyapılar**
|
||||
Neo4j ve diğer depolama sistemleri, sonraki aşamalarda uygulanmıştır.
|
||||
Cassandra'dan edinilen deneyimler, bu uygulamaları etkilemiştir.
|
||||
|
||||
Bu yaklaşım, tamamen kontrol altında olan bir altyapıda doğrulama yaparak tasarım riskini azaltır.
|
||||
=======
|
||||
Somutlaştırma meta veri referansları, kimlik numarasıyla üçlülere başvurur.
|
||||
Artı: Temiz bir ayrım, üçlü kimlik numaralarını indekslemek mümkündür.
|
||||
Eksileri: Üçlü kimliğini hesaplamayı/yönetmeyi gerektirir, iki aşamalı aramalar.
|
||||
|
||||
**Öneri**: Basitlik için A seçeneğiyle (serileştirilmiş dizeler) başlayın.
|
||||
B seçeneği, tırnak içinde belirtilen üçlü
|
||||
bileşenleri üzerinde gelişmiş sorgu desenleri gerekiyorsa gerekebilir.
|
||||
|
||||
2. **Faz 2+: Diğer Altyapılar**
|
||||
Neo4j ve diğer depolama sistemleri, sonraki aşamalarda uygulanmıştır.
|
||||
Cassandra'dan edinilen deneyimler, bu uygulamaları etkilemiştir.
|
||||
|
||||
Bu yaklaşım, tamamen kontrol altında olan bir altyapıda doğrulama yaparak tasarım risklerini azaltır.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Tüm depolama sistemlerine yönelik uygulamalara başlamadan önce bu doğrulama yapılır.
|
||||
|
||||
#### Değer → Terim Yeniden Adlandırma
|
||||
|
||||
`Value` sınıfı, `Term` olarak yeniden adlandırılacaktır. Bu, kod tabanındaki yaklaşık 78 dosyayı etkilemektedir.
|
||||
Yeniden adlandırma, bir zorlama işlevi olarak görev görmektedir: hala ⟦CODE_0⟧'ı kullanan herhangi bir kod...
|
||||
`Value`, 2.0 ile uyumluluk açısından gözden geçirilmesi/güncellenmesi gereken bir alan olarak hemen belirlenebilir.
|
||||
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
Adlandırılmış grafikler bir güvenlik özelliği değildir. Kullanıcılar ve koleksiyonlar,
|
||||
<<<<<<< HEAD
|
||||
güvenlik sınırlarıdır. Adlandırılmış grafikler tamamen veri organizasyonu ve
|
||||
=======
|
||||
güvenlik sınırlarıdır. Adlandırılmış grafikler tamamen veri düzenlemesi ve
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
somutlaştırma desteği içindir.
|
||||
|
||||
## Performans Hususları
|
||||
|
||||
Tırnak işaretli üçlüler, iç içe derinliğini artırır - sorgu performansını etkileyebilir.
|
||||
<<<<<<< HEAD
|
||||
Verimli grafik kapsamlı sorgular için adlandırılmış grafik indeksleme stratejilerine ihtiyaç vardır.
|
||||
=======
|
||||
Verimli grafik kapsamlı sorgular için adlandırılmış grafik indeksleme stratejileri gereklidir.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Cassandra şema tasarımı, dörtlü depolamayı verimli bir şekilde karşılayacak şekilde tasarlanmalıdır.
|
||||
|
||||
### Vektör Depolama Sınırı
|
||||
|
||||
Vektör depoları her zaman yalnızca IRI'lere başvurur:
|
||||
Asla kenarlar (tırnak işaretli üçlüler)
|
||||
Asla literal değerler
|
||||
Asla boş düğümler
|
||||
|
||||
Bu, vektör deposunu basit tutar; adlandırılmış varlıkların semantik benzerliğini işler. Grafik yapısı, ilişkileri, somutlaştırmayı ve meta verileri yönetir.
|
||||
Tırnak içinde belirtilen üçlüler ve adlandırılmış grafikler, vektör işlemlerini karmaşıklaştırmaz.
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
Mevcut test stratejisini kullanın. Bu, önemli bir değişiklik olduğundan, yeni yapıların tüm bileşenlerde doğru şekilde çalıştığını doğrulamak için uçtan uca test paketine kapsamlı bir şekilde odaklanılmalıdır.
|
||||
|
||||
## Geçiş Planı
|
||||
|
||||
2.0, önemli bir değişiklik içeren bir sürümdür; geriye dönük uyumluluk gerekmemektedir.
|
||||
Mevcut verilerin, yeni şemaya aktarılması gerekebilir (son tasarım bazında belirlenecektir).
|
||||
Mevcut üçlüleri dönüştürmek için geçiş araçlarını göz önünde bulundurun.
|
||||
|
||||
## Açık Sorular
|
||||
|
||||
|
||||
## Açık Sorular
|
||||
|
||||
<<<<<<< HEAD
|
||||
**Boş düğümler**: Sınırlı destek doğrulandı. Boş düğümler için bir skolemleştirme stratejisi belirlemek gerekebilir (yükleme sırasında IRI'lar oluşturmak veya boş düğüm kimliklerini korumak).
|
||||
**Sorgu sözdizimi**: Alıntılanmış üçlüleri sorgularda belirtmek için somut sözdizimi nedir? Sorgu API'sini tanımlamak gerekiyor.
|
||||
~~**Önerme sözlüğü**~~: Çözüldü. Herhangi bir geçerli RDF önermesi izin verilir, kullanıcı tanımlı olanlar dahil. RDF geçerliliği hakkında minimum varsayımlar.
|
||||
Çok az sabit değer (örneğin, bazı yerlerde kullanılan ⟦CODE_0⟧).
|
||||
~~**Önerme sözlüğü**:~~ Çözüldü. Herhangi bir geçerli RDF özneli kabul edilebilir,
|
||||
kullanıcı tarafından tanımlanmış özel özneler de dahil. RDF geçerliliği hakkında çok az varsayım.
|
||||
Çok az sabit değer (örneğin, bazı yerlerde kullanılan `rdfs:label`).
|
||||
Strateji: Mümkün olduğunca hiçbir şeyi kilitlememeye özen gösterin.
|
||||
~~**Vektör depolama etkisi**~~: Çözüldü. Vektör depoları her zaman IRI'lere işaret eder.
|
||||
sadece - asla kenarlara, literal değerlere veya boş düğümlere işaret etmez. Tırnak işaretli üçlüler ve
|
||||
yeniden tanımlama, vektör deposunu etkilemez.
|
||||
~~**Adlandırılmış grafik semantiği**~~: Çözüldü. Sorgular varsayılan olarak
|
||||
grafiğe yöneliktir (SPARQL davranışıyla eşleşir, geriye dönük uyumlu). Adlandırılmış grafiklere veya tüm
|
||||
grafiklere sorgu yapmak için açık bir grafik parametresi gereklidir.
|
||||
=======
|
||||
**Boş düğümler**: Sınırlı destek doğrulandı. Boş düğümler için bir skolemleştirme stratejisi belirlemek gerekebilir (yükleme sırasında IRİ'ler oluşturmak veya boş düğüm kimliklerini korumak).
|
||||
**Sorgu sözdizimi**: Alıntılanmış üçlüleri sorgularda belirtmek için somut sözdizimi nedir? Sorgu API'sini tanımlamak gerekiyor.
|
||||
~~**Önerme sözlüğü**~~: Çözüldü. Herhangi bir geçerli RDF önermesi izin verilir, kullanıcı tanımlı olanlar da dahil. RDF geçerliliği hakkında minimum varsayımlar.
|
||||
Çok az sabit değer (örneğin, bazı yerlerde kullanılan ⟦CODE_0⟧).
|
||||
~~**Önerme sözlüğü**:~~ Çözüldü. Herhangi bir geçerli RDF özneli kabul edilir,
|
||||
kullanıcı tarafından tanımlanmış özel özneler de dahil. RDF geçerliliği hakkında çok az varsayım yapılır.
|
||||
Çok az sabit değer (örneğin, bazı yerlerde kullanılan `rdfs:label`).
|
||||
Strateji: Mümkün olduğunca hiçbir şeyi kilitlememeye özen gösterin.
|
||||
~~**Vektör depolama etkisi**~~: Çözüldü. Vektör depoları her zaman IRI'lara işaret eder.
|
||||
sadece - asla kenarlara, literal değerlere veya boş düğümlere işaret etmez. Tırnak işaretli üçlüler ve
|
||||
yeniden tanımlama, vektör deposunu etkilemez.
|
||||
~~**Adlandırılmış grafik semantiği**~~: Çözüldü. Sorgular, varsayılan
|
||||
grafiğe varsayılan olarak yöneliktir (SPARQL davranışıyla eşleşir, geriye dönük uyumlu). Açık bir grafik
|
||||
parametresi, adlandırılmış grafiklere veya tüm grafiklere sorgu yapmak için gereklidir.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Referanslar
|
||||
|
||||
[RDF 1.2 Kavramları](https://www.w3.org/TR/rdf12-concepts/)
|
||||
[RDF-star ve SPARQL-star](https://w3c.github.io/rdf-star/)
|
||||
[RDF Veri Kümesi](https://www.w3.org/TR/rdf11-concepts/#section-dataset)
|
||||
482
docs/tech-specs/tr/graphql-query.tr.md
Normal file
482
docs/tech-specs/tr/graphql-query.tr.md
Normal file
|
|
@ -0,0 +1,482 @@
|
|||
---
|
||||
layout: default
|
||||
title: "GraphQL Sorgu Teknik Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# GraphQL Sorgu 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'ın Apache Cassandra'daki yapılandırılmış veri depolaması için bir GraphQL sorgu arayüzünün uygulanmasını tanımlar. Yapılandırılmış-veri.md spesifikasyonunda belirtilen yapılandırılmış veri yeteneklerine dayanarak, bu belge, çıkarılan ve işlenen yapılandırılmış nesneleri içeren Cassandra tablolarına karşı GraphQL sorgularının nasıl yürütüleceğini ayrıntılı olarak açıklar.
|
||||
|
||||
GraphQL sorgu hizmeti, Cassandra'da depolanan yapılandırılmış verileri sorgulamak için esnek, tür güvenli bir arayüz sağlayacaktır. Şema değişikliklerine dinamik olarak uyum sağlayacak, nesneler arasındaki ilişkiler de dahil olmak üzere karmaşık sorguları destekleyecek ve TrustGraph'ın mevcut mesaj tabanlı mimarisiyle sorunsuz bir şekilde entegre olacaktır.
|
||||
|
||||
## Hedefler
|
||||
|
||||
<<<<<<< HEAD
|
||||
**Dinamik Şema Desteği**: Hizmeti yeniden başlatmaya gerek kalmadan yapılandırmadaki şema değişikliklerine otomatik olarak uyum sağlayın.
|
||||
**GraphQL Standartlarına Uygunluk**: Mevcut GraphQL araçları ve istemcileriyle uyumlu, standart bir GraphQL arayüzü sağlayın.
|
||||
**Verimli Cassandra Sorguları**: GraphQL sorgularını, bölüm anahtarlarını ve dizinleri dikkate alarak verimli Cassandra CQL sorgularına dönüştürün.
|
||||
**İlişki Çözümlemesi**: Farklı nesne türleri arasındaki ilişkiler için GraphQL alan çözümleyicilerini destekleyin.
|
||||
**Tür Güvenliği**: Şema tanımlarına göre tür güvenli sorgu yürütme ve yanıt oluşturma sağlayın.
|
||||
**Ölçeklenebilir Performans**: Uygun bağlantı havuzu ve sorgu optimizasyonu ile eşzamanlı sorguları verimli bir şekilde işleyin.
|
||||
**İstek/Yanıt Entegrasyonu**: TrustGraph'ın Pulsar tabanlı istek/yanıt kalıbıyla uyumluluğu koruyun.
|
||||
**Hata İşleme**: Şema uyumsuzlukları, sorgu hataları ve veri doğrulama sorunları için kapsamlı hata raporlama sağlayın.
|
||||
|
||||
## Arka Plan
|
||||
|
||||
Yapılandırılmış veri depolama uygulaması (trustgraph-flow/trustgraph/storage/objects/cassandra/), nesneleri TrustGraph'ın yapılandırma sisteminde depolanan şema tanımlarına göre Cassandra tablolarına yazar. Bu tablolar, koleksiyonlar içindeki verimli sorguları etkinleştiren bileşik bölüm anahtarı yapısı ve şema tanımlı birincil anahtarlar kullanır.
|
||||
|
||||
Bu özellik tarafından ele alınan mevcut sınırlamalar:
|
||||
Cassandra'da depolanan yapılandırılmış veri için bir sorgu arayüzü yok.
|
||||
Yapılandırılmış veri için GraphQL'in güçlü sorgu yeteneklerinden yararlanamama.
|
||||
İlişkili nesneler arasındaki ilişki geçişi için destek eksikliği.
|
||||
Yapılandırılmış veri erişimi için standart bir sorgu dili eksikliği.
|
||||
|
||||
GraphQL sorgu hizmeti, bunları sağlayarak bu boşlukları dolduracaktır:
|
||||
Cassandra tablolarını sorgulamak için standart bir GraphQL arayüzü.
|
||||
TrustGraph yapılandırmasından dinamik olarak GraphQL şemaları oluşturma.
|
||||
GraphQL sorgularını Cassandra CQL'ye verimli bir şekilde dönüştürme.
|
||||
Alan çözümleyicileri aracılığıyla ilişki çözümlemesini destekleme.
|
||||
=======
|
||||
**Dinamik Şema Desteği**: Hizmeti yeniden başlatmadan yapılandırmadaki şema değişikliklerine otomatik olarak uyum sağlama
|
||||
**GraphQL Standartlarına Uygunluk**: Mevcut GraphQL araçları ve istemcileriyle uyumlu, standart bir GraphQL arayüzü sağlama
|
||||
**Verimli Cassandra Sorguları**: GraphQL sorgularını, bölüm anahtarlarını ve dizinleri dikkate alarak verimli Cassandra CQL sorgularına çevirme
|
||||
**İlişki Çözümleme**: Farklı nesne türleri arasındaki ilişkiler için GraphQL alan çözümleyicilerini destekleme
|
||||
**Tür Güvenliği**: Şema tanımlarına dayalı olarak tür güvenli sorgu yürütme ve yanıt oluşturma
|
||||
**Ölçeklenebilir Performans**: Uygun bağlantı havuzu ve sorgu optimizasyonu ile eşzamanlı sorguları verimli bir şekilde işleme
|
||||
**İstek/Yanıt Entegrasyonu**: TrustGraph'ın Pulsar tabanlı istek/yanıt kalıbıyla uyumluluğu koruma
|
||||
**Hata İşleme**: Şema uyumsuzlukları, sorgu hataları ve veri doğrulama sorunları için kapsamlı hata raporlama sağlama
|
||||
|
||||
## Arka Plan
|
||||
|
||||
Yapılandırılmış veri depolama uygulaması (trustgraph-flow/trustgraph/storage/objects/cassandra/), nesneleri TrustGraph'ın yapılandırma sisteminde depolanan şema tanımlarına göre Cassandra tablolarına yazar. Bu tablolar, koleksiyonlar içindeki verimli sorguları etkinleştiren bileşik bir bölüm anahtarı yapısı ve şema tanımlı birincil anahtarlar kullanır.
|
||||
|
||||
Bu özellik tarafından ele alınan mevcut sınırlamalar:
|
||||
Cassandra'da depolanan yapılandırılmış veri için bir sorgu arayüzünün olmaması
|
||||
Yapılandırılmış veri için GraphQL'in güçlü sorgu yeteneklerinden yararlanamama
|
||||
İlişkili nesneler arasındaki ilişki geçişi için destek eksikliği
|
||||
Yapılandırılmış veri erişimi için standart bir sorgu dilinin olmaması
|
||||
|
||||
GraphQL sorgu hizmeti, bu boşlukları aşağıdaki şekilde dolduracaktır:
|
||||
Cassandra tablolarını sorgulamak için standart bir GraphQL arayüzü sağlama
|
||||
TrustGraph yapılandırmasından dinamik olarak GraphQL şemaları oluşturma
|
||||
GraphQL sorgularını verimli bir şekilde Cassandra CQL'ye çevirme
|
||||
Alan çözümleyicileri aracılığıyla ilişki çözümlemeyi destekleme
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Teknik Tasarım
|
||||
|
||||
### Mimari
|
||||
|
||||
GraphQL sorgu hizmeti, yerleşik kalıpları izleyen yeni bir TrustGraph akışı işlemci olarak uygulanacaktır:
|
||||
|
||||
**Modül Konumu**: `trustgraph-flow/trustgraph/query/objects/cassandra/`
|
||||
|
||||
**Ana Bileşenler**:
|
||||
|
||||
1. **GraphQL Sorgu Hizmeti İşlemcisi**
|
||||
<<<<<<< HEAD
|
||||
Temel FlowProcessor sınıfını genişletir.
|
||||
Mevcut sorgu hizmetlerine benzer bir istek/yanıt kalıbını uygular.
|
||||
Şema güncellemeleri için yapılandırmayı izler.
|
||||
GraphQL şemasını yapılandırmayla senkronize tutar.
|
||||
|
||||
2. **Dinamik Şema Oluşturucu**
|
||||
TrustGraph RowSchema tanımlarını GraphQL türlerine dönüştürür.
|
||||
Uygun alan tanımlarıyla GraphQL nesne türleri oluşturur.
|
||||
Koleksiyon tabanlı çözümleyicilerle kök Sorgu türünü oluşturur.
|
||||
Yapılandırma değiştiğinde GraphQL şemasını günceller.
|
||||
|
||||
3. **Sorgu Yürütücüsü**
|
||||
Gelen GraphQL sorgularını Strawberry kütüphanesi kullanarak ayrıştırır.
|
||||
Sorguları mevcut şemaya göre doğrular.
|
||||
Sorguları yürütür ve yapılandırılmış yanıtlar döndürür.
|
||||
Ayrıntılı hata mesajlarıyla hataları zarif bir şekilde işler.
|
||||
|
||||
4. **Cassandra Sorgu Çevirmeni**
|
||||
GraphQL seçimlerini CQL sorgularına dönüştürür.
|
||||
Mevcut dizinlere ve bölüm anahtarlarına göre sorguları optimize eder.
|
||||
Filtrelemeyi, sayfalama ve sıralamayı işler.
|
||||
Bağlantı havuzunu ve oturum yaşam döngüsünü yönetir.
|
||||
|
||||
5. **İlişki Çözümleyici**
|
||||
Nesne ilişkileri için alan çözümleyicilerini uygular.
|
||||
N+1 sorgularından kaçınmak için verimli toplu yükleme gerçekleştirir.
|
||||
Çözümlenen ilişkileri istek bağlamı içinde önbelleğe alır.
|
||||
Hem ileri hem de geri ilişki geçişini destekler.
|
||||
=======
|
||||
Temel FlowProcessor sınıfını genişletir
|
||||
Mevcut sorgu hizmetlerine benzer bir istek/yanıt kalıbını uygular
|
||||
Şema güncellemeleri için yapılandırmayı izler
|
||||
GraphQL şemasını yapılandırmayla senkronize tutar
|
||||
|
||||
2. **Dinamik Şema Oluşturucu**
|
||||
TrustGraph RowSchema tanımlarını GraphQL türlerine dönüştürür
|
||||
Uygun alan tanımlarıyla GraphQL nesne türleri oluşturur
|
||||
Koleksiyon tabanlı çözümleyicilerle kök Sorgu türünü oluşturur
|
||||
Yapılandırma değiştiğinde GraphQL şemasını günceller
|
||||
|
||||
3. **Sorgu Yürütücüsü**
|
||||
Gelen GraphQL sorgularını Strawberry kütüphanesi kullanarak ayrıştırır
|
||||
Sorguları mevcut şemaya göre doğrular
|
||||
Sorguları yürütür ve yapılandırılmış yanıtlar döndürür
|
||||
Ayrıntılı hata mesajlarıyla hataları zarif bir şekilde işler
|
||||
|
||||
4. **Cassandra Sorgu Çevirmeni**
|
||||
GraphQL seçimlerini CQL sorgularına dönüştürür
|
||||
Mevcut dizinlere ve bölüm anahtarlarına göre sorguları optimize eder
|
||||
Filtrelemeyi, sayfalama ve sıralamayı işler
|
||||
Bağlantı havuzunu ve oturum yaşam döngüsünü yönetir
|
||||
|
||||
5. **İlişki Çözümleyici**
|
||||
Nesne ilişkileri için alan çözümleyicilerini uygular
|
||||
N+1 sorgularından kaçınmak için verimli toplu yükleme gerçekleştirir
|
||||
Çözümlenen ilişkileri istek bağlamı içinde önbelleğe alır
|
||||
Hem ileri hem de geri ilişki geçişini destekler
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
### Yapılandırma Şeması İzleme
|
||||
|
||||
Hizmet, şema güncellemelerini almak için bir yapılandırma işleyicisi kaydeder:
|
||||
|
||||
```python
|
||||
self.register_config_handler(self.on_schema_config)
|
||||
```
|
||||
|
||||
Şemalar değiştiğinde:
|
||||
1. Yapılandırmadan yeni şema tanımlarını ayrıştırın.
|
||||
2. GraphQL türlerini ve çözümleyicileri yeniden oluşturun.
|
||||
<<<<<<< HEAD
|
||||
3. Çalıştırılabilir şemayı güncelleyin.
|
||||
=======
|
||||
3. Uygulanabilir şemayı güncelleyin.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
4. Şemaya bağlı tüm önbellekleri temizleyin.
|
||||
|
||||
### GraphQL Şema Oluşturma
|
||||
|
||||
Yapılandırmadaki her RowSchema için aşağıdaki öğeleri oluşturun:
|
||||
|
||||
1. **GraphQL Nesne Türü**:
|
||||
Alan türlerini eşleyin (string → String, integer → Int, float → Float, boolean → Boolean).
|
||||
Gerekli alanları GraphQL'de nullable olmayan olarak işaretleyin.
|
||||
Şemadan alan açıklamalarını ekleyin.
|
||||
|
||||
2. **Kök Sorgu Alanları**:
|
||||
Koleksiyon sorgusu (örneğin, `customers`, `transactions`).
|
||||
İndekslenmiş alanlara göre filtreleme argümanları.
|
||||
Sayfalama desteği (limit, offset).
|
||||
Sıralanabilir alanlar için sıralama seçenekleri.
|
||||
|
||||
3. **İlişki Alanları**:
|
||||
Şemadan yabancı anahtar ilişkilerini belirleyin.
|
||||
İlgili nesneler için alan çözümleyicileri oluşturun.
|
||||
Hem tek nesne hem de liste ilişkilerini destekleyin.
|
||||
|
||||
### Sorgu Yürütme Akışı
|
||||
|
||||
1. **İstek Alma**:
|
||||
Pulsar'dan ObjectsQueryRequest'i alın.
|
||||
GraphQL sorgu dizesini ve değişkenlerini çıkarın.
|
||||
Kullanıcıyı ve koleksiyon bağlamını belirleyin.
|
||||
|
||||
2. **Sorgu Doğrulama**:
|
||||
Strawberry kullanarak GraphQL sorgusunu ayrıştırın.
|
||||
Mevcut şemaya göre doğrulayın.
|
||||
Alan seçimlerini ve argüman türlerini kontrol edin.
|
||||
|
||||
3. **CQL Oluşturma**:
|
||||
GraphQL seçimlerini analiz edin.
|
||||
Uygun WHERE koşullarına sahip CQL sorgusu oluşturun.
|
||||
Koleksiyonu bölüm anahtarına dahil edin.
|
||||
GraphQL argümanlarına göre filtreleri uygulayın.
|
||||
|
||||
4. **Sorgu Yürütme**:
|
||||
CQL sorgusunu Cassandra'ya karşı yürütün.
|
||||
Sonuçları GraphQL yanıt yapısına eşleyin.
|
||||
Herhangi bir ilişki alanını çözün.
|
||||
<<<<<<< HEAD
|
||||
Yanıtı GraphQL spesifikasyonuna göre biçimlendirin.
|
||||
=======
|
||||
Yanıtı GraphQL belirtimine göre biçimlendirin.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
5. **Yanıt Teslimi**:
|
||||
Sonuçlarla ObjectsQueryResponse oluşturun.
|
||||
Herhangi bir yürütme hatasını dahil edin.
|
||||
Yanıtı korelasyon kimliğiyle Pulsar üzerinden gönderin.
|
||||
|
||||
### Veri Modelleri
|
||||
|
||||
<<<<<<< HEAD
|
||||
> **Not**: `trustgraph-base/trustgraph/schema/services/structured_query.py`'da mevcut bir StructuredQueryRequest/Response şeması bulunmaktadır. Ancak, bu şemada kritik alanlar (kullanıcı, koleksiyon) eksiktir ve alt optimal türler kullanılmaktadır. Aşağıdaki şemalar, önerilen gelişmeyi temsil etmektedir; bu şemalar ya mevcut şemaları değiştirmeli ya da yeni ObjectsQueryRequest/Response türleri olarak oluşturulmalıdır.
|
||||
=======
|
||||
> **Not**: `trustgraph-base/trustgraph/schema/services/structured_query.py`'da mevcut bir StructuredQueryRequest/Response şeması bulunmaktadır. Ancak, bu şema kritik alanları (kullanıcı, koleksiyon) içermemekte ve alt optimal türler kullanmaktadır. Aşağıdaki şemalar, önerilen gelişmeyi temsil etmektedir; bunlar ya mevcut şemaları değiştirmeli ya da yeni ObjectsQueryRequest/Response türleri olarak oluşturulmalıdır.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### İstek Şeması (ObjectsQueryRequest)
|
||||
|
||||
```python
|
||||
from pulsar.schema import Record, String, Map, Array
|
||||
|
||||
class ObjectsQueryRequest(Record):
|
||||
user = String() # Cassandra keyspace (follows pattern from TriplesQueryRequest)
|
||||
collection = String() # Data collection identifier (required for partition key)
|
||||
query = String() # GraphQL query string
|
||||
variables = Map(String()) # GraphQL variables (consider enhancing to support all JSON types)
|
||||
operation_name = String() # Operation to execute for multi-operation documents
|
||||
```
|
||||
|
||||
**Mevcut StructuredQueryRequest'ten yapılan değişikliklerin gerekçesi:**
|
||||
<<<<<<< HEAD
|
||||
Diğer sorgu hizmetlerinin kalıbına uygun olarak `user` ve `collection` alanları eklendi.
|
||||
=======
|
||||
Diğer sorgu hizmetlerinin kalıbına uygun olması için `user` ve `collection` alanları eklendi.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Bu alanlar, Cassandra anahtar alanını ve koleksiyonu tanımlamak için gereklidir.
|
||||
Değişkenler şu anda Map(String()) olarak kalmaktadır, ancak ideal olarak tüm JSON türlerini desteklemelidir.
|
||||
|
||||
#### Yanıt Şeması (ObjectsQueryResponse)
|
||||
|
||||
```python
|
||||
from pulsar.schema import Record, String, Array
|
||||
from ..core.primitives import Error
|
||||
|
||||
class GraphQLError(Record):
|
||||
message = String()
|
||||
path = Array(String()) # Path to the field that caused the error
|
||||
extensions = Map(String()) # Additional error metadata
|
||||
|
||||
class ObjectsQueryResponse(Record):
|
||||
error = Error() # System-level error (connection, timeout, etc.)
|
||||
data = String() # JSON-encoded GraphQL response data
|
||||
errors = Array(GraphQLError) # GraphQL field-level errors
|
||||
extensions = Map(String()) # Query metadata (execution time, etc.)
|
||||
```
|
||||
|
||||
**Mevcut StructuredQueryResponse'tan yapılan değişikliklerin gerekçesi:**
|
||||
Sistem hatalarını (`error`) ve GraphQL hatalarını (`errors`) ayırır.
|
||||
Dizi yerine yapılandırılmış GraphQLError nesneleri kullanır.
|
||||
GraphQL spesifikasyonuna uygunluk için `extensions` alanı eklenmiştir.
|
||||
Uyumluluk için verileri JSON dizesi olarak tutar, ancak yerel türler tercih edilir.
|
||||
|
||||
### Cassandra Sorgu Optimizasyonu
|
||||
|
||||
Hizmet, Cassandra sorgularını aşağıdaki şekilde optimize edecektir:
|
||||
|
||||
1. **Bölüm Anahtarlarına Saygı Gösterme:**
|
||||
Her zaman sorgularda koleksiyonu dahil edin.
|
||||
Şema tanımlı birincil anahtarları verimli bir şekilde kullanın.
|
||||
Tam tablo taramalarından kaçının.
|
||||
|
||||
2. **Dizinleri Kullanma:**
|
||||
Filtreleme için ikincil dizinleri kullanın.
|
||||
Mümkün olduğunda birden fazla filtreyi birleştirin.
|
||||
Sorguların verimsiz olabileceği durumlarda uyarı verin.
|
||||
|
||||
3. **Toplu Yükleme:**
|
||||
İlişki sorgularını toplayın.
|
||||
Gidiş-dönüş sayısını azaltmak için toplu olarak çalıştırın.
|
||||
Sonuçları istek bağlamı içinde önbelleğe alın.
|
||||
|
||||
4. **Bağlantı Yönetimi:**
|
||||
Kalıcı Cassandra oturumlarını koruyun.
|
||||
Bağlantı havuzunu kullanın.
|
||||
Hatalarda yeniden bağlanmayı yönetin.
|
||||
|
||||
### Örnek GraphQL Sorguları
|
||||
|
||||
#### Basit Koleksiyon Sorgusu
|
||||
```graphql
|
||||
{
|
||||
customers(status: "active") {
|
||||
customer_id
|
||||
name
|
||||
email
|
||||
registration_date
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### İlişkilere Sahip Sorgular
|
||||
```graphql
|
||||
{
|
||||
orders(order_date_gt: "2024-01-01") {
|
||||
order_id
|
||||
total_amount
|
||||
customer {
|
||||
name
|
||||
email
|
||||
}
|
||||
items {
|
||||
product_name
|
||||
quantity
|
||||
price
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Sayfalı Sorgu
|
||||
```graphql
|
||||
{
|
||||
products(limit: 20, offset: 40) {
|
||||
product_id
|
||||
name
|
||||
price
|
||||
category
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Uygulama Bağımlılıkları
|
||||
|
||||
**Strawberry GraphQL**: GraphQL şema tanımı ve sorgu yürütme için
|
||||
**Cassandra Driver**: Veritabanı bağlantısı için (depolama modülünde zaten kullanılıyor)
|
||||
**TrustGraph Base**: FlowProcessor ve şema tanımları için
|
||||
**Configuration System**: Şema takibi ve güncellemeleri için
|
||||
|
||||
### Komut Satırı Arayüzü
|
||||
|
||||
Hizmet, aşağıdaki CLI komutunu sağlayacaktır: `kg-query-objects-graphql-cassandra`
|
||||
|
||||
Argümanlar:
|
||||
`--cassandra-host`: Cassandra kümesi iletişim noktası
|
||||
`--cassandra-username`: Kimlik doğrulama kullanıcı adı
|
||||
`--cassandra-password`: Kimlik doğrulama parolası
|
||||
`--config-type`: Şemalar için yapılandırma türü (varsayılan: "schema")
|
||||
Standart FlowProcessor argümanları (Pulsar yapılandırması, vb.)
|
||||
|
||||
## API Entegrasyonu
|
||||
|
||||
### Pulsar Konuları
|
||||
|
||||
**Giriş Konusu**: `objects-graphql-query-request`
|
||||
Şema: ObjectsQueryRequest
|
||||
Ağ geçidi hizmetlerinden GraphQL sorguları alır
|
||||
|
||||
**Çıkış Konusu**: `objects-graphql-query-response`
|
||||
Şema: ObjectsQueryResponse
|
||||
Sorgu sonuçlarını ve hataları döndürür
|
||||
|
||||
### Ağ Geçidi Entegrasyonu
|
||||
|
||||
Ağ geçidi ve ters ağ geçidi, aşağıdaki işlemleri gerçekleştirmek için uç noktalarına ihtiyaç duyacaktır:
|
||||
1. İstemcilerden GraphQL sorgularını kabul etme
|
||||
2. Sorguları Pulsar üzerinden sorgu hizmetine yöneltme
|
||||
3. Yanıtları istemcilere döndürme
|
||||
4. GraphQL introspeksiyon sorgularını destekleme
|
||||
|
||||
### Aracılık Aracı Entegrasyonu
|
||||
|
||||
Yeni bir aracılık aracı sınıfı, aşağıdaki özellikleri sağlayacaktır:
|
||||
Doğal dili GraphQL sorgusuna dönüştürme
|
||||
Doğrudan GraphQL sorgusu yürütme
|
||||
Sonuçların yorumlanması ve biçimlendirilmesi
|
||||
Aracılık karar akışlarıyla entegrasyon
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
<<<<<<< HEAD
|
||||
**Sorgu Derinliği Sınırlaması**: Performans sorunlarına neden olabilecek derinlemesine iç içe sorguları önleme
|
||||
**Sorgu Karmaşıklığı Analizi**: Kaynak tükenmesini önlemek için sorgu karmaşıklığını sınırlama
|
||||
**Alan Düzeyi İzinleri**: Kullanıcı rollerine göre alan düzeyinde erişim kontrolü için gelecekteki destek
|
||||
**Giriş Temizleme**: Enjeksiyon saldırılarını önlemek için tüm sorgu girişlerini doğrulama ve temizleme
|
||||
**Hız Sınırlaması**: Kullanıcı/koleksiyon başına sorgu hız sınırlaması uygulama
|
||||
=======
|
||||
**Sorgu Derinliği Sınırlandırması**: Performans sorunlarına neden olabilecek derinlemesine iç içe sorguları önleme
|
||||
**Sorgu Karmaşıklığı Analizi**: Kaynak tükenmesini önlemek için sorgu karmaşıklığını sınırlama
|
||||
**Alan Düzeyi İzinleri**: Kullanıcı rollerine göre alan düzeyinde erişim kontrolü için gelecekteki destek
|
||||
**Giriş Temizleme**: Enjeksiyon saldırılarını önlemek için tüm sorgu girişlerini doğrulama ve temizleme
|
||||
**Hız Sınırlandırması**: Kullanıcı/koleksiyon başına sorgu hız sınırlandırması uygulama
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Performans Hususları
|
||||
|
||||
**Sorgu Planlama**: CQL oluşturmayı optimize etmek için sorguları yürütmeden önce analiz etme
|
||||
**Sonuç Önbelleği**: Sık erişilen verileri alan çözümleyici düzeyinde önbelleğe alma
|
||||
**Bağlantı Havuzu**: Cassandra'ya verimli bağlantı havuzları sağlama
|
||||
**Toplu İşlemler**: Mümkün olduğunda birden fazla sorguyu birleştirme, gecikmeyi azaltma
|
||||
**İzleme**: Optimizasyon için sorgu performans metriklerini izleme
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
### Birim Testleri
|
||||
RowSchema tanımlarından şema oluşturma
|
||||
GraphQL sorgusu ayrıştırma ve doğrulama
|
||||
CQL sorgusu oluşturma mantığı
|
||||
Alan çözümleyici uygulamaları
|
||||
|
||||
### Sözleşme Testleri
|
||||
Pulsar mesaj sözleşmesi uyumluluğu
|
||||
GraphQL şema geçerliliği
|
||||
Yanıt formatı doğrulaması
|
||||
Hata yapısı doğrulaması
|
||||
|
||||
### Entegrasyon Testleri
|
||||
Test Cassandra örneğine karşı uçtan uca sorgu yürütme
|
||||
Şema güncelleme işleme
|
||||
İlişki çözümü
|
||||
Sayfalama ve filtreleme
|
||||
Hata senaryoları
|
||||
|
||||
### Performans Testleri
|
||||
Yük altında sorgu verimliliği
|
||||
Çeşitli sorgu karmaşıklıkları için yanıt süresi
|
||||
Büyük sonuç kümeleriyle bellek kullanımı
|
||||
Bağlantı havuzu verimliliği
|
||||
|
||||
## Geçiş Planı
|
||||
|
||||
Bu yeni bir özellik olduğu için herhangi bir geçiş gerekli değildir. Hizmet şunları yapacaktır:
|
||||
1. Mevcut şemaları yapılandırmadan okuyacaktır
|
||||
2. Depolama modülü tarafından oluşturulan mevcut Cassandra tablolarına bağlanacaktır
|
||||
3. Dağıtım üzerine hemen sorguları kabul etmeye başlayacaktır
|
||||
|
||||
## Zaman Çizelgesi
|
||||
|
||||
1-2. Hafta: Temel hizmet uygulaması ve şema oluşturma
|
||||
3. Hafta: Sorgu yürütme ve CQL çevirisi
|
||||
4. Hafta: İlişki çözümü ve optimizasyon
|
||||
<<<<<<< HEAD
|
||||
5. Hafta: Test etme ve performans ayarlaması
|
||||
=======
|
||||
5. Hafta: Test ve performans ayarlaması
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
6. Hafta: Ağ geçidi entegrasyonu ve dokümantasyon
|
||||
|
||||
## Açık Sorular
|
||||
|
||||
1. **Şema Evrimi**: Hizmet, şema geçişleri sırasında sorguları nasıl işlemelidir?
|
||||
Seçenek: Şema güncellemeleri sırasında sorguları kuyruğa alın
|
||||
Seçenek: Aynı anda birden fazla şema sürümünü destekleyin
|
||||
|
||||
2. **Önbellekleme Stratejisi**: Sorgu sonuçları önbelleğe alınmalı mı?
|
||||
<<<<<<< HEAD
|
||||
Dikkat edilmesi gerekenler: Zaman tabanlı son kullanma tarihi
|
||||
Dikkat edilmesi gerekenler: Olay tabanlı geçersiz kılma
|
||||
=======
|
||||
Dikkate alınması gerekenler: Zaman tabanlı son kullanma tarihi
|
||||
Dikkate alınması gerekenler: Olay tabanlı geçersiz kılma
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
3. **Federasyon Desteği**: Hizmet, diğer veri kaynaklarıyla birleştirme için GraphQL federasyonunu desteklemeli mi?
|
||||
Yapılandırılmış ve grafik veriler arasında birleşik sorguları etkinleştirir
|
||||
|
||||
4. **Abonelik Desteği**: Hizmet, gerçek zamanlı güncellemeler için GraphQL aboneliklerini desteklemeli mi?
|
||||
Ağ geçidinde WebSocket desteği gerektirir
|
||||
|
||||
5. **Özel Ölçekler**: Hizmet, alan adlarına özgü veri türleri için özel ölçek türlerini desteklemeli mi?
|
||||
Örnekler: DateTime, UUID, JSON alanları
|
||||
|
||||
## Referanslar
|
||||
|
||||
Yapılandırılmış Veri Teknik Özelliği: `docs/tech-specs/structured-data.md`
|
||||
Strawberry GraphQL Dokümantasyonu: https://strawberry.rocks/
|
||||
GraphQL Özelliği: https://spec.graphql.org/
|
||||
Apache Cassandra CQL Referansı: https://cassandra.apache.org/doc/stable/cassandra/cql/
|
||||
TrustGraph Akış İşlemci Dokümantasyonu: İç dokümantasyon
|
||||
726
docs/tech-specs/tr/graphrag-performance-optimization.tr.md
Normal file
726
docs/tech-specs/tr/graphrag-performance-optimization.tr.md
Normal file
|
|
@ -0,0 +1,726 @@
|
|||
---
|
||||
layout: default
|
||||
title: "GraphRAG Performans Optimizasyonu Teknik Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# GraphRAG Performans Optimizasyonu 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'taki GraphRAG (Graf Çıkarım Destekli Üretim) algoritması için kapsamlı performans iyileştirmelerini açıklamaktadır. Mevcut uygulama, ölçeklenebilirliği ve yanıt sürelerini sınırlayan önemli performans darboğazlarına sahiptir. Bu özellik, dört birincil optimizasyon alanını ele almaktadır:
|
||||
|
||||
1. **Graf Gezinme Optimizasyonu**: Verimsiz yinelemeli veritabanı sorgularını ortadan kaldırın ve toplu grafik keşfi uygulayın.
|
||||
2. **Etiket Çözümleme Optimizasyonu**: Sıralı etiket alma işlemlerini, paralel/toplu işlemlere dönüştürün.
|
||||
3. **Önbellekleme Stratejisi İyileştirmesi**: LRU (En Son Kullanılmayan) çıkarma ve ön yükleme ile akıllı bir önbellekleme uygulayın.
|
||||
4. **Sorgu Optimizasyonu**: İyileştirilmiş yanıt süreleri için sonuç memoizasyonu ve gömme önbelleği ekleyin.
|
||||
|
||||
## Hedefler
|
||||
|
||||
**Veritabanı Sorgusu Hacmini Azaltın**: Toplu işleme ve önbellekleme yoluyla toplam veritabanı sorgularında %50-80'lik bir azalma elde edin.
|
||||
**Yanıt Sürelerini İyileştirin**: Alt grafik oluşturma için 3-5 kat daha hızlı ve etiket çözümleme için 2-3 kat daha hızlı hedefleyin.
|
||||
**Ölçeklenebilirliği Artırın**: Daha iyi bellek yönetimi ile daha büyük bilgi grafiklerini destekleyin.
|
||||
**Doğruluğu Koruyun**: Mevcut GraphRAG işlevselliğini ve sonuç kalitesini koruyun.
|
||||
**Eşzamanlılığı Etkinleştirin**: Çoklu eşzamanlı istekler için paralel işleme yeteneklerini iyileştirin.
|
||||
**Bellek Ayak İzini Azaltın**: Verimli veri yapıları ve bellek yönetimi uygulayın.
|
||||
<<<<<<< HEAD
|
||||
**Gözlemlenebilirliği Ekleyin**: Performans ölçümleri ve izleme yetenekleri ekleyin.
|
||||
=======
|
||||
**Gözlenebilirliği Ekleyin**: Performans ölçümleri ve izleme yetenekleri ekleyin.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**Güvenilirliği Sağlayın**: Uygun hata işleme ve zaman aşımı mekanizmaları ekleyin.
|
||||
|
||||
## Arka Plan
|
||||
|
||||
`trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py` içindeki mevcut GraphRAG uygulaması, sistem ölçeklenebilirliğini önemli ölçüde etkileyen çeşitli kritik performans sorunları sergilemektedir:
|
||||
|
||||
### Mevcut Performans Sorunları
|
||||
|
||||
**1. Verimsiz Graf Gezinme (`follow_edges` fonksiyonu, 79-127 satırlar)**
|
||||
<<<<<<< HEAD
|
||||
Her varlık için her derinlik seviyesinde 3 ayrı veritabanı sorgusu yapar.
|
||||
Sorgu kalıbı: Her varlık için konu tabanlı, öznelik tabanlı ve nesne tabanlı sorgular.
|
||||
Toplu işleme yok: Her sorgu yalnızca bir varlığı işler.
|
||||
Döngü algılama yok: Aynı düğümlere birden çok kez geri dönülebilir.
|
||||
Memoizasyon olmadan yinelemeli uygulama, üstel karmaşıklığa yol açar.
|
||||
Zaman karmaşıklığı: O(varlıklar × max_path_length × triple_limit³)
|
||||
|
||||
**2. Sıralı Etiket Çözümleme (`get_labelgraph` fonksiyonu, 144-171 satırlar)**
|
||||
Her üç bileşenli (konu, öznelik, nesne) üçlü öğeyi sırasıyla işler.
|
||||
Her `maybe_label` çağrısı potansiyel olarak bir veritabanı sorgusu tetikler.
|
||||
Etiket sorgularının paralel yürütülmesi veya toplu işlenmesi yoktur.
|
||||
subgraph_size × 3 adet ayrı veritabanı çağrısına yol açar.
|
||||
|
||||
**3. Basit Önbellekleme Stratejisi (`maybe_label` fonksiyonu, 62-77 satırlar)**
|
||||
Boyut sınırları veya TTL (Yaşam Süresi) olmadan basit bir sözlük önbelleği.
|
||||
Önbellek çıkarma politikası olmaması, sınırsız bellek büyümesine yol açar.
|
||||
Önbellek hataları, ayrı veritabanı sorgularını tetikler.
|
||||
Ön yükleme veya akıllı önbellek önleme yoktur.
|
||||
|
||||
**4. Alt Optimum Sorgu Kalıpları**
|
||||
Benzer istekler arasında varlık vektör benzerliği sorguları önbelleğe alınmaz.
|
||||
Tekrarlayan sorgu kalıpları için sonuç memoizasyonu yoktur.
|
||||
Yaygın erişim kalıpları için sorgu optimizasyonu eksiktir.
|
||||
=======
|
||||
Her varlık için 3 ayrı veritabanı sorgusu yapar.
|
||||
Sorgu kalıbı: her varlık için konu tabanlı, öznelik tabanlı ve nesne tabanlı sorgular.
|
||||
Toplu işleme yok: Her sorgu yalnızca bir varlığı işler.
|
||||
Döngü algılama yok: Aynı düğümlere birden çok kez geri dönülebilir.
|
||||
Memoizasyon olmadan yinelemeli uygulama, üstel karmaşıklığa yol açar.
|
||||
Zaman karmaşıklığı: O(varlıklar × maks_yol_uzunluğu × üçlü_sınırı³)
|
||||
|
||||
**2. Sıralı Etiket Çözümleme (`get_labelgraph` fonksiyonu, 144-171 satırlar)**
|
||||
Her üç bileşenli (konu, öznelik, nesne) sırayla işler.
|
||||
Her `maybe_label` çağrısı potansiyel olarak bir veritabanı sorgusu tetikler.
|
||||
Etiket sorgularının paralel yürütülmesi veya toplu işlenmesi yok.
|
||||
subgraph_size × 3 adet ayrı veritabanı çağrısına yol açar.
|
||||
|
||||
**3. Basit Önbellekleme Stratejisi (`maybe_label` fonksiyonu, 62-77 satırlar)**
|
||||
Boyut sınırları veya TTL (Yaşam Süresi Sonu) olmadan basit bir sözlük önbelleği.
|
||||
Önbellek çıkarma politikası olmaması, sınırsız bellek büyümesine yol açar.
|
||||
Önbellek hataları, ayrı veritabanı sorgularını tetikler.
|
||||
Ön yükleme veya akıllı önbellek önleme yok.
|
||||
|
||||
**4. Alt Optimum Sorgu Kalıpları**
|
||||
Benzer istekler arasında varlık vektör benzerliği sorguları önbelleğe alınmaz.
|
||||
Tekrarlayan sorgu kalıpları için sonuç memoizasyonu yok.
|
||||
Yaygın erişim kalıpları için sorgu optimizasyonu eksik.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
**5. Kritik Nesne Ömrü Sorunları (`rag.py:96-102`)**
|
||||
**GraphRag nesnesi her istek için yeniden oluşturulur**: Her sorgu için yeni bir örnek oluşturulur, böylece tüm önbellek avantajları kaybolur.
|
||||
**Sorgu nesnesi son derece kısa ömürlüdür**: Tek bir sorgu yürütmesi içinde oluşturulur ve yok edilir (201-207 satırlar).
|
||||
**Etiket önbelleği her istek için sıfırlanır**: Önbellek önleme ve birikmiş bilgi istekler arasında kaybolur.
|
||||
**İstemci yeniden oluşturma ek yükü**: Veritabanı istemcileri potansiyel olarak her istek için yeniden oluşturulur.
|
||||
<<<<<<< HEAD
|
||||
**İstekler arası optimizasyon yok**: Sorgu kalıplarından veya sonuç paylaşımından yararlanamaz.
|
||||
=======
|
||||
**Çapraz istek optimizasyonu yok**: Sorgu kalıplarından veya sonuç paylaşımından yararlanamaz.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
### Performans Etki Analizi
|
||||
|
||||
Tipik bir sorgu için mevcut en kötü senaryo:
|
||||
**Varlık Alma**: 1 vektör benzerliği sorgusu.
|
||||
<<<<<<< HEAD
|
||||
**Graf Gezinme**: varlıklar × max_path_length × 3 × triple_limit sorgusu.
|
||||
=======
|
||||
**Graf Gezinme**: varlıklar × maks_yol_uzunluğu × 3 × üçlü_sınırı sorguları.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**Etiket Çözümleme**: subgraph_size × 3 adet ayrı etiket sorgusu.
|
||||
|
||||
Varsayılan parametreler için (50 varlık, yol uzunluğu 2, 30 üçlü sınırı, 150 alt grafik boyutu):
|
||||
**Minimum sorgular**: 1 + (50 × 2 × 3 × 30) + (150 × 3) = **9.451 veritabanı sorgusu**
|
||||
**Yanıt süresi**: Orta büyüklükteki grafikler için 15-30 saniye
|
||||
**Bellek kullanımı**: Zamanla sınırsız önbellek büyümesi
|
||||
**Önbellek etkinliği**: %0 - her istekte önbellekler sıfırlanır
|
||||
<<<<<<< HEAD
|
||||
**Nesne oluşturma ek yükü**: Her istek için oluşturulan/silinen GraphRag + Sorgu nesneleri
|
||||
=======
|
||||
**Nesne oluşturma ek yükü**: Her istek için GraphRag + Sorgu nesneleri oluşturulur/silinir
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
Bu özellik, toplu sorguları, akıllı önbelleği ve paralel işleme uygulayarak bu eksiklikleri giderir. Sorgu kalıplarını ve veri erişimini optimize ederek TrustGraph şunları yapabilir:
|
||||
Milyonlarca varlığa sahip kurumsal ölçekli bilgi grafiklerini destekleyin
|
||||
Tipik sorgular için saniyeden daha kısa yanıt süreleri sağlayın
|
||||
Yüzlerce eşzamanlı GraphRAG isteğini işleyin
|
||||
Grafik boyutu ve karmaşıklığıyla verimli bir şekilde ölçeklendirin
|
||||
|
||||
## Teknik Tasarım
|
||||
|
||||
### Mimari
|
||||
|
||||
GraphRAG performans optimizasyonu, aşağıdaki teknik bileşenleri gerektirir:
|
||||
|
||||
#### 1. **Nesne Ömrü Mimari Yeniden Düzenlemesi**
|
||||
**GraphRag'i uzun ömürlü hale getirin**: GraphRag örneğini, istekler arasında süreklilik sağlamak için İşlemci seviyesine taşıyın
|
||||
**Önbellekleri koruyun**: Etiket önbelleğini, gömme önbelleğini ve sorgu sonucu önbelleğini istekler arasında koruyun
|
||||
**Sorgu nesnesini optimize edin**: Sorguyu, veri kapsayıcısı değil, hafif bir yürütme bağlamı olarak yeniden düzenleyin
|
||||
**Bağlantı sürekliliği**: Veritabanı istemci bağlantılarını istekler arasında koruyun
|
||||
|
||||
Modül: `trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` (değiştirildi)
|
||||
|
||||
#### 2. **Optimize Edilmiş Grafik Gezinme Motoru**
|
||||
Özyinelemeli `follow_edges`'ı yinelemeli genişlik öncelikli arama ile değiştirin
|
||||
Her gezinme seviyesinde toplu varlık işleme uygulayın
|
||||
Ziyaret edilen düğüm takibi kullanarak döngü algılama ekleyin
|
||||
Sınırlar aşıldığında erken sonlandırma ekleyin
|
||||
|
||||
Modül: `trustgraph-flow/trustgraph/retrieval/graph_rag/optimized_traversal.py`
|
||||
|
||||
#### 3. **Paralel Etiket Çözümleme Sistemi**
|
||||
Birden çok varlık için etiket sorgularını aynı anda toplu olarak sorgulayın
|
||||
Eşzamanlı veritabanı erişimi için asenkron/bekle kalıplarını uygulayın
|
||||
Yaygın etiket kalıpları için akıllı ön yükleme ekleyin
|
||||
Etiket önbelleği ısıtma stratejileri ekleyin
|
||||
|
||||
Modül: `trustgraph-flow/trustgraph/retrieval/graph_rag/label_resolver.py`
|
||||
|
||||
#### 4. **Muhafazakar Etiket Önbelleği Katmanı**
|
||||
Performans ve tutarlılık dengesini sağlamak için yalnızca etiketler için kısa TTL'ye sahip LRU önbelleği (5 dakika)
|
||||
Önbellek metriklerini ve isabet oranını izleme
|
||||
**Gömme önbelleği yok**: Zaten her sorgu için önbelleğe alınmıştır, sorgular arası bir fayda yoktur
|
||||
**Sorgu sonucu önbelleği yok**: Grafik mutasyon tutarlılığı endişeleri nedeniyle
|
||||
|
||||
Modül: `trustgraph-flow/trustgraph/retrieval/graph_rag/cache_manager.py`
|
||||
|
||||
#### 5. **Sorgu Optimizasyon Çerçevesi**
|
||||
Sorgu kalıbı analizi ve optimizasyon önerileri
|
||||
Veritabanı erişimi için toplu sorgu koordinatörü
|
||||
Bağlantı havuzu ve sorgu zaman aşımı yönetimi
|
||||
Performans izleme ve ölçüm toplama
|
||||
|
||||
Modül: `trustgraph-flow/trustgraph/retrieval/graph_rag/query_optimizer.py`
|
||||
|
||||
### Veri Modelleri
|
||||
|
||||
#### Optimize Edilmiş Grafik Gezinme Durumu
|
||||
|
||||
Gezinme motoru, gereksiz işlemleri önlemek için durumu korur:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class TraversalState:
|
||||
visited_entities: Set[str]
|
||||
current_level_entities: Set[str]
|
||||
next_level_entities: Set[str]
|
||||
subgraph: Set[Tuple[str, str, str]]
|
||||
depth: int
|
||||
query_batch: List[TripleQuery]
|
||||
```
|
||||
|
||||
Bu yaklaşım şunları sağlar:
|
||||
Ziyaret edilen varlıkları takip ederek verimli döngü tespiti
|
||||
Her gezinme seviyesinde toplu sorgu hazırlama
|
||||
Bellek verimli durum yönetimi
|
||||
Boyut limitlerine ulaşıldığında erken sonlandırma
|
||||
|
||||
#### Gelişmiş Önbellek Yapısı
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class CacheEntry:
|
||||
value: Any
|
||||
timestamp: float
|
||||
access_count: int
|
||||
ttl: Optional[float]
|
||||
|
||||
class CacheManager:
|
||||
label_cache: LRUCache[str, CacheEntry]
|
||||
embedding_cache: LRUCache[str, CacheEntry]
|
||||
query_result_cache: LRUCache[str, CacheEntry]
|
||||
cache_stats: CacheStatistics
|
||||
```
|
||||
|
||||
#### Toplu Sorgu Yapıları
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class BatchTripleQuery:
|
||||
entities: List[str]
|
||||
query_type: QueryType # SUBJECT, PREDICATE, OBJECT
|
||||
limit_per_entity: int
|
||||
|
||||
@dataclass
|
||||
class BatchLabelQuery:
|
||||
entities: List[str]
|
||||
predicate: str = LABEL
|
||||
```
|
||||
|
||||
### API'ler
|
||||
|
||||
#### Yeni API'ler:
|
||||
|
||||
**GraphTraversal API'si**
|
||||
```python
|
||||
async def optimized_follow_edges_batch(
|
||||
entities: List[str],
|
||||
max_depth: int,
|
||||
triple_limit: int,
|
||||
max_subgraph_size: int
|
||||
) -> Set[Tuple[str, str, str]]
|
||||
```
|
||||
|
||||
**Toplu Etiket Çözümleme API'si**
|
||||
```python
|
||||
async def resolve_labels_batch(
|
||||
entities: List[str],
|
||||
cache_manager: CacheManager
|
||||
) -> Dict[str, str]
|
||||
```
|
||||
|
||||
**Önbellek Yönetimi API'si**
|
||||
```python
|
||||
class CacheManager:
|
||||
async def get_or_fetch_label(self, entity: str) -> str
|
||||
async def get_or_fetch_embeddings(self, query: str) -> List[float]
|
||||
async def cache_query_result(self, query_hash: str, result: Any, ttl: int)
|
||||
def get_cache_statistics(self) -> CacheStatistics
|
||||
```
|
||||
|
||||
#### Değiştirilmiş API'ler:
|
||||
|
||||
**GraphRag.query()** - Performans optimizasyonlarıyla geliştirildi:
|
||||
Önbellek kontrolü için `cache_manager` parametresi eklendi.
|
||||
Performans metriklerini içeren `performance_metrics` dönüş değeri eklendi.
|
||||
Güvenilirlik için `query_timeout` parametresi eklendi.
|
||||
|
||||
**Query sınıfı** - Toplu işleme için yeniden düzenlendi:
|
||||
Bireysel varlık işleme yerine toplu işlemler kullanıldı.
|
||||
Kaynak temizliği için asenkron bağlam yöneticileri eklendi.
|
||||
Uzun süren işlemler için ilerleme geri çağırmaları eklendi.
|
||||
|
||||
### Uygulama Detayları
|
||||
|
||||
#### Aşama 0: Kritik Mimari Yaşam Döngüsü Yeniden Düzenlemesi
|
||||
|
||||
**Mevcut Sorunlu Uygulama:**
|
||||
```python
|
||||
# INEFFICIENT: GraphRag recreated every request
|
||||
class Processor(FlowProcessor):
|
||||
async def on_request(self, msg, consumer, flow):
|
||||
# PROBLEM: New GraphRag instance per request!
|
||||
self.rag = GraphRag(
|
||||
embeddings_client = flow("embeddings-request"),
|
||||
graph_embeddings_client = flow("graph-embeddings-request"),
|
||||
triples_client = flow("triples-request"),
|
||||
prompt_client = flow("prompt-request"),
|
||||
verbose=True,
|
||||
)
|
||||
# Cache starts empty every time - no benefit from previous requests
|
||||
response = await self.rag.query(...)
|
||||
|
||||
# VERY SHORT-LIVED: Query object created/destroyed per request
|
||||
class GraphRag:
|
||||
async def query(self, query, user="trustgraph", collection="default", ...):
|
||||
q = Query(rag=self, user=user, collection=collection, ...) # Created
|
||||
kg = await q.get_labelgraph(query) # Used briefly
|
||||
# q automatically destroyed when function exits
|
||||
```
|
||||
|
||||
**Optimize Edilmiş, Uzun Ömürlü Mimari:**
|
||||
```python
|
||||
class Processor(FlowProcessor):
|
||||
def __init__(self, **params):
|
||||
super().__init__(**params)
|
||||
self.rag_instance = None # Will be initialized once
|
||||
self.client_connections = {}
|
||||
|
||||
async def initialize_rag(self, flow):
|
||||
"""Initialize GraphRag once, reuse for all requests"""
|
||||
if self.rag_instance is None:
|
||||
self.rag_instance = LongLivedGraphRag(
|
||||
embeddings_client=flow("embeddings-request"),
|
||||
graph_embeddings_client=flow("graph-embeddings-request"),
|
||||
triples_client=flow("triples-request"),
|
||||
prompt_client=flow("prompt-request"),
|
||||
verbose=True,
|
||||
)
|
||||
return self.rag_instance
|
||||
|
||||
async def on_request(self, msg, consumer, flow):
|
||||
# REUSE the same GraphRag instance - caches persist!
|
||||
rag = await self.initialize_rag(flow)
|
||||
|
||||
# Query object becomes lightweight execution context
|
||||
response = await rag.query_with_context(
|
||||
query=v.query,
|
||||
execution_context=QueryContext(
|
||||
user=v.user,
|
||||
collection=v.collection,
|
||||
entity_limit=entity_limit,
|
||||
# ... other params
|
||||
)
|
||||
)
|
||||
|
||||
class LongLivedGraphRag:
|
||||
def __init__(self, ...):
|
||||
# CONSERVATIVE caches - balance performance vs consistency
|
||||
self.label_cache = LRUCacheWithTTL(max_size=5000, ttl=300) # 5min TTL for freshness
|
||||
# Note: No embedding cache - already cached per-query, no cross-query benefit
|
||||
# Note: No query result cache due to consistency concerns
|
||||
self.performance_metrics = PerformanceTracker()
|
||||
|
||||
async def query_with_context(self, query: str, context: QueryContext):
|
||||
# Use lightweight QueryExecutor instead of heavyweight Query object
|
||||
executor = QueryExecutor(self, context) # Minimal object
|
||||
return await executor.execute(query)
|
||||
|
||||
@dataclass
|
||||
class QueryContext:
|
||||
"""Lightweight execution context - no heavy operations"""
|
||||
user: str
|
||||
collection: str
|
||||
entity_limit: int
|
||||
triple_limit: int
|
||||
max_subgraph_size: int
|
||||
max_path_length: int
|
||||
|
||||
class QueryExecutor:
|
||||
"""Lightweight execution context - replaces old Query class"""
|
||||
def __init__(self, rag: LongLivedGraphRag, context: QueryContext):
|
||||
self.rag = rag
|
||||
self.context = context
|
||||
# No heavy initialization - just references
|
||||
|
||||
async def execute(self, query: str):
|
||||
# All heavy lifting uses persistent rag caches
|
||||
return await self.rag.execute_optimized_query(query, self.context)
|
||||
```
|
||||
|
||||
Bu mimari değişiklik şunları sağlar:
|
||||
**Ortak ilişkileri olan grafikler için veritabanı sorgu sayısında %10-20'lik bir azalma** (şu anda %0'a kıyasla)
|
||||
<<<<<<< HEAD
|
||||
Her istek için **ortadan kaldırılan nesne oluşturma ek yükü**
|
||||
=======
|
||||
Her istek için **oluşturulan nesnelerin getirdiği ek yükün ortadan kaldırılması**
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**Sürekli bağlantı havuzu** ve istemci yeniden kullanımı
|
||||
Önbellek TTL (Yaşam Süresi) aralıkları içinde **istemler arası optimizasyon**
|
||||
|
||||
**Önemli Önbellek Tutarlılık Sınırlaması:**
|
||||
<<<<<<< HEAD
|
||||
Uzun süreli önbellekleme, temel grafikteki varlıkların/etiketlerin silindiği veya değiştirildiği durumlarda, güncelliği kaybetme riski oluşturur. LRU (En Son Kullanılmayan) önbelleği, performans kazanımları ile veri tazeliği arasında bir denge sağlarken, gerçek zamanlı grafik değişikliklerini tespit edemez.
|
||||
=======
|
||||
Uzun süreli önbellekleme, temel grafikteki varlıkların/etiketlerin silindiği veya değiştirildiği durumlarda, verilerin güncelliğini yitirme riski oluşturur. LRU (En Son Kullanılmayan) önbelleği, performans artışları ve veri tazeliği arasında bir denge sağlar, ancak gerçek zamanlı grafik değişikliklerini tespit edemez.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### 1. Aşama: Grafik Gezinme Optimizasyonu
|
||||
|
||||
**Mevcut Uygulama Sorunları:**
|
||||
```python
|
||||
# INEFFICIENT: 3 queries per entity per level
|
||||
async def follow_edges(self, ent, subgraph, path_length):
|
||||
# Query 1: s=ent, p=None, o=None
|
||||
res = await self.rag.triples_client.query(s=ent, p=None, o=None, limit=self.triple_limit)
|
||||
# Query 2: s=None, p=ent, o=None
|
||||
res = await self.rag.triples_client.query(s=None, p=ent, o=None, limit=self.triple_limit)
|
||||
# Query 3: s=None, p=None, o=ent
|
||||
res = await self.rag.triples_client.query(s=None, p=None, o=ent, limit=self.triple_limit)
|
||||
```
|
||||
|
||||
**Optimize Edilmiş Uygulama:**
|
||||
```python
|
||||
async def optimized_traversal(self, entities: List[str], max_depth: int) -> Set[Triple]:
|
||||
visited = set()
|
||||
current_level = set(entities)
|
||||
subgraph = set()
|
||||
|
||||
for depth in range(max_depth):
|
||||
if not current_level or len(subgraph) >= self.max_subgraph_size:
|
||||
break
|
||||
|
||||
# Batch all queries for current level
|
||||
batch_queries = []
|
||||
for entity in current_level:
|
||||
if entity not in visited:
|
||||
batch_queries.extend([
|
||||
TripleQuery(s=entity, p=None, o=None),
|
||||
TripleQuery(s=None, p=entity, o=None),
|
||||
TripleQuery(s=None, p=None, o=entity)
|
||||
])
|
||||
|
||||
# Execute all queries concurrently
|
||||
results = await self.execute_batch_queries(batch_queries)
|
||||
|
||||
# Process results and prepare next level
|
||||
next_level = set()
|
||||
for result in results:
|
||||
subgraph.update(result.triples)
|
||||
next_level.update(result.new_entities)
|
||||
|
||||
visited.update(current_level)
|
||||
current_level = next_level - visited
|
||||
|
||||
return subgraph
|
||||
```
|
||||
|
||||
#### 2. Aşama: Paralel Etiket Çözümlemesi
|
||||
|
||||
**Mevcut Sıralı Uygulama:**
|
||||
```python
|
||||
# INEFFICIENT: Sequential processing
|
||||
for edge in subgraph:
|
||||
s = await self.maybe_label(edge[0]) # Individual query
|
||||
p = await self.maybe_label(edge[1]) # Individual query
|
||||
o = await self.maybe_label(edge[2]) # Individual query
|
||||
```
|
||||
|
||||
**Optimize Edilmiş Paralel Uygulama:**
|
||||
```python
|
||||
async def resolve_labels_parallel(self, subgraph: List[Triple]) -> List[Triple]:
|
||||
# Collect all unique entities needing labels
|
||||
entities_to_resolve = set()
|
||||
for s, p, o in subgraph:
|
||||
entities_to_resolve.update([s, p, o])
|
||||
|
||||
# Remove already cached entities
|
||||
uncached_entities = [e for e in entities_to_resolve if e not in self.label_cache]
|
||||
|
||||
# Batch query for all uncached labels
|
||||
if uncached_entities:
|
||||
label_results = await self.batch_label_query(uncached_entities)
|
||||
self.label_cache.update(label_results)
|
||||
|
||||
# Apply labels to subgraph
|
||||
return [
|
||||
(self.label_cache.get(s, s), self.label_cache.get(p, p), self.label_cache.get(o, o))
|
||||
for s, p, o in subgraph
|
||||
]
|
||||
```
|
||||
|
||||
#### 3. Aşama: Gelişmiş Önbellekleme Stratejisi
|
||||
|
||||
**TTL ile LRU Önbelleği:**
|
||||
```python
|
||||
class LRUCacheWithTTL:
|
||||
def __init__(self, max_size: int, default_ttl: int = 3600):
|
||||
self.cache = OrderedDict()
|
||||
self.max_size = max_size
|
||||
self.default_ttl = default_ttl
|
||||
self.access_times = {}
|
||||
|
||||
async def get(self, key: str) -> Optional[Any]:
|
||||
if key in self.cache:
|
||||
# Check TTL expiration
|
||||
if time.time() - self.access_times[key] > self.default_ttl:
|
||||
del self.cache[key]
|
||||
del self.access_times[key]
|
||||
return None
|
||||
|
||||
# Move to end (most recently used)
|
||||
self.cache.move_to_end(key)
|
||||
return self.cache[key]
|
||||
return None
|
||||
|
||||
async def put(self, key: str, value: Any):
|
||||
if key in self.cache:
|
||||
self.cache.move_to_end(key)
|
||||
else:
|
||||
if len(self.cache) >= self.max_size:
|
||||
# Remove least recently used
|
||||
oldest_key = next(iter(self.cache))
|
||||
del self.cache[oldest_key]
|
||||
del self.access_times[oldest_key]
|
||||
|
||||
self.cache[key] = value
|
||||
self.access_times[key] = time.time()
|
||||
```
|
||||
|
||||
#### 4. Aşama: Sorgu Optimizasyonu ve İzleme
|
||||
|
||||
**Performans Metrikleri Toplama:**
|
||||
```python
|
||||
@dataclass
|
||||
class PerformanceMetrics:
|
||||
total_queries: int
|
||||
cache_hits: int
|
||||
cache_misses: int
|
||||
avg_response_time: float
|
||||
subgraph_construction_time: float
|
||||
label_resolution_time: float
|
||||
total_entities_processed: int
|
||||
memory_usage_mb: float
|
||||
```
|
||||
|
||||
**Sorgu Zaman Aşımı ve Devre Kesici:**
|
||||
```python
|
||||
async def execute_with_timeout(self, query_func, timeout: int = 30):
|
||||
try:
|
||||
return await asyncio.wait_for(query_func(), timeout=timeout)
|
||||
except asyncio.TimeoutError:
|
||||
logger.error(f"Query timeout after {timeout}s")
|
||||
raise GraphRagTimeoutError(f"Query exceeded timeout of {timeout}s")
|
||||
```
|
||||
|
||||
## Önbellek Tutarlılık Hususları
|
||||
|
||||
**Veri Güncelliği Dengesi:**
|
||||
**Etiket önbelleği (5 dakika TTL):** Silinmiş/yeniden adlandırılmış varlık etiketlerini sunma riski.
|
||||
**Gömme önbelleği yok:** Gerekli değil - gömmeler zaten her sorgu için önbelleğe alınmıştır.
|
||||
**Sonuç önbelleği yok:** Silinmiş varlıklar/ilişkilerden kaynaklanan eski alt grafik sonuçlarını önler.
|
||||
|
||||
**Azaltma Stratejileri:**
|
||||
**Muhafazakar TTL değerleri:** Performans kazanımları (10-20%) ile veri güncelliği arasındaki denge.
|
||||
<<<<<<< HEAD
|
||||
**Önbellek geçersiz kılma kancaları:** İsteğe bağlı olarak grafik mutasyon olaylarıyla entegrasyon.
|
||||
=======
|
||||
**Önbellek geçersiz kılma mekanizmaları:** Grafik mutasyon olaylarıyla isteğe bağlı entegrasyon.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
**İzleme panoları:** Önbellek isabet oranlarını, veri güncelliği sorunlarıyla karşılaştırarak izleyin.
|
||||
**Yapılandırılabilir önbellek politikaları:** Mutasyon sıklığına göre dağıtıma özel ayarlamalar yapılmasına izin verir.
|
||||
|
||||
**Grafik Mutasyon Oranına Göre Önerilen Önbellek Yapılandırması:**
|
||||
**Yüksek mutasyon (>100 değişiklik/saat):** TTL=60s, daha küçük önbellek boyutları.
|
||||
**Orta mutasyon (10-100 değişiklik/saat):** TTL=300s (varsayılan).
|
||||
**Düşük mutasyon (<10 değişiklik/saat):** TTL=600s, daha büyük önbellek boyutları.
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
<<<<<<< HEAD
|
||||
**Sorgu Enjeksiyonunu Önleme:**
|
||||
=======
|
||||
**Sorgu Enjeksiyonu Önleme:**
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Tüm varlık tanımlayıcılarını ve sorgu parametrelerini doğrulayın.
|
||||
Tüm veritabanı etkileşimleri için parametreli sorgular kullanın.
|
||||
DoS saldırılarını önlemek için sorgu karmaşıklığı limitleri uygulayın.
|
||||
|
||||
**Kaynak Koruması:**
|
||||
<<<<<<< HEAD
|
||||
Maksimum alt grafik boyutları limitlerini uygulayın.
|
||||
Kaynak tükenmesini önlemek için sorgu zaman aşımlarını uygulayın.
|
||||
=======
|
||||
Maksimum alt grafik boyutları için limitler uygulayın.
|
||||
Kaynak tükenmesini önlemek için sorgu zaman aşımları uygulayın.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Bellek kullanımı izleme ve limitleri ekleyin.
|
||||
|
||||
**Erişim Kontrolü:**
|
||||
Mevcut kullanıcı ve koleksiyon izolasyonunu koruyun.
|
||||
Performansı etkileyen işlemler için denetim kaydı ekleyin.
|
||||
Pahalı işlemler için hız sınırlaması uygulayın.
|
||||
|
||||
## Performans Hususları
|
||||
|
||||
### Beklenen Performans İyileştirmeleri
|
||||
|
||||
**Sorgu Azaltma:**
|
||||
<<<<<<< HEAD
|
||||
Mevcut: Tipik bir istek için ~9.000+ sorgu.
|
||||
=======
|
||||
Mevcut: Tipik bir istek için ~9.000'den fazla sorgu.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Optimize edilmiş: ~50-100 toplu sorgu (98% azalma).
|
||||
|
||||
**Yanıt Süresi İyileştirmeleri:**
|
||||
Grafik geçişi: 15-20s → 3-5s (4-5 kat daha hızlı).
|
||||
Etiket çözümü: 8-12s → 2-4s (3 kat daha hızlı).
|
||||
Genel sorgu: 25-35s → 6-10s (3-4 kat iyileşme).
|
||||
|
||||
**Bellek Verimliliği:**
|
||||
Sınırlı önbellek boyutları, bellek sızıntılarını önler.
|
||||
Verimli veri yapıları, bellek ayak izini yaklaşık %40 azaltır.
|
||||
Uygun kaynak temizliği sayesinde daha iyi çöp toplama.
|
||||
|
||||
**Gerçekçi Performans Beklentileri:**
|
||||
**Etiket önbelleği:** Ortak ilişkilere sahip grafikler için sorgu azaltmada %10-20.
|
||||
**Toplu optimizasyon:** %50-80 sorgu azaltma (birincil optimizasyon).
|
||||
**Nesne ömrü optimizasyonu:** Her istekte oluşturma ek yükünü ortadan kaldırır.
|
||||
**Genel iyileşme:** Toplu işlemden kaynaklanan 3-4 kat yanıt süresi iyileşmesi.
|
||||
|
||||
**Ölçeklenebilirlik İyileştirmeleri:**
|
||||
<<<<<<< HEAD
|
||||
3-5 kat daha büyük bilgi grafiklerini destekler (önbellek tutarlılık ihtiyaçları ile sınırlıdır).
|
||||
=======
|
||||
3-5 kat daha büyük bilgi grafiklerini destekler (önbellek tutarlılık gereksinimleriyle sınırlıdır).
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
3-5 kat daha yüksek eşzamanlı istek kapasitesi.
|
||||
Bağlantı yeniden kullanımı sayesinde daha iyi kaynak kullanımı.
|
||||
|
||||
### Performans İzleme
|
||||
|
||||
**Gerçek Zamanlı Metrikler:**
|
||||
İşlem türüne göre sorgu yürütme süreleri.
|
||||
Önbellek isabet oranları ve etkinliği.
|
||||
Veritabanı bağlantı havuzu kullanımı.
|
||||
Bellek kullanımı ve çöp toplama etkisi.
|
||||
|
||||
**Performans Karşılaştırması:**
|
||||
Otomatik performans gerileme testi
|
||||
Gerçekçi veri hacimleriyle yük testi
|
||||
Mevcut uygulamaya karşı karşılaştırma testleri
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
### Birim Testi
|
||||
Gezinme, önbellekleme ve etiket çözümleme için bireysel bileşen testi
|
||||
Performans testi için sahte veritabanı etkileşimleri
|
||||
Önbellek temizleme ve TTL (Yaşam Süresi) sonlandırma testi
|
||||
Hata işleme ve zaman aşımı senaryoları
|
||||
|
||||
### Entegrasyon Testi
|
||||
Optimizasyonlarla uçtan uca GraphRAG sorgu testi
|
||||
<<<<<<< HEAD
|
||||
Gerçek verilerle veritabanı etkileşim testi
|
||||
=======
|
||||
Gerçek verilerle veritabanı etkileşimi testi
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Eşzamanlı istek işleme ve kaynak yönetimi
|
||||
Bellek sızıntısı tespiti ve kaynak temizleme doğrulaması
|
||||
|
||||
### Performans Testi
|
||||
Mevcut uygulamaya karşı karşılaştırma testi
|
||||
Farklı grafik boyutları ve karmaşıklıklarla yük testi
|
||||
Bellek ve bağlantı limitleri için stres testi
|
||||
Performans iyileştirmeleri için regresyon testi
|
||||
|
||||
### Uyumluluk Testi
|
||||
Mevcut GraphRAG API uyumluluğunu doğrulayın
|
||||
Çeşitli grafik veritabanı arka uçlarıyla test yapın
|
||||
Mevcut uygulamaya kıyasla sonuç doğruluğunu doğrulayın
|
||||
|
||||
## Uygulama Planı
|
||||
|
||||
### Doğrudan Uygulama Yaklaşımı
|
||||
API'lerin değişmesine izin verildiğinden, geçiş karmaşıklığı olmadan doğrudan optimizasyonları uygulayın:
|
||||
|
||||
1. **`follow_edges` yöntemini değiştirin**: Yinelemeli toplu işleme ile yeniden yazın
|
||||
<<<<<<< HEAD
|
||||
2. **`get_labelgraph`'ı optimize edin**: Paralel etiket çözümlemeyi uygulayın
|
||||
3. **Uzun ömürlü GraphRag ekleyin**: Kalıcı bir örnek tutmak için İşlemci'yi değiştirin
|
||||
4. **Etiket önbelleğini uygulayın**: GraphRag sınıfına TTL ile LRU (En Son Kullanılan) önbelleği ekleyin
|
||||
=======
|
||||
2. **`get_labelgraph`'ı optimize edin**: Paralel etiket çözümlemesini uygulayın
|
||||
3. **Uzun ömürlü GraphRag ekleyin**: Kalıcı bir örnek tutmak için İşlemci'yi değiştirin
|
||||
4. **Etiket önbelleklemesini uygulayın**: GraphRag sınıfına TTL ile LRU (En Son Kullanılan) önbelleği ekleyin
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
### Değişiklik Kapsamı
|
||||
**Sorgu sınıfı**: `follow_edges` içinde ~50 satırı değiştirin, toplu işleme için ~30 satır ekleyin
|
||||
**GraphRag sınıfı**: Önbellekleme katmanı ekleyin (~40 satır)
|
||||
**İşlemci sınıfı**: Kalıcı bir GraphRag örneği kullanmak için değiştirin (~20 satır)
|
||||
**Toplam**: Odaklanmış değişikliklerin ~140 satırı, çoğunlukla mevcut sınıfların içinde
|
||||
|
||||
## Zaman Çizelgesi
|
||||
|
||||
**1. Hafta: Temel Uygulama**
|
||||
`follow_edges`'ı toplu yinelemeli gezinmeyle değiştirin
|
||||
<<<<<<< HEAD
|
||||
`get_labelgraph` içinde paralel etiket çözümlemeyi uygulayın
|
||||
=======
|
||||
`get_labelgraph` içinde paralel etiket çözümlemesini uygulayın
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
İşlemci'ye uzun ömürlü GraphRag örneği ekleyin
|
||||
Etiket önbellekleme katmanı uygulayın
|
||||
|
||||
**2. Hafta: Test ve Entegrasyon**
|
||||
Yeni gezinme ve önbellekleme mantığı için birim testleri
|
||||
Mevcut uygulamaya karşı performans karşılaştırması
|
||||
Gerçek grafik verileriyle entegrasyon testi
|
||||
Kod incelemesi ve optimizasyon
|
||||
|
||||
**3. Hafta: Dağıtım**
|
||||
Optimize edilmiş uygulamayı dağıtın
|
||||
Performans iyileştirmelerini izleyin
|
||||
<<<<<<< HEAD
|
||||
Gerçek kullanım temelinde önbellek TTL'sini ve toplu boyutları ayarlayın
|
||||
=======
|
||||
Gerçek kullanım bazında önbellek TTL'sini ve toplu boyutları ayarlayın
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Açık Sorular
|
||||
|
||||
**Veritabanı Bağlantı Havuzu**: Özel bir bağlantı havuzu mu uygulamalıyız yoksa mevcut veritabanı istemci havuzuna mı güvenmeliyiz?
|
||||
**Önbellek Kalıcılığı**: Etiket ve gömme önbellekleri hizmet yeniden başlatmalarında kalıcı mı olmalı?
|
||||
**Dağıtılmış Önbellekleme**: Çok örnekli dağıtımlar için Redis/Memcached ile dağıtılmış önbellekleme mi uygulamalıyız?
|
||||
**Sorgu Sonucu Formatı**: Daha iyi bellek verimliliği için dahili üçlü gösterimi optimize etmeli miyiz?
|
||||
**İzleme Entegrasyonu**: Hangi ölçümler mevcut izleme sistemlerine (Prometheus, vb.) maruz bırakılmalıdır?
|
||||
|
||||
## Referanslar
|
||||
|
||||
[GraphRAG Orijinal Uygulaması](trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py)
|
||||
[TrustGraph Mimari Prensipleri](architecture-principles.md)
|
||||
[Koleksiyon Yönetimi Özellikleri](collection-management.md)
|
||||
729
docs/tech-specs/tr/import-export-graceful-shutdown.tr.md
Normal file
729
docs/tech-specs/tr/import-export-graceful-shutdown.tr.md
Normal file
|
|
@ -0,0 +1,729 @@
|
|||
---
|
||||
layout: default
|
||||
title: "İçe/Dışa Aktarma, Zarif Kapanış Teknik Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# İçe/Dışa Aktarma, Zarif Kapanış 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.
|
||||
|
||||
## Problem Tanımı
|
||||
|
||||
<<<<<<< HEAD
|
||||
TrustGraph ağ geçidi, hem içe aktarma hem de dışa aktarma işlemlerinde websocket kapanışı sırasında mesaj kaybı yaşamaktadır. Bu, aktarım halindeki mesajların, hedeflerine (içe aktarmalar için Pulsar kuyrukları, dışa aktarmalar için websocket istemcileri) ulaşmadan önce atıldığı yarış koşulları nedeniyle oluşmaktadır.
|
||||
|
||||
### İçe Aktarma Tarafındaki Sorunlar
|
||||
1. Yayınlayıcının asyncio.Queue tamponu, kapanışta boşaltılmamaktadır.
|
||||
=======
|
||||
TrustGraph geçidi, hem içe hem de dışa aktarma işlemlerinde websocket kapanması sırasında mesaj kaybı yaşamaktadır. Bu, aktarım halindeki mesajların, hedeflerine (içe aktarmalar için Pulsar kuyrukları, dışa aktarmalar için websocket istemcileri) ulaşmadan önce atıldığı yarış koşulları nedeniyle oluşmaktadır.
|
||||
|
||||
### İçe Aktarma Tarafındaki Sorunlar
|
||||
1. Yayınlayıcının asyncio.Queue tamponu, kapanmada boşaltılmamaktadır.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
2. Websocket, kuyruğa alınmış mesajların Pulsar'a ulaşmasını sağladıktan sonra kapanmaktadır.
|
||||
3. Başarılı mesaj teslimatı için bir onay mekanizması bulunmamaktadır.
|
||||
|
||||
### Dışa Aktarma Tarafındaki Sorunlar
|
||||
1. Mesajlar, istemcilere başarılı bir şekilde teslim edilmeden önce Pulsar'da onaylanmaktadır.
|
||||
2. Sabit kodlu zaman aşımı değerleri, kuyruklar dolduğunda mesaj kayıplarına neden olmaktadır.
|
||||
3. Yavaş tüketicileri işlemek için bir geri basınç mekanizması bulunmamaktadır.
|
||||
<<<<<<< HEAD
|
||||
4. Verilerin kaybolabileceği birden fazla tampon noktası bulunmaktadır.
|
||||
=======
|
||||
4. Verilerin kaybolabileceği birden fazla tamponlama noktası bulunmaktadır.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Mimari Genel Bakış
|
||||
|
||||
```
|
||||
Import Flow:
|
||||
Client -> Websocket -> TriplesImport -> Publisher -> Pulsar Queue
|
||||
|
||||
Export Flow:
|
||||
Pulsar Queue -> Subscriber -> TriplesExport -> Websocket -> Client
|
||||
```
|
||||
|
||||
## Önerilen Çözümler
|
||||
|
||||
### 1. Yayıncı İyileştirmeleri (İçe Aktarma Tarafı)
|
||||
|
||||
#### A. Zarif Kuyruk Boşaltma
|
||||
|
||||
**Dosya**: `trustgraph-base/trustgraph/base/publisher.py`
|
||||
|
||||
```python
|
||||
class Publisher:
|
||||
def __init__(self, client, topic, schema=None, max_size=10,
|
||||
chunking_enabled=True, drain_timeout=5.0):
|
||||
self.client = client
|
||||
self.topic = topic
|
||||
self.schema = schema
|
||||
self.q = asyncio.Queue(maxsize=max_size)
|
||||
self.chunking_enabled = chunking_enabled
|
||||
self.running = True
|
||||
self.draining = False # New state for graceful shutdown
|
||||
self.task = None
|
||||
self.drain_timeout = drain_timeout
|
||||
|
||||
async def stop(self):
|
||||
"""Initiate graceful shutdown with draining"""
|
||||
self.running = False
|
||||
self.draining = True
|
||||
|
||||
if self.task:
|
||||
# Wait for run() to complete draining
|
||||
await self.task
|
||||
|
||||
async def run(self):
|
||||
"""Enhanced run method with integrated draining logic"""
|
||||
while self.running or self.draining:
|
||||
try:
|
||||
producer = self.client.create_producer(
|
||||
topic=self.topic,
|
||||
schema=JsonSchema(self.schema),
|
||||
chunking_enabled=self.chunking_enabled,
|
||||
)
|
||||
|
||||
drain_end_time = None
|
||||
|
||||
while self.running or self.draining:
|
||||
try:
|
||||
# Start drain timeout when entering drain mode
|
||||
if self.draining and drain_end_time is None:
|
||||
drain_end_time = time.time() + self.drain_timeout
|
||||
logger.info(f"Publisher entering drain mode, timeout={self.drain_timeout}s")
|
||||
|
||||
# Check drain timeout
|
||||
if self.draining and time.time() > drain_end_time:
|
||||
if not self.q.empty():
|
||||
logger.warning(f"Drain timeout reached with {self.q.qsize()} messages remaining")
|
||||
self.draining = False
|
||||
break
|
||||
|
||||
# Calculate wait timeout based on mode
|
||||
if self.draining:
|
||||
# Shorter timeout during draining to exit quickly when empty
|
||||
timeout = min(0.1, drain_end_time - time.time())
|
||||
else:
|
||||
# Normal operation timeout
|
||||
timeout = 0.25
|
||||
|
||||
# Get message from queue
|
||||
id, item = await asyncio.wait_for(
|
||||
self.q.get(),
|
||||
timeout=timeout
|
||||
)
|
||||
|
||||
# Send the message (single place for sending)
|
||||
if id:
|
||||
producer.send(item, { "id": id })
|
||||
else:
|
||||
producer.send(item)
|
||||
|
||||
except asyncio.TimeoutError:
|
||||
# If draining and queue is empty, we're done
|
||||
if self.draining and self.q.empty():
|
||||
logger.info("Publisher queue drained successfully")
|
||||
self.draining = False
|
||||
break
|
||||
continue
|
||||
|
||||
except asyncio.QueueEmpty:
|
||||
# If draining and queue is empty, we're done
|
||||
if self.draining and self.q.empty():
|
||||
logger.info("Publisher queue drained successfully")
|
||||
self.draining = False
|
||||
break
|
||||
continue
|
||||
|
||||
# Flush producer before closing
|
||||
if producer:
|
||||
producer.flush()
|
||||
producer.close()
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Exception in publisher: {e}", exc_info=True)
|
||||
|
||||
if not self.running and not self.draining:
|
||||
return
|
||||
|
||||
# If handler drops out, sleep a retry
|
||||
await asyncio.sleep(1)
|
||||
|
||||
async def send(self, id, item):
|
||||
"""Send still works normally - just adds to queue"""
|
||||
if self.draining:
|
||||
# Optionally reject new messages during drain
|
||||
raise RuntimeError("Publisher is shutting down, not accepting new messages")
|
||||
await self.q.put((id, item))
|
||||
```
|
||||
|
||||
**Temel Tasarım Avantajları:**
|
||||
**Tek Gönderme Konumu**: Tüm `producer.send()` çağrıları, `run()` metodu içinde tek bir yerde gerçekleşir.
|
||||
**Temiz Durum Makinesi**: Üç açık durum - çalışıyor, boşaltılıyor, durdurulmuş.
|
||||
**Zaman Aşımı Koruması**: Boşaltma sırasında sonsuza kadar takılmayacaktır.
|
||||
**Daha İyi Gözlemlenebilirlik**: Boşaltma ilerlemesi ve durum geçişlerinin açık bir şekilde günlüğe kaydedilmesi.
|
||||
<<<<<<< HEAD
|
||||
**İsteğe Bağlı Mesaj Reddi**: Kapatma aşamasında yeni mesajları reddedebilir.
|
||||
=======
|
||||
**İsteğe Bağlı Mesaj Reddi**: Kapatma aşamasında yeni mesajları reddetme imkanı.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### B. İyileştirilmiş Kapatma Sırası
|
||||
|
||||
**Dosya**: `trustgraph-flow/trustgraph/gateway/dispatch/triples_import.py`
|
||||
|
||||
```python
|
||||
class TriplesImport:
|
||||
async def destroy(self):
|
||||
"""Enhanced destroy with proper shutdown order"""
|
||||
# Step 1: Stop accepting new messages
|
||||
self.running.stop()
|
||||
|
||||
# Step 2: Wait for publisher to drain its queue
|
||||
logger.info("Draining publisher queue...")
|
||||
await self.publisher.stop()
|
||||
|
||||
# Step 3: Close websocket only after queue is drained
|
||||
if self.ws:
|
||||
await self.ws.close()
|
||||
```
|
||||
|
||||
### 2. Abonelik İyileştirmeleri (Dışa Aktarma Tarafı)
|
||||
|
||||
#### A. Entegre Boşaltma Modeli
|
||||
|
||||
**Dosya**: `trustgraph-base/trustgraph/base/subscriber.py`
|
||||
|
||||
```python
|
||||
class Subscriber:
|
||||
def __init__(self, client, topic, subscription, consumer_name,
|
||||
schema=None, max_size=100, metrics=None,
|
||||
backpressure_strategy="block", drain_timeout=5.0):
|
||||
# ... existing init ...
|
||||
self.backpressure_strategy = backpressure_strategy
|
||||
self.running = True
|
||||
self.draining = False # New state for graceful shutdown
|
||||
self.drain_timeout = drain_timeout
|
||||
self.pending_acks = {} # Track messages awaiting delivery
|
||||
|
||||
async def stop(self):
|
||||
"""Initiate graceful shutdown with draining"""
|
||||
self.running = False
|
||||
self.draining = True
|
||||
|
||||
if self.task:
|
||||
# Wait for run() to complete draining
|
||||
await self.task
|
||||
|
||||
async def run(self):
|
||||
"""Enhanced run method with integrated draining logic"""
|
||||
while self.running or self.draining:
|
||||
if self.metrics:
|
||||
self.metrics.state("stopped")
|
||||
|
||||
try:
|
||||
self.consumer = self.client.subscribe(
|
||||
topic = self.topic,
|
||||
subscription_name = self.subscription,
|
||||
consumer_name = self.consumer_name,
|
||||
schema = JsonSchema(self.schema),
|
||||
)
|
||||
|
||||
if self.metrics:
|
||||
self.metrics.state("running")
|
||||
|
||||
logger.info("Subscriber running...")
|
||||
drain_end_time = None
|
||||
|
||||
while self.running or self.draining:
|
||||
# Start drain timeout when entering drain mode
|
||||
if self.draining and drain_end_time is None:
|
||||
drain_end_time = time.time() + self.drain_timeout
|
||||
logger.info(f"Subscriber entering drain mode, timeout={self.drain_timeout}s")
|
||||
|
||||
# Stop accepting new messages from Pulsar during drain
|
||||
self.consumer.pause_message_listener()
|
||||
|
||||
# Check drain timeout
|
||||
if self.draining and time.time() > drain_end_time:
|
||||
async with self.lock:
|
||||
total_pending = sum(
|
||||
q.qsize() for q in
|
||||
list(self.q.values()) + list(self.full.values())
|
||||
)
|
||||
if total_pending > 0:
|
||||
logger.warning(f"Drain timeout reached with {total_pending} messages in queues")
|
||||
self.draining = False
|
||||
break
|
||||
|
||||
# Check if we can exit drain mode
|
||||
if self.draining:
|
||||
async with self.lock:
|
||||
all_empty = all(
|
||||
q.empty() for q in
|
||||
list(self.q.values()) + list(self.full.values())
|
||||
)
|
||||
if all_empty and len(self.pending_acks) == 0:
|
||||
logger.info("Subscriber queues drained successfully")
|
||||
self.draining = False
|
||||
break
|
||||
|
||||
# Process messages only if not draining
|
||||
if not self.draining:
|
||||
try:
|
||||
msg = await asyncio.to_thread(
|
||||
self.consumer.receive,
|
||||
timeout_millis=250
|
||||
)
|
||||
except _pulsar.Timeout:
|
||||
continue
|
||||
except Exception as e:
|
||||
logger.error(f"Exception in subscriber receive: {e}", exc_info=True)
|
||||
raise e
|
||||
|
||||
if self.metrics:
|
||||
self.metrics.received()
|
||||
|
||||
# Process the message
|
||||
await self._process_message(msg)
|
||||
else:
|
||||
# During draining, just wait for queues to empty
|
||||
await asyncio.sleep(0.1)
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Subscriber exception: {e}", exc_info=True)
|
||||
|
||||
finally:
|
||||
# Negative acknowledge any pending messages
|
||||
for msg in self.pending_acks.values():
|
||||
self.consumer.negative_acknowledge(msg)
|
||||
self.pending_acks.clear()
|
||||
|
||||
if self.consumer:
|
||||
self.consumer.unsubscribe()
|
||||
self.consumer.close()
|
||||
self.consumer = None
|
||||
|
||||
if self.metrics:
|
||||
self.metrics.state("stopped")
|
||||
|
||||
if not self.running and not self.draining:
|
||||
return
|
||||
|
||||
# If handler drops out, sleep a retry
|
||||
await asyncio.sleep(1)
|
||||
|
||||
async def _process_message(self, msg):
|
||||
"""Process a single message with deferred acknowledgment"""
|
||||
# Store message for later acknowledgment
|
||||
msg_id = str(uuid.uuid4())
|
||||
self.pending_acks[msg_id] = msg
|
||||
|
||||
try:
|
||||
id = msg.properties()["id"]
|
||||
except:
|
||||
id = None
|
||||
|
||||
value = msg.value()
|
||||
delivery_success = False
|
||||
|
||||
async with self.lock:
|
||||
# Deliver to specific subscribers
|
||||
if id in self.q:
|
||||
delivery_success = await self._deliver_to_queue(
|
||||
self.q[id], value
|
||||
)
|
||||
|
||||
# Deliver to all subscribers
|
||||
for q in self.full.values():
|
||||
if await self._deliver_to_queue(q, value):
|
||||
delivery_success = True
|
||||
|
||||
# Acknowledge only on successful delivery
|
||||
if delivery_success:
|
||||
self.consumer.acknowledge(msg)
|
||||
del self.pending_acks[msg_id]
|
||||
else:
|
||||
# Negative acknowledge for retry
|
||||
self.consumer.negative_acknowledge(msg)
|
||||
del self.pending_acks[msg_id]
|
||||
|
||||
async def _deliver_to_queue(self, queue, value):
|
||||
"""Deliver message to queue with backpressure handling"""
|
||||
try:
|
||||
if self.backpressure_strategy == "block":
|
||||
# Block until space available (no timeout)
|
||||
await queue.put(value)
|
||||
return True
|
||||
|
||||
elif self.backpressure_strategy == "drop_oldest":
|
||||
# Drop oldest message if queue full
|
||||
if queue.full():
|
||||
try:
|
||||
queue.get_nowait()
|
||||
if self.metrics:
|
||||
self.metrics.dropped()
|
||||
except asyncio.QueueEmpty:
|
||||
pass
|
||||
await queue.put(value)
|
||||
return True
|
||||
|
||||
elif self.backpressure_strategy == "drop_new":
|
||||
# Drop new message if queue full
|
||||
if queue.full():
|
||||
if self.metrics:
|
||||
self.metrics.dropped()
|
||||
return False
|
||||
await queue.put(value)
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to deliver message: {e}")
|
||||
return False
|
||||
```
|
||||
|
||||
**Temel Tasarım Avantajları (Yayıncı modeline uygun):**
|
||||
**Tek İşlem Konumu**: Tüm mesaj işleme, `run()` metodu içinde gerçekleşir.
|
||||
<<<<<<< HEAD
|
||||
**Temiz Durum Makinesi**: Üç açık durum - çalışıyor, boşaltma, durdurulmuş.
|
||||
**Boşaltma Sırasında Duraklama**: Mevcut kuyrukları boşaltırken, Pulsar'dan yeni mesaj kabul etmeyi durdurur.
|
||||
**Zaman Aşımı Koruması**: Boşaltma sırasında sonsuza kadar takılmayacaktır.
|
||||
**Doğru Temizleme**: Kapatma sırasında teslim edilmemiş mesajlar varsa, bunlara ilişkin olumsuz onaylar gönderilir.
|
||||
=======
|
||||
**Temiz Durum Makinesi**: Üç açık durum - çalışıyor, boşaltılıyor, durdurulmuş.
|
||||
**Boşaltma Sırasında Duraklama**: Mevcut kuyrukları boşaltırken, Pulsar'dan yeni mesaj kabul etmeyi durdurur.
|
||||
**Zaman Aşımı Koruması**: Boşaltma sırasında sonsuza kadar takılmayacaktır.
|
||||
**Doğru Temizleme**: Kapatma sırasında teslim edilmemiş herhangi bir mesaj için olumsuz onay gönderir.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
#### B. Dışa Aktarma İşleyici İyileştirmeleri
|
||||
|
||||
**Dosya**: `trustgraph-flow/trustgraph/gateway/dispatch/triples_export.py`
|
||||
|
||||
```python
|
||||
class TriplesExport:
|
||||
async def destroy(self):
|
||||
"""Enhanced destroy with graceful shutdown"""
|
||||
# Step 1: Signal stop to prevent new messages
|
||||
self.running.stop()
|
||||
|
||||
# Step 2: Wait briefly for in-flight messages
|
||||
await asyncio.sleep(0.5)
|
||||
|
||||
# Step 3: Unsubscribe and stop subscriber (triggers queue drain)
|
||||
if hasattr(self, 'subs'):
|
||||
await self.subs.unsubscribe_all(self.id)
|
||||
await self.subs.stop()
|
||||
|
||||
# Step 4: Close websocket last
|
||||
if self.ws and not self.ws.closed:
|
||||
await self.ws.close()
|
||||
|
||||
async def run(self):
|
||||
"""Enhanced run with better error handling"""
|
||||
self.subs = Subscriber(
|
||||
client = self.pulsar_client,
|
||||
topic = self.queue,
|
||||
consumer_name = self.consumer,
|
||||
subscription = self.subscriber,
|
||||
schema = Triples,
|
||||
backpressure_strategy = "block" # Configurable
|
||||
)
|
||||
|
||||
await self.subs.start()
|
||||
|
||||
self.id = str(uuid.uuid4())
|
||||
q = await self.subs.subscribe_all(self.id)
|
||||
|
||||
consecutive_errors = 0
|
||||
max_consecutive_errors = 5
|
||||
|
||||
while self.running.get():
|
||||
try:
|
||||
resp = await asyncio.wait_for(q.get(), timeout=0.5)
|
||||
await self.ws.send_json(serialize_triples(resp))
|
||||
consecutive_errors = 0 # Reset on success
|
||||
|
||||
except asyncio.TimeoutError:
|
||||
continue
|
||||
|
||||
except queue.Empty:
|
||||
continue
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Exception sending to websocket: {str(e)}")
|
||||
consecutive_errors += 1
|
||||
|
||||
if consecutive_errors >= max_consecutive_errors:
|
||||
logger.error("Too many consecutive errors, shutting down")
|
||||
break
|
||||
|
||||
# Brief pause before retry
|
||||
await asyncio.sleep(0.1)
|
||||
|
||||
# Graceful cleanup handled in destroy()
|
||||
```
|
||||
|
||||
### 3. Soket Seviyesindeki İyileştirmeler
|
||||
|
||||
**Dosya**: `trustgraph-flow/trustgraph/gateway/endpoint/socket.py`
|
||||
|
||||
```python
|
||||
class SocketEndpoint:
|
||||
async def listener(self, ws, dispatcher, running):
|
||||
"""Enhanced listener with graceful shutdown"""
|
||||
async for msg in ws:
|
||||
if msg.type == WSMsgType.TEXT:
|
||||
await dispatcher.receive(msg)
|
||||
continue
|
||||
elif msg.type == WSMsgType.BINARY:
|
||||
await dispatcher.receive(msg)
|
||||
continue
|
||||
else:
|
||||
# Graceful shutdown on close
|
||||
logger.info("Websocket closing, initiating graceful shutdown")
|
||||
running.stop()
|
||||
|
||||
# Allow time for dispatcher cleanup
|
||||
await asyncio.sleep(1.0)
|
||||
break
|
||||
|
||||
async def handle(self, request):
|
||||
"""Enhanced handler with better cleanup"""
|
||||
# ... existing setup code ...
|
||||
|
||||
try:
|
||||
async with asyncio.TaskGroup() as tg:
|
||||
running = Running()
|
||||
|
||||
dispatcher = await self.dispatcher(
|
||||
ws, running, request.match_info
|
||||
)
|
||||
|
||||
worker_task = tg.create_task(
|
||||
self.worker(ws, dispatcher, running)
|
||||
)
|
||||
|
||||
lsnr_task = tg.create_task(
|
||||
self.listener(ws, dispatcher, running)
|
||||
)
|
||||
|
||||
except ExceptionGroup as e:
|
||||
logger.error("Exception group occurred:", exc_info=True)
|
||||
|
||||
# Attempt graceful dispatcher shutdown
|
||||
try:
|
||||
await asyncio.wait_for(
|
||||
dispatcher.destroy(),
|
||||
timeout=5.0
|
||||
)
|
||||
except asyncio.TimeoutError:
|
||||
logger.warning("Dispatcher shutdown timed out")
|
||||
except Exception as de:
|
||||
logger.error(f"Error during dispatcher cleanup: {de}")
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Socket exception: {e}", exc_info=True)
|
||||
|
||||
finally:
|
||||
# Ensure dispatcher cleanup
|
||||
if dispatcher and hasattr(dispatcher, 'destroy'):
|
||||
try:
|
||||
await dispatcher.destroy()
|
||||
except:
|
||||
pass
|
||||
|
||||
# Ensure websocket is closed
|
||||
if ws and not ws.closed:
|
||||
await ws.close()
|
||||
|
||||
return ws
|
||||
```
|
||||
|
||||
## Yapılandırma Seçenekleri
|
||||
|
||||
Davranışı ayarlamak için yapılandırma desteği ekleyin:
|
||||
|
||||
```python
|
||||
# config.py
|
||||
class GracefulShutdownConfig:
|
||||
# Publisher settings
|
||||
PUBLISHER_DRAIN_TIMEOUT = 5.0 # Seconds to wait for queue drain
|
||||
PUBLISHER_FLUSH_TIMEOUT = 2.0 # Producer flush timeout
|
||||
|
||||
# Subscriber settings
|
||||
SUBSCRIBER_DRAIN_TIMEOUT = 5.0 # Seconds to wait for queue drain
|
||||
BACKPRESSURE_STRATEGY = "block" # Options: "block", "drop_oldest", "drop_new"
|
||||
SUBSCRIBER_MAX_QUEUE_SIZE = 100 # Maximum queue size before backpressure
|
||||
|
||||
# Socket settings
|
||||
SHUTDOWN_GRACE_PERIOD = 1.0 # Seconds to wait for graceful shutdown
|
||||
MAX_CONSECUTIVE_ERRORS = 5 # Maximum errors before forced shutdown
|
||||
|
||||
# Monitoring
|
||||
LOG_QUEUE_STATS = True # Log queue statistics on shutdown
|
||||
METRICS_ENABLED = True # Enable metrics collection
|
||||
```
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
### Birim Testleri
|
||||
|
||||
```python
|
||||
async def test_publisher_queue_drain():
|
||||
"""Verify Publisher drains queue on shutdown"""
|
||||
publisher = Publisher(...)
|
||||
|
||||
# Fill queue with messages
|
||||
for i in range(10):
|
||||
await publisher.send(f"id-{i}", {"data": i})
|
||||
|
||||
# Stop publisher
|
||||
await publisher.stop()
|
||||
|
||||
# Verify all messages were sent
|
||||
assert publisher.q.empty()
|
||||
assert mock_producer.send.call_count == 10
|
||||
|
||||
async def test_subscriber_deferred_ack():
|
||||
"""Verify Subscriber only acks on successful delivery"""
|
||||
subscriber = Subscriber(..., backpressure_strategy="drop_new")
|
||||
|
||||
# Fill queue to capacity
|
||||
queue = await subscriber.subscribe("test")
|
||||
for i in range(100):
|
||||
await queue.put({"data": i})
|
||||
|
||||
# Try to add message when full
|
||||
msg = create_mock_message()
|
||||
await subscriber._process_message(msg)
|
||||
|
||||
# Verify negative acknowledgment
|
||||
assert msg.negative_acknowledge.called
|
||||
assert not msg.acknowledge.called
|
||||
```
|
||||
|
||||
### Entegrasyon Testleri
|
||||
|
||||
```python
|
||||
async def test_import_graceful_shutdown():
|
||||
"""Test import path handles shutdown gracefully"""
|
||||
# Setup
|
||||
import_handler = TriplesImport(...)
|
||||
await import_handler.start()
|
||||
|
||||
# Send messages
|
||||
messages = []
|
||||
for i in range(100):
|
||||
msg = {"metadata": {...}, "triples": [...]}
|
||||
await import_handler.receive(msg)
|
||||
messages.append(msg)
|
||||
|
||||
# Shutdown while messages in flight
|
||||
await import_handler.destroy()
|
||||
|
||||
# Verify all messages reached Pulsar
|
||||
received = await pulsar_consumer.receive_all()
|
||||
assert len(received) == 100
|
||||
|
||||
async def test_export_no_message_loss():
|
||||
"""Test export path doesn't lose acknowledged messages"""
|
||||
# Setup Pulsar with test messages
|
||||
for i in range(100):
|
||||
await pulsar_producer.send({"data": i})
|
||||
|
||||
# Start export handler
|
||||
export_handler = TriplesExport(...)
|
||||
export_task = asyncio.create_task(export_handler.run())
|
||||
|
||||
# Receive some messages
|
||||
received = []
|
||||
for _ in range(50):
|
||||
msg = await websocket.receive()
|
||||
received.append(msg)
|
||||
|
||||
# Force shutdown
|
||||
await export_handler.destroy()
|
||||
|
||||
# Continue receiving until websocket closes
|
||||
while not websocket.closed:
|
||||
try:
|
||||
msg = await websocket.receive()
|
||||
received.append(msg)
|
||||
except:
|
||||
break
|
||||
|
||||
# Verify no acknowledged messages were lost
|
||||
assert len(received) >= 50
|
||||
```
|
||||
|
||||
## Dağıtım Planı
|
||||
|
||||
### Aşama 1: Kritik Düzeltmeler (1. Hafta)
|
||||
Abonelik onayı zamanlaması düzeltildi (mesaj kaybını önler)
|
||||
Yayıncı kuyruğu boşaltma özelliği eklendi
|
||||
Staging ortamına dağıtıldı
|
||||
|
||||
### Aşama 2: Düzenli Kapanış (2. Hafta)
|
||||
Kapanış koordinasyonu uygulandı
|
||||
Geri basınç stratejileri eklendi
|
||||
Performans testi
|
||||
|
||||
### Aşama 3: İzleme ve Ayarlama (3. Hafta)
|
||||
Kuyruk derinlikleri için metrikler eklendi
|
||||
Mesaj kayıpları için uyarılar eklendi
|
||||
Üretim verilerine göre zaman aşımı değerleri ayarlandı
|
||||
|
||||
## İzleme ve Uyarılar
|
||||
|
||||
### İzlenecek Metrikler
|
||||
`publisher.queue.depth` - Mevcut yayıncı kuyruğu boyutu
|
||||
`publisher.messages.dropped` - Kapanma sırasında kaybolan mesajlar
|
||||
`subscriber.messages.negatively_acknowledged` - Başarısız teslimatlar
|
||||
`websocket.graceful_shutdowns` - Başarılı düzenli kapanışlar
|
||||
`websocket.forced_shutdowns` - Zorlanmış/zaman aşımı kapanışları
|
||||
|
||||
### Uyarılar
|
||||
<<<<<<< HEAD
|
||||
Yayıncı kuyruğu derinliği %80 kapasitenin üzerinde
|
||||
Kapanma sırasında herhangi bir mesaj kaybı
|
||||
Abonelik olumsuz onay oranı > %1
|
||||
Kapanış zaman aşımı aşıldı
|
||||
=======
|
||||
Yayıncı kuyruğu derinliği %80 kapasiteyi aştığında
|
||||
Kapanma sırasında herhangi bir mesaj kaybı olduğunda
|
||||
Abonelik olumsuz onay oranı > %1 olduğunda
|
||||
Kapanış zaman aşımı aşıldığında
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Geriye Dönük Uyumluluk
|
||||
|
||||
Tüm değişiklikler geriye dönük uyumluluğu korur:
|
||||
<<<<<<< HEAD
|
||||
Yapılandırma olmadan varsayılan davranış değişmedi
|
||||
Mevcut dağıtımlar çalışmaya devam ediyor
|
||||
Yeni özellikler kullanılamıyorsa, kademeli bozulma
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
Herhangi bir yeni saldırı vektörü tanıtılmadı
|
||||
=======
|
||||
Yapılandırma olmadan varsayılan davranış değişmez
|
||||
Mevcut dağıtımlar çalışmaya devam eder
|
||||
Yeni özellikler kullanılamadığında, düzgün bir şekilde performans düşüşü olur
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
Herhangi bir yeni saldırı vektörü tanıtılmamıştır
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
Geri basınç, bellek tükenmesi saldırılarını önler
|
||||
Yapılandırılabilir sınırlar, kaynak kötüye kullanımını önler
|
||||
|
||||
## Performans Etkisi
|
||||
|
||||
Normal çalışma sırasında minimum ek yük
|
||||
Kapanma, 5 saniyeye kadar daha uzun sürebilir (yapılandırılabilir)
|
||||
Bellek kullanımı, kuyruk boyutu sınırları ile sınırlıdır
|
||||
CPU etkisi ihmal edilebilir (<%1 artış)
|
||||
556
docs/tech-specs/tr/jsonl-prompt-output.tr.md
Normal file
556
docs/tech-specs/tr/jsonl-prompt-output.tr.md
Normal file
|
|
@ -0,0 +1,556 @@
|
|||
---
|
||||
layout: default
|
||||
title: "JSONL İstek Çıktısı Teknik Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# JSONL İstek Çıktısı 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'ta istek yanıtları için JSONL (JSON Lines) çıktı biçiminin uygulanmasını tanımlar. JSONL, LLM yanıtlarından yapılandırılmış verilerin, LLM yanıtları çıktı belirteç sınırlarına ulaştığında JSON dizisi çıktıları bozulduğunda ortaya çıkan kritik sorunları ele alarak, kesme hatalarına karşı dayanıklı bir şekilde çıkarılmasını sağlar.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Bu uygulama, aşağıdaki kullanım senaryolarını destekler:
|
||||
|
||||
1. **Kesintiye Dayanıklı Çıkarma**: LLM çıktısı yanıtın ortasında kesildiğinde bile geçerli kısmi sonuçları çıkarın.
|
||||
|
||||
2. **Büyük Ölçekli Çıkarma**: Token limitleri nedeniyle tam bir başarısızlık riski olmadan birçok öğenin çıkarılmasını işleyin.
|
||||
|
||||
3. **Karma Tip Çıkarma**: Tek bir istemde birden fazla varlık türünün (tanımlar, ilişkiler, varlıklar, özellikler) çıkarılmasını destekleyin.
|
||||
|
||||
4. **Akışla Uyumlu Çıktı**: Çıkarma sonuçlarının gelecekteki akış/artımlı
|
||||
işlenmesini sağlayın.
|
||||
|
||||
## Hedefler
|
||||
|
||||
<<<<<<< HEAD
|
||||
**Geriye Dönük Uyumluluk**: `response-type: "text"` kullanan mevcut istemler ve
|
||||
`response-type: "json"`, herhangi bir değişiklik yapılmadan çalışmaya devam eder.
|
||||
**Kesinti Dayanıklılığı**: Kısmi LLM çıktıları, tam bir başarısızlık yerine kısmi, geçerli sonuçlar üretir.
|
||||
|
||||
**Şema Doğrulama**: Bireysel nesneler için JSON şema doğrulamasını destekler.
|
||||
**Ayırıcı Birleşimler**: `type` alanını kullanarak karma türlü çıktıları destekler.
|
||||
|
||||
**Minimum API Değişiklikleri**: Mevcut istem yapılandırmasını, yeni
|
||||
yanıt türü ve şema anahtarıyla genişletir.
|
||||
=======
|
||||
**Geriye Dönük Uyumluluk**: `response-type: "text"` ve
|
||||
`response-type: "json"` kullanan mevcut istemler, herhangi bir değişiklik yapılmadan çalışmaya devam eder.
|
||||
**Kesme Direnci**: Kısmi LLM çıktıları, tam bir başarısızlık yerine, kısmi geçerli sonuçlar üretir.
|
||||
|
||||
**Şema Doğrulama**: Bireysel nesneler için JSON Şema doğrulamasını destekleyin.
|
||||
**Ayırıcı Birleşimler**: `type` alanı kullanılarak farklı türlerde çıktıları destekleyin.
|
||||
ayırıcı.
|
||||
**Minimum API Değişiklikleri**: Mevcut istem yapılandırmasını yeni
|
||||
yanıt türü ve şema anahtarıyla genişletin.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
## Arka Plan
|
||||
|
||||
### Mevcut Mimari
|
||||
|
||||
İstek hizmeti, iki tür yanıtı destekler:
|
||||
|
||||
1. `response-type: "text"` - Ham metin yanıtı, olduğu gibi döndürülür.
|
||||
2. `response-type: "json"` - Yanıttan ayrıştırılan JSON, isteğe bağlı `response-type: "json"`'a göre doğrulanır.
|
||||
isteğe bağlı `schema`
|
||||
|
||||
<<<<<<< HEAD
|
||||
`trustgraph-flow/trustgraph/template/prompt_manager.py`'daki mevcut uygulama:
|
||||
=======
|
||||
Mevcut uygulama `trustgraph-flow/trustgraph/template/prompt_manager.py` içinde:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
```python
|
||||
class Prompt:
|
||||
def __init__(self, template, response_type = "text", terms=None, schema=None):
|
||||
self.template = template
|
||||
self.response_type = response_type
|
||||
self.terms = terms
|
||||
self.schema = schema
|
||||
```
|
||||
|
||||
### Mevcut Sınırlamalar
|
||||
|
||||
Çıkarma komutları, çıktıyı JSON dizileri (`[{...}, {...}, ...]`) olarak istediğinde:
|
||||
|
||||
<<<<<<< HEAD
|
||||
**Kesme nedeniyle oluşan bozulma**: Eğer LLM, dizi ortasında çıktı belirteç sınırlarına ulaştığında,
|
||||
tüm yanıt geçersiz bir JSON haline gelir ve işlenemez.
|
||||
**Tümünü veya hiçbirini işleme**: İşlemeye başlamadan önce tam çıktıyı almanız gerekir.
|
||||
**Kısmi sonuçlar yok**: Kesilmiş bir yanıt, kullanılabilir veri olarak sıfır veri verir.
|
||||
**Büyük çıkarmalar için güvenilir değil**: Çıkarılan öğe sayısı arttıkça, başarısızlık riski daha yüksektir.
|
||||
=======
|
||||
**Kesme bozulması**: Eğer LLM, dizi ortasında çıktı belirteç sınırlarına ulaştığında,
|
||||
tüm yanıt geçersiz bir JSON haline gelir ve işlenemez.
|
||||
**Tüm veya hiçbir işleme**: İşlemeye başlamadan önce tam çıktının alınması gerekir.
|
||||
**Kısmi sonuçlar yok**: Kesilmiş bir yanıt, kullanılabilir veri olarak sıfır veri verir.
|
||||
**Büyük çıkarmalar için güvenilir değil**: Çıkarılan öğe sayısı arttıkça, başarısızlık riski artar.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
Bu özellik, her çıkarılan öğenin kendi satırında bulunan tam bir JSON nesnesi olduğu JSONL formatını kullanarak, bu sınırlamaları ele alır.
|
||||
|
||||
|
||||
|
||||
## Teknik Tasarım
|
||||
|
||||
### Yanıt Tipi Genişletmesi
|
||||
|
||||
Mevcut `"text"` ve `"json"` türlerinin yanı sıra yeni bir yanıt türü `"jsonl"` ekleyin.
|
||||
|
||||
<<<<<<< HEAD
|
||||
|
||||
#### Yapılandırma Değişiklikleri
|
||||
|
||||
=======
|
||||
#### Yapılandırma Değişiklikleri
|
||||
|
||||
**Yeni yanıt türü değeri:**
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
```
|
||||
"response-type": "jsonl"
|
||||
```
|
||||
|
||||
**Şema yorumlaması:**
|
||||
|
||||
Mevcut `"schema"` anahtarı, hem `"json"` hem de `"jsonl"` yanıtları için kullanılmaktadır.
|
||||
Yorumlama, yanıt türüne bağlıdır:
|
||||
|
||||
`"json"`: Şema, tüm yanıtı (genellikle bir dizi veya nesne) tanımlar.
|
||||
`"jsonl"`: Şema, her bir satırı/nesneyi ayrı ayrı tanımlar.
|
||||
|
||||
```json
|
||||
{
|
||||
"response-type": "jsonl",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"entity": { "type": "string" },
|
||||
"definition": { "type": "string" }
|
||||
},
|
||||
"required": ["entity", "definition"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Bu, istem yapılandırma araçlarına ve düzenleyicilere yapılan değişiklikleri önler.
|
||||
|
||||
### JSONL Biçim Özellikleri
|
||||
|
||||
#### Basit Çıkarma
|
||||
|
||||
Tek bir nesne türünü (tanımlar, ilişkiler,
|
||||
konular, satırlar) çıkaran istemler için, çıktı her satırda bir JSON nesnesidir ve herhangi bir sarma bulunmaz:
|
||||
|
||||
**İstem çıktı biçimi:**
|
||||
```
|
||||
{"entity": "photosynthesis", "definition": "Process by which plants convert sunlight"}
|
||||
{"entity": "chlorophyll", "definition": "Green pigment in plants"}
|
||||
{"entity": "mitochondria", "definition": "Powerhouse of the cell"}
|
||||
```
|
||||
|
||||
**Önceki JSON dizi formatıyla karşılaştırma:**
|
||||
```json
|
||||
[
|
||||
{"entity": "photosynthesis", "definition": "Process by which plants convert sunlight"},
|
||||
{"entity": "chlorophyll", "definition": "Green pigment in plants"},
|
||||
{"entity": "mitochondria", "definition": "Powerhouse of the cell"}
|
||||
]
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
Eğer LLM, 2. satırdan sonra kesilirse, JSON dizisi formatı geçersiz bir JSON oluşturur,
|
||||
ancak JSONL iki geçerli nesne üretir.
|
||||
|
||||
#### Karışık Tip Çıkarımı (Ayırıcı Birleşimler)
|
||||
|
||||
Birden fazla nesne türünü çıkaran (örneğin, hem tanımları hem de
|
||||
ilişkileri, veya varlıklar, ilişkiler ve özellikler) istemler için, bir `"type"`
|
||||
=======
|
||||
Eğer LLM, 2. satırdan sonra kesilirse, JSON dizisi formatı geçersiz bir JSON oluştururken,
|
||||
JSONL ise iki geçerli nesne üretir.
|
||||
|
||||
#### Karışık Tip Çıkarımı (Ayırıcı Birleşimler)
|
||||
|
||||
Birden fazla nesne türünü çıkaran (örneğin, hem tanımları ve
|
||||
ilişkiler veya varlıklar, ilişkiler ve özellikler) istemler için, bir `"type"`
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
alanını ayırıcı olarak kullanın:
|
||||
|
||||
**İstem çıktısı formatı:**
|
||||
```
|
||||
{"type": "definition", "entity": "DNA", "definition": "Molecule carrying genetic instructions"}
|
||||
{"type": "relationship", "subject": "DNA", "predicate": "located_in", "object": "cell nucleus", "object-entity": true}
|
||||
{"type": "definition", "entity": "RNA", "definition": "Molecule that carries genetic information"}
|
||||
{"type": "relationship", "subject": "RNA", "predicate": "transcribed_from", "object": "DNA", "object-entity": true}
|
||||
```
|
||||
|
||||
**Ayırıcı birleşimler için şema, `oneOf` kullanır:**
|
||||
```json
|
||||
{
|
||||
"response-type": "jsonl",
|
||||
"schema": {
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"type": { "const": "definition" },
|
||||
"entity": { "type": "string" },
|
||||
"definition": { "type": "string" }
|
||||
},
|
||||
"required": ["type", "entity", "definition"]
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"type": { "const": "relationship" },
|
||||
"subject": { "type": "string" },
|
||||
"predicate": { "type": "string" },
|
||||
"object": { "type": "string" },
|
||||
"object-entity": { "type": "boolean" }
|
||||
},
|
||||
"required": ["type", "subject", "predicate", "object", "object-entity"]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Ontoloji Çıkarımı
|
||||
|
||||
Varlıklar, ilişkiler ve özelliklerle ontoloji tabanlı çıkarım için:
|
||||
|
||||
**İstenen çıktı formatı:**
|
||||
```
|
||||
{"type": "entity", "entity": "Cornish pasty", "entity_type": "fo/Recipe"}
|
||||
{"type": "entity", "entity": "beef", "entity_type": "fo/Food"}
|
||||
{"type": "relationship", "subject": "Cornish pasty", "subject_type": "fo/Recipe", "relation": "fo/has_ingredient", "object": "beef", "object_type": "fo/Food"}
|
||||
{"type": "attribute", "entity": "Cornish pasty", "entity_type": "fo/Recipe", "attribute": "fo/serves", "value": "4 people"}
|
||||
```
|
||||
|
||||
### Uygulama Detayları
|
||||
|
||||
#### İstek Sınıfı
|
||||
|
||||
Mevcut `Prompt` sınıfı herhangi bir değişiklik gerektirmiyor. `schema` alanı yeniden kullanılıyor.
|
||||
JSONL formatı için, yorumlanması `response_type` ile belirlenir:
|
||||
|
||||
```python
|
||||
class Prompt:
|
||||
def __init__(self, template, response_type="text", terms=None, schema=None):
|
||||
self.template = template
|
||||
self.response_type = response_type
|
||||
self.terms = terms
|
||||
self.schema = schema # Interpretation depends on response_type
|
||||
```
|
||||
|
||||
#### PromptManager.load_config
|
||||
|
||||
Herhangi bir değişiklik gerekli değil - mevcut yapılandırma yüklemesi zaten
|
||||
`schema` anahtarını işlemektedir.
|
||||
|
||||
#### JSONL Ayrıştırma
|
||||
|
||||
JSONL yanıtları için yeni bir ayrıştırma yöntemi ekleyin:
|
||||
|
||||
```python
|
||||
def parse_jsonl(self, text):
|
||||
"""
|
||||
Parse JSONL response, returning list of valid objects.
|
||||
|
||||
Invalid lines (malformed JSON, empty lines) are skipped with warnings.
|
||||
This provides truncation resilience - partial output yields partial results.
|
||||
"""
|
||||
results = []
|
||||
|
||||
for line_num, line in enumerate(text.strip().split('\n'), 1):
|
||||
line = line.strip()
|
||||
|
||||
# Skip empty lines
|
||||
if not line:
|
||||
continue
|
||||
|
||||
# Skip markdown code fence markers if present
|
||||
if line.startswith('```'):
|
||||
continue
|
||||
|
||||
try:
|
||||
obj = json.loads(line)
|
||||
results.append(obj)
|
||||
except json.JSONDecodeError as e:
|
||||
# Log warning but continue - this provides truncation resilience
|
||||
logger.warning(f"JSONL parse error on line {line_num}: {e}")
|
||||
|
||||
return results
|
||||
```
|
||||
|
||||
#### PromptManager.invoke Değişiklikleri
|
||||
|
||||
Yeni yanıt türünü işleyebilmek için invoke yöntemini genişletin:
|
||||
|
||||
```python
|
||||
async def invoke(self, id, input, llm):
|
||||
logger.debug("Invoking prompt template...")
|
||||
|
||||
terms = self.terms | self.prompts[id].terms | input
|
||||
resp_type = self.prompts[id].response_type
|
||||
|
||||
prompt = {
|
||||
"system": self.system_template.render(terms),
|
||||
"prompt": self.render(id, input)
|
||||
}
|
||||
|
||||
resp = await llm(**prompt)
|
||||
|
||||
if resp_type == "text":
|
||||
return resp
|
||||
|
||||
if resp_type == "json":
|
||||
try:
|
||||
obj = self.parse_json(resp)
|
||||
except:
|
||||
logger.error(f"JSON parse failed: {resp}")
|
||||
raise RuntimeError("JSON parse fail")
|
||||
|
||||
if self.prompts[id].schema:
|
||||
try:
|
||||
validate(instance=obj, schema=self.prompts[id].schema)
|
||||
logger.debug("Schema validation successful")
|
||||
except Exception as e:
|
||||
raise RuntimeError(f"Schema validation fail: {e}")
|
||||
|
||||
return obj
|
||||
|
||||
if resp_type == "jsonl":
|
||||
objects = self.parse_jsonl(resp)
|
||||
|
||||
if not objects:
|
||||
logger.warning("JSONL parse returned no valid objects")
|
||||
return []
|
||||
|
||||
# Validate each object against schema if provided
|
||||
if self.prompts[id].schema:
|
||||
validated = []
|
||||
for i, obj in enumerate(objects):
|
||||
try:
|
||||
validate(instance=obj, schema=self.prompts[id].schema)
|
||||
validated.append(obj)
|
||||
except Exception as e:
|
||||
logger.warning(f"Object {i} failed schema validation: {e}")
|
||||
return validated
|
||||
|
||||
return objects
|
||||
|
||||
raise RuntimeError(f"Response type {resp_type} not known")
|
||||
```
|
||||
|
||||
### Etkilenen İstekler
|
||||
|
||||
Aşağıdaki istekler JSONL formatına aktarılmalıdır:
|
||||
|
||||
| İstek Kimliği | Açıklama | Tür Alanı |
|
||||
|-----------|-------------|------------|
|
||||
| `extract-definitions` | Varlık/tanım çıkarma | Hayır (tek tür) |
|
||||
| `extract-relationships` | İlişki çıkarma | Hayır (tek tür) |
|
||||
| `extract-topics` | Konu/tanım çıkarma | Hayır (tek tür) |
|
||||
| `extract-rows` | Yapılandırılmış satır çıkarma | Hayır (tek tür) |
|
||||
| `agent-kg-extract` | Birleştirilmiş tanım + ilişki çıkarma | Evet: `"definition"`, `"relationship"` |
|
||||
| `extract-with-ontologies` / `ontology-extract` | Ontoloji tabanlı çıkarma | Evet: `"entity"`, `"relationship"`, `"attribute"` |
|
||||
|
||||
### API Değişiklikleri
|
||||
|
||||
#### Müşteri Perspektifi
|
||||
|
||||
<<<<<<< HEAD
|
||||
JSONL ayrıştırması, istem hizmeti API'sini kullananlar için şeffaftır. Ayrıştırma, istem hizmetinde sunucu tarafında gerçekleşir ve yanıt standart
|
||||
bir şekilde döndürülür.
|
||||
`PromptResponse.object` alanını seri hale edilmiş bir JSON dizisi olarak.
|
||||
|
||||
Müşteriler, istem hizmetini (`PromptClient.prompt()` veya benzeri bir yöntemle) kullandığında:
|
||||
|
||||
**`response-type: "json"`** (dizi şeması ile) → müşteri, Python `list` alır.
|
||||
**`response-type: "jsonl"`** → müşteri, Python `list` alır.
|
||||
|
||||
Müşterinin bakış açısıyla, her iki yöntem de aynı veri yapılarını döndürür.
|
||||
Fark, tamamen LLM çıktısının sunucu tarafında nasıl işlendiğindedir:
|
||||
|
||||
JSON dizisi formatı: Tek `json.loads()` çağrısı; kısaltılırsa tamamen başarısız olur.
|
||||
JSONL formatı: Satır satır ayrıştırma; kısaltılırsa kısmi sonuçlar verir.
|
||||
|
||||
Bu, çıkarma istemlerinden bir liste bekleyen mevcut istemci kodunun, istemleri JSON'dan JSONL formatına geçirirken herhangi bir değişikliğe ihtiyaç duymamasını sağlar.
|
||||
|
||||
|
||||
#### Sunucu Dönüş Değeri
|
||||
|
||||
`response-type: "jsonl"` için, `PromptManager.invoke()` metodu,
|
||||
başarıyla ayrıştırılmış ve doğrulanmış tüm nesneleri içeren bir `list[dict]` döndürür. Bu
|
||||
liste, daha sonra `PromptResponse.object` alanı için JSON'a dönüştürülür.
|
||||
|
||||
#### Hata Yönetimi
|
||||
|
||||
Boş sonuçlar: Uyarı günlüğü ile boş bir liste `[]` döndürür.
|
||||
Kısmi ayrıştırma hatası: Başarıyla ayrıştırılmış nesnelerin bir listesini ve
|
||||
hatalar için uyarı günlüklerini döndürür.
|
||||
Tam ayrıştırma hatası: Uyarı günlükleriyle boş bir liste `[]` döndürür.
|
||||
|
||||
Bu, `response-type: "json"`'den farklıdır, çünkü `RuntimeError` ayrıştırma hatası durumunda `RuntimeError` hatası oluşturur.
|
||||
JSONL için daha hoşgörülü davranış, kesintilere karşı dayanıklılık sağlamak amacıyla kasıtlıdır.
|
||||
=======
|
||||
JSONL ayrıştırması, istek hizmeti API kullanıcıları için şeffaftır. Ayrıştırma, isteğin
|
||||
sunucu tarafında gerçekleşir ve yanıt, standart
|
||||
`PromptResponse.object` alanı aracılığıyla seri hale getirilmiş bir JSON dizisi olarak döndürülür.
|
||||
|
||||
Müşteriler, istek hizmetini (`PromptClient.prompt()` veya benzeri aracılığıyla) çağırdığında:
|
||||
|
||||
**`response-type: "json"`** dizi şeması ile → müşteri, Python `list` alır
|
||||
**`response-type: "jsonl"`** → müşteri, Python `list` alır
|
||||
|
||||
Müşteri açısından, her iki yöntem de aynı veri yapılarını döndürür. Fark, yalnızca LLM çıktısının
|
||||
sunucu tarafında nasıl ayrıştırıldığıdır:
|
||||
|
||||
JSON dizisi formatı: Tek `json.loads()` çağrısı; kesintiye uğratılırsa tamamen başarısız olur
|
||||
JSONL formatı: Satır satır ayrıştırma; kesintiye uğratılırsa kısmi sonuçlar verir
|
||||
|
||||
Bu, çıkarma isteklerinden gelen listeleri bekleyen mevcut müşteri kodunun,
|
||||
istekleri JSON'dan JSONL formatına geçirirken herhangi bir değişikliğe ihtiyaç duymamasını sağlar.
|
||||
|
||||
#### Sunucu Dönüş Değeri
|
||||
|
||||
`response-type: "jsonl"` için, `PromptManager.invoke()` yöntemi bir
|
||||
`list[dict]` döndürür ve bu, başarıyla ayrıştırılmış ve doğrulanmış tüm nesneleri içerir.
|
||||
Bu liste daha sonra `PromptResponse.object` alanı için JSON'a seri hale getirilir.
|
||||
|
||||
#### Hata Yönetimi
|
||||
|
||||
Boş sonuçlar: Uyarı günlüğü ile boş bir liste `[]` döndürülür
|
||||
Kısmi ayrıştırma hatası: Başarıyla ayrıştırılmış nesnelerin listesi, hatalar için
|
||||
uyarı günlükleriyle birlikte döndürülür
|
||||
Tam ayrıştırma hatası: Uyarı günlükleriyle boş bir liste `[]` döndürülür
|
||||
|
||||
Bu, ayrıştırma hatası durumunda `RuntimeError`'i yükselten `response-type: "json"`'dan farklıdır.
|
||||
JSONL için esnek davranış, kesintiye karşı dayanıklılık sağlamak için kasıtlıdır.
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
|
||||
### Yapılandırma Örneği
|
||||
|
||||
<<<<<<< HEAD
|
||||
Tam istem yapılandırma örneği:
|
||||
=======
|
||||
Tam istek yapılandırma örneği:
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": "Extract all entities and their definitions from the following text. Output one JSON object per line.\n\nText:\n{{text}}\n\nOutput format per line:\n{\"entity\": \"<name>\", \"definition\": \"<definition>\"}",
|
||||
"response-type": "jsonl",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"entity": {
|
||||
"type": "string",
|
||||
"description": "The entity name"
|
||||
},
|
||||
"definition": {
|
||||
"type": "string",
|
||||
"description": "A clear definition of the entity"
|
||||
}
|
||||
},
|
||||
"required": ["entity", "definition"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
**Girdi Doğrulama**: JSON ayrıştırması, standart `json.loads()`'ı kullanır ve bu, enjeksiyon saldırılarına karşı güvenlidir.
|
||||
**Şema Doğrulama**: Şema zorlaması için ⟦CODE_0⟧ kullanılır.
|
||||
**Şema Doğrulama**: Şema uyumluluğunu sağlamak için `jsonschema.validate()` kullanılır.
|
||||
**Yeni Bir Saldırı Yüzeyi Yok**: JSONL ayrıştırması, satır satır işlenmesi nedeniyle JSON dizisi ayrıştırmasından çok daha güvenlidir.
|
||||
|
||||
|
||||
## Performans Hususları
|
||||
|
||||
**Bellek**: Satır satır ayrıştırma, tam JSON dizilerini yüklemekten daha az bellek kullanır.
|
||||
<<<<<<< HEAD
|
||||
**Gecikme**: Ayrıştırma performansı, JSON dizisi ayrıştırmasıyla karşılaştırılabilir.
|
||||
**Doğrulama**: Şema doğrulaması, her bir nesne için yapılır, bu da ek yük getirir ancak
|
||||
doğrulama başarısız olduğunda kısmi sonuçlar elde etmeyi sağlar.
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
=======
|
||||
|
||||
**Gecikme**: Ayrıştırma performansı, JSON dizisi ayrıştırmasıyla karşılaştırılabilir.
|
||||
**Doğrulama**: Şema doğrulaması, her bir nesne için yapılır, bu da ek yük getirir ancak
|
||||
doğrulama başarısız olduğunda kısmi sonuçlar elde etmeyi sağlar.
|
||||
|
||||
## Test Stratejisi
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
|
||||
### Birim Testleri
|
||||
|
||||
Geçerli giriş ile JSONL ayrıştırma
|
||||
Boş satırlarla JSONL ayrıştırma
|
||||
Markdown kod bloklarıyla JSONL ayrıştırma
|
||||
Kesilmiş son satırla JSONL ayrıştırma
|
||||
Geçersiz JSON satırlarının arasına serpiştirilmiş JSONL ayrıştırma
|
||||
`oneOf` ayrımcı birleşimlerle şema doğrulaması
|
||||
Geriye dönük uyumluluk: Mevcut `"text"` ve `"json"` istemleri değişmeden kalır
|
||||
|
||||
### Entegrasyon Testleri
|
||||
|
||||
JSONL istemleriyle uçtan uca çıkarma
|
||||
Simüle edilmiş kesme ile çıkarma (yapay olarak sınırlı yanıt)
|
||||
Tür ayrımcısı ile karma tür çıkarma
|
||||
Üç türün tamamıyla ontoloji çıkarma
|
||||
|
||||
### Çıkarma Kalitesi Testleri
|
||||
|
||||
Çıkarma sonuçlarını karşılaştırın: JSONL ile JSON dizisi formatı
|
||||
Kesme dayanıklılığını doğrulayın: JSONL, JSON'un başarısız olduğu durumlarda kısmi sonuçlar verir
|
||||
|
||||
## Geçiş Planı
|
||||
|
||||
### 1. Aşama: Uygulama
|
||||
|
||||
1. `parse_jsonl()` yöntemini `PromptManager` içinde uygulayın
|
||||
2. `invoke()`'ı `response-type: "jsonl"`'i işleyebilecek şekilde genişletin
|
||||
3. Birim testleri ekleyin
|
||||
|
||||
### 2. Aşama: İstek Geçişi
|
||||
|
||||
1. `extract-definitions` isteğini ve yapılandırmasını güncelleyin
|
||||
2. `extract-relationships` isteğini ve yapılandırmasını güncelleyin
|
||||
3. `extract-topics` isteğini ve yapılandırmasını güncelleyin
|
||||
4. `extract-rows` isteğini ve yapılandırmasını güncelleyin
|
||||
5. `agent-kg-extract` isteğini ve yapılandırmasını güncelleyin
|
||||
6. `extract-with-ontologies` isteğini ve yapılandırmasını güncelleyin
|
||||
|
||||
### 3. Aşama: Aşağı Akış Güncellemeleri
|
||||
|
||||
1. Çıkarma sonuçlarını kullanan tüm kodu, liste dönüş türünü işleyebilecek şekilde güncelleyin
|
||||
<<<<<<< HEAD
|
||||
2. `type` alanına göre karma türdeki çıkarma sonuçlarını kategorize eden kodu güncelleyin
|
||||
=======
|
||||
2. `type` alanıyla karma türdeki çıkarma türlerini sınıflandıran kodu güncelleyin
|
||||
>>>>>>> 82edf2d (New md files from RunPod)
|
||||
3. Çıkarma çıktısı formatı hakkında doğrulama yapan testleri güncelleyin
|
||||
|
||||
## Açık Sorular
|
||||
|
||||
Şu anda yok.
|
||||
|
||||
## Referanslar
|
||||
|
||||
Mevcut uygulama: `trustgraph-flow/trustgraph/template/prompt_manager.py`
|
||||
JSON Lines belirtimi: https://jsonlines.org/
|
||||
JSON Şeması `oneOf`: https://json-schema.org/understanding-json-schema/reference/combining.html#oneof
|
||||
İlgili belirtim: Streaming LLM Responses (`docs/tech-specs/streaming-llm-responses.md`)
|
||||
992
docs/tech-specs/tr/large-document-loading.tr.md
Normal file
992
docs/tech-specs/tr/large-document-loading.tr.md
Normal file
|
|
@ -0,0 +1,992 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Büyük Belge Yükleme Teknik Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Büyük Belge Yükleme 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 teknik özellik, TrustGraph'e büyük belgelerin yüklenmesi sırasında ortaya çıkan ölçeklenebilirlik ve kullanıcı deneyimi sorunlarını ele almaktadır. Mevcut mimari, belge yüklemeyi tek bir atomik işlem olarak ele almaktadır, bu da boru hattının çeşitli noktalarında bellek yüklenmesine neden olmakta ve kullanıcılara herhangi bir geri bildirim veya kurtarma seçeneği sunmamaktadır.
|
||||
|
||||
Bu uygulama, aşağıdaki kullanım senaryolarına yöneliktir:
|
||||
|
||||
|
||||
1. **Büyük PDF İşleme**: Belleği tüketmeden yüzlerce megabayt boyutunda PDF dosyalarını yükleyin ve işleyin.
|
||||
|
||||
2. **Devam Eden Yüklemeler**: Kesintiye uğrayan yüklemelerin, baştan başlamak yerine, durdurulduğu yerden devam etmesini sağlayın.
|
||||
|
||||
3. **İlerleme Geri Bildirimi**: Kullanıcılara yükleme ve işleme sürecinin gerçek zamanlı görünürlüğünü sağlayın.
|
||||
|
||||
4. **Bellek Verimli İşleme**: Belgeleri, tüm dosyaları bellekte tutmadan, akış halinde işleyin.
|
||||
|
||||
|
||||
## Hedefler
|
||||
|
||||
|
||||
**Artımlı Yükleme**: REST ve WebSocket üzerinden parçalı belge yüklemeyi destekleyin.
|
||||
**Devam Eden Aktarımlar**: Kesintiye uğrayan yüklemelerden kurtarmayı sağlayın.
|
||||
**İlerleme Görünürlüğü**: İstemcilere yükleme/işleme sürecinin ilerleme durumunu geri bildirin.
|
||||
**Bellek Verimliliği**: Boru hattının tamamında tam belge tamponlamayı ortadan kaldırın.
|
||||
**Geriye Dönük Uyumluluk**: Mevcut, küçük belge iş akışlarının değişmeden devam etmesini sağlayın.
|
||||
**Akış İşleme**: PDF kod çözme ve metin parçalama işlemleri, akışlar üzerinde gerçekleştirilir.
|
||||
|
||||
## Arka Plan
|
||||
|
||||
|
||||
### Mevcut Mimari
|
||||
|
||||
Belge gönderme işlemi, aşağıdaki yolu izlemektedir:
|
||||
|
||||
1. **İstemci**, belgeyi REST (`POST /api/v1/librarian`) veya WebSocket üzerinden gönderir.
|
||||
2. **API Ağ Geçidi**, base64 ile kodlanmış belge içeriği içeren eksiksiz isteği alır.
|
||||
3. **LibrarianRequestor**, isteği Pulsar mesajına dönüştürür.
|
||||
4. **Librarian Hizmeti**, mesajı alır, belgeyi belleğe kodlar.
|
||||
5. **BlobStore**, belgeyi Garage/S3'e yükler.
|
||||
6. **Cassandra**, nesne referansı ile birlikte meta verileri depolar.
|
||||
7. İşleme için: belge S3'ten alınır, kodlanır, parçalara ayrılır - hepsi bellekte.
|
||||
|
||||
Önemli dosyalar:
|
||||
REST/WebSocket girişi: `trustgraph-flow/trustgraph/gateway/service.py`
|
||||
Librarian çekirdeği: `trustgraph-flow/trustgraph/librarian/librarian.py`
|
||||
Blob depolama: `trustgraph-flow/trustgraph/librarian/blob_store.py`
|
||||
Cassandra tabloları: `trustgraph-flow/trustgraph/tables/library.py`
|
||||
API şeması: `trustgraph-base/trustgraph/schema/services/library.py`
|
||||
|
||||
### Mevcut Sınırlamalar
|
||||
|
||||
Mevcut tasarımın, çeşitli birikimli bellek ve kullanıcı deneyimi sorunları bulunmaktadır:
|
||||
|
||||
1. **Atomik Yükleme İşlemi**: Tüm belge,
|
||||
tek bir istekte iletilmelidir. Büyük belgeler, bağlantı başarısız olursa geri alma mekanizması olmadan, ilerleme göstergesi olmayan uzun süreli istekler gerektirir.
|
||||
|
||||
|
||||
2. **API Tasarımı**: Hem REST hem de WebSocket API'leri,
|
||||
tüm belgeyi tek bir mesajda bekler. Şema (`LibrarianRequest`), tüm base64 ile kodlanmış belgeyi içeren tek bir `content`
|
||||
alanına sahiptir.
|
||||
|
||||
3. **Kütüphaneci Belleği**: Kütüphaneci hizmeti, belgeyi S3'e yüklemeden önce tüm belgeyi belleğe aktarır. 500MB'lık bir PDF için, bu, işlem belleğinde 500MB+'yi tutmak anlamına gelir.
|
||||
500MB+ işlem belleğinde tutmak anlamına gelir.
|
||||
|
||||
|
||||
4. **PDF Kod Çözücü Belleği**: İşleme başladığında, PDF kod çözücü, metni çıkarmak için tüm PDF'yi belleğe yükler. PyPDF ve benzeri kütüphaneler genellikle belgenin tamamına erişim gerektirir.
|
||||
|
||||
|
||||
|
||||
5. **Parçalayıcı Belleği**: Metin parçalayıcı, çıkarılan tamamlanmış metni alır ve parçalar oluştururken bunu bellekte tutar.
|
||||
|
||||
|
||||
**Bellek Kullanımı Örneği** (500MB PDF):
|
||||
Gateway: ~700MB (base64 kodlama ek yükü)
|
||||
Librarian: ~500MB (çözülmüş baytlar)
|
||||
PDF Çözücü: ~500MB + çıkarma arabellekleri
|
||||
Parçalayıcı: çıkarılan metin (değişken, potansiyel olarak 100MB+)
|
||||
|
||||
Tek bir büyük belge için toplam maksimum bellek kullanımı 2GB'ı aşabilir.
|
||||
|
||||
## Teknik Tasarım
|
||||
|
||||
### Tasarım İlkeleri
|
||||
|
||||
1. **API Arayüzü**: Tüm istemci etkileşimi, librarian API'si üzerinden gerçekleşir. İstemciler,
|
||||
temelindeki S3/Garage depolamaya doğrudan erişemez veya bu depolama hakkında bilgi sahibi değildir.
|
||||
|
||||
2. **S3 Çoklu Parça Yükleme**: Temelde standart S3 çoklu parça yükleme özelliğini kullanın.
|
||||
Bu, S3 uyumlu sistemlerde (AWS S3, MinIO, Garage,
|
||||
Ceph, DigitalOcean Spaces, Backblaze B2, vb.) yaygın olarak desteklenir ve taşınabilirliği sağlar.
|
||||
|
||||
3. **Atomik Tamamlama**: S3 çoklu parça yüklemeleri doğası gereği atomiktir; yüklenen
|
||||
parçalar, `CompleteMultipartUpload` çağrılana kadar görünmez. Geçici
|
||||
dosyalar veya yeniden adlandırma işlemleri gerekmez.
|
||||
|
||||
4. **Takip Edilebilir Durum**: Yükleme oturumları Cassandra'da takip edilir, bu da
|
||||
tamamlanmamış yüklemeler hakkında görünürlük sağlar ve devam ettirme özelliğini etkinleştirir.
|
||||
|
||||
### Parçalı Yükleme Akışı
|
||||
|
||||
```
|
||||
Client Librarian API S3/Garage
|
||||
│ │ │
|
||||
│── begin-upload ───────────►│ │
|
||||
│ (metadata, size) │── CreateMultipartUpload ────►│
|
||||
│ │◄── s3_upload_id ─────────────│
|
||||
│◄── upload_id ──────────────│ (store session in │
|
||||
│ │ Cassandra) │
|
||||
│ │ │
|
||||
│── upload-chunk ───────────►│ │
|
||||
│ (upload_id, index, data) │── UploadPart ───────────────►│
|
||||
│ │◄── etag ─────────────────────│
|
||||
│◄── ack + progress ─────────│ (store etag in session) │
|
||||
│ ⋮ │ ⋮ │
|
||||
│ (repeat for all chunks) │ │
|
||||
│ │ │
|
||||
│── complete-upload ────────►│ │
|
||||
│ (upload_id) │── CompleteMultipartUpload ──►│
|
||||
│ │ (parts coalesced by S3) │
|
||||
│ │── store doc metadata ───────►│ Cassandra
|
||||
│◄── document_id ────────────│ (delete session) │
|
||||
```
|
||||
|
||||
Müşteri, S3 ile doğrudan etkileşimde bulunmaz. Kütüphaneci, parçalı yükleme API'miz ile S3 çok parçalı işlemler arasında dahili olarak çeviri yapar.
|
||||
|
||||
### Kütüphaneci API İşlemleri
|
||||
### Kütüphaneci API İşlemleri
|
||||
|
||||
#### `begin-upload`
|
||||
|
||||
Parçalı bir yükleme oturumu başlatın.
|
||||
|
||||
İstek:
|
||||
```json
|
||||
{
|
||||
"operation": "begin-upload",
|
||||
"document-metadata": {
|
||||
"id": "doc-123",
|
||||
"kind": "application/pdf",
|
||||
"title": "Large Document",
|
||||
"user": "user-id",
|
||||
"tags": ["tag1", "tag2"]
|
||||
},
|
||||
"total-size": 524288000,
|
||||
"chunk-size": 5242880
|
||||
}
|
||||
```
|
||||
|
||||
Yanıt:
|
||||
```json
|
||||
{
|
||||
"upload-id": "upload-abc-123",
|
||||
"chunk-size": 5242880,
|
||||
"total-chunks": 100
|
||||
}
|
||||
```
|
||||
|
||||
Kütüphaneci:
|
||||
1. Benzersiz bir `upload_id` ve `object_id` oluşturur (blob depolama için UUID).
|
||||
2. S3'ü `CreateMultipartUpload` ile çağırır, `s3_upload_id`'i alır.
|
||||
3. Cassandra'da oturum kaydını oluşturur.
|
||||
4. `upload_id`'ı istemciye döndürür.
|
||||
|
||||
#### `upload-chunk`
|
||||
|
||||
Tek bir bölüm yükleyin.
|
||||
|
||||
İstek:
|
||||
```json
|
||||
{
|
||||
"operation": "upload-chunk",
|
||||
"upload-id": "upload-abc-123",
|
||||
"chunk-index": 0,
|
||||
"content": "<base64-encoded-chunk>"
|
||||
}
|
||||
```
|
||||
|
||||
Yanıt:
|
||||
```json
|
||||
{
|
||||
"upload-id": "upload-abc-123",
|
||||
"chunk-index": 0,
|
||||
"chunks-received": 1,
|
||||
"total-chunks": 100,
|
||||
"bytes-received": 5242880,
|
||||
"total-bytes": 524288000
|
||||
}
|
||||
```
|
||||
|
||||
Kütüphaneci:
|
||||
1. `upload_id` ile oturumu arar.
|
||||
2. Mülkiyeti doğrular (kullanıcı, oturum oluşturucuyu eşleştirmelidir).
|
||||
3. Parça verileriyle S3'ü `UploadPart` ile çağırır, `etag` alır.
|
||||
4. Parça indeksini ve etiketini kullanarak oturum kaydını günceller.
|
||||
5. İlerleme durumunu istemciye döndürür.
|
||||
|
||||
Başarısız parçalar tekrar denenebilir - aynı `chunk-index`'ı tekrar gönderin.
|
||||
|
||||
#### `complete-upload`
|
||||
|
||||
Yüklemeyi tamamlayın ve belgeyi oluşturun.
|
||||
|
||||
İstek:
|
||||
```json
|
||||
{
|
||||
"operation": "complete-upload",
|
||||
"upload-id": "upload-abc-123"
|
||||
}
|
||||
```
|
||||
|
||||
Yanıt:
|
||||
```json
|
||||
{
|
||||
"document-id": "doc-123",
|
||||
"object-id": "550e8400-e29b-41d4-a716-446655440000"
|
||||
}
|
||||
```
|
||||
|
||||
Kütüphaneci:
|
||||
1. Oturumu kontrol eder, tüm parçaların alındığından emin olur.
|
||||
2. Parça etiketleriyle birlikte S3'ü `CompleteMultipartUpload` ile çağırır (S3 parçaları dahili olarak birleştirir - kütüphaneci için bellek maliyeti sıfırdır).
|
||||
3. Cassandra'da, meta veriler ve nesne referansı ile birlikte bir belge kaydı oluşturur.
|
||||
4. Yükleme oturumu kaydını siler.
|
||||
5. Belge kimliğini müşteriye döndürür.
|
||||
|
||||
|
||||
#### `abort-upload`
|
||||
|
||||
Devam eden bir yüklemeyi iptal et.
|
||||
|
||||
İstek:
|
||||
```json
|
||||
{
|
||||
"operation": "abort-upload",
|
||||
"upload-id": "upload-abc-123"
|
||||
}
|
||||
```
|
||||
|
||||
Kütüphaneci:
|
||||
1. Parçaları temizlemek için S3 `AbortMultipartUpload`'ı çağırır.
|
||||
2. Oturum kaydını Cassandra'dan siler.
|
||||
|
||||
#### `get-upload-status`
|
||||
|
||||
Bir yüklemenin durumunu sorgula (devam ettirme özelliği için).
|
||||
|
||||
İstek:
|
||||
```json
|
||||
{
|
||||
"operation": "get-upload-status",
|
||||
"upload-id": "upload-abc-123"
|
||||
}
|
||||
```
|
||||
|
||||
Yanıt:
|
||||
```json
|
||||
{
|
||||
"upload-id": "upload-abc-123",
|
||||
"state": "in-progress",
|
||||
"chunks-received": [0, 1, 2, 5, 6],
|
||||
"missing-chunks": [3, 4, 7, 8],
|
||||
"total-chunks": 100,
|
||||
"bytes-received": 36700160,
|
||||
"total-bytes": 524288000
|
||||
}
|
||||
```
|
||||
|
||||
#### `list-uploads`
|
||||
|
||||
Bir kullanıcı için eksik yüklemeleri listele.
|
||||
|
||||
İstek:
|
||||
```json
|
||||
{
|
||||
"operation": "list-uploads"
|
||||
}
|
||||
```
|
||||
|
||||
Yanıt:
|
||||
```json
|
||||
{
|
||||
"uploads": [
|
||||
{
|
||||
"upload-id": "upload-abc-123",
|
||||
"document-metadata": { "title": "Large Document", ... },
|
||||
"progress": { "chunks-received": 43, "total-chunks": 100 },
|
||||
"created-at": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Yükleme Oturum Depolama
|
||||
|
||||
Cassandra'da devam eden yüklemeleri takip edin:
|
||||
|
||||
```sql
|
||||
CREATE TABLE upload_session (
|
||||
upload_id text PRIMARY KEY,
|
||||
user text,
|
||||
document_id text,
|
||||
document_metadata text, -- JSON: title, kind, tags, comments, etc.
|
||||
s3_upload_id text, -- internal, for S3 operations
|
||||
object_id uuid, -- target blob ID
|
||||
total_size bigint,
|
||||
chunk_size int,
|
||||
total_chunks int,
|
||||
chunks_received map<int, text>, -- chunk_index → etag
|
||||
created_at timestamp,
|
||||
updated_at timestamp
|
||||
) WITH default_time_to_live = 86400; -- 24 hour TTL
|
||||
|
||||
CREATE INDEX upload_session_user ON upload_session (user);
|
||||
```
|
||||
|
||||
**TTL Davranışı:**
|
||||
Oturumlar, tamamlanmadığı takdirde 24 saat sonra sona erer.
|
||||
Cassandra TTL'si dolduğunda, oturum kaydı silinir.
|
||||
Yalnız kalmış S3 parçaları, S3 yaşam döngüsü politikası tarafından temizlenir (kovada yapılandırılır).
|
||||
|
||||
### Hata Yönetimi ve Atomiklik
|
||||
|
||||
**Parça yükleme hatası:**
|
||||
İstemci, başarısız olan parçayı tekrar dener (aynı `upload_id` ve `chunk-index`).
|
||||
S3 `UploadPart`, aynı parça numarası için idempotent'tir.
|
||||
Oturum, hangi parçaların başarılı olduğunu takip eder.
|
||||
|
||||
**İstemci, yükleme sırasında bağlantıyı keser:**
|
||||
Oturum, Cassandra'da alınan parçalarla birlikte kalır.
|
||||
İstemci, eksik olanları görmek için `get-upload-status`'ı çağırabilir.
|
||||
Yalnızca eksik parçaları yükleyerek devam edin ve ardından `complete-upload`'ı çağırın.
|
||||
|
||||
**Tamamlanmış yükleme hatası:**
|
||||
S3 `CompleteMultipartUpload` atomiktir - ya tamamen başarılı olur ya da başarısız olur.
|
||||
Başarısızlık durumunda, parçalar kalır ve istemci `complete-upload`'ı tekrar deneyebilir.
|
||||
Hiçbir kısmi belge görünmez.
|
||||
|
||||
**Oturumun sona ermesi:**
|
||||
Cassandra TTL, oturum kaydını 24 saat sonra siler.
|
||||
S3 kova yaşam döngüsü politikası, tamamlanmamış çok parçalı yüklemeleri temizler.
|
||||
Manuel temizliğe gerek yoktur.
|
||||
|
||||
### S3 Çok Parçalı Atomiklik
|
||||
|
||||
S3 çok parçalı yüklemeler, yerleşik atomiklik sağlar:
|
||||
|
||||
1. **Parçalar görünmezdir:** Yüklenen parçalar, nesne olarak erişilemez.
|
||||
Bunlar yalnızca tamamlanmamış bir çok parçalı yüklemenin parçaları olarak vardır.
|
||||
|
||||
2. **Atomik tamamlama:** `CompleteMultipartUpload` ya başarılı olur (nesne
|
||||
atomik olarak görünür) ya da başarısız olur (nesne oluşturulmaz). Herhangi bir kısmi durum yoktur.
|
||||
|
||||
3. **Yeniden adlandırmaya gerek yoktur:** Son nesne anahtarı,
|
||||
`CreateMultipartUpload` zamanında belirtilir. Parçalar doğrudan bu anahtara birleştirilir.
|
||||
|
||||
4. **Sunucu tarafı birleştirme:** S3, parçaları dahili olarak birleştirir. Kütüphaneci
|
||||
parçaları asla tekrar okumaz - belgenin boyutundan bağımsız olarak sıfır bellek yükü.
|
||||
|
||||
### BlobStore Uzantıları
|
||||
|
||||
**Dosya:** `trustgraph-flow/trustgraph/librarian/blob_store.py`
|
||||
|
||||
Çok parçalı yükleme yöntemleri ekleyin:
|
||||
|
||||
```python
|
||||
class BlobStore:
|
||||
# Existing methods...
|
||||
|
||||
def create_multipart_upload(self, object_id: UUID, kind: str) -> str:
|
||||
"""Initialize multipart upload, return s3_upload_id."""
|
||||
# minio client: create_multipart_upload()
|
||||
|
||||
def upload_part(
|
||||
self, object_id: UUID, s3_upload_id: str,
|
||||
part_number: int, data: bytes
|
||||
) -> str:
|
||||
"""Upload a single part, return etag."""
|
||||
# minio client: upload_part()
|
||||
# Note: S3 part numbers are 1-indexed
|
||||
|
||||
def complete_multipart_upload(
|
||||
self, object_id: UUID, s3_upload_id: str,
|
||||
parts: List[Tuple[int, str]] # [(part_number, etag), ...]
|
||||
) -> None:
|
||||
"""Finalize multipart upload."""
|
||||
# minio client: complete_multipart_upload()
|
||||
|
||||
def abort_multipart_upload(
|
||||
self, object_id: UUID, s3_upload_id: str
|
||||
) -> None:
|
||||
"""Cancel multipart upload, clean up parts."""
|
||||
# minio client: abort_multipart_upload()
|
||||
```
|
||||
|
||||
### Parça Boyutu Hususları
|
||||
|
||||
**S3 minimumu**: Parça başına 5 MB (son parça hariç)
|
||||
**S3 maksimumu**: Bir yükleme başına 10.000 parça
|
||||
**Pratik varsayılan**: 5 MB'lık parçalar
|
||||
500 MB'lık bir belge = 100 parça
|
||||
5 GB'lık bir belge = 1.000 parça
|
||||
**İlerleme hassasiyeti**: Daha küçük parçalar = daha hassas ilerleme güncellemeleri
|
||||
**Ağ verimliliği**: Daha büyük parçalar = daha az sayıda istek
|
||||
|
||||
Parça boyutu, belirli sınırlar içinde (5 MB - 100 MB) istemci tarafından yapılandırılabilir.
|
||||
|
||||
### Belge İşleme: Akışlı Alma
|
||||
|
||||
Yükleme akışı, belgelerin depolamaya verimli bir şekilde aktarılmasını sağlar. İşleme akışı, belgelerin tamamını belleğe yüklemeden, belgelerin çıkarılmasını ve parçalara ayrılmasını sağlar.
|
||||
|
||||
|
||||
|
||||
#### Tasarım İlkesi: İçerik Değil, Tanımlayıcı
|
||||
|
||||
Şu anda, işleme başlatıldığında, belge içeriği Pulsar mesajları aracılığıyla akar. Bu, tüm belgelerin belleğe yüklenmesine neden olur. Bunun yerine:
|
||||
|
||||
|
||||
Pulsar mesajları yalnızca **belge tanımlayıcısını** taşır
|
||||
İşleyiciler, belge içeriğini doğrudan kütüphaneden alırlar
|
||||
Alma işlemi, bir **geçici dosyaya akış şeklinde** gerçekleşir
|
||||
Belgeye özgü ayrıştırma (PDF, metin vb.), bellek arabellekleri yerine dosyalarla çalışır
|
||||
|
||||
Bu, kütüphanenin belge yapısına bağımlı olmamasını sağlar. PDF ayrıştırma, metin
|
||||
çıkarma ve diğer biçime özgü mantık, ilgili kodlayıcılarda kalır.
|
||||
|
||||
#### İşleme Akışı
|
||||
|
||||
```
|
||||
Pulsar PDF Decoder Librarian S3
|
||||
│ │ │ │
|
||||
│── doc-id ───────────►│ │ │
|
||||
│ (processing msg) │ │ │
|
||||
│ │ │ │
|
||||
│ │── stream-document ──────►│ │
|
||||
│ │ (doc-id) │── GetObject ────►│
|
||||
│ │ │ │
|
||||
│ │◄── chunk ────────────────│◄── stream ───────│
|
||||
│ │ (write to temp file) │ │
|
||||
│ │◄── chunk ────────────────│◄── stream ───────│
|
||||
│ │ (append to temp file) │ │
|
||||
│ │ ⋮ │ ⋮ │
|
||||
│ │◄── EOF ──────────────────│ │
|
||||
│ │ │ │
|
||||
│ │ ┌──────────────────────────┐ │
|
||||
│ │ │ temp file on disk │ │
|
||||
│ │ │ (memory stays bounded) │ │
|
||||
│ │ └────────────┬─────────────┘ │
|
||||
│ │ │ │
|
||||
│ │ PDF library opens file │
|
||||
│ │ extract page 1 text ──► chunker │
|
||||
│ │ extract page 2 text ──► chunker │
|
||||
│ │ ⋮ │
|
||||
│ │ close file │
|
||||
│ │ delete temp file │
|
||||
```
|
||||
|
||||
#### Kütüphaneci Akış API'si
|
||||
|
||||
Bir akışlı belge alma işlemi ekleyin:
|
||||
|
||||
**`stream-document`**
|
||||
|
||||
İstek:
|
||||
```json
|
||||
{
|
||||
"operation": "stream-document",
|
||||
"document-id": "doc-123"
|
||||
}
|
||||
```
|
||||
|
||||
Yanıt: Akışlı ikili veri parçaları (tek bir yanıt değil).
|
||||
|
||||
REST API için, bu, `Transfer-Encoding: chunked` ile bir akışlı yanıt döndürür.
|
||||
|
||||
İç hizmetler arası iletişimler (işlemci ile kütüphaneci), şu şekilde olabilir:
|
||||
İmza yoluyla doğrudan S3 akışı (eğer iç ağ izin veriyorsa)
|
||||
Hizmet protokolü üzerinden parçalı yanıtlar
|
||||
Özel bir akış uç noktası
|
||||
|
||||
Temel gereksinim: Veri, kütüphaneci tarafından asla tamamen tamponlanmadan, parçalar halinde akmalıdır.
|
||||
|
||||
#### PDF Kod Çözücü Değişiklikleri
|
||||
|
||||
**Mevcut uygulama** (bellek yoğun):
|
||||
|
||||
```python
|
||||
def decode_pdf(document_content: bytes) -> str:
|
||||
reader = PdfReader(BytesIO(document_content)) # full doc in memory
|
||||
text = ""
|
||||
for page in reader.pages:
|
||||
text += page.extract_text() # accumulating
|
||||
return text # full text in memory
|
||||
```
|
||||
|
||||
**Yeni uygulama** (geçici dosya, kademeli):
|
||||
|
||||
```python
|
||||
def decode_pdf_streaming(doc_id: str, librarian_client) -> Iterator[str]:
|
||||
"""Yield extracted text page by page."""
|
||||
|
||||
with tempfile.NamedTemporaryFile(delete=True, suffix='.pdf') as tmp:
|
||||
# Stream document to temp file
|
||||
for chunk in librarian_client.stream_document(doc_id):
|
||||
tmp.write(chunk)
|
||||
tmp.flush()
|
||||
|
||||
# Open PDF from file (not memory)
|
||||
reader = PdfReader(tmp.name)
|
||||
|
||||
# Yield pages incrementally
|
||||
for page in reader.pages:
|
||||
yield page.extract_text()
|
||||
|
||||
# tmp file auto-deleted on context exit
|
||||
```
|
||||
|
||||
Bellek profili:
|
||||
Geçici dosya diskte: PDF'nin boyutu (disk ucuzdur)
|
||||
Bellekte: bir seferde bir sayfanın metni
|
||||
Maksimum bellek: sınırlı, belge boyutundan bağımsız
|
||||
|
||||
#### Metin Belgesi Kod Çözücü Değişiklikleri
|
||||
|
||||
Düz metin belgeleri için, daha da basit - geçici dosyaya ihtiyaç yok:
|
||||
|
||||
```python
|
||||
def decode_text_streaming(doc_id: str, librarian_client) -> Iterator[str]:
|
||||
"""Yield text in chunks as it streams from storage."""
|
||||
|
||||
buffer = ""
|
||||
for chunk in librarian_client.stream_document(doc_id):
|
||||
buffer += chunk.decode('utf-8')
|
||||
|
||||
# Yield complete lines/paragraphs as they arrive
|
||||
while '\n\n' in buffer:
|
||||
paragraph, buffer = buffer.split('\n\n', 1)
|
||||
yield paragraph + '\n\n'
|
||||
|
||||
# Yield remaining buffer
|
||||
if buffer:
|
||||
yield buffer
|
||||
```
|
||||
|
||||
Metin belgeleri, geçici bir dosyaya ihtiyaç duymadan doğrudan akış halinde iletilebilir, çünkü bunlar
|
||||
doğrusal bir yapıya sahiptir.
|
||||
|
||||
#### Akış Tabanlı Parçalama Entegrasyonu
|
||||
|
||||
Parçalayıcı, metin (sayfalar veya paragraflar)den oluşan bir yineleyici alır ve
|
||||
parçaları kademeli olarak üretir:
|
||||
|
||||
```python
|
||||
class StreamingChunker:
|
||||
def __init__(self, chunk_size: int, overlap: int):
|
||||
self.chunk_size = chunk_size
|
||||
self.overlap = overlap
|
||||
|
||||
def process(self, text_stream: Iterator[str]) -> Iterator[str]:
|
||||
"""Yield chunks as text arrives."""
|
||||
buffer = ""
|
||||
|
||||
for text_segment in text_stream:
|
||||
buffer += text_segment
|
||||
|
||||
while len(buffer) >= self.chunk_size:
|
||||
chunk = buffer[:self.chunk_size]
|
||||
yield chunk
|
||||
# Keep overlap for context continuity
|
||||
buffer = buffer[self.chunk_size - self.overlap:]
|
||||
|
||||
# Yield remaining buffer as final chunk
|
||||
if buffer.strip():
|
||||
yield buffer
|
||||
```
|
||||
|
||||
#### Uçtan Uca İşlem Hattı
|
||||
|
||||
```python
|
||||
async def process_document(doc_id: str, librarian_client, embedder):
|
||||
"""Process document with bounded memory."""
|
||||
|
||||
# Get document metadata to determine type
|
||||
metadata = await librarian_client.get_document_metadata(doc_id)
|
||||
|
||||
# Select decoder based on document type
|
||||
if metadata.kind == 'application/pdf':
|
||||
text_stream = decode_pdf_streaming(doc_id, librarian_client)
|
||||
elif metadata.kind == 'text/plain':
|
||||
text_stream = decode_text_streaming(doc_id, librarian_client)
|
||||
else:
|
||||
raise UnsupportedDocumentType(metadata.kind)
|
||||
|
||||
# Chunk incrementally
|
||||
chunker = StreamingChunker(chunk_size=1000, overlap=100)
|
||||
|
||||
# Process each chunk as it's produced
|
||||
for chunk in chunker.process(text_stream):
|
||||
# Generate embeddings, store in vector DB, etc.
|
||||
embedding = await embedder.embed(chunk)
|
||||
await store_chunk(doc_id, chunk, embedding)
|
||||
```
|
||||
|
||||
Hiçbir noktada, tam belge veya tam çıkarılmış metin bellekte tutulmaz.
|
||||
|
||||
#### Geçici Dosya Hususları
|
||||
|
||||
**Konum:** Sistem geçici dizinini kullanın (`/tmp` veya eşdeğeri).
|
||||
Sanallaştırılmış dağıtımlar için, geçici dizinin yeterli alana sahip olduğundan ve mümkünse hızlı depolama üzerinde olduğundan emin olun.
|
||||
|
||||
|
||||
**Temizleme:** Temizlemenin, istisnalar olsa bile, sağlanması için bağlam yöneticileri (`with tempfile...`) kullanın.
|
||||
|
||||
|
||||
**Eşzamanlı işleme:** Her işleme görevi kendi geçici dosyasına sahiptir.
|
||||
Paralel belge işleme arasında herhangi bir çakışma olmaz.
|
||||
|
||||
**Disk alanı:** Geçici dosyalar, kısa ömürlüdür (işlem süresi boyunca).
|
||||
500MB'lık bir PDF için, işleme sırasında 500MB geçici alana ihtiyaç vardır. Disk alanı sınırlıysa, boyut sınırı yükleme sırasında uygulanabilir.
|
||||
|
||||
|
||||
### Birlikte Çalışan İşlem Arayüzü: Alt Belgeler
|
||||
|
||||
PDF çıkarma ve metin belge işleme, aynı
|
||||
aşağı akış hattına (parçalayıcı → gömüler → depolama) beslenmelidir. Bunu, tutarlı bir "ID'ye göre alma" arayüzüyle sağlamak için, çıkarılan metin blokları, "librarian"a alt belgeler olarak geri kaydedilir.
|
||||
|
||||
|
||||
|
||||
#### Alt Belgelerle İşlem Akışı
|
||||
|
||||
```
|
||||
PDF Document Text Document
|
||||
│ │
|
||||
▼ │
|
||||
pdf-extractor │
|
||||
│ │
|
||||
│ (stream PDF from librarian) │
|
||||
│ (extract page 1 text) │
|
||||
│ (store as child doc → librarian) │
|
||||
│ (extract page 2 text) │
|
||||
│ (store as child doc → librarian) │
|
||||
│ ⋮ │
|
||||
▼ ▼
|
||||
[child-doc-id, child-doc-id, ...] [doc-id]
|
||||
│ │
|
||||
└─────────────────────┬───────────────────────────────┘
|
||||
▼
|
||||
chunker
|
||||
│
|
||||
│ (receives document ID)
|
||||
│ (streams content from librarian)
|
||||
│ (chunks incrementally)
|
||||
▼
|
||||
[chunks → embedding → storage]
|
||||
```
|
||||
|
||||
Parçalayıcı, tek bir standart arayüze sahiptir:
|
||||
Bir belge kimliğini alın (Pulsar aracılığıyla)
|
||||
Kütüphaneden içeriği akış olarak alın
|
||||
Bunu parçalara ayırın
|
||||
|
||||
Bu, kimliğin neye atıfta bulunduğunu bilmez veya umursamaz:
|
||||
Kullanıcı tarafından yüklenen bir metin belgesi
|
||||
Bir PDF sayfasından çıkarılan bir metin bloğu
|
||||
Herhangi bir gelecekteki belge türü
|
||||
|
||||
#### Alt Belge Meta Verileri
|
||||
|
||||
Belge şemasını, ana/alt ilişkilerini izlemek için genişletin:
|
||||
|
||||
```sql
|
||||
-- Add columns to document table
|
||||
ALTER TABLE document ADD parent_id text;
|
||||
ALTER TABLE document ADD document_type text;
|
||||
|
||||
-- Index for finding children of a parent
|
||||
CREATE INDEX document_parent ON document (parent_id);
|
||||
```
|
||||
|
||||
**Belge türleri:**
|
||||
|
||||
| `document_type` | Açıklama |
|
||||
|-----------------|-------------|
|
||||
| `source` | Kullanıcı tarafından yüklenen belge (PDF, metin, vb.) |
|
||||
| `extracted` | Kaynak bir belgeden türetilmiş (örneğin, PDF sayfa metni) |
|
||||
|
||||
**Meta veri alanları:**
|
||||
|
||||
| Alan | Kaynak Belge | Çıkarılan Alt Belge |
|
||||
|-------|-----------------|-----------------|
|
||||
| `id` | kullanıcı tarafından sağlanan veya oluşturulan | oluşturulan (örneğin, `{parent-id}-page-{n}`) |
|
||||
| `parent_id` | `NULL` | ana belge kimliği |
|
||||
| `document_type` | `source` | `extracted` |
|
||||
| `kind` | `application/pdf`, vb. | `text/plain` |
|
||||
| `title` | kullanıcı tarafından sağlanan | oluşturulan (örneğin, "Rapor.pdf'nin 3. sayfası") |
|
||||
| `user` | kimliği doğrulanmış kullanıcı | ana belge ile aynı |
|
||||
|
||||
#### Alt Belgeler için Kütüphaneci API'si
|
||||
|
||||
**Alt belgeler oluşturma** (içerik, pdf-extractor tarafından kullanılır):
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "add-child-document",
|
||||
"parent-id": "doc-123",
|
||||
"document-metadata": {
|
||||
"id": "doc-123-page-1",
|
||||
"kind": "text/plain",
|
||||
"title": "Page 1"
|
||||
},
|
||||
"content": "<base64-encoded-text>"
|
||||
}
|
||||
```
|
||||
|
||||
Küçük boyutlu, çıkarılmış metinler için (tipik bir sayfa metni < 100KB), tek seferlik yükleme kabul edilebilir. Çok büyük metin çıkarımları için, parçalı yükleme kullanılabilir.
|
||||
|
||||
**Alt belgelerin listelenmesi** (hata ayıklama/yönetim için):
|
||||
|
||||
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "list-children",
|
||||
"parent-id": "doc-123"
|
||||
}
|
||||
```
|
||||
|
||||
Yanıt:
|
||||
```json
|
||||
{
|
||||
"children": [
|
||||
{ "id": "doc-123-page-1", "title": "Page 1", "kind": "text/plain" },
|
||||
{ "id": "doc-123-page-2", "title": "Page 2", "kind": "text/plain" },
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Kullanıcı Arayüzü Davranışı
|
||||
|
||||
**`list-documents` varsayılan davranış:**
|
||||
|
||||
```sql
|
||||
SELECT * FROM document WHERE user = ? AND parent_id IS NULL;
|
||||
```
|
||||
|
||||
Yalnızca en üst düzey (kaynak) belgeler, kullanıcının belge listesinde görünür.
|
||||
Alt belgeler, varsayılan olarak filtrelenir.
|
||||
|
||||
**İsteğe bağlı "çocukları-dahil-et" bayrağı** (yönetici/hata ayıklama için):
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "list-documents",
|
||||
"include-children": true
|
||||
}
|
||||
```
|
||||
|
||||
#### Kaskad Sıralı Silme
|
||||
|
||||
Bir üst belge silindiğinde, tüm alt belgelerin de silinmesi gerekir:
|
||||
|
||||
```python
|
||||
def delete_document(doc_id: str):
|
||||
# Find all children
|
||||
children = query("SELECT id, object_id FROM document WHERE parent_id = ?", doc_id)
|
||||
|
||||
# Delete child blobs from S3
|
||||
for child in children:
|
||||
blob_store.delete(child.object_id)
|
||||
|
||||
# Delete child metadata from Cassandra
|
||||
execute("DELETE FROM document WHERE parent_id = ?", doc_id)
|
||||
|
||||
# Delete parent blob and metadata
|
||||
parent = get_document(doc_id)
|
||||
blob_store.delete(parent.object_id)
|
||||
execute("DELETE FROM document WHERE id = ? AND user = ?", doc_id, user)
|
||||
```
|
||||
|
||||
#### Depolama Hususları
|
||||
|
||||
Çıkarılan metin blokları, yinelenen içerik oluşturur:
|
||||
Orijinal PDF, "Garage" (Depo) içinde saklanır.
|
||||
Her sayfa için çıkarılan metin de "Garage" içinde saklanır.
|
||||
|
||||
Bu denge şunları sağlar:
|
||||
**Tutarlı bir parçalama arayüzü**: Parçalayıcı her zaman ID'ye göre veri alır.
|
||||
**Devam ettirme/yeniden deneme**: PDF'i yeniden çıkarmadan, parçalama aşamasında yeniden başlatılabilir.
|
||||
**Hata ayıklama**: Çıkarılan metin incelenebilir.
|
||||
**Sorumlulukların ayrılması**: PDF çıkarıcı ve parçalayıcı bağımsız hizmetlerdir.
|
||||
|
||||
200 sayfalık ve sayfa başına ortalama 5KB metin içeren 500MB'lık bir PDF için:
|
||||
PDF depolama: 500MB
|
||||
Çıkarılan metin depolama: ~1MB toplam
|
||||
Ek yük: ihmal edilebilir
|
||||
|
||||
#### PDF Çıkarıcı Çıktısı
|
||||
|
||||
pdf-çıkarıcı, bir belgeyi işledikten sonra:
|
||||
|
||||
1. PDF'i "librarian" (kütüphaneci) üzerinden geçici bir dosyaya aktarır.
|
||||
2. Metni sayfa sayfa çıkarır.
|
||||
3. Her sayfa için, çıkarılan metni "librarian" aracılığıyla bir alt belge olarak saklar.
|
||||
4. Alt belge ID'lerini parçalayıcı kuyruğuna gönderir.
|
||||
ÇIKTI SÖZLEŞMESİ (tam olarak aşağıdaki formatı takip etmelidir):
|
||||
```python
|
||||
async def extract_pdf(doc_id: str, librarian_client, output_queue):
|
||||
"""Extract PDF pages and store as child documents."""
|
||||
|
||||
with tempfile.NamedTemporaryFile(delete=True, suffix='.pdf') as tmp:
|
||||
# Stream PDF to temp file
|
||||
for chunk in librarian_client.stream_document(doc_id):
|
||||
tmp.write(chunk)
|
||||
tmp.flush()
|
||||
|
||||
# Extract pages
|
||||
reader = PdfReader(tmp.name)
|
||||
for page_num, page in enumerate(reader.pages, start=1):
|
||||
text = page.extract_text()
|
||||
|
||||
# Store as child document
|
||||
child_id = f"{doc_id}-page-{page_num}"
|
||||
await librarian_client.add_child_document(
|
||||
parent_id=doc_id,
|
||||
document_id=child_id,
|
||||
kind="text/plain",
|
||||
title=f"Page {page_num}",
|
||||
content=text.encode('utf-8')
|
||||
)
|
||||
|
||||
# Send to chunker queue
|
||||
await output_queue.send(child_id)
|
||||
```
|
||||
|
||||
Parçalayıcı, bu alt kimlikleri alır ve bunları, bir kullanıcının yüklediği bir metin belgesini işlerken olduğu gibi aynı şekilde işler.
|
||||
|
||||
### İstemci Güncellemeleri
|
||||
|
||||
#### Python SDK
|
||||
|
||||
|
||||
Python SDK'sı (`trustgraph-base/trustgraph/api/library.py`), parçalı yüklemeleri şeffaf bir şekilde işlemelidir. Kamu arayüzü değişmeden kalır:
|
||||
|
||||
|
||||
```python
|
||||
# Existing interface - no change for users
|
||||
library.add_document(
|
||||
id="doc-123",
|
||||
title="Large Report",
|
||||
kind="application/pdf",
|
||||
content=large_pdf_bytes, # Can be hundreds of MB
|
||||
tags=["reports"]
|
||||
)
|
||||
```
|
||||
|
||||
İçeride, SDK belge boyutunu algılar ve stratejiyi değiştirir:
|
||||
|
||||
```python
|
||||
class Library:
|
||||
CHUNKED_UPLOAD_THRESHOLD = 2 * 1024 * 1024 # 2MB
|
||||
|
||||
def add_document(self, id, title, kind, content, tags=None, ...):
|
||||
if len(content) < self.CHUNKED_UPLOAD_THRESHOLD:
|
||||
# Small document: single operation (existing behavior)
|
||||
return self._add_document_single(id, title, kind, content, tags)
|
||||
else:
|
||||
# Large document: chunked upload
|
||||
return self._add_document_chunked(id, title, kind, content, tags)
|
||||
|
||||
def _add_document_chunked(self, id, title, kind, content, tags):
|
||||
# 1. begin-upload
|
||||
session = self._begin_upload(
|
||||
document_metadata={...},
|
||||
total_size=len(content),
|
||||
chunk_size=5 * 1024 * 1024
|
||||
)
|
||||
|
||||
# 2. upload-chunk for each chunk
|
||||
for i, chunk in enumerate(self._chunk_bytes(content, session.chunk_size)):
|
||||
self._upload_chunk(session.upload_id, i, chunk)
|
||||
|
||||
# 3. complete-upload
|
||||
return self._complete_upload(session.upload_id)
|
||||
```
|
||||
|
||||
**İlerleme geri bildirimleri** (isteğe bağlı iyileştirme):
|
||||
|
||||
```python
|
||||
def add_document(self, ..., on_progress=None):
|
||||
"""
|
||||
on_progress: Optional callback(bytes_sent, total_bytes)
|
||||
"""
|
||||
```
|
||||
|
||||
Bu, kullanıcı arayüzlerinin temel API'yi değiştirmeden yükleme ilerlemesini görüntülemesini sağlar.
|
||||
|
||||
#### Komut Satırı Araçları
|
||||
|
||||
**`tg-add-library-document`** değişmeden çalışmaya devam ediyor:
|
||||
|
||||
```bash
|
||||
# Works transparently for any size - SDK handles chunking internally
|
||||
tg-add-library-document --file large-report.pdf --title "Large Report"
|
||||
```
|
||||
|
||||
İsteğe bağlı bir ilerleme durumu göstergesi eklenebilir:
|
||||
|
||||
```bash
|
||||
tg-add-library-document --file large-report.pdf --title "Large Report" --progress
|
||||
# Output:
|
||||
# Uploading: 45% (225MB / 500MB)
|
||||
```
|
||||
|
||||
**Eski araçlar kaldırıldı:**
|
||||
|
||||
`tg-load-pdf` - kullanımdan kaldırıldı, `tg-add-library-document`'i kullanın.
|
||||
`tg-load-text` - kullanımdan kaldırıldı, `tg-add-library-document`'i kullanın.
|
||||
|
||||
**Yönetici/hata ayıklama komutları** (isteğe bağlı, düşük öncelikli):
|
||||
|
||||
```bash
|
||||
# List incomplete uploads (admin troubleshooting)
|
||||
tg-add-library-document --list-pending
|
||||
|
||||
# Resume specific upload (recovery scenario)
|
||||
tg-add-library-document --resume upload-abc-123 --file large-report.pdf
|
||||
```
|
||||
|
||||
Bunlar, ayrı araçlar yerine mevcut komuttaki bayraklar olabilir.
|
||||
|
||||
#### API Özellik Güncellemeleri
|
||||
|
||||
OpenAPI spesifikasyonu (`specs/api/paths/librarian.yaml`), aşağıdaki güncellemeleri gerektiriyor:
|
||||
|
||||
**Yeni işlemler:**
|
||||
|
||||
`begin-upload` - Parçalı yükleme oturumunu başlat
|
||||
`upload-chunk` - Tek bir parçayı yükle
|
||||
`complete-upload` - Yüklemeyi tamamla
|
||||
`abort-upload` - Yüklemeyi iptal et
|
||||
`get-upload-status` - Yükleme ilerlemesini sorgula
|
||||
`list-uploads` - Kullanıcı için tamamlanmamış yüklemeleri listele
|
||||
`stream-document` - Akışlı belge alma
|
||||
`add-child-document` - Çıkarılan metni kaydet (iç)
|
||||
`list-children` - Alt belgeleri listele (yönetici)
|
||||
|
||||
**Değiştirilen işlemler:**
|
||||
|
||||
`list-documents` - `include-children` parametresini ekle
|
||||
|
||||
**Yeni şemalar:**
|
||||
|
||||
`ChunkedUploadBeginRequest`
|
||||
`ChunkedUploadBeginResponse`
|
||||
`ChunkedUploadChunkRequest`
|
||||
`ChunkedUploadChunkResponse`
|
||||
`UploadSession`
|
||||
`UploadProgress`
|
||||
|
||||
**WebSocket spesifikasyonunda yapılan güncellemeler** (`specs/websocket/`):
|
||||
|
||||
WebSocket istemcileri için REST işlemlerini yansıtın, böylece yükleme sırasında gerçek zamanlı
|
||||
ilerleme güncellemeleri sağlanır.
|
||||
|
||||
#### Kullanıcı Deneyimi Hususları
|
||||
|
||||
API spesifikasyonundaki güncellemeler, ön yüzdeki iyileştirmelere olanak tanır:
|
||||
|
||||
**Yükleme ilerleme arayüzü:**
|
||||
Yüklenen parçaları gösteren ilerleme çubuğu
|
||||
Kalan tahmini süre
|
||||
Duraklatma/devam ettirme özelliği
|
||||
|
||||
**Hata kurtarma:**
|
||||
Kesintiye uğramış yüklemeler için "Yüklemeyi devam ettir" seçeneği
|
||||
Yeniden bağlanırken bekleyen yüklemelerin listesi
|
||||
|
||||
**Büyük dosya işleme:**
|
||||
İstemci tarafında dosya boyutu tespiti
|
||||
Büyük dosyalar için otomatik parçalı yükleme
|
||||
Uzun yüklemeler sırasında net geri bildirim
|
||||
|
||||
Bu kullanıcı deneyimi iyileştirmeleri, güncellenmiş API spesifikasyonu tarafından yönlendirilen ön yüz işleme gerektirir.
|
||||
358
docs/tech-specs/tr/logging-strategy.tr.md
Normal file
358
docs/tech-specs/tr/logging-strategy.tr.md
Normal file
|
|
@ -0,0 +1,358 @@
|
|||
---
|
||||
layout: default
|
||||
title: "TrustGraph Kayıt (Log) Stratejisi"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# TrustGraph Kayıt (Log) Stratejisi
|
||||
|
||||
> **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ış
|
||||
|
||||
TrustGraph, tüm kayıt işlemlerinde Python'un yerleşik `logging` modülünü kullanır, merkezi yapılandırma ve kayıt toplama için isteğe bağlı Loki entegrasyonuna sahiptir. Bu, sistemin tüm bileşenleri için standartlaştırılmış, esnek bir kayıt yaklaşımı sağlar.
|
||||
|
||||
## Varsayılan Yapılandırma
|
||||
|
||||
### Kayıt Seviyesi
|
||||
**Varsayılan Seviye**: `INFO`
|
||||
**Yapılandırılabilir**: `--log-level` komut satırı argümanı aracılığıyla
|
||||
**Seçenekler**: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
|
||||
|
||||
### Çıkış Hedefleri
|
||||
1. **Konsol (stdout)**: Her zaman etkindir - konteynerleştirilmiş ortamlarla uyumluluğu sağlar.
|
||||
2. **Loki**: İsteğe bağlı, merkezi kayıt toplama (varsayılan olarak etkindir, devre dışı bırakılabilir).
|
||||
|
||||
## Merkezi Kayıt Modülü
|
||||
|
||||
Tüm kayıt yapılandırması, aşağıdaki özellikleri sağlayan `trustgraph.base.logging` modülü tarafından yönetilir:
|
||||
`add_logging_args(parser)` - Standart kayıt komut satırı argümanlarını ekler.
|
||||
`setup_logging(args)` - Ayrıştırılmış argümanlardan kaydı yapılandırır.
|
||||
|
||||
Bu modül, tüm sunucu tarafı bileşenleri tarafından kullanılır:
|
||||
AsyncProcessor tabanlı hizmetler
|
||||
API Ağ Geçidi
|
||||
MCP Sunucusu
|
||||
|
||||
## Uygulama Yönergeleri
|
||||
|
||||
### 1. Kayıt Oluşturucu Başlatma
|
||||
|
||||
Her modül, modülün `__name__`'ını kullanarak kendi kayıt oluşturucusunu oluşturmalıdır:
|
||||
|
||||
```python
|
||||
import logging
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
```
|
||||
|
||||
Kayıt günlüğünün adı, Loki'de filtreleme ve arama için otomatik olarak bir etiket olarak kullanılır.
|
||||
|
||||
### 2. Hizmet Başlatma
|
||||
|
||||
Tüm sunucu tarafı hizmetleri, merkezi modül aracılığıyla otomatik olarak günlük yapılandırması alır:
|
||||
|
||||
```python
|
||||
from trustgraph.base import add_logging_args, setup_logging
|
||||
import argparse
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser()
|
||||
|
||||
# Add standard logging arguments (includes Loki configuration)
|
||||
add_logging_args(parser)
|
||||
|
||||
# Add your service-specific arguments
|
||||
parser.add_argument('--port', type=int, default=8080)
|
||||
|
||||
args = parser.parse_args()
|
||||
args = vars(args)
|
||||
|
||||
# Setup logging early in startup
|
||||
setup_logging(args)
|
||||
|
||||
# Rest of your service initialization
|
||||
logger = logging.getLogger(__name__)
|
||||
logger.info("Service starting...")
|
||||
```
|
||||
|
||||
### 3. Komut Satırı Argümanları
|
||||
|
||||
Tüm hizmetler bu günlük kaydı argümanlarını destekler:
|
||||
|
||||
**Günlük Seviyesi:**
|
||||
```bash
|
||||
--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
|
||||
```
|
||||
|
||||
**Loki Yapılandırması:**
|
||||
```bash
|
||||
--loki-enabled # Enable Loki (default)
|
||||
--no-loki-enabled # Disable Loki
|
||||
--loki-url URL # Loki push URL (default: http://loki:3100/loki/api/v1/push)
|
||||
--loki-username USERNAME # Optional authentication
|
||||
--loki-password PASSWORD # Optional authentication
|
||||
```
|
||||
|
||||
**Örnekler:**
|
||||
```bash
|
||||
# Default - INFO level, Loki enabled
|
||||
./my-service
|
||||
|
||||
# Debug mode, console only
|
||||
./my-service --log-level DEBUG --no-loki-enabled
|
||||
|
||||
# Custom Loki server with auth
|
||||
./my-service --loki-url http://loki.prod:3100/loki/api/v1/push \
|
||||
--loki-username admin --loki-password secret
|
||||
```
|
||||
|
||||
### 4. Ortam Değişkenleri
|
||||
|
||||
Loki yapılandırması, ortam değişkeni geri dönüşlerini destekler:
|
||||
|
||||
```bash
|
||||
export LOKI_URL=http://loki.prod:3100/loki/api/v1/push
|
||||
export LOKI_USERNAME=admin
|
||||
export LOKI_PASSWORD=secret
|
||||
```
|
||||
|
||||
Komut satırı argümanları, ortam değişkenlerine göre önceliklidir.
|
||||
|
||||
### 5. Kayıt (Logging) İçin En İyi Uygulamalar
|
||||
|
||||
#### Kayıt Seviyelerinin Kullanımı
|
||||
**DEBUG**: Sorunları teşhis etmek için detaylı bilgiler (değişken değerleri, fonksiyon giriş/çıkış)
|
||||
**INFO**: Genel bilgilendirici mesajlar (hizmet başlatıldı, yapılandırma yüklendi, işlem aşamaları)
|
||||
**WARNING**: Potansiyel olarak tehlikeli durumlara yönelik uyarı mesajları (kullanımdan kaldırılmış özellikler, düzeltilebilir hatalar)
|
||||
**ERROR**: Ciddi sorunlara yönelik hata mesajları (başarısız işlemler, istisnalar)
|
||||
**CRITICAL**: Acil müdahale gerektiren sistem arızalarına yönelik kritik mesajlar
|
||||
|
||||
#### Mesaj Formatı
|
||||
```python
|
||||
# Good - includes context
|
||||
logger.info(f"Processing document: {doc_id}, size: {doc_size} bytes")
|
||||
logger.error(f"Failed to connect to database: {error}", exc_info=True)
|
||||
|
||||
# Avoid - lacks context
|
||||
logger.info("Processing document")
|
||||
logger.error("Connection failed")
|
||||
```
|
||||
|
||||
#### Performans Hususları
|
||||
```python
|
||||
# Use lazy formatting for expensive operations
|
||||
logger.debug("Expensive operation result: %s", expensive_function())
|
||||
|
||||
# Check log level for very expensive debug operations
|
||||
if logger.isEnabledFor(logging.DEBUG):
|
||||
debug_data = compute_expensive_debug_info()
|
||||
logger.debug(f"Debug data: {debug_data}")
|
||||
```
|
||||
|
||||
### 6. Loki ile Yapılandırılmış Günlüğe Kayıt
|
||||
|
||||
Karmaşık veriler için, Loki için ek etiketlerle yapılandırılmış günlüğe kaydı kullanın:
|
||||
|
||||
```python
|
||||
logger.info("Request processed", extra={
|
||||
'tags': {
|
||||
'request_id': request_id,
|
||||
'user_id': user_id,
|
||||
'status': 'success'
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
Bu etiketler, otomatik etiketlerin yanı sıra, Loki'de aranabilir etiketler haline gelir:
|
||||
`severity` - Log seviyesi (DEBUG, INFO, WARNING, ERROR, CRITICAL)
|
||||
`logger` - Modül adı (`__name__`'den)
|
||||
|
||||
### 7. İstisna Kaydı
|
||||
|
||||
İstisnalar için her zaman yığın izlerini ekleyin:
|
||||
|
||||
```python
|
||||
try:
|
||||
process_data()
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to process data: {e}", exc_info=True)
|
||||
raise
|
||||
```
|
||||
|
||||
### 8. Asenkron Kayıt (Logging) Hususları
|
||||
|
||||
Kayıt sistemi, Loki için engellemeyen, kuyruklu işleyiciler kullanır:
|
||||
Konsol çıktısı senkron (hızlıdır)
|
||||
Loki çıktısı, 500 mesajlık bir arabellekle kuyruğa alınır
|
||||
Arka plan iş parçacığı, Loki iletimini yönetir
|
||||
Ana uygulama kodunun engellenmesi olmaz
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
import logging
|
||||
|
||||
async def async_operation():
|
||||
logger = logging.getLogger(__name__)
|
||||
# Logging is thread-safe and won't block async operations
|
||||
logger.info(f"Starting async operation in task: {asyncio.current_task().get_name()}")
|
||||
```
|
||||
|
||||
## Loki Entegrasyonu
|
||||
|
||||
### Mimari
|
||||
|
||||
Günlük sistemi, engellemeyen Loki entegrasyonu için Python'un yerleşik `QueueHandler` ve `QueueListener` özelliklerini kullanır:
|
||||
|
||||
1. **QueueHandler**: Günlükler, 500 mesajlık bir kuyruğa (engellemesiz) yerleştirilir.
|
||||
2. **Arka Plan İş Parçacığı**: QueueListener, günlükleri Loki'ye asenkron olarak gönderir.
|
||||
3. **Usulüne Uygun Bozulma**: Loki kullanılamıyorsa, konsol günlüğü devam eder.
|
||||
|
||||
### Otomatik Etiketler
|
||||
|
||||
Loki'ye gönderilen her günlük şunları içerir:
|
||||
`processor`: İşlemci kimliği (örneğin, `config-svc`, `text-completion`, `embeddings`)
|
||||
`severity`: Günlük seviyesi (DEBUG, INFO, vb.)
|
||||
`logger`: Modül adı (örneğin, `trustgraph.gateway.service`, `trustgraph.agent.react.service`)
|
||||
|
||||
### Özel Etiketler
|
||||
|
||||
Özel etiketleri `extra` parametresi aracılığıyla ekleyin:
|
||||
|
||||
```python
|
||||
logger.info("User action", extra={
|
||||
'tags': {
|
||||
'user_id': user_id,
|
||||
'action': 'document_upload',
|
||||
'collection': collection_name
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Loki'de Logları Sorgulama
|
||||
|
||||
```logql
|
||||
# All logs from a specific processor (recommended - matches Prometheus metrics)
|
||||
{processor="config-svc"}
|
||||
{processor="text-completion"}
|
||||
{processor="embeddings"}
|
||||
|
||||
# Error logs from a specific processor
|
||||
{processor="config-svc", severity="ERROR"}
|
||||
|
||||
# Error logs from all processors
|
||||
{severity="ERROR"}
|
||||
|
||||
# Logs from a specific processor with text filter
|
||||
{processor="text-completion"} |= "Processing"
|
||||
|
||||
# All logs from API gateway
|
||||
{processor="api-gateway"}
|
||||
|
||||
# Logs from processors matching pattern
|
||||
{processor=~".*-completion"}
|
||||
|
||||
# Logs with custom tags
|
||||
{processor="api-gateway"} | json | user_id="12345"
|
||||
```
|
||||
|
||||
### Zarif Bozulma
|
||||
|
||||
Eğer Loki kullanılamıyorsa veya `python-logging-loki` yüklü değilse:
|
||||
Uyarı mesajı konsola yazdırılır
|
||||
Konsol kaydı normal şekilde devam eder
|
||||
Uygulama çalışmaya devam eder
|
||||
Loki bağlantısı için tekrar deneme mantığı yoktur (hızlı bir şekilde başarısız olun, zarif bir şekilde bozulun)
|
||||
|
||||
## Test
|
||||
|
||||
Testler sırasında, farklı bir kayıt yapılandırması kullanmayı düşünün:
|
||||
|
||||
```python
|
||||
# In test setup
|
||||
import logging
|
||||
|
||||
# Reduce noise during tests
|
||||
logging.getLogger().setLevel(logging.WARNING)
|
||||
|
||||
# Or disable Loki for tests
|
||||
setup_logging({'log_level': 'WARNING', 'loki_enabled': False})
|
||||
```
|
||||
|
||||
## İzleme Entegrasyonu
|
||||
|
||||
### Standart Format
|
||||
Tüm günlükler tutarlı bir formata sahiptir:
|
||||
```
|
||||
2025-01-09 10:30:45,123 - trustgraph.gateway.service - INFO - Request processed
|
||||
```
|
||||
|
||||
Biçim öğeleri:
|
||||
Zaman damgası (milisaniyelerle birlikte ISO formatı)
|
||||
Kayıt yöneticisi adı (modül yolu)
|
||||
Kayıt düzeyi
|
||||
Mesaj
|
||||
|
||||
### İzleme için Loki Sorguları
|
||||
|
||||
Yaygın izleme sorguları:
|
||||
|
||||
```logql
|
||||
# Error rate by processor
|
||||
rate({severity="ERROR"}[5m]) by (processor)
|
||||
|
||||
# Top error-producing processors
|
||||
topk(5, count_over_time({severity="ERROR"}[1h]) by (processor))
|
||||
|
||||
# Recent errors with processor name
|
||||
{severity="ERROR"} | line_format "{{.processor}}: {{.message}}"
|
||||
|
||||
# All agent processors
|
||||
{processor=~".*agent.*"} |= "exception"
|
||||
|
||||
# Specific processor error count
|
||||
count_over_time({processor="config-svc", severity="ERROR"}[1h])
|
||||
```
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
**Hassas bilgileri asla kaydetmeyin** (şifreler, API anahtarları, kişisel veriler, token'lar)
|
||||
**Kayıt işleminden önce kullanıcı girişini temizleyin**
|
||||
**Hassas alanlar için yer tutucular kullanın**: `user_id=****1234`
|
||||
**Loki kimlik doğrulaması**: Güvenli dağıtımlar için `--loki-username` ve `--loki-password`'i kullanın
|
||||
**Güvenli taşıma**: Üretimde Loki URL'si için HTTPS kullanın: `https://loki.prod:3100/loki/api/v1/push`
|
||||
|
||||
## Bağımlılıklar
|
||||
|
||||
Merkezi günlük kaydı modülü şunları gerektirir:
|
||||
`python-logging-loki` - Loki entegrasyonu için (isteğe bağlı, eksikse sorunsuz bir şekilde çalışır)
|
||||
|
||||
Zaten `trustgraph-base/pyproject.toml` ve `requirements.txt` içinde bulunmaktadır.
|
||||
|
||||
## Geçiş Yolu
|
||||
|
||||
Mevcut kod için:
|
||||
|
||||
1. **AsyncProcessor kullanan hizmetler**: Herhangi bir değişiklik gerekmez, Loki desteği otomatik olarak sağlanır
|
||||
2. **AsyncProcessor kullanmayan hizmetler** (api-gateway, mcp-server): Zaten güncellenmiştir
|
||||
3. **CLI araçları**: Kapsam dışındadır - print() veya basit günlük kaydını kullanmaya devam edin
|
||||
|
||||
### print()'ten günlük kaydına:
|
||||
```python
|
||||
# Before
|
||||
print(f"Processing document {doc_id}")
|
||||
|
||||
# After
|
||||
logger = logging.getLogger(__name__)
|
||||
logger.info(f"Processing document {doc_id}")
|
||||
```
|
||||
|
||||
## Yapılandırma Özeti
|
||||
|
||||
| Argüman | Varsayılan Değer | Ortam Değişkeni | Açıklama |
|
||||
|----------|---------|---------------------|-------------|
|
||||
| `--log-level` | `INFO` | - | Konsol ve Loki log seviyesi |
|
||||
| `--loki-enabled` | `True` | - | Loki log kaydını etkinleştir |
|
||||
| `--loki-url` | `http://loki:3100/loki/api/v1/push` | `LOKI_URL` | Loki push endpoint'i |
|
||||
| `--loki-username` | `None` | `LOKI_USERNAME` | Loki kimlik doğrulama kullanıcı adı |
|
||||
| `--loki-password` | `None` | `LOKI_PASSWORD` | Loki kimlik doğrulama parolası |
|
||||
264
docs/tech-specs/tr/mcp-tool-arguments.tr.md
Normal file
264
docs/tech-specs/tr/mcp-tool-arguments.tr.md
Normal file
|
|
@ -0,0 +1,264 @@
|
|||
---
|
||||
layout: default
|
||||
title: "MCP Aracı Argümanları Belirtimi"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# MCP Aracı Argümanları Belirtimi
|
||||
|
||||
> **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ış
|
||||
**Özellik Adı**: MCP Aracı Argümanları Desteği
|
||||
**Yazar**: Claude Code Assistant
|
||||
**Tarih**: 2025-08-21
|
||||
**Durum**: Tamamlandı
|
||||
|
||||
### Yönetici Özeti
|
||||
|
||||
ReACT ajanlarının, argüman belirtimi desteğini MCP (Model Bağlam Protokolü) araç yapılandırmalarına ekleyerek,
|
||||
doğru şekilde tanımlanmış argümanlarla MCP araçlarını çağırmasına olanak sağlayın; bu, mevcut istem şablonu araçlarının
|
||||
nasıl çalıştığına benzer şekilde.
|
||||
|
||||
|
||||
### Problem Tanımı
|
||||
|
||||
|
||||
Şu anda, ReACT ajan çerçevesindeki MCP araçları, beklenen argümanlarını belirleyememektedir. `McpToolImpl.get_arguments()` metodu
|
||||
boş bir liste döndürmektedir, bu da LLM'lerin (Büyük Dil Modelleri) yalnızca araç adlarına ve açıklamalarına dayanarak
|
||||
doğru parametre yapısını tahmin etmesini gerektirmektedir. Bu, aşağıdaki sorunlara yol açmaktadır:
|
||||
Parametre tahminine bağlı olarak güvenilir olmayan araç çağrıları
|
||||
Yanlış argümanlar nedeniyle araçların başarısız olması durumunda kötü kullanıcı deneyimi
|
||||
Yürütmeden önce araç parametrelerinin doğrulanmaması
|
||||
Ajan istemlerindeki eksik parametre dokümantasyonu
|
||||
|
||||
### Hedefler
|
||||
|
||||
[ ] MCP araç yapılandırmalarının beklenen argümanları (ad, tür, açıklama) belirtmesine izin verin.
|
||||
[ ] Ajan yöneticisini, MCP araç argümanlarını istemler aracılığıyla LLM'lere sunacak şekilde güncelleyin.
|
||||
[ ] Mevcut MCP araç yapılandırmalarıyla geriye dönük uyumluluğu koruyun.
|
||||
[ ] İstem şablonu araçlarına benzer şekilde argüman doğrulamasını destekleyin.
|
||||
|
||||
### Kapsam Dışı Hedefler
|
||||
MCP sunucularından dinamik argüman keşfi (gelecek iyileştirme)
|
||||
Temel yapı dışındaki argüman türü doğrulaması
|
||||
Karmaşık argüman şemaları (iç içe nesneler, diziler)
|
||||
|
||||
## Arka Plan ve Bağlam
|
||||
|
||||
### Mevcut Durum
|
||||
MCP araçları, ReACT ajan sisteminde minimum düzeyde meta veriyle yapılandırılmaktadır:
|
||||
```json
|
||||
{
|
||||
"type": "mcp-tool",
|
||||
"name": "get_bank_balance",
|
||||
"description": "Get bank account balance",
|
||||
"mcp-tool": "get_bank_balance"
|
||||
}
|
||||
```
|
||||
|
||||
`McpToolImpl.get_arguments()` metodu `[]` değerini döndürür, bu nedenle LLM'ler, istemlerinde argüman rehberliği almaz.
|
||||
|
||||
### Sınırlamalar
|
||||
|
||||
1. **Argüman belirtimi yok**: MCP araçları, beklenen
|
||||
parametreleri tanımlayamaz.
|
||||
|
||||
2. **LLM parametre tahmini**: Ajanlar, parametreleri araç
|
||||
adlarından/açıklamalarından çıkarım yoluyla belirlemelidir.
|
||||
|
||||
3. **Eksik istem bilgisi**: Ajan istemleri, MCP araçları için argüman
|
||||
ayrıntılarını göstermez.
|
||||
|
||||
4. **Doğrulama yok**: Geçersiz parametreler, yalnızca MCP araç
|
||||
yürütme zamanında tespit edilir.
|
||||
|
||||
### İlgili Bileşenler
|
||||
**trustgraph-flow/agent/react/service.py**: Araç yapılandırması yükleme ve AgentManager oluşturma.
|
||||
**trustgraph-flow/agent/react/tools.py**: McpToolImpl uygulaması.
|
||||
**trustgraph-flow/agent/react/agent_manager.py**: Araç argümanlarıyla birlikte istem oluşturma.
|
||||
**trustgraph-cli**: MCP araç yönetimi için komut satırı araçları.
|
||||
**Workbench**: Ajan araç yapılandırması için harici kullanıcı arayüzü.
|
||||
|
||||
## Gereksinimler
|
||||
|
||||
### Fonksiyonel Gereksinimler
|
||||
|
||||
1. **MCP Araç Yapılandırma Argümanları**: MCP araç yapılandırmaları, isteğe bağlı bir `arguments` dizisiyle (ad, tür ve açıklama alanları) desteklemelidir.
|
||||
2. **Argüman Açıklaması**: `McpToolImpl.get_arguments()`, boş bir liste yerine yapılandırılmış argümanları döndürmelidir.
|
||||
3. **İstem Entegrasyonu**: Ajan istemleri, argümanlar belirtildiğinde MCP araç argümanı ayrıntılarını içermelidir.
|
||||
4. **Geriye Dönük Uyumluluk**: Argümanlar olmadan mevcut MCP araç yapılandırmaları çalışmaya devam etmelidir.
|
||||
5. **Komut Satırı Desteği**: Mevcut `tg-invoke-mcp-tool` komut satırı araçları, argümanları destekler (zaten uygulanmıştır).
|
||||
|
||||
### Fonksiyonel Olmayan Gereksinimler
|
||||
1. **Geriye Dönük Uyumluluk**: Mevcut MCP araç yapılandırmaları için hiçbir bozucu değişiklik olmamalıdır.
|
||||
2. **Performans**: Ajan istemi oluşturma üzerinde önemli bir performans etkisi olmamalıdır.
|
||||
3. **Tutarlılık**: Argüman işleme, istem şablonu araç kalıplarıyla eşleşmelidir.
|
||||
|
||||
### Kullanıcı Hikayeleri
|
||||
|
||||
1. Bir **ajan geliştirici** olarak, LLM'lerin doğru parametrelerle araçları çağırması için MCP araç argümanlarını yapılandırmada belirtmek istiyorum.
|
||||
2. Bir **workbench kullanıcısı** olarak, ajanların araçları doğru şekilde kullanması için MCP araç argümanlarını kullanıcı arayüzünde yapılandırmak istiyorum.
|
||||
3. Bir **ReACT ajanı içindeki bir LLM** olarak, doğru parametreler sağlamak için istemlerdeki araç argümanı özelliklerini görmek istiyorum.
|
||||
|
||||
## Tasarım
|
||||
|
||||
### Yüksek Seviyeli Mimari
|
||||
MCP araç yapılandırmasını, istem şablonu kalıbıyla eşleşecek şekilde aşağıdaki adımlarla genişletin:
|
||||
1. MCP araç yapılandırmalarına isteğe bağlı bir `arguments` dizisi ekleyin.
|
||||
2. `McpToolImpl`'nin yapılandırılmış argümanları kabul etmesini ve döndürmesini sağlayın.
|
||||
3. MCP araç argümanlarını işlemek için araç yapılandırması yüklemeyi güncelleyin.
|
||||
4. Ajan istemlerinin MCP araç argümanı bilgilerini içermesini sağlayın.
|
||||
|
||||
### Yapılandırma Şeması
|
||||
```json
|
||||
{
|
||||
"type": "mcp-tool",
|
||||
"name": "get_bank_balance",
|
||||
"description": "Get bank account balance",
|
||||
"mcp-tool": "get_bank_balance",
|
||||
"arguments": [
|
||||
{
|
||||
"name": "account_id",
|
||||
"type": "string",
|
||||
"description": "Bank account identifier"
|
||||
},
|
||||
{
|
||||
"name": "date",
|
||||
"type": "string",
|
||||
"description": "Date for balance query (optional, format: YYYY-MM-DD)"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Veri Akışı
|
||||
1. **Yapılandırma Yükleme**: `on_tools_config()` ile birlikte MCP aracı yapılandırması yüklenir.
|
||||
2. **Araç Oluşturma**: Argümanlar ayrıştırılır ve `McpToolImpl`'e oluşturucu aracılığıyla iletilir.
|
||||
3. **İstem Oluşturma**: `agent_manager.py`, LLM istemlerine dahil etmek için `tool.arguments`'i çağırır.
|
||||
4. **Araç Çağrısı**: LLM, MCP hizmetine değiştirilmeden parametreler sağlar.
|
||||
|
||||
### API Değişiklikleri
|
||||
Harici API değişiklikleri yok - bu tamamen içsel yapılandırma ve argüman işleme ile ilgilidir.
|
||||
|
||||
### Bileşen Detayları
|
||||
|
||||
#### Bileşen 1: service.py (Araç Yapılandırma Yükleme)
|
||||
**Amaç**: MCP araç yapılandırmalarını ayrıştırın ve araç örnekleri oluşturun.
|
||||
**Gerekli Değişiklikler**: MCP araçları için argüman ayrıştırması ekleyin (istem araçlarına benzer şekilde).
|
||||
**Yeni İşlevsellik**: MCP araç yapılandırmasından `arguments` dizisini çıkarın ve `Argument` nesneleri oluşturun.
|
||||
|
||||
#### Bileşen 2: tools.py (McpToolImpl)
|
||||
**Amaç**: MCP araç uygulaması sarmalayıcısı.
|
||||
**Gerekli Değişiklikler**: Oluşturucuda argümanları kabul edin ve bunları `get_arguments()`'den döndürün.
|
||||
**Yeni İşlevsellik**: Boş bir liste döndürmek yerine yapılandırılmış argümanları saklayın ve sergileyin.
|
||||
|
||||
#### Bileşen 3: Workbench (Harici Depo)
|
||||
**Amaç**: Aracılar için kullanıcı arayüzü yapılandırma.
|
||||
**Gerekli Değişiklikler**: MCP araçları için argüman belirtme kullanıcı arayüzü ekleyin.
|
||||
**Yeni İşlevsellik**: Kullanıcıların MCP araçları için argümanları eklemesine/düzenlemesine/kaldırmasına izin verin.
|
||||
|
||||
#### Bileşen 4: CLI Araçları
|
||||
**Amaç**: Komut satırı aracı yönetimi.
|
||||
**Gerekli Değişiklikler**: MCP araç oluşturma/güncelleme komutlarında argüman belirtimini destekleyin.
|
||||
**Yeni İşlevsellik**: Araç yapılandırma komutlarında argüman parametresini kabul edin.
|
||||
|
||||
## Uygulama Planı
|
||||
|
||||
### 1. Aşama: Temel Ajan Çerçevesi Değişiklikleri
|
||||
[ ] `McpToolImpl` oluşturucusunu `arguments` parametresini kabul edecek şekilde güncelleyin.
|
||||
[ ] `McpToolImpl.get_arguments()`'ın saklanan argümanları döndürmesi için değiştirin.
|
||||
[ ] `service.py` MCP araç yapılandırma ayrıştırmasını argümanları işleyecek şekilde değiştirin.
|
||||
[ ] MCP araç argüman işleme için birim testleri ekleyin.
|
||||
[ ] Ajan istemlerinin MCP araç argümanlarını içerdiğini doğrulayın.
|
||||
|
||||
### 2. Aşama: Harici Araç Desteği
|
||||
[ ] CLI araçlarını MCP araç argüman belirtimini destekleyecek şekilde güncelleyin.
|
||||
[ ] Kullanıcılar için argüman yapılandırma biçimini belgeleyin.
|
||||
[ ] Workbench kullanıcı arayüzünü MCP araç argüman yapılandırmasını destekleyecek şekilde güncelleyin.
|
||||
[ ] Örnekler ve belgeler ekleyin.
|
||||
|
||||
### Kod Değişiklikleri Özeti
|
||||
| Dosya | Değişiklik Türü | Açıklama |
|
||||
|------|------------|-------------|
|
||||
| `tools.py` | Değiştirildi | `tools.py`'ı argümanları kabul edecek ve saklayacak şekilde güncelleyin |
|
||||
| `service.py` | Değiştirildi | MCP araç yapılandırmasından argümanları ayrıştırın (satır 108-113) |
|
||||
| `test_react_processor.py` | Değiştirildi | MCP araç argümanları için testler ekleyin |
|
||||
| CLI araçları | Değiştirildi | Komutlarda argüman belirtimini destekleyin |
|
||||
| Workbench | Değiştirildi | MCP araç argüman yapılandırması için bir kullanıcı arayüzü ekleyin |
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
### Birim Testleri
|
||||
**MCP Araç Argüman Ayrıştırması**: `service.py`'ın MCP araç yapılandırmalarından argümanları doğru bir şekilde ayrıştırdığını test edin.
|
||||
**McpToolImpl Argümanları**: `get_arguments()`'ın yapılandırılmış argümanları döndürdüğünü ve boş bir liste döndürmediğini test edin.
|
||||
**Geriye Dönük Uyumluluk**: Argümanları olmayan MCP araçlarının çalışmaya devam ettiğini (boş bir liste döndürdüğünü) test edin.
|
||||
**Ajan İstem Oluşturma**: Ajan istemlerinin MCP araç argümanı ayrıntılarını içerdiğini test edin.
|
||||
|
||||
### Entegrasyon Testleri
|
||||
**Uçtan Uca Araç Çağrısı**: MCP araç argümanlarıyla test aracısı, araçları başarıyla çağırabilir.
|
||||
**Yapılandırma Yükleme**: MCP araç argümanlarıyla test yapılandırma yükleme döngüsünü tamamlayın.
|
||||
**Çoklu Bileşen**: Argümanların yapılandırmadan → araç oluşturmaya → istem oluşturmaya doğru doğru şekilde aktarılmasını test edin.
|
||||
|
||||
### Manuel Testler
|
||||
**Ajan Davranışı**: LLM'nin ReACT döngülerinde argüman bilgilerini alıp kullandığını manuel olarak doğrulayın.
|
||||
**CLI Entegrasyonu**: `tg-invoke-mcp-tool`'un yeni argüman yapılandırmalı MCP araçlarıyla çalıştığını test edin.
|
||||
**Çalışma Ortamı Entegrasyonu**: Kullanıcı arayüzünün MCP araç argümanı yapılandırmasını desteklediğini test edin.
|
||||
|
||||
## Göç ve Dağıtım
|
||||
|
||||
### Göç Stratejisi
|
||||
Göç gerektirmez - bu tamamen ek bir işlevsellik:
|
||||
``arguments`` içermeyen mevcut MCP araç yapılandırmaları, herhangi bir değişiklik olmadan çalışmaya devam eder.
|
||||
``McpToolImpl.get_arguments()``, eski araçlar için boş bir liste döndürür.
|
||||
Yeni yapılandırmalar isteğe bağlı olarak ``arguments`` dizisini içerebilir.
|
||||
|
||||
### Dağıtım Planı
|
||||
1. **1. Aşama**: Çekirdek ajan çerçevesi değişikliklerini geliştirme/hazırlık ortamına dağıtın.
|
||||
2. **2. Aşama**: CLI araç güncellemelerini ve belgeleri dağıtın.
|
||||
3. **3. Aşama**: Argüman yapılandırması için çalışma ortamı kullanıcı arayüzü güncellemelerini dağıtın.
|
||||
4. **4. Aşama**: İzleme ile üretim dağıtımı.
|
||||
|
||||
### Geri Alma Planı
|
||||
Çekirdek değişiklikler geriye dönük uyumludur - işlevsellik için geri alma işlemine gerek yoktur.
|
||||
Sorunlar ortaya çıkarsa, MCP araç yapılandırma yükleme mantığını geri alarak argüman ayrıştırmayı devre dışı bırakın.
|
||||
Çalışma ortamı ve CLI değişiklikleri bağımsızdır ve ayrı olarak geri alınabilir.
|
||||
|
||||
## Güvenlik Hususları
|
||||
**Yeni bir saldırı yüzeyi yok**: Argümanlar, yeni girdiler olmadan mevcut yapılandırma kaynaklarından ayrıştırılır.
|
||||
**Parametre doğrulama**: Argümanlar MCP araçlarına değiştirilmeden iletilir - doğrulama MCP araç seviyesinde kalır.
|
||||
**Yapılandırma bütünlüğü**: Argüman özellikleri araç yapılandırmasının bir parçasıdır - aynı güvenlik modeli uygulanır.
|
||||
|
||||
## Performans Etkisi
|
||||
**Minimum ek yük**: Argüman ayrıştırması yalnızca yapılandırma yükleme sırasında, her istekte değil gerçekleşir.
|
||||
**İstem boyutu artışı**: Ajan istemleri, MCP araç argümanı ayrıntılarını içerecek ve bu da token kullanımını biraz artıracaktır.
|
||||
**Bellek kullanımı**: Argüman özelliklerinin araç nesnelerinde depolanması için ihmal edilebilir bir artış.
|
||||
|
||||
## Belgeler
|
||||
|
||||
### Kullanıcı Belgeleri
|
||||
[ ] Argüman örnekleriyle MCP araç yapılandırma kılavuzunu güncelleyin.
|
||||
[ ] CLI araç yardım metnine argüman belirtimi ekleyin.
|
||||
[ ] Yaygın MCP araç argümanı kalıplarının örneklerini oluşturun.
|
||||
|
||||
### Geliştirici Belgeleri
|
||||
[ ] `McpToolImpl` sınıfının belgelerini güncelleyin.
|
||||
[ ] Argüman ayrıştırma mantığı için iç içe yorumlar ekleyin.
|
||||
[ ] Sistem mimarisinde argüman akışını belgeleyin.
|
||||
|
||||
## Açık Sorular
|
||||
1. **Argüman doğrulama**: Temel yapı kontrolünün ötesinde argüman türlerini/formatlarını doğrulamalı mıyız?
|
||||
2. **Dinamik keşif**: Gelecekte MCP sunucularından araç şemalarını otomatik olarak sorgulamak için bir özellik mi?
|
||||
|
||||
## Göz Önünde Bulundurulan Alternatifler
|
||||
1. **Dinamik MCP şema keşfi**: Çalışma zamanında araç argüman şemaları için MCP sunucularını sorgulayın - karmaşıklık ve güvenilirlik sorunları nedeniyle reddedildi.
|
||||
2. **Ayrı argüman kaydı**: MCP araç argümanlarını ayrı bir yapılandırma bölümünde saklayın - başlangıç uygulamasının basit kalması için istem şablonu yaklaşımıyla tutarlılık nedeniyle reddedildi.
|
||||
3. **Tip doğrulama**: Argümanlar için tam JSON şema doğrulaması - başlangıçta basit bir uygulama sağlamak için gelecekteki bir özellik olarak ertelendi.
|
||||
|
||||
## Referanslar
|
||||
[MCP Protokolü Özellikleri](https://github.com/modelcontextprotocol/spec)
|
||||
[İstem Şablonu Araç Uygulaması](./trustgraph-flow/trustgraph/agent/react/service.py#L114-129)
|
||||
[Mevcut MCP Araç Uygulaması](./trustgraph-flow/trustgraph/agent/react/tools.py#L58-86)
|
||||
|
||||
## Ek
|
||||
[Herhangi bir ek bilgi, diyagram veya örnek]
|
||||
562
docs/tech-specs/tr/mcp-tool-bearer-token.tr.md
Normal file
562
docs/tech-specs/tr/mcp-tool-bearer-token.tr.md
Normal file
|
|
@ -0,0 +1,562 @@
|
|||
---
|
||||
layout: default
|
||||
title: "MCP Aracı Taşıyıcı (Bearer) Token Doğrulama Özelliği Belirtimi"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# MCP Aracı Taşıyıcı (Bearer) Token Doğrulama Özelliği Belirtimi
|
||||
|
||||
> **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.
|
||||
|
||||
> **⚠️ ÖNEMLİ: YALNIZCA TEK-KİRACI (SINGLE-TENANT) ORTAMLAR İÇİN**
|
||||
>
|
||||
> Bu belirtim, MCP araçları için temel, hizmet seviyesinde bir doğrulama mekanizmasını açıklamaktadır. Bu, **TAMAMLANMIŞ** bir doğrulama çözümü değildir ve aşağıdaki durumlar için **UYGUN DEĞİL**:
|
||||
> - Çok kullanıcılı ortamlar
|
||||
> - Çok kiracılı (multi-tenant) dağıtımlar
|
||||
> - Federasyonlu doğrulama
|
||||
> - Kullanıcı bağlamı yayılımı
|
||||
> - Kullanıcı bazlı yetkilendirme
|
||||
>
|
||||
> Bu özellik, her MCP aracı için **tek bir statik token** sağlar ve bu token tüm kullanıcılar ve oturumlar arasında paylaşılır. Kullanıcı bazlı veya kiracı bazlı doğrulama gerekiyorsa, bu çözüm uygun değildir.
|
||||
|
||||
## Genel Bakış
|
||||
**Özellik Adı**: MCP Aracı Taşıyıcı (Bearer) Token Doğrulama Desteği
|
||||
**Yazar**: Claude Code Assistant
|
||||
**Tarih**: 2025-11-11
|
||||
**Durum**: Geliştirme Aşamasında
|
||||
|
||||
### Yönetici Özeti
|
||||
|
||||
MCP araçlarının, korumalı MCP sunucularıyla kimlik doğrulaması yapmak için isteğe bağlı taşıyıcı (bearer) token'lar belirtmesine olanak tanıyın. Bu, TrustGraph'ın, kimlik doğrulaması gerektiren sunucularda barındırılan MCP araçlarını, aracının veya araç çağrı arayüzlerinin değiştirilmesi olmadan güvenli bir şekilde çağırmasını sağlar.
|
||||
|
||||
**ÖNEMLİ**: Bu, tek kiracılı, hizmetten hizmete doğrulama senaryoları için tasarlanmış temel bir doğrulama mekanizmasıdır. Aşağıdaki durumlar için **UYGUN DEĞİL**:
|
||||
Farklı kullanıcıların farklı kimlik bilgilerine ihtiyaç duyduğu çok kullanıcılı ortamlar
|
||||
Kiracı başına izolasyon gerektiren çok kiracılı dağıtımlar
|
||||
Federasyonlu doğrulama senaryoları
|
||||
Kullanıcı seviyesinde doğrulama veya yetkilendirme
|
||||
Dinamik kimlik bilgisi yönetimi veya token yenileme
|
||||
|
||||
Bu özellik, her MCP aracı yapılandırması için statik, sistem genelinde bir taşıyıcı (bearer) token sağlar ve bu token, o aracın tüm kullanıcıları ve çağrıları tarafından paylaşılır.
|
||||
|
||||
### Sorun Tanımı
|
||||
|
||||
Şu anda, MCP araçları yalnızca herkese açık olarak erişilebilir MCP sunucularına bağlanabilir. Birçok üretim MCP dağıtımı, güvenlik için taşıyıcı (bearer) token'lar aracılığıyla kimlik doğrulaması gerektirir. Kimlik doğrulama desteği olmadan:
|
||||
MCP araçları, güvenli MCP sunucularına bağlanamaz
|
||||
Kullanıcılar ya MCP sunucularını herkese açık hale getirmeli ya da ters vekil (reverse proxy) uygulamalıdır
|
||||
MCP bağlantılarına kimlik bilgilerini iletmenin standart bir yolu yoktur
|
||||
MCP uç noktalarında güvenlik en iyi uygulamaları uygulanamaz
|
||||
|
||||
### Hedefler
|
||||
|
||||
[ ] MCP araç yapılandırmalarının isteğe bağlı `auth-token` parametresini belirtmesine izin verin
|
||||
[ ] MCP araç hizmetini, MCP sunucularına bağlanırken taşıyıcı (bearer) token'ları kullanacak şekilde güncelleyin
|
||||
[ ] CLI araçlarını, kimlik doğrulama token'larını ayarlama/görüntüleme özelliğini destekleyecek şekilde güncelleyin
|
||||
[ ] Kimlik doğrulaması olmayan MCP yapılandırmalarıyla geriye dönük uyumluluğu koruyun
|
||||
[ ] Token depolama için güvenlik hususlarını belgeleyin
|
||||
|
||||
### Hedef Dışı Kalanlar
|
||||
Dinamik token yenileme veya OAuth akışları (yalnızca statik token'lar)
|
||||
Depolanmış token'ların şifrelenmesi (yapılandırma sistemi güvenliği kapsam dışındadır)
|
||||
Alternatif doğrulama yöntemleri (Temel kimlik doğrulama, API anahtarları, vb.)
|
||||
Token doğrulama veya son kullanma kontrolü
|
||||
**Kullanıcı başına doğrulama**: Bu özellik, kullanıcıya özel kimlik bilgilerini desteklemez
|
||||
**Kiracı izolasyonu**: Bu özellik, kiracı başına token yönetimi sağlamaz
|
||||
**Federasyonlu doğrulama**: Bu özellik, kimlik sağlayıcılarıyla (SSO, OAuth, SAML, vb.) entegre olmaz
|
||||
**Bağlama duyarlı doğrulama**: Token'lar, kullanıcı bağlamına veya oturuma göre iletilmez
|
||||
|
||||
## Arka Plan ve Bağlam
|
||||
|
||||
### Mevcut Durum
|
||||
MCP araç yapılandırmaları, `mcp` yapılandırma grubunda aşağıdaki yapıya sahip olarak saklanır:
|
||||
```json
|
||||
{
|
||||
"remote-name": "tool_name",
|
||||
"url": "http://mcp-server:3000/api"
|
||||
}
|
||||
```
|
||||
|
||||
MCP aracı hizmeti, `streamablehttp_client(url)` kullanarak sunuculara bağlanır ve herhangi bir kimlik doğrulama başlığı kullanmaz.
|
||||
|
||||
### Sınırlamalar
|
||||
|
||||
**Mevcut Sistem Sınırlamaları:**
|
||||
1. **Kimlik doğrulama desteği yok:** Güvenli MCP sunucularına bağlanılamaz.
|
||||
2. **Güvenlik açığı:** MCP sunucuları, yalnızca ağ seviyesinde güvenlik kullanılarak genel olarak erişilebilir olmalıdır.
|
||||
3. **Üretim dağıtım sorunları:** API uç noktaları için güvenlik en iyi uygulamalarını takip edilemez.
|
||||
|
||||
**Bu Çözümün Sınırlamaları:**
|
||||
1. **Yalnızca tek kiracı:** Her MCP aracı için tek bir statik belirteç, tüm kullanıcılar arasında paylaşılır.
|
||||
2. **Kullanıcı başına kimlik bilgileri yok:** Farklı kullanıcılar olarak kimlik doğrulaması yapılamaz veya kullanıcı bağlamı geçirilemez.
|
||||
3. **Çok kiracılı destek yok:** Kimlik bilgilerini kiracı veya kuruluş başına izole etmek mümkün değildir.
|
||||
4. **Yalnızca statik belirteçler:** Belirteç yenileme, döndürme veya son kullanma süresi yönetimi desteği yoktur.
|
||||
5. **Hizmet seviyesi kimlik doğrulaması:** Bireysel kullanıcılar yerine TrustGraph hizmetini doğrular.
|
||||
6. **Paylaşılan güvenlik bağlamı:** Bir MCP aracının tüm çağrıları aynı kimlik bilgisini kullanır.
|
||||
|
||||
### Kullanım Alanı Uygunluğu
|
||||
|
||||
**✅ Uygun Kullanım Alanları:**
|
||||
Tek kiracılı TrustGraph dağıtımları
|
||||
Hizmetten hizmete kimlik doğrulama (TrustGraph → MCP Sunucusu)
|
||||
Geliştirme ve test ortamları
|
||||
TrustGraph sistemi tarafından erişilen dahili MCP araçları
|
||||
Tüm kullanıcıların aynı MCP aracı erişim düzeyini paylaştığı senaryolar
|
||||
Statik, uzun ömürlü hizmet kimlik bilgileri
|
||||
|
||||
**❌ Uygun Olmayan Kullanım Alanları:**
|
||||
Kullanıcı başına kimlik doğrulama gerektiren çok kullanıcılı sistemler
|
||||
Kiracı izolasyonu gereksinimleri olan çok kiracılı SaaS dağıtımları
|
||||
Federasyon kimlik doğrulama senaryoları (SSO, OAuth, SAML)
|
||||
MCP sunucularına kullanıcı bağlamının iletilmesi gereken sistemler
|
||||
Dinamik belirteç yenileme veya kısa ömürlü belirteçler gerektiren ortamlar
|
||||
Farklı kullanıcıların farklı izin düzeylerine ihtiyaç duyduğu uygulamalar
|
||||
Kullanıcı seviyesinde denetim izleri için uyumluluk gereksinimleri
|
||||
|
||||
**Örnek Uygun Senaryo:**
|
||||
Tüm çalışanların aynı dahili MCP aracını (örneğin, şirket veritabanı sorgusu) kullandığı tek organizasyonlu bir TrustGraph dağıtımı. MCP sunucusunun harici erişimi önlemek için kimlik doğrulama gerektirmesi, ancak tüm dahili kullanıcıların aynı erişim düzeyine sahip olması.
|
||||
|
||||
**Örnek Uygun Olmayan Senaryo:**
|
||||
Kiracı A ve Kiracı B'nin her birinin ayrı kimlik bilgileriyle kendi izole MCP sunucularına erişmesi gereken çok kiracılı bir TrustGraph SaaS platformu. Bu özellik, kiracı başına belirteç yönetimi DEĞİLDİR.
|
||||
|
||||
### İlgili Bileşenler
|
||||
**trustgraph-flow/trustgraph/agent/mcp_tool/service.py**: MCP aracı çağrı hizmeti
|
||||
**trustgraph-cli/trustgraph/cli/set_mcp_tool.py**: MCP yapılandırmalarını oluşturmak/güncellemek için CLI aracı
|
||||
**trustgraph-cli/trustgraph/cli/show_mcp_tools.py**: MCP yapılandırmalarını görüntülemek için CLI aracı
|
||||
**MCP Python SDK**: `streamablehttp_client` from `mcp.client.streamable_http`
|
||||
|
||||
## Gereksinimler
|
||||
|
||||
### Fonksiyonel Gereksinimler
|
||||
|
||||
1. **MCP Yapılandırma Kimlik Doğrulama Belirteci**: MCP aracı yapılandırmaları, isteğe bağlı bir `auth-token` alanı DESTEKLEMELİDİR.
|
||||
2. **Bearer Belirteç Kullanımı**: MCP aracı hizmeti, kimlik doğrulama belirteci yapılandırıldığında `Authorization: Bearer {token}` başlığını GÖNDERMELİDİR.
|
||||
3. **CLI Desteği**: `tg-set-mcp-tool`, isteğe bağlı bir `--auth-token` parametresi KABUL ETMELİDİR.
|
||||
4. **Belirteç Görüntüleme**: `tg-show-mcp-tools`, kimlik doğrulama belirtecinin yapılandırıldığını GÖSTERMELİDİR (güvenlik için gizlenmiş).
|
||||
5. **Geriye Dönük Uyumluluk**: Kimlik doğrulama belirteci olmayan mevcut MCP aracı yapılandırmaları çalışmaya DEVAM ETMELİDİR.
|
||||
|
||||
### Fonksiyonel Olmayan Gereksinimler
|
||||
1. **Geriye Dönük Uyumluluk**: Mevcut MCP aracı yapılandırmaları için hiçbir bozucu değişiklik olmamalıdır.
|
||||
2. **Performans**: MCP aracı çağrısı üzerinde önemli bir performans etkisi olmamalıdır.
|
||||
3. **Güvenlik**: Belirteçler yapılandırmada saklanır (güvenlik etkilerini belgeleyin).
|
||||
|
||||
### Kullanıcı Hikayeleri
|
||||
|
||||
1. Bir **DevOps mühendisi** olarak, MCP sunucusu uç noktalarını güvence altına almak için MCP araçları için taşıyıcı belirteçleri yapılandırmak istiyorum.
|
||||
2. Bir **CLI kullanıcısı** olarak, korumalı sunuculara bağlanabilmem için MCP araçları oluştururken kimlik doğrulama belirteçleri ayarlamak istiyorum.
|
||||
3. Bir **sistem yöneticisi** olarak, hangi MCP araçlarının kimlik doğrulamasının yapılandırıldığını görmek istiyorum, böylece güvenlik ayarlarını denetleyebilirim.
|
||||
|
||||
## Tasarım
|
||||
|
||||
### Yüksek Seviyeli Mimari
|
||||
Taşıyıcı belirteç kimlik doğrulaması desteği için MCP aracı yapılandırmasını ve hizmetini genişletin:
|
||||
1. MCP aracı yapılandırma şemasına isteğe bağlı bir `auth-token` alanı ekleyin.
|
||||
2. Kimlik doğrulama belirteci yapılandırıldığında, MCP aracı hizmetinin kimlik doğrulama belirteci okuyup HTTP istemcisine iletmesini sağlayın.
|
||||
3. Kimlik doğrulama belirteçleri ayarlamak ve görüntülemek için CLI araçlarını güncelleyin.
|
||||
4. Güvenlik hususlarını ve en iyi uygulamaları belgeleyin.
|
||||
|
||||
### Yapılandırma Şeması
|
||||
|
||||
**Mevcut Şema**:
|
||||
```json
|
||||
{
|
||||
"remote-name": "tool_name",
|
||||
"url": "http://mcp-server:3000/api"
|
||||
}
|
||||
```
|
||||
|
||||
**Yeni Şema** (isteğe bağlı kimlik doğrulama jetonu ile):
|
||||
```json
|
||||
{
|
||||
"remote-name": "tool_name",
|
||||
"url": "http://mcp-server:3000/api",
|
||||
"auth-token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
}
|
||||
```
|
||||
|
||||
**Alan Açıklamaları**:
|
||||
`remote-name` (isteğe bağlı): MCP sunucusu tarafından kullanılan isim (varsayılan olarak yapılandırma anahtarı)
|
||||
`url` (gerekli): MCP sunucusu uç noktası URL'si
|
||||
`auth-token` (isteğe bağlı): Kimlik doğrulama için kullanılan taşıyıcı belirteci
|
||||
|
||||
### Veri Akışı
|
||||
|
||||
1. **Yapılandırma Depolama**: Kullanıcı `tg-set-mcp-tool --id my-tool --tool-url http://server/api --auth-token xyz123`'ı çalıştırır
|
||||
2. **Yapılandırma Yükleme**: MCP aracı hizmeti, `on_mcp_config()` geri çağırması aracılığıyla yapılandırma güncellemelerini alır
|
||||
3. **Araç Çağrısı**: Araç çağrıldığında:
|
||||
Hizmet, yapılandırmadan `auth-token`'ı okur (varsa)
|
||||
Başlıklar sözlüğünü oluşturur: `{"Authorization": "Bearer {token}"}`
|
||||
Başlıkları `streamablehttp_client(url, headers=headers)`'a iletir
|
||||
MCP sunucusu belirteci doğrular ve isteği işler
|
||||
|
||||
### API Değişiklikleri
|
||||
Harici API değişiklikleri yok - yalnızca yapılandırma şeması uzantısı.
|
||||
|
||||
### Bileşen Detayları
|
||||
|
||||
#### Bileşen 1: service.py (MCP Aracı Hizmeti)
|
||||
**Dosya**: `trustgraph-flow/trustgraph/agent/mcp_tool/service.py`
|
||||
|
||||
**Amaç**: Uzak sunuculardaki MCP araçlarını çağırmak
|
||||
|
||||
**Gerekli Değişiklikler** (`invoke_tool()` yönteminde):
|
||||
1. `auth-token`'ın `self.mcp_services[name]` yapılandırmasında olup olmadığını kontrol edin
|
||||
2. Belirteç varsa, Authorization başlığıyla başlıklar sözlüğünü oluşturun
|
||||
3. Başlıkları `streamablehttp_client(url, headers=headers)`'a iletin
|
||||
|
||||
**Mevcut Kod** (42-89 satırları):
|
||||
```python
|
||||
async def invoke_tool(self, name, parameters):
|
||||
try:
|
||||
if name not in self.mcp_services:
|
||||
raise RuntimeError(f"MCP service {name} not known")
|
||||
if "url" not in self.mcp_services[name]:
|
||||
raise RuntimeError(f"MCP service {name} URL not defined")
|
||||
|
||||
url = self.mcp_services[name]["url"]
|
||||
|
||||
if "remote-name" in self.mcp_services[name]:
|
||||
remote_name = self.mcp_services[name]["remote-name"]
|
||||
else:
|
||||
remote_name = name
|
||||
|
||||
logger.info(f"Invoking {remote_name} at {url}")
|
||||
|
||||
# Connect to a streamable HTTP server
|
||||
async with streamablehttp_client(url) as (
|
||||
read_stream,
|
||||
write_stream,
|
||||
_,
|
||||
):
|
||||
# ... rest of method
|
||||
```
|
||||
|
||||
**Değiştirilmiş Kod:**
|
||||
```python
|
||||
async def invoke_tool(self, name, parameters):
|
||||
try:
|
||||
if name not in self.mcp_services:
|
||||
raise RuntimeError(f"MCP service {name} not known")
|
||||
if "url" not in self.mcp_services[name]:
|
||||
raise RuntimeError(f"MCP service {name} URL not defined")
|
||||
|
||||
url = self.mcp_services[name]["url"]
|
||||
|
||||
if "remote-name" in self.mcp_services[name]:
|
||||
remote_name = self.mcp_services[name]["remote-name"]
|
||||
else:
|
||||
remote_name = name
|
||||
|
||||
# Build headers with optional bearer token
|
||||
headers = {}
|
||||
if "auth-token" in self.mcp_services[name]:
|
||||
token = self.mcp_services[name]["auth-token"]
|
||||
headers["Authorization"] = f"Bearer {token}"
|
||||
|
||||
logger.info(f"Invoking {remote_name} at {url}")
|
||||
|
||||
# Connect to a streamable HTTP server with headers
|
||||
async with streamablehttp_client(url, headers=headers) as (
|
||||
read_stream,
|
||||
write_stream,
|
||||
_,
|
||||
):
|
||||
# ... rest of method (unchanged)
|
||||
```
|
||||
|
||||
#### Bileşen 2: set_mcp_tool.py (CLI Yapılandırma Aracı)
|
||||
**Dosya**: `trustgraph-cli/trustgraph/cli/set_mcp_tool.py`
|
||||
|
||||
**Amaç**: MCP aracı yapılandırmalarını oluşturma/güncelleme
|
||||
|
||||
**Gerekli Değişiklikler**:
|
||||
1. `--auth-token` isteğe bağlı argümanı argparse'a ekleyin
|
||||
2. Sağlandığında, `auth-token`'yi yapılandırma JSON'una dahil edin
|
||||
|
||||
**Mevcut Argümanlar**:
|
||||
`--id` (gerekli): MCP aracı tanımlayıcısı
|
||||
`--remote-name` (isteğe bağlı): Uzak MCP aracı adı
|
||||
`--tool-url` (gerekli): MCP aracı URL uç noktası
|
||||
`-u, --api-url` (isteğe bağlı): TrustGraph API URL'si
|
||||
|
||||
**Yeni Argüman**:
|
||||
`--auth-token` (isteğe bağlı): Kimlik doğrulama için taşıyıcı belirteci
|
||||
|
||||
**Değiştirilmiş Yapılandırma Oluşturma**:
|
||||
```python
|
||||
# Build configuration object
|
||||
config = {
|
||||
"url": args.tool_url,
|
||||
}
|
||||
|
||||
if args.remote_name:
|
||||
config["remote-name"] = args.remote_name
|
||||
|
||||
if args.auth_token:
|
||||
config["auth-token"] = args.auth_token
|
||||
|
||||
# Store configuration
|
||||
api.config().put([
|
||||
ConfigValue(type="mcp", key=args.id, value=json.dumps(config))
|
||||
])
|
||||
```
|
||||
|
||||
#### Bileşen 3: show_mcp_tools.py (CLI Görüntüleme Aracı)
|
||||
**Dosya**: `trustgraph-cli/trustgraph/cli/show_mcp_tools.py`
|
||||
|
||||
**Amaç**: MCP araç yapılandırmalarını görüntülemek
|
||||
|
||||
**Gerekli Değişiklikler**:
|
||||
1. Çıktı tablosuna "Auth" sütununu ekleyin
|
||||
2. "auth-token" varlığına bağlı olarak "Evet" veya "Hayır" görüntüleyin
|
||||
3. Gerçek token değerini görüntülemeyin (güvenlik)
|
||||
|
||||
**Mevcut Çıktı**:
|
||||
```
|
||||
ID Remote Name URL
|
||||
---------- ------------- ------------------------
|
||||
my-tool my-tool http://server:3000/api
|
||||
```
|
||||
|
||||
**Yeni Çıktı**:
|
||||
```
|
||||
ID Remote Name URL Auth
|
||||
---------- ------------- ------------------------ ------
|
||||
my-tool my-tool http://server:3000/api Yes
|
||||
other-tool other-tool http://other:3000/api No
|
||||
```
|
||||
|
||||
#### Bileşen 4: Belgeler
|
||||
**Dosya**: `docs/cli/tg-set-mcp-tool.md`
|
||||
|
||||
**Gerekli Değişiklikler**:
|
||||
1. Yeni `--auth-token` parametresini belgeleyin
|
||||
2. Kimlik doğrulama ile örnek kullanım sağlayın
|
||||
3. Güvenlik hususlarını belgeleyin
|
||||
|
||||
## Uygulama Planı
|
||||
|
||||
### Aşama 1: Teknik Özellikleri Oluşturma
|
||||
[x] Tüm değişiklikleri belgeleyen kapsamlı bir teknik özellik yazın
|
||||
|
||||
### Aşama 2: MCP Araç Hizmetini Güncelleme
|
||||
[ ] `service.py` içindeki `invoke_tool()`'ı, auth-token'ı yapılandırmadan okumak için değiştirin
|
||||
[ ] Başlıklar sözlüğünü oluşturun ve `streamablehttp_client`'a iletin
|
||||
[ ] Kimliği doğrulanmış bir MCP sunucusuyla test edin
|
||||
|
||||
### Aşama 3: CLI Araçlarını Güncelleme
|
||||
[ ] `set_mcp_tool.py`'e `--auth-token` argümanını ekleyin
|
||||
[ ] auth-token'ı yapılandırma JSON'unda dahil edin
|
||||
[ ] `show_mcp_tools.py` çıktısına "Auth" sütununu ekleyin
|
||||
[ ] CLI araç değişikliklerini test edin
|
||||
|
||||
### Aşama 4: Belgeleri Güncelleme
|
||||
[ ] `tg-set-mcp-tool.md` içindeki `--auth-token` parametresini belgeleyin
|
||||
[ ] Güvenlik hususları bölümünü ekleyin
|
||||
[ ] Örnek kullanım sağlayın
|
||||
|
||||
### Aşama 5: Test
|
||||
[ ] MCP aracının auth-token ile başarıyla bağlandığını test edin
|
||||
[ ] Geriye dönük uyumluluğu test edin (auth-token olmadan çalışan araçlar)
|
||||
[ ] CLI araçlarının auth-token'ı doğru şekilde kabul ettiğini ve depoladığını test edin
|
||||
[ ] "show" komutunun auth durumunu doğru şekilde gösterdiğini test edin
|
||||
|
||||
### Kod Değişiklikleri Özeti
|
||||
| Dosya | Değişiklik Türü | Satırlar | Açıklama |
|
||||
|------|------------|-------|-------------|
|
||||
| `service.py` | Değiştirildi | ~52-66 | auth-token okuma ve başlık oluşturma ekleyin |
|
||||
| `set_mcp_tool.py` | Değiştirildi | ~30-60 | --auth-token argümanı ve yapılandırma depolama ekleyin |
|
||||
| `show_mcp_tools.py` | Değiştirildi | ~40-70 | Görüntüleme için "Auth" sütununu ekleyin |
|
||||
| `tg-set-mcp-tool.md` | Değiştirildi | Çeşitli | Yeni parametreyi belgeleyin |
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
### Birim Testleri
|
||||
**Auth Token Okuma**: `invoke_tool()`'ın auth-token'ı yapılandırmadan doğru şekilde okuduğunu test edin
|
||||
**Başlık Oluşturma**: Authorization başlığının Bearer öneki ile doğru şekilde oluşturulduğunu test edin
|
||||
**Geriye Dönük Uyumluluk**: auth-token olmadan çalışan araçların değişmeden çalıştığını test edin
|
||||
**CLI Argümanı Ayrıştırma**: `--auth-token` argümanının doğru şekilde ayrıştırıldığını test edin
|
||||
|
||||
### Entegrasyon Testleri
|
||||
**Kimliği Doğrulanmış Bağlantı**: MCP araç hizmetinin kimliği doğrulanmış bir sunucuya bağlandığını test edin
|
||||
**Uçtan Uca**: CLI → yapılandırma depolama → auth token ile hizmet çağrısını test edin
|
||||
**Token Gerekli Değil**: Kimliği doğrulanmamış bir sunucuya bağlantının hala çalıştığını test edin
|
||||
|
||||
### Manuel Testler
|
||||
**Gerçek MCP Sunucusu**: bearer token kimlik doğrulaması gerektiren gerçek bir MCP sunucusuyla test edin
|
||||
**CLI İş Akışı**: Tam iş akışını test edin: aracı auth ile yapılandır → aracı çağır → başarıyı doğrulayın
|
||||
**Görüntü Maskeleme**: auth durumunun gösterildiğini ancak token değerinin görünmediğini doğrulayın
|
||||
|
||||
## Göç ve Dağıtım
|
||||
|
||||
### Göç Stratejisi
|
||||
Göç gerektirmez - bu tamamen ek bir işlevsellik:
|
||||
`auth-token` içermeyen mevcut MCP araç yapılandırmaları çalışmaya devam eder
|
||||
Yeni yapılandırmalar isteğe bağlı olarak `auth-token` alanını içerebilir
|
||||
CLI araçları `--auth-token` parametresini kabul eder, ancak gerektirmez
|
||||
|
||||
### Dağıtım Planı
|
||||
1. **Aşama 1**: Temel hizmet değişikliklerini geliştirme/hazırlık ortamına dağıtın
|
||||
2. **Aşama 2**: CLI araç güncellemelerini dağıtın
|
||||
3. **Aşama 3**: Belgeleri güncelleyin
|
||||
4. **Aşama 4**: İzleme ile üretim dağıtımı
|
||||
|
||||
### Geri Alma Planı
|
||||
Temel değişiklikler geriye dönük uyumludur - mevcut araçlar etkilenmez
|
||||
Sorunlar ortaya çıkarsa, auth-token işleme, başlık oluşturma mantığını kaldırarak devre dışı bırakılabilir
|
||||
CLI değişiklikleri bağımsızdır ve ayrı olarak geri alınabilir
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
### ⚠️ Kritik Sınırlama: Yalnızca Tek Kiracılı Kimlik Doğrulama
|
||||
|
||||
**Bu kimlik doğrulama mekanizması, çok kullanıcılı veya çok kiracılı ortamlar için UYGUN DEĞİLDİR.**
|
||||
|
||||
**Paylaşılan kimlik bilgiler**: Tüm kullanıcılar ve çağrılar, her MCP aracı için aynı token'ı paylaşır
|
||||
**Kullanıcı bağlamı yok**: MCP sunucusu, farklı TrustGraph kullanıcıları arasında ayrım yapamaz
|
||||
**Kiracı yalıtımı yok**: Tüm kiracılar, her MCP aracı için aynı kimlik bilgilerini paylaşır
|
||||
**Denetim izi sınırlaması**: MCP sunucusu, aynı kimlik bilgilerinden gelen tüm istekleri günlüğe kaydeder
|
||||
**İzin kapsamı**: Farklı kullanıcılara farklı izin seviyeleri uygulanamaz
|
||||
|
||||
**Bu özelliği KULLANMAYIN eğer:**
|
||||
TrustGraph dağıtımınız birden fazla kuruluşu (çok kiracılı) hizmet veriyorsa
|
||||
Hangi kullanıcının hangi MCP aracına eriştiğini izlemeniz gerekiyorsa
|
||||
Farklı kullanıcıların farklı izin seviyelerine ihtiyacı varsa
|
||||
Kullanıcı düzeyinde denetim gereksinimlerine uymanız gerekiyorsa
|
||||
MCP sunucunuz kullanıcı başına hız sınırlamaları veya kotaları uyguluyorsa
|
||||
|
||||
**Çok kullanıcılı/çok kiracılı senaryolar için alternatif çözümler:**
|
||||
Özel başlıklar aracılığıyla kullanıcı bağlamı yayılımını uygulayın
|
||||
Her kiracı için ayrı TrustGraph örnekleri dağıtın
|
||||
Ağ seviyesinde izolasyon kullanın (VPC'ler, hizmet ağları)
|
||||
Her kullanıcı için kimlik doğrulamayı yöneten bir ara katman uygulayın
|
||||
|
||||
### Token Depolama
|
||||
**Risk**: Kimlik doğrulama jetonları yapılandırma sisteminde düz metin olarak saklanır
|
||||
|
||||
**Giderilmesi Gereken Durum:**
|
||||
Jetonların şifrelenmeden saklandığını belgeleyin
|
||||
Mümkün olduğunda kısa ömürlü jetonlar kullanılması önerin
|
||||
Yapılandırma depolaması için uygun erişim kontrolü kullanılması önerin
|
||||
Şifrelenmiş jeton depolama için gelecekteki bir iyileştirmeyi düşünün
|
||||
|
||||
### Jetonun Açığa Çıkarılması
|
||||
**Risk**: Jetonlar günlüklerde veya CLI çıktısında açığa çıkabilir
|
||||
|
||||
**Giderilmesi Gereken Durum:**
|
||||
Jeton değerlerini kaydetmeyin (sadece "kimlik doğrulama yapılandırıldı: evet/hayır" kaydını tutun)
|
||||
CLI göster komutu yalnızca maskelenmiş durumu gösterir, gerçek jetonu göstermez
|
||||
Jetonları hata mesajlarında dahil etmeyin
|
||||
|
||||
### Ağ Güvenliği
|
||||
**Risk**: Jetonlar şifrelenmemiş bağlantılar üzerinden iletilir
|
||||
|
||||
**Giderilmesi Gereken Durum:**
|
||||
MCP sunucuları için HTTPS URL'lerinin kullanılması önerisi belgelendirilmelidir
|
||||
HTTP ile düz metin iletim riskine ilişkin kullanıcılara uyarı verilmelidir
|
||||
|
||||
### Yapılandırma Erişimi
|
||||
**Risk**: Yapılandırma sistemine yetkisiz erişim, jetonları açığa çıkarır
|
||||
|
||||
**Giderilmesi Gereken Durum:**
|
||||
Yapılandırma sistemi erişiminin güvenliğinin önemini belgeleyin
|
||||
Yapılandırma erişimi için en az ayrıcalık ilkesi önerin
|
||||
Yapılandırma değişiklikleri için denetim günlüğü almayı düşünün (gelecekteki iyileştirme)
|
||||
|
||||
### Çok Kullanıcılı Ortamlar
|
||||
**Risk**: Çok kullanıcılı dağıtımlarda, tüm kullanıcılar aynı MCP kimlik bilgilerini paylaşır
|
||||
|
||||
**Riskin Anlaşılması:**
|
||||
Kullanıcı A ve Kullanıcı B, bir MCP aracını kullanırken aynı jetonu kullanır
|
||||
MCP sunucusu, farklı TrustGraph kullanıcıları arasında ayrım yapamaz
|
||||
Kullanıcı başına izinleri veya hız sınırlamalarını uygulama imkanı yoktur
|
||||
MCP sunucusundaki denetim günlükleri, aynı kimlik bilgilerinden gelen tüm istekleri gösterir
|
||||
Bir kullanıcının oturumu tehlikeye girerse, saldırganın tüm kullanıcılar kadar aynı MCP erişimi vardır
|
||||
|
||||
**Bu bir hata DEĞİLDİR - bu tasarımın temel bir sınırlamasıdır.**
|
||||
|
||||
## Performans Etkisi
|
||||
**Minimum ek yük**: Başlık oluşturma, ihmal edilebilir bir işlem süresi ekler
|
||||
**Ağ etkisi**: Ek HTTP başlığı, istek başına yaklaşık 50-200 bayt ekler
|
||||
**Bellek kullanımı**: Yapılandırmada jeton dizesini depolamak için ihmal edilebilir bir artış
|
||||
|
||||
## Belgeler
|
||||
|
||||
### Kullanıcı Belgeleri
|
||||
[ ] `tg-set-mcp-tool.md`'ı `--auth-token` parametresiyle güncelleyin
|
||||
[ ] Güvenlik hususları bölümü ekleyin
|
||||
[ ] Bir örnek kullanım senaryosuyla birlikte taşıyıcı jetonu sağlayın
|
||||
[ ] Jeton depolama etkilerini belgeleyin
|
||||
|
||||
### Geliştirici Belgeleri
|
||||
[ ] `service.py` içindeki kimlik doğrulama jetonu işleme için satır içi yorumlar ekleyin
|
||||
[ ] Başlık oluşturma mantığını belgeleyin
|
||||
[ ] MCP aracı yapılandırma şeması belgelerini güncelleyin
|
||||
|
||||
## Açık Sorular
|
||||
1. **Jeton şifreleme**: Yapılandırma sisteminde şifrelenmiş jeton depolamayı uygulamalı mıyız?
|
||||
2. **Jeton yenileme**: OAuth yenileme akışları veya jeton rotasyonu için gelecekteki destek?
|
||||
3. **Alternatif kimlik doğrulama yöntemleri**: Temel kimlik doğrulama, API anahtarları veya diğer yöntemleri desteklemeli miyiz?
|
||||
|
||||
## Değerlendirilen Alternatifler
|
||||
|
||||
1. **Jetonlar için ortam değişkenleri**: Jetonları yapılandırma yerine ortam değişkenlerinde saklayın
|
||||
**Reddedildi**: Dağıtımı ve yapılandırma yönetimini karmaşıklaştırır
|
||||
|
||||
2. **Ayrı gizli anahtar deposu**: Özel bir gizli anahtar yönetim sistemi kullanın
|
||||
**Erteleme**: Başlangıç uygulaması kapsamı dışındadır, gelecekteki bir iyileştirme olarak düşünün
|
||||
|
||||
3. **Çoklu kimlik doğrulama yöntemleri**: Temel, API anahtarı, OAuth vb. destekleyin
|
||||
**Reddedildi**: Taşıyıcı jetonlar çoğu kullanım durumunu kapsar, başlangıç uygulamasını basit tutun
|
||||
|
||||
4. **Şifrelenmiş jeton depolama**: Jetonları yapılandırma sisteminde şifreleyin
|
||||
**Erteleme**: Yapılandırma sistemi güvenliği daha geniş bir endişedir, gelecekteki çalışmalara bırakın
|
||||
|
||||
5. **Her çağrı için jetonlar**: Jetonların çağrı zamanında geçirilmesine izin verin
|
||||
**Reddedildi**: Endişe ayrımını ihlal eder, aracının kimlik bilgilerini işlemesi gerekmez
|
||||
|
||||
## Referanslar
|
||||
[MCP Protokolü Özellikleri](https://github.com/modelcontextprotocol/spec)
|
||||
[HTTP Taşıyıcı Kimlik Doğrulaması (RFC 6750)](https://tools.ietf.org/html/rfc6750)
|
||||
[Mevcut MCP Aracı Hizmeti](../trustgraph-flow/trustgraph/agent/mcp_tool/service.py)
|
||||
[MCP Aracı Argümanları Özellikleri](./mcp-tool-arguments.md)
|
||||
|
||||
## Ek
|
||||
|
||||
### Örnek Kullanım
|
||||
|
||||
**Kimlik doğrulama ile MCP aracının yapılandırılması:**
|
||||
```bash
|
||||
tg-set-mcp-tool \
|
||||
--id secure-tool \
|
||||
--tool-url https://secure-server.example.com/mcp \
|
||||
--auth-token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
```
|
||||
|
||||
**MCP araçlarını göster:**
|
||||
```bash
|
||||
tg-show-mcp-tools
|
||||
|
||||
ID Remote Name URL Auth
|
||||
----------- ----------- ------------------------------------ ------
|
||||
secure-tool secure-tool https://secure-server.example.com/mcp Yes
|
||||
public-tool public-tool http://localhost:3000/mcp No
|
||||
```
|
||||
|
||||
### Yapılandırma Örneği
|
||||
|
||||
**Yapılandırma sisteminde saklanır**:
|
||||
```json
|
||||
{
|
||||
"type": "mcp",
|
||||
"key": "secure-tool",
|
||||
"value": "{\"url\": \"https://secure-server.example.com/mcp\", \"auth-token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"}"
|
||||
}
|
||||
```
|
||||
|
||||
### Güvenlik En İyi Uygulamaları
|
||||
|
||||
1. **HTTPS Kullanımı**: Kimlik doğrulama ile çalışan MCP sunucuları için her zaman HTTPS URL'lerini kullanın.
|
||||
2. **Kısa Ömürlü Token'lar**: Mümkün olduğunda, son kullanma tarihine sahip token'lar kullanın.
|
||||
3. **En Az Yetki**: Token'lara, yalnızca gerekli olan minimum izinleri verin.
|
||||
4. **Erişim Kontrolü**: Yapılandırma sistemine erişimi kısıtlayın.
|
||||
5. **Token Döndürme**: Token'ları düzenli olarak değiştirin.
|
||||
6. **Denetim Kayıtları**: Güvenlik olayları için yapılandırma değişikliklerini izleyin.
|
||||
266
docs/tech-specs/tr/minio-to-s3-migration.tr.md
Normal file
266
docs/tech-specs/tr/minio-to-s3-migration.tr.md
Normal file
|
|
@ -0,0 +1,266 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Teknik Özellikler: S3 Uyumlu Depolama Arka Ucu Desteği"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Teknik Özellikler: S3 Uyumlu Depolama Arka Ucu Desteği
|
||||
|
||||
> **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ış
|
||||
|
||||
Librarian hizmeti, belge bloğu depolaması için S3 uyumlu nesne depolamayı kullanır. Bu özellik, MinIO, Ceph RADOS Gateway (RGW), AWS S3, Cloudflare R2, DigitalOcean Spaces ve diğerleri dahil olmak üzere herhangi bir S3 uyumlu arka uç için desteği etkinleştiren uygulamayı belgelemektedir.
|
||||
|
||||
## Mimari
|
||||
|
||||
### Depolama Bileşenleri
|
||||
**Bloğu Depolama**: `minio` Python istemci kitaplığı aracılığıyla S3 uyumlu nesne depolama
|
||||
**Metaveri Depolama**: Cassandra (object_id eşlemesini ve belge meta verilerini depolar)
|
||||
**Etkilenen Bileşen**: Yalnızca Librarian hizmeti
|
||||
**Depolama Modeli**: Cassandra'da metaveri, S3 uyumlu depolamada içerikle hibrit depolama
|
||||
|
||||
### Uygulama
|
||||
**Kitaplık**: `minio` Python istemcisi (herhangi bir S3 uyumlu API'yi destekler)
|
||||
**Konum**: `trustgraph-flow/trustgraph/librarian/blob_store.py`
|
||||
**İşlemler**:
|
||||
`add()` - UUID object_id ile bloğu kaydet
|
||||
`get()` - object_id ile bloğu al
|
||||
`remove()` - object_id ile bloğu sil
|
||||
`ensure_bucket()` - Yoksa bucket oluştur
|
||||
**Bucket**: `library`
|
||||
**Nesne Yolu**: `doc/{object_id}`
|
||||
**Desteklenen MIME Türleri**: `text/plain`, `application/pdf`
|
||||
|
||||
### Önemli Dosyalar
|
||||
1. `trustgraph-flow/trustgraph/librarian/blob_store.py` - BlobStore uygulaması
|
||||
2. `trustgraph-flow/trustgraph/librarian/librarian.py` - BlobStore başlatma
|
||||
3. `trustgraph-flow/trustgraph/librarian/service.py` - Hizmet yapılandırması
|
||||
4. `trustgraph-flow/pyproject.toml` - Bağımlılıklar (`minio` paketi)
|
||||
5. `docs/apis/api-librarian.md` - API dokümantasyonu
|
||||
|
||||
## Desteklenen Depolama Arka Uçları
|
||||
|
||||
Bu uygulama, herhangi bir S3 uyumlu nesne depolama sistemiyle çalışır:
|
||||
|
||||
### Test Edildi/Destekleniyor
|
||||
**Ceph RADOS Gateway (RGW)** - S3 API'sine sahip dağıtılmış depolama sistemi (varsayılan yapılandırma)
|
||||
**MinIO** - Hafif, kendi kendine barındırılan nesne depolama
|
||||
**Garage** - Hafif, coğrafi olarak dağıtılmış S3 uyumlu depolama
|
||||
|
||||
### Çalışması Gerekiyor (S3 Uyumlu)
|
||||
**AWS S3** - Amazon'un bulut nesne depolaması
|
||||
**Cloudflare R2** - Cloudflare'in S3 uyumlu depolaması
|
||||
**DigitalOcean Spaces** - DigitalOcean'ın nesne depolaması
|
||||
**Wasabi** - S3 uyumlu bulut depolama
|
||||
**Backblaze B2** - S3 uyumlu yedekleme depolama
|
||||
S3 REST API'sini uygulayan herhangi bir hizmet
|
||||
|
||||
## Yapılandırma
|
||||
|
||||
### CLI Argümanları
|
||||
|
||||
```bash
|
||||
librarian \
|
||||
--object-store-endpoint <hostname:port> \
|
||||
--object-store-access-key <access_key> \
|
||||
--object-store-secret-key <secret_key> \
|
||||
[--object-store-use-ssl] \
|
||||
[--object-store-region <region>]
|
||||
```
|
||||
|
||||
**Not:** `http://` veya `https://`'i uç noktada dahil etmeyin. HTTPS'yi etkinleştirmek için `--object-store-use-ssl`'yi kullanın.
|
||||
|
||||
### Ortam Değişkenleri (Alternatif)
|
||||
|
||||
```bash
|
||||
OBJECT_STORE_ENDPOINT=<hostname:port>
|
||||
OBJECT_STORE_ACCESS_KEY=<access_key>
|
||||
OBJECT_STORE_SECRET_KEY=<secret_key>
|
||||
OBJECT_STORE_USE_SSL=true|false # Optional, default: false
|
||||
OBJECT_STORE_REGION=<region> # Optional
|
||||
```
|
||||
|
||||
### Örnekler
|
||||
|
||||
**Ceph RADOS Ağ Geçidi (varsayılan):**
|
||||
```bash
|
||||
--object-store-endpoint ceph-rgw:7480 \
|
||||
--object-store-access-key object-user \
|
||||
--object-store-secret-key object-password
|
||||
```
|
||||
|
||||
**MinIO:**
|
||||
```bash
|
||||
--object-store-endpoint minio:9000 \
|
||||
--object-store-access-key minioadmin \
|
||||
--object-store-secret-key minioadmin
|
||||
```
|
||||
|
||||
**Garaj (S3 uyumlu):**
|
||||
```bash
|
||||
--object-store-endpoint garage:3900 \
|
||||
--object-store-access-key GK000000000000000000000001 \
|
||||
--object-store-secret-key b171f00be9be4c32c734f4c05fe64c527a8ab5eb823b376cfa8c2531f70fc427
|
||||
```
|
||||
|
||||
**AWS S3 SSL ile:**
|
||||
```bash
|
||||
--object-store-endpoint s3.amazonaws.com \
|
||||
--object-store-access-key AKIAIOSFODNN7EXAMPLE \
|
||||
--object-store-secret-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
|
||||
--object-store-use-ssl \
|
||||
--object-store-region us-east-1
|
||||
```
|
||||
|
||||
## Kimlik Doğrulama
|
||||
|
||||
Tüm S3 uyumlu arka uçlar, AWS Signature Version 4 (veya v2) kimlik doğrulamasını gerektirir:
|
||||
|
||||
**Erişim Anahtarı** - Genel tanımlayıcı (kullanıcı adı gibi)
|
||||
**Gizli Anahtar** - Özel imzalama anahtarı (parola gibi)
|
||||
|
||||
MinIO Python istemcisi, tüm imza hesaplamalarını otomatik olarak yapar.
|
||||
|
||||
### Kimlik Bilgilerini Oluşturma
|
||||
|
||||
**MinIO için:**
|
||||
```bash
|
||||
# Use default credentials or create user via MinIO Console
|
||||
minioadmin / minioadmin
|
||||
```
|
||||
|
||||
**Ceph RGW için:**
|
||||
```bash
|
||||
radosgw-admin user create --uid="trustgraph" --display-name="TrustGraph Service"
|
||||
# Returns access_key and secret_key
|
||||
```
|
||||
|
||||
**AWS S3 için:**
|
||||
S3 izinlerine sahip bir IAM kullanıcısı oluşturun.
|
||||
AWS Konsolu'nda bir erişim anahtarı oluşturun.
|
||||
|
||||
## Kütüphane Seçimi: MinIO Python İstemcisi
|
||||
|
||||
**Gerekçe:**
|
||||
Hafif (~500KB, boto3'ün ~50MB'sine kıyasla)
|
||||
S3 uyumlu - herhangi bir S3 API uç noktasıyla çalışır.
|
||||
Temel işlemler için boto3'e göre daha basit bir API.
|
||||
Zaten kullanımda, herhangi bir geçişe gerek yok.
|
||||
MinIO ve diğer S3 sistemleriyle test edilmiş.
|
||||
|
||||
## BlobStore Uygulaması
|
||||
|
||||
**Konum:** `trustgraph-flow/trustgraph/librarian/blob_store.py`
|
||||
|
||||
```python
|
||||
from minio import Minio
|
||||
import io
|
||||
import logging
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
class BlobStore:
|
||||
"""
|
||||
S3-compatible blob storage for document content.
|
||||
Supports MinIO, Ceph RGW, AWS S3, and other S3-compatible backends.
|
||||
"""
|
||||
|
||||
def __init__(self, endpoint, access_key, secret_key, bucket_name,
|
||||
use_ssl=False, region=None):
|
||||
"""
|
||||
Initialize S3-compatible blob storage.
|
||||
|
||||
Args:
|
||||
endpoint: S3 endpoint (e.g., "minio:9000", "ceph-rgw:7480")
|
||||
access_key: S3 access key
|
||||
secret_key: S3 secret key
|
||||
bucket_name: Bucket name for storage
|
||||
use_ssl: Use HTTPS instead of HTTP (default: False)
|
||||
region: S3 region (optional, e.g., "us-east-1")
|
||||
"""
|
||||
self.client = Minio(
|
||||
endpoint=endpoint,
|
||||
access_key=access_key,
|
||||
secret_key=secret_key,
|
||||
secure=use_ssl,
|
||||
region=region,
|
||||
)
|
||||
|
||||
self.bucket_name = bucket_name
|
||||
|
||||
protocol = "https" if use_ssl else "http"
|
||||
logger.info(f"Connected to S3-compatible storage at {protocol}://{endpoint}")
|
||||
|
||||
self.ensure_bucket()
|
||||
|
||||
def ensure_bucket(self):
|
||||
"""Create bucket if it doesn't exist"""
|
||||
found = self.client.bucket_exists(bucket_name=self.bucket_name)
|
||||
if not found:
|
||||
self.client.make_bucket(bucket_name=self.bucket_name)
|
||||
logger.info(f"Created bucket {self.bucket_name}")
|
||||
else:
|
||||
logger.debug(f"Bucket {self.bucket_name} already exists")
|
||||
|
||||
async def add(self, object_id, blob, kind):
|
||||
"""Store blob in S3-compatible storage"""
|
||||
self.client.put_object(
|
||||
bucket_name=self.bucket_name,
|
||||
object_name=f"doc/{object_id}",
|
||||
length=len(blob),
|
||||
data=io.BytesIO(blob),
|
||||
content_type=kind,
|
||||
)
|
||||
logger.debug("Add blob complete")
|
||||
|
||||
async def remove(self, object_id):
|
||||
"""Delete blob from S3-compatible storage"""
|
||||
self.client.remove_object(
|
||||
bucket_name=self.bucket_name,
|
||||
object_name=f"doc/{object_id}",
|
||||
)
|
||||
logger.debug("Remove blob complete")
|
||||
|
||||
async def get(self, object_id):
|
||||
"""Retrieve blob from S3-compatible storage"""
|
||||
resp = self.client.get_object(
|
||||
bucket_name=self.bucket_name,
|
||||
object_name=f"doc/{object_id}",
|
||||
)
|
||||
return resp.read()
|
||||
```
|
||||
|
||||
## Temel Avantajlar
|
||||
|
||||
1. **Satıcıya Bağlılık Yok** - Herhangi bir S3 uyumlu depolama ile çalışır.
|
||||
2. **Hafif** - MinIO istemcisi yaklaşık 500KB'dir.
|
||||
3. **Basit Yapılandırma** - Sadece uç nokta + kimlik bilgileri gereklidir.
|
||||
4. **Veri Göçü Yok** - Arka uçlar arasında doğrudan değiştirilebilir.
|
||||
5. **Kanıtlanmış** - MinIO istemcisi, tüm büyük S3 uygulamalarıyla çalışır.
|
||||
|
||||
## Uygulama Durumu
|
||||
|
||||
Tüm kod, genel S3 parametre adlarını kullanacak şekilde güncellenmiştir:
|
||||
|
||||
✅ `blob_store.py` - `endpoint`, `access_key` ve `secret_key`'ü kabul edecek şekilde güncellendi.
|
||||
✅ `librarian.py` - Parametre adları güncellendi.
|
||||
✅ `service.py` - CLI argümanları ve yapılandırma güncellendi.
|
||||
✅ Belgeler güncellendi.
|
||||
|
||||
## Gelecek Geliştirmeler
|
||||
|
||||
1. **SSL/TLS Desteği** - HTTPS için `--s3-use-ssl` bayrağı eklenecek.
|
||||
2. **Yeniden Deneme Mantığı** - Geçici hatalar için üstel geri alma uygulanacak.
|
||||
3. **Önceden İmzalı URL'ler** - Geçici yükleme/indirme URL'leri oluşturulacak.
|
||||
4. **Çok Bölgeli Destek** - Verileri bölgeler arasında çoğaltılacak.
|
||||
5. **CDN Entegrasyonu** - Veriler CDN üzerinden sunulacak.
|
||||
6. **Depolama Sınıfları** - Maliyet optimizasyonu için S3 depolama sınıfları kullanılacak.
|
||||
7. **Yaşam Döngüsü Politikaları** - Otomatik arşivleme/silme.
|
||||
8. **Sürümleme** - Verilerin birden fazla sürümü saklanacak.
|
||||
|
||||
## Referanslar
|
||||
|
||||
MinIO Python İstemcisi: https://min.io/docs/minio/linux/developers/python/API.html
|
||||
Ceph RGW S3 API: https://docs.ceph.com/en/latest/radosgw/s3/
|
||||
S3 API Referansı: https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html
|
||||
287
docs/tech-specs/tr/more-config-cli.tr.md
Normal file
287
docs/tech-specs/tr/more-config-cli.tr.md
Normal file
|
|
@ -0,0 +1,287 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Daha Fazla Yapılandırma CLI Teknik Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Daha Fazla Yapılandırma CLI 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çin gelişmiş komut satırı yapılandırma yeteneklerini tanımlar ve kullanıcıların ayrı yapılandırma öğelerini ayrıntılı CLI komutları aracılığıyla yönetmelerini sağlar. Bu entegrasyon, dört birincil kullanım senaryosunu destekler:
|
||||
|
||||
1. **Yapılandırma Öğelerini Listele**: Belirli bir türdeki yapılandırma anahtarlarını görüntüleyin
|
||||
2. **Yapılandırma Öğesini Al**: Belirli yapılandırma değerlerini alın
|
||||
3. **Yapılandırma Öğesini Ekle/Güncelle**: Bireysel yapılandırma öğelerini ayarlayın veya güncelleyin
|
||||
4. **Yapılandırma Öğesini Sil**: Belirli yapılandırma öğelerini kaldırın
|
||||
|
||||
## Hedefler
|
||||
|
||||
**Ayrıntılı Kontrol**: Toplu işlemler yerine bireysel yapılandırma öğelerinin yönetimini sağlayın
|
||||
**Türe Dayalı Listeleme**: Kullanıcıların yapılandırma öğelerini türe göre incelemesine izin verin
|
||||
**Tek Öğeli İşlemler**: Bireysel yapılandırma öğelerinin alınması/eklenmesi/güncellenmesi/silinmesi için komutlar sağlayın
|
||||
**API Entegrasyonu**: Tüm işlemler için mevcut Config API'sini kullanın
|
||||
**Tutarlı CLI Modeli**: Kuruluş içi TrustGraph CLI kurallarına ve kalıplarına uyun
|
||||
**Hata Yönetimi**: Geçersiz işlemler için açık hata mesajları sağlayın
|
||||
**JSON Çıkışı**: Programlı kullanım için yapılandırılmış çıktı desteği sağlayın
|
||||
**Belgeleme**: Kapsamlı yardım ve kullanım örnekleri ekleyin
|
||||
|
||||
## Arka Plan
|
||||
|
||||
TrustGraph şu anda Config API ve tüm yapılandırmayı görüntüleyen `tg-show-config` adlı tek bir CLI komutu aracılığıyla yapılandırma yönetimini sağlar. Bu, yapılandırmayı görüntülemek için işe yarasa da, ayrıntılı yönetim yetenekleri eksiktir.
|
||||
|
||||
Mevcut sınırlamalar şunlardır:
|
||||
CLI'den yapılandırma öğelerini türe göre listelemenin bir yolu yok
|
||||
Belirli yapılandırma değerlerini almak için bir CLI komutu yok
|
||||
Bireysel yapılandırma öğelerini ayarlamak için bir CLI komutu yok
|
||||
Belirli yapılandırma öğelerini silmek için bir CLI komutu yok
|
||||
|
||||
Bu özellik, ayrıntılı yapılandırma yönetimi sağlayan dört yeni CLI komutu ekleyerek bu boşlukları giderir. Bireysel Config API işlemlerini CLI komutları aracılığıyla açığa çıkararak TrustGraph şunları yapabilir:
|
||||
Betik tabanlı yapılandırma yönetimini etkinleştirin
|
||||
Yapılandırma yapısını türe göre incelemeye izin verin
|
||||
Hedefli yapılandırma güncellemelerini destekleyin
|
||||
İnce taneli yapılandırma kontrolü sağlayın
|
||||
|
||||
## Teknik Tasarım
|
||||
|
||||
### Mimari
|
||||
|
||||
Gelişmiş CLI yapılandırması, aşağıdaki teknik bileşenleri gerektirir:
|
||||
|
||||
1. **tg-list-config-items**
|
||||
Belirtilen bir tür için yapılandırma anahtarlarını listeler
|
||||
Config.list(type) API yöntemini çağırır
|
||||
Yapılandırma anahtarlarının listesini çıktı olarak verir
|
||||
|
||||
Modül: `trustgraph.cli.list_config_items`
|
||||
|
||||
2. **tg-get-config-item**
|
||||
Belirli yapılandırma öğesi(ni) alır
|
||||
Config.get(keys) API yöntemini çağırır
|
||||
Yapılandırma değerlerini JSON formatında çıktı olarak verir
|
||||
|
||||
Modül: `trustgraph.cli.get_config_item`
|
||||
|
||||
3. **tg-put-config-item**
|
||||
Bir yapılandırma öğesini ayarlar veya günceller
|
||||
Config.put(values) API yöntemini çağırır
|
||||
Tür, anahtar ve değer parametrelerini kabul eder
|
||||
|
||||
Modül: `trustgraph.cli.put_config_item`
|
||||
|
||||
4. **tg-delete-config-item**
|
||||
Bir yapılandırma öğesini siler
|
||||
Config.delete(keys) API yöntemini çağırır
|
||||
Tür ve anahtar parametrelerini kabul eder
|
||||
|
||||
Modül: `trustgraph.cli.delete_config_item`
|
||||
|
||||
### Veri Modelleri
|
||||
|
||||
#### ConfigKey ve ConfigValue
|
||||
|
||||
Bu komutlar, `trustgraph.api.types`'dan mevcut veri yapılarını kullanır:
|
||||
|
||||
```python
|
||||
@dataclasses.dataclass
|
||||
class ConfigKey:
|
||||
type : str
|
||||
key : str
|
||||
|
||||
@dataclasses.dataclass
|
||||
class ConfigValue:
|
||||
type : str
|
||||
key : str
|
||||
value : str
|
||||
```
|
||||
|
||||
Bu yaklaşım şunları sağlar:
|
||||
CLI ve API'ler arasında tutarlı veri işleme
|
||||
Tür güvenli yapılandırma işlemleri
|
||||
Yapılandırılmış girdi/çıktı formatları
|
||||
Mevcut Config API ile entegrasyon
|
||||
|
||||
### CLI Komut Özellikleri
|
||||
|
||||
#### tg-list-config-items
|
||||
```bash
|
||||
tg-list-config-items --type <config-type> [--format text|json] [--api-url <url>]
|
||||
```
|
||||
**Amaç**: Belirli bir tür için tüm yapılandırma anahtarlarını listele.
|
||||
**API Çağrısı**: `Config.list(type)`
|
||||
**Çıktı**:
|
||||
`text` (varsayılan): Yeni satırlarla ayrılmış yapılandırma anahtarları.
|
||||
`json`: Yapılandırma anahtarlarının JSON dizisi.
|
||||
|
||||
#### tg-get-config-item
|
||||
```bash
|
||||
tg-get-config-item --type <type> --key <key> [--format text|json] [--api-url <url>]
|
||||
```
|
||||
**Amaç**: Belirli bir yapılandırma öğesini almak.
|
||||
**API Çağrısı**: `Config.get([ConfigKey(type, key)])`
|
||||
**Çıktı**:
|
||||
`text` (varsayılan): Ham metin değeri.
|
||||
`json`: JSON olarak kodlanmış metin değeri.
|
||||
|
||||
#### tg-put-config-item
|
||||
```bash
|
||||
tg-put-config-item --type <type> --key <key> --value <value> [--api-url <url>]
|
||||
tg-put-config-item --type <type> --key <key> --stdin [--api-url <url>]
|
||||
```
|
||||
**Amaç**: Yapılandırma öğesini ayarlayın veya güncelleyin.
|
||||
**API Çağrısı**: `Config.put([ConfigValue(type, key, value)])`
|
||||
**Giriş Seçenekleri**:
|
||||
`--value`: Değer, doğrudan komut satırından sağlanır.
|
||||
`--stdin`: Değer, standart girişten okunur.
|
||||
**Çıktı**: Başarı onayı.
|
||||
|
||||
#### tg-delete-config-item
|
||||
```bash
|
||||
tg-delete-config-item --type <type> --key <key> [--api-url <url>]
|
||||
```
|
||||
**Amaç**: Yapılandırma öğesini silme
|
||||
**API Çağrısı**: `Config.delete([ConfigKey(type, key)])`
|
||||
**Çıktı**: Başarı onayı
|
||||
|
||||
### Uygulama Detayları
|
||||
|
||||
Tüm komutlar, mevcut TrustGraph CLI kalıbını izler:
|
||||
Komut satırı argüman ayrıştırması için `argparse` kullanın
|
||||
Arka uç iletişimi için `trustgraph.api.Api`'i içe aktarın ve kullanın
|
||||
Mevcut CLI komutlarındaki aynı hata işleme kalıplarını izleyin
|
||||
API uç noktası yapılandırması için standart `--api-url` parametresini destekleyin
|
||||
Açıklayıcı yardım metni ve kullanım örnekleri sağlayın
|
||||
|
||||
#### Çıktı Biçimi İşleme
|
||||
|
||||
**Metin Biçimi (Varsayılan)**:
|
||||
`tg-list-config-items`: Her satırda bir anahtar, düz metin
|
||||
`tg-get-config-item`: Ham dize değeri, tırnak veya kodlama yok
|
||||
|
||||
**JSON Biçimi**:
|
||||
`tg-list-config-items`: `["key1", "key2", "key3"]` dize dizisi
|
||||
`tg-get-config-item`: JSON ile kodlanmış dize değeri `"actual string value"`
|
||||
|
||||
#### Giriş İşleme
|
||||
|
||||
**tg-put-config-item**, iki karşılıklı olarak münhasır giriş yöntemini destekler:
|
||||
`--value <string>`: Doğrudan komut satırı dize değeri
|
||||
`--stdin`: Tüm girdiyi yapılandırma değeri olarak standart girdiden okuyun
|
||||
stdin içeriği ham metin olarak okunur (satır başları, boşluklar vb. korunur)
|
||||
Dosyalardan, komutlardan veya etkileşimli girdiden boru hattı desteği
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
**Giriş Doğrulama**: Tüm komut satırı parametreleri, API çağrıları yapılmadan önce doğrulanmalıdır.
|
||||
**API Kimlik Doğrulama**: Komutlar, mevcut API kimlik doğrulama mekanizmalarını kullanır.
|
||||
**Yapılandırma Erişimi**: Komutlar, mevcut yapılandırma erişim kontrollerine saygı gösterir.
|
||||
**Hata Bilgisi**: Hata mesajları, hassas yapılandırma ayrıntılarını ifşa etmemelidir.
|
||||
|
||||
## Performans Hususları
|
||||
|
||||
**Tek Öğeli İşlemler**: Komutlar, toplu işlem yükünü önlemek için tek tek öğeler için tasarlanmıştır.
|
||||
**API Verimliliği**: Doğrudan API çağrıları, işleme katmanlarını en aza indirir.
|
||||
**Ağ Gecikmesi**: Her komut, tek bir API çağrısı yapar ve bu da ağ iletişimini en aza indirir.
|
||||
**Bellek Kullanımı**: Tek öğeli işlemler için minimum bellek kullanımı.
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
**Birim Testleri**: Her CLI komut modülünü bağımsız olarak test edin.
|
||||
**Entegrasyon Testleri**: CLI komutlarını canlı Config API'ye karşı test edin.
|
||||
**Hata Yönetimi Testleri**: Geçersiz girişler için uygun hata yönetimini doğrulayın.
|
||||
**API Uyumluluğu**: Komutların mevcut Config API sürümleriyle çalıştığından emin olun.
|
||||
|
||||
## Geçiş Planı
|
||||
|
||||
Geçiş gerekli değil - bunlar, mevcut işlevselliği tamamlayan yeni CLI komutlarıdır:
|
||||
Mevcut `tg-show-config` komutu değişmeden kalır.
|
||||
Yeni komutlar kademeli olarak eklenebilir.
|
||||
Mevcut yapılandırma iş akışlarında herhangi bir değişiklik yapılmaz.
|
||||
|
||||
## Paketleme ve Dağıtım
|
||||
|
||||
Bu komutlar, mevcut `trustgraph-cli` paketine eklenecektir:
|
||||
|
||||
**Paket Konumu**: `trustgraph-cli/`
|
||||
**Modül Dosyaları**:
|
||||
`trustgraph-cli/trustgraph/cli/list_config_items.py`
|
||||
`trustgraph-cli/trustgraph/cli/get_config_item.py`
|
||||
`trustgraph-cli/trustgraph/cli/put_config_item.py`
|
||||
`trustgraph-cli/trustgraph/cli/delete_config_item.py`
|
||||
|
||||
**Giriş Noktaları**: `trustgraph-cli/pyproject.toml`'a `[project.scripts]` bölümüne eklendi:
|
||||
```toml
|
||||
tg-list-config-items = "trustgraph.cli.list_config_items:main"
|
||||
tg-get-config-item = "trustgraph.cli.get_config_item:main"
|
||||
tg-put-config-item = "trustgraph.cli.put_config_item:main"
|
||||
tg-delete-config-item = "trustgraph.cli.delete_config_item:main"
|
||||
```
|
||||
|
||||
## Uygulama Görevleri
|
||||
|
||||
1. **CLI Modüllerini Oluşturma**: `trustgraph-cli/trustgraph/cli/` içinde dört CLI komut modülünü uygulayın.
|
||||
2. **pyproject.toml'yi Güncelleme**: `trustgraph-cli/pyproject.toml`'a yeni komut giriş noktaları ekleyin.
|
||||
3. **Belgeleme**: `docs/cli/` içindeki her komut için CLI belgelerini oluşturun.
|
||||
4. **Test**: Kapsamlı test kapsamı uygulayın.
|
||||
5. **Entegrasyon**: Komutların mevcut TrustGraph altyapısıyla çalıştığından emin olun.
|
||||
6. **Paket Oluşturma**: Komutların `pip install trustgraph-cli` ile düzgün bir şekilde yüklendiğini doğrulayın.
|
||||
|
||||
## Kullanım Örnekleri
|
||||
|
||||
#### Yapılandırma öğelerini listeleme
|
||||
```bash
|
||||
# List prompt keys (text format)
|
||||
tg-list-config-items --type prompt
|
||||
template-1
|
||||
template-2
|
||||
system-prompt
|
||||
|
||||
# List prompt keys (JSON format)
|
||||
tg-list-config-items --type prompt --format json
|
||||
["template-1", "template-2", "system-prompt"]
|
||||
```
|
||||
|
||||
#### Yapılandırma öğesini al
|
||||
```bash
|
||||
# Get prompt value (text format)
|
||||
tg-get-config-item --type prompt --key template-1
|
||||
You are a helpful assistant. Please respond to: {query}
|
||||
|
||||
# Get prompt value (JSON format)
|
||||
tg-get-config-item --type prompt --key template-1 --format json
|
||||
"You are a helpful assistant. Please respond to: {query}"
|
||||
```
|
||||
|
||||
#### Yapılandırma öğesini ayarlayın
|
||||
```bash
|
||||
# Set from command line
|
||||
tg-put-config-item --type prompt --key new-template --value "Custom prompt: {input}"
|
||||
|
||||
# Set from file via pipe
|
||||
cat ./prompt-template.txt | tg-put-config-item --type prompt --key complex-template --stdin
|
||||
|
||||
# Set from file via redirect
|
||||
tg-put-config-item --type prompt --key complex-template --stdin < ./prompt-template.txt
|
||||
|
||||
# Set from command output
|
||||
echo "Generated template: {query}" | tg-put-config-item --type prompt --key auto-template --stdin
|
||||
```
|
||||
|
||||
#### Yapılandırma öğesini sil
|
||||
```bash
|
||||
tg-delete-config-item --type prompt --key old-template
|
||||
```
|
||||
|
||||
## Açık Sorular
|
||||
|
||||
Komutlar, tek öğelerin yanı sıra toplu işlemleri (çoklu anahtarlar) desteklemeli mi?
|
||||
Başarı onayları için hangi çıktı formatı kullanılmalıdır?
|
||||
Konfigürasyon türleri kullanıcılar tarafından nasıl belgelenmeli/keşfedilmelidir?
|
||||
|
||||
## Referanslar
|
||||
|
||||
Mevcut Konfigürasyon API'si: `trustgraph/api/config.py`
|
||||
CLI kalıpları: `trustgraph-cli/trustgraph/cli/show_config.py`
|
||||
Veri türleri: `trustgraph/api/types.py`
|
||||
780
docs/tech-specs/tr/multi-tenant-support.tr.md
Normal file
780
docs/tech-specs/tr/multi-tenant-support.tr.md
Normal file
|
|
@ -0,0 +1,780 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Teknik Özellikler: Çok Kiracılı Destek"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Teknik Özellikler: Çok Kiracılı Destek
|
||||
|
||||
> **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ış
|
||||
|
||||
Kuyumuzu özelleştirmeyi engelleyen parametre adı eşleşmezliklerini düzelterek ve Cassandra anahtar alanı parametrelemesini ekleyerek çok kiracılı dağıtımları etkinleştirin.
|
||||
|
||||
## Mimari Bağlam
|
||||
|
||||
### Akış Tabanlı Kuyruk Çözümlemesi
|
||||
|
||||
TrustGraph sistemi, dinamik kuyruk çözümlemesi için **akış tabanlı bir mimari** kullanır ve bu, doğal olarak çok kiracılığı destekler:
|
||||
|
||||
**Akış Tanımları**, Cassandra'da saklanır ve arayüz tanımları aracılığıyla kuyruk adlarını belirtir.
|
||||
**Kuyruk adları**, akış örneği kimlikleriyle değiştirilen `{id}` değişkenlerine sahip **şablonlar** kullanır.
|
||||
**Hizmetler**, istek zamanında akış yapılandırmalarını arayarak **kuyrukları dinamik olarak çözümler**.
|
||||
**Her kiracı, farklı kuyruk adlarına sahip benzersiz akışlara sahip olabilir**, bu da izolasyon sağlar.
|
||||
|
||||
Örnek akış arayüz tanımı:
|
||||
```json
|
||||
{
|
||||
"interfaces": {
|
||||
"triples-store": "persistent://tg/flow/triples-store:{id}",
|
||||
"graph-embeddings-store": "persistent://tg/flow/graph-embeddings-store:{id}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Kiracı A, `tenant-a-prod` akışını başlatığında ve kiracı B, `tenant-b-prod` akışını başlattığında, otomatik olarak izole edilmiş kuyruklar elde ederler:
|
||||
`persistent://tg/flow/triples-store:tenant-a-prod`
|
||||
`persistent://tg/flow/triples-store:tenant-b-prod`
|
||||
|
||||
**Çoklu kiracılığa doğru şekilde tasarlanmış hizmetler:**
|
||||
✅ **Bilgi Yönetimi (çekirdekler)** - İsteğe eklenen akış yapılandırmasından kuyrukları dinamik olarak çözer.
|
||||
|
||||
**Düzeltilmesi gereken hizmetler:**
|
||||
🔴 **Yapılandırma Hizmeti** - Parametre adı eşleşmezliği, kuyruk özelleştirmesini engeller.
|
||||
🔴 **Kütüphaneci Hizmeti** - Sabit kodlanmış depolama yönetimi konuları (aşağıda açıklanmıştır).
|
||||
🔴 **Tüm Hizmetler** - Cassandra anahtar alanını özelleştiremezsiniz.
|
||||
|
||||
## Sorun Tanımı
|
||||
|
||||
### Sorun #1: AsyncProcessor'daki Parametre Adı Eşleşmezliği
|
||||
**CLI tanımları:** `--config-queue` (belirsiz adlandırma)
|
||||
**Argparse'ın dönüştürdüğü:** `config_queue` (params sözlüğünde)
|
||||
**Kodun aradığı:** `config_push_queue`
|
||||
**Sonuç:** Parametre göz ardı edilir ve varsayılan olarak `persistent://tg/config/config` olur.
|
||||
**Etkisi:** AsyncProcessor'dan türeyen 32'den fazla hizmeti etkiler.
|
||||
**Engeller:** Çoklu kiracılı dağıtımlar, kiracıya özel yapılandırma kuyruklarını kullanamaz.
|
||||
**Çözüm:** CLI parametresinin adını `--config-push-queue` olarak değiştirerek netliği artırın (özellik şu anda bozuk olduğundan, bozucu değişiklik kabul edilebilir).
|
||||
|
||||
### Sorun #2: Yapılandırma Hizmetindeki Parametre Adı Eşleşmezliği
|
||||
**CLI tanımları:** `--push-queue` (belirsiz adlandırma)
|
||||
**Argparse'ın dönüştürdüğü:** `push_queue` (params sözlüğünde)
|
||||
**Kodun aradığı:** `config_push_queue`
|
||||
**Sonuç:** Parametre göz ardı edilir.
|
||||
**Etkisi:** Yapılandırma hizmeti, özel bir push kuyruğunu kullanamaz.
|
||||
**Çözüm:** CLI parametresinin adını `--config-push-queue` olarak değiştirerek tutarlılığı ve netliği artırın (bozucu değişiklik kabul edilebilir).
|
||||
|
||||
### Sorun #3: Sabit Kodlanmış Cassandra Anahtar Alanı
|
||||
**Mevcut durum:** Anahtar alanı, çeşitli hizmetlerde `"config"`, `"knowledge"`, `"librarian"` olarak sabit kodlanmıştır.
|
||||
**Sonuç:** Çoklu kiracılı dağıtımlar için anahtar alanı özelleştirilemez.
|
||||
**Etkisi:** Yapılandırma, çekirdek ve kütüphaneci hizmetleri.
|
||||
**Engeller:** Birden fazla kiracı, ayrı Cassandra anahtar alanlarını kullanamaz.
|
||||
|
||||
### Sorun #4: Koleksiyon Yönetimi Mimarisi ✅ TAMAMLANDI
|
||||
**Önceki durum:** Koleksiyonlar, ayrı koleksiyon tablosu aracılığıyla Cassandra kütüphaneci anahtar alanında depolanıyordu.
|
||||
**Önceki durum:** Kütüphaneci, koleksiyon oluşturma/silme işlemini koordine etmek için 4 sabit kodlanmış depolama yönetimi konusunu kullanıyordu:
|
||||
`vector_storage_management_topic`
|
||||
`object_storage_management_topic`
|
||||
`triples_storage_management_topic`
|
||||
`storage_management_response_topic`
|
||||
**Sorunlar (Çözüldü):**
|
||||
Sabit kodlanmış konular, çoklu kiracılı dağıtımlar için özelleştirilemezdi.
|
||||
Kütüphaneci ile 4+ depolama hizmeti arasında karmaşık asenkron koordinasyon.
|
||||
Ayrı bir Cassandra tablosu ve yönetim altyapısı.
|
||||
Kritik işlemler için kalıcı olmayan istek/yanıt kuyrukları.
|
||||
**Uygulanan Çözüm:** Koleksiyonları yapılandırma hizmeti depolamasına taşıdık, dağıtım için yapılandırma push'u kullandık.
|
||||
**Durum:** Tüm depolama arka uçları `CollectionConfigHandler` modeline taşınmıştır.
|
||||
|
||||
## Çözüm
|
||||
|
||||
Bu özellik, Sorunlar #1, #2, #3 ve #4'ü ele alır.
|
||||
|
||||
### 1. Bölüm: Parametre Adı Eşleşmezliklerini Düzeltme
|
||||
|
||||
#### Değişiklik 1: AsyncProcessor Temel Sınıfı - CLI Parametresinin Adını Değiştirme
|
||||
**Dosya:** `trustgraph-base/trustgraph/base/async_processor.py`
|
||||
**Satır:** 260-264
|
||||
|
||||
**Mevcut:**
|
||||
```python
|
||||
parser.add_argument(
|
||||
'--config-queue',
|
||||
default=default_config_queue,
|
||||
help=f'Config push queue {default_config_queue}',
|
||||
)
|
||||
```
|
||||
|
||||
**Sabit:**
|
||||
```python
|
||||
parser.add_argument(
|
||||
'--config-push-queue',
|
||||
default=default_config_queue,
|
||||
help=f'Config push queue (default: {default_config_queue})',
|
||||
)
|
||||
```
|
||||
|
||||
**Gerekçe:**
|
||||
Daha açık, daha kesin bir adlandırma
|
||||
İç değişken adıyla eşleşiyor: `config_push_queue`
|
||||
Özellik şu anda çalışmadığı için, bu bir değişikliktir ve kabul edilebilir.
|
||||
params.get() içinde herhangi bir kod değişikliğine gerek yok; zaten doğru adı arıyor.
|
||||
|
||||
#### Değişiklik 2: Konfigürasyon Servisi - CLI Parametresinin Yeniden Adlandırılması
|
||||
**Dosya:** `trustgraph-flow/trustgraph/config/service/service.py`
|
||||
**Satır:** 276-279
|
||||
|
||||
**Mevcut:**
|
||||
```python
|
||||
parser.add_argument(
|
||||
'--push-queue',
|
||||
default=default_config_push_queue,
|
||||
help=f'Config push queue (default: {default_config_push_queue})'
|
||||
)
|
||||
```
|
||||
|
||||
**Sabit:**
|
||||
```python
|
||||
parser.add_argument(
|
||||
'--config-push-queue',
|
||||
default=default_config_push_queue,
|
||||
help=f'Config push queue (default: {default_config_push_queue})'
|
||||
)
|
||||
```
|
||||
|
||||
**Gerekçe:**
|
||||
Daha anlaşılır bir adlandırma - "config-push-queue", sadece "push-queue"den daha açık.
|
||||
İç değişken adıyla eşleşiyor: `config_push_queue`
|
||||
AsyncProcessor'ın `--config-push-queue` parametresiyle tutarlı.
|
||||
Özellik şu anda çalışmadığı için değişiklik kabul edilebilir.
|
||||
params.get() içinde herhangi bir kod değişikliğine gerek yok - zaten doğru adı arıyor.
|
||||
|
||||
### 2. Bölüm: Cassandra Keyspace Parametrelendirmesi
|
||||
|
||||
#### 3. Değişiklik: cassandra_config Modülüne Keyspace Parametresi Ekle
|
||||
**Dosya:** `trustgraph-base/trustgraph/base/cassandra_config.py`
|
||||
|
||||
**CLI argümanı ekle** (`add_cassandra_args()` fonksiyonunda):
|
||||
```python
|
||||
parser.add_argument(
|
||||
'--cassandra-keyspace',
|
||||
default=None,
|
||||
help='Cassandra keyspace (default: service-specific)'
|
||||
)
|
||||
```
|
||||
|
||||
**Ortam değişkeni desteği ekleyin** (`resolve_cassandra_config()` fonksiyonunda):
|
||||
```python
|
||||
keyspace = params.get(
|
||||
"cassandra_keyspace",
|
||||
os.environ.get("CASSANDRA_KEYSPACE")
|
||||
)
|
||||
```
|
||||
|
||||
**`resolve_cassandra_config()`'nin dönüş değerini güncelleyin:**
|
||||
Şu anda döndürüyor: `(hosts, username, password)`
|
||||
Aşağıdaki değeri döndürmesi için değiştirin: `(hosts, username, password, keyspace)`
|
||||
|
||||
**Gerekçe:**
|
||||
Mevcut Cassandra yapılandırma kalıbıyla tutarlı
|
||||
`add_cassandra_args()` aracılığıyla tüm hizmetlere erişilebilir
|
||||
Hem CLI hem de ortam değişkeni yapılandırmasını destekler
|
||||
|
||||
#### Değişiklik 4: Yapılandırma Hizmeti - Parametreli Keyspace Kullanımı
|
||||
**Dosya:** `trustgraph-flow/trustgraph/config/service/service.py`
|
||||
|
||||
**30. Satır** - Sabit kodlanmış keyspace'i kaldırın:
|
||||
```python
|
||||
# DELETE THIS LINE:
|
||||
keyspace = "config"
|
||||
```
|
||||
|
||||
**69-73 satırları** - Cassandra yapılandırma çözümlemesi güncellendi:
|
||||
|
||||
**Mevcut:**
|
||||
```python
|
||||
cassandra_host, cassandra_username, cassandra_password = \
|
||||
resolve_cassandra_config(params)
|
||||
```
|
||||
|
||||
**Sabit:**
|
||||
```python
|
||||
cassandra_host, cassandra_username, cassandra_password, keyspace = \
|
||||
resolve_cassandra_config(params, default_keyspace="config")
|
||||
```
|
||||
|
||||
**Gerekçe:**
|
||||
"config" varsayılan olarak kullanılarak geriye dönük uyumluluk sağlanır.
|
||||
`--cassandra-keyspace` veya `CASSANDRA_KEYSPACE` ile geçersiz kılınabilir.
|
||||
|
||||
#### Değişiklik 5: Cores/Bilgi Hizmeti - Parametreleştirilmiş Anahtar Alanı Kullanımı
|
||||
**Dosya:** `trustgraph-flow/trustgraph/cores/service.py`
|
||||
|
||||
**Satır 37** - Sabit kodlanmış anahtar alanını kaldırın:
|
||||
```python
|
||||
# DELETE THIS LINE:
|
||||
keyspace = "knowledge"
|
||||
```
|
||||
|
||||
**Cassandra yapılandırma çözümlemesi güncellendi** (yapılandırma hizmetiyle benzer konumda):
|
||||
```python
|
||||
cassandra_host, cassandra_username, cassandra_password, keyspace = \
|
||||
resolve_cassandra_config(params, default_keyspace="knowledge")
|
||||
```
|
||||
|
||||
#### Değişiklik 6: Kütüphaneci Hizmeti - Parametreleştirilmiş Anahtar Alanı Kullanımı
|
||||
**Dosya:** `trustgraph-flow/trustgraph/librarian/service.py`
|
||||
|
||||
**Satır 51** - Sabit kodlanmış anahtar alanını kaldır:
|
||||
```python
|
||||
# DELETE THIS LINE:
|
||||
keyspace = "librarian"
|
||||
```
|
||||
|
||||
**Cassandra yapılandırma çözümlemesi güncellendi** (yapılandırma hizmetiyle benzer konumda):
|
||||
```python
|
||||
cassandra_host, cassandra_username, cassandra_password, keyspace = \
|
||||
resolve_cassandra_config(params, default_keyspace="librarian")
|
||||
```
|
||||
|
||||
### 3. Bölüm: Koleksiyon Yönetimini Config Servisine Taşıma
|
||||
|
||||
#### Genel Bakış
|
||||
Koleksiyonları Cassandra librarian anahtar alanından config servisi depolama alanına taşıyın. Bu, sabit kodlanmış depolama yönetimi konularını ortadan kaldırır ve dağıtım için mevcut config push mekanizmasını kullanarak mimariyi basitleştirir.
|
||||
|
||||
#### Mevcut Mimari
|
||||
```
|
||||
API Request → Gateway → Librarian Service
|
||||
↓
|
||||
CollectionManager
|
||||
↓
|
||||
Cassandra Collections Table (librarian keyspace)
|
||||
↓
|
||||
Broadcast to 4 Storage Management Topics (hardcoded)
|
||||
↓
|
||||
Wait for 4+ Storage Service Responses
|
||||
↓
|
||||
Response to Gateway
|
||||
```
|
||||
|
||||
#### Yeni Mimari
|
||||
```
|
||||
API Request → Gateway → Librarian Service
|
||||
↓
|
||||
CollectionManager
|
||||
↓
|
||||
Config Service API (put/delete/getvalues)
|
||||
↓
|
||||
Cassandra Config Table (class='collections', key='user:collection')
|
||||
↓
|
||||
Config Push (to all subscribers on config-push-queue)
|
||||
↓
|
||||
All Storage Services receive config update independently
|
||||
```
|
||||
|
||||
#### Değişiklik 7: Koleksiyon Yöneticisi - Config Hizmeti API'sini Kullanın
|
||||
**Dosya:** `trustgraph-flow/trustgraph/librarian/collection_manager.py`
|
||||
|
||||
**Kaldırılacaklar:**
|
||||
`LibraryTableStore` kullanımı (33, 40-41 satırları)
|
||||
Depolama yönetimi üreticilerinin başlatılması (86-140 satırları)
|
||||
`on_storage_response` metodu (400-430 satırları)
|
||||
`pending_deletions` takibi (57, 90-96 satırları ve tüm kullanım alanları)
|
||||
|
||||
**Eklenecekler:**
|
||||
API çağrıları için Config hizmeti istemcisi (istek/yanıt kalıbı)
|
||||
|
||||
**Config İstemcisi Kurulumu:**
|
||||
```python
|
||||
# In __init__, add config request/response producers/consumers
|
||||
from trustgraph.schema.services.config import ConfigRequest, ConfigResponse
|
||||
|
||||
# Producer for config requests
|
||||
self.config_request_producer = Producer(
|
||||
client=pulsar_client,
|
||||
topic=config_request_queue,
|
||||
schema=ConfigRequest,
|
||||
)
|
||||
|
||||
# Consumer for config responses (with correlation ID)
|
||||
self.config_response_consumer = Consumer(
|
||||
taskgroup=taskgroup,
|
||||
client=pulsar_client,
|
||||
flow=None,
|
||||
topic=config_response_queue,
|
||||
subscriber=f"{id}-config",
|
||||
schema=ConfigResponse,
|
||||
handler=self.on_config_response,
|
||||
)
|
||||
|
||||
# Tracking for pending config requests
|
||||
self.pending_config_requests = {} # request_id -> asyncio.Event
|
||||
```
|
||||
|
||||
**`list_collections`'ı Değiştirin (145-180. satırlar):**
|
||||
```python
|
||||
async def list_collections(self, user, tag_filter=None, limit=None):
|
||||
"""List collections from config service"""
|
||||
# Send getvalues request to config service
|
||||
request = ConfigRequest(
|
||||
id=str(uuid.uuid4()),
|
||||
operation='getvalues',
|
||||
type='collections',
|
||||
)
|
||||
|
||||
# Send request and wait for response
|
||||
response = await self.send_config_request(request)
|
||||
|
||||
# Parse collections from response
|
||||
collections = []
|
||||
for key, value_json in response.values.items():
|
||||
if ":" in key:
|
||||
coll_user, collection = key.split(":", 1)
|
||||
if coll_user == user:
|
||||
metadata = json.loads(value_json)
|
||||
collections.append(CollectionMetadata(**metadata))
|
||||
|
||||
# Apply tag filtering in-memory (as before)
|
||||
if tag_filter:
|
||||
collections = [c for c in collections if any(tag in c.tags for tag in tag_filter)]
|
||||
|
||||
# Apply limit
|
||||
if limit:
|
||||
collections = collections[:limit]
|
||||
|
||||
return collections
|
||||
|
||||
async def send_config_request(self, request):
|
||||
"""Send config request and wait for response"""
|
||||
event = asyncio.Event()
|
||||
self.pending_config_requests[request.id] = event
|
||||
|
||||
await self.config_request_producer.send(request)
|
||||
await event.wait()
|
||||
|
||||
return self.pending_config_requests.pop(request.id + "_response")
|
||||
|
||||
async def on_config_response(self, message, consumer, flow):
|
||||
"""Handle config response"""
|
||||
response = message.value()
|
||||
if response.id in self.pending_config_requests:
|
||||
self.pending_config_requests[response.id + "_response"] = response
|
||||
self.pending_config_requests[response.id].set()
|
||||
```
|
||||
|
||||
**`update_collection`'yi değiştirin (182-312. satırlar):**
|
||||
```python
|
||||
async def update_collection(self, user, collection, name, description, tags):
|
||||
"""Update collection via config service"""
|
||||
# Create metadata
|
||||
metadata = CollectionMetadata(
|
||||
user=user,
|
||||
collection=collection,
|
||||
name=name,
|
||||
description=description,
|
||||
tags=tags,
|
||||
)
|
||||
|
||||
# Send put request to config service
|
||||
request = ConfigRequest(
|
||||
id=str(uuid.uuid4()),
|
||||
operation='put',
|
||||
type='collections',
|
||||
key=f'{user}:{collection}',
|
||||
value=json.dumps(metadata.to_dict()),
|
||||
)
|
||||
|
||||
response = await self.send_config_request(request)
|
||||
|
||||
if response.error:
|
||||
raise RuntimeError(f"Config update failed: {response.error.message}")
|
||||
|
||||
# Config service will trigger config push automatically
|
||||
# Storage services will receive update and create collections
|
||||
```
|
||||
|
||||
**`delete_collection`'ı Değiştirin (314-398. satırlar):**
|
||||
```python
|
||||
async def delete_collection(self, user, collection):
|
||||
"""Delete collection via config service"""
|
||||
# Send delete request to config service
|
||||
request = ConfigRequest(
|
||||
id=str(uuid.uuid4()),
|
||||
operation='delete',
|
||||
type='collections',
|
||||
key=f'{user}:{collection}',
|
||||
)
|
||||
|
||||
response = await self.send_config_request(request)
|
||||
|
||||
if response.error:
|
||||
raise RuntimeError(f"Config delete failed: {response.error.message}")
|
||||
|
||||
# Config service will trigger config push automatically
|
||||
# Storage services will receive update and delete collections
|
||||
```
|
||||
|
||||
**Koleksiyon Meta Veri Formatı:**
|
||||
`config` tablosunda şu şekilde saklanır: `class='collections', key='user:collection'`
|
||||
Değer, zaman damgası alanları olmadan JSON olarak seri hale getirilmiş `CollectionMetadata`'dır.
|
||||
Alanlar: `user`, `collection`, `name`, `description`, `tags`
|
||||
Örnek: `class='collections', key='alice:my-docs', value='{"user":"alice","collection":"my-docs","name":"My Documents","description":"...","tags":["work"]}'`
|
||||
|
||||
#### 8. Değişiklik: Kütüphane Hizmeti - Depolama Yönetimi Altyapısını Kaldır
|
||||
**Dosya:** `trustgraph-flow/trustgraph/librarian/service.py`
|
||||
|
||||
**Kaldır:**
|
||||
Depolama yönetimi üreticileri (173-190. satırlar):
|
||||
`vector_storage_management_producer`
|
||||
`object_storage_management_producer`
|
||||
`triples_storage_management_producer`
|
||||
Depolama yanıt tüketici (192-201. satırlar)
|
||||
`on_storage_response` işleyici (467-473. satırlar)
|
||||
|
||||
**Değiştir:**
|
||||
`CollectionManager` başlatma (215-224. satırlar) - depolama üretici parametrelerini kaldır
|
||||
|
||||
**Not:** Harici koleksiyon API'si değişmeden kalır:
|
||||
`list-collections`
|
||||
`update-collection`
|
||||
`delete-collection`
|
||||
|
||||
#### 9. Değişiklik: Koleksiyonlar Tablosunu `LibraryTableStore`'dan Kaldır
|
||||
**Dosya:** `trustgraph-flow/trustgraph/tables/library.py`
|
||||
|
||||
**Sil:**
|
||||
Koleksiyonlar tablosu `CREATE` ifadesi (114-127. satırlar)
|
||||
Koleksiyonlar için hazırlanmış ifadeler (205-240. satırlar)
|
||||
Tüm koleksiyon metotları (578-717. satırlar):
|
||||
`ensure_collection_exists`
|
||||
`list_collections`
|
||||
`update_collection`
|
||||
`delete_collection`
|
||||
`get_collection`
|
||||
`create_collection`
|
||||
|
||||
**Gerekçe:**
|
||||
Koleksiyonlar artık `config` tablosunda saklanıyor
|
||||
Uyumluluk bozan bir değişiklik kabul edilebilir - veri taşıma işlemine gerek yok
|
||||
Kütüphane hizmetini önemli ölçüde basitleştirir
|
||||
|
||||
#### 10. Değişiklik: Depolama Hizmetleri - Yapılandırmaya Dayalı Koleksiyon Yönetimi ✅ TAMAMLANDI
|
||||
|
||||
**Durum:** 11 depolama arka ucunun tamamı, `CollectionConfigHandler`'ı kullanmak üzere güncellendi.
|
||||
|
||||
**Etkilenen Hizmetler (toplam 11):**
|
||||
Belge gömülüleri: milvus, pinecone, qdrant
|
||||
Grafik gömülüleri: milvus, pinecone, qdrant
|
||||
Nesne depolama: cassandra
|
||||
Üçlü depolama: cassandra, falkordb, memgraph, neo4j
|
||||
|
||||
**Dosyalar:**
|
||||
`trustgraph-flow/trustgraph/storage/doc_embeddings/milvus/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/doc_embeddings/pinecone/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/doc_embeddings/qdrant/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/graph_embeddings/milvus/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/graph_embeddings/pinecone/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/graph_embeddings/qdrant/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/objects/cassandra/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/triples/cassandra/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/triples/falkordb/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/triples/memgraph/write.py`
|
||||
`trustgraph-flow/trustgraph/storage/triples/neo4j/write.py`
|
||||
|
||||
**Uygulama Deseni (tüm hizmetler):**
|
||||
|
||||
1. **Yapılandırma işleyiciyi `__init__` içinde kaydedin:**
|
||||
```python
|
||||
# Add after AsyncProcessor initialization
|
||||
self.register_config_handler(self.on_collection_config)
|
||||
self.known_collections = set() # Track (user, collection) tuples
|
||||
```
|
||||
|
||||
2. **Yapılandırma yöneticisini uygulayın:**
|
||||
```python
|
||||
async def on_collection_config(self, config, version):
|
||||
"""Handle collection configuration updates"""
|
||||
logger.info(f"Collection config version: {version}")
|
||||
|
||||
if "collections" not in config:
|
||||
return
|
||||
|
||||
# Parse collections from config
|
||||
# Key format: "user:collection" in config["collections"]
|
||||
config_collections = set()
|
||||
for key in config["collections"].keys():
|
||||
if ":" in key:
|
||||
user, collection = key.split(":", 1)
|
||||
config_collections.add((user, collection))
|
||||
|
||||
# Determine changes
|
||||
to_create = config_collections - self.known_collections
|
||||
to_delete = self.known_collections - config_collections
|
||||
|
||||
# Create new collections (idempotent)
|
||||
for user, collection in to_create:
|
||||
try:
|
||||
await self.create_collection_internal(user, collection)
|
||||
self.known_collections.add((user, collection))
|
||||
logger.info(f"Created collection: {user}/{collection}")
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to create {user}/{collection}: {e}")
|
||||
|
||||
# Delete removed collections (idempotent)
|
||||
for user, collection in to_delete:
|
||||
try:
|
||||
await self.delete_collection_internal(user, collection)
|
||||
self.known_collections.discard((user, collection))
|
||||
logger.info(f"Deleted collection: {user}/{collection}")
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to delete {user}/{collection}: {e}")
|
||||
```
|
||||
|
||||
3. **Başlangıçta bilinen koleksiyonları başlatın:**
|
||||
```python
|
||||
async def start(self):
|
||||
"""Start the processor"""
|
||||
await super().start()
|
||||
await self.sync_known_collections()
|
||||
|
||||
async def sync_known_collections(self):
|
||||
"""Query backend to populate known_collections set"""
|
||||
# Backend-specific implementation:
|
||||
# - Milvus/Pinecone/Qdrant: List collections/indexes matching naming pattern
|
||||
# - Cassandra: Query keyspaces or collection metadata
|
||||
# - Neo4j/Memgraph/FalkorDB: Query CollectionMetadata nodes
|
||||
pass
|
||||
```
|
||||
|
||||
4. **Mevcut işleyici metotları yeniden düzenleyin:**
|
||||
```python
|
||||
# Rename and remove response sending:
|
||||
# handle_create_collection → create_collection_internal
|
||||
# handle_delete_collection → delete_collection_internal
|
||||
|
||||
async def create_collection_internal(self, user, collection):
|
||||
"""Create collection (idempotent)"""
|
||||
# Same logic as current handle_create_collection
|
||||
# But remove response producer calls
|
||||
# Handle "already exists" gracefully
|
||||
pass
|
||||
|
||||
async def delete_collection_internal(self, user, collection):
|
||||
"""Delete collection (idempotent)"""
|
||||
# Same logic as current handle_delete_collection
|
||||
# But remove response producer calls
|
||||
# Handle "not found" gracefully
|
||||
pass
|
||||
```
|
||||
|
||||
5. **Depolama yönetimi altyapısını kaldırın:**
|
||||
`self.storage_request_consumer` kurulumunu ve başlatmayı kaldırın
|
||||
`self.storage_response_producer` kurulumunu kaldırın
|
||||
`on_storage_management` dağıtıcı yöntemini kaldırın
|
||||
Depolama yönetimi için metrikleri kaldırın
|
||||
Aşağıdaki import'ları kaldırın: `StorageManagementRequest`, `StorageManagementResponse`
|
||||
|
||||
**Arka Uç Özel Hususlar:**
|
||||
|
||||
**Vektör depoları (Milvus, Pinecone, Qdrant):** `known_collections` içinde mantıksal `(user, collection)`'ı takip edin, ancak her boyut için birden fazla arka uç koleksiyonu oluşturabilir. Tembel oluşturma modeline devam edin. Silme işlemleri, tüm boyut varyantlarını kaldırmalıdır.
|
||||
|
||||
**Cassandra Nesneleri:** Koleksiyonlar, yapılar değil, satır özellikleridir. Veritabanı seviyesindeki bilgileri takip edin.
|
||||
|
||||
**Grafik depoları (Neo4j, Memgraph, FalkorDB):** Başlangıçta `CollectionMetadata` düğümlerini sorgulayın. Senkronizasyon sırasında meta veri düğümlerini oluşturun/silin.
|
||||
|
||||
**Cassandra Üçlüleri:** Koleksiyon işlemleri için `KnowledgeGraph` API'sini kullanın.
|
||||
|
||||
**Temel Tasarım Noktaları:**
|
||||
|
||||
**Son tutarlılık:** İstek/yanıt mekanizması yoktur, yapılandırma itmesi yayınlanır
|
||||
**Tekrarlanabilirlik:** Tüm oluşturma/silme işlemleri, yeniden denenmek üzere güvenli olmalıdır
|
||||
**Hata işleme:** Hataları günlüğe kaydedin, ancak yapılandırma güncellemelerini engellemeyin
|
||||
**Kendini iyileştirme:** Başarısız işlemler, bir sonraki yapılandırma itmesinde yeniden denenecektir
|
||||
**Koleksiyon anahtar biçimi:** `config["collections"]` içinde `"user:collection"`
|
||||
|
||||
#### Değişiklik 11: Koleksiyon Şemasını Güncelle - Zaman Damgalarını Kaldır
|
||||
**Dosya:** `trustgraph-base/trustgraph/schema/services/collection.py`
|
||||
|
||||
**CollectionMetadata'ı değiştirin (Satırlar 13-21):**
|
||||
Aşağıdaki alanları kaldırın: `created_at` ve `updated_at`:
|
||||
```python
|
||||
class CollectionMetadata(Record):
|
||||
user = String()
|
||||
collection = String()
|
||||
name = String()
|
||||
description = String()
|
||||
tags = Array(String())
|
||||
# Remove: created_at = String()
|
||||
# Remove: updated_at = String()
|
||||
```
|
||||
|
||||
**CollectionManagementRequest'i Değiştir (25-47. satırlar):**
|
||||
Zaman damgası alanlarını kaldır:
|
||||
```python
|
||||
class CollectionManagementRequest(Record):
|
||||
operation = String()
|
||||
user = String()
|
||||
collection = String()
|
||||
timestamp = String()
|
||||
name = String()
|
||||
description = String()
|
||||
tags = Array(String())
|
||||
# Remove: created_at = String()
|
||||
# Remove: updated_at = String()
|
||||
tag_filter = Array(String())
|
||||
limit = Integer()
|
||||
```
|
||||
|
||||
**Gerekçe:**
|
||||
Zaman damgaları, koleksiyonlar için değer katmaz.
|
||||
Yapılandırma hizmeti, kendi sürüm takibini yapar.
|
||||
Şemayı basitleştirir ve depolama alanını azaltır.
|
||||
|
||||
#### Yapılandırma Hizmeti Geçişinin Faydaları
|
||||
|
||||
1. ✅ **Sabit kodlanmış depolama yönetimi konularını ortadan kaldırır** - Çok kiracılı sorunu çözer.
|
||||
2. ✅ **Daha basit koordinasyon** - 4 veya daha fazla depolama yanıtı için karmaşık asenkron beklemeler olmaz.
|
||||
3. ✅ **Sonunda tutarlılık** - Depolama hizmetleri, yapılandırma itme yoluyla bağımsız olarak güncellenir.
|
||||
4. ✅ **Daha iyi güvenilirlik** - Kalıcı yapılandırma itme, kalıcı olmayan istek/yanıt yerine.
|
||||
5. ✅ **Birleşik yapılandırma modeli** - Koleksiyonlar, yapılandırma olarak ele alınır.
|
||||
6. ✅ **Karmaşıklığı azaltır** - Yaklaşık 300 satır koordinasyon kodunu kaldırır.
|
||||
7. ✅ **Çok kiracılı için hazır** - Yapılandırma, anahtar alanı aracılığıyla zaten kiracı izolasyonunu destekler.
|
||||
8. ✅ **Sürüm takibi** - Yapılandırma hizmeti sürüm mekanizması, denetim izi sağlar.
|
||||
|
||||
## Uygulama Notları
|
||||
|
||||
### Geriye Dönük Uyumluluk
|
||||
|
||||
**Parametre Değişiklikleri:**
|
||||
CLI parametrelerinin yeniden adlandırılması, bozucu değişikliklerdir ancak kabul edilebilir (özellik şu anda çalışmıyor).
|
||||
Hizmetler parametreler olmadan çalışır (varsayılanları kullanır).
|
||||
Varsayılan anahtar alanları korunur: "config", "knowledge", "librarian".
|
||||
Varsayılan kuyruk: `persistent://tg/config/config`
|
||||
|
||||
**Koleksiyon Yönetimi:**
|
||||
**Bozucu değişiklik:** Koleksiyon tablosu, "librarian" anahtar alanından kaldırılmıştır.
|
||||
**Veri geçişi sağlanmamıştır** - bu aşama için kabul edilebilir.
|
||||
Harici koleksiyon API'si değişmemiştir (listeleme/güncelleme/silme işlemleri).
|
||||
Koleksiyon meta veri biçimi basitleştirilmiştir (zaman damgaları kaldırılmıştır).
|
||||
|
||||
### Test Gereksinimleri
|
||||
|
||||
**Parametre Testi:**
|
||||
1. `--config-push-queue` parametresinin "graph-embeddings" hizmetinde çalıştığını doğrulayın.
|
||||
2. `--config-push-queue` parametresinin "text-completion" hizmetinde çalıştığını doğrulayın.
|
||||
3. `--config-push-queue` parametresinin yapılandırma hizmetinde çalıştığını doğrulayın.
|
||||
4. `--cassandra-keyspace` parametresinin yapılandırma hizmeti için çalıştığını doğrulayın.
|
||||
5. `--cassandra-keyspace` parametresinin "cores" hizmeti için çalıştığını doğrulayın.
|
||||
6. `--cassandra-keyspace` parametresinin "librarian" hizmeti için çalıştığını doğrulayın.
|
||||
7. Hizmetlerin parametreler olmadan çalıştığını (varsayılanları kullandığını) doğrulayın.
|
||||
8. Özel kuyruk adları ve anahtar alanı ile çok kiracılı dağıtımı doğrulayın.
|
||||
|
||||
**Koleksiyon Yönetimi Testi:**
|
||||
9. `list-collections` işlemini yapılandırma hizmeti aracılığıyla doğrulayın.
|
||||
10. `update-collection`'ın yapılandırma tablosunda oluşturulduğunu/güncellendiğini doğrulayın.
|
||||
11. `delete-collection`'ın yapılandırma tablosundan kaldırıldığını doğrulayın.
|
||||
12. Koleksiyon güncellemelerinde yapılandırma itmesinin tetiklendiğini doğrulayın.
|
||||
13. Etiket filtrelemenin yapılandırma tabanlı depolama ile çalıştığını doğrulayın.
|
||||
14. Koleksiyon işlemlerinin zaman damgası alanları olmadan çalıştığını doğrulayın.
|
||||
|
||||
### Çok Kiracılı Dağıtım Örneği
|
||||
```bash
|
||||
# Tenant: tg-dev
|
||||
graph-embeddings \
|
||||
-p pulsar+ssl://broker:6651 \
|
||||
--pulsar-api-key <KEY> \
|
||||
--config-push-queue persistent://tg-dev/config/config
|
||||
|
||||
config-service \
|
||||
-p pulsar+ssl://broker:6651 \
|
||||
--pulsar-api-key <KEY> \
|
||||
--config-push-queue persistent://tg-dev/config/config \
|
||||
--cassandra-keyspace tg_dev_config
|
||||
```
|
||||
|
||||
## Etki Analizi
|
||||
|
||||
### 1-2 Değişikliklerinden Etkilenen Hizmetler (CLI Parametre Adı Değişikliği)
|
||||
AsyncProcessor veya FlowProcessor'dan türeyen tüm hizmetler:
|
||||
config-service
|
||||
cores-service
|
||||
librarian-service
|
||||
graph-embeddings
|
||||
document-embeddings
|
||||
text-completion-* (tüm sağlayıcılar)
|
||||
extract-* (tüm çıkarıcılar)
|
||||
query-* (tüm sorgu hizmetleri)
|
||||
retrieval-* (tüm RAG hizmetleri)
|
||||
storage-* (tüm depolama hizmetleri)
|
||||
Ve 20'den fazla hizmet daha
|
||||
|
||||
### 3-6 Değişikliklerinden Etkilenen Hizmetler (Cassandra Keyspace)
|
||||
config-service
|
||||
cores-service
|
||||
librarian-service
|
||||
|
||||
### 7-11 Değişikliklerinden Etkilenen Hizmetler (Koleksiyon Yönetimi)
|
||||
|
||||
**Hızlı Uygulanacak Değişiklikler:**
|
||||
librarian-service (collection_manager.py, service.py)
|
||||
tables/library.py (collections tablosunun kaldırılması)
|
||||
schema/services/collection.py (zaman damgası kaldırma)
|
||||
|
||||
**Tamamlanan Değişiklikler (Değişiklik 10):** ✅
|
||||
Tüm depolama hizmetleri (toplam 11) - `CollectionConfigHandler` üzerinden koleksiyon güncellemeleri için yapılandırma itme işlemine geçirildi
|
||||
Depolama yönetimi şeması `storage.py`'dan kaldırıldı
|
||||
|
||||
## Gelecek Hususlar
|
||||
|
||||
### Kullanıcı Başına Keyspace Modeli
|
||||
|
||||
Bazı hizmetler, her kullanıcının kendi Cassandra keyspace'ine sahip olduğu **kullanıcı başına keyspace**'leri dinamik olarak kullanır:
|
||||
|
||||
**Kullanıcı başına keyspace kullanan hizmetler:**
|
||||
1. **Triples Sorgu Hizmeti** (`trustgraph-flow/trustgraph/query/triples/cassandra/service.py:65`)
|
||||
`keyspace=query.user` kullanır
|
||||
2. **Objects Sorgu Hizmeti** (`trustgraph-flow/trustgraph/query/objects/cassandra/service.py:479`)
|
||||
`keyspace=self.sanitize_name(user)` kullanır
|
||||
3. **KnowledgeGraph Doğrudan Erişim** (`trustgraph-flow/trustgraph/direct/cassandra_kg.py:18`)
|
||||
Varsayılan parametre `keyspace="trustgraph"`
|
||||
|
||||
**Durum:** Bu, bu belirtimde **değiştirilmemiştir**.
|
||||
|
||||
**Gelecekte İnceleme Gerekli:**
|
||||
Kullanıcı başına keyspace modelinin kiracı izolasyonu sorunlarına neden olup olmadığını değerlendirin
|
||||
Çok kiracılı dağıtımların keyspace önek kalıplarına (örneğin, `tenant_a_user1`) ihtiyaç duyup duymadığını düşünün
|
||||
Kiracılar arasında potansiyel kullanıcı kimliği çakışmalarını gözden geçirin
|
||||
Tek, paylaşılan keyspace'in, kullanıcı tabanlı satır izolasyonu ile birlikte daha mı tercih edilebilir olduğunu değerlendirin
|
||||
|
||||
**Not:** Bu, mevcut çok kiracılı uygulamayı engellemez, ancak üretim çok kiracılı dağıtımlardan önce incelenmelidir.
|
||||
|
||||
## Uygulama Aşamaları
|
||||
|
||||
### Aşama 1: Parametre Düzeltmeleri (Değişiklikler 1-6)
|
||||
`--config-push-queue` parametre adlandırmasını düzeltin
|
||||
`--cassandra-keyspace` parametre desteğini ekleyin
|
||||
**Sonuç:** Çok kiracılı kuyruk ve keyspace yapılandırması etkinleştirildi
|
||||
|
||||
### Aşama 2: Koleksiyon Yönetimi Geçişi (Değişiklikler 7-9, 11)
|
||||
Koleksiyon depolamasını yapılandırma hizmetine geçirin
|
||||
librarian'dan koleksiyon tablosunu kaldırın
|
||||
Koleksiyon şemasını güncelleyin (zaman damgalarını kaldırın)
|
||||
**Sonuç:** Sabit kodlu depolama yönetimi konuları ortadan kaldırılır, librarian basitleştirilir
|
||||
|
||||
### Aşama 3: Depolama Hizmeti Güncellemeleri (Değişiklik 10) ✅ TAMAMLANDI
|
||||
Tüm depolama hizmetlerini koleksiyonlar için yapılandırma itme işlemine almak için güncelleyin `CollectionConfigHandler`
|
||||
Depolama yönetimi istek/yanıt altyapısını kaldırın
|
||||
Eski şema tanımlarını kaldırın
|
||||
**Sonuç:** Tamamen yapılandırmaya dayalı koleksiyon yönetimi elde edildi
|
||||
|
||||
## Referanslar
|
||||
GitHub Sorunu: https://github.com/trustgraph-ai/trustgraph/issues/582
|
||||
İlgili Dosyalar:
|
||||
`trustgraph-base/trustgraph/base/async_processor.py`
|
||||
`trustgraph-base/trustgraph/base/cassandra_config.py`
|
||||
`trustgraph-base/trustgraph/schema/core/topic.py`
|
||||
`trustgraph-base/trustgraph/schema/services/collection.py`
|
||||
`trustgraph-flow/trustgraph/config/service/service.py`
|
||||
`trustgraph-flow/trustgraph/cores/service.py`
|
||||
`trustgraph-flow/trustgraph/librarian/service.py`
|
||||
`trustgraph-flow/trustgraph/librarian/collection_manager.py`
|
||||
`trustgraph-flow/trustgraph/tables/library.py`
|
||||
367
docs/tech-specs/tr/neo4j-user-collection-isolation.tr.md
Normal file
367
docs/tech-specs/tr/neo4j-user-collection-isolation.tr.md
Normal file
|
|
@ -0,0 +1,367 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Neo4j Kullanıcı/Koleksiyon İzolasyonu Desteği"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Neo4j Kullanıcı/Koleksiyon İzolasyonu Desteği
|
||||
|
||||
> **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.
|
||||
|
||||
## Problem Tanımı
|
||||
|
||||
Mevcut Neo4j üçlü depolama ve sorgu uygulaması, kullanıcı/koleksiyon izolasyonu eksikliği nedeniyle çoklu kiracılık güvenliği sorunlarına yol açmaktadır. Tüm üçlüler, kullanıcıların diğer kullanıcıların verilerine erişmesini veya koleksiyonları karıştırmasını engelleyen herhangi bir mekanizma olmadan aynı grafik alanında saklanmaktadır.
|
||||
|
||||
TrustGraph'taki diğer depolama arka uçlarından farklı olarak:
|
||||
**Cassandra**: Her kullanıcı için ayrı anahtarlar ve her koleksiyon için tablolar kullanır.
|
||||
**Vektör depoları** (Milvus, Qdrant, Pinecone): Koleksiyona özgü ad alanlarını kullanır.
|
||||
**Neo4j**: Şu anda tüm verileri tek bir grafik alanında paylaşır (güvenlik açığı).
|
||||
|
||||
## Mevcut Mimari
|
||||
|
||||
### Veri Modeli
|
||||
**Düğümler**: `:Node` etiketi ile `uri` özelliği, `:Literal` etiketi ile `value` özelliği.
|
||||
**İlişkiler**: `:Rel` etiketi ile `uri` özelliği.
|
||||
**Dizinler**: `Node.uri`, `Literal.value`, `Rel.uri`.
|
||||
|
||||
### Mesaj Akışı
|
||||
`Triples` mesajları `metadata.user` ve `metadata.collection` alanlarını içerir.
|
||||
Depolama hizmeti kullanıcı/koleksiyon bilgilerini alır, ancak bunları yoksayar.
|
||||
Sorgu hizmeti `TriplesQueryRequest` içinde `user` ve `collection`'i bekler, ancak bunları yoksayar.
|
||||
|
||||
### Mevcut Güvenlik Sorunu
|
||||
```cypher
|
||||
# Any user can query any data - no isolation
|
||||
MATCH (src:Node)-[rel:Rel]->(dest:Node)
|
||||
RETURN src.uri, rel.uri, dest.uri
|
||||
```
|
||||
|
||||
## Önerilen Çözüm: Özellik Tabanlı Filtreleme (Önerilen)
|
||||
|
||||
### Genel Bakış
|
||||
Tüm düğümlere ve ilişkilerlere `user` ve `collection` özelliklerini ekleyin, ardından tüm işlemleri bu özelliklere göre filtreleyin. Bu yaklaşım, güçlü bir izolasyon sağlarken sorgu esnekliğini ve geriye dönük uyumluluğu korur.
|
||||
|
||||
### Veri Modeli Değişiklikleri
|
||||
|
||||
#### Gelişmiş Düğüm Yapısı
|
||||
```cypher
|
||||
// Node entities
|
||||
CREATE (n:Node {
|
||||
uri: "http://example.com/entity1",
|
||||
user: "john_doe",
|
||||
collection: "production_v1"
|
||||
})
|
||||
|
||||
// Literal entities
|
||||
CREATE (n:Literal {
|
||||
value: "literal value",
|
||||
user: "john_doe",
|
||||
collection: "production_v1"
|
||||
})
|
||||
```
|
||||
|
||||
#### Gelişmiş İlişki Yapısı
|
||||
```cypher
|
||||
// Relationships with user/collection properties
|
||||
CREATE (src)-[:Rel {
|
||||
uri: "http://example.com/predicate1",
|
||||
user: "john_doe",
|
||||
collection: "production_v1"
|
||||
}]->(dest)
|
||||
```
|
||||
|
||||
#### Güncellenmiş İndeksler
|
||||
```cypher
|
||||
// Compound indexes for efficient filtering
|
||||
CREATE INDEX node_user_collection_uri FOR (n:Node) ON (n.user, n.collection, n.uri);
|
||||
CREATE INDEX literal_user_collection_value FOR (n:Literal) ON (n.user, n.collection, n.value);
|
||||
CREATE INDEX rel_user_collection_uri FOR ()-[r:Rel]-() ON (r.user, r.collection, r.uri);
|
||||
|
||||
// Maintain existing indexes for backwards compatibility (optional)
|
||||
CREATE INDEX Node_uri FOR (n:Node) ON (n.uri);
|
||||
CREATE INDEX Literal_value FOR (n:Literal) ON (n.value);
|
||||
CREATE INDEX Rel_uri FOR ()-[r:Rel]-() ON (r.uri);
|
||||
```
|
||||
|
||||
### Uygulama Değişiklikleri
|
||||
|
||||
#### Depolama Hizmeti (`write.py`)
|
||||
|
||||
**Mevcut Kod:**
|
||||
```python
|
||||
def create_node(self, uri):
|
||||
summary = self.io.execute_query(
|
||||
"MERGE (n:Node {uri: $uri})",
|
||||
uri=uri, database_=self.db,
|
||||
).summary
|
||||
```
|
||||
|
||||
**Güncellenmiş Kod:**
|
||||
```python
|
||||
def create_node(self, uri, user, collection):
|
||||
summary = self.io.execute_query(
|
||||
"MERGE (n:Node {uri: $uri, user: $user, collection: $collection})",
|
||||
uri=uri, user=user, collection=collection, database_=self.db,
|
||||
).summary
|
||||
```
|
||||
|
||||
**Geliştirilmiş `store_triples` Metodu:**
|
||||
```python
|
||||
async def store_triples(self, message):
|
||||
user = message.metadata.user
|
||||
collection = message.metadata.collection
|
||||
|
||||
for t in message.triples:
|
||||
self.create_node(t.s.value, user, collection)
|
||||
|
||||
if t.o.is_uri:
|
||||
self.create_node(t.o.value, user, collection)
|
||||
self.relate_node(t.s.value, t.p.value, t.o.value, user, collection)
|
||||
else:
|
||||
self.create_literal(t.o.value, user, collection)
|
||||
self.relate_literal(t.s.value, t.p.value, t.o.value, user, collection)
|
||||
```
|
||||
|
||||
#### Sorgu Hizmeti (`service.py`)
|
||||
|
||||
**Mevcut Kod:**
|
||||
```python
|
||||
records, summary, keys = self.io.execute_query(
|
||||
"MATCH (src:Node {uri: $src})-[rel:Rel {uri: $rel}]->(dest:Node) "
|
||||
"RETURN dest.uri as dest",
|
||||
src=query.s.value, rel=query.p.value, database_=self.db,
|
||||
)
|
||||
```
|
||||
|
||||
**Güncellenmiş Kod:**
|
||||
```python
|
||||
records, summary, keys = self.io.execute_query(
|
||||
"MATCH (src:Node {uri: $src, user: $user, collection: $collection})-"
|
||||
"[rel:Rel {uri: $rel, user: $user, collection: $collection}]->"
|
||||
"(dest:Node {user: $user, collection: $collection}) "
|
||||
"RETURN dest.uri as dest",
|
||||
src=query.s.value, rel=query.p.value,
|
||||
user=query.user, collection=query.collection,
|
||||
database_=self.db,
|
||||
)
|
||||
```
|
||||
|
||||
### Göç Stratejisi
|
||||
|
||||
#### 1. Aşama: Yeni Verilere Özellikler Ekleme
|
||||
1. Kullanıcı/koleksiyon özelliklerini yeni üçlülere eklemek için depolama hizmetini güncelleyin.
|
||||
2. Geriye dönük uyumluluğu korumak için sorgularda özelliklerin gerekli olmaması.
|
||||
3. Mevcut veriler erişilebilir durumda kalır, ancak izole edilmez.
|
||||
|
||||
#### 2. Aşama: Mevcut Verilerin Taşınması
|
||||
```cypher
|
||||
// Migrate existing nodes (requires default user/collection assignment)
|
||||
MATCH (n:Node) WHERE n.user IS NULL
|
||||
SET n.user = 'legacy_user', n.collection = 'default_collection';
|
||||
|
||||
MATCH (n:Literal) WHERE n.user IS NULL
|
||||
SET n.user = 'legacy_user', n.collection = 'default_collection';
|
||||
|
||||
MATCH ()-[r:Rel]->() WHERE r.user IS NULL
|
||||
SET r.user = 'legacy_user', r.collection = 'default_collection';
|
||||
```
|
||||
|
||||
#### 3. Aşama: İzolasyonu Sağlama
|
||||
1. Sorgu hizmetini, kullanıcı/koleksiyon filtrelemesini gerektirecek şekilde güncelleyin.
|
||||
2. Doğru kullanıcı/koleksiyon bağlamı olmadan yapılan sorguları reddedecek doğrulama ekleyin.
|
||||
3. Eski veri erişim yollarını kaldırın.
|
||||
|
||||
### Güvenlik Hususları
|
||||
|
||||
#### Sorgu Doğrulama
|
||||
```python
|
||||
async def query_triples(self, query):
|
||||
# Validate user/collection parameters
|
||||
if not query.user or not query.collection:
|
||||
raise ValueError("User and collection must be specified")
|
||||
|
||||
# All queries must include user/collection filters
|
||||
# ... rest of implementation
|
||||
```
|
||||
|
||||
#### Parametre Enjeksiyonunu Önleme
|
||||
Yalnızca parametreli sorguları kullanın
|
||||
Kullanıcı/toplam değerlerini izin verilen kalıplara karşı doğrulayın
|
||||
Neo4j özellik adı gereksinimleri için sanitizasyonu göz önünde bulundurun
|
||||
|
||||
#### Denetim Kaydı
|
||||
```python
|
||||
logger.info(f"Query executed - User: {query.user}, Collection: {query.collection}, "
|
||||
f"Pattern: {query.s}/{query.p}/{query.o}")
|
||||
```
|
||||
|
||||
## Alternatif Yaklaşımlar
|
||||
|
||||
### Seçenek 2: Etiket Tabanlı İzolasyon
|
||||
|
||||
**Yaklaşım**: Dinamik etiketler kullanın, örneğin `User_john_Collection_prod`
|
||||
|
||||
**Avantajları:**
|
||||
Etiket filtreleme yoluyla güçlü izolasyon
|
||||
Etiket indeksleriyle verimli sorgu performansı
|
||||
Açık veri ayrımı
|
||||
|
||||
**Dezavantajları:**
|
||||
Neo4j'nin etiket sayısı konusunda pratik sınırlamaları vardır (~1000'ler)
|
||||
Karmaşık etiket adı oluşturma ve temizleme
|
||||
Gerekli olduğunda koleksiyonlar arasında sorgu yapmak zordur
|
||||
|
||||
**Uygulama Örneği:**
|
||||
```cypher
|
||||
CREATE (n:Node:User_john_Collection_prod {uri: "http://example.com/entity"})
|
||||
MATCH (n:User_john_Collection_prod) WHERE n:Node RETURN n
|
||||
```
|
||||
|
||||
### Seçenek 3: Kullanıcı Başına Veritabanı
|
||||
|
||||
**Yaklaşım:** Her kullanıcı veya kullanıcı/koleksiyon kombinasyonu için ayrı Neo4j veritabanları oluşturun.
|
||||
|
||||
**Avantajları:**
|
||||
Tam veri izolasyonu
|
||||
Çapraz bulaşma riski yok
|
||||
Kullanıcı başına bağımsız ölçeklendirme
|
||||
|
||||
**Dezavantajları:**
|
||||
Kaynak yükü (her veritabanı bellek tüketir)
|
||||
Karmaşık veritabanı yaşam döngüsü yönetimi
|
||||
Neo4j Community Edition veritabanı limitleri
|
||||
Kullanıcılar arası analizler yapmak zordur.
|
||||
|
||||
### Seçenek 4: Bileşik Anahtar Stratejisi
|
||||
|
||||
**Yaklaşım:** Tüm URI'ları ve değerleri kullanıcı/koleksiyon bilgileriyle ön ekleyin.
|
||||
|
||||
**Avantajları:**
|
||||
Mevcut sorgularla geriye dönük uyumluluk
|
||||
Basit uygulama
|
||||
Şema değişiklikleri gerektirmez
|
||||
|
||||
**Dezavantajları:**
|
||||
URI kirliliği, veri anlamını etkiler
|
||||
Daha az verimli sorgular (dize ön eki eşleştirme)
|
||||
RDF/semantik web standartlarını ihlal eder
|
||||
|
||||
**Uygulama Örneği:**
|
||||
```python
|
||||
def make_composite_uri(uri, user, collection):
|
||||
return f"usr:{user}:col:{collection}:uri:{uri}"
|
||||
```
|
||||
|
||||
## Uygulama Planı
|
||||
|
||||
### Aşama 1: Temel (1. Hafta)
|
||||
1. [ ] Depolama hizmetini, kullanıcı/koleksiyon özelliklerini kabul edecek ve saklayacak şekilde güncelleyin.
|
||||
2. [ ] Verimli sorgulama için bileşik indeksler ekleyin.
|
||||
3. [ ] Geriye dönük uyumluluk katmanı uygulayın.
|
||||
4. [ ] Yeni işlevler için birim testleri oluşturun.
|
||||
|
||||
### Aşama 2: Sorgu Güncellemeleri (2. Hafta)
|
||||
1. [ ] Tüm sorgu kalıplarını, kullanıcı/koleksiyon filtrelerini içerecek şekilde güncelleyin.
|
||||
2. [ ] Sorgu doğrulaması ve güvenlik kontrolleri ekleyin.
|
||||
3. [ ] Entegrasyon testlerini güncelleyin.
|
||||
4. [ ] Filtrelenmiş sorgularla performans testi yapın.
|
||||
|
||||
### Aşama 3: Göç ve Dağıtım (3. Hafta)
|
||||
1. [ ] Mevcut Neo4j örnekleri için veri geçiş betikleri oluşturun.
|
||||
2. [ ] Dağıtım belgeleri ve çalıştırma kılavuzları.
|
||||
3. [ ] İzolasyon ihlalleri için izleme ve uyarı.
|
||||
4. [ ] Çok sayıda kullanıcı/koleksiyonla uçtan uca testler yapın.
|
||||
|
||||
### Aşama 4: Güçlendirme (4. Hafta)
|
||||
1. [ ] Eski uyumluluk modunu kaldırın.
|
||||
2. [ ] Kapsamlı denetim kaydı ekleyin.
|
||||
3. [ ] Güvenlik incelemesi ve sızma testi.
|
||||
4. [ ] Performans optimizasyonu.
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
### Birim Testleri
|
||||
```python
|
||||
def test_user_collection_isolation():
|
||||
# Store triples for user1/collection1
|
||||
processor.store_triples(triples_user1_coll1)
|
||||
|
||||
# Store triples for user2/collection2
|
||||
processor.store_triples(triples_user2_coll2)
|
||||
|
||||
# Query as user1 should only return user1's data
|
||||
results = processor.query_triples(query_user1_coll1)
|
||||
assert all_results_belong_to_user1_coll1(results)
|
||||
|
||||
# Query as user2 should only return user2's data
|
||||
results = processor.query_triples(query_user2_coll2)
|
||||
assert all_results_belong_to_user2_coll2(results)
|
||||
```
|
||||
|
||||
### Entegrasyon Testleri
|
||||
Eş zamanlı veri içeren çok kullanıcılı senaryolar
|
||||
Koleksiyonlar arası sorgular (başarısız olmalıdır)
|
||||
Mevcut verilerle yapılan geçiş testleri
|
||||
Büyük veri kümeleriyle yapılan performans ölçümleri
|
||||
|
||||
### Güvenlik Testleri
|
||||
Diğer kullanıcıların verilerine erişme girişimleri
|
||||
Kullanıcı/koleksiyon parametrelerine yönelik SQL enjeksiyonu tarzı saldırılar
|
||||
Çeşitli sorgu kalıpları altında tam izolasyonu doğrulayın
|
||||
|
||||
## Performans Hususları
|
||||
|
||||
### İndeks Stratejisi
|
||||
Optimum filtreleme için `(user, collection, uri)` üzerinde birleşik indeksler
|
||||
Bazı koleksiyonların çok daha büyük olması durumunda, kısmi indeksleri göz önünde bulundurun
|
||||
İndeks kullanımını ve sorgu performansını izleyin
|
||||
|
||||
### Sorgu Optimizasyonu
|
||||
Filtrelenmiş sorgularda indeks kullanımını doğrulamak için EXPLAIN'i kullanın
|
||||
Sık erişilen veriler için sorgu sonucu önbelleklemesini göz önünde bulundurun
|
||||
Çok sayıda kullanıcı/koleksiyonla bellek kullanımını analiz edin
|
||||
|
||||
### Ölçeklenebilirlik
|
||||
Her kullanıcı/koleksiyon kombinasyonu, ayrı veri adacıkları oluşturur
|
||||
Veritabanı boyutunu ve bağlantı havuzu kullanımını izleyin
|
||||
Gerekirse, yatay ölçeklendirme stratejilerini göz önünde bulundurun
|
||||
|
||||
## Güvenlik ve Uyumluluk
|
||||
|
||||
### Veri İzolasyon Garantileri
|
||||
**Fiziksel**: Tüm kullanıcı verileri, açık kullanıcı/koleksiyon özellikleri ile saklanır
|
||||
**Mantıksal**: Tüm sorgular, kullanıcı/koleksiyon bağlamıyla filtrelenir
|
||||
**Erişim Kontrolü**: Hizmet seviyesindeki doğrulama, yetkisiz erişimi engeller
|
||||
|
||||
### Denetim Gereksinimleri
|
||||
Tüm veri erişimlerini kullanıcı/koleksiyon bağlamıyla kaydedin
|
||||
Geçiş etkinliklerini ve veri hareketlerini izleyin
|
||||
İzolasyon ihlali girişimlerini izleyin
|
||||
|
||||
### Uyumluluk Hususları
|
||||
GDPR: Kullanıcıya özel verileri bulma ve silme yeteneğinin geliştirilmesi
|
||||
SOC2: Açık veri izolasyonu ve erişim kontrolleri
|
||||
HIPAA: Sağlık verileri için güçlü kiracı izolasyonu
|
||||
|
||||
## Riskler ve Önlemler
|
||||
|
||||
| Risk | Etki | Olasılık | Önlem |
|
||||
|------|--------|------------|------------|
|
||||
| Sorguda eksik kullanıcı/koleksiyon filtresi | Yüksek | Orta | Zorunlu doğrulama, kapsamlı testler |
|
||||
| Performans düşüşü | Orta | Düşük | İndeks optimizasyonu, sorgu analizi |
|
||||
| Geçiş sırasında veri bozulması | Yüksek | Düşük | Yedekleme stratejisi, geri alma prosedürleri |
|
||||
| Karmaşık, koleksiyonlar arası sorgular | Orta | Orta | Sorgu kalıplarını belgeleyin, örnekler sağlayın |
|
||||
|
||||
## Başarı Kriterleri
|
||||
|
||||
1. **Güvenlik**: Üretimde, kullanıcılar arası veri erişiminin sıfır olması
|
||||
2. **Performans**: Filtrelenmemiş sorgulara kıyasla %10'dan düşük sorgu performans etkisi
|
||||
3. **Geçiş**: Mevcut verilerin %100'ü, kayıp olmadan başarıyla geçirilmiştir
|
||||
4. **Kullanılabilirlik**: Tüm mevcut sorgu kalıpları, kullanıcı/koleksiyon bağlamıyla çalışır
|
||||
5. **Uyumluluk**: Kullanıcı/koleksiyon verilerine yapılan tüm erişimlerin tam denetim kaydı
|
||||
|
||||
## Sonuç
|
||||
|
||||
Özellik tabanlı filtreleme yaklaşımı, Neo4j'ye kullanıcı/koleksiyon izolasyonu eklemek için güvenlik, performans ve bakım açısından en iyi dengeyi sağlar. TrustGraph'ın mevcut çok kiracılık kalıplarıyla uyumludur ve aynı zamanda Neo4j'nin grafik sorgulama ve indeksleme konusundaki güçlü yönlerinden yararlanır.
|
||||
|
||||
Bu çözüm, TrustGraph'ın Neo4j arka ucunun, diğer depolama arka uçları ile aynı güvenlik standartlarını karşılamasını sağlar ve veri izolasyonu güvenlik açıklarını önlerken, grafik sorgularının esnekliğini ve gücünü korur.
|
||||
769
docs/tech-specs/tr/ontology-extract-phase-2.tr.md
Normal file
769
docs/tech-specs/tr/ontology-extract-phase-2.tr.md
Normal file
|
|
@ -0,0 +1,769 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Ontoloji Bilgi Çıkarma - 2. Aşama Yeniden Düzenleme"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Ontoloji Bilgi Çıkarma - 2. Aşama Yeniden Düzenleme
|
||||
|
||||
> **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.
|
||||
|
||||
**Durum**: Taslak
|
||||
**Yazar**: Analiz Oturumu 2025-12-03
|
||||
**İlgili**: `ontology.md`, `ontorag.md`
|
||||
|
||||
## Genel Bakış
|
||||
|
||||
Bu belge, mevcut ontoloji tabanlı bilgi çıkarma sistemindeki tutarsızlıkları belirlemektedir ve LLM performansını iyileştirmek ve bilgi kaybını azaltmak için bir yeniden düzenleme önermektedir.
|
||||
|
||||
## Mevcut Uygulama
|
||||
|
||||
### Şu Anda Nasıl Çalışıyor
|
||||
|
||||
1. **Ontoloji Yükleme** (`ontology_loader.py`)
|
||||
`"fo/Recipe"`, `"fo/Food"`, `"fo/produces"` gibi anahtarlara sahip ontoloji JSON'unu yükler.
|
||||
Sınıf kimlikleri, anahtar içinde namespace önekini içerir.
|
||||
`food.ontology`'dan bir örnek:
|
||||
```json
|
||||
"classes": {
|
||||
"fo/Recipe": {
|
||||
"uri": "http://purl.org/ontology/fo/Recipe",
|
||||
"rdfs:comment": "A Recipe is a combination..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **İstem Oluşturma** (`extract.py:299-307`, `ontology-prompt.md`)
|
||||
Şablon, `classes`, `object_properties`, `datatype_properties` sözlüklerini alır.
|
||||
Şablon döngüye girer: `{% for class_id, class_def in classes.items() %}`
|
||||
LLM (Büyük Dil Modeli) şunları görür: `**fo/Recipe**: A Recipe is a combination...`
|
||||
Örnek çıktı formatı şöyledir:
|
||||
```json
|
||||
{"subject": "recipe:cornish-pasty", "predicate": "rdf:type", "object": "Recipe"}
|
||||
{"subject": "recipe:cornish-pasty", "predicate": "has_ingredient", "object": "ingredient:flour"}
|
||||
```
|
||||
|
||||
3. **Yanıt Ayrıştırma** (`extract.py:382-428`)
|
||||
JSON dizisi beklenir: `[{"subject": "...", "predicate": "...", "object": "..."}]`
|
||||
Ontoloji alt kümesine göre doğrulanır.
|
||||
URI'lar `expand_uri()` aracılığıyla genişletilir (extract.py:473-521).
|
||||
|
||||
4. **URI Genişletme** (`extract.py:473-521`)
|
||||
Değerin `ontology_subset.classes` sözlüğünde olup olmadığını kontrol eder.
|
||||
Bulunursa, URI sınıf tanımından çıkarılır.
|
||||
Bulunmazsa, URI oluşturulur: `f"https://trustgraph.ai/ontology/{ontology_id}#{value}"`
|
||||
|
||||
### Veri Akışı Örneği
|
||||
|
||||
**Ontoloji JSON → Yükleyici → İstek:**
|
||||
```
|
||||
"fo/Recipe" → classes["fo/Recipe"] → LLM sees "**fo/Recipe**"
|
||||
```
|
||||
|
||||
**LLM → Ayrıştırıcı → Çıktı:**
|
||||
```
|
||||
"Recipe" → not in classes["fo/Recipe"] → constructs URI → LOSES original URI
|
||||
"fo/Recipe" → found in classes → uses original URI → PRESERVES URI
|
||||
```
|
||||
|
||||
## Belirlenen Sorunlar
|
||||
|
||||
### 1. **İstemde Tutarsız Örnekler**
|
||||
|
||||
**Sorun**: İstem şablonu, sınıf kimliklerini öneklerle (`fo/Recipe`) gösterirken, örnek çıktı önek kullanılmayan sınıf adlarını kullanır (`Recipe`).
|
||||
|
||||
**Konum**: `ontology-prompt.md:5-52`
|
||||
|
||||
```markdown
|
||||
## Ontology Classes:
|
||||
- **fo/Recipe**: A Recipe is...
|
||||
|
||||
## Example Output:
|
||||
{"subject": "recipe:cornish-pasty", "predicate": "rdf:type", "object": "Recipe"}
|
||||
```
|
||||
|
||||
**Etki**: LLM, hangi formatı kullanması gerektiği konusunda çelişkili sinyaller alır.
|
||||
|
||||
### 2. **URI Genişletmesinde Bilgi Kaybı**
|
||||
|
||||
**Sorun**: LLM, örneğe uygun olarak önekli olmayan sınıf adları döndürdüğünde, `expand_uri()` bunları ontoloji sözlüğünde bulamaz ve yedek URI'ler oluşturur, böylece orijinal doğru URI'ler kaybolur.
|
||||
|
||||
**Konum**: `extract.py:494-500`
|
||||
|
||||
```python
|
||||
if value in ontology_subset.classes: # Looks for "Recipe"
|
||||
class_def = ontology_subset.classes[value] # But key is "fo/Recipe"
|
||||
if isinstance(class_def, dict) and 'uri' in class_def:
|
||||
return class_def['uri'] # Never reached!
|
||||
return f"https://trustgraph.ai/ontology/{ontology_id}#{value}" # Fallback
|
||||
```
|
||||
|
||||
**Etki:**
|
||||
Orijinal URI: `http://purl.org/ontology/fo/Recipe`
|
||||
Oluşturulmuş URI: `https://trustgraph.ai/ontology/food#Recipe`
|
||||
Anlamsal anlam kayboluyor, birlikte çalışabilirlik bozuluyor.
|
||||
|
||||
### 3. **Belirsiz Varlık Örneği Biçimi**
|
||||
|
||||
**Sorun:** Varlık örneği URI biçimi hakkında net bir rehberlik yok.
|
||||
|
||||
**İpuçlarındaki örnekler:**
|
||||
`"recipe:cornish-pasty"` (namespace benzeri önek)
|
||||
`"ingredient:flour"` (farklı önek)
|
||||
|
||||
**Gerçek davranış** (extract.py:517-520):
|
||||
```python
|
||||
# Treat as entity instance - construct unique URI
|
||||
normalized = value.replace(" ", "-").lower()
|
||||
return f"https://trustgraph.ai/{ontology_id}/{normalized}"
|
||||
```
|
||||
|
||||
**Etki**: LLM'nin, herhangi bir ontoloji bağlamı olmadan, önekleme kuralını tahmin etmesi gerekir.
|
||||
|
||||
### 4. **Ada Alanı Önekleri Hakkında Rehberlik Yok**
|
||||
|
||||
**Sorun**: Ontoloji JSON dosyası, ada alanı tanımlarını içerir (food.ontology dosyasının 10-25. satırları):
|
||||
```json
|
||||
"namespaces": {
|
||||
"fo": "http://purl.org/ontology/fo/",
|
||||
"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Ancak bunlar asla LLM'ye iletilmez. LLM şunları bilmez:
|
||||
"fo" kelimesinin ne anlama geldiğini
|
||||
Varlıklar için hangi öneklerin kullanılması gerektiğini
|
||||
Hangi ad alanının hangi öğelere uygulandığını
|
||||
|
||||
### 5. **İpuçunda Kullanılmayan Etiketler**
|
||||
|
||||
**Sorun**: Her sınıfın `rdfs:label` alanları vardır (örneğin, `{"value": "Recipe", "lang": "en-gb"}`), ancak ipucu şablonu bunları kullanmaz.
|
||||
|
||||
**Mevcut durum**: Sadece `class_id` ve `comment` gösteriliyor.
|
||||
```jinja
|
||||
- **{{class_id}}**{% if class_def.comment %}: {{class_def.comment}}{% endif %}
|
||||
```
|
||||
|
||||
**Kullanılabilir ancak kullanılmayan:**
|
||||
```python
|
||||
"rdfs:label": [{"value": "Recipe", "lang": "en-gb"}]
|
||||
```
|
||||
|
||||
**Etki**: Teknik kimliklerin yanı sıra insan tarafından okunabilir isimler sağlayabilir.
|
||||
|
||||
## Önerilen Çözümler
|
||||
|
||||
### Seçenek A: Önek Olmayan Kimliklere Normalleştirme
|
||||
|
||||
**Yaklaşım**: Sınıf kimliklerinden önekleri, LLM'ye göstermeden önce kaldırın.
|
||||
|
||||
**Değişiklikler**:
|
||||
1. `build_extraction_variables()`'ı, anahtarları dönüştürmek için değiştirin:
|
||||
```python
|
||||
classes_for_prompt = {
|
||||
k.split('/')[-1]: v # "fo/Recipe" → "Recipe"
|
||||
for k, v in ontology_subset.classes.items()
|
||||
}
|
||||
```
|
||||
|
||||
2. İstem örneğini, (zaten önek kullanmayan) mevcut duruma uygun hale getirin.
|
||||
|
||||
3. `expand_uri()`'ı, her iki formatı da işleyebilecek şekilde değiştirin:
|
||||
```python
|
||||
# Try exact match first
|
||||
if value in ontology_subset.classes:
|
||||
return ontology_subset.classes[value]['uri']
|
||||
|
||||
# Try with prefix
|
||||
for prefix in ['fo/', 'rdf:', 'rdfs:']:
|
||||
prefixed = f"{prefix}{value}"
|
||||
if prefixed in ontology_subset.classes:
|
||||
return ontology_subset.classes[prefixed]['uri']
|
||||
```
|
||||
|
||||
**Artıları:**
|
||||
Daha temiz, daha insan tarafından okunabilir
|
||||
Mevcut örnek istemlerle eşleşir
|
||||
Büyük dil modelleri (LLM'ler), daha basit belirteçlerle daha iyi çalışır
|
||||
|
||||
**Eksileri:**
|
||||
Birden fazla ontolojinin aynı sınıf adına sahip olması durumunda sınıf adı çakışmaları
|
||||
Ad alanı bilgilerini kaybettirir
|
||||
Arama işlemlerinde yedekleme mantığı gerektirir
|
||||
|
||||
### B Seçeneği: Tam Önekli Kimlikleri Tutarlı Bir Şekilde Kullanın
|
||||
|
||||
**Yaklaşım:** Örnekleri, sınıf listesinde gösterilenlerle eşleşen önekli kimlikleri kullanacak şekilde güncelleyin.
|
||||
|
||||
**Değişiklikler:**
|
||||
1. Örnek istemi güncelleyin (ontology-prompt.md:46-52):
|
||||
```json
|
||||
[
|
||||
{"subject": "recipe:cornish-pasty", "predicate": "rdf:type", "object": "fo/Recipe"},
|
||||
{"subject": "recipe:cornish-pasty", "predicate": "rdfs:label", "object": "Cornish Pasty"},
|
||||
{"subject": "recipe:cornish-pasty", "predicate": "fo/produces", "object": "food:cornish-pasty"},
|
||||
{"subject": "food:cornish-pasty", "predicate": "rdf:type", "object": "fo/Food"}
|
||||
]
|
||||
```
|
||||
|
||||
2. İstemde (prompt) ad alanı açıklamasını ekleyin:
|
||||
```markdown
|
||||
## Namespace Prefixes:
|
||||
- **fo/**: Food Ontology (http://purl.org/ontology/fo/)
|
||||
- **rdf:**: RDF Schema
|
||||
- **rdfs:**: RDF Schema
|
||||
|
||||
Use these prefixes exactly as shown when referencing classes and properties.
|
||||
```
|
||||
|
||||
3. `expand_uri()`'ı olduğu gibi tutun (eşleşmeler bulunduğunda doğru şekilde çalışır).
|
||||
|
||||
**Avantajları:**
|
||||
Giriş = Çıkış tutarlılığı
|
||||
Bilgi kaybı yok
|
||||
Ada alanı semantiğini korur
|
||||
Birden fazla ontoloji ile çalışır
|
||||
|
||||
**Dezavantajları:**
|
||||
LLM için daha ayrıntılı belirteçler
|
||||
LLM'nin önekleri takip etmesini gerektirir
|
||||
|
||||
### Seçenek C: Hibrit - Hem Etiketi Hem de Kimliği Gösterin
|
||||
|
||||
**Yaklaşım:** İnsan tarafından okunabilir etiketleri ve teknik kimlikleri göstermek için istemi geliştirin.
|
||||
|
||||
**Değişiklikler:**
|
||||
1. İstem şablonunu güncelleyin:
|
||||
```jinja
|
||||
{% for class_id, class_def in classes.items() %}
|
||||
- **{{class_id}}** (label: "{{class_def.labels[0].value if class_def.labels else class_id}}"){% if class_def.comment %}: {{class_def.comment}}{% endif %}
|
||||
{% endfor %}
|
||||
```
|
||||
|
||||
Örnek çıktı:
|
||||
```markdown
|
||||
- **fo/Recipe** (label: "Recipe"): A Recipe is a combination...
|
||||
```
|
||||
|
||||
2. Güncelleme talimatları:
|
||||
```markdown
|
||||
When referencing classes:
|
||||
- Use the full prefixed ID (e.g., "fo/Recipe") in JSON output
|
||||
- The label (e.g., "Recipe") is for human understanding only
|
||||
```
|
||||
|
||||
**Avantajları**:
|
||||
LLM için en anlaşılır olanı
|
||||
Tüm bilgileri korur
|
||||
Ne kullanılması gerektiği konusunda açık
|
||||
|
||||
**Dezavantajları**:
|
||||
Daha uzun bir istem
|
||||
Daha karmaşık bir şablon
|
||||
|
||||
## Uygulanan Yaklaşım
|
||||
|
||||
**Basitleştirilmiş Varlık-İlişki-Özellik Formatı** - eski üçlü tabanlı formatın tamamen yerini alır.
|
||||
|
||||
Bu yeni yaklaşım aşağıdaki nedenlerle seçilmiştir:
|
||||
|
||||
1. **Bilgi Kaybı Yok**: Orijinal URI'ler doğru şekilde korunur
|
||||
2. **Daha Basit Mantık**: Dönüştürmeye gerek yoktur, doğrudan sözlük aramaları çalışır
|
||||
3. **Ad Alanı Güvenliği**: Çakışmalar olmadan birden fazla ontolojiyi işler
|
||||
4. **Anlamsal Doğruluk**: RDF/OWL semantiğini korur
|
||||
|
||||
## Uygulama Tamamlandı
|
||||
|
||||
### Oluşturulanlar:
|
||||
|
||||
1. **Yeni İstek Şablonu** (`prompts/ontology-extract-v2.txt`)
|
||||
✅ Açık bölümler: Varlık Türleri, İlişkiler, Özellikler
|
||||
✅ Tam tür tanımlayıcılarını kullanan örnek (`fo/Recipe`, `fo/has_ingredient`)
|
||||
✅ Şemadan tam tanımlayıcıları kullanma talimatları
|
||||
✅ Varlıklar/ilişkiler/özellikler dizileri içeren yeni JSON formatı
|
||||
|
||||
2. **Varlık Normalizasyonu** (`entity_normalizer.py`)
|
||||
✅ `normalize_entity_name()` - İsimleri URI'ye uygun formata dönüştürür
|
||||
✅ `normalize_type_identifier()` - Türlerdeki eğik çizgileri işler (`fo/Recipe` → `fo-recipe`)
|
||||
✅ `build_entity_uri()` - (isim, tür) tuple'ını kullanarak benzersiz URI'ler oluşturur
|
||||
✅ `EntityRegistry` - Tekrarlamayı önlemek için varlıkları takip eder
|
||||
|
||||
3. **JSON Ayrıştırıcı** (`simplified_parser.py`)
|
||||
✅ Yeni formatı ayrıştırır: `{entities: [...], relationships: [...], attributes: [...]}`
|
||||
✅ kebab-case ve snake_case alan adlarını destekler
|
||||
✅ Yapılandırılmış veri sınıfları döndürür
|
||||
✅ Günlükleme ile zarif hata işleme
|
||||
|
||||
4. **Üçlü Dönüştürücü** (`triple_converter.py`)
|
||||
✅ `convert_entity()` - Tür + etiket üçlülerini otomatik olarak oluşturur
|
||||
✅ `convert_relationship()` - Varlık URI'lerini özellikler aracılığıyla bağlar
|
||||
✅ `convert_attribute()` - Literal değerleri ekler
|
||||
✅ Ontoloji tanımlarından tam URI'leri alır
|
||||
|
||||
5. **Güncellenmiş Ana İşlemci** (`extract.py`)
|
||||
✅ Eski üçlü tabanlı çıkarma kodunu kaldırdı
|
||||
✅ `extract_with_simplified_format()` yöntemini ekledi
|
||||
✅ Artık yalnızca yeni, basitleştirilmiş formatı kullanır
|
||||
✅ İstemleri `extract-with-ontologies-v2` kimliğiyle çağırır
|
||||
|
||||
## Test Senaryoları
|
||||
|
||||
### Test 1: URI Korunması
|
||||
```python
|
||||
# Given ontology class
|
||||
classes = {"fo/Recipe": {"uri": "http://purl.org/ontology/fo/Recipe", ...}}
|
||||
|
||||
# When LLM returns
|
||||
llm_output = {"subject": "x", "predicate": "rdf:type", "object": "fo/Recipe"}
|
||||
|
||||
# Then expanded URI should be
|
||||
assert expanded == "http://purl.org/ontology/fo/Recipe"
|
||||
# Not: "https://trustgraph.ai/ontology/food#Recipe"
|
||||
```
|
||||
|
||||
### Test 2: Çoklu Ontoloji Çakışması
|
||||
```python
|
||||
# Given two ontologies
|
||||
ont1 = {"fo/Recipe": {...}}
|
||||
ont2 = {"cooking/Recipe": {...}}
|
||||
|
||||
# LLM should use full prefix to disambiguate
|
||||
llm_output = {"object": "fo/Recipe"} # Not just "Recipe"
|
||||
```
|
||||
|
||||
### Test 3: Varlık Örneği Formatı
|
||||
```python
|
||||
# Given prompt with food ontology
|
||||
# LLM should create instances like
|
||||
{"subject": "recipe:cornish-pasty"} # Namespace-style
|
||||
{"subject": "food:beef"} # Consistent prefix
|
||||
```
|
||||
|
||||
## Açık Sorular
|
||||
|
||||
1. **Varlık örnekleri namespace önekleri kullanmalı mı?**
|
||||
Mevcut durum: `"recipe:cornish-pasty"` (keyfi)
|
||||
Alternatif: Ontoloji önekini kullanın `"fo:cornish-pasty"`?
|
||||
Alternatif: Önek yok, URI'da genişletin `"cornish-pasty"` → tam URI?
|
||||
|
||||
2. **Alan/kapsam (domain/range) nasıl işlenmeli?**
|
||||
Şu anda gösterilen: `(Recipe → Food)`
|
||||
Şu şekilde olmalı mı: `(fo/Recipe → fo/Food)`?
|
||||
|
||||
3. **Alan/kapsam kısıtlamalarını doğrulamalı mıyız?**
|
||||
TODO yorumu extract.py:470 satırında
|
||||
Daha fazla hata yakalanır, ancak daha karmaşık olur
|
||||
|
||||
4. **Ters özellikler ve eşdeğerlikler hakkında ne düşünülmeli?**
|
||||
Ontolojide `owl:inverseOf`, `owl:equivalentClass` bulunmaktadır
|
||||
Şu anda çıkarımda kullanılmıyor
|
||||
Kullanılmalı mı?
|
||||
|
||||
## Başarı Metrikleri
|
||||
|
||||
✅ Sıfır URI bilgisi kaybı (orijinal URI'lerin %100 korunması)
|
||||
✅ LLM çıktısı formatı, giriş formatıyla eşleşiyor
|
||||
✅ Girişte belirsiz örnek yok
|
||||
✅ Birden fazla ontolojiyle testler geçiliyor
|
||||
✅ İyileştirilmiş çıkarım kalitesi (geçerli üçlü yüzdesi ile ölçülür)
|
||||
|
||||
## Alternatif Yaklaşım: Basitleştirilmiş Çıkarım Formatı
|
||||
|
||||
### Felsefe
|
||||
|
||||
LLM'den RDF/OWL semantiğini anlamasını istemek yerine, LLM'nin iyi olduğu şeyi yapmasını isteyin: **metindeki varlıkları ve ilişkileri bulun**.
|
||||
|
||||
URI oluşturma, RDF'ye dönüştürme ve semantik web formalitelerini kodun halletmesine izin verin.
|
||||
|
||||
### Örnek: Varlık Sınıflandırması
|
||||
|
||||
**Giriş Metni:**
|
||||
```
|
||||
Cornish pasty is a traditional British pastry filled with meat and vegetables.
|
||||
```
|
||||
|
||||
**Ontoloji Şeması (LLM'ye gösterilen):**
|
||||
```markdown
|
||||
## Entity Types:
|
||||
- Recipe: A recipe is a combination of ingredients and a method
|
||||
- Food: A food is something that can be eaten
|
||||
- Ingredient: An ingredient combines a quantity and a food
|
||||
```
|
||||
|
||||
**LLM'nin Döndürdükleri (Basit JSON):**
|
||||
```json
|
||||
{
|
||||
"entities": [
|
||||
{
|
||||
"entity": "Cornish pasty",
|
||||
"type": "Recipe"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Kodun Ürettiği Şeyler (RDF Üçlüleri):**
|
||||
```python
|
||||
# 1. Normalize entity name + type to ID (type prevents collisions)
|
||||
entity_id = "recipe-cornish-pasty" # normalize("Cornish pasty", "Recipe")
|
||||
entity_uri = "https://trustgraph.ai/food/recipe-cornish-pasty"
|
||||
|
||||
# Note: Same name, different type = different URI
|
||||
# "Cornish pasty" (Recipe) → recipe-cornish-pasty
|
||||
# "Cornish pasty" (Food) → food-cornish-pasty
|
||||
|
||||
# 2. Generate triples
|
||||
triples = [
|
||||
# Type triple
|
||||
Triple(
|
||||
s=Value(value=entity_uri, is_uri=True),
|
||||
p=Value(value="http://www.w3.org/1999/02/22-rdf-syntax-ns#type", is_uri=True),
|
||||
o=Value(value="http://purl.org/ontology/fo/Recipe", is_uri=True)
|
||||
),
|
||||
# Label triple (automatic)
|
||||
Triple(
|
||||
s=Value(value=entity_uri, is_uri=True),
|
||||
p=Value(value="http://www.w3.org/2000/01/rdf-schema#label", is_uri=True),
|
||||
o=Value(value="Cornish pasty", is_uri=False)
|
||||
)
|
||||
]
|
||||
```
|
||||
|
||||
### Faydalar
|
||||
|
||||
1. **LLM'nin (Büyük Dil Modeli) yapması gerekmiyor:**
|
||||
URI sözdizimini anlamak
|
||||
Tanımlayıcı önekleri oluşturmak (`recipe:`, `ingredient:`)
|
||||
`rdf:type` veya `rdfs:label` hakkında bilgi sahibi olmak
|
||||
Semantik web tanımlayıcıları oluşturmak
|
||||
|
||||
2. **LLM'nin sadece yapması gerekiyor:**
|
||||
Metindeki varlıkları bulmak
|
||||
Bunları ontoloji sınıflarına eşlemek
|
||||
İlişkileri ve özellikleri çıkarmak
|
||||
|
||||
3. **Kod şunları yönetir:**
|
||||
URI normalizasyonu ve oluşturulması
|
||||
RDF üçlü üretimi
|
||||
Otomatik etiket ataması
|
||||
İsim alanı yönetimi
|
||||
|
||||
### Neden Bu Daha İyi Çalışıyor
|
||||
|
||||
**Daha basit istem** = daha az kafa karışıklığı = daha az hata
|
||||
**Tutarlı kimlikler** = kod, normalizasyon kurallarını kontrol eder
|
||||
**Otomatik olarak oluşturulan etiketler** = eksik rdfs:label üçlüleri yok
|
||||
**LLM, çıkarma üzerine odaklanır** = aslında iyi olduğu şey
|
||||
|
||||
### Örnek: Varlık İlişkileri
|
||||
|
||||
**Giriş Metni:**
|
||||
```
|
||||
Cornish pasty is a traditional British pastry filled with beef and potatoes.
|
||||
```
|
||||
|
||||
**Ontoloji Şeması (LLM'ye gösterilen):**
|
||||
```markdown
|
||||
## Entity Types:
|
||||
- Recipe: A recipe is a combination of ingredients and a method
|
||||
- Food: A food is something that can be eaten
|
||||
- Ingredient: An ingredient combines a quantity and a food
|
||||
|
||||
## Relationships:
|
||||
- has_ingredient: Relates a recipe to an ingredient it uses (Recipe → Ingredient)
|
||||
- food: Relates an ingredient to the food that is required (Ingredient → Food)
|
||||
```
|
||||
|
||||
**LLM'nin Döndürdükleri (Basit JSON):**
|
||||
```json
|
||||
{
|
||||
"entities": [
|
||||
{
|
||||
"entity": "Cornish pasty",
|
||||
"type": "Recipe"
|
||||
},
|
||||
{
|
||||
"entity": "beef",
|
||||
"type": "Food"
|
||||
},
|
||||
{
|
||||
"entity": "potatoes",
|
||||
"type": "Food"
|
||||
}
|
||||
],
|
||||
"relationships": [
|
||||
{
|
||||
"subject": "Cornish pasty",
|
||||
"subject-type": "Recipe",
|
||||
"relation": "has_ingredient",
|
||||
"object": "beef",
|
||||
"object-type": "Food"
|
||||
},
|
||||
{
|
||||
"subject": "Cornish pasty",
|
||||
"subject-type": "Recipe",
|
||||
"relation": "has_ingredient",
|
||||
"object": "potatoes",
|
||||
"object-type": "Food"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Kodun Ürettiği Şeyler (RDF Üçlüleri):**
|
||||
```python
|
||||
# Normalize entity names to URIs
|
||||
cornish_pasty_uri = "https://trustgraph.ai/food/cornish-pasty"
|
||||
beef_uri = "https://trustgraph.ai/food/beef"
|
||||
potatoes_uri = "https://trustgraph.ai/food/potatoes"
|
||||
|
||||
# Look up relation URI from ontology
|
||||
has_ingredient_uri = "http://purl.org/ontology/fo/ingredients" # from fo/has_ingredient
|
||||
|
||||
triples = [
|
||||
# Entity type triples (as before)
|
||||
Triple(s=cornish_pasty_uri, p=rdf_type, o="http://purl.org/ontology/fo/Recipe"),
|
||||
Triple(s=cornish_pasty_uri, p=rdfs_label, o="Cornish pasty"),
|
||||
|
||||
Triple(s=beef_uri, p=rdf_type, o="http://purl.org/ontology/fo/Food"),
|
||||
Triple(s=beef_uri, p=rdfs_label, o="beef"),
|
||||
|
||||
Triple(s=potatoes_uri, p=rdf_type, o="http://purl.org/ontology/fo/Food"),
|
||||
Triple(s=potatoes_uri, p=rdfs_label, o="potatoes"),
|
||||
|
||||
# Relationship triples
|
||||
Triple(
|
||||
s=Value(value=cornish_pasty_uri, is_uri=True),
|
||||
p=Value(value=has_ingredient_uri, is_uri=True),
|
||||
o=Value(value=beef_uri, is_uri=True)
|
||||
),
|
||||
Triple(
|
||||
s=Value(value=cornish_pasty_uri, is_uri=True),
|
||||
p=Value(value=has_ingredient_uri, is_uri=True),
|
||||
o=Value(value=potatoes_uri, is_uri=True)
|
||||
)
|
||||
]
|
||||
```
|
||||
|
||||
**Önemli Noktalar:**
|
||||
LLM, doğal dil varlık isimlerini döndürür: `"Cornish pasty"`, `"beef"`, `"potatoes"`
|
||||
LLM, anlam belirsizliğini gidermek için türleri içerir: `subject-type`, `object-type`
|
||||
LLM, şemadan ilişki adını kullanır: `"has_ingredient"`
|
||||
Kod, (isim, tür) kullanarak tutarlı kimlikler türetir: `("Cornish pasty", "Recipe")` → `recipe-cornish-pasty`
|
||||
Kod, ontolojiden ilişki URI'sini arar: `fo/has_ingredient` → tam URI
|
||||
Aynı (isim, tür) ikilisi her zaman aynı URI'yi alır (çiftleme önleme)
|
||||
|
||||
### Örnek: Varlık İsimlerinin Anlam Belirsizliğinin Giderilmesi
|
||||
|
||||
**Sorun:** Aynı isim, farklı varlık türlerini ifade edebilir.
|
||||
|
||||
**Gerçek dünya örneği:**
|
||||
```
|
||||
"Cornish pasty" can be:
|
||||
- A Recipe (instructions for making it)
|
||||
- A Food (the dish itself)
|
||||
```
|
||||
|
||||
**Nasıl İşlendiği:**
|
||||
|
||||
LLM, her ikisini de ayrı varlıklar olarak döndürür:
|
||||
```json
|
||||
{
|
||||
"entities": [
|
||||
{"entity": "Cornish pasty", "type": "Recipe"},
|
||||
{"entity": "Cornish pasty", "type": "Food"}
|
||||
],
|
||||
"relationships": [
|
||||
{
|
||||
"subject": "Cornish pasty",
|
||||
"subject-type": "Recipe",
|
||||
"relation": "produces",
|
||||
"object": "Cornish pasty",
|
||||
"object-type": "Food"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Kod Çözümleme:**
|
||||
```python
|
||||
# Different types → different URIs
|
||||
recipe_uri = normalize("Cornish pasty", "Recipe")
|
||||
# → "https://trustgraph.ai/food/recipe-cornish-pasty"
|
||||
|
||||
food_uri = normalize("Cornish pasty", "Food")
|
||||
# → "https://trustgraph.ai/food/food-cornish-pasty"
|
||||
|
||||
# Relationship connects them correctly
|
||||
triple = Triple(
|
||||
s=recipe_uri, # The Recipe
|
||||
p="http://purl.org/ontology/fo/produces",
|
||||
o=food_uri # The Food
|
||||
)
|
||||
```
|
||||
|
||||
**Neden İşe Yarıyor:**
|
||||
Tip, TÜM referanslarda (varlıklar, ilişkiler, özellikler) bulunur.
|
||||
Kod, arama anahtarı olarak `(name, type)` tuple'ını kullanır.
|
||||
Herhangi bir belirsizlik, herhangi bir çakışma yoktur.
|
||||
|
||||
### Örnek: Varlık Özellikleri
|
||||
|
||||
**Giriş Metni:**
|
||||
```
|
||||
This Cornish pasty recipe serves 4-6 people and takes 45 minutes to prepare.
|
||||
```
|
||||
|
||||
**Ontoloji Şeması (LLM'ye gösterilen):**
|
||||
```markdown
|
||||
## Entity Types:
|
||||
- Recipe: A recipe is a combination of ingredients and a method
|
||||
|
||||
## Attributes:
|
||||
- serves: Indicates what the recipe is intended to serve (Recipe → text)
|
||||
- preparation_time: Time needed to prepare the recipe (Recipe → text)
|
||||
```
|
||||
|
||||
**LLM'nin Döndürdükleri (Basit JSON):**
|
||||
```json
|
||||
{
|
||||
"entities": [
|
||||
{
|
||||
"entity": "Cornish pasty recipe",
|
||||
"type": "Recipe"
|
||||
}
|
||||
],
|
||||
"attributes": [
|
||||
{
|
||||
"entity": "Cornish pasty recipe",
|
||||
"entity-type": "Recipe",
|
||||
"attribute": "serves",
|
||||
"value": "4-6 people"
|
||||
},
|
||||
{
|
||||
"entity": "Cornish pasty recipe",
|
||||
"entity-type": "Recipe",
|
||||
"attribute": "preparation_time",
|
||||
"value": "45 minutes"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Kodun Ürettiği Şeyler (RDF Üçlüleri):**
|
||||
```python
|
||||
# Normalize entity name to URI
|
||||
recipe_uri = "https://trustgraph.ai/food/cornish-pasty-recipe"
|
||||
|
||||
# Look up attribute URIs from ontology
|
||||
serves_uri = "http://purl.org/ontology/fo/serves" # from fo/serves
|
||||
prep_time_uri = "http://purl.org/ontology/fo/preparation_time" # from fo/preparation_time
|
||||
|
||||
triples = [
|
||||
# Entity type triple
|
||||
Triple(
|
||||
s=Value(value=recipe_uri, is_uri=True),
|
||||
p=Value(value=rdf_type, is_uri=True),
|
||||
o=Value(value="http://purl.org/ontology/fo/Recipe", is_uri=True)
|
||||
),
|
||||
|
||||
# Label triple (automatic)
|
||||
Triple(
|
||||
s=Value(value=recipe_uri, is_uri=True),
|
||||
p=Value(value=rdfs_label, is_uri=True),
|
||||
o=Value(value="Cornish pasty recipe", is_uri=False)
|
||||
),
|
||||
|
||||
# Attribute triples (objects are literals, not URIs)
|
||||
Triple(
|
||||
s=Value(value=recipe_uri, is_uri=True),
|
||||
p=Value(value=serves_uri, is_uri=True),
|
||||
o=Value(value="4-6 people", is_uri=False) # Literal value!
|
||||
),
|
||||
Triple(
|
||||
s=Value(value=recipe_uri, is_uri=True),
|
||||
p=Value(value=prep_time_uri, is_uri=True),
|
||||
o=Value(value="45 minutes", is_uri=False) # Literal value!
|
||||
)
|
||||
]
|
||||
```
|
||||
|
||||
**Önemli Noktalar:**
|
||||
LLM, gerçek değerleri çıkarır: `"4-6 people"`, `"45 minutes"`
|
||||
LLM, anlam ayrımı için varlık türünü içerir: `entity-type`
|
||||
LLM, şemadan öznitelik adını kullanır: `"serves"`, `"preparation_time"`
|
||||
Kod, öznitelik URI'sini ontoloji veri türü özelliklerinden arar
|
||||
**Nesne bir literaldir** (`is_uri=False`), bir URI referansı değildir
|
||||
Değerler, doğal metin olarak kalır, normalleştirmeye gerek yoktur
|
||||
|
||||
**İlişkilerden Farkı:**
|
||||
İlişkiler: hem konu hem de nesne varlıklardır (URI'ler)
|
||||
Öznitelikler: konu bir varlıktır (URI), nesne bir literal değerdir (dize/sayı)
|
||||
|
||||
### Tam Örnek: Varlıklar + İlişkiler + Öznitelikler
|
||||
|
||||
**Giriş Metni:**
|
||||
```
|
||||
Cornish pasty is a savory pastry filled with beef and potatoes.
|
||||
This recipe serves 4 people.
|
||||
```
|
||||
|
||||
**LLM'nin Döndürdükleri:**
|
||||
```json
|
||||
{
|
||||
"entities": [
|
||||
{
|
||||
"entity": "Cornish pasty",
|
||||
"type": "Recipe"
|
||||
},
|
||||
{
|
||||
"entity": "beef",
|
||||
"type": "Food"
|
||||
},
|
||||
{
|
||||
"entity": "potatoes",
|
||||
"type": "Food"
|
||||
}
|
||||
],
|
||||
"relationships": [
|
||||
{
|
||||
"subject": "Cornish pasty",
|
||||
"subject-type": "Recipe",
|
||||
"relation": "has_ingredient",
|
||||
"object": "beef",
|
||||
"object-type": "Food"
|
||||
},
|
||||
{
|
||||
"subject": "Cornish pasty",
|
||||
"subject-type": "Recipe",
|
||||
"relation": "has_ingredient",
|
||||
"object": "potatoes",
|
||||
"object-type": "Food"
|
||||
}
|
||||
],
|
||||
"attributes": [
|
||||
{
|
||||
"entity": "Cornish pasty",
|
||||
"entity-type": "Recipe",
|
||||
"attribute": "serves",
|
||||
"value": "4 people"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Sonuç:** 11 RDF üçlüsü oluşturuldu:
|
||||
3 varlık türü üçlüsü (rdf:type)
|
||||
3 varlık etiket üçlüsü (rdfs:label) - otomatik
|
||||
2 ilişki üçlüsü (has_ingredient)
|
||||
1 özellik üçlüsü (serves)
|
||||
|
||||
Bunların hepsi, LLM tarafından yapılan basit, doğal dil çıkarımlarından elde edilmiştir!
|
||||
|
||||
## Referanslar
|
||||
|
||||
Mevcut uygulama: `trustgraph-flow/trustgraph/extract/kg/ontology/extract.py`
|
||||
İstek şablonu: `ontology-prompt.md`
|
||||
Test senaryoları: `tests/unit/test_extract/test_ontology/`
|
||||
Örnek ontoloji: `e2e/test-data/food.ontology`
|
||||
294
docs/tech-specs/tr/ontology.tr.md
Normal file
294
docs/tech-specs/tr/ontology.tr.md
Normal file
|
|
@ -0,0 +1,294 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Ontoloji Yapısı Teknik Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Ontoloji Yapısı 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 sistemindeki ontolojilerin yapısını ve biçimini tanımlar. Ontolojiler, sınıfları, özellikleri ve ilişkileri tanımlayan resmi bilgi modelleri sağlar ve akıl yürütme ve çıkarım yeteneklerini destekler. Sistem, OWL'den ilham alan bir yapılandırma biçimi kullanır ve bu, OWL/RDFS kavramlarını geniş ölçüde temsil ederken aynı zamanda TrustGraph'ın gereksinimleri için optimize edilmiştir.
|
||||
|
||||
**İsimlendirme Kuralları**: Bu proje, yılan_biçimi yerine tüm tanımlayıcılar (yapılandırma anahtarları, API uç noktaları, modül adları vb.) için kebab-case kullanır.
|
||||
|
||||
## Hedefler
|
||||
|
||||
**Sınıf ve Özellik Yönetimi**: OWL benzeri sınıfları, özellikleri, etki alanlarını, aralıkları ve tür kısıtlamalarını tanımlayın.
|
||||
**Zengin Anlamsal Destek**: Etiketler, çoklu dil desteği ve resmi kısıtlamalar dahil olmak üzere kapsamlı RDFS/OWL özellikleri sağlayın.
|
||||
**Çoklu Ontoloji Desteği**: Birden fazla ontolojinin birlikte var olmasına ve etkileşimde olmasına izin verin.
|
||||
**Doğrulama ve Akıl Yürütme**: Ontolojilerin, tutarlılık kontrolü ve çıkarım desteği ile OWL benzeri standartlara uygun olduğundan emin olun.
|
||||
**Standart Uyumluluğu**: İç optimizasyonu korurken standart formatlarda (Turtle, RDF/XML, OWL/XML) içe/dışa aktarma desteğini sağlayın.
|
||||
|
||||
## Arka Plan
|
||||
|
||||
TrustGraph, ontolojileri esnek bir anahtar-değer sisteminde yapılandırma öğeleri olarak saklar. Biçim OWL (Web Ontology Language) tarafından ilham alınmış olsa da, TrustGraph'ın belirli kullanım durumları için optimize edilmiştir ve tüm OWL özelliklerine kesin olarak uymamaktadır.
|
||||
|
||||
TrustGraph'taki ontolojiler şunları sağlar:
|
||||
Resmi nesne türlerinin ve özelliklerinin tanımlanması
|
||||
Özellik etki alanlarının, aralıklarının ve tür kısıtlamalarının belirtilmesi
|
||||
Mantıksal akıl yürütme ve çıkarım
|
||||
Karmaşık ilişkiler ve kardinalite kısıtlamaları
|
||||
Uluslararasılaştırma için çoklu dil desteği
|
||||
|
||||
## Ontoloji Yapısı
|
||||
|
||||
### Yapılandırma Depolama
|
||||
|
||||
Ontolojiler, aşağıdaki kalıba sahip yapılandırma öğeleri olarak saklanır:
|
||||
**Tür**: `ontology`
|
||||
**Anahtar**: Benzersiz ontoloji tanımlayıcısı (örneğin, `natural-world`, `domain-model`)
|
||||
**Değer**: JSON formatında eksiksiz ontoloji
|
||||
|
||||
### JSON Yapısı
|
||||
|
||||
Ontoloji JSON biçimi, dört ana bölümden oluşur:
|
||||
|
||||
#### 1. Meta Veriler
|
||||
|
||||
Ontoloji hakkında idari ve tanımlayıcı bilgiler içerir:
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"name": "The natural world",
|
||||
"description": "Ontology covering the natural order",
|
||||
"version": "1.0.0",
|
||||
"created": "2025-09-20T12:07:37.068Z",
|
||||
"modified": "2025-09-20T12:12:20.725Z",
|
||||
"creator": "current-user",
|
||||
"namespace": "http://trustgraph.ai/ontologies/natural-world",
|
||||
"imports": ["http://www.w3.org/2002/07/owl#"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Alanlar:**
|
||||
`name`: Ontolojinin insan tarafından okunabilir adı
|
||||
`description`: Ontolojinin amacının kısa açıklaması
|
||||
`version`: Semantik sürüm numarası
|
||||
`created`: Oluşturulma zamanının ISO 8601 zaman damgası
|
||||
`modified`: Son değişiklik zamanının ISO 8601 zaman damgası
|
||||
`creator`: Ontolojiyi oluşturan kullanıcı/sistemin kimliği
|
||||
`namespace`: Ontoloji öğeleri için temel URI
|
||||
`imports`: İçe aktarılan ontoloji URI'lerinin dizisi
|
||||
|
||||
#### 2. Sınıflar
|
||||
|
||||
Nesne türlerini ve hiyerarşik ilişkilerini tanımlar:
|
||||
|
||||
```json
|
||||
{
|
||||
"classes": {
|
||||
"animal": {
|
||||
"uri": "http://trustgraph.ai/ontologies/natural-world#animal",
|
||||
"type": "owl:Class",
|
||||
"rdfs:label": [{"value": "Animal", "lang": "en"}],
|
||||
"rdfs:comment": "An animal",
|
||||
"rdfs:subClassOf": "lifeform",
|
||||
"owl:equivalentClass": ["creature"],
|
||||
"owl:disjointWith": ["plant"],
|
||||
"dcterms:identifier": "ANI-001"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Desteklenen Özellikler:**
|
||||
`uri`: Sınıfın tam URI'si
|
||||
`type`: Her zaman `"owl:Class"`
|
||||
`rdfs:label`: Dil etiketli etiketlerin dizisi
|
||||
`rdfs:comment`: Sınıfın açıklaması
|
||||
`rdfs:subClassOf`: Üst sınıf tanımlayıcısı (tekli miras)
|
||||
`owl:equivalentClass`: Eşdeğer sınıf tanımlayıcılarının dizisi
|
||||
`owl:disjointWith`: Ayrık sınıf tanımlayıcılarının dizisi
|
||||
`dcterms:identifier`: İsteğe bağlı harici referans tanımlayıcısı
|
||||
|
||||
#### 3. Nesne Özellikleri
|
||||
|
||||
Örnekleri diğer örneklere bağlayan özellikler:
|
||||
|
||||
```json
|
||||
{
|
||||
"objectProperties": {
|
||||
"has-parent": {
|
||||
"uri": "http://trustgraph.ai/ontologies/natural-world#has-parent",
|
||||
"type": "owl:ObjectProperty",
|
||||
"rdfs:label": [{"value": "has parent", "lang": "en"}],
|
||||
"rdfs:comment": "Links an animal to its parent",
|
||||
"rdfs:domain": "animal",
|
||||
"rdfs:range": "animal",
|
||||
"owl:inverseOf": "parent-of",
|
||||
"owl:functionalProperty": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Desteklenen Özellikler:**
|
||||
`uri`: Özelliğin tam URI'si
|
||||
`type`: Her zaman `"owl:ObjectProperty"`
|
||||
`rdfs:label`: Dil etiketli etiketlerin dizisi
|
||||
`rdfs:comment`: Özelliğin açıklaması
|
||||
`rdfs:domain`: Bu özelliğe sahip sınıf tanımlayıcısı
|
||||
`rdfs:range`: Özellik değerleri için sınıf tanımlayıcısı
|
||||
`owl:inverseOf`: Ters özelliğin tanımlayıcısı
|
||||
`owl:functionalProperty`: En fazla bir değer olduğunu gösteren boolean değeri
|
||||
`owl:inverseFunctionalProperty`: Benzersiz tanımlayıcı özellikleri için boolean değeri
|
||||
|
||||
#### 4. Veri Tipi Özellikleri
|
||||
|
||||
Örnekleri, literal değerlere bağlayan özellikler:
|
||||
|
||||
```json
|
||||
{
|
||||
"datatypeProperties": {
|
||||
"number-of-legs": {
|
||||
"uri": "http://trustgraph.ai/ontologies/natural-world#number-of-legs",
|
||||
"type": "owl:DatatypeProperty",
|
||||
"rdfs:label": [{"value": "number of legs", "lang": "en"}],
|
||||
"rdfs:comment": "Count of number of legs of the animal",
|
||||
"rdfs:domain": "animal",
|
||||
"rdfs:range": "xsd:nonNegativeInteger",
|
||||
"owl:functionalProperty": true,
|
||||
"owl:minCardinality": 0,
|
||||
"owl:maxCardinality": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Desteklenen Özellikler:**
|
||||
`uri`: Özelliğin tam URI'si
|
||||
`type`: Her zaman `"owl:DatatypeProperty"`
|
||||
`rdfs:label`: Dil etiketli etiketlerin dizisi
|
||||
`rdfs:comment`: Özelliğin açıklaması
|
||||
`rdfs:domain`: Bu özelliğe sahip sınıf tanımlayıcısı
|
||||
`rdfs:range`: Özellik değerleri için XSD veri türü
|
||||
`owl:functionalProperty`: En fazla bir değer olduğunu gösteren boolean değeri
|
||||
`owl:minCardinality`: Minimum değer sayısı (isteğe bağlı)
|
||||
`owl:maxCardinality`: Maksimum değer sayısı (isteğe bağlı)
|
||||
`owl:cardinality`: Tam değer sayısı (isteğe bağlı)
|
||||
|
||||
### Desteklenen XSD Veri Türleri
|
||||
|
||||
Aşağıdaki XML Şema veri türleri, veri türü özellik aralıkları için desteklenmektedir:
|
||||
|
||||
`xsd:string` - Metin değerleri
|
||||
`xsd:integer` - Tamsayılar
|
||||
`xsd:nonNegativeInteger` - Negatif olmayan tamsayılar
|
||||
`xsd:float` - Ondalık sayılar
|
||||
`xsd:double` - Çift hassasiyetli sayılar
|
||||
`xsd:boolean` - Doğru/yanlış değerleri
|
||||
`xsd:dateTime` - Tarih ve saat değerleri
|
||||
`xsd:date` - Tarih değerleri
|
||||
`xsd:anyURI` - URI referansları
|
||||
|
||||
### Dil Desteği
|
||||
|
||||
Etiketler ve yorumlar, W3C dil etiketi biçimini kullanarak çoklu dilleri destekler:
|
||||
|
||||
```json
|
||||
{
|
||||
"rdfs:label": [
|
||||
{"value": "Animal", "lang": "en"},
|
||||
{"value": "Tier", "lang": "de"},
|
||||
{"value": "Animal", "lang": "es"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Örnek Ontoloji
|
||||
|
||||
İşte basit bir ontolojinin eksiksiz bir örneği:
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"name": "The natural world",
|
||||
"description": "Ontology covering the natural order",
|
||||
"version": "1.0.0",
|
||||
"created": "2025-09-20T12:07:37.068Z",
|
||||
"modified": "2025-09-20T12:12:20.725Z",
|
||||
"creator": "current-user",
|
||||
"namespace": "http://trustgraph.ai/ontologies/natural-world",
|
||||
"imports": ["http://www.w3.org/2002/07/owl#"]
|
||||
},
|
||||
"classes": {
|
||||
"lifeform": {
|
||||
"uri": "http://trustgraph.ai/ontologies/natural-world#lifeform",
|
||||
"type": "owl:Class",
|
||||
"rdfs:label": [{"value": "Lifeform", "lang": "en"}],
|
||||
"rdfs:comment": "A living thing"
|
||||
},
|
||||
"animal": {
|
||||
"uri": "http://trustgraph.ai/ontologies/natural-world#animal",
|
||||
"type": "owl:Class",
|
||||
"rdfs:label": [{"value": "Animal", "lang": "en"}],
|
||||
"rdfs:comment": "An animal",
|
||||
"rdfs:subClassOf": "lifeform"
|
||||
},
|
||||
"cat": {
|
||||
"uri": "http://trustgraph.ai/ontologies/natural-world#cat",
|
||||
"type": "owl:Class",
|
||||
"rdfs:label": [{"value": "Cat", "lang": "en"}],
|
||||
"rdfs:comment": "A cat",
|
||||
"rdfs:subClassOf": "animal"
|
||||
},
|
||||
"dog": {
|
||||
"uri": "http://trustgraph.ai/ontologies/natural-world#dog",
|
||||
"type": "owl:Class",
|
||||
"rdfs:label": [{"value": "Dog", "lang": "en"}],
|
||||
"rdfs:comment": "A dog",
|
||||
"rdfs:subClassOf": "animal",
|
||||
"owl:disjointWith": ["cat"]
|
||||
}
|
||||
},
|
||||
"objectProperties": {},
|
||||
"datatypeProperties": {
|
||||
"number-of-legs": {
|
||||
"uri": "http://trustgraph.ai/ontologies/natural-world#number-of-legs",
|
||||
"type": "owl:DatatypeProperty",
|
||||
"rdfs:label": [{"value": "number-of-legs", "lang": "en"}],
|
||||
"rdfs:comment": "Count of number of legs of the animal",
|
||||
"rdfs:range": "xsd:nonNegativeInteger",
|
||||
"rdfs:domain": "animal"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Doğrulama Kuralları
|
||||
|
||||
### Yapısal Doğrulama
|
||||
|
||||
1. **URI Tutarlılığı**: Tüm URI'ler `{namespace}#{identifier}` kalıbını takip etmelidir.
|
||||
2. **Sınıf Hiyerarşisi**: `rdfs:subClassOf` içinde döngüsel miras ilişkisi olmamalıdır.
|
||||
3. **Özellik Alanları/Aralıkları**: Mevcut sınıflara veya geçerli XSD türlerine başvurmalıdır.
|
||||
4. **Ayrık Sınıflar**: Birbirinin alt sınıfı olamazlar.
|
||||
5. **Ters Özellikler**: Belirtilmişse, çift yönlü olmalıdır.
|
||||
|
||||
### Anlamsal Doğrulama
|
||||
|
||||
1. **Benzersiz Tanımlayıcılar**: Sınıf ve özellik tanımlayıcıları, bir ontoloji içinde benzersiz olmalıdır.
|
||||
2. **Dil Etiketleri**: BCP 47 dil etiketi formatını takip etmelidir.
|
||||
3. **Kardinalite Kısıtlamaları**: Hem belirtilmişse, `minCardinality` ≤ `maxCardinality` olmalıdır.
|
||||
4. **Fonksiyonel Özellikler**: `maxCardinality` > 1 olamaz.
|
||||
|
||||
## İçe/Dışa Aktarma Formatı Desteği
|
||||
|
||||
İç format JSON olmasına rağmen, sistem standart ontoloji formatlarına dönüştürmeyi destekler:
|
||||
|
||||
**Turtle (.ttl)** - RDF'nin kompakt seri hale getirilmesi
|
||||
**RDF/XML (.rdf, .owl)** - W3C standardı formatı
|
||||
**OWL/XML (.owx)** - OWL'e özel XML formatı
|
||||
**JSON-LD (.jsonld)** - Bağlı Veri için JSON
|
||||
|
||||
## Referanslar
|
||||
|
||||
[OWL 2 Web Ontology Language](https://www.w3.org/TR/owl2-overview/)
|
||||
[RDF Schema 1.1](https://www.w3.org/TR/rdf-schema/)
|
||||
[XML Schema Datatypes](https://www.w3.org/TR/xmlschema-2/)
|
||||
[BCP 47 Language Tags](https://tools.ietf.org/html/bcp47)
|
||||
1075
docs/tech-specs/tr/ontorag.tr.md
Normal file
1075
docs/tech-specs/tr/ontorag.tr.md
Normal file
File diff suppressed because it is too large
Load diff
239
docs/tech-specs/tr/openapi-spec.tr.md
Normal file
239
docs/tech-specs/tr/openapi-spec.tr.md
Normal file
|
|
@ -0,0 +1,239 @@
|
|||
---
|
||||
layout: default
|
||||
title: "OpenAPI Özellikleri - Teknik Belge"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# OpenAPI Özellikleri - Teknik Belge
|
||||
|
||||
> **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.
|
||||
|
||||
## Amaç
|
||||
|
||||
TrustGraph REST API Gateway için kapsamlı, modüler bir OpenAPI 3.1 spesifikasyonu oluşturmak, bu spesifikasyon şunları sağlamalıdır:
|
||||
Tüm REST uç noktalarını belgelemelidir
|
||||
Modülerlik ve bakım kolaylığı için harici `$ref` kullanmalıdır
|
||||
Doğrudan mesaj çevirici koduna eşlenmelidir
|
||||
Doğru istek/yanıt şemaları sağlamalıdır
|
||||
|
||||
## Doğru Kaynak
|
||||
|
||||
API aşağıdaki öğeler tarafından tanımlanır:
|
||||
**Mesaj Çeviriciler**: `trustgraph-base/trustgraph/messaging/translators/*.py`
|
||||
**Dağıtıcı Yöneticisi**: `trustgraph-flow/trustgraph/gateway/dispatch/manager.py`
|
||||
**Uç Nokta Yöneticisi**: `trustgraph-flow/trustgraph/gateway/endpoint/manager.py`
|
||||
|
||||
## Dizin Yapısı
|
||||
|
||||
```
|
||||
openapi/
|
||||
├── openapi.yaml # Main entry point
|
||||
├── paths/
|
||||
│ ├── config.yaml # Global services
|
||||
│ ├── flow.yaml
|
||||
│ ├── librarian.yaml
|
||||
│ ├── knowledge.yaml
|
||||
│ ├── collection-management.yaml
|
||||
│ ├── flow-services/ # Flow-hosted services
|
||||
│ │ ├── agent.yaml
|
||||
│ │ ├── document-rag.yaml
|
||||
│ │ ├── graph-rag.yaml
|
||||
│ │ ├── text-completion.yaml
|
||||
│ │ ├── prompt.yaml
|
||||
│ │ ├── embeddings.yaml
|
||||
│ │ ├── mcp-tool.yaml
|
||||
│ │ ├── triples.yaml
|
||||
│ │ ├── objects.yaml
|
||||
│ │ ├── nlp-query.yaml
|
||||
│ │ ├── structured-query.yaml
|
||||
│ │ ├── structured-diag.yaml
|
||||
│ │ ├── graph-embeddings.yaml
|
||||
│ │ ├── document-embeddings.yaml
|
||||
│ │ ├── text-load.yaml
|
||||
│ │ └── document-load.yaml
|
||||
│ ├── import-export/
|
||||
│ │ ├── core-import.yaml
|
||||
│ │ ├── core-export.yaml
|
||||
│ │ └── flow-import-export.yaml # WebSocket import/export
|
||||
│ ├── websocket.yaml
|
||||
│ └── metrics.yaml
|
||||
├── components/
|
||||
│ ├── schemas/
|
||||
│ │ ├── config/
|
||||
│ │ ├── flow/
|
||||
│ │ ├── librarian/
|
||||
│ │ ├── knowledge/
|
||||
│ │ ├── collection/
|
||||
│ │ ├── ai-services/
|
||||
│ │ ├── common/
|
||||
│ │ └── errors/
|
||||
│ ├── parameters/
|
||||
│ ├── responses/
|
||||
│ └── examples/
|
||||
└── security/
|
||||
└── bearerAuth.yaml
|
||||
```
|
||||
|
||||
## Hizmet Eşlemesi
|
||||
|
||||
### Küresel Hizmetler (`/api/v1/{kind}`)
|
||||
`config` - Yapılandırma yönetimi
|
||||
`flow` - Akış yaşam döngüsü
|
||||
`librarian` - Belge kütüphanesi
|
||||
`knowledge` - Bilgi çekirdekleri
|
||||
`collection-management` - Koleksiyon meta verileri
|
||||
|
||||
### Akışa Dayalı Hizmetler (`/api/v1/flow/{flow}/service/{kind}`)
|
||||
|
||||
**İstek/Yanıt:**
|
||||
`agent`, `text-completion`, `prompt`, `mcp-tool`
|
||||
`graph-rag`, `document-rag`
|
||||
`embeddings`, `graph-embeddings`, `document-embeddings`
|
||||
`triples`, `objects`, `nlp-query`, `structured-query`, `structured-diag`
|
||||
|
||||
**Gönder ve Unut:**
|
||||
`text-load`, `document-load`
|
||||
|
||||
### İçe/Dışa Aktarma
|
||||
`/api/v1/import-core` (POST)
|
||||
`/api/v1/export-core` (GET)
|
||||
`/api/v1/flow/{flow}/import/{kind}` (WebSocket)
|
||||
`/api/v1/flow/{flow}/export/{kind}` (WebSocket)
|
||||
|
||||
### Diğer
|
||||
`/api/v1/socket` (WebSocket çoklama)
|
||||
`/api/metrics` (Prometheus)
|
||||
|
||||
## Yaklaşım
|
||||
|
||||
### Aşama 1: Kurulum
|
||||
1. Dizin yapısını oluşturun
|
||||
2. Ana `openapi.yaml` dosyasını meta veriler, sunucular, güvenlik ile birlikte oluşturun
|
||||
3. Yeniden kullanılabilir bileşenleri (hatalar, ortak parametreler, güvenlik şemaları) oluşturun
|
||||
|
||||
### Aşama 2: Ortak Şemalar
|
||||
Hizmetler arasında kullanılan ortak şemaları oluşturun:
|
||||
`RdfValue`, `Triple` - RDF/üçlü yapılar
|
||||
`ErrorObject` - Hata yanıtı
|
||||
`DocumentMetadata`, `ProcessingMetadata` - Meta veri yapıları
|
||||
Ortak parametreler: `FlowId`, `User`, `Collection`
|
||||
|
||||
### Aşama 3: Küresel Hizmetler
|
||||
Her küresel hizmet için (yapılandırma, akış, kütüphaneci, bilgi, koleksiyon yönetimi):
|
||||
1. `paths/` içinde bir yol dosyası oluşturun
|
||||
2. `components/schemas/{service}/` içinde bir istek şeması oluşturun
|
||||
3. Bir yanıt şeması oluşturun
|
||||
4. Örnekler ekleyin
|
||||
5. Ana `openapi.yaml` dosyasından referans alın
|
||||
|
||||
### Aşama 4: Akışa Dayalı Hizmetler
|
||||
Her akışa dayalı hizmet için:
|
||||
1. `paths/flow-services/` içinde bir yol dosyası oluşturun
|
||||
2. `components/schemas/ai-services/` içinde istek/yanıt şemalarını oluşturun
|
||||
3. Gerekli durumlarda akış düzeyi akış bayrak dokümantasyonunu ekleyin
|
||||
4. Ana `openapi.yaml` dosyasından referans alın
|
||||
|
||||
### Aşama 5: İçe/Dışa Aktarma & WebSocket
|
||||
1. Temel içe/dışa aktarma uç noktalarını belgeleyin
|
||||
2. WebSocket protokol kalıplarını belgeleyin
|
||||
3. Akış düzeyindeki içe/dışa aktarma WebSocket uç noktalarını belgeleyin
|
||||
|
||||
### Aşama 6: Doğrulama
|
||||
1. OpenAPI doğrulama araçlarıyla doğrulayın
|
||||
2. Swagger UI ile test edin
|
||||
3. Tüm çeviricilerin kapsandığından emin olun
|
||||
|
||||
## Alan Adlandırma Kuralları
|
||||
|
||||
Tüm JSON alanları **kebab-case** kullanır:
|
||||
`flow-id`, `blueprint-name`, `doc-limit`, `entity-limit`, vb.
|
||||
|
||||
## Şema Dosyaları Oluşturma
|
||||
|
||||
Her çevirici için `trustgraph-base/trustgraph/messaging/translators/` içinde:
|
||||
|
||||
1. **Çevirici `to_pulsar()` yöntemini okuyun** - İstek şemasını tanımlar
|
||||
2. **Çevirici `from_pulsar()` yöntemini okuyun** - Yanıt şemasını tanımlar
|
||||
3. **Alan adlarını ve türlerini çıkarın**
|
||||
4. Aşağıdakilerle bir OpenAPI şeması oluşturun:
|
||||
Alan adları (kebab-case)
|
||||
Türler (string, integer, boolean, object, array)
|
||||
Gerekli alanlar
|
||||
Varsayılanlar
|
||||
Açıklamalar
|
||||
|
||||
### Örnek Eşleme Süreci
|
||||
|
||||
```python
|
||||
# From retrieval.py DocumentRagRequestTranslator
|
||||
def to_pulsar(self, data: Dict[str, Any]) -> DocumentRagQuery:
|
||||
return DocumentRagQuery(
|
||||
query=data["query"], # required string
|
||||
user=data.get("user", "trustgraph"), # optional string, default "trustgraph"
|
||||
collection=data.get("collection", "default"), # optional string, default "default"
|
||||
doc_limit=int(data.get("doc-limit", 20)), # optional integer, default 20
|
||||
streaming=data.get("streaming", False) # optional boolean, default false
|
||||
)
|
||||
```
|
||||
|
||||
Çevrilir:
|
||||
|
||||
```yaml
|
||||
# components/schemas/ai-services/DocumentRagRequest.yaml
|
||||
type: object
|
||||
required:
|
||||
- query
|
||||
properties:
|
||||
query:
|
||||
type: string
|
||||
description: Search query
|
||||
user:
|
||||
type: string
|
||||
default: trustgraph
|
||||
collection:
|
||||
type: string
|
||||
default: default
|
||||
doc-limit:
|
||||
type: integer
|
||||
default: 20
|
||||
description: Maximum number of documents to retrieve
|
||||
streaming:
|
||||
type: boolean
|
||||
default: false
|
||||
description: Enable streaming responses
|
||||
```
|
||||
|
||||
## Akışlı Yanıtlar
|
||||
|
||||
Akışlı yanıtları destekleyen hizmetler, `end_of_stream` bayrağı ile birden fazla yanıt döndürür:
|
||||
`agent`, `text-completion`, `prompt`
|
||||
`document-rag`, `graph-rag`
|
||||
|
||||
Bu kalıbı, her hizmetin yanıt şemasında belgeleyin.
|
||||
|
||||
## Hata Yanıtları
|
||||
|
||||
Tüm hizmetler aşağıdaki yanıtları döndürebilir:
|
||||
```yaml
|
||||
error:
|
||||
oneOf:
|
||||
- type: string
|
||||
- $ref: '#/components/schemas/ErrorObject'
|
||||
```
|
||||
|
||||
`ErrorObject` ifadesi nerede bulunuyor:
|
||||
```yaml
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
message:
|
||||
type: string
|
||||
```
|
||||
|
||||
## Referanslar
|
||||
|
||||
Çevirenler: `trustgraph-base/trustgraph/messaging/translators/`
|
||||
Dağıtım eşlemesi: `trustgraph-flow/trustgraph/gateway/dispatch/manager.py`
|
||||
Uç nokta yönlendirmesi: `trustgraph-flow/trustgraph/gateway/endpoint/manager.py`
|
||||
Hizmet özeti: `API_SERVICES_SUMMARY.md`
|
||||
965
docs/tech-specs/tr/pubsub.tr.md
Normal file
965
docs/tech-specs/tr/pubsub.tr.md
Normal file
|
|
@ -0,0 +1,965 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Pub/Sub Altyapısı"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Pub/Sub Altyapısı
|
||||
|
||||
> **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 belge, TrustGraph kod tabanı ile pub/sub altyapısı arasındaki tüm bağlantıları listeler. Şu anda sistem, Apache Pulsar'ı kullanmak üzere sabit kodlanmıştır. Bu analiz, yapılandırılabilir bir pub/sub soyutlamasına yönelik gelecekteki yeniden düzenlemeleri bilgilendirmek için tüm entegrasyon noktalarını belirler.
|
||||
|
||||
## Mevcut Durum: Pulsar Entegrasyon Noktaları
|
||||
|
||||
### 1. Doğrudan Pulsar İstemci Kullanımı
|
||||
|
||||
**Konum:** `trustgraph-flow/trustgraph/gateway/service.py`
|
||||
|
||||
API ağ geçidi, doğrudan Pulsar istemcisini içe aktarır ve örnekler:
|
||||
|
||||
**Satır 20:** `import pulsar`
|
||||
**Satırlar 54-61:** `pulsar.Client()`'ın doğrudan örneklenmesi, isteğe bağlı `pulsar.AuthenticationToken()` ile birlikte
|
||||
**Satırlar 33-35:** Ortam değişkenlerinden varsayılan Pulsar ana bilgisayarı yapılandırması
|
||||
**Satırlar 178-192:** `--pulsar-host`, `--pulsar-api-key` ve `--pulsar-listener` için CLI argümanları
|
||||
**Satırlar 78, 124:** `pulsar_client`'ı `ConfigReceiver` ve `DispatcherManager`'ye geçirir
|
||||
|
||||
Bu, bir soyutlama katmanı dışında bir Pulsar istemcisinin doğrudan örneklenmesini yapan tek konumdur.
|
||||
|
||||
### 2. Temel İşlemci Çerçevesi
|
||||
|
||||
**Konum:** `trustgraph-base/trustgraph/base/async_processor.py`
|
||||
|
||||
Tüm işlemciler için temel sınıf, Pulsar bağlantısı sağlar:
|
||||
|
||||
**Satır 9:** `import _pulsar` (istisna işleme için)
|
||||
**Satır 18:** `from . pubsub import PulsarClient`
|
||||
**Satır 38:** `pulsar_client_object = PulsarClient(**params)` oluşturur
|
||||
**Satırlar 104-108:** `pulsar_host` ve `pulsar_client`'i ortaya koyan özellikler
|
||||
**Satır 250:** Statik yöntem `add_args()`, CLI argümanları için `PulsarClient.add_args(parser)`'i çağırır
|
||||
**Satırlar 223-225:** `_pulsar.Interrupted` için istisna işleme
|
||||
|
||||
Tüm işlemciler `AsyncProcessor`'dan türetildiği için, bu merkezi bir entegrasyon noktasıdır.
|
||||
|
||||
### 3. Tüketici Soyutlaması
|
||||
|
||||
**Konum:** `trustgraph-base/trustgraph/base/consumer.py`
|
||||
|
||||
Kuyruklardan mesajlar tüketir ve işleyici fonksiyonlarını çağırır:
|
||||
|
||||
**Pulsar içe aktarmaları:**
|
||||
**Satır 12:** `from pulsar.schema import JsonSchema`
|
||||
**Satır 13:** `import pulsar`
|
||||
**Satır 14:** `import _pulsar`
|
||||
|
||||
**Pulsar'a özgü kullanım:**
|
||||
**Satırlar 100, 102:** `pulsar.InitialPosition.Earliest` / `pulsar.InitialPosition.Latest`
|
||||
**Satır 108:** `JsonSchema(self.schema)` sarmalayıcısı
|
||||
**Satır 110:** `pulsar.ConsumerType.Shared`
|
||||
**Satırlar 104-111:** Pulsar'a özgü parametrelerle `self.client.subscribe()`
|
||||
**Satırlar 143, 150, 65:** `consumer.unsubscribe()` ve `consumer.close()` yöntemleri
|
||||
**Satır 162:** `_pulsar.Timeout` istisnası
|
||||
**Satırlar 182, 205, 232:** `consumer.acknowledge()` / `consumer.negative_acknowledge()`
|
||||
|
||||
**Belge dosyası:** `trustgraph-base/trustgraph/base/consumer_spec.py`
|
||||
**Satır 22:** `processor.pulsar_client`'a referans
|
||||
|
||||
### 4. Yayıncı Soyutlaması
|
||||
|
||||
**Konum:** `trustgraph-base/trustgraph/base/producer.py`
|
||||
|
||||
Kuyruklara mesaj gönderir:
|
||||
|
||||
**Pulsar içe aktarmaları:**
|
||||
**Satır 2:** `from pulsar.schema import JsonSchema`
|
||||
|
||||
**Pulsar'a özgü kullanım:**
|
||||
**Satır 49:** `JsonSchema(self.schema)` sarmalayıcısı
|
||||
**Satırlar 47-51:** Pulsar'a özgü parametrelerle (konu, şema, chunking_enabled) `self.client.create_producer()`
|
||||
**Satırlar 31, 76:** `producer.close()` yöntemi
|
||||
**Satırlar 64-65:** Mesaj ve özelliklerle `producer.send()`
|
||||
|
||||
**Belge dosyası:** `trustgraph-base/trustgraph/base/producer_spec.py`
|
||||
**Satır 18:** `processor.pulsar_client`'a referans
|
||||
|
||||
### 5. Yayıncı Soyutlaması
|
||||
|
||||
**Konum:** `trustgraph-base/trustgraph/base/publisher.py`
|
||||
|
||||
Kuyruklu tamponlama ile asenkron mesaj yayınlama:
|
||||
|
||||
**Pulsar içe aktarmaları:**
|
||||
**Satır 2:** `from pulsar.schema import JsonSchema`
|
||||
**Satır 6:** `import pulsar`
|
||||
|
||||
**Pulsar'a özgü kullanım:**
|
||||
**Satır 52:** `JsonSchema(self.schema)` sarmalayıcısı
|
||||
**Satırlar 50-54:** Pulsar'a özgü parametrelerle `self.client.create_producer()`
|
||||
**Satırlar 101, 103:** Mesaj ve isteğe bağlı özelliklerle `producer.send()`
|
||||
**Satırlar 106-107:** `producer.flush()` ve `producer.close()` yöntemleri
|
||||
|
||||
### 6. Abonelik Soyutlaması
|
||||
|
||||
**Konum:** `trustgraph-base/trustgraph/base/subscriber.py`
|
||||
|
||||
Kuyruklardan çoklu alıcıya mesaj dağıtımı sağlar:
|
||||
|
||||
**Pulsar importları:**
|
||||
**6. Satır:** `from pulsar.schema import JsonSchema`
|
||||
**8. Satır:** `import _pulsar`
|
||||
|
||||
**Pulsar'a özgü kullanım:**
|
||||
**55. Satır:** `JsonSchema(self.schema)` wrapper
|
||||
**57. Satır:** `self.client.subscribe(**subscribe_args)`
|
||||
**101, 136, 160, 167-172. Satırlar:** Pulsar istisnaları: `_pulsar.Timeout`, `_pulsar.InvalidConfiguration`, `_pulsar.AlreadyClosed`
|
||||
**159, 166, 170. Satırlar:** Tüketici metotları: `negative_acknowledge()`, `unsubscribe()`, `close()`
|
||||
**247, 251. Satırlar:** Mesaj onayı: `acknowledge()`, `negative_acknowledge()`
|
||||
|
||||
**Spec dosyası:** `trustgraph-base/trustgraph/base/subscriber_spec.py`
|
||||
**19. Satır:** `processor.pulsar_client`'a referans
|
||||
|
||||
### 7. Şema Sistemi (Heart of Darkness)
|
||||
|
||||
**Konum:** `trustgraph-base/trustgraph/schema/`
|
||||
|
||||
Sistemdeki her mesaj şeması, Pulsar'ın şema çerçevesi kullanılarak tanımlanır.
|
||||
|
||||
**Temel öğeler:** `schema/core/primitives.py`
|
||||
**2. Satır:** `from pulsar.schema import Record, String, Boolean, Array, Integer`
|
||||
Tüm şemalar, Pulsar'ın `Record` temel sınıfından türetilir.
|
||||
Tüm alan türleri Pulsar türleridir: `String()`, `Integer()`, `Boolean()`, `Array()`, `Map()`, `Double()`
|
||||
|
||||
**Örnek şemalar:**
|
||||
`schema/services/llm.py` (2. Satır): `from pulsar.schema import Record, String, Array, Double, Integer, Boolean`
|
||||
`schema/services/config.py` (2. Satır): `from pulsar.schema import Record, Bytes, String, Boolean, Array, Map, Integer`
|
||||
|
||||
**Konu adlandırması:** `schema/core/topic.py`
|
||||
**2-3. Satırlar:** Konu formatı: `{kind}://{tenant}/{namespace}/{topic}`
|
||||
Bu URI yapısı Pulsar'a özgüdür (örneğin, `persistent://tg/flow/config`)
|
||||
|
||||
**Etki:**
|
||||
Kod tabanındaki tüm istek/yanıt mesaj tanımları, Pulsar şemalarını kullanır.
|
||||
Bu, aşağıdaki hizmetler için geçerlidir: yapılandırma, akış, LLM, istem, sorgu, depolama, aracı, koleksiyon, tanı, kütüphane, arama, NLP sorgusu, nesne sorgusu, alma, yapılandırılmış sorgu.
|
||||
Şema tanımları, tüm işlemciler ve hizmetler genelinde kapsamlı bir şekilde içe aktarılır ve kullanılır.
|
||||
|
||||
## Özet
|
||||
|
||||
### Kategoriye Göre Pulsar Bağımlılıkları
|
||||
|
||||
1. **İstem oluşturma:**
|
||||
Doğrudan: `gateway/service.py`
|
||||
Soyutlanmış: `async_processor.py` → `pubsub.py` (PulsarClient)
|
||||
|
||||
2. **Mesaj taşıma:**
|
||||
Tüketici: `consumer.py`, `consumer_spec.py`
|
||||
Üretici: `producer.py`, `producer_spec.py`
|
||||
Yayıncı: `publisher.py`
|
||||
Abonelik: `subscriber.py`, `subscriber_spec.py`
|
||||
|
||||
3. **Şema sistemi:**
|
||||
Temel türler: `schema/core/primitives.py`
|
||||
Tüm hizmet şemaları: `schema/services/*.py`
|
||||
Konu adlandırması: `schema/core/topic.py`
|
||||
|
||||
4. **Gereken Pulsar'a özgü kavramlar:**
|
||||
Konuya dayalı mesajlaşma
|
||||
Şema sistemi (Kayıt, alan türleri)
|
||||
Paylaşımlı abonelikler
|
||||
Mesaj onayı (olumlu/olumsuz)
|
||||
Tüketici konumlandırması (en erken/en son)
|
||||
Mesaj özellikleri
|
||||
Başlangıç konumları ve tüketici türleri
|
||||
Parçalama desteği
|
||||
Kalıcı ve kalıcı olmayan konular
|
||||
|
||||
### Yeniden Düzenleme Zorlukları
|
||||
|
||||
İyi haber: Soyutlama katmanı (Tüketici, Üretici, Yayıncı, Abonelik), çoğu Pulsar etkileşimini temiz bir şekilde kapsar.
|
||||
|
||||
Zorluklar:
|
||||
1. **Şema sisteminin yaygınlığı:** Her mesaj tanımı `pulsar.schema.Record` ve Pulsar alan türlerini kullanır.
|
||||
2. **Pulsar'a özgü numaralandırmalar:** `InitialPosition`, `ConsumerType`
|
||||
3. **Pulsar istisnaları:** `_pulsar.Timeout`, `_pulsar.Interrupted`, `_pulsar.InvalidConfiguration`, `_pulsar.AlreadyClosed`
|
||||
4. **Metot imzaları:** `acknowledge()`, `negative_acknowledge()`, `subscribe()`, `create_producer()`, vb.
|
||||
5. **Konu URI formatı:** Pulsar'ın `kind://tenant/namespace/topic` yapısı
|
||||
|
||||
### Sonraki Adımlar
|
||||
|
||||
Yayın/abone altyapısını yapılandırılabilir hale getirmek için şunları yapmamız gerekiyor:
|
||||
|
||||
1. İstem/şema sistemi için bir soyutlama arayüzü oluşturun.
|
||||
2. Pulsar'a özgü numaralandırmaları ve istisnaları soyutlayın.
|
||||
3. Şema sargıları veya alternatif şema tanımları oluşturun.
|
||||
4. Arayüzü hem Pulsar hem de alternatif sistemler (Kafka, RabbitMQ, Redis Streams, vb.) için uygulayın.
|
||||
5. `pubsub.py`'ı yapılandırılabilir hale getirin ve çoklu arka uçları destekleyin.
|
||||
6. Mevcut dağıtımlar için bir geçiş yolu sağlayın.
|
||||
|
||||
## Yaklaşım Taslağı 1: Şema Çeviri Katmanıyla Adaptör Kalıbı
|
||||
|
||||
### Temel Bilgi
|
||||
**Şema sistemi**, en derin entegrasyon noktasıdır - her şey ondan kaynaklanır. Önce bunu çözmemiz gerekiyor, aksi takdirde tüm kodu yeniden yazmamız gerekecek.
|
||||
|
||||
### Strateji: Minimum Bozulma ile Adaptörler
|
||||
|
||||
**1. Pulsar şemalarını, dahili gösterim olarak koruyun**
|
||||
Tüm şema tanımlarını yeniden yazmayın
|
||||
Şemalar, dahili olarak `pulsar.schema.Record` olarak kalır
|
||||
Adaptörleri, kendi kodumuz ile yayın/abonelik arka ucu arasındaki sınırdaki çevirileri yapmak için kullanın
|
||||
|
||||
**2. Bir yayın/abonelik soyutlama katmanı oluşturun:**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Existing Code (unchanged) │
|
||||
│ - Uses Pulsar schemas internally │
|
||||
│ - Consumer/Producer/Publisher │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
┌──────────────┴──────────────────────┐
|
||||
│ PubSubFactory (configurable) │
|
||||
│ - Creates backend-specific client │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
┌──────┴──────┐
|
||||
│ │
|
||||
┌───────▼─────┐ ┌────▼─────────┐
|
||||
│ PulsarAdapter│ │ KafkaAdapter │ etc...
|
||||
│ (passthrough)│ │ (translates) │
|
||||
└──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
**3. Soyut arayüzleri tanımlayın:**
|
||||
`PubSubClient` - istemci bağlantısı
|
||||
`PubSubProducer` - mesaj gönderme
|
||||
`PubSubConsumer` - mesaj alma
|
||||
`SchemaAdapter` - Pulsar şemalarını JSON'a veya arka uç özel formatlarına dönüştürme/dönüştürme
|
||||
|
||||
**4. Uygulama detayları:**
|
||||
|
||||
**Pulsar adaptörü için:** Neredeyse doğrudan geçiş, minimum çeviri
|
||||
|
||||
**Diğer arka uçlar için** (Kafka, RabbitMQ, vb.):
|
||||
Pulsar Kayıt nesnelerini JSON/byte'a serileştirin
|
||||
Aşağıdaki kavramları eşleyin:
|
||||
`InitialPosition.Earliest/Latest` → Kafka'nın auto.offset.reset'i
|
||||
`acknowledge()` → Kafka'nın commit'i
|
||||
`negative_acknowledge()` → Yeniden kuyruklama veya DLQ deseni
|
||||
Konu URI'leri → Arka uç özel konu adları
|
||||
|
||||
### Analiz
|
||||
|
||||
**Artıları:**
|
||||
✅ Mevcut hizmetlerde minimum kod değişikliği
|
||||
✅ Şemalar olduğu gibi kalır (büyük bir yeniden yazım olmaz)
|
||||
✅ Aşamalı geçiş yolu
|
||||
✅ Pulsar kullanıcıları hiçbir fark görmez
|
||||
✅ Yeni arka uçlar adaptörler aracılığıyla eklenir
|
||||
|
||||
**Eksileri:**
|
||||
⚠️ Hala Pulsar bağımlılığı taşır (şema tanımları için)
|
||||
⚠️ Kavramları çevirirken bazı uyumsuzluklar olabilir
|
||||
|
||||
### Alternatif Düşünce
|
||||
|
||||
Bir **TrustGraph şema sistemi** oluşturun; bu sistem, pub/sub'dan bağımsızdır (dataclass'lar veya Pydantic kullanarak). Ardından, bu sistemden Pulsar/Kafka/vb. şemalarını oluşturun. Bu, her şema dosyasının yeniden yazılmasını gerektirir ve potansiyel olarak uyumsuzluklara neden olabilir.
|
||||
|
||||
### Taslak 1 için Öneri
|
||||
|
||||
**Adaptör yaklaşımıyla** başlayın çünkü:
|
||||
1. Pratik bir yaklaşımdır - mevcut kodla çalışır
|
||||
2. Minimum riskle kavramı kanıtlar
|
||||
3. Gerekirse daha sonra yerel bir şema sistemine dönüştürülebilir
|
||||
4. Yapılandırma odaklıdır: tek bir ortam değişkeni arka uçları değiştirir
|
||||
|
||||
## Yaklaşım Taslağı 2: Dataclass'larla Arka Uçtan Bağımsız Şema Sistemi
|
||||
|
||||
### Temel Kavram
|
||||
|
||||
Python **dataclass'ları** tarafsız şema tanımı formatı olarak kullanın. Her pub/sub arka ucu, dataclass'lar için kendi serileştirme/deserileştirme işlemlerini sağlar; bu, Pulsar şemalarının kod tabanında kalma ihtiyacını ortadan kaldırır.
|
||||
|
||||
### Fabrika Seviyesinde Şema Çok Biçimliliği
|
||||
|
||||
Pulsar şemalarını çevirmek yerine, **her arka uç, standart Python dataclass'larıyla çalışan kendi şema işleme yöntemini sağlar**.
|
||||
|
||||
### Yayıncı Akışı
|
||||
|
||||
```python
|
||||
# 1. Get the configured backend from factory
|
||||
pubsub = get_pubsub() # Returns PulsarBackend, MQTTBackend, etc.
|
||||
|
||||
# 2. Get schema class from the backend
|
||||
# (Can be imported directly - backend-agnostic)
|
||||
from trustgraph.schema.services.llm import TextCompletionRequest
|
||||
|
||||
# 3. Create a producer/publisher for a specific topic
|
||||
producer = pubsub.create_producer(
|
||||
topic="text-completion-requests",
|
||||
schema=TextCompletionRequest # Tells backend what schema to use
|
||||
)
|
||||
|
||||
# 4. Create message instances (same API regardless of backend)
|
||||
request = TextCompletionRequest(
|
||||
system="You are helpful",
|
||||
prompt="Hello world",
|
||||
streaming=False
|
||||
)
|
||||
|
||||
# 5. Send the message
|
||||
producer.send(request) # Backend serializes appropriately
|
||||
```
|
||||
|
||||
### Tüketici Akışı
|
||||
|
||||
```python
|
||||
# 1. Get the configured backend
|
||||
pubsub = get_pubsub()
|
||||
|
||||
# 2. Create a consumer
|
||||
consumer = pubsub.subscribe(
|
||||
topic="text-completion-requests",
|
||||
schema=TextCompletionRequest # Tells backend how to deserialize
|
||||
)
|
||||
|
||||
# 3. Receive and deserialize
|
||||
msg = consumer.receive()
|
||||
request = msg.value() # Returns TextCompletionRequest dataclass instance
|
||||
|
||||
# 4. Use the data (type-safe access)
|
||||
print(request.system) # "You are helpful"
|
||||
print(request.prompt) # "Hello world"
|
||||
print(request.streaming) # False
|
||||
```
|
||||
|
||||
### Sahne Arkasındaki Olaylar
|
||||
|
||||
**Pulsar arka ucu için:**
|
||||
`create_producer()` → JSON şeması veya dinamik olarak oluşturulmuş bir kayıtla Pulsar üreticisi oluşturur.
|
||||
`send(request)` → veri sınıfını JSON/Pulsar formatına serileştirir ve Pulsar'a gönderir.
|
||||
`receive()` → Pulsar mesajını alır, veri sınıfına geri serileştirir.
|
||||
|
||||
**MQTT arka ucu için:**
|
||||
`create_producer()` → MQTT aracısına bağlanır, şema kaydı gerektirmez.
|
||||
`send(request)` → veri sınıfını JSON'a dönüştürür ve MQTT konusuna yayınlar.
|
||||
`receive()` → MQTT konusuna abone olur, JSON'ı veri sınıfına geri serileştirir.
|
||||
|
||||
**Kafka arka ucu için:**
|
||||
`create_producer()` → Kafka üreticisini oluşturur, gerekirse Avro şemasını kaydeder.
|
||||
`send(request)` → veri sınıfını Avro formatına serileştirir ve Kafka'ya gönderir.
|
||||
`receive()` → Kafka mesajını alır, Avro'yu veri sınıfına geri serileştirir.
|
||||
|
||||
### Temel Tasarım Noktaları
|
||||
|
||||
1. **Şema nesnesi oluşturma**: Veri sınıfı örneği (`TextCompletionRequest(...)`), arka uçtan bağımsız olarak aynıdır.
|
||||
2. **Arka uç, kodlamayı yönetir**: Her arka uç, veri sınıfını kablo formatına nasıl serileştireceğini bilir.
|
||||
3. **Oluşturma sırasında şema tanımı**: Üretici/tüketici oluştururken, şema türünü belirtirsiniz.
|
||||
4. **Tür güvenliği korunur**: Doğru bir `TextCompletionRequest` nesnesi alırsınız, bir sözlük değil.
|
||||
5. **Arka uç sızıntısı yok**: Uygulama kodu, arka uçla ilgili özel kütüphaneleri asla içe aktarmaz.
|
||||
|
||||
### Örnek Dönüşüm
|
||||
|
||||
**Mevcut (Pulsar'a özel):**
|
||||
```python
|
||||
# schema/services/llm.py
|
||||
from pulsar.schema import Record, String, Boolean, Integer
|
||||
|
||||
class TextCompletionRequest(Record):
|
||||
system = String()
|
||||
prompt = String()
|
||||
streaming = Boolean()
|
||||
```
|
||||
|
||||
**Yeni (Arka uçtan bağımsız):**
|
||||
```python
|
||||
# schema/services/llm.py
|
||||
from dataclasses import dataclass
|
||||
|
||||
@dataclass
|
||||
class TextCompletionRequest:
|
||||
system: str
|
||||
prompt: str
|
||||
streaming: bool = False
|
||||
```
|
||||
|
||||
### Arka Uç Entegrasyonu
|
||||
|
||||
Her arka uç, veri sınıflarının serileştirme/deserileştirme işlemlerini gerçekleştirir:
|
||||
|
||||
**Pulsar arka ucu:**
|
||||
Veri sınıflarından dinamik olarak `pulsar.schema.Record` sınıfları oluşturun
|
||||
Veya veri sınıflarını JSON'a serileştirin ve Pulsar'ın JSON şemasını kullanın
|
||||
Mevcut Pulsar kurulumlarıyla uyumluluğu korur
|
||||
|
||||
**MQTT/Redis arka ucu:**
|
||||
Veri sınıfı örneklerinin doğrudan JSON serileştirilmesi
|
||||
`dataclasses.asdict()` / `from_dict()` kullanın
|
||||
Hafif, şema kayıt defterine gerek yok
|
||||
|
||||
**Kafka arka ucu:**
|
||||
Veri sınıfı tanımlarından Avro şemaları oluşturun
|
||||
Confluent'ın şema kayıt defterini kullanın
|
||||
Şema evrimi desteğiyle tür güvenli serileştirme
|
||||
|
||||
### Mimari
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Application Code │
|
||||
│ - Uses dataclass schemas │
|
||||
│ - Backend-agnostic │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
┌──────────────┴──────────────────────┐
|
||||
│ PubSubFactory (configurable) │
|
||||
│ - get_pubsub() returns backend │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
┌──────┴──────┐
|
||||
│ │
|
||||
┌───────▼─────────┐ ┌────▼──────────────┐
|
||||
│ PulsarBackend │ │ MQTTBackend │
|
||||
│ - JSON schema │ │ - JSON serialize │
|
||||
│ - or dynamic │ │ - Simple queues │
|
||||
│ Record gen │ │ │
|
||||
└─────────────────┘ └───────────────────┘
|
||||
```
|
||||
|
||||
### Uygulama Detayları
|
||||
|
||||
**1. Şema tanımları:** Basit dataclass'lar ve tür ipuçları
|
||||
`str`, `int`, `bool`, `float` temel veri tipleri için
|
||||
`list[T]` diziler için
|
||||
`dict[str, T]` haritalar için
|
||||
Karmaşık tipler için iç içe dataclass'lar
|
||||
|
||||
**2. Her arka uç şunları sağlar:**
|
||||
Serileştirici: `dataclass → bytes/wire format`
|
||||
Seri dışa aktarıcı: `bytes/wire format → dataclass`
|
||||
Şema kaydı (gerekirse, örneğin Pulsar/Kafka)
|
||||
|
||||
**3. Tüketici/Üretici soyutlaması:**
|
||||
Zaten mevcut (consumer.py, producer.py)
|
||||
Arka uç tarafından sağlanan seri dışa aktarmayı kullanmak için güncellenmeli
|
||||
Doğrudan Pulsar içe aktarmalarını kaldırmalı
|
||||
|
||||
**4. Tür eşlemeleri:**
|
||||
Pulsar `String()` → Python `str`
|
||||
Pulsar `Integer()` → Python `int`
|
||||
Pulsar `Boolean()` → Python `bool`
|
||||
Pulsar `Array(T)` → Python `list[T]`
|
||||
Pulsar `Map(K, V)` → Python `dict[K, V]`
|
||||
Pulsar `Double()` → Python `float`
|
||||
Pulsar `Bytes()` → Python `bytes`
|
||||
|
||||
### Geçiş Yolu
|
||||
|
||||
1. `trustgraph/schema/` içindeki tüm şemaların **dataclass versiyonlarını oluşturun**
|
||||
2. Arka uç tarafından sağlanan seri dışa aktarmayı kullanmak için **arka uç sınıflarını (Tüketici, Üretici, Yayıncı, Abonelik) güncelleyin**
|
||||
3. JSON şemasını veya dinamik Kayıt oluşturmayı kullanarak **PulsarBackend'i uygulayın**
|
||||
4. **Mevcut dağıtımlarla geriye dönük uyumluluğu sağlamak için Pulsar ile test edin**
|
||||
5. Gerekirse **yeni arka uçlar ekleyin (MQTT, Kafka, Redis, vb.)**
|
||||
6. Şema dosyalarından **Pulsar içe aktarmalarını kaldırın**
|
||||
|
||||
### Avantajlar
|
||||
|
||||
✅ **Şema tanımlarında herhangi bir yayın/abonelik bağımlılığı yok**
|
||||
✅ **Standart Python** - anlaşılması, tür denetimi yapılması ve belgelenmesi kolay
|
||||
✅ **Modern araçlar** - mypy, IDE otomatik tamamlama, lint araçlarıyla çalışır
|
||||
✅ **Arka uç odaklı** - her arka uç yerel seri dışa aktarmayı kullanır
|
||||
✅ **Çeviri ek yükü yok** - doğrudan seri dışa aktarma, adaptörler yok
|
||||
✅ **Tür güvenliği** - uygun türlere sahip gerçek nesneler
|
||||
✅ **Kolay doğrulama** - gerekirse Pydantic kullanılabilir
|
||||
|
||||
### Zorluklar & Çözümler
|
||||
|
||||
**Zorluk:** Pulsar'ın `Record`'ı çalışma zamanı alan doğrulamasına sahiptir
|
||||
**Çözüm:** Gerekirse doğrulama için Pydantic dataclass'larını kullanın veya `__post_init__` ile Python 3.10+ dataclass özelliklerini kullanın
|
||||
|
||||
**Zorluk:** Bazı Pulsar'a özgü özellikler (örneğin `Bytes` türü)
|
||||
**Çözüm:** Bu türü dataclass'ta `bytes` türüne eşleyin, arka uç uygun şekilde kodlamayı işler
|
||||
|
||||
**Zorluk:** Konu adlandırması (`persistent://tenant/namespace/topic`)
|
||||
**Çözüm:** Şema tanımlarında konu adlarını soyutlayın, arka uç uygun formata dönüştürür
|
||||
|
||||
**Zorluk:** Şema evrimi ve sürüm oluşturma
|
||||
**Çözüm:** Her arka uç, yeteneklerine göre bunu işler (Pulsar şema sürümleri, Kafka şema kaydı, vb.)
|
||||
|
||||
**Zorluk:** İç içe karmaşık türler
|
||||
**Çözüm:** İç içe dataclass'ları kullanın, arka uçlar yinelemeli olarak seri dışa aktarır/serileştirir
|
||||
|
||||
### Tasarım Kararları
|
||||
|
||||
1. **Basit dataclass'lar mı yoksa Pydantic mi?**
|
||||
✅ **Karar: Basit Python dataclass'ları kullanın**
|
||||
Daha basit, ek bağımlılık yok
|
||||
Uygulamada doğrulama gerekli değil
|
||||
Anlaşılması ve bakımı daha kolay
|
||||
|
||||
2. **Şema evrimi:**
|
||||
✅ **Karar: Herhangi bir sürüm oluşturma mekanizmasına gerek yok**
|
||||
Şemalar kararlı ve uzun ömürlü
|
||||
Güncellemeler genellikle yeni alanlar ekler (geriye dönük uyumlu)
|
||||
Arka uçlar, yeteneklerine göre şema evrimini işler
|
||||
|
||||
3. **Geriye dönük uyumluluk:**
|
||||
✅ **Karar: Ana sürüm değişikliği, geriye dönük uyumluluk gerekli değil**
|
||||
Bu, bir kopma değişikliği olacak ve geçiş talimatları sağlanacak
|
||||
Temiz bir kopma, daha iyi bir tasarım sağlar
|
||||
Mevcut dağıtımlar için bir geçiş kılavuzu sağlanacaktır
|
||||
|
||||
4. **İç içe türler ve karmaşık yapılar:**
|
||||
✅ **Karar: İç içe dataclass'ları doğal olarak kullanın**
|
||||
Python dataclass'ları iç içe geçmeyi mükemmel şekilde işler
|
||||
Diziler için `list[T]`, haritalar için `dict[K, V]`
|
||||
Arka uçlar yinelemeli olarak seri dışa aktarır/serileştirir
|
||||
Örnek:
|
||||
```python
|
||||
@dataclass
|
||||
class Value:
|
||||
value: str
|
||||
is_uri: bool
|
||||
|
||||
@dataclass
|
||||
class Triple:
|
||||
s: Value # Nested dataclass
|
||||
p: Value
|
||||
o: Value
|
||||
|
||||
@dataclass
|
||||
class GraphQuery:
|
||||
triples: list[Triple] # Array of nested dataclasses
|
||||
metadata: dict[str, str]
|
||||
```
|
||||
|
||||
5. **Varsayılan değerler ve isteğe bağlı alanlar:**
|
||||
✅ **Karar: Gerekli, varsayılan ve isteğe bağlı alanların birleşimi**
|
||||
Gerekli alanlar: Herhangi bir varsayılan değer yok
|
||||
Varsayılan değerlere sahip alanlar: Her zaman mevcut, anlamlı varsayılan değerlere sahip
|
||||
Tamamen isteğe bağlı alanlar: `T | None = None`, `None` olduğunda serileştirmeden çıkarılır
|
||||
Örnek:
|
||||
```python
|
||||
@dataclass
|
||||
class TextCompletionRequest:
|
||||
system: str # Required, no default
|
||||
prompt: str # Required, no default
|
||||
streaming: bool = False # Optional with default value
|
||||
metadata: dict | None = None # Truly optional, can be absent
|
||||
```
|
||||
|
||||
**Önemli serileştirme kuralları:**
|
||||
|
||||
`metadata = None` olduğunda:
|
||||
```json
|
||||
{
|
||||
"system": "...",
|
||||
"prompt": "...",
|
||||
"streaming": false
|
||||
// metadata field NOT PRESENT
|
||||
}
|
||||
```
|
||||
|
||||
`metadata = {}` (açıkça boş) olduğunda:
|
||||
```json
|
||||
{
|
||||
"system": "...",
|
||||
"prompt": "...",
|
||||
"streaming": false,
|
||||
"metadata": {} // Field PRESENT but empty
|
||||
}
|
||||
```
|
||||
|
||||
**Temel ayrım:**
|
||||
`None` → JSON'da bulunmayan alan (serileştirilmiyor)
|
||||
Boş değer (`{}`, `[]`, `""`) → alan, boş bir değerle mevcut
|
||||
Bu, anlamsal olarak önemlidir: "sağlanmadı" ile "açıkça boş"
|
||||
Serileştirme arka uçları, `None` alanlarını atlamalı, bunları `null` olarak kodlamamalıdır.
|
||||
|
||||
## Yaklaşım Taslağı 3: Uygulama Detayları
|
||||
|
||||
### Genel Kuyruk Adlandırma Formatı
|
||||
|
||||
Arka uçlara özgü kuyruk adlarını, arka uçların uygun şekilde eşleyebileceği genel bir formata dönüştürün.
|
||||
|
||||
**Format:** `{qos}/{tenant}/{namespace}/{queue-name}`
|
||||
|
||||
Nerede:
|
||||
`qos`: Hizmet kalitesi seviyesi
|
||||
`q0` = en iyi çaba (ateşle ve unut, onay yok)
|
||||
`q1` = en az bir kez (onay gerektirir)
|
||||
`q2` = tam olarak bir kez (iki aşamalı onay)
|
||||
`tenant`: Çok kiracılılık için mantıksal gruplandırma
|
||||
`namespace`: Kiracı içindeki alt gruplandırma
|
||||
`queue-name`: Gerçek kuyruk/konu adı
|
||||
|
||||
**Örnekler:**
|
||||
```
|
||||
q1/tg/flow/text-completion-requests
|
||||
q2/tg/config/config-push
|
||||
q0/tg/metrics/stats
|
||||
```
|
||||
|
||||
### Arka Uç Konu Eşlemesi
|
||||
|
||||
Her arka uç, genel formatı kendi yerel formatına eşler:
|
||||
|
||||
**Pulsar Arka Ucu:**
|
||||
```python
|
||||
def map_topic(self, generic_topic: str) -> str:
|
||||
# Parse: q1/tg/flow/text-completion-requests
|
||||
qos, tenant, namespace, queue = generic_topic.split('/', 3)
|
||||
|
||||
# Map QoS to persistence
|
||||
persistence = 'persistent' if qos in ['q1', 'q2'] else 'non-persistent'
|
||||
|
||||
# Return Pulsar URI: persistent://tg/flow/text-completion-requests
|
||||
return f"{persistence}://{tenant}/{namespace}/{queue}"
|
||||
```
|
||||
|
||||
**MQTT Altyapısı:**
|
||||
```python
|
||||
def map_topic(self, generic_topic: str) -> tuple[str, int]:
|
||||
# Parse: q1/tg/flow/text-completion-requests
|
||||
qos, tenant, namespace, queue = generic_topic.split('/', 3)
|
||||
|
||||
# Map QoS level
|
||||
qos_level = {'q0': 0, 'q1': 1, 'q2': 2}[qos]
|
||||
|
||||
# Build MQTT topic including tenant/namespace for proper namespacing
|
||||
mqtt_topic = f"{tenant}/{namespace}/{queue}"
|
||||
|
||||
return mqtt_topic, qos_level
|
||||
```
|
||||
|
||||
### Güncellenmiş Konu Yardımcı Fonksiyonu
|
||||
|
||||
```python
|
||||
# schema/core/topic.py
|
||||
def topic(queue_name, qos='q1', tenant='tg', namespace='flow'):
|
||||
"""
|
||||
Create a generic topic identifier that can be mapped by backends.
|
||||
|
||||
Args:
|
||||
queue_name: The queue/topic name
|
||||
qos: Quality of service
|
||||
- 'q0' = best-effort (no ack)
|
||||
- 'q1' = at-least-once (ack required)
|
||||
- 'q2' = exactly-once (two-phase ack)
|
||||
tenant: Tenant identifier for multi-tenancy
|
||||
namespace: Namespace within tenant
|
||||
|
||||
Returns:
|
||||
Generic topic string: qos/tenant/namespace/queue_name
|
||||
|
||||
Examples:
|
||||
topic('my-queue') # q1/tg/flow/my-queue
|
||||
topic('config', qos='q2', namespace='config') # q2/tg/config/config
|
||||
"""
|
||||
return f"{qos}/{tenant}/{namespace}/{queue_name}"
|
||||
```
|
||||
|
||||
### Yapılandırma ve Başlatma
|
||||
|
||||
**Komut Satırı Argümanları + Ortam Değişkenleri:**
|
||||
|
||||
```python
|
||||
# In base/async_processor.py - add_args() method
|
||||
@staticmethod
|
||||
def add_args(parser):
|
||||
# Pub/sub backend selection
|
||||
parser.add_argument(
|
||||
'--pubsub-backend',
|
||||
default=os.getenv('PUBSUB_BACKEND', 'pulsar'),
|
||||
choices=['pulsar', 'mqtt'],
|
||||
help='Pub/sub backend (default: pulsar, env: PUBSUB_BACKEND)'
|
||||
)
|
||||
|
||||
# Pulsar-specific configuration
|
||||
parser.add_argument(
|
||||
'--pulsar-host',
|
||||
default=os.getenv('PULSAR_HOST', 'pulsar://localhost:6650'),
|
||||
help='Pulsar host (default: pulsar://localhost:6650, env: PULSAR_HOST)'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--pulsar-api-key',
|
||||
default=os.getenv('PULSAR_API_KEY', None),
|
||||
help='Pulsar API key (env: PULSAR_API_KEY)'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--pulsar-listener',
|
||||
default=os.getenv('PULSAR_LISTENER', None),
|
||||
help='Pulsar listener name (env: PULSAR_LISTENER)'
|
||||
)
|
||||
|
||||
# MQTT-specific configuration
|
||||
parser.add_argument(
|
||||
'--mqtt-host',
|
||||
default=os.getenv('MQTT_HOST', 'localhost'),
|
||||
help='MQTT broker host (default: localhost, env: MQTT_HOST)'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--mqtt-port',
|
||||
type=int,
|
||||
default=int(os.getenv('MQTT_PORT', '1883')),
|
||||
help='MQTT broker port (default: 1883, env: MQTT_PORT)'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--mqtt-username',
|
||||
default=os.getenv('MQTT_USERNAME', None),
|
||||
help='MQTT username (env: MQTT_USERNAME)'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--mqtt-password',
|
||||
default=os.getenv('MQTT_PASSWORD', None),
|
||||
help='MQTT password (env: MQTT_PASSWORD)'
|
||||
)
|
||||
```
|
||||
|
||||
**Fabrika Fonksiyonu:**
|
||||
|
||||
```python
|
||||
# In base/pubsub.py or base/pubsub_factory.py
|
||||
def get_pubsub(**config) -> PubSubBackend:
|
||||
"""
|
||||
Create and return a pub/sub backend based on configuration.
|
||||
|
||||
Args:
|
||||
config: Configuration dict from command-line args
|
||||
Must include 'pubsub_backend' key
|
||||
|
||||
Returns:
|
||||
Backend instance (PulsarBackend, MQTTBackend, etc.)
|
||||
"""
|
||||
backend_type = config.get('pubsub_backend', 'pulsar')
|
||||
|
||||
if backend_type == 'pulsar':
|
||||
return PulsarBackend(
|
||||
host=config.get('pulsar_host'),
|
||||
api_key=config.get('pulsar_api_key'),
|
||||
listener=config.get('pulsar_listener'),
|
||||
)
|
||||
elif backend_type == 'mqtt':
|
||||
return MQTTBackend(
|
||||
host=config.get('mqtt_host'),
|
||||
port=config.get('mqtt_port'),
|
||||
username=config.get('mqtt_username'),
|
||||
password=config.get('mqtt_password'),
|
||||
)
|
||||
else:
|
||||
raise ValueError(f"Unknown pub/sub backend: {backend_type}")
|
||||
```
|
||||
|
||||
**AsyncProcessor'da Kullanım:**
|
||||
|
||||
```python
|
||||
# In async_processor.py
|
||||
class AsyncProcessor:
|
||||
def __init__(self, **params):
|
||||
self.id = params.get("id")
|
||||
|
||||
# Create backend from config (replaces PulsarClient)
|
||||
self.pubsub = get_pubsub(**params)
|
||||
|
||||
# Rest of initialization...
|
||||
```
|
||||
|
||||
### Arka Uç Arayüzü
|
||||
|
||||
```python
|
||||
class PubSubBackend(Protocol):
|
||||
"""Protocol defining the interface all pub/sub backends must implement."""
|
||||
|
||||
def create_producer(self, topic: str, schema: type, **options) -> BackendProducer:
|
||||
"""
|
||||
Create a producer for a topic.
|
||||
|
||||
Args:
|
||||
topic: Generic topic format (qos/tenant/namespace/queue)
|
||||
schema: Dataclass type for messages
|
||||
options: Backend-specific options (e.g., chunking_enabled)
|
||||
|
||||
Returns:
|
||||
Backend-specific producer instance
|
||||
"""
|
||||
...
|
||||
|
||||
def create_consumer(
|
||||
self,
|
||||
topic: str,
|
||||
subscription: str,
|
||||
schema: type,
|
||||
initial_position: str = 'latest',
|
||||
consumer_type: str = 'shared',
|
||||
**options
|
||||
) -> BackendConsumer:
|
||||
"""
|
||||
Create a consumer for a topic.
|
||||
|
||||
Args:
|
||||
topic: Generic topic format (qos/tenant/namespace/queue)
|
||||
subscription: Subscription/consumer group name
|
||||
schema: Dataclass type for messages
|
||||
initial_position: 'earliest' or 'latest' (MQTT may ignore)
|
||||
consumer_type: 'shared', 'exclusive', 'failover' (MQTT may ignore)
|
||||
options: Backend-specific options
|
||||
|
||||
Returns:
|
||||
Backend-specific consumer instance
|
||||
"""
|
||||
...
|
||||
|
||||
def close(self) -> None:
|
||||
"""Close the backend connection."""
|
||||
...
|
||||
```
|
||||
|
||||
```python
|
||||
class BackendProducer(Protocol):
|
||||
"""Protocol for backend-specific producer."""
|
||||
|
||||
def send(self, message: Any, properties: dict = {}) -> None:
|
||||
"""Send a message (dataclass instance) with optional properties."""
|
||||
...
|
||||
|
||||
def flush(self) -> None:
|
||||
"""Flush any buffered messages."""
|
||||
...
|
||||
|
||||
def close(self) -> None:
|
||||
"""Close the producer."""
|
||||
...
|
||||
```
|
||||
|
||||
```python
|
||||
class BackendConsumer(Protocol):
|
||||
"""Protocol for backend-specific consumer."""
|
||||
|
||||
def receive(self, timeout_millis: int = 2000) -> Message:
|
||||
"""
|
||||
Receive a message from the topic.
|
||||
|
||||
Raises:
|
||||
TimeoutError: If no message received within timeout
|
||||
"""
|
||||
...
|
||||
|
||||
def acknowledge(self, message: Message) -> None:
|
||||
"""Acknowledge successful processing of a message."""
|
||||
...
|
||||
|
||||
def negative_acknowledge(self, message: Message) -> None:
|
||||
"""Negative acknowledge - triggers redelivery."""
|
||||
...
|
||||
|
||||
def unsubscribe(self) -> None:
|
||||
"""Unsubscribe from the topic."""
|
||||
...
|
||||
|
||||
def close(self) -> None:
|
||||
"""Close the consumer."""
|
||||
...
|
||||
```
|
||||
|
||||
```python
|
||||
class Message(Protocol):
|
||||
"""Protocol for a received message."""
|
||||
|
||||
def value(self) -> Any:
|
||||
"""Get the deserialized message (dataclass instance)."""
|
||||
...
|
||||
|
||||
def properties(self) -> dict:
|
||||
"""Get message properties/metadata."""
|
||||
...
|
||||
```
|
||||
|
||||
### Mevcut Sınıfların Yeniden Düzenlenmesi
|
||||
|
||||
Mevcut `Consumer`, `Producer`, `Publisher`, `Subscriber` sınıfları büyük ölçüde aynı kalacaktır:
|
||||
|
||||
**Mevcut sorumluluklar (saklanacak):**
|
||||
Asenkron iş parçacığı modeli ve görev grupları
|
||||
Yeniden bağlantı mantığı ve tekrar deneme işleme
|
||||
Ölçüm toplama
|
||||
Hız sınırlama
|
||||
Eşzamanlılık yönetimi
|
||||
|
||||
**Gerekli değişiklikler:**
|
||||
Doğrudan Pulsar içe aktarmalarını kaldırın (`pulsar.schema`, `pulsar.InitialPosition`, vb.)
|
||||
`BackendProducer`/`BackendConsumer`'i Pulsar istemcisi yerine kullanın
|
||||
Gerçek yayın/abonelik işlemlerini arka uç örneklerine devredin
|
||||
Genel kavramları arka uç çağrılarına eşleyin
|
||||
|
||||
**Örnek yeniden düzenleme:**
|
||||
|
||||
```python
|
||||
# OLD - consumer.py
|
||||
class Consumer:
|
||||
def __init__(self, client, topic, subscriber, schema, ...):
|
||||
self.client = client # Direct Pulsar client
|
||||
# ...
|
||||
|
||||
async def consumer_run(self):
|
||||
# Uses pulsar.InitialPosition, pulsar.ConsumerType
|
||||
self.consumer = self.client.subscribe(
|
||||
topic=self.topic,
|
||||
schema=JsonSchema(self.schema),
|
||||
initial_position=pulsar.InitialPosition.Earliest,
|
||||
consumer_type=pulsar.ConsumerType.Shared,
|
||||
)
|
||||
|
||||
# NEW - consumer.py
|
||||
class Consumer:
|
||||
def __init__(self, backend_consumer, schema, ...):
|
||||
self.backend_consumer = backend_consumer # Backend-specific consumer
|
||||
self.schema = schema
|
||||
# ...
|
||||
|
||||
async def consumer_run(self):
|
||||
# Backend consumer already created with right settings
|
||||
# Just use it directly
|
||||
while self.running:
|
||||
msg = await asyncio.to_thread(
|
||||
self.backend_consumer.receive,
|
||||
timeout_millis=2000
|
||||
)
|
||||
await self.handle_message(msg)
|
||||
```
|
||||
|
||||
### Arka Uç Özel Davranışlar
|
||||
|
||||
**Pulsar Arka Uç:**
|
||||
`q0`'ı `non-persistent://`'e, `q1`/`q2`'ü `persistent://`'e eşler.
|
||||
Tüm tüketici türlerini (paylaşımlı, özel, yedekli) destekler.
|
||||
Başlangıç konumunu (en erken/en son) destekler.
|
||||
Yerel mesaj onayı.
|
||||
Şema kayıt defteri desteği.
|
||||
|
||||
**MQTT Arka Uç:**
|
||||
`q0`/`q1`/`q2`'yi MQTT QoS seviyeleri 0/1/2'ye eşler.
|
||||
Adlandırma için konu yoluna kiracı/isim alanı ekler.
|
||||
Abonelik adlarından otomatik olarak istemci kimlikleri oluşturur.
|
||||
Başlangıç konumunu yoksayar (temel MQTT'de mesaj geçmişi yoktur).
|
||||
Tüketici türünü yoksayar (MQTT, tüketici grupları yerine istemci kimlikleri kullanır).
|
||||
Basit yayın/abone modeli.
|
||||
|
||||
### Tasarım Kararları Özeti
|
||||
|
||||
1. ✅ **Genel kuyruk adlandırması**: `qos/tenant/namespace/queue-name` formatı
|
||||
2. ✅ **Kuyruk kimliğindeki QoS**: Kuyruk tanımı tarafından belirlenir, yapılandırma ile değil.
|
||||
3. ✅ **Yeniden bağlanma**: Tüketici/Üretici sınıfları tarafından işlenir, arka uçlar tarafından değil.
|
||||
4. ✅ **MQTT konuları**: Doğru adlandırma için kiracı/isim alanı içerir.
|
||||
5. ✅ **Mesaj geçmişi**: MQTT, `initial_position` parametresini yoksayar (gelecek geliştirmeler).
|
||||
6. ✅ **İstemci kimlikleri**: MQTT arka ucu, abonelik adından otomatik olarak oluşturur.
|
||||
|
||||
### Gelecek Geliştirmeler
|
||||
|
||||
**MQTT mesaj geçmişi:**
|
||||
İsteğe bağlı bir kalıcılık katmanı eklenebilir (örneğin, saklanan mesajlar, harici depolama).
|
||||
`initial_position='earliest'`'ı desteklemeyi mümkün kılacaktır.
|
||||
Başlangıç uygulamasında gerekli değildir.
|
||||
1516
docs/tech-specs/tr/python-api-refactor.tr.md
Normal file
1516
docs/tech-specs/tr/python-api-refactor.tr.md
Normal file
File diff suppressed because it is too large
Load diff
271
docs/tech-specs/tr/query-time-explainability.tr.md
Normal file
271
docs/tech-specs/tr/query-time-explainability.tr.md
Normal file
|
|
@ -0,0 +1,271 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Sorgu Zamanı Açıklanabilirlik"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Sorgu Zamanı Açıklanabilirlik
|
||||
|
||||
> **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.
|
||||
|
||||
## Durum
|
||||
|
||||
Uygulandı
|
||||
|
||||
## Genel Bakış
|
||||
|
||||
Bu özellik, GraphRAG'ın sorgu yürütülmesi sırasında açıklanabilirlik verilerini nasıl kaydettiğini ve ilettiğini açıklamaktadır. Amaç, nihai cevaptan başlayarak, seçilen kenarlara ve kaynak belgelere kadar tam bir izlenebilirlik sağlamaktır.
|
||||
|
||||
Sorgu zamanı açıklanabilirliği, GraphRAG boru hattının akıl yürütme sırasında neler yaptığını yakalar. Bu, bilginin nereden geldiğini kaydeden, çıkarma zamanı köken bilgilerine bağlanır.
|
||||
|
||||
## Terminoloji
|
||||
|
||||
| Terim | Tanım |
|
||||
|------|------------|
|
||||
| **Açıklanabilirlik** | Bir sonucun nasıl elde edildiğinin kaydı |
|
||||
| **Oturum** | Tek bir GraphRAG sorgu yürütmesi |
|
||||
| **Kenar Seçimi** | Akıl yürütmeyle ilgili kenarların LLM tarafından seçilmesi |
|
||||
| **Köken Zinciri** | Kenar → parça → sayfa → belge yolu |
|
||||
|
||||
## Mimari
|
||||
|
||||
### Açıklanabilirlik Akışı
|
||||
|
||||
```
|
||||
GraphRAG Query
|
||||
│
|
||||
├─► Session Activity
|
||||
│ └─► Query text, timestamp
|
||||
│
|
||||
├─► Retrieval Entity
|
||||
│ └─► All edges retrieved from subgraph
|
||||
│
|
||||
├─► Selection Entity
|
||||
│ └─► Selected edges with LLM reasoning
|
||||
│ └─► Each edge links to extraction provenance
|
||||
│
|
||||
└─► Answer Entity
|
||||
└─► Reference to synthesized response (in librarian)
|
||||
```
|
||||
|
||||
### İki Aşamalı GraphRAG İşlem Hattı
|
||||
|
||||
1. **Kenar Seçimi**: LLM, alt grafikten ilgili kenarları seçer ve her biri için bir gerekçe sunar.
|
||||
2. **Sentez**: LLM, yalnızca seçilen kenarlardan cevap oluşturur.
|
||||
|
||||
Bu ayrım, açıklanabilirliği sağlar - hangi kenarların katkıda bulunduğunu tam olarak biliyoruz.
|
||||
|
||||
### Depolama
|
||||
|
||||
Açıklanabilirlik üçlüleri, yapılandırılabilir bir koleksiyonda saklanır (varsayılan: `explainability`).
|
||||
Kaynak ilişkileri için PROV-O ontolojisi kullanılır.
|
||||
Kenar referansları için RDF-star yeniden tanımlaması.
|
||||
Cevap içeriği, kütüphaneci hizmetinde saklanır (satır içi değil - çok büyük).
|
||||
|
||||
### Gerçek Zamanlı Akış
|
||||
|
||||
Açıklanabilirlik olayları, sorgu yürütüldüğü sırada istemciye akış olarak gönderilir:
|
||||
|
||||
1. Oturum oluşturuldu → olay gönderildi.
|
||||
2. Kenarlar alındı → olay gönderildi.
|
||||
3. Gerekçeyle birlikte kenarlar seçildi → olay gönderildi.
|
||||
4. Cevap oluşturuldu → olay gönderildi.
|
||||
|
||||
İstemci, `explain_id` ve `explain_collection`'i tam ayrıntıları almak için kullanır.
|
||||
|
||||
## URI Yapısı
|
||||
|
||||
Tüm URI'ler, UUID'lerle birlikte `urn:trustgraph:` ad alanını kullanır:
|
||||
|
||||
| Varlık | URI Kalıbı |
|
||||
|--------|-------------|
|
||||
| Oturum | `urn:trustgraph:session:{uuid}` |
|
||||
| Alma | `urn:trustgraph:prov:retrieval:{uuid}` |
|
||||
| Seçim | `urn:trustgraph:prov:selection:{uuid}` |
|
||||
| Cevap | `urn:trustgraph:prov:answer:{uuid}` |
|
||||
| Kenar Seçimi | `urn:trustgraph:prov:edge:{uuid}:{index}` |
|
||||
|
||||
## RDF Modeli (PROV-O)
|
||||
|
||||
### Oturum Etkinliği
|
||||
|
||||
```turtle
|
||||
<session-uri> a prov:Activity ;
|
||||
rdfs:label "GraphRAG query session" ;
|
||||
prov:startedAtTime "2024-01-15T10:30:00Z" ;
|
||||
tg:query "What was the War on Terror?" .
|
||||
```
|
||||
|
||||
### Veri Alma Varlığı
|
||||
|
||||
```turtle
|
||||
<retrieval-uri> a prov:Entity ;
|
||||
rdfs:label "Retrieved edges" ;
|
||||
prov:wasGeneratedBy <session-uri> ;
|
||||
tg:edgeCount 50 .
|
||||
```
|
||||
|
||||
### Seçim Varlığı
|
||||
|
||||
```turtle
|
||||
<selection-uri> a prov:Entity ;
|
||||
rdfs:label "Selected edges" ;
|
||||
prov:wasDerivedFrom <retrieval-uri> ;
|
||||
tg:selectedEdge <edge-sel-0> ;
|
||||
tg:selectedEdge <edge-sel-1> .
|
||||
|
||||
<edge-sel-0> tg:edge << <s> <p> <o> >> ;
|
||||
tg:reasoning "This edge establishes the key relationship..." .
|
||||
```
|
||||
|
||||
### Cevap Varlığı
|
||||
|
||||
```turtle
|
||||
<answer-uri> a prov:Entity ;
|
||||
rdfs:label "GraphRAG answer" ;
|
||||
prov:wasDerivedFrom <selection-uri> ;
|
||||
tg:document <urn:trustgraph:answer:{uuid}> .
|
||||
```
|
||||
|
||||
`tg:document`, kütüphaneci hizmetinde saklanan cevabı referans alır.
|
||||
|
||||
## Ad Alanı Sabitleri
|
||||
|
||||
`trustgraph-base/trustgraph/provenance/namespaces.py` içinde tanımlanmıştır:
|
||||
|
||||
| Sabit | URI |
|
||||
|----------|-----|
|
||||
| `TG_QUERY` | `https://trustgraph.ai/ns/query` |
|
||||
| `TG_EDGE_COUNT` | `https://trustgraph.ai/ns/edgeCount` |
|
||||
| `TG_SELECTED_EDGE` | `https://trustgraph.ai/ns/selectedEdge` |
|
||||
| `TG_EDGE` | `https://trustgraph.ai/ns/edge` |
|
||||
| `TG_REASONING` | `https://trustgraph.ai/ns/reasoning` |
|
||||
| `TG_CONTENT` | `https://trustgraph.ai/ns/content` |
|
||||
| `TG_DOCUMENT` | `https://trustgraph.ai/ns/document` |
|
||||
|
||||
## GraphRagResponse Şeması
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class GraphRagResponse:
|
||||
error: Error | None = None
|
||||
response: str = ""
|
||||
end_of_stream: bool = False
|
||||
explain_id: str | None = None
|
||||
explain_collection: str | None = None
|
||||
message_type: str = "" # "chunk" or "explain"
|
||||
end_of_session: bool = False
|
||||
```
|
||||
|
||||
### Mesaj Türleri
|
||||
|
||||
| mesaj_türü | Amaç |
|
||||
|--------------|---------|
|
||||
| `chunk` | Yanıt metni (akış veya son) |
|
||||
| `explain` | IRI referansıyla açıklanabilirlik olayı |
|
||||
|
||||
### Oturum Yaşam Döngüsü
|
||||
|
||||
1. Birden fazla `explain` mesajı (oturum, alma, seçim, yanıt)
|
||||
2. Birden fazla `chunk` mesajı (akış yanıtı)
|
||||
3. `end_of_session=True` ile birlikte son `chunk`
|
||||
|
||||
## Kenar Seçim Formatı
|
||||
|
||||
LLM, seçilen kenarlarla birlikte JSONL döndürür:
|
||||
|
||||
```jsonl
|
||||
{"id": "edge-hash-1", "reasoning": "This edge shows the key relationship..."}
|
||||
{"id": "edge-hash-2", "reasoning": "Provides supporting evidence..."}
|
||||
```
|
||||
|
||||
`id`, `(labeled_s, labeled_p, labeled_o)`'nin `edge_id()` tarafından hesaplanan bir karma değeridir.
|
||||
|
||||
## URI'nin Korunması
|
||||
|
||||
### Sorun
|
||||
|
||||
GraphRAG, LLM'ye okunabilir etiketler gösterir, ancak açıklanabilirlik, köken takibi için orijinal URI'lere ihtiyaç duyar.
|
||||
|
||||
### Çözüm
|
||||
|
||||
`get_labelgraph()`, şunları döndürür:
|
||||
`labeled_edges`: LLM için `(label_s, label_p, label_o)` listesi
|
||||
`uri_map`: `edge_id(labels)` → `(uri_s, uri_p, uri_o)` eşlemesini içeren sözlük
|
||||
|
||||
Açıklanabilirlik verilerini saklarken, `uri_map`'dan gelen URI'ler kullanılır.
|
||||
|
||||
## Köken Takibi
|
||||
|
||||
### Kaynaktan Kenara
|
||||
|
||||
Seçilen kenarlar, kaynak belgelere kadar izlenebilir:
|
||||
|
||||
1. İçeren alt grafiği sorgulayın: `?subgraph tg:contains <<s p o>>`
|
||||
2. Kök belgeye kadar `prov:wasDerivedFrom` zincirini izleyin
|
||||
3. Zincirdeki her adım: parça → sayfa → belge
|
||||
|
||||
### Cassandra Tırnaklı Üçlü Desteği
|
||||
|
||||
Cassandra sorgu hizmeti, tırnaklı üçlüleri eşleştirmeyi destekler:
|
||||
|
||||
```python
|
||||
# In get_term_value():
|
||||
elif term.type == TRIPLE:
|
||||
return serialize_triple(term.triple)
|
||||
```
|
||||
|
||||
Bu, şu tür sorguları mümkün kılar:
|
||||
```
|
||||
?subgraph tg:contains <<http://example.org/s http://example.org/p "value">>
|
||||
```
|
||||
|
||||
## CLI Kullanımı
|
||||
|
||||
```bash
|
||||
tg-invoke-graph-rag --explainable -q "What was the War on Terror?"
|
||||
```
|
||||
|
||||
### Çıktı Formatı
|
||||
|
||||
```
|
||||
[session] urn:trustgraph:session:abc123
|
||||
|
||||
[retrieval] urn:trustgraph:prov:retrieval:abc123
|
||||
|
||||
[selection] urn:trustgraph:prov:selection:abc123
|
||||
Selected 12 edge(s)
|
||||
Edge: (Guantanamo, definition, A detention facility...)
|
||||
Reason: Directly connects Guantanamo to the War on Terror
|
||||
Source: Chunk 1 → Page 2 → Beyond the Vigilant State
|
||||
|
||||
[answer] urn:trustgraph:prov:answer:abc123
|
||||
|
||||
Based on the provided knowledge statements...
|
||||
```
|
||||
|
||||
### Özellikler
|
||||
|
||||
Sorgu sırasında gerçek zamanlı açıklanabilirlik olayları
|
||||
`rdfs:label` aracılığıyla kenar bileşenleri için etiket çözümü
|
||||
`prov:wasDerivedFrom` aracılığıyla kaynak zinciri takibi
|
||||
Tekrarlanan sorguları önlemek için etiket önbelleği
|
||||
|
||||
## Uygulanan Dosyalar
|
||||
|
||||
| Dosya | Amaç |
|
||||
|------|---------|
|
||||
| `trustgraph-base/trustgraph/provenance/uris.py` | URI oluşturucular |
|
||||
| `trustgraph-base/trustgraph/provenance/namespaces.py` | RDF ad alanı sabitleri |
|
||||
| `trustgraph-base/trustgraph/provenance/triples.py` | Üçlü oluşturucular |
|
||||
| `trustgraph-base/trustgraph/schema/services/retrieval.py` | GraphRagResponse şeması |
|
||||
| `trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py` | URI korumasıyla temel GraphRAG |
|
||||
| `trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` | Kütüphaneci entegrasyonlu hizmet |
|
||||
| `trustgraph-flow/trustgraph/query/triples/cassandra/service.py` | Tırnaklı üçlü sorgu desteği |
|
||||
| `trustgraph-cli/trustgraph/cli/invoke_graph_rag.py` | Açıklanabilirlik gösterimiyle CLI |
|
||||
|
||||
## Referanslar
|
||||
|
||||
PROV-O (W3C Provenance Ontology): https://www.w3.org/TR/prov-o/
|
||||
RDF-star: https://w3c.github.io/rdf-star/
|
||||
Çıkarma zamanı kökeni: `docs/tech-specs/extraction-time-provenance.md`
|
||||
296
docs/tech-specs/tr/rag-streaming-support.tr.md
Normal file
296
docs/tech-specs/tr/rag-streaming-support.tr.md
Normal file
|
|
@ -0,0 +1,296 @@
|
|||
---
|
||||
layout: default
|
||||
title: "RAG Akış Desteği Teknik Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# RAG Akış Desteği 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, GraphRAG ve DocumentRAG hizmetlerine akış desteği eklemeyi tanımlar. Bu, bilgi grafiği ve belge sorguları için gerçek zamanlı, token bazlı yanıtlar sağlar. Bu, LLM metin tamamlama, istem ve ajan hizmetleri için zaten uygulanan mevcut akış mimarisini genişletir.
|
||||
|
||||
## Hedefler
|
||||
|
||||
**Tutarlı akış kullanıcı deneyimi**: Tüm TrustGraph hizmetlerinde aynı akış deneyimini sağlayın.
|
||||
**Minimum API değişiklikleri**: Akış desteğini, yerleşik kalıpları izleyerek tek bir `streaming` bayrağıyla ekleyin.
|
||||
**Geriye dönük uyumluluk**: Mevcut, akış olmayan davranışı varsayılan olarak koruyun.
|
||||
**Mevcut altyapıyı yeniden kullanın**: Zaten uygulanan PromptClient akışını kullanın.
|
||||
**Gateway desteği**: İstemci uygulamaları için websocket gateway üzerinden akışı etkinleştirin.
|
||||
|
||||
## Arka Plan
|
||||
|
||||
Şu anda uygulanan akış hizmetleri:
|
||||
**LLM metin tamamlama hizmeti**: 1. Aşama - LLM sağlayıcılardan akış.
|
||||
**İstem hizmeti**: 2. Aşama - istem şablonları aracılığıyla akış.
|
||||
**Ajan hizmeti**: 3.-4. Aşama - ReAct yanıtlarını, artımlı düşünce/gözlem/cevap parçalarıyla akış.
|
||||
|
||||
RAG hizmetleri için mevcut sınırlamalar:
|
||||
GraphRAG ve DocumentRAG yalnızca engellenen yanıtları destekler.
|
||||
Kullanıcılar, herhangi bir çıktı görmeden önce LLM'den gelen tamamlanmış yanıtı beklemelidir.
|
||||
Bilgi grafiği veya belge sorgularından gelen uzun yanıtlar için kötü kullanıcı deneyimi.
|
||||
Diğer TrustGraph hizmetlerine kıyasla tutarsız deneyim.
|
||||
|
||||
Bu özellik, GraphRAG ve DocumentRAG'a akış desteği ekleyerek bu boşlukları giderir. Token bazlı yanıtları etkinleştirerek, TrustGraph şunları yapabilir:
|
||||
Tüm sorgu türleri için tutarlı bir akış kullanıcı deneyimi sağlayın.
|
||||
RAG sorguları için algılanan gecikmeyi azaltın.
|
||||
Uzun süren sorgular için daha iyi ilerleme geri bildirimi sağlayın.
|
||||
İstemci uygulamalarında gerçek zamanlı görüntülemeyi destekleyin.
|
||||
|
||||
## Teknik Tasarım
|
||||
|
||||
### Mimari
|
||||
|
||||
RAG akış uygulaması, mevcut altyapıyı kullanır:
|
||||
|
||||
1. **PromptClient Akışı** (Zaten uygulandı)
|
||||
`kg_prompt()` ve `document_prompt()` zaten `streaming` ve `chunk_callback` parametrelerini kabul eder.
|
||||
Bunlar dahili olarak akış desteğiyle `prompt()`'ı çağırır.
|
||||
PromptClient'ta herhangi bir değişiklik yapılmasına gerek yoktur.
|
||||
|
||||
Modül: `trustgraph-base/trustgraph/base/prompt_client.py`
|
||||
|
||||
2. **GraphRAG Hizmeti** (Akış parametresi geçişi gereklidir)
|
||||
`query()` yöntemine `streaming` parametresini ekleyin.
|
||||
Akış bayrağını ve geri çağırmaları `prompt_client.kg_prompt()`'a geçirin.
|
||||
GraphRagRequest şemasının `streaming` alanına ihtiyacı vardır.
|
||||
|
||||
Modüller:
|
||||
`trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py`
|
||||
`trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` (İşlemci)
|
||||
`trustgraph-base/trustgraph/schema/graph_rag.py` (İstek şeması)
|
||||
`trustgraph-flow/trustgraph/gateway/dispatch/graph_rag.py` (Gateway)
|
||||
|
||||
3. **DocumentRAG Hizmeti** (Akış parametresi geçişi gereklidir)
|
||||
`query()` yöntemine `streaming` parametresini ekleyin.
|
||||
Akış bayrağını ve geri çağırmaları `prompt_client.document_prompt()`'a geçirin.
|
||||
DocumentRagRequest şemasının `streaming` alanına ihtiyacı vardır.
|
||||
|
||||
Modüller:
|
||||
`trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py`
|
||||
`trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` (İşlemci)
|
||||
`trustgraph-base/trustgraph/schema/document_rag.py` (İstek şeması)
|
||||
`trustgraph-flow/trustgraph/gateway/dispatch/document_rag.py` (Gateway)
|
||||
|
||||
### Veri Akışı
|
||||
|
||||
**Engellenmeyen (mevcut)**:
|
||||
```
|
||||
Client → Gateway → RAG Service → PromptClient.kg_prompt(streaming=False)
|
||||
↓
|
||||
Prompt Service → LLM
|
||||
↓
|
||||
Complete response
|
||||
↓
|
||||
Client ← Gateway ← RAG Service ← Response
|
||||
```
|
||||
|
||||
**Akış (önerilen)**:
|
||||
```
|
||||
Client → Gateway → RAG Service → PromptClient.kg_prompt(streaming=True, chunk_callback=cb)
|
||||
↓
|
||||
Prompt Service → LLM (streaming)
|
||||
↓
|
||||
Chunk → callback → RAG Response (chunk)
|
||||
↓ ↓
|
||||
Client ← Gateway ← ────────────────────────────────── Response stream
|
||||
```
|
||||
|
||||
### API'ler
|
||||
|
||||
**GraphRAG Değişiklikleri**:
|
||||
|
||||
1. **GraphRag.query()** - Akış parametreleri eklendi.
|
||||
```python
|
||||
async def query(
|
||||
self, query, user, collection,
|
||||
verbose=False, streaming=False, chunk_callback=None # NEW
|
||||
):
|
||||
# ... existing entity/triple retrieval ...
|
||||
|
||||
if streaming and chunk_callback:
|
||||
resp = await self.prompt_client.kg_prompt(
|
||||
query, kg,
|
||||
streaming=True,
|
||||
chunk_callback=chunk_callback
|
||||
)
|
||||
else:
|
||||
resp = await self.prompt_client.kg_prompt(query, kg)
|
||||
|
||||
return resp
|
||||
```
|
||||
|
||||
2. **GraphRagRequest şeması** - Akış alanı ekleyin.
|
||||
```python
|
||||
class GraphRagRequest(Record):
|
||||
query = String()
|
||||
user = String()
|
||||
collection = String()
|
||||
streaming = Boolean() # NEW
|
||||
```
|
||||
|
||||
3. **GraphRagResponse şeması** - Akış alanlarını ekleyin (Agent modelini takip edin).
|
||||
```python
|
||||
class GraphRagResponse(Record):
|
||||
response = String() # Legacy: complete response
|
||||
chunk = String() # NEW: streaming chunk
|
||||
end_of_stream = Boolean() # NEW: indicates last chunk
|
||||
```
|
||||
|
||||
4. **İşlemci** - Veriyi sürekli akış halinde ilet.
|
||||
```python
|
||||
async def handle(self, msg):
|
||||
# ... existing code ...
|
||||
|
||||
async def send_chunk(chunk):
|
||||
await self.respond(GraphRagResponse(
|
||||
chunk=chunk,
|
||||
end_of_stream=False,
|
||||
response=None
|
||||
))
|
||||
|
||||
if request.streaming:
|
||||
full_response = await self.rag.query(
|
||||
query=request.query,
|
||||
user=request.user,
|
||||
collection=request.collection,
|
||||
streaming=True,
|
||||
chunk_callback=send_chunk
|
||||
)
|
||||
# Send final message
|
||||
await self.respond(GraphRagResponse(
|
||||
chunk=None,
|
||||
end_of_stream=True,
|
||||
response=full_response
|
||||
))
|
||||
else:
|
||||
# Existing non-streaming path
|
||||
response = await self.rag.query(...)
|
||||
await self.respond(GraphRagResponse(response=response))
|
||||
```
|
||||
|
||||
**DocumentRAG Değişiklikleri**:
|
||||
|
||||
GraphRAG ile aynı yapı:
|
||||
1. `streaming` ve `chunk_callback` parametrelerini `DocumentRag.query()`'ye ekleyin.
|
||||
2. `streaming` alanını `DocumentRagRequest`'e ekleyin.
|
||||
3. `chunk` ve `end_of_stream` alanlarını `DocumentRagResponse`'ye ekleyin.
|
||||
4. İşlemciyi, geri çağırmalarla akışı işleyebilecek şekilde güncelleyin.
|
||||
|
||||
**Gateway Değişiklikleri**:
|
||||
|
||||
Hem `graph_rag.py` hem de `document_rag.py`, gateway/dispatch içinde, akış parçacıklarını websocket'e iletebilmesi için güncellenmelidir:
|
||||
|
||||
```python
|
||||
async def handle(self, message, session, websocket):
|
||||
# ... existing code ...
|
||||
|
||||
if request.streaming:
|
||||
async def recipient(resp):
|
||||
if resp.chunk:
|
||||
await websocket.send(json.dumps({
|
||||
"id": message["id"],
|
||||
"response": {"chunk": resp.chunk},
|
||||
"complete": resp.end_of_stream
|
||||
}))
|
||||
return resp.end_of_stream
|
||||
|
||||
await self.rag_client.request(request, recipient=recipient)
|
||||
else:
|
||||
# Existing non-streaming path
|
||||
resp = await self.rag_client.request(request)
|
||||
await websocket.send(...)
|
||||
```
|
||||
|
||||
### Uygulama Detayları
|
||||
|
||||
**Uygulama sırası**:
|
||||
1. Şema alanlarını ekleyin (Hem RAG hizmetleri için İstek + Yanıt)
|
||||
2. GraphRag.query() ve DocumentRag.query() yöntemlerini güncelleyin
|
||||
3. Akışı işlemek için İşleyicileri güncelleyin
|
||||
4. Ağ geçidi yönlendirme işleyicilerini güncelleyin
|
||||
5. `--no-streaming` bayraklarını `tg-invoke-graph-rag` ve `tg-invoke-document-rag`'ye ekleyin (akış varsayılan olarak etkindir, ajan CLI kalıbını takip eder)
|
||||
|
||||
**Geri çağırma kalıbı**:
|
||||
Ajan akışında oluşturulan aynı asenkron geri çağırma kalıbını izleyin:
|
||||
İşleyici, `async def send_chunk(chunk)` geri çağrısını tanımlar
|
||||
Geri çağrıyı RAG hizmetine iletir
|
||||
RAG hizmeti, geri çağrıyı PromptClient'a iletir
|
||||
PromptClient, her LLM parçası için geri çağrıyı çağırır
|
||||
İşleyici, her parça için akış yanıt mesajını gönderir
|
||||
|
||||
**Hata işleme**:
|
||||
Akış sırasında oluşan hatalar, `end_of_stream=True` ile hata yanıtı göndermelidir
|
||||
Ajan akışından mevcut hata yayılım kalıplarını izleyin
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
Mevcut RAG hizmetlerinin ötesinde yeni güvenlik hususları yoktur:
|
||||
Akış yanıtları, aynı kullanıcı/toplam izolasyonunu kullanır
|
||||
Kimlik doğrulama veya yetkilendirmede herhangi bir değişiklik yoktur
|
||||
Parça sınırları, hassas verileri ortaya çıkarmaz
|
||||
|
||||
## Performans Hususları
|
||||
|
||||
**Faydaları**:
|
||||
Algılanan gecikmenin azaltılması (ilk belirteçler daha hızlı gelir)
|
||||
Uzun yanıtlar için daha iyi kullanıcı deneyimi
|
||||
Daha düşük bellek kullanımı (tam yanıtı tamponlamaya gerek yoktur)
|
||||
|
||||
**Olası endişeler**:
|
||||
Akış yanıtları için daha fazla Pulsar mesajı
|
||||
Parçalama/geri çağırma ek yükü için biraz daha yüksek CPU
|
||||
Akış, isteğe bağlıdır, varsayılan olarak akış etkin değildir, bu nedenle bu sorunlar hafifletilmiştir
|
||||
|
||||
**Test hususları**:
|
||||
Çok sayıda üçlü içeren büyük bilgi grafikleriyle test edin
|
||||
Çok sayıda alınmış belgeyle test edin
|
||||
Akışın ve akış dışı durumun ek yükünü ölçün
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
**Birim testleri**:
|
||||
GraphRag.query()'yi streaming=True/False ile test edin
|
||||
DocumentRag.query()'yi streaming=True/False ile test edin
|
||||
Geri çağırma çağrılarını doğrulamak için PromptClient'ı taklit edin
|
||||
|
||||
**Entegrasyon testleri**:
|
||||
Tam GraphRAG akışını test edin (mevcut ajan akış testlerine benzer)
|
||||
Tam DocumentRAG akışını test edin
|
||||
Ağ geçidi akış yönlendirmesini test edin
|
||||
CLI akış çıktısını test edin
|
||||
|
||||
**Manuel testler**:
|
||||
`tg-invoke-graph-rag -q "What is machine learning?"` (akış varsayılan olarak etkindir)
|
||||
`tg-invoke-document-rag -q "Summarize the documents about AI"` (akış varsayılan olarak etkindir)
|
||||
`tg-invoke-graph-rag --no-streaming -q "..."` (akış dışı modu test edin)
|
||||
Akış modunda kademeli çıktının göründüğünü doğrulayın
|
||||
|
||||
## Geçiş Planı
|
||||
|
||||
Herhangi bir geçişe gerek yoktur:
|
||||
Akış, `streaming` parametresi aracılığıyla isteğe bağlıdır (varsayılan olarak False)
|
||||
Mevcut istemciler, herhangi bir değişiklik olmadan çalışmaya devam eder
|
||||
Yeni istemciler, akışı kullanabilir
|
||||
|
||||
## Zaman Çizelgesi
|
||||
|
||||
Tahmini uygulama süresi: 4-6 saat
|
||||
1. Aşama (2 saat): GraphRAG akış desteği
|
||||
2. Aşama (2 saat): DocumentRAG akış desteği
|
||||
3. Aşama (1-2 saat): Ağ geçidi güncellemeleri ve CLI bayrakları
|
||||
Test: Her aşamaya entegre edilmiştir
|
||||
|
||||
## Açık Sorular
|
||||
|
||||
NLP Sorgu hizmetine de akış desteği eklemeli miyiz?
|
||||
Ara adımları (örneğin, "Varlıkların alınması...", "Grafiğin sorgulanması...") mi yoksa sadece LLM çıktısını mı akışa vermeliyiz?
|
||||
GraphRAG/DocumentRAG yanıtları, parça meta verilerini (örneğin, parça numarası, toplam beklenen) içermeli mi?
|
||||
|
||||
## Referanslar
|
||||
|
||||
Mevcut uygulama: `docs/tech-specs/streaming-llm-responses.md`
|
||||
Ajan akışı: `trustgraph-flow/trustgraph/agent/react/agent_manager.py`
|
||||
PromptClient akışı: `trustgraph-base/trustgraph/base/prompt_client.py`
|
||||
99
docs/tech-specs/tr/schema-refactoring-proposal.tr.md
Normal file
99
docs/tech-specs/tr/schema-refactoring-proposal.tr.md
Normal file
|
|
@ -0,0 +1,99 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Şema Dizini Yeniden Düzenleme Önerisi"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Şema Dizini Yeniden Düzenleme Önerisi
|
||||
|
||||
> **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.
|
||||
|
||||
## Mevcut Sorunlar
|
||||
|
||||
1. **Düz yapı** - Tüm şemaların tek bir dizinde olması, ilişkileri anlamayı zorlaştırıyor.
|
||||
2. **Karışık konular** - Temel tipler, alan nesneleri ve API sözleşmeleri bir arada bulunuyor.
|
||||
3. **Belirsiz adlandırma** - "object.py", "types.py", "topic.py" gibi dosyalar, amaçlarını açıkça belirtmiyor.
|
||||
4. **Açık katmanlama yok** - Neyin neye bağlı olduğunu kolayca görmek mümkün değil.
|
||||
|
||||
## Önerilen Yapı
|
||||
|
||||
```
|
||||
trustgraph-base/trustgraph/schema/
|
||||
├── __init__.py
|
||||
├── core/ # Core primitive types used everywhere
|
||||
│ ├── __init__.py
|
||||
│ ├── primitives.py # Error, Value, Triple, Field, RowSchema
|
||||
│ ├── metadata.py # Metadata record
|
||||
│ └── topic.py # Topic utilities
|
||||
│
|
||||
├── knowledge/ # Knowledge domain models and extraction
|
||||
│ ├── __init__.py
|
||||
│ ├── graph.py # EntityContext, EntityEmbeddings, Triples
|
||||
│ ├── document.py # Document, TextDocument, Chunk
|
||||
│ ├── knowledge.py # Knowledge extraction types
|
||||
│ ├── embeddings.py # All embedding-related types (moved from multiple files)
|
||||
│ └── nlp.py # Definition, Topic, Relationship, Fact types
|
||||
│
|
||||
└── services/ # Service request/response contracts
|
||||
├── __init__.py
|
||||
├── llm.py # TextCompletion, Embeddings, Tool requests/responses
|
||||
├── retrieval.py # GraphRAG, DocumentRAG queries/responses
|
||||
├── query.py # GraphEmbeddingsRequest/Response, DocumentEmbeddingsRequest/Response
|
||||
├── agent.py # Agent requests/responses
|
||||
├── flow.py # Flow requests/responses
|
||||
├── prompt.py # Prompt service requests/responses
|
||||
├── config.py # Configuration service
|
||||
├── library.py # Librarian service
|
||||
└── lookup.py # Lookup service
|
||||
```
|
||||
|
||||
## Temel Değişiklikler
|
||||
|
||||
1. **Hiyerarşik organizasyon** - Temel tipler, bilgi modelleri ve hizmet sözleşmeleri arasında net bir ayrım.
|
||||
2. **Daha iyi adlandırma**:
|
||||
`types.py` → `core/primitives.py` (daha açık amaç)
|
||||
`object.py` → Gerçek içeriğe göre uygun dosyalara ayrım
|
||||
`documents.py` → `knowledge/document.py` (tekil, tutarlı)
|
||||
`models.py` → `services/llm.py` (hangi tür modeller olduğu daha açık)
|
||||
`prompt.py` → Ayrım: hizmet kısımları `services/prompt.py`'e, veri tipleri `knowledge/nlp.py`'ye
|
||||
|
||||
3. **Mantıksal gruplandırma**:
|
||||
Tüm gömme türleri `knowledge/embeddings.py` içinde toplandı.
|
||||
Tüm LLM ile ilgili hizmet sözleşmeleri `services/llm.py` içinde.
|
||||
Hizmetler dizininde istek/yanıt çiftlerinin net bir şekilde ayrılması.
|
||||
Bilgi çıkarma türleri, diğer bilgi alanı modelleriyle gruplandırıldı.
|
||||
|
||||
4. **Bağımlılık netliği**:
|
||||
Temel tiplerin hiçbir bağımlılığı yoktur.
|
||||
Bilgi modelleri yalnızca temel bağımlılıklarına sahiptir.
|
||||
Hizmet sözleşmeleri hem temel hem de bilgi modellerine bağımlı olabilir.
|
||||
|
||||
## Geçiş Faydaları
|
||||
|
||||
1. **Daha kolay gezinme** - Geliştiriciler ihtiyaç duyduklarını hızla bulabilir.
|
||||
2. **Daha iyi modülerlik** - Farklı konular arasındaki sınırlar nettir.
|
||||
3. **Daha basit içe aktarmalar** - Daha sezgisel içe aktarma yolları.
|
||||
4. **Geleceğe yönelik** - Yeni bilgi türleri veya hizmetler eklemek, karmaşayı önleyecek şekilde kolaydır.
|
||||
|
||||
## Örnek İçe Aktarma Değişiklikleri
|
||||
|
||||
```python
|
||||
# Before
|
||||
from trustgraph.schema import Error, Triple, GraphEmbeddings, TextCompletionRequest
|
||||
|
||||
# After
|
||||
from trustgraph.schema.core import Error, Triple
|
||||
from trustgraph.schema.knowledge import GraphEmbeddings
|
||||
from trustgraph.schema.services import TextCompletionRequest
|
||||
```
|
||||
|
||||
## Uygulama Notları
|
||||
|
||||
1. Kök dizindeki `__init__.py` içindeki import'ları koruyarak geriye dönük uyumluluğu sağlayın.
|
||||
2. Dosyaları kademeli olarak taşıyın ve gerektiğinde import'ları güncelleyin.
|
||||
3. Geçiş dönemi için her şeyi import eden bir `legacy.py` eklemeyi düşünün.
|
||||
4. Yeni yapıyı yansıtacak şekilde dokümantasyonu güncelleyin.
|
||||
|
||||
<function_calls>
|
||||
<invoke name="TodoWrite">
|
||||
<parameter name="todos">[{"id": "1", "content": "Mevcut şema dizin yapısını inceleyin", "status": "tamamlandı", "priority": "yüksek"}, {"id": "2", "content": "Şema dosyalarını ve amaçlarını analiz edin", "status": "tamamlandı", "priority": "yüksek"}, {"id": "3", "content": "Geliştirilmiş adlandırma ve yapı önerin", "status": "tamamlandı", "priority": "yüksek"}]
|
||||
578
docs/tech-specs/tr/streaming-llm-responses.tr.md
Normal file
578
docs/tech-specs/tr/streaming-llm-responses.tr.md
Normal file
|
|
@ -0,0 +1,578 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Akışlı LLM Yanıtları Teknik Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Akışlı LLM Yanıtları 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'ta LLM yanıtları için akış desteğinin uygulanmasını tanımlar. Akış, üretilen token'ların LLM tarafından üretildikleri anda gerçek zamanlı olarak iletilmesini sağlar, böylece tamamlanmış bir yanıtın oluşturulmasını beklemez.
|
||||
|
||||
Bu uygulama aşağıdaki kullanım senaryolarını destekler:
|
||||
|
||||
|
||||
1. **Gerçek Zamanlı Kullanıcı Arayüzleri**: Token'ları, oluşturuldukları anda kullanıcı arayüzüne aktarın ve böylece anında görsel geri bildirim sağlayın.
|
||||
|
||||
2. **İlk Token'a Ulaşma Süresinin Azaltılması**: Kullanıcılar, tam oluşturma beklemeden çıktıyı hemen görmeye başlar.
|
||||
|
||||
3. **Uzun Yanıtların İşlenmesi**: Aksi takdirde zaman aşımına uğrayabilecek veya bellek sınırlarını aşabilecek çok uzun çıktıları işleyin.
|
||||
|
||||
4. **Etkileşimli Uygulamalar**: Duyarlı sohbet ve ajan arayüzlerini etkinleştirin.
|
||||
|
||||
## Hedefler
|
||||
|
||||
|
||||
**Geriye Dönük Uyumluluk**: Mevcut, akış kullanmayan istemciler, herhangi bir değişiklik yapılmadan çalışmaya devam etmelidir.
|
||||
|
||||
**Tutarlı API Tasarımı**: Akışlı ve akışsız kullanım, minimum farklılıklarla aynı şema kalıplarını kullanır.
|
||||
|
||||
**Sağlayıcı Esnekliği**: Akış mevcut olduğunda akışı destekleyin, aksi takdirde zarif bir şekilde geri dönün.
|
||||
|
||||
**Aşamalı Dağıtım**: Riski azaltmak için kademeli uygulama.
|
||||
|
||||
**Uçtan Uca Destek**: LLM sağlayıcısından Pulsar, Gateway API ve Python API aracılığıyla istemci uygulamalarına kadar akış desteği.
|
||||
|
||||
## Arka Plan
|
||||
|
||||
### Mevcut Mimari
|
||||
|
||||
|
||||
Mevcut LLM metin tamamlama akışı aşağıdaki gibi çalışır:
|
||||
|
||||
1. İstemci, `TextCompletionRequest` ile `system` ve `prompt` alanlarını gönderir.
|
||||
2. LLM hizmeti, isteği işler ve tamamlanmış bir oluşturmayı bekler.
|
||||
3. Tamamlanmış `response` dizesiyle tek bir `TextCompletionResponse` döndürülür.
|
||||
|
||||
Mevcut şema (`trustgraph-base/trustgraph/schema/services/llm.py`):
|
||||
|
||||
```python
|
||||
class TextCompletionRequest(Record):
|
||||
system = String()
|
||||
prompt = String()
|
||||
|
||||
class TextCompletionResponse(Record):
|
||||
error = Error()
|
||||
response = String()
|
||||
in_token = Integer()
|
||||
out_token = Integer()
|
||||
model = String()
|
||||
```
|
||||
|
||||
### Mevcut Sınırlamalar
|
||||
|
||||
**Gecikme**: Kullanıcılar, herhangi bir çıktı görmeden önce, tamamlanmış bir üretimi beklemelidir.
|
||||
**Zaman Aşımı Riski**: Uzun üretmeler, istemci zaman aşımı eşiklerini aşabilir.
|
||||
**Kötü Kullanıcı Deneyimi**: Üretim sırasında geri bildirim olmaması, yavaşlık algısı yaratır.
|
||||
**Kaynak Kullanımı**: Tam yanıtlar bellekte tamponlanmalıdır.
|
||||
|
||||
Bu özellik, art arda yanıt verme özelliğini etkinleştirerek bu sınırlamalara çözüm getirir ve aynı zamanda tam geriye dönük uyumluluğu korur.
|
||||
|
||||
|
||||
## Teknik Tasarım
|
||||
|
||||
### Aşama 1: Altyapı
|
||||
|
||||
Aşama 1, şemaları, API'leri ve komut satırı araçlarını değiştirerek akış için temel altyapıyı oluşturur.
|
||||
|
||||
|
||||
#### Şema Değişiklikleri
|
||||
|
||||
##### LLM Şeması (`trustgraph-base/trustgraph/schema/services/llm.py`)
|
||||
|
||||
**İstek Değişiklikleri:**
|
||||
|
||||
```python
|
||||
class TextCompletionRequest(Record):
|
||||
system = String()
|
||||
prompt = String()
|
||||
streaming = Boolean() # NEW: Default false for backward compatibility
|
||||
```
|
||||
|
||||
`streaming`: `true` olduğunda, akışlı yanıt gönderimi talep eder.
|
||||
Varsayılan: `false` (mevcut davranış korunmuştur).
|
||||
|
||||
**Yanıt Değişiklikleri:**
|
||||
|
||||
```python
|
||||
class TextCompletionResponse(Record):
|
||||
error = Error()
|
||||
response = String()
|
||||
in_token = Integer()
|
||||
out_token = Integer()
|
||||
model = String()
|
||||
end_of_stream = Boolean() # NEW: Indicates final message
|
||||
```
|
||||
|
||||
`end_of_stream`: `true` olduğunda, bunun son (veya tek) yanıt olduğunu gösterir.
|
||||
Akış olmayan istekler için: `end_of_stream=true` ile tek bir yanıt.
|
||||
Akış istekleri için: `end_of_stream=false` ile birden fazla yanıt (son yanıt hariç).
|
||||
hariç.
|
||||
|
||||
##### İstek Şeması (`trustgraph-base/trustgraph/schema/services/prompt.py`)
|
||||
|
||||
İstek hizmeti, metin tamamlama işlemini kapsar, bu nedenle aynı kalıbı yansıtır:
|
||||
|
||||
**İstek Değişiklikleri:**
|
||||
|
||||
```python
|
||||
class PromptRequest(Record):
|
||||
id = String()
|
||||
terms = Map(String())
|
||||
streaming = Boolean() # NEW: Default false
|
||||
```
|
||||
|
||||
**Değişiklikler:**
|
||||
|
||||
```python
|
||||
class PromptResponse(Record):
|
||||
error = Error()
|
||||
text = String()
|
||||
object = String()
|
||||
end_of_stream = Boolean() # NEW: Indicates final message
|
||||
```
|
||||
|
||||
#### Ağ Geçidi API Değişiklikleri
|
||||
|
||||
Ağ Geçidi API'sinin, HTTP/WebSocket istemcilerine akış yeteneklerini sunması gerekir.
|
||||
|
||||
**REST API Güncellemeleri:**
|
||||
|
||||
`POST /api/v1/text-completion`: İstek gövdesinde `streaming` parametresini kabul et
|
||||
Yanıt davranışı, akış bayrağına bağlıdır:
|
||||
`streaming=false`: Tek JSON yanıtı (mevcut davranış)
|
||||
`streaming=true`: Sunucu Tarafından Gönderilen Olaylar (SSE) akışı veya WebSocket mesajları
|
||||
|
||||
**Yanıt Formatı (Akış):**
|
||||
|
||||
Her akış parçası, aynı şema yapısını izler:
|
||||
```json
|
||||
{
|
||||
"response": "partial text...",
|
||||
"end_of_stream": false,
|
||||
"model": "model-name"
|
||||
}
|
||||
```
|
||||
|
||||
Son bölüm:
|
||||
```json
|
||||
{
|
||||
"response": "final text chunk",
|
||||
"end_of_stream": true,
|
||||
"in_token": 150,
|
||||
"out_token": 500,
|
||||
"model": "model-name"
|
||||
}
|
||||
```
|
||||
|
||||
#### Python API Değişiklikleri
|
||||
|
||||
Python istemci API'si, geriye dönük uyumluluğu korurken hem akışlı hem de akışsız modları desteklemelidir.
|
||||
|
||||
|
||||
**LlmClient Güncellemeleri** (`trustgraph-base/trustgraph/clients/llm_client.py`):
|
||||
|
||||
```python
|
||||
class LlmClient(BaseClient):
|
||||
def request(self, system, prompt, timeout=300, streaming=False):
|
||||
"""
|
||||
Non-streaming request (backward compatible).
|
||||
Returns complete response string.
|
||||
"""
|
||||
# Existing behavior when streaming=False
|
||||
|
||||
async def request_stream(self, system, prompt, timeout=300):
|
||||
"""
|
||||
Streaming request.
|
||||
Yields response chunks as they arrive.
|
||||
"""
|
||||
# New async generator method
|
||||
```
|
||||
|
||||
**PromptClient Güncellemeleri** (`trustgraph-base/trustgraph/base/prompt_client.py`):
|
||||
|
||||
`streaming` parametresi ve asenkron üreteç varyantıyla benzer yapı.
|
||||
|
||||
#### CLI Aracı Değişiklikleri
|
||||
|
||||
**tg-invoke-llm** (`trustgraph-cli/trustgraph/cli/invoke_llm.py`):
|
||||
|
||||
```
|
||||
tg-invoke-llm [system] [prompt] [--no-streaming] [-u URL] [-f flow-id]
|
||||
```
|
||||
|
||||
Daha iyi etkileşimli kullanıcı deneyimi için, akış varsayılan olarak etkindir.
|
||||
`--no-streaming` bayrağı, akışı devre dışı bırakır.
|
||||
Akış açıkken: Token'ları geldikleri gibi standart çıktıya yazdırın.
|
||||
Akış kapalıyken: Tam yanıtı bekleyin, ardından çıktı verin.
|
||||
|
||||
**tg-invoke-prompt** (`trustgraph-cli/trustgraph/cli/invoke_prompt.py`):
|
||||
|
||||
```
|
||||
tg-invoke-prompt [template-id] [var=value...] [--no-streaming] [-u URL] [-f flow-id]
|
||||
```
|
||||
|
||||
`tg-invoke-llm` ile aynı kalıp.
|
||||
|
||||
#### LLM Hizmeti Temel Sınıfındaki Değişiklikler
|
||||
|
||||
**LlmService** (`trustgraph-base/trustgraph/base/llm_service.py`):
|
||||
|
||||
```python
|
||||
class LlmService(FlowProcessor):
|
||||
async def on_request(self, msg, consumer, flow):
|
||||
request = msg.value()
|
||||
streaming = getattr(request, 'streaming', False)
|
||||
|
||||
if streaming and self.supports_streaming():
|
||||
async for chunk in self.generate_content_stream(...):
|
||||
await self.send_response(chunk, end_of_stream=False)
|
||||
await self.send_response(final_chunk, end_of_stream=True)
|
||||
else:
|
||||
response = await self.generate_content(...)
|
||||
await self.send_response(response, end_of_stream=True)
|
||||
|
||||
def supports_streaming(self):
|
||||
"""Override in subclass to indicate streaming support."""
|
||||
return False
|
||||
|
||||
async def generate_content_stream(self, system, prompt, model, temperature):
|
||||
"""Override in subclass to implement streaming."""
|
||||
raise NotImplementedError()
|
||||
```
|
||||
|
||||
--
|
||||
|
||||
### 2. Aşama: VertexAI Prova Çalışması
|
||||
|
||||
2. Aşama, altyapıyı doğrulamak ve uçtan uca testleri sağlamak için tek bir sağlayıcıda (VertexAI) akışı uygulamaktadır.
|
||||
|
||||
|
||||
#### VertexAI Uygulaması
|
||||
|
||||
**Modül:** `trustgraph-vertexai/trustgraph/model/text_completion/vertexai/llm.py`
|
||||
|
||||
**Değişiklikler:**
|
||||
|
||||
1. `supports_streaming()`'ı `True` değerini döndürecek şekilde geçersiz kılın.
|
||||
2. `generate_content_stream()` asenkron oluşturucusunu uygulayın.
|
||||
3. Hem Gemini hem de Claude modellerini (VertexAI Anthropic API aracılığıyla) işleyin.
|
||||
|
||||
**Gemini Akışı:**
|
||||
|
||||
```python
|
||||
async def generate_content_stream(self, system, prompt, model, temperature):
|
||||
model_instance = self.get_model(model, temperature)
|
||||
response = model_instance.generate_content(
|
||||
[system, prompt],
|
||||
stream=True # Enable streaming
|
||||
)
|
||||
for chunk in response:
|
||||
yield LlmChunk(
|
||||
text=chunk.text,
|
||||
in_token=None, # Available only in final chunk
|
||||
out_token=None,
|
||||
)
|
||||
# Final chunk includes token counts from response.usage_metadata
|
||||
```
|
||||
|
||||
**Claude (VertexAI Anthropic) Akışı:**
|
||||
|
||||
```python
|
||||
async def generate_content_stream(self, system, prompt, model, temperature):
|
||||
with self.anthropic_client.messages.stream(...) as stream:
|
||||
for text in stream.text_stream:
|
||||
yield LlmChunk(text=text)
|
||||
# Token counts from stream.get_final_message()
|
||||
```
|
||||
|
||||
#### Test Etme
|
||||
|
||||
Akış yanıtı birleştirme için birim testleri
|
||||
VertexAI (Gemini ve Claude) ile entegrasyon testleri
|
||||
Uçtan uca testler: CLI -> Ağ Geçidi -> Pulsar -> VertexAI -> geri
|
||||
Geriye dönük uyumluluk testleri: Akış olmayan istekler hala çalışıyor
|
||||
|
||||
--
|
||||
|
||||
### 3. Aşama: Tüm LLM Sağlayıcıları
|
||||
|
||||
3. Aşama, akış desteğini sistemdeki tüm LLM sağlayıcılarına genişletir.
|
||||
|
||||
#### Sağlayıcı Uygulama Durumu
|
||||
|
||||
Her sağlayıcı aşağıdaki seçeneklerden birini uygulamalıdır:
|
||||
1. **Tam Akış Desteği**: `generate_content_stream()`'ı uygulayın
|
||||
2. **Uyumluluk Modu**: `end_of_stream` bayrağını doğru şekilde işleyin
|
||||
(tek bir yanıt döndürün `end_of_stream=true` ile birlikte)
|
||||
|
||||
| Sağlayıcı | Paket | Akış Desteği |
|
||||
|----------|---------|-------------------|
|
||||
| OpenAI | trustgraph-flow | Tam (yerel akış API'si) |
|
||||
| Claude/Anthropic | trustgraph-flow | Tam (yerel akış API'si) |
|
||||
| Ollama | trustgraph-flow | Tam (yerel akış API'si) |
|
||||
| Cohere | trustgraph-flow | Tam (yerel akış API'si) |
|
||||
| Mistral | trustgraph-flow | Tam (yerel akış API'si) |
|
||||
| Azure OpenAI | trustgraph-flow | Tam (yerel akış API'si) |
|
||||
| Google AI Studio | trustgraph-flow | Tam (yerel akış API'si) |
|
||||
| VertexAI | trustgraph-vertexai | Tam (2. Aşama) |
|
||||
| Bedrock | trustgraph-bedrock | Tam (yerel akış API'si) |
|
||||
| LM Studio | trustgraph-flow | Tam (OpenAI ile uyumlu) |
|
||||
| LlamaFile | trustgraph-flow | Tam (OpenAI ile uyumlu) |
|
||||
| vLLM | trustgraph-flow | Tam (OpenAI ile uyumlu) |
|
||||
| TGI | trustgraph-flow | Belirlenecek |
|
||||
| Azure | trustgraph-flow | Belirlenecek |
|
||||
|
||||
#### Uygulama Modeli
|
||||
|
||||
OpenAI ile uyumlu sağlayıcılar (OpenAI, LM Studio, LlamaFile, vLLM) için:
|
||||
|
||||
```python
|
||||
async def generate_content_stream(self, system, prompt, model, temperature):
|
||||
response = await self.client.chat.completions.create(
|
||||
model=model,
|
||||
messages=[
|
||||
{"role": "system", "content": system},
|
||||
{"role": "user", "content": prompt}
|
||||
],
|
||||
temperature=temperature,
|
||||
stream=True
|
||||
)
|
||||
async for chunk in response:
|
||||
if chunk.choices[0].delta.content:
|
||||
yield LlmChunk(text=chunk.choices[0].delta.content)
|
||||
```
|
||||
|
||||
--
|
||||
|
||||
### 4. Aşama: Ajan API'si
|
||||
|
||||
4. Aşama, akışı Ajan API'sine genişletmektedir. Bu, Ajan API'sinin doğası gereği zaten çok mesajlı olması nedeniyle daha karmaşıktır (düşünce → eylem → gözlem
|
||||
→ tekrar → son yanıt).
|
||||
|
||||
|
||||
#### Mevcut Ajan Şeması
|
||||
|
||||
```python
|
||||
class AgentStep(Record):
|
||||
thought = String()
|
||||
action = String()
|
||||
arguments = Map(String())
|
||||
observation = String()
|
||||
user = String()
|
||||
|
||||
class AgentRequest(Record):
|
||||
question = String()
|
||||
state = String()
|
||||
group = Array(String())
|
||||
history = Array(AgentStep())
|
||||
user = String()
|
||||
|
||||
class AgentResponse(Record):
|
||||
answer = String()
|
||||
error = Error()
|
||||
thought = String()
|
||||
observation = String()
|
||||
```
|
||||
|
||||
#### Önerilen Ajan Şema Değişiklikleri
|
||||
|
||||
**Değişiklik İstekleri:**
|
||||
|
||||
```python
|
||||
class AgentRequest(Record):
|
||||
question = String()
|
||||
state = String()
|
||||
group = Array(String())
|
||||
history = Array(AgentStep())
|
||||
user = String()
|
||||
streaming = Boolean() # NEW: Default false
|
||||
```
|
||||
|
||||
**Cevap Değişiklikleri:**
|
||||
|
||||
Ajan, akıl yürütme döngüsü sırasında çeşitli türde çıktılar üretir:
|
||||
Düşünceler (akıl yürütme)
|
||||
Eylemler (araç çağrıları)
|
||||
Gözlemler (araç sonuçları)
|
||||
Cevap (sonuç yanıtı)
|
||||
Hatalar
|
||||
|
||||
`chunk_type`, gönderilen içeriğin türünü tanımladığı için, ayrı
|
||||
`answer`, `error`, `thought` ve `observation` alanları tek bir alana dönüştürülebilir.
|
||||
Tek bir `content` alanı:
|
||||
|
||||
```python
|
||||
class AgentResponse(Record):
|
||||
chunk_type = String() # "thought", "action", "observation", "answer", "error"
|
||||
content = String() # The actual content (interpretation depends on chunk_type)
|
||||
end_of_message = Boolean() # Current thought/action/observation/answer is complete
|
||||
end_of_dialog = Boolean() # Entire agent dialog is complete
|
||||
```
|
||||
|
||||
**Alan Anlamı:**
|
||||
|
||||
`chunk_type`: `content` alanında bulunan içeriğin türünü belirtir.
|
||||
`"thought"`: Aracın muhakemesi/düşüncesi.
|
||||
`"action"`: Çağrılan araç/eylem.
|
||||
`"observation"`: Araç çalıştırmasından elde edilen sonuç.
|
||||
`"answer"`: Kullanıcının sorusuna verilen nihai cevap.
|
||||
`"error"`: Hata mesajı.
|
||||
|
||||
`content`: `chunk_type`'e göre yorumlanan, gerçek akış içeriği.
|
||||
|
||||
`end_of_message`: `true` olduğunda, mevcut parça türü tamamlanmıştır.
|
||||
Örnek: Mevcut düşünce için tüm belirteçler gönderilmiştir.
|
||||
İstemcilerin bir sonraki aşamaya ne zaman geçmeleri gerektiğini bilmesini sağlar.
|
||||
|
||||
`end_of_dialog`: `true` olduğunda, tüm aracı etkileşimi tamamlanmıştır.
|
||||
Bu, akıştaki son mesajdır.
|
||||
|
||||
#### Aracı Akış Davranışı
|
||||
|
||||
`streaming=true` olduğunda:
|
||||
|
||||
1. **Düşünce akışı:**
|
||||
`chunk_type="thought"` ve `end_of_message=false` ile birden fazla parça.
|
||||
Son düşünce parçası `end_of_message=true`'a sahiptir.
|
||||
2. **Eylem bildirimi:**
|
||||
`chunk_type="action"` ve `end_of_message=true` ile tek bir parça.
|
||||
3. **Gözlem:**
|
||||
`chunk_type="observation"` ile parçalar, son parça `end_of_message=true`'e sahiptir.
|
||||
4. Aracı muhakeme ederken 1-3 adımlarını tekrarlayın.
|
||||
5. **Son cevap:**
|
||||
`content` içindeki son yanıtla `chunk_type="answer"`.
|
||||
Son parça `end_of_message=true` ve `end_of_dialog=true`'e sahiptir.
|
||||
|
||||
**Örnek Akış Sırası:**
|
||||
|
||||
```
|
||||
{chunk_type: "thought", content: "I need to", end_of_message: false, end_of_dialog: false}
|
||||
{chunk_type: "thought", content: " search for...", end_of_message: true, end_of_dialog: false}
|
||||
{chunk_type: "action", content: "search", end_of_message: true, end_of_dialog: false}
|
||||
{chunk_type: "observation", content: "Found: ...", end_of_message: true, end_of_dialog: false}
|
||||
{chunk_type: "thought", content: "Based on this", end_of_message: false, end_of_dialog: false}
|
||||
{chunk_type: "thought", content: " I can answer...", end_of_message: true, end_of_dialog: false}
|
||||
{chunk_type: "answer", content: "The answer is...", end_of_message: true, end_of_dialog: true}
|
||||
```
|
||||
|
||||
`streaming=false` olduğunda:
|
||||
Mevcut davranış korunmuştur
|
||||
Tam bir cevap içeren tek bir yanıt
|
||||
`end_of_message=true`, `end_of_dialog=true`
|
||||
|
||||
#### Ağ Geçidi ve Python API'si
|
||||
|
||||
Ağ Geçidi: Ajan akışı için yeni SSE/WebSocket uç noktası
|
||||
Python API'si: Yeni `agent_stream()` asenkron oluşturucu metodu
|
||||
|
||||
--
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
**Yeni bir saldırı yüzeyi yok**: Akış, aynı kimlik doğrulama/yetkilendirme mekanizmalarını kullanır
|
||||
**Hız sınırlaması**: Gerekirse, her jeton veya her parça için hız sınırları uygulayın
|
||||
**Bağlantı yönetimi**: İstemci bağlantısının kesilmesi durumunda akışları düzgün bir şekilde sonlandırın
|
||||
**Zaman aşımı yönetimi**: Akış istekleri için uygun zaman aşımı işleme gereklidir
|
||||
|
||||
## Performans Hususları
|
||||
|
||||
**Bellek**: Akış, tepe bellek kullanımını azaltır (tam yanıt tamponlama yok)
|
||||
**Gecikme**: İlk jetona ulaşma süresi önemli ölçüde azaltılmıştır
|
||||
**Bağlantı ek yükü**: SSE/WebSocket bağlantılarının devamlılık ek yükü vardır
|
||||
**Pulsar verim**: Tek büyük mesaj yerine çok sayıda küçük mesaj
|
||||
dengesi
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
### Birim Testleri
|
||||
Yeni alanlarla şema serileştirme/deserileştirme
|
||||
Geriye dönük uyumluluk (eksik alanlar için varsayılan değerler kullanılır)
|
||||
Parça birleştirme mantığı
|
||||
|
||||
### Entegrasyon Testleri
|
||||
Her LLM sağlayıcısının akış uygulaması
|
||||
Ağ Geçidi API akış uç noktaları
|
||||
Python istemci akış metotları
|
||||
|
||||
### Uçtan Uca Testler
|
||||
CLI aracının akış çıktısı
|
||||
Tam akış: İstemci → Ağ Geçidi → Pulsar → LLM → geri
|
||||
Karışık akış/akış dışı iş yükleri
|
||||
|
||||
### Geriye Dönük Uyumluluk Testleri
|
||||
Mevcut istemciler değişiklik yapılmadan çalışır
|
||||
Akış dışı istekler aynı şekilde davranır
|
||||
|
||||
## Geçiş Planı
|
||||
|
||||
### 1. Aşama: Altyapı
|
||||
Şema değişikliklerini dağıtın (geriye dönük uyumlu)
|
||||
Ağ Geçidi API güncellemelerini dağıtın
|
||||
Python API güncellemelerini dağıtın
|
||||
CLI aracı güncellemelerini yayınlayın
|
||||
|
||||
### 2. Aşama: VertexAI
|
||||
VertexAI akış uygulamasını dağıtın
|
||||
Test iş yükleriyle doğrulayın
|
||||
|
||||
### 3. Aşama: Tüm Sağlayıcılar
|
||||
Sağlayıcı güncellemelerini aşamalı olarak yayınlayın
|
||||
Sorunlar için izleyin
|
||||
|
||||
### 4. Aşama: Ajan API'si
|
||||
Ajan şema değişikliklerini dağıtın
|
||||
Ajan akış uygulamasını dağıtın
|
||||
Belgeleri güncelleyin
|
||||
|
||||
## Zaman Çizelgesi
|
||||
|
||||
| Aşama | Açıklama | Bağımlılıklar |
|
||||
|-------|-------------|--------------|
|
||||
| 1. Aşama | Altyapı | Yok |
|
||||
| 2. Aşama | VertexAI PoC | 1. Aşama |
|
||||
| 3. Aşama | Tüm Sağlayıcılar | 2. Aşama |
|
||||
| 4. Aşama | Ajan API'si | 3. Aşama |
|
||||
|
||||
## Tasarım Kararları
|
||||
|
||||
Aşağıdaki sorular, belirtim sırasında çözülmüştür:
|
||||
|
||||
1. **Akıştaki Jeton Sayıları**: Jeton sayıları, toplamlar değil, artışlardır.
|
||||
Tüketiciler, gerekirse bunları toplayabilir. Bu, çoğu sağlayıcının kullanım
|
||||
raporlama şekliyle eşleşir ve uygulamayı basitleştirir.
|
||||
|
||||
2. **Akışlardaki Hata İşleme**: Bir hata oluşursa, `error` alanı
|
||||
doldurulur ve diğer alanlara ihtiyaç duyulmaz. Bir hata her zaman son
|
||||
iletişimdir; hata sonrasında başka mesajlara izin verilmez veya beklenmez.
|
||||
LLM/İstem akışları için `end_of_stream=true`. Ajan akışları için,
|
||||
`chunk_type="error"` ile `end_of_dialog=true`.
|
||||
|
||||
3. **Kısmi Yanıt Kurtarma**: Mesajlaşma protokolü (Pulsar) dayanıklıdır,
|
||||
bu nedenle mesaj düzeyinde yeniden deneme gerekli değildir. Bir istem, akışı
|
||||
takip edemezse veya bağlantısı kesilirse, isteği baştan yeniden denemesi gerekir.
|
||||
|
||||
4. **İstem Hizmeti Akışı**: Akış yalnızca metin (`text`) yanıtları için
|
||||
desteklenir, yapılandırılmış (`object`) yanıtlar için değil. İstem hizmeti,
|
||||
çıktının JSON mu yoksa metin tabanlı mı olacağını, istem şablonuna göre
|
||||
önceden bilir. Bir akış isteği, JSON çıktılı bir istem için yapılırsa,
|
||||
hizmet şunlardan birini yapmalıdır:
|
||||
Tam JSON'ı tek bir yanıtla `end_of_stream=true` ile döndürün veya
|
||||
Akış isteğini bir hata ile reddedin
|
||||
|
||||
## Açık Sorular
|
||||
|
||||
Şu anda yok.
|
||||
|
||||
## Referanslar
|
||||
|
||||
Mevcut LLM şeması: `trustgraph-base/trustgraph/schema/services/llm.py`
|
||||
Mevcut istem şeması: `trustgraph-base/trustgraph/schema/services/prompt.py`
|
||||
Mevcut ajan şeması: `trustgraph-base/trustgraph/schema/services/agent.py`
|
||||
LLM hizmeti tabanı: `trustgraph-base/trustgraph/base/llm_service.py`
|
||||
VertexAI sağlayıcısı: `trustgraph-vertexai/trustgraph/model/text_completion/vertexai/llm.py`
|
||||
Ağ Geçidi API'si: `trustgraph-base/trustgraph/api/`
|
||||
CLI araçları: `trustgraph-cli/trustgraph/cli/`
|
||||
621
docs/tech-specs/tr/structured-data-2.tr.md
Normal file
621
docs/tech-specs/tr/structured-data-2.tr.md
Normal file
|
|
@ -0,0 +1,621 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Yapılandırılmış Veri Teknik Özellikleri (Bölüm 2)"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Yapılandırılmış Veri Teknik Özellikleri (Bölüm 2)
|
||||
|
||||
> **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'ın yapılandırılmış veri entegrasyonunun ilk uygulamasının ilk aşamalarında tespit edilen sorunları ve eksiklikleri ele almaktadır, bu da `structured-data.md`'da açıklanmıştır.
|
||||
|
||||
## Sorun Tanımları
|
||||
|
||||
### 1. İsimlendirme Tutarsızlığı: "Nesne" vs "Satır"
|
||||
|
||||
Mevcut uygulama, "nesne" terimini tüm alanlarda kullanmaktadır (örneğin, `ExtractedObject`, nesne çıkarma, nesne gömme). Bu isimlendirme çok genel olup kafa karışıklığına neden olmaktadır:
|
||||
|
||||
"Nesne" terimi, yazılımda (Python nesneleri, JSON nesneleri vb.) aşırı kullanılan bir terimdir.
|
||||
İşlenen veri temelde tablolardır; tanımlı şemalara sahip satırlar.
|
||||
"Satır", veri modelini daha doğru bir şekilde tanımlar ve veritabanı terminolojisiyle uyumludur.
|
||||
|
||||
Bu tutarsızlık, modül adlarında, sınıf adlarında, mesaj türlerinde ve belgelerde görülmektedir.
|
||||
|
||||
### 2. Satır Depolama Sorgu Sınırlamaları
|
||||
|
||||
Mevcut satır depolama uygulamasının önemli sorgu sınırlamaları bulunmaktadır:
|
||||
|
||||
**Doğal Dil Uyumsuzluğu**: Sorgular, gerçek dünya verilerindeki değişikliklerle başa çıkmakta zorlanmaktadır. Örneğin:
|
||||
`"CHESTNUT ST"` içeren bir sokak veritabanını sorgulamak, `"Chestnut Street"` hakkında bilgi almak için zordur.
|
||||
Kısaltmalar, büyük/küçük harf farklılıkları ve biçimlendirme değişiklikleri, tam eşleşme sorgularını bozmaktadır.
|
||||
Kullanıcılar semantik bir anlayış beklemekte, ancak depolama literal eşleşme sağlamaktadır.
|
||||
|
||||
**Şema Evrimi Sorunları**: Şemaların değiştirilmesi sorunlara neden olmaktadır:
|
||||
Mevcut veriler, güncellenmiş şemalara uygun olmayabilir.
|
||||
Tablo yapısındaki değişiklikler, sorguları ve veri bütünlüğünü bozabilir.
|
||||
Şema güncellemeleri için net bir geçiş yolu bulunmamaktadır.
|
||||
|
||||
### 3. Satır Gömme Gerekliliği
|
||||
|
||||
2. soruna bağlı olarak, sistemin satır verileri için vektör gömmelere ihtiyacı vardır, bu da şunları sağlamak için gereklidir:
|
||||
|
||||
Yapılandırılmış veriler arasında semantik arama (örneğin, "Chestnut Street" verisinin "CHESTNUT ST" olarak bulunduğu durumlarda)
|
||||
Bulanık sorgular için benzerlik eşleştirme
|
||||
Yapılandırılmış filtreleri semantik benzerlikle birleştiren hibrit arama
|
||||
Daha iyi doğal dil sorgu desteği
|
||||
|
||||
Gömme hizmeti belirtilmiş, ancak uygulanmamıştır.
|
||||
|
||||
### 4. Satır Veri Alımı Eksikliği
|
||||
|
||||
Yapılandırılmış veri alım hattı henüz tam olarak çalışır durumda değildir:
|
||||
|
||||
Giriş formatlarını (CSV, JSON vb.) sınıflandırmak için tanısal istemler bulunmaktadır.
|
||||
Bu istemleri kullanan alım hizmeti, sisteme entegre edilmemiştir.
|
||||
Önceden yapılandırılmış verileri satır deposuna yüklemek için uçtan uca bir yol bulunmamaktadır.
|
||||
|
||||
## Hedefler
|
||||
|
||||
**Şema Esnekliği**: Mevcut verileri bozmadan veya geçişler gerektirmeden şema evrimini etkinleştirin.
|
||||
**Tutarlı İsimlendirme**: Kod tabanında "satır" terimini standartlaştırın.
|
||||
**Semantik Sorgulanabilirlik**: Satır gömmeleri aracılığıyla bulanık/semantik eşleştirmeyi destekleyin.
|
||||
**Tam Alım Hattı**: Yapılandırılmış verileri yüklemek için uçtan uca bir yol sağlayın.
|
||||
|
||||
## Teknik Tasarım
|
||||
|
||||
### Birleşik Satır Depolama Şeması
|
||||
|
||||
Önceki uygulamada, her şema için ayrı bir Cassandra tablosu oluşturulmuştur. Bu, şema evrimleri sırasında tablo yapısındaki değişikliklerin geçişler gerektirmesine neden olmuştur.
|
||||
|
||||
Yeni tasarım, tüm satır verileri için tek birleşik bir tablo kullanmaktadır:
|
||||
|
||||
```sql
|
||||
CREATE TABLE rows (
|
||||
collection text,
|
||||
schema_name text,
|
||||
index_name text,
|
||||
index_value frozen<list<text>>,
|
||||
data map<text, text>,
|
||||
source text,
|
||||
PRIMARY KEY ((collection, schema_name, index_name), index_value)
|
||||
)
|
||||
```
|
||||
|
||||
#### Sütun Tanımları
|
||||
|
||||
| Sütun | Tür | Açıklama |
|
||||
|--------|------|-------------|
|
||||
| `collection` | `text` | Veri toplama/içe aktarma tanımlayıcısı (metaveriden) |
|
||||
| `schema_name` | `text` | Bu satırın uyduğu şema adı |
|
||||
| `index_name` | `text` | Birleştirilmiş virgülle indekslenen alan(lar) adı |
|
||||
| `index_value` | `frozen<list<text>>` | Liste olarak indeks değerleri |
|
||||
| `data` | `map<text, text>` | Satır verisi, anahtar-değer çiftleri olarak |
|
||||
| `source` | `text` | Bilgi grafiğindeki kaynak bilgisine bağlanan isteğe bağlı URI. Boş bir dize veya NULL, kaynak olmadığını gösterir. |
|
||||
|
||||
#### İndeks Yönetimi
|
||||
|
||||
Her satır, şemada tanımlanan her indeks için bir kez olmak üzere birden çok kez saklanır. Birincil anahtar alanları, özel bir işaretçi olmadan bir indeks olarak kabul edilir ve bu, gelecekteki esnekliği sağlar.
|
||||
|
||||
**Tek alanlı indeks örneği:**
|
||||
Şema, `email`'ı indeks olarak tanımlar
|
||||
`index_name = "email"`
|
||||
`index_value = ['foo@bar.com']`
|
||||
|
||||
**Bileşik indeks örneği:**
|
||||
Şema, `region` ve `status` üzerinde bileşik bir indeks tanımlar
|
||||
`index_name = "region,status"` (alan adları sıralanır ve virgülle birleştirilir)
|
||||
`index_value = ['US', 'active']` (değerler, alan adları sırasıyla aynı sırada)
|
||||
|
||||
**Birincil anahtar örneği:**
|
||||
Şema, `customer_id`'ı birincil anahtar olarak tanımlar
|
||||
`index_name = "customer_id"`
|
||||
`index_value = ['CUST001']`
|
||||
|
||||
#### Sorgu Desenleri
|
||||
|
||||
Tüm sorgular, kullanılan indeksten bağımsız olarak aynı deseni izler:
|
||||
|
||||
```sql
|
||||
SELECT * FROM rows
|
||||
WHERE collection = 'import_2024'
|
||||
AND schema_name = 'customers'
|
||||
AND index_name = 'email'
|
||||
AND index_value = ['foo@bar.com']
|
||||
```
|
||||
|
||||
#### Tasarım Uzlaşmaları
|
||||
|
||||
**Avantajları:**
|
||||
Şema değişiklikleri, tablo yapısı değişiklikleri gerektirmez.
|
||||
Satır verileri Cassandra için şeffaftır; alan ekleme/çıkarma işlemleri şeffaftır.
|
||||
Tüm erişim yöntemleri için tutarlı sorgu kalıbı.
|
||||
Cassandra'nın ikincil indeksleri (ki bunlar ölçekte yavaş olabilir).
|
||||
Tüm yerel Cassandra türleri (`map`, `frozen<list>`).
|
||||
|
||||
**Uzlaşmalar:**
|
||||
Yazma çoğaltması: her satır eklemesi = N eklemesi (dizinlenmiş alan başına bir tane).
|
||||
Tekrarlanan satır verilerinden kaynaklanan depolama ek yükü.
|
||||
Tür bilgisi şema yapılandırmasında saklanır, dönüşüm uygulama katmanında yapılır.
|
||||
|
||||
#### Tutarlılık Modeli
|
||||
|
||||
Bu tasarım, belirli basitleştirmeleri kabul eder:
|
||||
|
||||
1. **Satır güncellemeleri yok:** Sistem yalnızca eklemelerle çalışır. Bu, aynı satırın birden çok kopyasının güncellenmesiyle ilgili tutarlılık sorunlarını ortadan kaldırır.
|
||||
|
||||
2. **Şema değişikliği toleransı:** Şemalar değiştiğinde (örneğin, indeksler eklendi/çıkarıldı), mevcut satırlar orijinal dizinlemelerini korur. Eski satırlar, gerektiğinde kullanıcılar tutarlılığı sağlamak için bir şemayı silebilir ve yeniden oluşturabilir, ancak yeni indeksler aracılığıyla bulunamaz.
|
||||
|
||||
### Bölüm Takibi ve Silme
|
||||
|
||||
#### Sorun
|
||||
|
||||
Bölüm anahtarı `(collection, schema_name, index_name)` ile, verimli silme, silinecek tüm bölüm anahtarlarını bilmeyi gerektirir. Yalnızca `collection` veya `collection + schema_name` ile silmek, veriye sahip olan tüm `index_name` değerlerini bilmeyi gerektirir.
|
||||
|
||||
#### Bölüm Takip Tablosu
|
||||
|
||||
Birincil olmayan bir arama tablosu, hangi bölümlerin mevcut olduğunu izler:
|
||||
|
||||
```sql
|
||||
CREATE TABLE row_partitions (
|
||||
collection text,
|
||||
schema_name text,
|
||||
index_name text,
|
||||
PRIMARY KEY ((collection), schema_name, index_name)
|
||||
)
|
||||
```
|
||||
|
||||
Bu, silme işlemleri için bölümlerin verimli bir şekilde bulunmasını sağlar.
|
||||
|
||||
#### Satır Yazıcı Davranışı
|
||||
|
||||
Satır yazıcı, kaydedilen `(collection, schema_name)` çiftlerinin bellek içi bir önbelleğini tutar. Bir satırı işlerken:
|
||||
|
||||
1. `(collection, schema_name)`'ın önbellekte olup olmadığını kontrol edin.
|
||||
2. Önbellekte yoksa (bu çift için ilk satır):
|
||||
Tüm indeks adlarını almak için şema yapılandırmasını arayın.
|
||||
Her `(collection, schema_name, index_name)` için `row_partitions`'a girişler ekleyin.
|
||||
Çifti önbelleğe ekleyin.
|
||||
3. Satır verilerini yazmaya devam edin.
|
||||
|
||||
Satır yazıcı ayrıca şema yapılandırma değişiklik olaylarını da izler. Bir şema değiştiğinde, ilgili önbellek girişleri temizlenir, böylece sonraki satır, güncellenmiş indeks adlarıyla yeniden kayda alınmasını sağlar.
|
||||
|
||||
Bu yaklaşım şunları sağlar:
|
||||
Arama tablosu yazmaları, satır başına değil, her `(collection, schema_name)` çifti için bir kez gerçekleşir.
|
||||
Arama tablosu, verilerin yazıldığı sırada aktif olan indeksleri yansıtır.
|
||||
İçe aktarma sırasında yapılan şema değişiklikleri doğru şekilde algılanır.
|
||||
|
||||
#### Silme İşlemleri
|
||||
|
||||
**Koleksiyonu sil:**
|
||||
```sql
|
||||
-- 1. Discover all partitions
|
||||
SELECT schema_name, index_name FROM row_partitions WHERE collection = 'X';
|
||||
|
||||
-- 2. Delete each partition from rows table
|
||||
DELETE FROM rows WHERE collection = 'X' AND schema_name = '...' AND index_name = '...';
|
||||
-- (repeat for each discovered partition)
|
||||
|
||||
-- 3. Clean up the lookup table
|
||||
DELETE FROM row_partitions WHERE collection = 'X';
|
||||
```
|
||||
|
||||
**Koleksiyonu ve şemayı sil:**
|
||||
```sql
|
||||
-- 1. Discover partitions for this schema
|
||||
SELECT index_name FROM row_partitions WHERE collection = 'X' AND schema_name = 'Y';
|
||||
|
||||
-- 2. Delete each partition from rows table
|
||||
DELETE FROM rows WHERE collection = 'X' AND schema_name = 'Y' AND index_name = '...';
|
||||
-- (repeat for each discovered partition)
|
||||
|
||||
-- 3. Clean up the lookup table entries
|
||||
DELETE FROM row_partitions WHERE collection = 'X' AND schema_name = 'Y';
|
||||
```
|
||||
|
||||
### Satır Gömme İşlemleri
|
||||
|
||||
Satır gömme işlemleri, indeksli değerlerde semantik/bulanık eşleşme sağlayarak, doğal dil uyumsuzluğu sorununu çözer (örneğin, "Chestnut Street" için arama yaparken "CHESTNUT ST" bulmak).
|
||||
|
||||
#### Tasarım Genel Bakışı
|
||||
|
||||
Her indeksli değer gömülür ve bir vektör deposunda (Qdrant) saklanır. Sorgu zamanında, sorgu gömülür, benzer vektörler bulunur ve ilişkili meta veriler, Cassandra'daki gerçek satırları bulmak için kullanılır.
|
||||
|
||||
#### Qdrant Koleksiyonu Yapısı
|
||||
|
||||
Her `(user, collection, schema_name, dimension)` tuple'ı için bir Qdrant koleksiyonu:
|
||||
|
||||
**Koleksiyon adı:** `rows_{user}_{collection}_{schema_name}_{dimension}`
|
||||
İsimler temizlenir (alfanumerik olmayan karakterler `_` ile değiştirilir, küçük harfe dönüştürülür, sayısal önekler `r_` öneki alır)
|
||||
**Gerekçe:** Bir `(user, collection, schema_name)` örneğini, eşleşen Qdrant koleksiyonlarını silerek temiz bir şekilde silmeyi sağlar; boyut soneki, farklı gömme modellerinin birlikte var olmasına olanak tanır.
|
||||
|
||||
#### Nelerin Gömüldüğü
|
||||
|
||||
İndeks değerlerinin metin gösterimi:
|
||||
|
||||
| İndeks Tipi | Örnek `index_value` | Gömülecek Metin |
|
||||
|------------|----------------------|---------------|
|
||||
| Tek Alan | `['foo@bar.com']` | `"foo@bar.com"` |
|
||||
| Birleşik | `['US', 'active']` | `"US active"` (boşluklarla birleştirilmiş) |
|
||||
|
||||
#### Nokta Yapısı
|
||||
|
||||
Her Qdrant noktası şunları içerir:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "<uuid>",
|
||||
"vector": [0.1, 0.2, ...],
|
||||
"payload": {
|
||||
"index_name": "street_name",
|
||||
"index_value": ["CHESTNUT ST"],
|
||||
"text": "CHESTNUT ST"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Yük Verisi Alanı | Açıklama |
|
||||
|---------------|-------------|
|
||||
| `index_name` | Bu gömme işleminin temsil ettiği indeksli alan(lar). |
|
||||
| `index_value` | Cassandra araması için orijinal değer listesi. |
|
||||
| `text` | Gömülen metin (hata ayıklama/görüntüleme için). |
|
||||
|
||||
Not: `user`, `collection` ve `schema_name`, Qdrant koleksiyon adı aracılığıyla örtülüdür. |
|
||||
|
||||
#### Sorgu Akışı |
|
||||
|
||||
1. Kullanıcı, kullanıcı U, koleksiyon X ve şema Y içinde "Chestnut Street" için sorgu yapar. |
|
||||
2. Sorgu metnini gömün. |
|
||||
3. Önekle eşleşen Qdrant koleksiyon adı(larını) belirleyin: `rows_U_X_Y_`. |
|
||||
4. En yakın vektörler için eşleşen Qdrant koleksiyonları içinde arama yapın. |
|
||||
5. `index_name` ve `index_value` içeren yük verilerine sahip eşleşen noktaları alın. |
|
||||
6. Cassandra'ya sorgu yapın: |
|
||||
```sql
|
||||
SELECT * FROM rows
|
||||
WHERE collection = 'X'
|
||||
AND schema_name = 'Y'
|
||||
AND index_name = '<from payload>'
|
||||
AND index_value = <from payload>
|
||||
```
|
||||
7. Eşleşen satırları döndür.
|
||||
|
||||
#### İsteğe Bağlı: İndeks Adı ile Filtreleme
|
||||
|
||||
Sorgular, Qdrant'ta yalnızca belirli alanları aramak için isteğe bağlı olarak `index_name` ile filtrelenebilir:
|
||||
|
||||
**" 'Chestnut' ile eşleşen herhangi bir alanı bul"** → koleksiyondaki tüm vektörleri arayın.
|
||||
**" 'Chestnut' ile eşleşen 'street_name' alanını bul"** → `payload.index_name = 'street_name'` alanını filtreleyin.
|
||||
|
||||
#### Mimari
|
||||
|
||||
Satır gömüleri, GraphRAG tarafından kullanılan **iki aşamalı yapılandırmaya** sahiptir (grafik-gömüleri, belge-gömüleri):
|
||||
|
||||
**1. Aşama: Gömü hesaplama** (`trustgraph-flow/trustgraph/embeddings/row_embeddings/`) - `ExtractedObject`'i tüketir, gömü hizmeti aracılığıyla gömüleri hesaplar, `RowEmbeddings` çıktısını üretir.
|
||||
**2. Aşama: Gömü depolama** (`trustgraph-flow/trustgraph/storage/row_embeddings/qdrant/`) - `RowEmbeddings`'i tüketir, vektörleri Qdrant'a yazar.
|
||||
|
||||
Cassandra satır yazarı, ayrı bir paralel tüketici işlemidir:
|
||||
|
||||
**Cassandra satır yazarı** (`trustgraph-flow/trustgraph/storage/rows/cassandra`) - `ExtractedObject`'i tüketir, satırları Cassandra'ya yazar.
|
||||
|
||||
Tüm üç hizmet de aynı akıştan tüketir, böylece bunlar birbirinden ayrılır. Bu, şunları sağlar:
|
||||
Cassandra yazma işlemlerinin, gömü oluşturma işlemlerine ve vektör depolama işlemlerine göre bağımsız olarak ölçeklenebilmesi.
|
||||
Gerekli değilse gömü hizmetleri devre dışı bırakılabilir.
|
||||
Bir hizmetteki hatalar diğerlerini etkilemez.
|
||||
GraphRAG işlem hatları ile tutarlı bir mimari.
|
||||
|
||||
#### Yazma Yolu
|
||||
|
||||
**1. Aşama (satır-gömü işlemcisi):** Bir `ExtractedObject` aldığında:
|
||||
|
||||
1. İndeksli alanları bulmak için şemayı arayın.
|
||||
2. Her indeksli alan için:
|
||||
İndeks değerinin metin gösterimini oluşturun.
|
||||
Gömü hizmeti aracılığıyla gömüyü hesaplayın.
|
||||
3. Tüm hesaplanan vektörleri içeren bir `RowEmbeddings` mesajı çıktısını verin.
|
||||
|
||||
**2. Aşama (satır-gömü-yaz-qdrant):** Bir `RowEmbeddings` aldığında:
|
||||
|
||||
1. Mesajdaki her gömü için:
|
||||
`(user, collection, schema_name, dimension)`'dan Qdrant koleksiyonunu belirleyin.
|
||||
Gerekirse koleksiyonu oluşturun (ilk yazmada tembel oluşturma).
|
||||
Vektör ve yük ile noktayı ekleyin/güncelleyin.
|
||||
|
||||
#### Mesaj Türleri
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class RowIndexEmbedding:
|
||||
index_name: str # The indexed field name(s)
|
||||
index_value: list[str] # The field value(s)
|
||||
text: str # Text that was embedded
|
||||
vectors: list[list[float]] # Computed embedding vectors
|
||||
|
||||
@dataclass
|
||||
class RowEmbeddings:
|
||||
metadata: Metadata
|
||||
schema_name: str
|
||||
embeddings: list[RowIndexEmbedding]
|
||||
```
|
||||
|
||||
#### Silme Entegrasyonu
|
||||
|
||||
Qdrant koleksiyonları, koleksiyon adı kalıbına göre önek eşleştirmesiyle bulunur:
|
||||
|
||||
**`(user, collection)`'ı Silin:**
|
||||
1. Önek `rows_{user}_{collection}_` ile eşleşen tüm Qdrant koleksiyonlarını listeleyin
|
||||
2. Her eşleşen koleksiyonu silin
|
||||
3. Cassandra satır bölümlerini silin (yukarıda belirtildiği gibi)
|
||||
4. `row_partitions` girişlerini temizleyin
|
||||
|
||||
**`(user, collection, schema_name)`'ı Silin:**
|
||||
1. Önek `rows_{user}_{collection}_{schema_name}_` ile eşleşen tüm Qdrant koleksiyonlarını listeleyin
|
||||
2. Her eşleşen koleksiyonu silin (çoklu boyutları işler)
|
||||
3. Cassandra satır bölümlerini silin
|
||||
4. `row_partitions`'ı temizleyin
|
||||
|
||||
#### Modül Konumları
|
||||
|
||||
| Aşama | Modül | Giriş Noktası |
|
||||
|-------|--------|-------------|
|
||||
| Aşama 1 | `trustgraph-flow/trustgraph/embeddings/row_embeddings/` | `row-embeddings` |
|
||||
| Aşama 2 | `trustgraph-flow/trustgraph/storage/row_embeddings/qdrant/` | `row-embeddings-write-qdrant` |
|
||||
|
||||
### Satır Gömme Sorgu API'si
|
||||
|
||||
Satır gömme sorgusu, GraphQL satır sorgu hizmetinden **ayrı bir API'dir**:
|
||||
|
||||
| API | Amaç | Arka Uç |
|
||||
|-----|---------|---------|
|
||||
| Satır Sorgusu (GraphQL) | İndekslenmiş alanlarda tam eşleşme | Cassandra |
|
||||
| Satır Gömme Sorgusu | Bulanık/anlamsal eşleşme | Qdrant |
|
||||
|
||||
Bu ayrım, işlevleri net tutar:
|
||||
GraphQL hizmeti, tam ve yapılandırılmış sorgulara odaklanır
|
||||
Gömme API'si, anlamsal benzerliği işler
|
||||
Kullanıcı iş akışı: adayları bulmak için gömmeler aracılığıyla bulanık arama, ardından tam satır verilerini almak için tam sorgu
|
||||
|
||||
#### İstek/Yanıt Şeması
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class RowEmbeddingsRequest:
|
||||
vectors: list[list[float]] # Query vectors (pre-computed embeddings)
|
||||
user: str = ""
|
||||
collection: str = ""
|
||||
schema_name: str = ""
|
||||
index_name: str = "" # Optional: filter to specific index
|
||||
limit: int = 10 # Max results per vector
|
||||
|
||||
@dataclass
|
||||
class RowIndexMatch:
|
||||
index_name: str = "" # The matched index field(s)
|
||||
index_value: list[str] = [] # The matched value(s)
|
||||
text: str = "" # Original text that was embedded
|
||||
score: float = 0.0 # Similarity score
|
||||
|
||||
@dataclass
|
||||
class RowEmbeddingsResponse:
|
||||
error: Error | None = None
|
||||
matches: list[RowIndexMatch] = []
|
||||
```
|
||||
|
||||
#### Sorgu İşleyici
|
||||
|
||||
Modül: `trustgraph-flow/trustgraph/query/row_embeddings/qdrant`
|
||||
|
||||
Giriş noktası: `row-embeddings-query-qdrant`
|
||||
|
||||
İşleyici:
|
||||
1. `RowEmbeddingsRequest` ile sorgu vektörlerini alır.
|
||||
2. Önek eşleştirmesiyle uygun Qdrant koleksiyonunu bulur.
|
||||
3. İsteğe bağlı `index_name` filtresiyle en yakın vektörleri arar.
|
||||
4. Eşleşen indeks bilgileriyle `RowEmbeddingsResponse` döndürür.
|
||||
|
||||
#### API Ağ Geçidi Entegrasyonu
|
||||
|
||||
Ağ geçidi, standart istek/yanıt kalıbı aracılığıyla satır gömme sorgularını sunar:
|
||||
|
||||
| Bileşen | Konum |
|
||||
|-----------|----------|
|
||||
| Yönlendirici | `trustgraph-flow/trustgraph/gateway/dispatch/row_embeddings_query.py` |
|
||||
| Kayıt | `"row-embeddings"`'ı `request_response_dispatchers`'e `manager.py` içinde ekleyin |
|
||||
|
||||
Akış arayüz adı: `row-embeddings`
|
||||
|
||||
Akış şablonundaki arayüz tanımı:
|
||||
```json
|
||||
{
|
||||
"interfaces": {
|
||||
"row-embeddings": {
|
||||
"request": "non-persistent://tg/request/row-embeddings:{id}",
|
||||
"response": "non-persistent://tg/response/row-embeddings:{id}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Python SDK Desteği
|
||||
|
||||
SDK, satır gömme sorguları için yöntemler sağlar:
|
||||
|
||||
```python
|
||||
# Flow-scoped query (preferred)
|
||||
api = Api(url)
|
||||
flow = api.flow().id("default")
|
||||
|
||||
# Query with text (SDK computes embeddings)
|
||||
matches = flow.row_embeddings_query(
|
||||
text="Chestnut Street",
|
||||
collection="my_collection",
|
||||
schema_name="addresses",
|
||||
index_name="street_name", # Optional filter
|
||||
limit=10
|
||||
)
|
||||
|
||||
# Query with pre-computed vectors
|
||||
matches = flow.row_embeddings_query(
|
||||
vectors=[[0.1, 0.2, ...]],
|
||||
collection="my_collection",
|
||||
schema_name="addresses"
|
||||
)
|
||||
|
||||
# Each match contains:
|
||||
for match in matches:
|
||||
print(match.index_name) # e.g., "street_name"
|
||||
print(match.index_value) # e.g., ["CHESTNUT ST"]
|
||||
print(match.text) # e.g., "CHESTNUT ST"
|
||||
print(match.score) # e.g., 0.95
|
||||
```
|
||||
|
||||
#### CLI Yardımcı Programı
|
||||
|
||||
Komut: `tg-invoke-row-embeddings`
|
||||
|
||||
```bash
|
||||
# Query by text (computes embedding automatically)
|
||||
tg-invoke-row-embeddings \
|
||||
--text "Chestnut Street" \
|
||||
--collection my_collection \
|
||||
--schema addresses \
|
||||
--index street_name \
|
||||
--limit 10
|
||||
|
||||
# Query by vector file
|
||||
tg-invoke-row-embeddings \
|
||||
--vectors vectors.json \
|
||||
--collection my_collection \
|
||||
--schema addresses
|
||||
|
||||
# Output formats
|
||||
tg-invoke-row-embeddings --text "..." --format json
|
||||
tg-invoke-row-embeddings --text "..." --format table
|
||||
```
|
||||
|
||||
#### Tipik Kullanım Şekli
|
||||
|
||||
Satır gömme sorgusu genellikle bulanık aramadan kesin aramaya geçiş akışının bir parçası olarak kullanılır:
|
||||
|
||||
```python
|
||||
# Step 1: Fuzzy search via embeddings
|
||||
matches = flow.row_embeddings_query(
|
||||
text="chestnut street",
|
||||
collection="geo",
|
||||
schema_name="streets"
|
||||
)
|
||||
|
||||
# Step 2: Exact lookup via GraphQL for full row data
|
||||
for match in matches:
|
||||
query = f'''
|
||||
query {{
|
||||
streets(where: {{ {match.index_name}: {{ eq: "{match.index_value[0]}" }} }}) {{
|
||||
street_name
|
||||
city
|
||||
zip_code
|
||||
}}
|
||||
}}
|
||||
'''
|
||||
rows = flow.rows_query(query, collection="geo")
|
||||
```
|
||||
|
||||
Bu iki aşamalı yapı şu olanakları sağlar:
|
||||
Kullanıcı "Chestnut Street" araması yaptığında "CHESTNUT ST" ifadesinin bulunması
|
||||
Tüm alanlarıyla birlikte eksiksiz satır verilerinin alınması
|
||||
Anlamsal benzerliği yapılandırılmış veri erişimiyle birleştirme
|
||||
|
||||
### Satır Veri Alımı
|
||||
|
||||
Daha sonraki bir aşamaya ertelenmiştir. Diğer veri alım değişiklikleriyle birlikte tasarlanacaktır.
|
||||
|
||||
## Uygulama Etkisi
|
||||
|
||||
### Mevcut Durum Analizi
|
||||
|
||||
Mevcut uygulama iki ana bileşenden oluşmaktadır:
|
||||
|
||||
| Bileşen | Konum | Satır Sayısı | Açıklama |
|
||||
|-----------|----------|-------|-------------|
|
||||
| Sorgu Servisi | `trustgraph-flow/trustgraph/query/objects/cassandra/service.py` | ~740 | Tek bir blok: GraphQL şema oluşturma, filtre ayrıştırma, Cassandra sorguları, istek işleme |
|
||||
| Yazıcı | `trustgraph-flow/trustgraph/storage/objects/cassandra/write.py` | ~540 | Şema başına tablo oluşturma, ikincil indeksler, ekleme/silme |
|
||||
|
||||
**Mevcut Sorgu Modeli:**
|
||||
```sql
|
||||
SELECT * FROM {keyspace}.o_{schema_name}
|
||||
WHERE collection = 'X' AND email = 'foo@bar.com'
|
||||
ALLOW FILTERING
|
||||
```
|
||||
|
||||
**Yeni Sorgu Deseni:**
|
||||
```sql
|
||||
SELECT * FROM {keyspace}.rows
|
||||
WHERE collection = 'X' AND schema_name = 'customers'
|
||||
AND index_name = 'email' AND index_value = ['foo@bar.com']
|
||||
```
|
||||
|
||||
### Önemli Değişiklikler
|
||||
|
||||
1. **Sorgu anlamları basitleştirildi**: Yeni şema, yalnızca `index_value` üzerindeki tam eşleşmeleri desteklemektedir. Mevcut GraphQL filtreleri (`gt`, `lt`, `contains`, vb.):
|
||||
Gerekliyse, döndürülen veriler üzerinde arka filtreleme olarak kullanılır.
|
||||
Bulanık eşleştirme için gömülü API'nin kullanılması lehine kaldırılır.
|
||||
|
||||
2. **GraphQL kodu sıkı bir şekilde birleştirilmiş durumda**: Mevcut `service.py`, Strawberry türü oluşturma, filtre ayrıştırma ve Cassandra'ya özgü sorguları bir araya getirmektedir. Başka bir satır depolama arka ucunun eklenmesi, yaklaşık 400 satır GraphQL kodunun çoğaltılmasına neden olacaktır.
|
||||
|
||||
### Önerilen Yeniden Düzenleme
|
||||
|
||||
Yeniden düzenleme iki bölümden oluşmaktadır:
|
||||
|
||||
#### 1. GraphQL Kodunu Ayırmak
|
||||
|
||||
Yeniden kullanılabilir GraphQL bileşenlerini, paylaşılan bir modüle çıkarın:
|
||||
|
||||
```
|
||||
trustgraph-flow/trustgraph/query/graphql/
|
||||
├── __init__.py
|
||||
├── types.py # Filter types (IntFilter, StringFilter, FloatFilter)
|
||||
├── schema.py # Dynamic schema generation from RowSchema
|
||||
└── filters.py # Filter parsing utilities
|
||||
```
|
||||
|
||||
Bu, şunları sağlar:
|
||||
Farklı satır depolama arka uçlarında yeniden kullanılabilirlik
|
||||
Daha temiz bir sorumluluk ayrımı
|
||||
GraphQL mantığının bağımsız olarak daha kolay test edilebilmesi
|
||||
|
||||
#### 2. Yeni Tablo Şemasını Uygulayın
|
||||
|
||||
Cassandra'ya özgü kodu, birleşik tabloyu kullanacak şekilde yeniden düzenleyin:
|
||||
|
||||
**Yazıcı** (`trustgraph-flow/trustgraph/storage/rows/cassandra/`):
|
||||
Her şema için ayrı tablolar yerine tek bir `rows` tablosu
|
||||
Her satır için N kopyası yazın (her indeks için bir tane)
|
||||
`row_partitions` tablosuna kaydolun
|
||||
Daha basit tablo oluşturma (tek seferlik kurulum)
|
||||
|
||||
**Sorgu Hizmeti** (`trustgraph-flow/trustgraph/query/rows/cassandra/`):
|
||||
Birleşik `rows` tablosunu sorgulayın
|
||||
Şema oluşturma için çıkarılan GraphQL modülünü kullanın
|
||||
Basitleştirilmiş filtre işleme (yalnızca veritabanı düzeyinde tam eşleşme)
|
||||
|
||||
### Modül Yeniden Adlandırmaları
|
||||
|
||||
"nesne" → "satır" adlandırma temizliği kapsamında:
|
||||
|
||||
| Mevcut | Yeni |
|
||||
|---------|-----|
|
||||
| `storage/objects/cassandra/` | `storage/rows/cassandra/` |
|
||||
| `query/objects/cassandra/` | `query/rows/cassandra/` |
|
||||
| `embeddings/object_embeddings/` | `embeddings/row_embeddings/` |
|
||||
|
||||
### Yeni Modüller
|
||||
|
||||
| Modül | Amaç |
|
||||
|--------|---------|
|
||||
| `trustgraph-flow/trustgraph/query/graphql/` | Paylaşılan GraphQL yardımcı programları |
|
||||
| `trustgraph-flow/trustgraph/query/row_embeddings/qdrant/` | Satır gömme sorgu API'si |
|
||||
| `trustgraph-flow/trustgraph/embeddings/row_embeddings/` | Satır gömme hesaplama (1. Aşama) |
|
||||
| `trustgraph-flow/trustgraph/storage/row_embeddings/qdrant/` | Satır gömme depolama (2. Aşama) |
|
||||
|
||||
## Referanslar
|
||||
|
||||
[Yapılandırılmış Veri Teknik Özellikleri](structured-data.md)
|
||||
567
docs/tech-specs/tr/structured-data-descriptor.tr.md
Normal file
567
docs/tech-specs/tr/structured-data-descriptor.tr.md
Normal file
|
|
@ -0,0 +1,567 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Yapılandırılmış Veri Tanımlayıcı Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Yapılandırılmış Veri Tanımlayıcı Ö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ış
|
||||
|
||||
Yapılandırılmış Veri Tanımlayıcı, JSON tabanlı bir yapılandırma dilidir ve TrustGraph'a yapılandırılmış verilerin nasıl ayrıştırıldığı, dönüştürüldüğü ve içe aktarıldığını tanımlar. Veri içe aktarma için deklaratif bir yaklaşım sunar, çoklu giriş formatlarını ve özel kod gerektirmeden karmaşık dönüşüm süreçlerini destekler.
|
||||
|
||||
## Temel Kavramlar
|
||||
|
||||
### 1. Format Tanımı
|
||||
Giriş dosya türünü ve ayrıştırma seçeneklerini tanımlar. Hangi ayrıştırıcının kullanılacağını ve kaynak verilerin nasıl yorumlanacağını belirler.
|
||||
|
||||
### 2. Alan Eşlemeleri
|
||||
Kaynak yollarını hedef alanlarla dönüşümlerle eşler. Verilerin kaynaklardan çıktı şema alanlarına nasıl aktığını tanımlar.
|
||||
|
||||
### 3. Dönüşüm Süreci
|
||||
Alan değerlerine uygulanabilecek veri dönüşüm zinciri. Şunları içerir:
|
||||
Veri temizleme (boşlukları kaldırma, normalleştirme)
|
||||
Biçim dönüştürme (tarih ayrıştırma, tür dönüştürme)
|
||||
Hesaplamalar (aritmetik işlemler, dize manipülasyonu)
|
||||
Arama tabloları (referans tabloları, eşleştirmeler)
|
||||
|
||||
### 4. Doğrulama Kuralları
|
||||
Veri bütünlüğünü sağlamak için uygulanan veri kalitesi kontrolleri:
|
||||
Tür doğrulama
|
||||
Aralık kontrolleri
|
||||
Desen eşleştirme (regex)
|
||||
Gerekli alan doğrulama
|
||||
Özel doğrulama mantığı
|
||||
|
||||
### 5. Genel Ayarlar
|
||||
Tüm içe aktarma sürecine uygulanan yapılandırma:
|
||||
Veri zenginleştirme için arama tabloları
|
||||
Küresel değişkenler ve sabitler
|
||||
Çıktı biçimi özellikleri
|
||||
Hata işleme politikaları
|
||||
|
||||
## Uygulama Stratejisi
|
||||
|
||||
İçe aktarıcı uygulaması aşağıdaki süreci izler:
|
||||
|
||||
1. **Yapılandırmayı Ayrıştır** - JSON tanımlayıcısını yükleyin ve doğrulayın
|
||||
2. **Ayrıştırıcıyı Başlat** - `format.type`'a göre uygun ayrıştırıcıyı yükleyin (CSV, XML, JSON, vb.)
|
||||
3. **Ön İşleme Uygula** - Küresel filtreleri ve dönüşümleri çalıştırın
|
||||
4. **Kayıtları İşle** - Her giriş kaydı için:
|
||||
Kaynak yollarını (JSONPath, XPath, sütun adları) kullanarak verileri çıkarın
|
||||
Alan düzeyindeki dönüşümleri sırayla uygulayın
|
||||
Sonuçları tanımlı kurallara göre doğrulayın
|
||||
Eksik veriler için varsayılan değerleri uygulayın
|
||||
5. **Son İşleme Uygula** - Tekilleştirme, birleştirme, vb. işlemlerini gerçekleştirin
|
||||
6. **Çıktıyı Oluştur** - Verileri belirtilen hedef biçimde oluşturun
|
||||
|
||||
## Yol İfadesi Desteği
|
||||
|
||||
Farklı giriş formatları, uygun yol ifadesi dillerini kullanır:
|
||||
|
||||
**CSV**: Sütun adları veya indeksler (`"column_name"` veya `"[2]"`)
|
||||
**JSON**: JSONPath sözdizimi (`"$.user.profile.email"`)
|
||||
**XML**: XPath ifadeleri (`"//product[@id='123']/price"`)
|
||||
**Sabit genişlik**: Alan tanımlarından alan adları
|
||||
|
||||
## Avantajlar
|
||||
|
||||
**Tek Kod Tabanı** - Tek bir içe aktarıcı, çoklu giriş formatlarını işler
|
||||
**Kullanıcı Dostu** - Teknik olmayan kullanıcılar, yapılandırmalar oluşturabilir
|
||||
**Yeniden Kullanılabilir** - Yapılandırmalar paylaşılabilir ve sürüm kontrolüne tabi tutulabilir
|
||||
**Esnek** - Özel kodlama olmadan karmaşık dönüşümler
|
||||
**Sağlam** - Yerleşik doğrulama ve kapsamlı hata işleme
|
||||
**Bakımı Kolay** - Deklaratif yaklaşım, uygulama karmaşıklığını azaltır
|
||||
|
||||
## Dil Özellikleri
|
||||
|
||||
Yapılandırılmış Veri Tanımlayıcı, aşağıdaki üst düzey yapıya sahip bir JSON yapılandırma biçimi kullanır:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"metadata": {
|
||||
"name": "Configuration Name",
|
||||
"description": "Description of what this config does",
|
||||
"author": "Author Name",
|
||||
"created": "2024-01-01T00:00:00Z"
|
||||
},
|
||||
"format": { ... },
|
||||
"globals": { ... },
|
||||
"preprocessing": [ ... ],
|
||||
"mappings": [ ... ],
|
||||
"postprocessing": [ ... ],
|
||||
"output": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
### Biçim Tanımı
|
||||
|
||||
Giriş verisi biçimini ve ayrıştırma seçeneklerini açıklar:
|
||||
|
||||
```json
|
||||
{
|
||||
"format": {
|
||||
"type": "csv|json|xml|fixed-width|excel|parquet",
|
||||
"encoding": "utf-8",
|
||||
"options": {
|
||||
// Format-specific options
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### CSV Format Seçenekleri
|
||||
```json
|
||||
{
|
||||
"format": {
|
||||
"type": "csv",
|
||||
"options": {
|
||||
"delimiter": ",",
|
||||
"quote_char": "\"",
|
||||
"escape_char": "\\",
|
||||
"skip_rows": 1,
|
||||
"has_header": true,
|
||||
"null_values": ["", "NULL", "null", "N/A"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### JSON Formatı Seçenekleri
|
||||
```json
|
||||
{
|
||||
"format": {
|
||||
"type": "json",
|
||||
"options": {
|
||||
"root_path": "$.data",
|
||||
"array_mode": "records|single",
|
||||
"flatten": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### XML Formatı Seçenekleri
|
||||
```json
|
||||
{
|
||||
"format": {
|
||||
"type": "xml",
|
||||
"options": {
|
||||
"root_element": "//records/record",
|
||||
"namespaces": {
|
||||
"ns": "http://example.com/namespace"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Küresel Ayarlar
|
||||
|
||||
Arama tablolarını, değişkenleri ve genel yapılandırmayı tanımlayın:
|
||||
|
||||
```json
|
||||
{
|
||||
"globals": {
|
||||
"variables": {
|
||||
"current_date": "2024-01-01",
|
||||
"batch_id": "BATCH_001",
|
||||
"default_confidence": 0.8
|
||||
},
|
||||
"lookup_tables": {
|
||||
"country_codes": {
|
||||
"US": "United States",
|
||||
"UK": "United Kingdom",
|
||||
"CA": "Canada"
|
||||
},
|
||||
"status_mapping": {
|
||||
"1": "active",
|
||||
"0": "inactive"
|
||||
}
|
||||
},
|
||||
"constants": {
|
||||
"source_system": "legacy_crm",
|
||||
"import_type": "full"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Alan Eşlemeleri
|
||||
|
||||
Dönüşümlerle birlikte kaynak verilerinin hedef alanlara nasıl eşlendiğini tanımlayın:
|
||||
|
||||
```json
|
||||
{
|
||||
"mappings": [
|
||||
{
|
||||
"target_field": "person_name",
|
||||
"source": "$.name",
|
||||
"transforms": [
|
||||
{"type": "trim"},
|
||||
{"type": "title_case"},
|
||||
{"type": "required"}
|
||||
],
|
||||
"validation": [
|
||||
{"type": "min_length", "value": 2},
|
||||
{"type": "max_length", "value": 100},
|
||||
{"type": "pattern", "value": "^[A-Za-z\\s]+$"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"target_field": "age",
|
||||
"source": "$.age",
|
||||
"transforms": [
|
||||
{"type": "to_int"},
|
||||
{"type": "default", "value": 0}
|
||||
],
|
||||
"validation": [
|
||||
{"type": "range", "min": 0, "max": 150}
|
||||
]
|
||||
},
|
||||
{
|
||||
"target_field": "country",
|
||||
"source": "$.country_code",
|
||||
"transforms": [
|
||||
{"type": "lookup", "table": "country_codes"},
|
||||
{"type": "default", "value": "Unknown"}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Dönüşüm Türleri
|
||||
|
||||
Kullanılabilir dönüşüm fonksiyonları:
|
||||
|
||||
#### String Dönüşümleri
|
||||
```json
|
||||
{"type": "trim"},
|
||||
{"type": "upper"},
|
||||
{"type": "lower"},
|
||||
{"type": "title_case"},
|
||||
{"type": "replace", "pattern": "old", "replacement": "new"},
|
||||
{"type": "regex_replace", "pattern": "\\d+", "replacement": "XXX"},
|
||||
{"type": "substring", "start": 0, "end": 10},
|
||||
{"type": "pad_left", "length": 10, "char": "0"}
|
||||
```
|
||||
|
||||
#### Tür Dönüşümleri
|
||||
```json
|
||||
{"type": "to_string"},
|
||||
{"type": "to_int"},
|
||||
{"type": "to_float"},
|
||||
{"type": "to_bool"},
|
||||
{"type": "to_date", "format": "YYYY-MM-DD"},
|
||||
{"type": "parse_json"}
|
||||
```
|
||||
|
||||
#### Veri İşlemleri
|
||||
```json
|
||||
{"type": "default", "value": "default_value"},
|
||||
{"type": "lookup", "table": "table_name"},
|
||||
{"type": "concat", "values": ["field1", " - ", "field2"]},
|
||||
{"type": "calculate", "expression": "${field1} + ${field2}"},
|
||||
{"type": "conditional", "condition": "${age} > 18", "true_value": "adult", "false_value": "minor"}
|
||||
```
|
||||
|
||||
### Doğrulama Kuralları
|
||||
|
||||
Yapılandırılabilir hata yönetimi ile veri kalitesi kontrolleri:
|
||||
|
||||
#### Temel Doğrulamalar
|
||||
```json
|
||||
{"type": "required"},
|
||||
{"type": "not_null"},
|
||||
{"type": "min_length", "value": 5},
|
||||
{"type": "max_length", "value": 100},
|
||||
{"type": "range", "min": 0, "max": 1000},
|
||||
{"type": "pattern", "value": "^[A-Z]{2,3}$"},
|
||||
{"type": "in_list", "values": ["active", "inactive", "pending"]}
|
||||
```
|
||||
|
||||
#### Özel Doğrulamalar
|
||||
```json
|
||||
{
|
||||
"type": "custom",
|
||||
"expression": "${age} >= 18 && ${country} == 'US'",
|
||||
"message": "Must be 18+ and in US"
|
||||
},
|
||||
{
|
||||
"type": "cross_field",
|
||||
"fields": ["start_date", "end_date"],
|
||||
"expression": "${start_date} < ${end_date}",
|
||||
"message": "Start date must be before end date"
|
||||
}
|
||||
```
|
||||
|
||||
### Ön İşleme ve Son İşleme
|
||||
|
||||
Alan eşlemesi öncesinde/sonrasında uygulanan genel işlemler:
|
||||
|
||||
```json
|
||||
{
|
||||
"preprocessing": [
|
||||
{
|
||||
"type": "filter",
|
||||
"condition": "${status} != 'deleted'"
|
||||
},
|
||||
{
|
||||
"type": "sort",
|
||||
"field": "created_date",
|
||||
"order": "asc"
|
||||
}
|
||||
],
|
||||
"postprocessing": [
|
||||
{
|
||||
"type": "deduplicate",
|
||||
"key_fields": ["email", "phone"]
|
||||
},
|
||||
{
|
||||
"type": "aggregate",
|
||||
"group_by": ["country"],
|
||||
"functions": {
|
||||
"total_count": {"type": "count"},
|
||||
"avg_age": {"type": "avg", "field": "age"}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Çıktı Yapılandırması
|
||||
|
||||
İşlenmiş verilerin nasıl çıktı olarak verilmesi gerektiğini tanımlayın:
|
||||
|
||||
```json
|
||||
{
|
||||
"output": {
|
||||
"format": "trustgraph-objects",
|
||||
"schema_name": "person",
|
||||
"options": {
|
||||
"batch_size": 1000,
|
||||
"confidence": 0.9,
|
||||
"source_span_field": "raw_text",
|
||||
"metadata": {
|
||||
"source": "crm_import",
|
||||
"version": "1.0"
|
||||
}
|
||||
},
|
||||
"error_handling": {
|
||||
"on_validation_error": "skip|fail|log",
|
||||
"on_transform_error": "skip|fail|default",
|
||||
"max_errors": 100,
|
||||
"error_output": "errors.json"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Tam Bir Örnek
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"metadata": {
|
||||
"name": "Customer Import from CRM CSV",
|
||||
"description": "Imports customer data from legacy CRM system",
|
||||
"author": "Data Team",
|
||||
"created": "2024-01-01T00:00:00Z"
|
||||
},
|
||||
"format": {
|
||||
"type": "csv",
|
||||
"encoding": "utf-8",
|
||||
"options": {
|
||||
"delimiter": ",",
|
||||
"has_header": true,
|
||||
"skip_rows": 1
|
||||
}
|
||||
},
|
||||
"globals": {
|
||||
"variables": {
|
||||
"import_date": "2024-01-01",
|
||||
"default_confidence": 0.85
|
||||
},
|
||||
"lookup_tables": {
|
||||
"country_codes": {
|
||||
"US": "United States",
|
||||
"CA": "Canada",
|
||||
"UK": "United Kingdom"
|
||||
}
|
||||
}
|
||||
},
|
||||
"preprocessing": [
|
||||
{
|
||||
"type": "filter",
|
||||
"condition": "${status} == 'active'"
|
||||
}
|
||||
],
|
||||
"mappings": [
|
||||
{
|
||||
"target_field": "full_name",
|
||||
"source": "customer_name",
|
||||
"transforms": [
|
||||
{"type": "trim"},
|
||||
{"type": "title_case"}
|
||||
],
|
||||
"validation": [
|
||||
{"type": "required"},
|
||||
{"type": "min_length", "value": 2}
|
||||
]
|
||||
},
|
||||
{
|
||||
"target_field": "email",
|
||||
"source": "email_address",
|
||||
"transforms": [
|
||||
{"type": "trim"},
|
||||
{"type": "lower"}
|
||||
],
|
||||
"validation": [
|
||||
{"type": "pattern", "value": "^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}$"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"target_field": "age",
|
||||
"source": "age",
|
||||
"transforms": [
|
||||
{"type": "to_int"},
|
||||
{"type": "default", "value": 0}
|
||||
],
|
||||
"validation": [
|
||||
{"type": "range", "min": 0, "max": 120}
|
||||
]
|
||||
},
|
||||
{
|
||||
"target_field": "country",
|
||||
"source": "country_code",
|
||||
"transforms": [
|
||||
{"type": "lookup", "table": "country_codes"},
|
||||
{"type": "default", "value": "Unknown"}
|
||||
]
|
||||
}
|
||||
],
|
||||
"output": {
|
||||
"format": "trustgraph-objects",
|
||||
"schema_name": "customer",
|
||||
"options": {
|
||||
"confidence": "${default_confidence}",
|
||||
"batch_size": 500
|
||||
},
|
||||
"error_handling": {
|
||||
"on_validation_error": "log",
|
||||
"max_errors": 50
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Açıklayıcı Oluşturma İçin LLM İstem
|
||||
|
||||
Aşağıdaki istem, bir LLM'nin örnek verileri analiz etmesi ve bir açıklayıcı yapılandırma oluşturması için kullanılabilir:
|
||||
|
||||
```
|
||||
I need you to analyze the provided data sample and create a Structured Data Descriptor configuration in JSON format.
|
||||
|
||||
The descriptor should follow this specification:
|
||||
- version: "1.0"
|
||||
- metadata: Configuration name, description, author, and creation date
|
||||
- format: Input format type and parsing options
|
||||
- globals: Variables, lookup tables, and constants
|
||||
- preprocessing: Filters and transformations applied before mapping
|
||||
- mappings: Field-by-field mapping from source to target with transformations and validations
|
||||
- postprocessing: Operations like deduplication or aggregation
|
||||
- output: Target format and error handling configuration
|
||||
|
||||
ANALYZE THE DATA:
|
||||
1. Identify the format (CSV, JSON, XML, etc.)
|
||||
2. Detect delimiters, encodings, and structure
|
||||
3. Find data types for each field
|
||||
4. Identify patterns and constraints
|
||||
5. Look for fields that need cleaning or transformation
|
||||
6. Find relationships between fields
|
||||
7. Identify lookup opportunities (codes that map to values)
|
||||
8. Detect required vs optional fields
|
||||
|
||||
CREATE THE DESCRIPTOR:
|
||||
For each field in the sample data:
|
||||
- Map it to an appropriate target field name
|
||||
- Add necessary transformations (trim, case conversion, type casting)
|
||||
- Include appropriate validations (required, patterns, ranges)
|
||||
- Set defaults for missing values
|
||||
|
||||
Include preprocessing if needed:
|
||||
- Filters to exclude invalid records
|
||||
- Sorting requirements
|
||||
|
||||
Include postprocessing if beneficial:
|
||||
- Deduplication on key fields
|
||||
- Aggregation for summary data
|
||||
|
||||
Configure output for TrustGraph:
|
||||
- format: "trustgraph-objects"
|
||||
- schema_name: Based on the data entity type
|
||||
- Appropriate error handling
|
||||
|
||||
DATA SAMPLE:
|
||||
[Insert data sample here]
|
||||
|
||||
ADDITIONAL CONTEXT (optional):
|
||||
- Target schema name: [if known]
|
||||
- Business rules: [any specific requirements]
|
||||
- Data quality issues to address: [known problems]
|
||||
|
||||
Generate a complete, valid Structured Data Descriptor configuration that will properly import this data into TrustGraph. Include comments explaining key decisions.
|
||||
```
|
||||
|
||||
### Örnek Kullanım İsteği
|
||||
|
||||
```
|
||||
I need you to analyze the provided data sample and create a Structured Data Descriptor configuration in JSON format.
|
||||
|
||||
[Standard instructions from above...]
|
||||
|
||||
DATA SAMPLE:
|
||||
```csv
|
||||
MüşteriID,Ad,E-posta,Yaş,Ülke,Durum,KayıtTarihi,ToplamSatınAlımlar
|
||||
1001,"Smith, John",john.smith@email.com,35,US,1,2023-01-15,5420.50
|
||||
1002,"doe, jane",JANE.DOE@GMAIL.COM,28,CA,1,2023-03-22,3200.00
|
||||
1003,"Bob Johnson",bob@,62,UK,0,2022-11-01,0
|
||||
1004,"Alice Chen","alice.chen@company.org",41,US,1,2023-06-10,8900.25
|
||||
1005,,invalid-email,25,XX,1,2024-01-01,100
|
||||
```
|
||||
|
||||
ADDITIONAL CONTEXT:
|
||||
- Target schema name: customer
|
||||
- Business rules: Email should be valid and lowercase, names should be title case
|
||||
- Data quality issues: Some emails are invalid, some names are missing, country codes need mapping
|
||||
```
|
||||
|
||||
### Mevcut Verileri Örnek Olmadan Analiz Etme İsteği
|
||||
|
||||
```
|
||||
I need you to help me create a Structured Data Descriptor configuration for importing [data type] data.
|
||||
|
||||
The source data has these characteristics:
|
||||
- Format: [CSV/JSON/XML/etc]
|
||||
- Fields: [list the fields]
|
||||
- Data quality issues: [describe any known issues]
|
||||
- Volume: [approximate number of records]
|
||||
|
||||
Requirements:
|
||||
- [List any specific transformation needs]
|
||||
- [List any validation requirements]
|
||||
- [List any business rules]
|
||||
|
||||
Please generate a Structured Data Descriptor configuration that will:
|
||||
1. Parse the input format correctly
|
||||
2. Clean and standardize the data
|
||||
3. Validate according to the requirements
|
||||
4. Handle errors gracefully
|
||||
5. Output in TrustGraph ExtractedObject format
|
||||
|
||||
Focus on making the configuration robust and reusable.
|
||||
```
|
||||
147
docs/tech-specs/tr/structured-data-schemas.tr.md
Normal file
147
docs/tech-specs/tr/structured-data-schemas.tr.md
Normal file
|
|
@ -0,0 +1,147 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Yapılandırılmış Veri Pulsar Şema Değişiklikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Yapılandırılmış Veri Pulsar Şema Değişiklikleri
|
||||
|
||||
> **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ış
|
||||
|
||||
STRUCTURED_DATA.md spesifikasyonuna dayanarak, bu belge, TrustGraph'ta yapılandırılmış veri yeteneklerini desteklemek için gerekli olan Pulsar şema eklemelerini ve değişikliklerini önermektedir.
|
||||
|
||||
## Gerekli Şema Değişiklikleri
|
||||
|
||||
### 1. Temel Şema Geliştirmeleri
|
||||
|
||||
#### Gelişmiş Alan Tanımı
|
||||
`core/primitives.py` içindeki mevcut `Field` sınıfı, ek özelliklere ihtiyaç duymaktadır:
|
||||
|
||||
```python
|
||||
class Field(Record):
|
||||
name = String()
|
||||
type = String() # int, string, long, bool, float, double, timestamp
|
||||
size = Integer()
|
||||
primary = Boolean()
|
||||
description = String()
|
||||
# NEW FIELDS:
|
||||
required = Boolean() # Whether field is required
|
||||
enum_values = Array(String()) # For enum type fields
|
||||
indexed = Boolean() # Whether field should be indexed
|
||||
```
|
||||
|
||||
### 2. Yeni Bilgi Şemaları
|
||||
|
||||
#### 2.1 Yapılandırılmış Veri Gönderimi
|
||||
Yeni dosya: `knowledge/structured.py`
|
||||
|
||||
```python
|
||||
from pulsar.schema import Record, String, Bytes, Map
|
||||
from ..core.metadata import Metadata
|
||||
|
||||
class StructuredDataSubmission(Record):
|
||||
metadata = Metadata()
|
||||
format = String() # "json", "csv", "xml"
|
||||
schema_name = String() # Reference to schema in config
|
||||
data = Bytes() # Raw data to ingest
|
||||
options = Map(String()) # Format-specific options
|
||||
```
|
||||
|
||||
### 3. Yeni Hizmet Şemaları
|
||||
|
||||
#### 3.1 Doğal Dil İşleme'den Yapılandırılmış Sorgu Hizmeti
|
||||
Yeni dosya: `services/nlp_query.py`
|
||||
|
||||
```python
|
||||
from pulsar.schema import Record, String, Array, Map, Integer, Double
|
||||
from ..core.primitives import Error
|
||||
|
||||
class NLPToStructuredQueryRequest(Record):
|
||||
natural_language_query = String()
|
||||
max_results = Integer()
|
||||
context_hints = Map(String()) # Optional context for query generation
|
||||
|
||||
class NLPToStructuredQueryResponse(Record):
|
||||
error = Error()
|
||||
graphql_query = String() # Generated GraphQL query
|
||||
variables = Map(String()) # GraphQL variables if any
|
||||
detected_schemas = Array(String()) # Which schemas the query targets
|
||||
confidence = Double()
|
||||
```
|
||||
|
||||
#### 3.2 Yapılandırılmış Sorgu Hizmeti
|
||||
Yeni dosya: `services/structured_query.py`
|
||||
|
||||
```python
|
||||
from pulsar.schema import Record, String, Map, Array
|
||||
from ..core.primitives import Error
|
||||
|
||||
class StructuredQueryRequest(Record):
|
||||
query = String() # GraphQL query
|
||||
variables = Map(String()) # GraphQL variables
|
||||
operation_name = String() # Optional operation name for multi-operation documents
|
||||
|
||||
class StructuredQueryResponse(Record):
|
||||
error = Error()
|
||||
data = String() # JSON-encoded GraphQL response data
|
||||
errors = Array(String()) # GraphQL errors if any
|
||||
```
|
||||
|
||||
#### 2.2 Nesne Çıkarımı Çıktısı
|
||||
Yeni dosya: `knowledge/object.py`
|
||||
|
||||
```python
|
||||
from pulsar.schema import Record, String, Map, Double
|
||||
from ..core.metadata import Metadata
|
||||
|
||||
class ExtractedObject(Record):
|
||||
metadata = Metadata()
|
||||
schema_name = String() # Which schema this object belongs to
|
||||
values = Map(String()) # Field name -> value
|
||||
confidence = Double()
|
||||
source_span = String() # Text span where object was found
|
||||
```
|
||||
|
||||
### 4. Gelişmiş Bilgi Şemaları
|
||||
|
||||
#### 4.1 Nesne Gömme İyileştirmeleri
|
||||
`knowledge/embeddings.py`'ı, yapılandırılmış nesne gömmelerini daha iyi destekleyecek şekilde güncelleyin:
|
||||
|
||||
```python
|
||||
class StructuredObjectEmbedding(Record):
|
||||
metadata = Metadata()
|
||||
vectors = Array(Array(Double()))
|
||||
schema_name = String()
|
||||
object_id = String() # Primary key value
|
||||
field_embeddings = Map(Array(Double())) # Per-field embeddings
|
||||
```
|
||||
|
||||
## Entegrasyon Noktaları
|
||||
|
||||
### Akış Entegrasyonu
|
||||
|
||||
Bu şemalar, yeni akış modülleri tarafından kullanılacaktır:
|
||||
`trustgraph-flow/trustgraph/decoding/structured` - StructuredDataSubmission'ı kullanır
|
||||
`trustgraph-flow/trustgraph/query/nlp_query/cassandra` - NLP sorgu şemalarını kullanır
|
||||
`trustgraph-flow/trustgraph/query/objects/cassandra` - Yapılandırılmış sorgu şemalarını kullanır
|
||||
`trustgraph-flow/trustgraph/extract/object/row/` - Chunk'ı tüketir, ExtractedObject üretir
|
||||
`trustgraph-flow/trustgraph/storage/objects/cassandra` - Rows şemasını kullanır
|
||||
`trustgraph-flow/trustgraph/embeddings/object_embeddings/qdrant` - Nesne gömme şemalarını kullanır
|
||||
|
||||
## Uygulama Notları
|
||||
|
||||
1. **Şema Sürümleme**: Gelecekteki geçiş desteği için RowSchema'ya bir `version` alanı eklemeyi düşünün.
|
||||
2. **Tip Sistemi**: `Field.type`, tüm Cassandra yerel türlerini desteklemelidir.
|
||||
3. **Toplu İşlemler**: Çoğu hizmet, hem tekil hem de toplu işlemleri desteklemelidir.
|
||||
4. **Hata Yönetimi**: Tüm yeni hizmetlerde tutarlı hata raporlama.
|
||||
5. **Geriye Uyumluluk**: Mevcut şemalar, küçük alan geliştirmeleri dışında değişmeden kalacaktır.
|
||||
|
||||
## Sonraki Adımlar
|
||||
|
||||
1. Şema dosyalarını yeni yapıya göre uygulayın.
|
||||
2. Mevcut hizmetleri, yeni şema türlerini tanıyacak şekilde güncelleyin.
|
||||
3. Bu şemaları kullanan akış modüllerini uygulayın.
|
||||
4. Yeni hizmetler için ağ geçidi/geri ağ geçidi uç noktaları ekleyin.
|
||||
5. Şema doğrulaması için birim testleri oluşturun.
|
||||
260
docs/tech-specs/tr/structured-data.tr.md
Normal file
260
docs/tech-specs/tr/structured-data.tr.md
Normal file
|
|
@ -0,0 +1,260 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Yapılandırılmış Veri Teknik Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Yapılandırılmış Veri 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'ın yapılandırılmış veri akışlarıyla entegrasyonunu tanımlar ve sistemin, satırlar halinde tablolarda veya nesne depolarında temsil edilebilen verilerle çalışmasını sağlar. Bu entegrasyon, dört birincil kullanım senaryosunu destekler:
|
||||
|
||||
1. **Yapısızdan Yapılandırılmışa Çıkarma**: Yapısız veri kaynaklarını okuyun, nesne yapılarını belirleyin ve çıkarın ve bunları tablo formatında saklayın.
|
||||
2. **Yapılandırılmış Veri Alma**: Zaten yapılandırılmış formatlarda olan verileri, çıkarılan verilerle birlikte yapılandırılmış depoya doğrudan yükleyin.
|
||||
3. **Doğal Dil Sorgulama**: Doğal dil sorularını, depodan eşleşen verileri çıkarmak için yapılandırılmış sorgulara dönüştürün.
|
||||
4. **Doğrudan Yapılandırılmış Sorgulama**: Hassas veri alımı için yapılandırılmış sorguları doğrudan veri deposuna çalıştırın.
|
||||
|
||||
## Hedefler
|
||||
|
||||
**Birleşik Veri Erişimi**: TrustGraph içinde hem yapılandırılmış hem de yapılandırılmamış verilere erişmek için tek bir arayüz sağlayın.
|
||||
**Sorunsuz Entegrasyon**: TrustGraph'ın grafik tabanlı bilgi gösterimi ile geleneksel yapılandırılmış veri formatları arasındaki sorunsuz uyumluluğu sağlayın.
|
||||
**Esnek Çıkarma**: Çeşitli yapılandırılmamış kaynaklardan (belgeler, metin vb.) yapılandırılmış verilerin otomatik olarak çıkarılmasını destekleyin.
|
||||
**Sorgu Çeşitliliği**: Kullanıcıların verilere hem doğal dil hem de yapılandırılmış sorgu dilleriyle sorgu yapmasına izin verin.
|
||||
**Veri Tutarlılığı**: Farklı veri gösterimleri arasında veri bütünlüğünü ve tutarlılığını koruyun.
|
||||
**Performans Optimizasyonu**: Ölçekte yapılandırılmış verilerin verimli bir şekilde depolanmasını ve alınmasını sağlayın.
|
||||
**Şema Esnekliği**: Çeşitli veri kaynaklarına uyum sağlamak için hem şema-yazma hem de şema-okuma yaklaşımlarını destekleyin.
|
||||
**Geriye Dönük Uyumluluk**: Yapılandırılmış veri yetenekleri eklerken mevcut TrustGraph işlevselliğini koruyun.
|
||||
|
||||
## Arka Plan
|
||||
|
||||
TrustGraph şu anda yapılandırılmamış verileri işleme ve çeşitli kaynaklardan bilgi grafikleri oluşturma konusunda mükemmeldir. Ancak, birçok kurumsal kullanım senaryosu, müşteri kayıtları, işlem günlükleri, envanter veritabanları ve diğer tablo veri kümeleri gibi doğası gereği yapılandırılmış verileri içerir. Bu yapılandırılmış veri kümeleri genellikle kapsamlı bilgiler sağlamak için yapılandırılmamış içerikle birlikte analiz edilmelidir.
|
||||
|
||||
Mevcut sınırlamalar şunlardır:
|
||||
Önceden yapılandırılmış veri formatlarını (CSV, JSON dizileri, veritabanı dışa aktarmaları) alma konusunda yerel destek yoktur.
|
||||
Belgelerden tablo verilerini çıkarırken, yerleşik yapıyı koruyamama.
|
||||
Yapılandırılmış veri kalıpları için verimli sorgulama mekanizmalarının olmaması.
|
||||
SQL benzeri sorgular ile TrustGraph'ın grafik sorguları arasındaki köprünün olmaması.
|
||||
|
||||
Bu özellik, TrustGraph'ın mevcut yeteneklerini tamamlayan bir yapılandırılmış veri katmanı tanıtarak bu boşlukları giderir. Yapılandırılmış verilere yerel olarak destek sağlayarak, TrustGraph şunları yapabilir:
|
||||
Hem yapılandırılmış hem de yapılandırılmamış veri analizleri için birleşik bir platform görevi görmek.
|
||||
Hem grafik ilişkilerini hem de tablo verilerini kapsayan hibrit sorguları etkinleştirmek.
|
||||
Yapılandırılmış verilerle çalışmaya alışkın kullanıcılar için tanıdık arayüzler sağlamak.
|
||||
Veri entegrasyonu ve iş zekası alanlarında yeni kullanım senaryolarını açmak.
|
||||
|
||||
## Teknik Tasarım
|
||||
|
||||
### Mimari
|
||||
|
||||
Yapılandırılmış veri entegrasyonu, aşağıdaki teknik bileşenleri gerektirir:
|
||||
|
||||
1. **NLP'den Yapılandırılmış Sorgu Hizmetine**
|
||||
Doğal dil sorularını yapılandırılmış sorgulara dönüştürür.
|
||||
Birden çok sorgu dili hedefi (başlangıçta SQL benzeri sözdizimi) destekler.
|
||||
Mevcut TrustGraph NLP yetenekleriyle entegre olur.
|
||||
|
||||
Modül: trustgraph-flow/trustgraph/query/nlp_query/cassandra
|
||||
|
||||
2. **Yapılandırma Şema Desteği** ✅ **[TAMAMLANDI]**
|
||||
Yapılandırılmış veri şemalarını depolamak için genişletilmiş yapılandırma sistemi.
|
||||
Tablo yapılarını, alan türlerini ve ilişkileri tanımlama desteği.
|
||||
Şema sürümleme ve geçiş yetenekleri.
|
||||
|
||||
3. **Nesne Çıkarma Modülü** ✅ **[TAMAMLANDI]**
|
||||
Gelişmiş bilgi çıkarıcı akışı entegrasyonu.
|
||||
Yapısız kaynaklardan yapılandırılmış nesneleri tanımlar ve çıkarır.
|
||||
Kaynak ve güven puanlarını korur.
|
||||
Yapılandırma verilerini almak ve şema bilgilerini çözmek için bir yapılandırma işleyici (örneğin: trustgraph-flow/trustgraph/prompt/template/service.py) kaydeder.
|
||||
Nesneleri alır ve bunları Pulsar kuyruğuna teslim etmek üzere ExtractedObject nesnelerine dönüştürür.
|
||||
NOT: `trustgraph-flow/trustgraph/extract/object/row/` adresinde mevcut kod bulunmaktadır. Bu, önceki bir girişimdir ve mevcut API'lere uymadığından büyük ölçüde yeniden düzenlenmesi gerekecektir. Kullanışlıysa kullanın, değilse sıfırdan başlayın.
|
||||
Bir komut satırı arayüzü gerektirir: `kg-extract-objects`
|
||||
|
||||
Modül: trustgraph-flow/trustgraph/extract/kg/objects/
|
||||
|
||||
4. **Yapılandırılmış Depo Yazma Modülü** ✅ **[TAMAMLANDI]**
|
||||
ExtractedObject formatında nesneleri Pulsar kuyruklarından alır.
|
||||
İlk uygulama, yapılandırılmış veri deposu olarak Apache Cassandra'yı hedef alır.
|
||||
Karşılaşılan şemalara göre dinamik olarak tablo oluşturmayı yönetir.
|
||||
Şema-Cassandra tablo eşlemesini ve veri dönüşümünü yönetir.
|
||||
Performans optimizasyonu için toplu ve akışlı yazma işlemleri sağlar.
|
||||
Pulsar çıktıları yok - bu, veri akışında bir terminal hizmetidir.
|
||||
|
||||
**Şema İşleme**:
|
||||
Yeni bir şema ilk kez karşılaşıldığında, otomatik olarak ilgili Cassandra tablosunu oluşturur.
|
||||
Tekrarlayan tablo oluşturma girişimlerinden kaçınmak için bilinen şemaların bir önbelleğini korur.
|
||||
Şema tanımlarını doğrudan alıp almamak veya ExtractedObject mesajlarındaki şema adlarına güvenip güvenmemek konusunda dikkat edilmesi gereken bir durum.
|
||||
|
||||
|
||||
**Cassandra Tablo Eşlemesi**:
|
||||
Anahtar alanı, ExtractedObject'in Meta Verilerinden gelen `user` alanından alınır.
|
||||
Tablo, ExtractedObject'in `schema_name` alanından alınır.
|
||||
Meta Verilerden gelen Koleksiyon, Cassandra düğümleri arasında doğal veri dağılımını sağlamak için bölüm anahtarının bir parçası haline gelir:
|
||||
Cassandra düğümleri arasında verilerin doğal bir şekilde dağıtılmasını sağlar.
|
||||
Belirli bir koleksiyon içindeki sorguların verimli bir şekilde çalışmasını sağlar.
|
||||
Farklı veri aktarımları/kaynakları arasında mantıksal bir izolasyon sağlar.
|
||||
Birincil anahtar yapısı: `PRIMARY KEY ((collection, <schema_primary_key_fields>), <clustering_keys>)`
|
||||
Koleksiyon, her zaman bölüm anahtarının ilk bileşenidir.
|
||||
Şema tanımlı birincil anahtar alanları, birleşik bölüm anahtarının bir parçası olarak gelir.
|
||||
Bu, sorguların koleksiyonu belirtmesini gerektirir ve öngörülebilir bir performans sağlar.
|
||||
Alan tanımları, Cassandra sütunlarına tür dönüşümleriyle eşlenir:
|
||||
`string` → `text`
|
||||
`integer` → `int` veya `bigint` (boyut ipucuna bağlı olarak)
|
||||
`float` → `float` veya `double` (doğruluk gereksinimlerine bağlı olarak)
|
||||
`boolean` → `boolean`
|
||||
`timestamp` → `timestamp`
|
||||
`enum` → `text` (uygulama seviyesinde doğrulama ile)
|
||||
İndeksli alanlar, Cassandra ikincil indekslerini oluşturur (birincil anahtarda zaten bulunan alanlar hariç).
|
||||
Gerekli alanlar, uygulama seviyesinde zorunlu kılınır (Cassandra NOT NULL'ı desteklemez).
|
||||
|
||||
**Nesne Depolama**:
|
||||
ExtractedObject.values haritasından değerleri çıkarır.
|
||||
Eklemeden önce tür dönüşümü ve doğrulama yapar.
|
||||
Eksik isteğe bağlı alanları zarif bir şekilde işler.
|
||||
Nesne kökeni hakkında meta verileri korur (kaynak belge, güvenilirlik puanları).
|
||||
Mesaj tekrar senaryolarını işlemek için idempotent yazma işlemlerini destekler.
|
||||
|
||||
**Uygulama Notları**:
|
||||
`trustgraph-flow/trustgraph/storage/objects/cassandra/` adresindeki mevcut kod güncel değildir ve mevcut API'lere uygun değildir.
|
||||
Çalışan bir depolama işlemcisinin örneği olarak `trustgraph-flow/trustgraph/storage/triples/cassandra`'a başvurulmalıdır.
|
||||
Yeniden düzenleme veya yeniden yazma kararı vermeden önce, yeniden kullanılabilir bileşenler için mevcut kodun değerlendirilmesi gerekir.
|
||||
|
||||
Modül: trustgraph-flow/trustgraph/storage/objects/cassandra
|
||||
|
||||
5. **Yapılandırılmış Sorgu Hizmeti** ✅ **[TAMAMLANDI]**
|
||||
Tanımlanmış formatlarda yapılandırılmış sorguları kabul eder.
|
||||
Yapılandırılmış depoya karşı sorguları yürütür.
|
||||
Sorgu kriterlerine uyan nesneleri döndürür.
|
||||
Sayfalama ve sonuç filtrelemeyi destekler.
|
||||
|
||||
Modül: trustgraph-flow/trustgraph/query/objects/cassandra
|
||||
|
||||
6. **Ajan Aracı Entegrasyonu**
|
||||
Ajan çerçeveleri için yeni bir araç sınıfı.
|
||||
Ajanların yapılandırılmış veri depolarını sorgulamasına olanak tanır.
|
||||
Doğal dil ve yapılandırılmış sorgu arayüzleri sağlar.
|
||||
Mevcut ajan karar verme süreçleriyle entegre olur.
|
||||
|
||||
7. **Yapılandırılmış Veri Alma Hizmeti**
|
||||
Yapılandırılmış verileri çeşitli formatlarda (JSON, CSV, XML) kabul eder.
|
||||
Gelen verileri tanımlanmış şemalara göre ayrıştırır ve doğrular.
|
||||
Verileri normalleştirilmiş nesne akışlarına dönüştürür.
|
||||
Nesneleri işleme için uygun mesaj kuyruklarına gönderir.
|
||||
Toplu yüklemeleri ve akışlı almayı destekler.
|
||||
|
||||
Modül: trustgraph-flow/trustgraph/decoding/structured
|
||||
|
||||
8. **Nesne Gömme Hizmeti**
|
||||
Yapılandırılmış nesneler için vektör gömmeleri oluşturur.
|
||||
Yapılandırılmış veriler arasında semantik aramayı sağlar.
|
||||
Yapılandırılmış sorguları semantik benzerlikle birleştiren hibrit aramayı destekler.
|
||||
Mevcut vektör depolarıyla entegre olur.
|
||||
|
||||
Modül: trustgraph-flow/trustgraph/embeddings/object_embeddings/qdrant
|
||||
|
||||
### Veri Modelleri
|
||||
|
||||
#### Şema Depolama Mekanizması
|
||||
|
||||
Şemalar, aşağıdaki yapı kullanılarak TrustGraph'ın yapılandırma sisteminde saklanır:
|
||||
|
||||
**Türü**: `schema` (tüm yapılandırılmış veri şemaları için sabit değer)
|
||||
**Anahtar**: Şemanın benzersiz adı/tanımlayıcısı (örneğin, `customer_records`, `transaction_log`)
|
||||
**Değer**: Yapıyı içeren JSON şema tanımı
|
||||
|
||||
Örnek yapılandırma girişi:
|
||||
```
|
||||
Type: schema
|
||||
Key: customer_records
|
||||
Value: {
|
||||
"name": "customer_records",
|
||||
"description": "Customer information table",
|
||||
"fields": [
|
||||
{
|
||||
"name": "customer_id",
|
||||
"type": "string",
|
||||
"primary_key": true
|
||||
},
|
||||
{
|
||||
"name": "name",
|
||||
"type": "string",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"name": "email",
|
||||
"type": "string",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"name": "registration_date",
|
||||
"type": "timestamp"
|
||||
},
|
||||
{
|
||||
"name": "status",
|
||||
"type": "string",
|
||||
"enum": ["active", "inactive", "suspended"]
|
||||
}
|
||||
],
|
||||
"indexes": ["email", "registration_date"]
|
||||
}
|
||||
```
|
||||
|
||||
Bu yaklaşım şunları sağlar:
|
||||
Kod değişiklikleri olmadan dinamik şema tanımı
|
||||
Kolay şema güncellemeleri ve sürüm yönetimi
|
||||
Mevcut TrustGraph yapılandırma yönetimi ile tutarlı entegrasyon
|
||||
Tek bir dağıtım içinde birden fazla şema desteği
|
||||
|
||||
### API'ler
|
||||
|
||||
Yeni API'ler:
|
||||
Yukarıdaki türler için Pulsar şemaları
|
||||
Yeni akışlarda Pulsar arayüzleri
|
||||
Akışların hangi şema türlerini yükleyeceğini bilmesi için, şema türlerini akışlarda belirtmenin bir yolu gereklidir
|
||||
Ağ geçidi ve ters ağ geçidine eklenen API'ler
|
||||
|
||||
|
||||
Değiştirilen API'ler:
|
||||
Bilgi çıkarma uç noktaları - Yapılandırılmış nesne çıktısı seçeneği ekleyin
|
||||
Ajan uç noktaları - Yapılandırılmış veri aracı desteği ekleyin
|
||||
|
||||
### Uygulama Detayları
|
||||
|
||||
Mevcut kurallara uygun olarak, bunlar sadece yeni işleme modülleridir.
|
||||
Her şey trustgraph-flow paketlerinde yer almaktadır, şema öğeleri ise trustgraph-base'de bulunmaktadır.
|
||||
|
||||
|
||||
Bu özelliği tanıtmak/denemek için Workbench'te bazı kullanıcı arayüzü (UI) çalışmaları yapılması gerekmektedir.
|
||||
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
Ek hususlar bulunmamaktadır.
|
||||
|
||||
## Performans Hususları
|
||||
|
||||
Sorguların yavaşlamasını önlemek için Cassandra sorgularının ve indekslerinin kullanımına ilişkin bazı sorular bulunmaktadır.
|
||||
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
Mevcut test stratejisi kullanılacak, birim, sözleşme ve entegrasyon testleri oluşturulacaktır.
|
||||
|
||||
## Geçiş Planı
|
||||
|
||||
Yok.
|
||||
|
||||
## Zaman Çizelgesi
|
||||
|
||||
Belirtilmemiştir.
|
||||
|
||||
## Açık Sorular
|
||||
|
||||
Bu, diğer depolama türleriyle de çalışacak şekilde yapılabilir mi? Tek bir depolamayla çalışan modüllerin, diğer depolamalara da uygulanabilmesi için arayüzler kullanmayı hedefliyoruz.
|
||||
|
||||
|
||||
## Referanslar
|
||||
|
||||
|
||||
n/a.
|
||||
281
docs/tech-specs/tr/structured-diag-service.tr.md
Normal file
281
docs/tech-specs/tr/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`
|
||||
499
docs/tech-specs/tr/tool-group.tr.md
Normal file
499
docs/tech-specs/tr/tool-group.tr.md
Normal file
|
|
@ -0,0 +1,499 @@
|
|||
---
|
||||
layout: default
|
||||
title: "TrustGraph Araç Grubu Sistemi"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# TrustGraph Araç Grubu Sistemi
|
||||
|
||||
> **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.
|
||||
## Teknik Özellikler v1.0
|
||||
|
||||
### Yönetici Özeti
|
||||
|
||||
Bu özellik, TrustGraph ajanları için, belirli istekler için hangi araçların kullanılabilir olduğuna ince ayar yapılmasına olanak tanıyan bir araç gruplama sistemi tanımlar. Sistem, yapılandırma ve istek düzeyinde belirtme yoluyla, grup tabanlı araç filtrelemesi sunarak, daha iyi güvenlik sınırları, kaynak yönetimi ve ajan yeteneklerinin işlevsel ayrımı sağlar.
|
||||
|
||||
### 1. Genel Bakış
|
||||
|
||||
#### 1.1 Problem Tanımı
|
||||
|
||||
Şu anda, TrustGraph ajanları, istek bağlamı veya güvenlik gereksinimlerinden bağımsız olarak, yapılandırılmış tüm araçlara erişebilir. Bu, çeşitli zorluklara yol açmaktadır:
|
||||
|
||||
**Güvenlik Riski**: Hassas araçlar (örneğin, veri değişikliği), yalnızca okuma istekleri için bile kullanılabilir.
|
||||
**Kaynak İsrafı**: Karmaşık araçlar, basit istekler için gerekli olmadığında bile yüklenir.
|
||||
**İşlevsel Karmaşa**: Ajanlar, daha basit alternatifler varken, uygun olmayan araçları seçebilir.
|
||||
**Çok Kiracılı İzolasyon**: Farklı kullanıcı gruplarının farklı araç setlerine erişmesi gerekir.
|
||||
|
||||
#### 1.2 Çözümün Genel Bakışı
|
||||
|
||||
Araç grubu sistemi aşağıdaki özellikleri sunar:
|
||||
|
||||
1. **Grup Sınıflandırması**: Araçlar, yapılandırma sırasında grup üyelikleriyle etiketlenir.
|
||||
2. **İstek Düzeyinde Filtreleme**: AgentRequest, hangi araç gruplarının izinli olduğunu belirtir.
|
||||
3. **Çalışma Zamanı Uygulaması**: Ajanlar, yalnızca istenen gruplarla eşleşen araçlara erişebilir.
|
||||
4. **Esnek Gruplandırma**: Araçlar, karmaşık senaryolar için birden fazla gruba ait olabilir.
|
||||
|
||||
### 2. Şema Değişiklikleri
|
||||
|
||||
#### 2.1 Araç Yapılandırma Şeması Geliştirmesi
|
||||
|
||||
Mevcut araç yapılandırması, bir `group` alanı ile geliştirilmiştir:
|
||||
|
||||
**Önce:**
|
||||
```json
|
||||
{
|
||||
"name": "knowledge-query",
|
||||
"type": "knowledge-query",
|
||||
"description": "Query the knowledge graph"
|
||||
}
|
||||
```
|
||||
|
||||
**Sonra:**
|
||||
```json
|
||||
{
|
||||
"name": "knowledge-query",
|
||||
"type": "knowledge-query",
|
||||
"description": "Query the knowledge graph",
|
||||
"group": ["read-only", "knowledge", "basic"]
|
||||
}
|
||||
```
|
||||
|
||||
**Grup Alanı Tanımlaması:**
|
||||
`group`: Array(String) - Bu aracın ait olduğu grupların listesi
|
||||
**İsteğe Bağlı:** Grup alanı olmayan araçlar, "varsayılan" gruba aittir
|
||||
**Çoklu Üyelik:** Araçlar, birden fazla gruba ait olabilir
|
||||
**Büyük/Küçük Harf Duyarlılığı:** Grup adları, tam string eşleşmeleridir
|
||||
|
||||
#### 2.1.2 Araç Durum Geçişi Geliştirmesi
|
||||
|
||||
Araçlar, isteğe bağlı olarak durum geçişlerini ve duruma bağlı kullanılabilirliği belirtebilir:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "knowledge-query",
|
||||
"type": "knowledge-query",
|
||||
"description": "Query the knowledge graph",
|
||||
"group": ["read-only", "knowledge", "basic"],
|
||||
"state": "analysis",
|
||||
"available_in_states": ["undefined", "research"]
|
||||
}
|
||||
```
|
||||
|
||||
**Durum Alanı Tanımlaması:**
|
||||
`state`: String - **İsteğe bağlı** - Başarılı araç çalıştırması sonrasında geçilecek durum
|
||||
`available_in_states`: Array(String) - **İsteğe bağlı** - Bu aracın mevcut olduğu durumlar
|
||||
**Varsayılan davranış:** `available_in_states` değeri olmayan araçlar, tüm durumlarda kullanılabilir
|
||||
**Durum geçişi:** Sadece başarılı araç çalıştırması sonrasında gerçekleşir
|
||||
|
||||
#### 2.2 AgentRequest Şema Geliştirmesi
|
||||
|
||||
`trustgraph-base/trustgraph/schema/services/agent.py` içindeki `AgentRequest` şeması geliştirilmiştir:
|
||||
|
||||
**Mevcut AgentRequest:**
|
||||
`question`: String - Kullanıcı sorgusu
|
||||
`plan`: String - Çalıştırma planı (kaldırılabilir)
|
||||
`state`: String - Ajan durumu
|
||||
`history`: Array(AgentStep) - Çalıştırma geçmişi
|
||||
|
||||
**Geliştirilmiş AgentRequest:**
|
||||
`question`: String - Kullanıcı sorgusu
|
||||
`state`: String - Ajan çalıştırma durumu (artık araç filtreleme için aktif olarak kullanılıyor)
|
||||
`history`: Array(AgentStep) - Çalıştırma geçmişi
|
||||
`group`: Array(String) - **YENİ** - Bu istek için izin verilen araç grupları
|
||||
|
||||
**Şema Değişiklikleri:**
|
||||
**Kaldırıldı:** `plan` alanı artık gerekli değildir ve kaldırılabilir (başlangıçta araç belirtimi için tasarlanmıştı)
|
||||
**Eklendi:** Araç grubu belirtimi için `group` alanı
|
||||
**Geliştirildi:** `state` alanı artık çalıştırma sırasında araç kullanılabilirliğini kontrol eder
|
||||
|
||||
**Alan Davranışları:**
|
||||
|
||||
**Grup Alanı:**
|
||||
**İsteğe bağlı:** Belirtilmezse, varsayılan olarak ["default"] değerini alır
|
||||
**Kesişim:** Sadece en az bir belirtilen grupla eşleşen araçlar kullanılabilir
|
||||
**Boş dizi:** Hiçbir araç kullanılamaz (ajan yalnızca dahili akıl yürütmeyi kullanabilir)
|
||||
**Yıldız işareti:** Özel "*" grubu, tüm araçlara erişim sağlar
|
||||
|
||||
**Durum Alanı:**
|
||||
**İsteğe bağlı:** Belirtilmezse, varsayılan olarak "undefined" değerini alır
|
||||
**Durum tabanlı filtreleme:** Yalnızca mevcut durumda bulunan araçlar uygun olabilir
|
||||
**Varsayılan durum:** "undefined" durumu, tüm araçlara izin verir (grup filtrelemesine tabidir)
|
||||
**Durum geçişleri:** Araçlar, başarılı çalıştırmadan sonra durumu değiştirebilir
|
||||
|
||||
### 3. Özel Grup Örnekleri
|
||||
|
||||
Kuruluşlar, alanla ilgili özel gruplar tanımlayabilir:
|
||||
|
||||
```json
|
||||
{
|
||||
"financial-tools": ["stock-query", "portfolio-analysis"],
|
||||
"medical-tools": ["diagnosis-assist", "drug-interaction"],
|
||||
"legal-tools": ["contract-analysis", "case-search"]
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Uygulama Detayları
|
||||
|
||||
#### 4.1 Araç Yükleme ve Filtreleme
|
||||
|
||||
**Yapılandırma Aşaması:**
|
||||
1. Tüm araçlar, grup atamalarıyla birlikte yapılandırmadan yüklenir.
|
||||
2. Açık bir grup atanmamış araçlar, "varsayılan" gruba atanır.
|
||||
3. Grup üyeliği doğrulanır ve araç kaydında saklanır.
|
||||
|
||||
**İstek İşleme Aşaması:**
|
||||
1. İsteğe bağlı grup belirtimiyle birlikte AgentRequest gelir.
|
||||
2. Agent, mevcut araçları grup kesişimi temelinde filtreler.
|
||||
3. Yalnızca eşleşen araçlar, agent yürütme bağlamına iletilir.
|
||||
4. Agent, istek yaşam döngüsü boyunca filtrelenmiş araç kümesiyle çalışır.
|
||||
|
||||
#### 4.2 Araç Filtreleme Mantığı
|
||||
|
||||
**Birleştirilmiş Grup ve Durum Filtreleme:**
|
||||
|
||||
```
|
||||
For each configured tool:
|
||||
tool_groups = tool.group || ["default"]
|
||||
tool_states = tool.available_in_states || ["*"] // Available in all states
|
||||
|
||||
For each request:
|
||||
requested_groups = request.group || ["default"]
|
||||
current_state = request.state || "undefined"
|
||||
|
||||
Tool is available if:
|
||||
// Group filtering
|
||||
(intersection(tool_groups, requested_groups) is not empty OR "*" in requested_groups)
|
||||
AND
|
||||
// State filtering
|
||||
(current_state in tool_states OR "*" in tool_states)
|
||||
```
|
||||
|
||||
**Durum Geçişi Mantığı:**
|
||||
|
||||
```
|
||||
After successful tool execution:
|
||||
if tool.state is defined:
|
||||
next_request.state = tool.state
|
||||
else:
|
||||
next_request.state = current_request.state // No change
|
||||
```
|
||||
|
||||
#### 4.3 Ajan Entegrasyon Noktaları
|
||||
|
||||
**ReAct Ajanı:**
|
||||
Araç filtrelemesi, araç kaydı oluşturulurken agent_manager.py dosyasında gerçekleşir.
|
||||
Kullanılabilir araçlar listesi, plan oluşturulmadan önce hem grup hem de duruma göre filtrelenir.
|
||||
Durum geçişleri, başarılı araç çalıştırması sonrasında AgentRequest.state alanını günceller.
|
||||
Bir sonraki yineleme, araç filtrelemesi için güncellenmiş durumu kullanır.
|
||||
|
||||
**Güvenilirlik Tabanlı Ajan:**
|
||||
Araç filtrelemesi, plan oluşturulurken planner.py dosyasında gerçekleşir.
|
||||
ExecutionStep doğrulama, yalnızca grup+durum uygun araçların kullanıldığından emin olur.
|
||||
Akış denetleyicisi, çalışma zamanında araç kullanılabilirliğini zorlar.
|
||||
Durum geçişleri, adımlar arasında Akış Denetleyicisi tarafından yönetilir.
|
||||
|
||||
### 5. Yapılandırma Örnekleri
|
||||
|
||||
#### 5.1 Gruplar ve Durumlarla Araç Yapılandırması
|
||||
|
||||
```yaml
|
||||
tool:
|
||||
knowledge-query:
|
||||
type: knowledge-query
|
||||
name: "Knowledge Graph Query"
|
||||
description: "Query the knowledge graph for entities and relationships"
|
||||
group: ["read-only", "knowledge", "basic"]
|
||||
state: "analysis"
|
||||
available_in_states: ["undefined", "research"]
|
||||
|
||||
graph-update:
|
||||
type: graph-update
|
||||
name: "Graph Update"
|
||||
description: "Add or modify entities in the knowledge graph"
|
||||
group: ["write", "knowledge", "admin"]
|
||||
available_in_states: ["analysis", "modification"]
|
||||
|
||||
text-completion:
|
||||
type: text-completion
|
||||
name: "Text Completion"
|
||||
description: "Generate text using language models"
|
||||
group: ["read-only", "text", "basic"]
|
||||
state: "undefined"
|
||||
# No available_in_states = available in all states
|
||||
|
||||
complex-analysis:
|
||||
type: mcp-tool
|
||||
name: "Complex Analysis Tool"
|
||||
description: "Perform complex data analysis"
|
||||
group: ["advanced", "compute", "expensive"]
|
||||
state: "results"
|
||||
available_in_states: ["analysis"]
|
||||
mcp_tool_id: "analysis-server"
|
||||
|
||||
reset-workflow:
|
||||
type: mcp-tool
|
||||
name: "Reset Workflow"
|
||||
description: "Reset to initial state"
|
||||
group: ["admin"]
|
||||
state: "undefined"
|
||||
available_in_states: ["analysis", "results"]
|
||||
```
|
||||
|
||||
#### 5.2 Durum İş Akışlarıyla Birlikte İstek Örnekleri
|
||||
|
||||
**Başlangıç Araştırma İsteği:**
|
||||
```json
|
||||
{
|
||||
"question": "What entities are connected to Company X?",
|
||||
"group": ["read-only", "knowledge"],
|
||||
"state": "undefined"
|
||||
}
|
||||
```
|
||||
*Mevcut araçlar: knowledge-query, text-completion*
|
||||
*knowledge-query işleminden sonra: durum → "analiz"*
|
||||
|
||||
**Analiz Aşaması:**
|
||||
```json
|
||||
{
|
||||
"question": "Continue analysis based on previous results",
|
||||
"group": ["advanced", "compute", "write"],
|
||||
"state": "analysis"
|
||||
}
|
||||
```
|
||||
*Mevcut araçlar: karmaşık analiz, grafik güncelleme, iş akışı sıfırlama*
|
||||
*Karmaşık analizden sonra: durum → "sonuçlar"*
|
||||
|
||||
**Sonuçlar Aşaması:**
|
||||
```json
|
||||
{
|
||||
"question": "What should I do with these results?",
|
||||
"group": ["admin"],
|
||||
"state": "results"
|
||||
}
|
||||
```
|
||||
*Mevcut araçlar: yalnızca reset-workflow*
|
||||
*reset-workflow'dan sonra: durum → "undefined"*
|
||||
|
||||
**İş Akışı Örneği - Tam Akış:**
|
||||
1. **Başlangıç (undefined):** knowledge-query kullanın → "analysis" durumuna geçiş yapar.
|
||||
2. **Analiz durumu:** complex-analysis kullanın → "results" durumuna geçiş yapar.
|
||||
3. **Sonuç durumu:** reset-workflow kullanın → "undefined" durumuna geri döner.
|
||||
4. **Başlangıca dönüş:** Tüm başlangıç araçları tekrar kullanılabilir.
|
||||
|
||||
### 6. Güvenlik Hususları
|
||||
|
||||
#### 6.1 Erişim Kontrolü Entegrasyonu
|
||||
|
||||
**Ağ Geçidi Seviyesinde Filtreleme:**
|
||||
Ağ geçidi, kullanıcı izinlerine göre grup kısıtlamalarını uygulayabilir.
|
||||
İstek manipülasyonu yoluyla yetki yükseltmesini engelleyin.
|
||||
Denetim kaydı, istenen ve verilen araç gruplarını içerir.
|
||||
|
||||
**Örnek Ağ Geçidi Mantığı:**
|
||||
```
|
||||
user_permissions = get_user_permissions(request.user_id)
|
||||
allowed_groups = user_permissions.tool_groups
|
||||
requested_groups = request.group
|
||||
|
||||
# Validate request doesn't exceed permissions
|
||||
if not is_subset(requested_groups, allowed_groups):
|
||||
reject_request("Insufficient permissions for requested tool groups")
|
||||
```
|
||||
|
||||
#### 6.2 Denetim ve İzleme
|
||||
|
||||
**Gelişmiş Denetim Kayıtları:**
|
||||
İstenen araç gruplarını ve her istek için başlangıç durumunu kaydet.
|
||||
Grup üyeliği tarafından durum geçişlerini ve araç kullanımını izle.
|
||||
Yetkisiz grup erişim girişimlerini ve geçersiz durum geçişlerini izle.
|
||||
Olağandışı grup kullanım kalıplarını veya şüpheli durum iş akışlarını tespit etme konusunda uyarı ver.
|
||||
|
||||
### 7. Geçiş Stratejisi
|
||||
|
||||
#### 7.1 Geriye Dönük Uyumluluk
|
||||
|
||||
**1. Aşama: Eklemeler**
|
||||
Araç yapılandırmalarına isteğe bağlı `group` alanı ekle.
|
||||
AgentRequest şemasına isteğe bağlı `group` alanı ekle.
|
||||
Varsayılan davranış: Tüm mevcut araçlar "varsayılan" grubuna aittir.
|
||||
Grup alanı olmayan mevcut istekler "varsayılan" grubunu kullanır.
|
||||
|
||||
**Mevcut Davranış Korunmuştur:**
|
||||
Grup yapılandırması olmayan araçlar çalışmaya devam eder (varsayılan grup).
|
||||
Durum yapılandırması olmayan araçlar tüm durumlarda kullanılabilir.
|
||||
Grup belirtimi olmayan istekler tüm araçlara erişebilir (varsayılan grup).
|
||||
Durum belirtimi olmayan istekler "belirsiz" durumu kullanır (tüm araçlar kullanılabilir).
|
||||
Mevcut dağıtımlarda herhangi bir değişiklik yapılmamıştır.
|
||||
|
||||
### 8. İzleme ve Gözlemlenebilirlik
|
||||
|
||||
#### 8.1 Yeni Metrikler
|
||||
|
||||
**Araç Grubu Kullanımı:**
|
||||
`agent_tool_group_requests_total` - Grup başına istek sayısı.
|
||||
`agent_tool_group_availability` - Grup başına kullanılabilir araç sayısı.
|
||||
`agent_filtered_tools_count` - Grup+durum filtrelemesinden sonraki araç sayısı histogramı.
|
||||
|
||||
**Durum İş Akışı Metrikleri:**
|
||||
`agent_state_transitions_total` - Araç başına durum geçişleri sayısı.
|
||||
`agent_workflow_duration_seconds` - Her durumda geçirilen süre histogramı.
|
||||
`agent_state_availability` - Durum başına kullanılabilir araç sayısı.
|
||||
|
||||
**Güvenlik Metrikleri:**
|
||||
`agent_group_access_denied_total` - Yetkisiz grup erişim sayısı.
|
||||
`agent_invalid_state_transition_total` - Geçersiz durum geçişleri sayısı.
|
||||
`agent_privilege_escalation_attempts_total` - Şüpheli istekler sayısı.
|
||||
|
||||
#### 8.2 Kayıt Güncellemeleri
|
||||
|
||||
**İstek Kayıtları:**
|
||||
```json
|
||||
{
|
||||
"request_id": "req-123",
|
||||
"requested_groups": ["read-only", "knowledge"],
|
||||
"initial_state": "undefined",
|
||||
"state_transitions": [
|
||||
{"tool": "knowledge-query", "from": "undefined", "to": "analysis", "timestamp": "2024-01-01T10:00:01Z"}
|
||||
],
|
||||
"available_tools": ["knowledge-query", "text-completion"],
|
||||
"filtered_by_group": ["graph-update", "admin-tool"],
|
||||
"filtered_by_state": [],
|
||||
"execution_time": "1.2s"
|
||||
}
|
||||
```
|
||||
|
||||
### 9. Test Stratejisi
|
||||
|
||||
#### 9.1 Birim Testleri
|
||||
|
||||
**Araç Filtreleme Mantığı:**
|
||||
Test grubu kesişimi hesaplamaları
|
||||
Test durumu tabanlı filtreleme mantığı
|
||||
Varsayılan grup ve durum atamasını doğrulayın
|
||||
Test joker karakterli grup davranışını
|
||||
Boş grup işleme doğrulamasını
|
||||
Test birleştirilmiş grup+durum filtreleme senaryolarını
|
||||
|
||||
**Yapılandırma Doğrulama:**
|
||||
Test farklı grup ve durum yapılandırmalarıyla araç yüklemeyi
|
||||
Geçersiz grup ve durum tanımları için şema doğrulamasını
|
||||
Test mevcut yapılandırmalarla geriye dönük uyumluluğu
|
||||
Durum geçişi tanımlarını ve döngülerini doğrulayın
|
||||
|
||||
#### 9.2 Entegrasyon Testleri
|
||||
|
||||
**Ajan Davranışı:**
|
||||
Ajanların yalnızca grup+durumla filtrelenmiş araçları gördüğünü doğrulayın
|
||||
Test farklı grup kombinasyonlarıyla istek yürütmeyi
|
||||
Ajan yürütülmesi sırasında durum geçişlerini test edin
|
||||
Kullanılabilir araç olmadığında hata işleme doğrulamasını
|
||||
Test çoklu durumlar aracılığıyla iş akışı ilerlemesini
|
||||
|
||||
**Güvenlik Testleri:**
|
||||
Test ayrıcalık yükseltme önlemini
|
||||
Denetim kaydı doğruluğunu doğrulayın
|
||||
Kullanıcı izinleriyle ağ geçidi entegrasyonunu test edin
|
||||
|
||||
#### 9.3 Uçtan Uca Senaryolar
|
||||
|
||||
**Durum İş Akışlarıyla Çok Kiracılı Kullanım:**
|
||||
```
|
||||
Scenario: Different users with different tool access and workflow states
|
||||
Given: User A has "read-only" permissions, state "undefined"
|
||||
And: User B has "write" permissions, state "analysis"
|
||||
When: Both request knowledge operations
|
||||
Then: User A gets read-only tools available in "undefined" state
|
||||
And: User B gets write tools available in "analysis" state
|
||||
And: State transitions are tracked per user session
|
||||
And: All usage and transitions are properly audited
|
||||
```
|
||||
|
||||
**İş Akışı Durumu İlerlemesi:**
|
||||
```
|
||||
Scenario: Complete workflow execution
|
||||
Given: Request with groups ["knowledge", "compute"] and state "undefined"
|
||||
When: Agent executes knowledge-query tool (transitions to "analysis")
|
||||
And: Agent executes complex-analysis tool (transitions to "results")
|
||||
And: Agent executes reset-workflow tool (transitions to "undefined")
|
||||
Then: Each step has correctly filtered available tools
|
||||
And: State transitions are logged with timestamps
|
||||
And: Final state allows initial workflow to repeat
|
||||
```
|
||||
|
||||
### 10. Performans Hususları
|
||||
|
||||
#### 10.1 Araç Yükleme Etkisi
|
||||
|
||||
**Yapılandırma Yükleme:**
|
||||
Grup ve durum meta verileri, başlatmada yalnızca bir kez yüklenir.
|
||||
Her araç için minimum bellek yükü (ek alanlar).
|
||||
Araç başlatma süresi üzerinde herhangi bir etkisi yoktur.
|
||||
|
||||
**İstek İşleme:**
|
||||
Grup+durum filtrelemesi, her istek için yalnızca bir kez yapılır.
|
||||
Yapılandırılmış araç sayısına (n) bağlı olarak O(n) karmaşıklığı.
|
||||
Durum geçişleri, minimum bir yük ekler (dize ataması).
|
||||
Tipik araç sayıları (< 100) için ihmal edilebilir bir etki.
|
||||
|
||||
#### 10.2 Optimizasyon Stratejileri
|
||||
|
||||
**Önceden Hesaplanan Araç Kümeleri:**
|
||||
Araç kümelerini grup+durum kombinasyonuna göre önbelleğe alın.
|
||||
Yaygın grup/durum kalıpları için tekrarlanan filtrelemeyi önleyin.
|
||||
Sık kullanılan kombinasyonlar için bellek ve hesaplama arasında bir denge.
|
||||
|
||||
**Gecikmeli Yükleme:**
|
||||
Araç uygulamalarını yalnızca ihtiyaç duyulduğunda yükleyin.
|
||||
Birçok araca sahip dağıtımların başlatma süresini azaltın.
|
||||
Grup gereksinimlerine göre dinamik araç kaydı.
|
||||
|
||||
### 11. Gelecekteki Geliştirmeler
|
||||
|
||||
#### 11.1 Dinamik Grup Ataması
|
||||
|
||||
**Bağlam Farkındalığına Sahip Gruplandırma:**
|
||||
Araçları, istek bağlamına göre gruplara atayın.
|
||||
Zaman tabanlı grup kullanılabilirliği (sadece iş saatleri).
|
||||
Yük tabanlı grup kısıtlamaları (düşük kullanımda pahalı araçlar).
|
||||
|
||||
#### 11.2 Grup Hiyerarşileri
|
||||
|
||||
**İç İçe Geçmiş Grup Yapısı:**
|
||||
```json
|
||||
{
|
||||
"knowledge": {
|
||||
"read": ["knowledge-query", "entity-search"],
|
||||
"write": ["graph-update", "entity-create"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 11.3 Araç Önerileri
|
||||
|
||||
**Grup Tabanlı Öneriler:**
|
||||
İstek türleri için en uygun araç gruplarını önerin
|
||||
Önerileri iyileştirmek için kullanım kalıplarından öğrenin
|
||||
Tercih edilen araçlar kullanılamadığında yedek gruplar sağlayın
|
||||
|
||||
### 12. Açık Sorular
|
||||
|
||||
1. **Grup Doğrulama**: İstehlerdeki geçersiz grup adları, sert hatalara mı yoksa uyarı mesajlarına mı neden olmalıdır?
|
||||
|
||||
2. **Grup Keşfi**: Sistem, mevcut grupları ve araçlarını listelemek için bir API sağlamalı mıdır?
|
||||
|
||||
3. **Dinamik Gruplar**: Gruplar, çalışma zamanında mı yoksa yalnızca başlangıçta mı yapılandırılabilir olmalıdır?
|
||||
|
||||
4. **Grup Mirası**: Araçlar, grup bilgilerini ebeveyn kategorilerinden veya uygulamalarından mı miras almalıdır?
|
||||
|
||||
5. **Performans İzleme**: Grup tabanlı araç kullanımını etkili bir şekilde izlemek için hangi ek metrikler gereklidir?
|
||||
|
||||
### 13. Sonuç
|
||||
|
||||
Araç grubu sistemi şunları sağlar:
|
||||
|
||||
**Güvenlik**: Aracılar üzerindeki yetenekler için ayrıntılı erişim kontrolü
|
||||
**Performans**: Araç yükleme ve seçim üzerindeki ek yükün azaltılması
|
||||
**Esneklik**: Çok boyutlu araç sınıflandırması
|
||||
**Uyumluluk**: Mevcut araç mimarileriyle sorunsuz entegrasyon
|
||||
|
||||
Bu sistem, TrustGraph dağıtımlarının araç erişimini daha iyi yönetmesini, güvenlik sınırlarını iyileştirmesini ve mevcut yapılandırmalar ve isteklerle tam uyumluluğu korurken kaynak kullanımını optimize etmesini sağlar.
|
||||
479
docs/tech-specs/tr/tool-services.tr.md
Normal file
479
docs/tech-specs/tr/tool-services.tr.md
Normal file
|
|
@ -0,0 +1,479 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Araç Hizmetleri: Dinamik Olarak Eklenebilen Ajan Araçları"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Araç Hizmetleri: Dinamik Olarak Eklenebilen Ajan Araçları
|
||||
|
||||
> **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.
|
||||
|
||||
## Durum
|
||||
|
||||
Uygulandı
|
||||
|
||||
## Genel Bakış
|
||||
|
||||
Bu özellik, "araç hizmetleri" olarak adlandırılan, dinamik olarak eklenebilen ajan araçları için bir mekanizma tanımlar. Mevcut, yerleşik araç türlerinin (`KnowledgeQueryImpl`, `McpToolImpl`, vb.) aksine, araç hizmetleri, aşağıdaki yöntemlerle yeni araçların eklenmesine olanak tanır:
|
||||
|
||||
1. Yeni bir Pulsar tabanlı hizmetin dağıtılması
|
||||
2. Ajanın hizmeti nasıl çağıracağını belirten bir yapılandırma açıklamasının eklenmesi
|
||||
|
||||
Bu, çekirdek ajan-yanıt çerçevesini değiştirmeden genişletilebilirlik sağlar.
|
||||
|
||||
## Terminoloji
|
||||
|
||||
| Terim | Tanım |
|
||||
|------|------------|
|
||||
| **Yerleşik Araç** | `tools.py` içinde sabit kodlanmış uygulamalara sahip mevcut araç türleri |
|
||||
| **Araç Hizmeti** | Bir hizmet açıklamasıyla tanımlanan ve bir ajan aracı olarak çağrılabilecek bir Pulsar hizmeti |
|
||||
| **Araç** | Bir hizmet aracını referans alan ve ajana/LLM'ye sunulan yapılandırılmış bir örnek |
|
||||
|
||||
Bu, MCP araçlarına benzer iki katmanlı bir modeldir:
|
||||
MCP: MCP sunucusu araç arayüzünü tanımlar → Araç yapılandırması buna başvurur
|
||||
Araç Hizmetleri: Araç hizmeti Pulsar arayüzünü tanımlar → Araç yapılandırması buna başvurur
|
||||
|
||||
## Arka Plan: Mevcut Araçlar
|
||||
|
||||
### Yerleşik Araç Uygulaması
|
||||
|
||||
Araçlar şu anda `trustgraph-flow/trustgraph/agent/react/tools.py` içinde, türlenmiş uygulamalarla tanımlanmıştır:
|
||||
|
||||
```python
|
||||
class KnowledgeQueryImpl:
|
||||
async def invoke(self, question):
|
||||
client = self.context("graph-rag-request")
|
||||
return await client.rag(question, self.collection)
|
||||
```
|
||||
|
||||
Her araç türü:
|
||||
Çağırdığı sabit kodlu bir Pulsar servisine sahiptir (örneğin, `graph-rag-request`)
|
||||
İstemci üzerinde çağrılacak kesin yöntemi bilir (örneğin, `client.rag()`)
|
||||
Uygulamada tanımlanmış türlü argümanlara sahiptir
|
||||
|
||||
### Araç Kaydı (service.py:105-214)
|
||||
|
||||
Araçlar, bir uygulamaya eşleyen `type` alanıyla yapılandırmadan yüklenir:
|
||||
|
||||
```python
|
||||
if impl_id == "knowledge-query":
|
||||
impl = functools.partial(KnowledgeQueryImpl, collection=data.get("collection"))
|
||||
elif impl_id == "text-completion":
|
||||
impl = TextCompletionImpl
|
||||
# ... etc
|
||||
```
|
||||
|
||||
## Mimari
|
||||
|
||||
### İki Katmanlı Model
|
||||
|
||||
#### 1. Katman: Araç Hizmeti Tanımlayıcısı
|
||||
|
||||
Bir araç hizmeti, bir Pulsar hizmeti arayüzünü tanımlar. Aşağıdakileri belirtir:
|
||||
İstek/yanıt için kullanılan Pulsar kuyrukları
|
||||
Onu kullanan araçlardan gerektirdiği yapılandırma parametreleri
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "custom-rag",
|
||||
"request-queue": "non-persistent://tg/request/custom-rag",
|
||||
"response-queue": "non-persistent://tg/response/custom-rag",
|
||||
"config-params": [
|
||||
{"name": "collection", "required": true}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Herhangi bir yapılandırma parametresine ihtiyaç duymayan bir araç hizmeti:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "calculator",
|
||||
"request-queue": "non-persistent://tg/request/calc",
|
||||
"response-queue": "non-persistent://tg/response/calc",
|
||||
"config-params": []
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Seviye: Araç Açıklaması
|
||||
|
||||
Bir araç, bir araç hizmetine başvurur ve şunları sağlar:
|
||||
Yapılandırma parametre değerleri (hizmetin gereksinimlerini karşılar)
|
||||
Aracının ajana yönelik meta verileri (ad, açıklama)
|
||||
LLM için argüman tanımları
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "tool-service",
|
||||
"name": "query-customers",
|
||||
"description": "Query the customer knowledge base",
|
||||
"service": "custom-rag",
|
||||
"collection": "customers",
|
||||
"arguments": [
|
||||
{
|
||||
"name": "question",
|
||||
"type": "string",
|
||||
"description": "The question to ask about customers"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Birden fazla aracın, farklı yapılandırmalarla aynı hizmete başvurabileceğini unutmayın:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "tool-service",
|
||||
"name": "query-products",
|
||||
"description": "Query the product knowledge base",
|
||||
"service": "custom-rag",
|
||||
"collection": "products",
|
||||
"arguments": [
|
||||
{
|
||||
"name": "question",
|
||||
"type": "string",
|
||||
"description": "The question to ask about products"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### İstek Formatı
|
||||
|
||||
Bir araç çağrıldığında, araca yapılan istek, aşağıdaki bilgileri içerir:
|
||||
`user`: Aracının isteğinden (çoklu kiracılık)
|
||||
`config`: Araç açıklamasından alınan, JSON formatında kodlanmış yapılandırma değerleri
|
||||
`arguments`: LLM'den alınan, JSON formatında kodlanmış argümanlar
|
||||
|
||||
```json
|
||||
{
|
||||
"user": "alice",
|
||||
"config": "{\"collection\": \"customers\"}",
|
||||
"arguments": "{\"question\": \"What are the top customer complaints?\"}"
|
||||
}
|
||||
```
|
||||
|
||||
Araç hizmeti, bunları `invoke` yönteminde ayrıştırılmış sözlükler olarak alır.
|
||||
|
||||
### Genel Araç Hizmeti Uygulaması
|
||||
|
||||
Bir `ToolServiceImpl` sınıfı, yapılandırmaya göre araç hizmetlerini çağırır:
|
||||
|
||||
```python
|
||||
class ToolServiceImpl:
|
||||
def __init__(self, context, request_queue, response_queue, config_values, arguments, processor):
|
||||
self.request_queue = request_queue
|
||||
self.response_queue = response_queue
|
||||
self.config_values = config_values # e.g., {"collection": "customers"}
|
||||
# ...
|
||||
|
||||
async def invoke(self, **arguments):
|
||||
client = await self._get_or_create_client()
|
||||
response = await client.call(user, self.config_values, arguments)
|
||||
if isinstance(response, str):
|
||||
return response
|
||||
else:
|
||||
return json.dumps(response)
|
||||
```
|
||||
|
||||
## Tasarım Kararları
|
||||
|
||||
### İki Katmanlı Konfigürasyon Modeli
|
||||
|
||||
Araç hizmetleri, MCP araçlarına benzer bir iki katmanlı model izler:
|
||||
|
||||
1. **Araç Hizmeti**: Pulsar hizmet arayüzünü (konu, gerekli yapılandırma parametreleri) tanımlar.
|
||||
2. **Araç**: Bir araç hizmetine başvurur, yapılandırma değerlerini sağlar, LLM argümanlarını tanımlar.
|
||||
|
||||
Bu ayrım şunları sağlar:
|
||||
Farklı yapılandırmalara sahip birden fazla aracın aynı araç hizmetini kullanabilmesi
|
||||
Hizmet arayüzü ve araç yapılandırması arasındaki net ayrım
|
||||
Hizmet tanımlarının yeniden kullanılabilirliği
|
||||
|
||||
### İstek Eşleme: Zarf ile Doğrudan İletim
|
||||
|
||||
Bir araç hizmetine yapılan istek, şunları içeren yapılandırılmış bir zarf içerir:
|
||||
`user`: Çoklu kiracılık için aracıdan gelen istekten aktarılır.
|
||||
Yapılandırma değerleri: Araç açıklamasından (örneğin, `collection`).
|
||||
`arguments`: LLM tarafından sağlanan argümanlar, bir sözlük olarak iletilir.
|
||||
|
||||
Aracı yöneticisi, LLM'nin yanıtını `act.arguments` olarak bir sözlükte (`agent_manager.py:117-154`) ayrıştırır. Bu sözlük, istek zarfında bulunur.
|
||||
|
||||
### Şema İşleme: Türsüz
|
||||
|
||||
İstekler ve yanıtlar, tür tanımlaması olmayan sözlükler kullanır. Aracılar seviyesinde herhangi bir şema doğrulaması yapılmaz; araç hizmeti, girişlerini doğrulamaktan sorumludur. Bu, yeni hizmetler tanımlamak için maksimum esneklik sağlar.
|
||||
|
||||
### İstemci Arayüzü: Doğrudan Pulsar Konuları
|
||||
|
||||
Araç hizmetleri, akış yapılandırması gerektirmeden doğrudan Pulsar konularını kullanır. Araç hizmeti tanımında, tam kuyruk adları belirtilir:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "joke-service",
|
||||
"request-queue": "non-persistent://tg/request/joke",
|
||||
"response-queue": "non-persistent://tg/response/joke",
|
||||
"config-params": [...]
|
||||
}
|
||||
```
|
||||
|
||||
Bu, hizmetlerin herhangi bir ad alanında barındırılmasını sağlar.
|
||||
|
||||
### Hata Yönetimi: Standart Hata Kuralı
|
||||
|
||||
Ara hizmet yanıtları, `error` alanı ile mevcut şema kuralını takip eder:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class Error:
|
||||
type: str = ""
|
||||
message: str = ""
|
||||
```
|
||||
|
||||
Yanıt yapısı:
|
||||
Başarı: `error`, `None` ise, yanıt sonuç içerir.
|
||||
Hata: `error`, `type` ve `message` ile doldurulur.
|
||||
|
||||
Bu, mevcut hizmet şemalarında kullanılan kalıpla eşleşir (örneğin, `PromptResponse`, `QueryResponse`, `AgentResponse`).
|
||||
|
||||
### İstek/Yanıt İlişkilendirmesi
|
||||
|
||||
İstekler ve yanıtlar, Pulsar mesaj özelliklerindeki bir `id` kullanılarak ilişkilendirilir:
|
||||
|
||||
İstek, özelliklerde `id` içerir: `properties={"id": id}`
|
||||
Yanıt(lar), aynı `id`'ı içerir: `properties={"id": id}`
|
||||
|
||||
Bu, kod tabanında kullanılan mevcut kalıpla uyumludur (örneğin, `agent_service.py`, `llm_service.py`).
|
||||
|
||||
### Akış Desteği
|
||||
|
||||
Araç hizmetleri, akış yanıtları döndürebilir:
|
||||
|
||||
Aynı `id`'a sahip çoklu yanıt mesajı
|
||||
Her yanıt, `end_of_stream: bool` alanını içerir
|
||||
Son yanıt, `end_of_stream: True`'a sahiptir
|
||||
|
||||
Bu, `AgentResponse` ve diğer akış hizmetlerinde kullanılan kalıpla eşleşir.
|
||||
|
||||
### Yanıt İşleme: String Dönüşü
|
||||
|
||||
Tüm mevcut araçlar aynı kalıbı izler: **argümanları bir sözlük olarak alın, gözlemi bir dize olarak döndürün**.
|
||||
|
||||
| Araç | Yanıt İşleme |
|
||||
|------|------------------|
|
||||
| `KnowledgeQueryImpl` | `client.rag()`'i doğrudan döndürür (dize) |
|
||||
| `TextCompletionImpl` | `client.question()`'i doğrudan döndürür (dize) |
|
||||
| `McpToolImpl` | Bir dize döndürür veya dize değilse `json.dumps(output)` döndürür |
|
||||
| `StructuredQueryImpl` | Sonucu bir dizeye dönüştürür |
|
||||
| `PromptImpl` | `client.prompt()`'i doğrudan döndürür (dize) |
|
||||
|
||||
Araç hizmetleri aynı sözleşmeyi izler:
|
||||
Hizmet, bir dize yanıtı (gözlem) döndürür
|
||||
Yanıt bir dize değilse, `json.dumps()` aracılığıyla dönüştürülür
|
||||
Tanımlayıcıda herhangi bir çıkarma yapılandırması gerekmez
|
||||
|
||||
Bu, tanımlayıcıyı basit tutar ve aracın uygun bir metin yanıtı döndürme sorumluluğunu hizmete bırakır.
|
||||
|
||||
## Yapılandırma Kılavuzu
|
||||
|
||||
Yeni bir araç hizmeti eklemek için, iki yapılandırma öğesi gereklidir:
|
||||
|
||||
### 1. Araç Hizmeti Yapılandırması
|
||||
|
||||
`tool-service` yapılandırma anahtarı altında saklanır. Pulsar kuyruklarını ve mevcut yapılandırma parametrelerini tanımlar.
|
||||
|
||||
| Alan | Gerekli | Açıklama |
|
||||
|-------|----------|-------------|
|
||||
| `id` | Evet | Araç hizmeti için benzersiz tanımlayıcı |
|
||||
| `request-queue` | Evet | İstekler için tam Pulsar konusu (örneğin, `non-persistent://tg/request/joke`) |
|
||||
| `response-queue` | Evet | Yanıtlar için tam Pulsar konusu (örneğin, `non-persistent://tg/response/joke`) |
|
||||
| `config-params` | Hayır | Hizmetin kabul ettiği yapılandırma parametrelerinin dizisi |
|
||||
|
||||
Her yapılandırma parametresi şunları belirtebilir:
|
||||
`name`: Parametre adı (gerekli)
|
||||
`required`: Parametrenin araçlar tarafından sağlanması gerekip gerekmediği (varsayılan: false)
|
||||
|
||||
Örnek:
|
||||
```json
|
||||
{
|
||||
"id": "joke-service",
|
||||
"request-queue": "non-persistent://tg/request/joke",
|
||||
"response-queue": "non-persistent://tg/response/joke",
|
||||
"config-params": [
|
||||
{"name": "style", "required": false}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Araç Yapılandırması
|
||||
|
||||
`tool` anahtarının altında saklanır. Aracının kullanabileceği bir aracı tanımlar.
|
||||
|
||||
| Alan | Gerekli | Açıklama |
|
||||
|-------|----------|-------------|
|
||||
| `type` | Evet | `"tool-service"` olmalıdır |
|
||||
| `name` | Evet | LLM'ye sunulan araç adı |
|
||||
| `description` | Evet | Aracın ne yaptığına dair açıklama (LLM'ye gösterilir) |
|
||||
| `service` | Evet | Çağrılacak araç hizmetinin kimliği |
|
||||
| `arguments` | Hayır | LLM için argüman tanımları dizisi |
|
||||
| *(yapılandırma parametreleri)* | Değişken | Hizmet tarafından tanımlanan herhangi bir yapılandırma parametresi |
|
||||
|
||||
Her argüman aşağıdaki gibi bir şeye sahip olabilir:
|
||||
`name`: Argüman adı (gerekli)
|
||||
`type`: Veri türü, örneğin `"string"` (gerekli)
|
||||
`description`: LLM'ye gösterilen açıklama (gerekli)
|
||||
|
||||
Örnek:
|
||||
```json
|
||||
{
|
||||
"type": "tool-service",
|
||||
"name": "tell-joke",
|
||||
"description": "Tell a joke on a given topic",
|
||||
"service": "joke-service",
|
||||
"style": "pun",
|
||||
"arguments": [
|
||||
{
|
||||
"name": "topic",
|
||||
"type": "string",
|
||||
"description": "The topic for the joke (e.g., programming, animals, food)"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Yapılandırmayı Yükleme
|
||||
|
||||
Yapılandırmaları yüklemek için `tg-put-config-item`'ı kullanın:
|
||||
|
||||
```bash
|
||||
# Load tool-service config
|
||||
tg-put-config-item tool-service/joke-service < joke-service.json
|
||||
|
||||
# Load tool config
|
||||
tg-put-config-item tool/tell-joke < tell-joke.json
|
||||
```
|
||||
|
||||
Aracının ve yöneticinin, yeni yapılandırmaları alabilmesi için yeniden başlatılması gerekir.
|
||||
|
||||
## Uygulama Detayları
|
||||
|
||||
### Şema
|
||||
|
||||
`trustgraph-base/trustgraph/schema/services/tool_service.py` içindeki istek ve yanıt türleri:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ToolServiceRequest:
|
||||
user: str = "" # User context for multi-tenancy
|
||||
config: str = "" # JSON-encoded config values from tool descriptor
|
||||
arguments: str = "" # JSON-encoded arguments from LLM
|
||||
|
||||
@dataclass
|
||||
class ToolServiceResponse:
|
||||
error: Error | None = None
|
||||
response: str = "" # String response (the observation)
|
||||
end_of_stream: bool = False
|
||||
```
|
||||
|
||||
### Sunucu Tarafı: DynamicToolService
|
||||
|
||||
`trustgraph-base/trustgraph/base/dynamic_tool_service.py` içindeki temel sınıf:
|
||||
|
||||
```python
|
||||
class DynamicToolService(AsyncProcessor):
|
||||
"""Base class for implementing tool services."""
|
||||
|
||||
def __init__(self, **params):
|
||||
topic = params.get("topic", default_topic)
|
||||
# Constructs topics: non-persistent://tg/request/{topic}, non-persistent://tg/response/{topic}
|
||||
# Sets up Consumer and Producer
|
||||
|
||||
async def invoke(self, user, config, arguments):
|
||||
"""Override this method to implement the tool's logic."""
|
||||
raise NotImplementedError()
|
||||
```
|
||||
|
||||
### İstemci Tarafı: ToolServiceImpl
|
||||
|
||||
`trustgraph-flow/trustgraph/agent/react/tools.py` içindeki uygulama:
|
||||
|
||||
```python
|
||||
class ToolServiceImpl:
|
||||
def __init__(self, context, request_queue, response_queue, config_values, arguments, processor):
|
||||
# Uses the provided queue paths directly
|
||||
# Creates ToolServiceClient on first use
|
||||
|
||||
async def invoke(self, **arguments):
|
||||
client = await self._get_or_create_client()
|
||||
response = await client.call(user, config_values, arguments)
|
||||
return response if isinstance(response, str) else json.dumps(response)
|
||||
```
|
||||
|
||||
### Dosyalar
|
||||
|
||||
| Dosya | Amaç |
|
||||
|------|---------|
|
||||
| `trustgraph-base/trustgraph/schema/services/tool_service.py` | İstek/yanıt şemaları |
|
||||
| `trustgraph-base/trustgraph/base/tool_service_client.py` | Hizmetleri çağırmak için istemci |
|
||||
| `trustgraph-base/trustgraph/base/dynamic_tool_service.py` | Hizmet uygulamasının temel sınıfı |
|
||||
| `trustgraph-flow/trustgraph/agent/react/tools.py` | `ToolServiceImpl` sınıfı |
|
||||
| `trustgraph-flow/trustgraph/agent/react/service.py` | Yapılandırma yükleme |
|
||||
|
||||
### Örnek: Şaka Hizmeti
|
||||
|
||||
`trustgraph-flow/trustgraph/tool_service/joke/`'da bir örnek hizmet:
|
||||
|
||||
```python
|
||||
class Processor(DynamicToolService):
|
||||
async def invoke(self, user, config, arguments):
|
||||
style = config.get("style", "pun")
|
||||
topic = arguments.get("topic", "")
|
||||
joke = pick_joke(topic, style)
|
||||
return f"Hey {user}! Here's a {style} for you:\n\n{joke}"
|
||||
```
|
||||
|
||||
Araç hizmeti yapılandırması:
|
||||
```json
|
||||
{
|
||||
"id": "joke-service",
|
||||
"request-queue": "non-persistent://tg/request/joke",
|
||||
"response-queue": "non-persistent://tg/response/joke",
|
||||
"config-params": [{"name": "style", "required": false}]
|
||||
}
|
||||
```
|
||||
|
||||
Araç yapılandırması:
|
||||
```json
|
||||
{
|
||||
"type": "tool-service",
|
||||
"name": "tell-joke",
|
||||
"description": "Tell a joke on a given topic",
|
||||
"service": "joke-service",
|
||||
"style": "pun",
|
||||
"arguments": [
|
||||
{"name": "topic", "type": "string", "description": "The topic for the joke"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Geriye Dönük Uyumluluk
|
||||
|
||||
Mevcut, yerleşik araç türleri, herhangi bir değişiklik olmadan çalışmaya devam etmektedir.
|
||||
`tool-service`, mevcut türlerin (`knowledge-query`, `mcp-tool`, vb.) yanı sıra yeni bir araç türüdür.
|
||||
|
||||
## Gelecek Planları
|
||||
|
||||
### Kendini Tanımlayan Hizmetler
|
||||
|
||||
Gelecekteki bir geliştirmede, hizmetlerin kendi tanımlarını yayınlamasına izin verilebilir:
|
||||
|
||||
Hizmetler, başlatıldığında, bilinen bir `tool-descriptors` konusuna yayın yapar.
|
||||
Aracılar abone olur ve araçları dinamik olarak kaydeder.
|
||||
Yapılandırma değişiklikleri olmadan gerçek bir tak ve çalıştır imkanı sağlar.
|
||||
|
||||
Bu, ilk uygulamada kapsam dışındadır.
|
||||
|
||||
## Referanslar
|
||||
|
||||
Mevcut araç uygulaması: `trustgraph-flow/trustgraph/agent/react/tools.py`
|
||||
Araç kaydı: `trustgraph-flow/trustgraph/agent/react/service.py:105-214`
|
||||
Aracı şemaları: `trustgraph-base/trustgraph/schema/services/agent.py`
|
||||
404
docs/tech-specs/tr/universal-decoder.tr.md
Normal file
404
docs/tech-specs/tr/universal-decoder.tr.md
Normal file
|
|
@ -0,0 +1,404 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Evrensel Belge Kodlayıcı"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Evrensel Belge Kodlayıcı
|
||||
|
||||
> **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.
|
||||
|
||||
## Başlık
|
||||
|
||||
`unstructured` tarafından desteklenen evrensel belge kodlayıcı — tüm kaynak konumlarını, uçtan uca izlenebilirlik için bilgi grafiği meta verisi olarak kaydederek, tam kökenli ve kütüphaneci entegrasyonu ile herhangi bir yaygın belge formatını tek bir hizmet aracılığıyla işleyin.
|
||||
|
||||
|
||||
|
||||
|
||||
## Sorun
|
||||
|
||||
TrustGraph şu anda PDF'ye özel bir çözücüye (decoder) sahip. Ek
|
||||
formatları (DOCX, XLSX, HTML, Markdown, düz metin, PPTX, vb.) desteklemek,
|
||||
ya her format için yeni bir çözücü yazmayı veya evrensel bir çıkarma
|
||||
kütüphanesini kullanmayı gerektirir. Her formatın farklı bir yapısı vardır — bazıları sayfa tabanlıyken, bazıları değildir — ve köken zinciri, çıkarılan her metin parçasının orijinal
|
||||
belgede nereden geldiğini kaydetmelidir.
|
||||
|
||||
## Yaklaşım
|
||||
## Yaklaşım
|
||||
|
||||
### Kütüphane: `unstructured`
|
||||
|
||||
`unstructured.partition.auto.partition()`'ı kullanın, bu, formatı otomatik olarak algılar
|
||||
MIME türünden veya dosya uzantısından yapılandırılmış öğeleri ayıklar
|
||||
(Başlık, AnlatıMetni, Tablo, Madde, vb.). Her öğe aşağıdaki bilgileri içerir:
|
||||
|
||||
|
||||
`page_number` (sayfa tabanlı formatlar için, örneğin PDF, PPTX)
|
||||
`element_id` (her öğe için benzersiz)
|
||||
`coordinates` (PDF'ler için sınırlayıcı kutu)
|
||||
`text` (çıkarılan metin içeriği)
|
||||
`category` (öğe türü: Başlık, AnlatıMetni, Tablo, vb.)
|
||||
|
||||
### Öğe Türleri
|
||||
|
||||
`unstructured`, belgelerden türlenmiş öğeleri çıkarır. Her öğenin bir kategorisi ve ilişkili meta verileri vardır:
|
||||
|
||||
|
||||
**Metin öğeleri:**
|
||||
`Title` — bölüm başlıkları
|
||||
`NarrativeText` — ana metin paragrafları
|
||||
`ListItem` — madde işaretli/numaralandırılmış liste öğeleri
|
||||
`Header`, `Footer` — sayfa başlıkları/altbilgileri
|
||||
`FigureCaption` — şekiller/görseller için başlıklar
|
||||
`Formula` — matematiksel ifadeler
|
||||
`Address`, `EmailAddress` — iletişim bilgileri
|
||||
`CodeSnippet` — kod blokları (markdown'dan)
|
||||
|
||||
**Tablolar:**
|
||||
`Table` — yapılandırılmış tablo verileri. `unstructured`, hem
|
||||
`element.text` (düz metin) hem de `element.metadata.text_as_html`
|
||||
(satırlar, sütunlar ve başlıklar korunmuş, tam HTML `<table>`) sağlar.
|
||||
Açık tablo yapısına sahip formatlar (DOCX, XLSX, HTML) için,
|
||||
çıkarma işlemi son derece güvenilirdir. PDF'ler için, tablo tespiti,
|
||||
düzen analizini içeren `hi_res` stratejisine bağlıdır.
|
||||
|
||||
**Görseller:**
|
||||
`Image` — düzen analizi yoluyla algılanan yerleşik görseller (gerektirir
|
||||
`hi_res` stratejisi). `extract_image_block_to_payload=True` ile,
|
||||
görüntü verilerini `element.metadata.image_base64` içinde base64 olarak döndürür.
|
||||
Görüntüden elde edilen OCR metni `element.text` içinde mevcuttur.
|
||||
|
||||
### Tablo İşleme
|
||||
|
||||
Tablolar, birincil bir çıktı türüdür. Kod çözücü, bir `Table`
|
||||
öğesiyle karşılaştığında, düz metne dönüştürmek yerine HTML yapısını korur.
|
||||
Bu, aşağı akış LLM çıkarıcısının, yapılandırılmış verileri içeren
|
||||
tablo verilerinden daha iyi bilgi almasını sağlar.
|
||||
|
||||
Sayfa/bölüm metni aşağıdaki gibi birleştirilir:
|
||||
Metin öğeleri: yeni satırlarla birleştirilmiş düz metin
|
||||
Tablo öğeleri: `text_as_html`'dan HTML tablo işaretlemesi, bir
|
||||
`<table>` işaretinin içine sarılır, böylece LLM tabloları, anlatıdan
|
||||
ayırt edebilir.
|
||||
Örneğin, bir başlık, paragraf ve tablo içeren bir sayfa şu şekilde üretilir:
|
||||
|
||||
```
|
||||
Financial Overview
|
||||
|
||||
Revenue grew 15% year-over-year driven by enterprise adoption.
|
||||
|
||||
<table>
|
||||
<tr><th>Quarter</th><th>Revenue</th><th>Growth</th></tr>
|
||||
<tr><td>Q1</td><td>$12M</td><td>12%</td></tr>
|
||||
<tr><td>Q2</td><td>$14M</td><td>17%</td></tr>
|
||||
</table>
|
||||
```
|
||||
|
||||
Bu, tablo yapısını parçalara ayırarak ve çıkarma işlemine aktararak korur.
|
||||
Bu sayede, LLM (Büyük Dil Modeli), sütun hizalamasını boşluklardan tahmin etmek yerine, doğrudan yapılandırılmış hücrelerden ilişkileri çıkarabilir.
|
||||
|
||||
|
||||
### Resim İşleme
|
||||
|
||||
|
||||
Görüntüler çıkarılır ve kütüphanede alt belgeler olarak saklanır.
|
||||
`document_type="image"` ile ve `urn:image:{uuid}` kimlik numarasına sahip. Bunlar
|
||||
`tg:Image` türündeki köken bilgisi üçlülerini içerir ve bunlar, ebeveynlerine bağlanmıştır.
|
||||
sayfa/bölüm, `prov:wasDerivedFrom` aracılığıyla. Görüntü meta verileri (koordinatlar,
|
||||
boyutlar, element_id) provenians kısmında kaydedilir.
|
||||
|
||||
**Önemli olarak, resimler, TextDocument çıktıları olarak YAYINLANMAMAKTIR.**
|
||||
Bunlar yalnızca saklanır; parçalayıcıya veya herhangi bir metin işleme
|
||||
işlem hattına gönderilmez. Bu kasıtlıdır:
|
||||
|
||||
1. Henüz bir resim işleme işlem hattı yoktur (görsel model entegrasyonu
|
||||
gelecekteki bir çalışmadır)
|
||||
2. Base64 resim verilerini veya OCR parçalarını metin çıkarma
|
||||
işlem hattına vermek, hatalı KG üçlüleri üretir.
|
||||
|
||||
Görüntüler de birleştirilmiş sayfa metninden hariç tutulur; herhangi bir `Image`
|
||||
öğesi, bir sayfa/bölüm için öğe metinlerini birleştirirken sessizce atlanır.
|
||||
Kaynak zinciri, görüntülerin var olduğunu ve belgede nerede
|
||||
bulunduğunu kaydeder, böylece gelecekte bir görüntü işleme hattı tarafından
|
||||
belgenin yeniden yüklenmesi olmadan da alınabilirler.
|
||||
|
||||
#### Gelecek çalışmalar
|
||||
|
||||
`tg:Image` varlıklarını, açıklama,
|
||||
diyagram yorumlama veya grafik veri çıkarma için bir görsel modele yönlendirin.
|
||||
Görüntü açıklamalarını, standart parçalama/çıkarma işlem hattına beslenen metin alt belgeleri olarak kaydedin.
|
||||
Çıkarılan bilgileri, kaynak görüntüleriyle köken bilgisi aracılığıyla ilişkilendirin.
|
||||
|
||||
|
||||
### Bölüm Stratejileri
|
||||
|
||||
Sayfa tabanlı formatlar (PDF, PPTX, XLSX) için, öğeler her zaman önce sayfa/slayt/sayfa içinde gruplandırılır.
|
||||
Sayfa tabanlı olmayan formatlar (DOCX, HTML, Markdown,
|
||||
vb.) için, kodlayıcının belgeyi bölümlere ayırmak için bir stratejiye ihtiyacı vardır.
|
||||
Bu, çalışma zamanında `--section-strategy` aracılığıyla yapılandırılabilir.
|
||||
|
||||
Her strateji, `unstructured` öğelerinin listesi üzerinde bir gruplama fonksiyonudur.
|
||||
Çıktı, öğe gruplarının bir listesidir; geri kalan işlem hattı (metin birleştirme, kütüphane depolama, köken, TextDocument
|
||||
oluşturma) stratejiden bağımsız olarak aynıdır.
|
||||
|
||||
|
||||
#### `whole-document` (varsayılan)
|
||||
|
||||
Tüm belgeyi tek bir bölüm olarak yayınlayın. Bölme işlemlerinin tümü, sonraki
|
||||
parçalayıcı tarafından gerçekleştirilir.
|
||||
|
||||
En basit yaklaşım, iyi bir başlangıç noktası.
|
||||
Büyük dosyalar için çok büyük TextDocument'ler oluşturabilir, ancak parçalayıcı
|
||||
bunu yönetir.
|
||||
Her bölüm için maksimum bağlam istediğinizde en iyisidir.
|
||||
|
||||
#### `heading`
|
||||
|
||||
Başlık öğelerinde (`Title`) bölün. Her bölüm, bir başlık ve bir sonraki
|
||||
aynı veya daha yüksek seviyedeki başlığa kadar olan tüm içeriktir. İç içe
|
||||
başlıklar, iç içe bölümler oluşturur.
|
||||
|
||||
Konuyla ilgili tutarlı birimler oluşturur.
|
||||
Yapılandırılmış belgeler (raporlar, kılavuzlar, teknik özellikler) için iyi çalışır.
|
||||
Çıkarma LLM'sine, içerikle birlikte başlık bağlamı sağlar.
|
||||
Başlık bulunamazsa `whole-document`'a geri döner.
|
||||
|
||||
#### `element-type`
|
||||
|
||||
Eleman türü önemli ölçüde değiştiğinde bölmeyi yapın — özellikle,
|
||||
anlatısal metin ile tablolar arasındaki geçişlerde yeni bir bölüm başlatın.
|
||||
Aynı geniş kategoriye ait ardışık öğeler (metin, metin, metin veya
|
||||
tablo, tablo) gruplandırılır.
|
||||
|
||||
Tabloları bağımsız bölümler olarak tutar
|
||||
Karışık içerikli belgeler için uygundur (veri tabloları içeren raporlar)
|
||||
Tablolar, özel bir çıkarma işlemine tabi tutulur
|
||||
|
||||
#### `count`
|
||||
|
||||
Bir bölümdeki öğe sayısını sabit bir sayıda gruplandırın. ⟦CODE_0⟧ aracılığıyla yapılandırılabilir (varsayılan: 20).
|
||||
`--section-element-count` (varsayılan: 20).
|
||||
|
||||
Basit ve öngörülebilir
|
||||
Belge yapısını dikkate almaz
|
||||
Yedek çözüm olarak veya deneme yapmak için kullanışlıdır
|
||||
|
||||
#### `size`
|
||||
|
||||
Öğeleri, bir karakter limiti dolana kadar biriktirin, ardından yeni bir bölüm başlatın. Öğeler arasındaki sınırları dikkate alır; hiçbir zaman bir öğenin ortasında bölünme yapmaz.
|
||||
⟦CODE_0⟧ gibi yer tutucuları veya ⟦URL_0⟧ gibi URL'leri çevirmeyin; bunları olduğu gibi bırakın.
|
||||
`--section-max-size` aracılığıyla yapılandırılabilir (varsayılan: 4000 karakter).
|
||||
|
||||
Yaklaşık olarak homojen bölüm boyutları üretir.
|
||||
Eleman sınırlarına saygı gösterir (aşağıdaki parçalayıcıdan farklı olarak).
|
||||
Yapı ve boyut kontrolü arasında iyi bir denge sağlar.
|
||||
Tek bir eleman limiti aşarsa, kendi bölümü haline gelir.
|
||||
|
||||
#### Sayfa tabanlı format etkileşimi
|
||||
|
||||
Sayfa tabanlı formatlar için, sayfa gruplandırması her zaman önceliklidir.
|
||||
Bölüm stratejileri, isteğe bağlı olarak, çok büyükse (örneğin, devasa bir tablo içeren bir PDF sayfası) bir sayfa *içinde* uygulanabilir, bu durum ⟦CODE_0⟧ ile kontrol edilir (varsayılan: false). Yanlış olduğunda, her sayfa boyuttan bağımsız olarak her zaman bir bölümdür.
|
||||
|
||||
`--section-within-pages` (varsayılan: false).
|
||||
|
||||
|
||||
### Biçim Algılama
|
||||
|
||||
Kodlayıcının, belgeyi ⟦CODE_0⟧'ın ⟦CODE_1⟧'ine iletebilmesi için belgenin MIME türünü bilmesi gerekir. İki yol:
|
||||
`unstructured`'ın `partition()`'i.
|
||||
|
||||
**Kütüphaneci yolu** (`document_id` ayarı): belge meta verilerini alın.
|
||||
Öncelikle kütüphaneciden belge meta verilerini alın — bu, `kind` (mime türü) değerini verir.
|
||||
Ardından belge içeriğini alın.
|
||||
İki kütüphaneci çağrısı, ancak meta veri alma işlemi hafiftir.
|
||||
**Satır içi yol** (geriye dönük uyumluluk, `data` ayarı): mesaj üzerinde herhangi bir meta veri bulunmamaktadır.
|
||||
Biçimi tespit etmek için `python-magic`'ı kullanın.
|
||||
Bu, içerik baytlarından biçimi algılamak için bir yedek yöntemdir.
|
||||
|
||||
`Document` şemasına herhangi bir değişiklik yapılmasına gerek yok — kütüphaneci zaten MIME türünü saklar.
|
||||
|
||||
|
||||
### Mimari
|
||||
|
||||
Tek bir `universal-decoder` hizmeti:
|
||||
|
||||
1. Bir `Document` mesajı alır (doğrudan veya kütüphaneci referansı aracılığıyla)
|
||||
2. Kütüphaneci yoluysa: belge meta verilerini alır (MIME türünü alır), ardından
|
||||
içeriği alır. Doğrudan yol ise: içeriğin baytlarından formatı algılar.
|
||||
3. Öğeleri çıkarmak için `partition()`'ı çağırır
|
||||
4. Öğeleri gruplandırır: sayfa tabanlı formatlar için sayfalara göre, sayfa dışı formatlar için yapılandırılmış
|
||||
bölüm stratejisine göre
|
||||
5. Her sayfa/bölüm için:
|
||||
Bir `urn:page:{uuid}` veya `urn:section:{uuid}` kimliği oluşturur
|
||||
Sayfa metnini birleştirir: anlatı düz metin olarak, tablolar HTML olarak,
|
||||
resimler atlanır
|
||||
Sayfa metnindeki her öğe için karakter ofsetlerini hesaplar
|
||||
Kütüphaneciye alt belge olarak kaydeder
|
||||
Konumsal meta verilerle birlikte kaynak üçlüleri yayınlar
|
||||
Parçalama için `TextDocument`'ı aşağı akışa gönderir
|
||||
6. Her resim öğesi için:
|
||||
Bir `urn:image:{uuid}` kimliği oluşturur
|
||||
Resim verilerini kütüphaneciye alt belge olarak kaydeder
|
||||
Kaynak üçlülerini yayınlar (sadece saklanır, aşağı akışa gönderilmez)
|
||||
|
||||
### Biçimlendirme İşlemi
|
||||
|
||||
| Biçim | MIME Tipi | Sayfa Tabanlı | Notlar |
|
||||
|----------|------------------------------------|------------|--------------------------------|
|
||||
| PDF | application/pdf | Evet | Sayfaya göre gruplandırma |
|
||||
| DOCX | application/vnd.openxmlformats... | Hayır | Bölüm stratejisi kullanır |
|
||||
| PPTX | application/vnd.openxmlformats... | Evet | Slayda göre gruplandırma |
|
||||
| XLSX/XLS | application/vnd.openxmlformats... | Evet | Sayfaya göre gruplandırma |
|
||||
| HTML | text/html | Hayır | Bölüm stratejisi kullanır |
|
||||
| Markdown | text/markdown | Hayır | Bölüm stratejisi kullanır |
|
||||
| Düz Metin | text/plain | Hayır | Bölüm stratejisi kullanır |
|
||||
| CSV | text/csv | Hayır | Bölüm stratejisi kullanır |
|
||||
| RST | text/x-rst | Hayır | Bölüm stratejisi kullanır |
|
||||
| RTF | application/rtf | Hayır | Bölüm stratejisi kullanır |
|
||||
| ODT | application/vnd.oasis... | Hayır | Bölüm stratejisi kullanır |
|
||||
| TSV | text/tab-separated-values | Hayır | Bölüm stratejisi kullanır |
|
||||
|
||||
### Kaynak Veri Meta Verileri
|
||||
|
||||
Her sayfa/bölüm öğesi, köken bilgisi olarak konum bilgisi meta verilerini kaydeder.
|
||||
`GRAPH_SOURCE` içindeki üçlüler, KG üçlülerinden tam bir izlenebilirlik sağlamaktadır.
|
||||
Kaynak belge konumlarına geri dönme.
|
||||
|
||||
#### Mevcut alanlar (zaten `derived_entity_triples` içinde)
|
||||
|
||||
`page_number` — sayfa/tablo/slayt numarası (1'den başlayarak, yalnızca sayfa tabanlı)
|
||||
`char_offset` — bu sayfa/bölümün,
|
||||
tam belge metni içindeki karakter ofseti
|
||||
`char_length` — bu sayfa/bölümün metninin karakter uzunluğu
|
||||
|
||||
#### Yeni alanlar (`derived_entity_triples`'ı genişletin)
|
||||
|
||||
`mime_type` — orijinal belge formatı (örneğin, `application/pdf`)
|
||||
`element_types` — `unstructured` öğelerinden oluşan virgülle ayrılmış liste
|
||||
bu sayfada/bölümde bulunan kategoriler (örneğin, "Başlık,AnlatıMetni,Tablo")
|
||||
`table_count` — bu sayfada/bölümdeki tablo sayısı
|
||||
`image_count` — bu sayfada/bölümdeki resim sayısı
|
||||
|
||||
Bunlar, yeni TG ad alanı özniteliklerini gerektirir:
|
||||
|
||||
```
|
||||
TG_SECTION_TYPE = "https://trustgraph.ai/ns/Section"
|
||||
TG_IMAGE_TYPE = "https://trustgraph.ai/ns/Image"
|
||||
TG_ELEMENT_TYPES = "https://trustgraph.ai/ns/elementTypes"
|
||||
TG_TABLE_COUNT = "https://trustgraph.ai/ns/tableCount"
|
||||
TG_IMAGE_COUNT = "https://trustgraph.ai/ns/imageCount"
|
||||
```
|
||||
|
||||
Görüntü URN şeması: `urn:image:{uuid}`
|
||||
|
||||
(`TG_MIME_TYPE` zaten mevcut.)
|
||||
|
||||
#### Yeni varlık türü
|
||||
|
||||
Sayfa formatı olmayan (DOCX, HTML, Markdown, vb.) belgeler için,
|
||||
kodlayıcı, belgeyi sayfalara ayırmak yerine tek bir birim olarak yayınladığında,
|
||||
varlığa yeni bir tür atanır:
|
||||
|
||||
```
|
||||
TG_SECTION_TYPE = "https://trustgraph.ai/ns/Section"
|
||||
```
|
||||
|
||||
Bu, sorgulama sırasında kökeni belirlerken bölümleri sayfalardan ayırır:
|
||||
|
||||
| Varlık | Tür | Ne zaman kullanılır |
|
||||
|----------|-----------------------------|----------------------------------------|
|
||||
| Belge | `tg:Document` | Orijinal yüklenen dosya |
|
||||
| Sayfa | `tg:Page` | Sayfaya dayalı formatlar (PDF, PPTX, XLSX) |
|
||||
| Bölüm | `tg:Section` | Sayfaya dayalı olmayan formatlar (DOCX, HTML, MD, vb.) |
|
||||
| Resim | `tg:Image` | Gömülü resimler (saklanan, işlenmeyen) |
|
||||
| Parça | `tg:Chunk` | Parçalayıcının çıktısı |
|
||||
| Alt Grafik | `tg:Subgraph` | KG çıkarma çıktısı |
|
||||
|
||||
Tür, kodlayıcı tarafından, sayfalara göre gruplandırılıp gruplandırılmadığına veya tüm belge bölümünün gönderilip gönderilmediğine bağlı olarak belirlenir. ⟦CODE_0⟧ elde edilir.
|
||||
veya tüm belge bölümünün gönderilip gönderilmediğine bağlı olarak belirlenir. `derived_entity_triples` kazanır.
|
||||
isteğe bağlı bir `section` boolean parametresi — doğru olduğunda, bu, varlığı belirtir.
|
||||
`tg:Section` olarak yazılmış, `tg:Page` yerine.
|
||||
|
||||
#### Tam kaynak zinciri
|
||||
|
||||
```
|
||||
KG triple
|
||||
→ subgraph (extraction provenance)
|
||||
→ chunk (char_offset, char_length within page)
|
||||
→ page/section (page_number, char_offset, char_length within doc, mime_type, element_types)
|
||||
→ document (original file in librarian)
|
||||
```
|
||||
|
||||
Her bağlantı, `GRAPH_SOURCE` adlı grafikte tanımlanan üçlülerden oluşan bir kümedir.
|
||||
|
||||
### Hizmet Yapılandırması
|
||||
|
||||
Komut satırı argümanları:
|
||||
|
||||
```
|
||||
--strategy Partitioning strategy: auto, hi_res, fast (default: auto)
|
||||
--languages Comma-separated OCR language codes (default: eng)
|
||||
--section-strategy Section grouping: whole-document, heading, element-type,
|
||||
count, size (default: whole-document)
|
||||
--section-element-count Elements per section for 'count' strategy (default: 20)
|
||||
--section-max-size Max chars per section for 'size' strategy (default: 4000)
|
||||
--section-within-pages Apply section strategy within pages too (default: false)
|
||||
```
|
||||
|
||||
Ayrıca standart `FlowProcessor` ve kütüphaneci kuyruk argümanlarını da içerir.
|
||||
|
||||
### Akış Entegrasyonu
|
||||
|
||||
Evrensel kod çözücü, işleme akışında mevcut PDF kod çözücünün bulunduğu aynı konumu işgal eder:
|
||||
|
||||
|
||||
```
|
||||
Document → [universal-decoder] → TextDocument → [chunker] → Chunk → ...
|
||||
```
|
||||
|
||||
Aşağıdakileri kaydeder:
|
||||
`input` tüketici (Belge şeması)
|
||||
`output` üretici (MetinBelgesi şeması)
|
||||
`triples` üretici (Üçlüler şeması)
|
||||
Kütüphaneci isteği/yanıtı (veri çekme ve alt belge depolama için)
|
||||
|
||||
### Dağıtım
|
||||
|
||||
Yeni kapsayıcı: `trustgraph-flow-universal-decoder`
|
||||
Bağımlılık: `unstructured[all-docs]` (PDF, DOCX, PPTX vb. içerir)
|
||||
Mevcut PDF çözücüyü tamamlayıcı olarak veya onun yerine çalışabilir.
|
||||
akış yapılandırması
|
||||
Mevcut PDF çözücü, ortamlar için kullanılabilir durumda kalacaktır.
|
||||
`unstructured` bağımlılıkları çok ağır.
|
||||
|
||||
### Değişiklikler
|
||||
|
||||
| Bileşen | Değişiklik |
|
||||
|------------------------------|-------------------------------------------------|
|
||||
| `provenance/namespaces.py` | `TG_SECTION_TYPE`, `TG_IMAGE_TYPE`, `TG_ELEMENT_TYPES`, `TG_TABLE_COUNT`, `TG_IMAGE_COUNT` ekleyin |
|
||||
| `provenance/triples.py` | `mime_type`, `element_types`, `table_count`, `image_count` argümanlarını ekleyin |
|
||||
| `provenance/__init__.py` | Yeni sabit değerleri dışa aktarın |
|
||||
| Yeni: `decoding/universal/` | Yeni bir kod çözücü hizmet modülü |
|
||||
| `setup.cfg` / `pyproject` | `unstructured[all-docs]` bağımlılığını ekleyin |
|
||||
| Docker | Yeni bir konteyner imajı |
|
||||
| Akış tanımları | Evrensel kod çözücüyü belge girişi olarak kullanın |
|
||||
|
||||
### Değişmeyenler
|
||||
|
||||
Chunker (MetinBelgesi'ni alır, önceki gibi çalışır)
|
||||
Aşağı akış ayıklayıcıları (Parçayı alır, değişmeden)
|
||||
Kütüphaneci (çocuk belgeleri saklar, değişmeden)
|
||||
Şema (Belge, MetinBelgesi, Parça değişmeden)
|
||||
Sorgu zamanı köken bilgisi (değişmeden)
|
||||
|
||||
## Riskler
|
||||
|
||||
`unstructured[all-docs]`, önemli bağımlılıklara sahiptir (poppler, tesseract,
|
||||
libreoffice, bazı formatlar için). Container imajı daha büyük olacaktır.
|
||||
Çözüm: OCR/ofis bağımlılıkları olmadan `[light]`'ın bir varyantını sunun.
|
||||
Bazı formatlar, zayıf metin çıkarma sonuçları verebilir (OCR uygulanmamış PDF'ler,
|
||||
OCR, karmaşık XLSX düzenleri). Çözüm: yapılandırılabilir `strategy`
|
||||
parametresi ve mevcut Mistral OCR çözücü kullanılabilir durumda.
|
||||
Yüksek kaliteli PDF OCR için.
|
||||
`unstructured` sürüm güncellemeleri, öğe meta verilerini değiştirebilir.
|
||||
Çözüm: sürümü sabitleyin, her format için çıkarma kalitesini test edin.
|
||||
307
docs/tech-specs/tr/vector-store-lifecycle.tr.md
Normal file
307
docs/tech-specs/tr/vector-store-lifecycle.tr.md
Normal file
|
|
@ -0,0 +1,307 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Vektör Depolama Yaşam Döngüsü Yönetimi"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Vektör Depolama Yaşam Döngüsü Yönetimi
|
||||
|
||||
> **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 belge, TrustGraph'ın farklı arka uç uygulamaları (Qdrant, Pinecone, Milvus) arasında vektör depolama koleksiyonlarını nasıl yönettiğini açıklamaktadır. Tasarım, sabit boyut değerleri kullanmadan farklı boyutlara sahip gömülmeleri destekleme zorluğunu ele almaktadır.
|
||||
|
||||
## Problem Tanımı
|
||||
|
||||
Vektör depoları, koleksiyonlar/indeksler oluşturulurken gömme boyutunun belirtilmesini gerektirir. Ancak:
|
||||
Farklı gömme modelleri farklı boyutlar üretir (örneğin, 384, 768, 1536).
|
||||
Boyut, ilk gömme oluşturulana kadar bilinmemektedir.
|
||||
Tek bir TrustGraph koleksiyonu, birden fazla modelden gömmeler alabilir.
|
||||
Bir boyutu (örneğin, 384) sabit kodlamak, diğer gömme boyutlarıyla uyumsuzluğa neden olur.
|
||||
|
||||
## Tasarım İlkeleri
|
||||
|
||||
1. **Gecikmeli Oluşturma**: Koleksiyonlar, koleksiyon yönetimi işlemlerinin aksine, ilk yazma sırasında talep üzerine oluşturulur.
|
||||
2. **Boyut Tabanlı İsimlendirme**: Koleksiyon adları, gömme boyutunu bir sonek olarak içerir.
|
||||
3. **Nazik Bozulma**: Var olmayan koleksiyonlara yapılan sorgular, hatalar yerine boş sonuçlar döndürür.
|
||||
4. **Çok Boyutlu Destek**: Tek bir mantıksal koleksiyon, birden fazla fiziksel koleksiyona (her biri bir boyut için bir tane) sahip olabilir.
|
||||
|
||||
## Mimari
|
||||
|
||||
### Koleksiyon İsimlendirme Kuralı
|
||||
|
||||
Vektör depolama koleksiyonları, birden fazla gömme boyutunu desteklemek için boyut soneklerini kullanır:
|
||||
|
||||
**Belge Gömme:**
|
||||
Qdrant: `d_{user}_{collection}_{dimension}`
|
||||
Pinecone: `d-{user}-{collection}-{dimension}`
|
||||
Milvus: `doc_{user}_{collection}_{dimension}`
|
||||
|
||||
**Graf Gömme:**
|
||||
Qdrant: `t_{user}_{collection}_{dimension}`
|
||||
Pinecone: `t-{user}-{collection}-{dimension}`
|
||||
Milvus: `entity_{user}_{collection}_{dimension}`
|
||||
|
||||
Örnekler:
|
||||
`d_alice_papers_384` - 384 boyutlu gömmelere sahip Alice'in makale koleksiyonu
|
||||
`d_alice_papers_768` - Aynı mantıksal koleksiyon, 768 boyutlu gömmelerle
|
||||
`t_bob_knowledge_1536` - 1536 boyutlu gömmelere sahip Bob'un bilgi grafiği
|
||||
|
||||
### Yaşam Döngüsü Aşamaları
|
||||
|
||||
#### 1. Koleksiyon Oluşturma İsteği
|
||||
|
||||
**İstek Akışı:**
|
||||
```
|
||||
User/System → Librarian → Storage Management Topic → Vector Stores
|
||||
```
|
||||
|
||||
**Davranış:**
|
||||
Kütüphaneci, `create-collection` isteklerini tüm depolama arka uçlarına yayınlar.
|
||||
Vektör depolama işlemcileri isteği kabul eder, ancak **fiziksel koleksiyonlar oluşturmaz**.
|
||||
Yanıt, başarıyla birlikte hemen döndürülür.
|
||||
Gerçek koleksiyon oluşturma, ilk yazma işlemine kadar ertelenir.
|
||||
|
||||
**Gerekçe:**
|
||||
Boyut, oluşturma zamanında bilinmemektedir.
|
||||
Yanlış boyutlara sahip koleksiyonların oluşturulması engellenir.
|
||||
Koleksiyon yönetimi mantığını basitleştirir.
|
||||
|
||||
#### 2. Yazma İşlemleri (Gecikmeli Oluşturma)
|
||||
|
||||
**Yazma Akışı:**
|
||||
```
|
||||
Data → Storage Processor → Check Collection → Create if Needed → Insert
|
||||
```
|
||||
|
||||
**Davranış:**
|
||||
1. Vektörden gömme boyutunu çıkarın: `dim = len(vector)`
|
||||
2. Boyut sonekiyle koleksiyon adını oluşturun
|
||||
3. Belirli o boyuta sahip koleksiyonun var olup olmadığını kontrol edin
|
||||
4. Yoksa:
|
||||
Doğru boyuta sahip bir koleksiyon oluşturun
|
||||
Kaydı tutun: `"Lazily creating collection {name} with dimension {dim}"`
|
||||
5. Gömme değerini, boyutuna özel koleksiyona ekleyin
|
||||
|
||||
**Örnek Senaryo:**
|
||||
```
|
||||
1. User creates collection "papers"
|
||||
→ No physical collections created yet
|
||||
|
||||
2. First document with 384-dim embedding arrives
|
||||
→ Creates d_user_papers_384
|
||||
→ Inserts data
|
||||
|
||||
3. Second document with 768-dim embedding arrives
|
||||
→ Creates d_user_papers_768
|
||||
→ Inserts data
|
||||
|
||||
Result: Two physical collections for one logical collection
|
||||
```
|
||||
|
||||
#### 3. Sorgu İşlemleri
|
||||
|
||||
**Sorgu Akışı:**
|
||||
```
|
||||
Query Vector → Determine Dimension → Check Collection → Search or Return Empty
|
||||
```
|
||||
|
||||
**Davranış:**
|
||||
1. Sorgu vektöründen boyutu çıkarın: `dim = len(vector)`
|
||||
2. Boyut sonekiyle koleksiyon adını oluşturun
|
||||
3. Koleksiyonun var olup olmadığını kontrol edin
|
||||
4. Varsa:
|
||||
Benzerlik araması yapın
|
||||
Sonuçları döndürün
|
||||
5. Yoksa:
|
||||
Kaydı tutun: `"Collection {name} does not exist, returning empty results"`
|
||||
Boş bir liste döndürün (hata yükseltilmez)
|
||||
|
||||
**Aynı Sorguda Birden Fazla Boyut:**
|
||||
Sorgu farklı boyutlardaki vektörler içeriyorsa
|
||||
Her boyut, ilgili koleksiyonunu sorgular
|
||||
Sonuçlar birleştirilir
|
||||
Eksik koleksiyonlar atlanır (hata olarak değerlendirilmez)
|
||||
|
||||
**Gerekçe:**
|
||||
Boş bir koleksiyonu sorgulamak geçerli bir kullanım durumudur
|
||||
Boş sonuçlar döndürmek anlamsal olarak doğrudur
|
||||
Sistem başlatılırken veya veri yüklemesinden önce hataları önler
|
||||
|
||||
#### 4. Koleksiyon Silme
|
||||
|
||||
**Silme Akışı:**
|
||||
```
|
||||
Delete Request → List All Collections → Filter by Prefix → Delete All Matches
|
||||
```
|
||||
|
||||
**Davranış:**
|
||||
1. Önek kalıbını oluştur: `d_{user}_{collection}_` (sonundaki alt çizgiye dikkat edin)
|
||||
2. Vektör deposundaki tüm koleksiyonları listele
|
||||
3. Öneğe uyan koleksiyonları filtrele
|
||||
4. Tüm eşleşen koleksiyonları sil
|
||||
5. Her silme işlemini kaydet: `"Deleted collection {name}"`
|
||||
6. Özet günlük: `"Deleted {count} collection(s) for {user}/{collection}"`
|
||||
|
||||
**Örnek:**
|
||||
```
|
||||
Collections in store:
|
||||
- d_alice_papers_384
|
||||
- d_alice_papers_768
|
||||
- d_alice_reports_384
|
||||
- d_bob_papers_384
|
||||
|
||||
Delete "papers" for alice:
|
||||
→ Deletes: d_alice_papers_384, d_alice_papers_768
|
||||
→ Keeps: d_alice_reports_384, d_bob_papers_384
|
||||
```
|
||||
|
||||
**Gerekçe:**
|
||||
Tüm boyut varyantlarının tamamen temizlenmesini sağlar.
|
||||
Desen eşleştirme, yanlışlıkla ilgili olmayan koleksiyonların silinmesini önler.
|
||||
Kullanıcı açısından atomik bir işlem (tüm boyutlar birlikte silinir).
|
||||
|
||||
## Davranışsal Özellikler
|
||||
|
||||
### Normal İşlemler
|
||||
|
||||
**Koleksiyon Oluşturma:**
|
||||
✓ Hemen başarı döndürür.
|
||||
✓ Herhangi bir fiziksel depolama alanı ayrılmaz.
|
||||
✓ Hızlı işlem (arka uç G/Ç yok).
|
||||
|
||||
**İlk Yazma:**
|
||||
✓ Doğru boyuta sahip koleksiyon oluşturur.
|
||||
✓ Koleksiyon oluşturma ek yükü nedeniyle biraz daha yavaştır.
|
||||
✓ Aynı boyuta yapılan sonraki yazmalar hızlıdır.
|
||||
|
||||
**Herhangi Bir Yazmadan Önce Sorgular:**
|
||||
✓ Boş sonuçlar döndürür.
|
||||
✓ Herhangi bir hata veya istisna oluşmaz.
|
||||
✓ Sistem kararlı kalır.
|
||||
|
||||
**Farklı Boyutlara Yazma:**
|
||||
✓ Otomatik olarak her boyut için ayrı koleksiyonlar oluşturur.
|
||||
✓ Her boyut kendi koleksiyonunda izole edilir.
|
||||
✓ Herhangi bir boyut çakışması veya şema hatası oluşmaz.
|
||||
|
||||
**Koleksiyon Silme:**
|
||||
✓ Tüm boyut varyantlarını kaldırır.
|
||||
✓ Tam temizleme.
|
||||
✓ Herhangi bir yetim koleksiyon kalmaz.
|
||||
|
||||
### Sınır Durumlar
|
||||
|
||||
**Çoklu Gömülü Model:**
|
||||
```
|
||||
Scenario: User switches from model A (384-dim) to model B (768-dim)
|
||||
Behavior:
|
||||
- Both dimensions coexist in separate collections
|
||||
- Old data (384-dim) remains queryable with 384-dim vectors
|
||||
- New data (768-dim) queryable with 768-dim vectors
|
||||
- Cross-dimension queries return results only for matching dimension
|
||||
```
|
||||
|
||||
**Eşzamanlı İlk Yazma İşlemleri:**
|
||||
```
|
||||
Scenario: Multiple processes write to same collection simultaneously
|
||||
Behavior:
|
||||
- Each process checks for existence before creating
|
||||
- Most vector stores handle concurrent creation gracefully
|
||||
- If race condition occurs, second create is typically idempotent
|
||||
- Final state: Collection exists and both writes succeed
|
||||
```
|
||||
|
||||
**Boyutların Taşınması:**
|
||||
```
|
||||
Scenario: User wants to migrate from 384-dim to 768-dim embeddings
|
||||
Behavior:
|
||||
- No automatic migration
|
||||
- Old collection (384-dim) persists
|
||||
- New collection (768-dim) created on first new write
|
||||
- Both dimensions remain accessible
|
||||
- Manual deletion of old dimension collections possible
|
||||
```
|
||||
|
||||
**Boş Koleksiyon Sorguları:**
|
||||
```
|
||||
Scenario: Query a collection that has never received data
|
||||
Behavior:
|
||||
- Collection doesn't exist (never created)
|
||||
- Query returns empty list
|
||||
- No error state
|
||||
- System logs: "Collection does not exist, returning empty results"
|
||||
```
|
||||
|
||||
## Uygulama Notları
|
||||
|
||||
### Depolama Arka Ucu Özellikleri
|
||||
|
||||
**Qdrant:**
|
||||
Varlık kontrolleri için `collection_exists()` kullanılır.
|
||||
Silme sırasında listeleme için `get_collections()` kullanılır.
|
||||
Koleksiyon oluşturma `VectorParams(size=dim, distance=Distance.COSINE)` gerektirir.
|
||||
|
||||
**Pinecone:**
|
||||
Varlık kontrolleri için `has_index()` kullanılır.
|
||||
Silme sırasında listeleme için `list_indexes()` kullanılır.
|
||||
İndeks oluşturma, "hazır" durumunu bekleme gerektirir.
|
||||
Sunucusuz yapılandırma, bulut/bölge ile yapılır.
|
||||
|
||||
**Milvus:**
|
||||
Doğrudan sınıflar (`DocVectors`, `EntityVectors`), yaşam döngüsünü yönetir.
|
||||
Performans için dahili önbellek `self.collections[(dim, user, collection)]`.
|
||||
Koleksiyon adları, yalnızca alfanümerik ve alt çizgi içeren şekilde temizlenir.
|
||||
Otomatik artan kimliklere sahip şema desteği.
|
||||
|
||||
### Performans Hususları
|
||||
|
||||
**İlk Yazma Gecikmesi:**
|
||||
Koleksiyon oluşturma nedeniyle ek yük.
|
||||
Qdrant: ~100-500ms
|
||||
Pinecone: ~10-30 saniye (sunucusuz sağlama)
|
||||
Milvus: ~500-2000ms (indekslemeyi içerir)
|
||||
|
||||
**Sorgu Performansı:**
|
||||
Varlık kontrolü, minimum ek yük ekler (~1-10ms).
|
||||
Koleksiyon mevcut olduğunda performans üzerinde etkisi yoktur.
|
||||
Her boyut koleksiyonu, bağımsız olarak optimize edilir.
|
||||
|
||||
**Depolama Yükü:**
|
||||
Her koleksiyon için minimum meta veri.
|
||||
Ana yük, boyut başına depolamadır.
|
||||
Dengeleme: Depolama alanı ile boyut esnekliği.
|
||||
|
||||
## Gelecek Hususlar
|
||||
|
||||
**Otomatik Boyut Birleştirme:**
|
||||
Kullanılmayan boyut varyantlarını belirlemek ve birleştirmek için arka plan işlemi eklenebilir.
|
||||
Yeniden gömme veya boyut azaltma gerektirecektir.
|
||||
|
||||
**Boyut Keşfi:**
|
||||
Bir koleksiyon için kullanılan tüm boyutları listelemek için bir API açılabilir.
|
||||
Yönetim ve izleme için kullanışlıdır.
|
||||
|
||||
**Varsayılan Boyut Tercihi:**
|
||||
Her koleksiyon için "birincil" boyut izlenebilir.
|
||||
Boyut bağlamı kullanılamadığında sorgular için kullanılır.
|
||||
|
||||
**Depolama Kotaları:**
|
||||
Her koleksiyon için boyut limitleri gerekebilir.
|
||||
Boyut varyantlarının yayılmasını önler.
|
||||
|
||||
## Geçiş Notları
|
||||
|
||||
**Ön Boyut-Sonek Sisteminden:**
|
||||
Eski koleksiyonlar: `d_{user}_{collection}` (boyut soneki yok)
|
||||
Yeni koleksiyonlar: `d_{user}_{collection}_{dim}` (boyut soneki ile)
|
||||
Otomatik geçiş yok - eski koleksiyonlar erişilebilir durumda kalır.
|
||||
Gerekirse, manuel bir geçiş betiği düşünülmelidir.
|
||||
Her iki adlandırma şeması de aynı anda kullanılabilir.
|
||||
|
||||
## Referanslar
|
||||
|
||||
Koleksiyon Yönetimi: `docs/tech-specs/collection-management.md`
|
||||
Depolama Şeması: `trustgraph-base/trustgraph/schema/services/storage.py`
|
||||
Kütüphaneci Hizmeti: `trustgraph-flow/trustgraph/librarian/service.py`
|
||||
Loading…
Add table
Add a link
Reference in a new issue