mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 00:46:22 +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
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`
|
||||
Loading…
Add table
Add a link
Reference in a new issue