apunkt/trustgraph
1
0
Fork 0
mirror of https://github.com/trustgraph-ai/trustgraph.git synced 2026-07-09 13:22:10 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

add more docs

Browse source 
Signed-off-by: Jenkins, Kenneth Alexander <kjenkins60@gatech.edu>
This commit is contained in:
Jenkins, Kenneth Alexander 2026-04-10 12:22:20 -04:00
parent 23e18cd562
commit 835acaa70e
No known key found for this signature in database
94 changed files with 60854 additions and 1126 deletions
Download patch file Download diff file Expand all files Collapse all files

691
docs/tech-specs/graphrag-performance-optimization.sw.md
View file

@ -1,119 +1,421 @@
# GraphRAG Utendaji Uboreshaji Maelezo ya Kiufundi
# Vipimo vya Ufanisi wa GraphRAG kwa Uboreshaji wa Kawaida
## Muhtasari
## Maelezo
Maelezo haya yanaeleza uboreshaji kamili wa utendaji wa algorithm ya GraphRAG (Graph Retrieval-Augmented Generation) katika TrustGraph. Matumizi ya sasa yana vizuizi vya utendaji muhimu ambavyo hu limit scalability na muda wa majibu. Maelezo haya yanashughulikia maeneo manne makuu ya uboreshaji:
Hati hii inaeleza uboreshaji wa kina wa utendaji wa algorithm ya GraphRAG (Graph Retrieval-Augmented Generation) katika TrustGraph. Utaratibu wa sasa una matatizo makubwa ya utendaji ambayo yanapunguza uwezo wa kupanuka na wakati wa majibu. Hati hii inashughulikia maeneo manne makuu ya uboreshaji:
1. **Uboreshaji wa Ufuatiliaji wa Grafu**: Ondoa maswali ya hivi karibuni ya database na utumie utafiti wa kikundi.
2. **Uboreshaji wa Utatuzi wa Labe**: Badilisha upataji wa mlolongo wa lebo kwa operesheni za sambamba/kikundi.
3. **Uboreshaji wa Mkakati wa Kumbukumbu**: Implement caching kwa akili pamoja na uondoshaji wa LRU na utaratibu wa kupata data.
4. **Uboreshaji wa Maswali**: Ongeza kumbukumbu ya matokeo na caching ya embeddings ili kuboresha muda wa majibu.
1. **Uboreshaji wa Ufuatiliaji wa Grafu**: Ondoa maswali ya hivi karibuni ya hivi karibuni ya hivi karibuni na tekeleza utafutaji wa grafu wa kikundi
2. **Uboreshaji wa Utatuzi wa Lebo**: Badilisha upekuzi wa hivi karibuni wa lebo na shughuli za sambamba/za kikundi
3. **Uboreshaji wa Mkakati wa Kumbukumbu**: Tekeleza kumbukumbu mahiri na kuondoa kwa LRU na utabiri
4. **Uboreshaji wa Ulipaji**: Ongeza kumbukumbu ya matokeo na kumbukumbu ya uingizaji kwa kuboresha wakati wa majibu
## Malengo
## Lengo
- **Punguza Idadi ya Maswali ya Database**: Punguza kwa 50-80% jumla ya maswali ya database kupitia kikundi na caching.
- **Boresha Muda wa Majibu**: Lenga ujenzi wa subgraph wa haraka 3-5x na utatuzi wa lebo wa haraka 2-3x.
- **Boresha Scalability**: Unga grafu kubwa zaidi za maarifa na usimamizi bora wa kumbukumbu.
- **Dumishe Usahihi**: Dumishe utendakazi na ubora wa matokeo ya GraphRAG iliyopo.
- **Wezesha Ujazo**: Boresha uwezo wa usindikaji sambamba kwa maombi mengi sambamba.
- **Punguza Uwepo wa Kumbukumbu**: Implement miundo ya data na usimamizi wa kumbukumbu bora.
- **Ongeza Ufuatiliaji**: Jumuisha metriki za utendaji na uwezo wa ufuatiliaji.
- **Hakikisha Utiaji Njia**: Ongeza utunzaji sahihi wa makosa na mitaratibu ya muda.
**Punguza Kiasi cha Maswali ya Hivi Karibuni**: Pata kupunguzwa kwa 50-80% katika jumla ya maswali ya hivi karibuni kupitia kikundi na kumbukumbu
**Boresha Wakati wa Majibu**: Lenga ujenzi wa subgrafu wa haraka 3-5x na utatuzi wa lebo wa haraka 2-3x
**Boresha Uwezo wa Kupanuka**: Unga grafu kubwa za maarifa na usimamizi bora wa kumbukumbu
**Dumishe Usahihi**: Dumishe utendaji na ubora wa matokeo ya GraphRAG iliyopo
**Wezesha Ulinganifu**: Boresha uwezo wa usindikaji sambamba kwa maombi mengi ya sambamba
**Punguza Uzito wa Kumbukumbu**: Tekeleza miundo ya data na usimamizi wa kumbukumbu bora
**Ongeza Ufuatiliaji**: Jumuisha metriki za utendaji na uwezo wa ufuatiliaji
**Hakikisha Utendaji**: Ongeza ushughulikiaji sahihi wa makosa na mitambo ya muda
## Asili
Matumizi ya sasa ya GraphRAG katika `trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py` ina masuala muhimu ya utendaji ambayo yanaathiri sana scalability ya mfumo:
Utaratibu wa sasa wa GraphRAG katika `trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py` una masuala muhimu ya utendaji ambayo yanaathiri sana uwezo wa kupanuka wa mfumo:
### Matatizo ya Sasa ya Utendaji
**1. Ufuatiliaji Usio na Ufanisi wa Grafu (`follow_edges` function, mistari 79-127)**
- Hufanya maswali 3 tofauti ya database kwa kila entiti kwa kila ngazi.
- Mfumo wa swali: maswali yanayozingatia mada, yanayozingatia predikat, na yanayozingatia kitu kwa kila entiti.
- Hakuna kikundi: Kila swali hutumia entiti moja tu wakati mmoja.
- Hakuna ugunduzi wa mzunguko: Inaweza kutembelea nodi sawa mara nyingi.
- Matumizi ya recursive bila kumbukumbu hupelekea utata wa kielelekeo.
- Utata wa muda: O(entities × max_path_length × triple_limit³)
**1. Ufuatiliaji Usio na Ufanisi wa Grafu (kitendaji cha `follow_edges`, mistari 79-127)**
Hufanya maswali 3 tofauti ya hivi karibuni kwa kila kitu kwa kila kiwango cha kina
Mfumo wa swali: maswali ya msingi ya mada, maswali ya msingi ya tabia, na maswali ya msingi ya kitu kwa kila kitu
Hakuna kikundi: Kila swali huchakata kitu kimoja wakati mmoja
Hakuna utambuzi wa mzunguko: Inaweza kurudi kwenye nodi sawa mara nyingi
Utaratibu wa hivi karibuni bila kumbukumbu husababisha utata wa kielelekevu
Utata wa wakati: O(vitabu × urefu_max_ya_njia × triple_limit³)
**2. Utatuzi Mfululizo wa Labe (`get_labelgraph` function, mistari 144-171)**
- Hufanya usindikaji wa kila sehemu ya triple (mada, predikat, kitu) mfululizo.
- Kila wito wa `maybe_label` inaweza kusababisha swali la database.
- Hakuna utekelezaji au kikundi sambamba wa maswali ya lebo.
- Hupelekea hadi simu 3 × subgraph_size za database.
**2. Utatuzi wa Hivi Karibuni wa Lebo (kitendaji cha `get_labelgraph`, mistari 144-171)**
Huchakata kila sehemu ya tatu (mhusika, tabia, kitu) kwa hivi karibuni
Kila wito wa `maybe_label` inaweza kusababisha swali la hivi karibuni la hivi karibuni
Hakuna utekelezaji sambamba au kikundi cha maswali ya lebo
Hupelekea hadi simu 3 × ya hivi karibuni ya hivi karibuni ya hivi karibuni.
**3. Mkakati wa Msingi wa Kumbukumbu (`maybe_label` function, mistari 62-77)**
- Cache rahisi ya kamusi bila mipaka ya saizi au TTL.
- Hakuna sera ya kuondolewa kwa cache hupelekea ukuaji usio na kikomo wa kumbukumbu.
- Upotezaji wa cache husababisha maswali ya database ya kibinafsi.
- Hakuna kupata data au uongezaji mahiri wa cache.
**3. Mkakati wa Kumbukumbu wa Msingi (kitendaji cha `maybe_label`, mistari 62-77)**
Kumbukumbu rahisi ya kamusi bila mipaka ya saizi au TTL
Hakuna sera ya kuondoa kumbukumbu inayosababisha ukuaji usio na kikomo wa kumbukumbu
Kupoteza kumbukumbu hutuma maswali ya hivi karibuni ya hivi karibuni ya hivi karibuni
Hakuna utabiri au uongezaji mahiri wa kumbukumbu
**4. Mfumo Usio bora wa Maswali**
- Maswali ya ufanano wa vector ya entiti hayahifadhiwi kati ya maombi sawa.
- Hakuna kumbukumbu ya matokeo kwa mifumo ya swali iliyorudiwa.
- Uboreshaji wa maswali unokosekana kwa mifumo ya kawaida ya ufikiaji.
**4. Mfumo Usio na Ufanisi wa Maswali**
Maswali ya ufanano wa vekta ya kitu hayahifadhiwi kati ya maombi sawa
Hakuna kumbukumbu ya matokeo kwa mifumo ya swali iliyorudiwa
Uboreshaji wa swali unaokosekana kwa mifumo ya kawaida ya ufikiaji
**5. Masuala Muhimu ya Muda wa Kitu (`rag.py:96-102`)**
- **Kitu cha GraphRag kinaundwa kila maombi**: Instance mpya huundwa kwa kila swali, na kupoteza faida zote za cache.
- **Kitu cha swali kina muda mfupi sana**: Huundwa na kuharibiwa ndani ya utekelezaji wa swali moja (mistari 201-207).
- **Cache ya lebo huwezeshwa kila maombi**: Uongezaji wa cache na maarifa yaliyokusanywa hayapotei kati ya maombi.
- **Utoaji wa upya wa mteja**: Wateja wa database wanaweza kuanzishwa tena kwa kila maombi.
- **Uboreshaji usio na maombi**: Haiwezi kufaidika na mifumo ya swali au kushiriki matokeo.
**5. Masuala Muhimu ya Maisha ya Kitu (`rag.py:96-102`)**
**Kitu cha GraphRag kinaundwa kwa kila ombi**: Toleo jipya huundwa kwa kila swali, na kupoteza faida zote za kumbukumbu
**Kitu cha swali kina muda mfupi sana**: Huundwa na kuharibiwa ndani ya utekelezaji wa swali moja (mistari 201-207)
**Kumbukumbu ya lebo inarejeshwa kwa kila ombi**: Uongezaji wa kumbukumbu na maarifa yaliyokusanywa yanapotea kati ya maombi
**Upeo wa upya wa mteja**: Wateja wa hivi karibuni wanaweza kuanzishwa tena kwa kila ombi
**Hakuna uboreshaji wa kati ya maombi**: Haiwezi kufaidika na mifumo ya swali au ushirikishwaji wa matokeo
### Uchambuzi wa Athari za Utendaji
### Uchambuzi wa Athari ya Utendaji
Jalada la mbaya zaidi linalowezekana kwa swali la kawaida:
- **Uongezaji wa Entiti**: Swali 1 la ufanano wa vector
- **Ufuatiliaji wa Grafu**: entities × max_path_length × 3 × maswali ya triple_limit
- **Utatuzi wa Labe**: maswali ya lebo ya `subgraph_size` × 3 ya kibinafsi
Hali mbaya zaidi ya sasa kwa swali la kawaida:
**Upekuzi wa Kitu**: swali 1 la ufanano wa vekta
**Ufuatiliaji wa Grafu**: vitu × urefu_max_ya_njia × 3 × maswali ya hivi karibuni ya hivi karibuni ya hivi karibuni
**Utatuzi wa Lebo**: maswali ya hivi karibuni ya hivi karibuni ya hivi karibuni ya subgrafu_size × 3
Kwa vigezo vya chagu msingi (entities 50, urefu wa njia 2, kikomo cha triple 30, saizi ya subgraph 150):
- **Maswali ya chini**: 1 + (50 × 2 × 3 × 30) + (150 × 3) = **maswali 9,451 ya database**
- **Muda wa majibu**: 15-30 sekunde kwa grafu za ukubwa wa wastani
- **Matumizi ya kumbukumbu**: Ukuaji usio na kikomo wa cache baada ya muda
- **Ufanisi wa cache**: 0% - caches huwezeshwa kila maombi
- **Utoaji wa kitu**: Kitu cha GraphRag + Kitu cha swali kinaundwa/kuharibiwa kwa kila maombi
Kwa vigezo chache (vitu 50, urefu wa njia 2, kikomo cha triplet 30, saizi ya subgraph 150):
**Maswali ya chini**: 1 + (50 × 2 × 3 × 30) + (150 × 3) = **maswali 9,451 ya hifadhidata**
**Wakati wa majibu**: Sekunde 15-30 kwa vielelezo vya saizi ya wastani
**Matumizi ya kumbukumbu**: Ukubwa wa kumbukumbu unaoongezeka bila kikomo baada ya muda
**Ufanisi wa kumbukumbu**: 0% - kumbukumbu hurejeshwa kila ombi
**Utozo wa kuunda vitu**: Vitu vya GraphRag + Query vinaundwa/vinaharibiwa kwa kila ombi
Maelezo haya yanashughulikia pengo hizi kwa kutumia maswali ya kikundi, caching kwa akili, na usindikaji sambamba. Kwa kuongeza ufanisi wa mifumo ya swali na ufikiaji wa data, TrustGraph inaweza:
- Unga grafu kubwa za maarifa na milioni ya entiti
- Kutoa muda wa majibu wa chini ya sekunde kwa swali la kawaida
- Kushughulikia maombi ya GraphRAG ya sambamba mamia
- Kuongezeka kwa ufanisi na saizi na utata wa grafu
Maelezo haya yanaangazia pengo hizi kwa kutumia maswali ya kikundi, uhifadhi mahiri, na usindikaji wa sambamba. Kwa kuboresha mifumo ya maswali na ufikiaji wa data, TrustGraph inaweza:
Kusaidia vielelezo vya maarifa vya kiwango cha shirika na mamilioni ya vitu
Kutoa wakati wa majibu ya chini ya sekunde kwa maswali ya kawaida
Kushughulikia maombi mamia ya GraphRAG kwa wakati mmoja
Kuongezeka kwa ufanisi na saizi na utata wa vielelezo
## Ubunifu wa Kiufundi
## Muundo wa Kiufundi
### Usanifu
Uboreshaji wa utendaji wa GraphRAG unahitaji vipengele hivi vya kiufundi:
#### 1. **Urekebishaji wa Usanifu wa Muda wa Kitu**
- **Fanya GraphRag kuwa wa muda mrefu**: Hamisha instance ya GraphRag hadi ngazi ya Processor ili kudumu katika maombi.
- **Dumishe caches**: Dumishe cache ya lebo, cache ya embedding, na cache ya matokeo ya swali kati ya maombi.
- **Boresha Kitu cha Swali**: Rekebisha Swali kama muktadha wa utekelezaji nyepesi, sio kontena ya data.
- **Usaidizi wa miunganisho**: Dumishe miunganisho ya mteja wa database katika maombi.
#### 1. **Urekebishaji wa Usanifu wa Muda wa Vitu**
**Fanya GraphRag iwe na muda mrefu**: Hamisha mfano wa GraphRag hadi ngazi ya Processor ili kudumu katika maombi
**Ondoa kumbukumbu**: Dumishe kumbukumbu ya lebo, kumbukumbu ya uingizaji, na kumbukumbu ya matokeo ya swali kati ya maombi
**Boresha kitu cha Swali**: Rekebisha Swali ili iwe mfumo wa utekelezaji mwepesi, sio chombo cha data
**Usaidizi wa muunganisho**: Dumishe miunganisho ya mteja wa hifadhidata katika maombi
Moduli: `trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` (imebadilishwa)
Moduli: `trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` (iliyorekebishwa)
#### 2. **Njia Iliyo bora ya Ufuatiliaji wa Grafu**
- Badilisha `follow_edges` ya recursive na utafutaji wa msingi wa upana wa iterative
- Implement utunzaji wa kikundi wa entiti katika kila ngazi ya utafutaji
- Ongeza ugunduzi wa mzunguko kwa kufuatilia nodi zilizotembelea
- Jumuisha kumalizika mapema wakati mipaka inafikiwa
#### 2. **Injini Iliyoboreshwa ya Ufuatiliaji wa Vielelezo**
Badilisha `follow_edges` ya kurudia na utafutaji wa upana wa mara kwa mara
Tekeleza usindikaji wa kikundi wa vitu katika kila ngazi ya ufuatiliaji
Ongeza ugunduzi wa mzunguko kwa kufuatilia nodi zilizotembelewa
Jumuisha kumalizika mapema wakati mipaka inafikiwa
Moduli: `trustgraph-flow/trustgraph/retrieval/graph_rag/optimized_traversal.py`
#### 3. **Mfumo Sambamba wa Utatuzi wa Labe**
- Kundi maswali ya lebo kwa entiti nyingi wakati mmoja
- Implement mifumo ya async/kusubiri kwa ufikiaji wa sambamba wa database
- Ongeza kupata data mahiri kwa mifumo ya kawaida ya lebo
- Jumusha mikakati ya uongezaji wa lebo
#### 3. **Mfumo wa Ufafanuzi wa Lebo Sambamba**
Kikundi maswali ya lebo kwa vitu vingi kwa wakati mmoja
Tekeleza mifumo ya async/await kwa ufikiaji sambamba wa hifadhidata
Ongeza upakiaji wa akili kwa mifumo ya kawaida ya lebo
Jumuisha mikakati ya ukausha wa kumbukumbu ya lebo
Moduli: `trustgraph-flow/trustgraph/retrieval/graph_rag/label_resolution.py`
Moduli: `trustgraph-flow/trustgraph/retrieval/graph_rag/label_resolver.py`
#### 4. **Mkakati wa Kina wa Kumbukumbu**
- Implement cache ya LRU na TTL
- Zana za ufuatiliaji wa utendaji wa cache
- Usalama wa maswali na utunzaji wa rasilimali
#### 4. **Nafasi ya Kumbukumbu ya Lebo Iliyohifadhiwa**
Kumbukumbu ya LRU na TTL fupi kwa lebo pekee (dakika 5) ili kusawazisha utendaji na uthabiti
Fuatilia metriki na uwiano wa hit
**Hakuna ukaushaji wa uingizaji**: Tayari umehifadhiwa kwa kila swali, hakuna faida ya kati ya maswali
**Hakuna ukaushaji wa matokeo ya swali**: Kutokana na wasiwasi wa uthabiti wa mabadiliko ya vielelezo
**Mbinu ya Ufuatiliaji ya Kumbukumbu**:
Moduli: `trustgraph-flow/trustgraph/retrieval/graph_rag/cache_manager.py`
#### 5. **Mfumo wa Uboreshaji wa Swali**
Uchambuzi na mapendekezo ya uboreshaji wa mfumo wa swali
Mratibu wa swali la kikundi kwa ufikiaji wa hifadhidata
Uunganisho wa mabwawa na usimamaji wa muda wa swali
Ufuatiliaji wa utendaji na ukusanyaji wa metriki
Moduli: `trustgraph-flow/trustgraph/retrieval/graph_rag/query_optimizer.py`
### Mifano ya Data
#### Hali Iliyoboreshwa ya Ufuatiliaji wa Vielelezo
Injini ya ufuatiliaji inahifadhi hali ili kuepuka shughuli za ziada:
```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]
```
Mbinu hii inaruhusu:
Uchunguzi wa haraka wa mzunguko kupitia kufuatilia vitu vilivyotembelewa
Maandalizi ya maswali kwa wingi katika kila ngazi ya utafutaji
Usimamizi wa hali unaohifadhi kumbukumbu
Kukomesha mapema wakati mipaka ya ukubwa inafikiwa
#### Muundo Ulioboreshwa wa Kumbukumbu (Cache)
```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
```
#### Muundo wa Maswali ya Kundi
```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
#### API mpya:
**API ya GraphTraversal**
```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]]
```
**API ya Utatuzi wa Lebo za Kundi**
```python
async def resolve_labels_batch(
entities: List[str],
cache_manager: CacheManager
) -> Dict[str, str]
```
**API ya Usimamizi wa Kumbukumbu (Cache)**
```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
```
#### API Zilizobadilishwa:
**GraphRag.query()** - Imeboreshwa kwa matumizi bora:
Ongeza parameter ya `cache_manager` kwa udhibiti wa kumbukumbu.
Jumuisha thamani ya kurudiwa ya `performance_metrics`.
Ongeza parameter ya `query_timeout` kwa uaminifu.
**Darasa la `Query`** - Limepangwa upya kwa usindikaji wa jumla:
Badilisha usindikaji wa kila kitu kwa shughuli za jumla.
Ongeza menejeri wa muktadha wa async kwa usafi wa rasilimali.
Jumuisha miongozo ya maendeleo kwa operesheni za muda mrefu.
### Maelezo ya Utendaji
#### Awamu ya 0: Urekebishaji Muhimu wa Muundo na Muda wa Maisha
**Utendaji Sasa Usiofaa:**
```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
```
**Muundo Ulioboreshwa na Umeundwa Kudumu:**
```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)
```
Mabadiliko haya ya usanifu yanatoa:
**Punguuzo la 10-20% la maswali ya hifadhidata** kwa grafu zilizo na uhusiano wa kawaida (kulinganisha na 0% kwa sasa)
**Kuondolewa kwa gharama ya ziada ya uundaji wa vitu** kwa kila ombi
**Uunganishaji wa kudumu na matumizi ya upya** kwa wateja
**Uboreshaji wa ombi hadi ombi** ndani ya vipindi vya muda wa kuhifadhi (TTL)
**Kizuia Muhimu cha Utangamano wa Kumbukumbu:**
Uhifadhi wa muda mrefu unaweza kusababisha data kuwa potofu wakati vitu/lebo zinafutwa au kubadilishwa katika grafu iliyoko. Kumbukumbu ya LRU yenye TTL hutoa usawa kati ya faida za utendaji na usafi wa data, lakini haiwezi kuchunguza mabadiliko ya grafu ya wakati halisi.
#### Awamu ya 1: Uboreshaji wa Ufuatiliaji wa Grafu
**Matatizo ya Utendaji wa Sasa:**
```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)
```
**Utekelezaji Ulioboreshwa:**
```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
```
#### Awamu ya 2: Utatuzi wa Lebo Sambamba
**Utendaji wa Sasa wa Mfululizo:**
```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
```
**Utekelezaji Ufuatao Mfumo Sambamba Uliorekebishwa:**
```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
]
```
#### Awamu ya 3: Mkakati wa Kupanua Data (Caching) wa Juu
**Kupanua Data (Cache) la LRU pamoja na TTL:**
```python
class LRUCacheWithTTL:
def __init__(self, max_size: int, default_ttl: int = 3600):
@ -149,92 +451,179 @@ class LRUCacheWithTTL:
self.access_times[key] = time.time()
```
#### 5. **Uboreshaji wa Swali na Ufuatiliaji**
- **Ukusanyaji wa Metriki za Utendaji**:
- **Upekuzi na Muda**:
- **Usimamizi wa Rasilimali**:
- **Ufuatiliaji**:
#### Awamu ya 4: Ubora wa Ufuatiliaji na Ufuatiliaji
**Muda wa Majibu**:
- Ufuatiliaji wa utendaji wa GraphRAG
- Ufuatiliaji wa maswali ya database
- Ufuatiliaji wa matumizi ya kumbukumbu
- Ufuatiliaji wa utekelezaji wa maombi
**Ukusanyaji wa Vipimo vya Utendaji:**
```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
```
## Mkakati wa Kujaribu
**Mipangilio ya Muda wa Muda na Mfumo wa Kuzuia:**
```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")
```
### Kujaribu Kawaida
- Kujaribu sehemu kwa sehemu kwa utafutaji, caching, na utatuzi wa lebo
- Ujaribu bandia wa mashambulio ya database kwa utendaji
- Kujaribu cache ya uondoshaji na utekelezaji wa TTL
- Kujaribu utunzaji na muda wa makosa
## Mawasilisho ya Ulinganishaji wa Kumbukumbu (Cache)
### Kujaribu Kuunganisha
- Kujaribu swali la GraphRAG kamili na uboreshaji
- Kujaribu mashambulio ya database ya kweli
- Kujaribu uendeshaji sambamba na usimamizi wa rasilimali
- Kujaribu ugunduzi na usimamizi wa rasilimali
- Kujaribu utangamano na API iliyopo ya GraphRAG
- Kujaribu na nyuma tofauti za database
- Kuhakikisha usahihi wa matokeo ikilinganisha na utumizi wa sasa
**Ulinganishaji wa Uharibifu wa Data:**
**Kumbukumbu ya lebo (TTL ya dakika 5)**: Hatari ya kuonyesha lebo za vitu ambazo zimefutwa/kubadilishwa
**Hakuna uwekaji kumbukumbu wa embeddings**: Haihitajiki - embeddings tayari zimehifadhiwa kwa kila swali
**Hakuna uwekaji kumbukumbu wa matokeo**: Inazuia matokeo ya subgrafu ya zamani kutoka kwa vitu/uhusiano ambao wamefutwa
### Kujaribu Utendaji
- Kujaribu utendaji dhidi ya utumizi wa sasa
- Kujaribu mzigo kwa saizi tofauti na utata wa grafu
- Kujaribu shinikizo kwa mipaka ya kumbukumbu na muunganisho
- Kujaribu utangamano kwa uboreshaji wa utendaji
**Mikakati ya Kupunguza Madhara:**
**Manufaa ya TTL ya kihafidhia:** Kusawazisha faida za utendaji (10-20%) na usafi wa data
**Viunganishi vya kutengua kumbukumbu:** Uunganishi wa hiari na matukio ya mabadiliko ya grafu
**Dashibodi za ufuatiliaji:** Kufuatilia viwango vya hit ya kumbukumbu dhidi ya matukio ya usafi
**Mawasilisho ya kumbukumbu yanayoweza kusanidi:** Kuruhusu urekebishaji kwa kila usakinishaji kulingana na masafa ya mabadiliko
### Kujaribu Utangamano
- Hakikisha utangamano wa API ya GraphRAG iliyopo
- Jaribu na nyuma tofauti za database
- Hakikisha usahihi wa matokeo ikilinganisha na utumizi wa sasa
**Mawasilisho Yanayopendekezwa ya Kumbukumbu Kulingana na Kasi ya Mabadiliko ya Grafu:**
**Mabadiliko ya juu (>100 mabadiliko/saa)**: TTL=60s, saizi ndogo za kumbukumbu
**Mabadiliko ya wastani (10-100 mabadiliko/saa)**: TTL=300s (ya kawaida)
**Mabadiliko ya chini (<10 mabadiliko/saa)**: TTL=600s, saizi kubwa za kumbukumbu
## Mpango wa Utekelezaji
## Mawasilisho ya Usalama
### Njia ya Utekelezaji Moja kwa Moja
Kwa kuwa API zinaidhinishwa kubadilika, implement uboreshaji moja kwa moja bila utata wa uhamishaji:
**Kuzuia Uingizwaji wa Swali:**
Thibitisha kitambulisho vyote vya vitu na vigezo vya swali
Tumia maswali yaliyoparametishwa kwa mwingiliano wote wa hifadhidata
Tekeleza mipaka ya utata wa swali ili kuzuia mashambulizi ya aina ya kukataa huduma (DoS)
1. **Badilisha njia ya `follow_edges`**: Andika upya na utafutaji ulioidhinishwa wa kikundi
2. **Boresha `get_labelgraph`**: Implement utatuzi sambamba wa lebo
3. **Ongeza GraphRag ya muda mrefu**: Badilisha Processor ili itumie instance ya GraphRag iliyodumu
4. **Implement cache ya lebo**: Ongeza safu ya caching kwenye darasa la GraphRag
**Ulinzi wa Rasilimali:**
Enforce mipaka ya juu ya saizi ya subgrafu
Tekeleza muda wa mwisho wa swali ili kuzuia kutokuwa na rasilimali
Ongeza ufuatiliaji na mipaka ya matumizi ya kumbukumbu
### Nguvu ya Marekebisho
- **Darasa la swali**: Badilisha ~50 mistari katika `follow_edges`, ongeza ~30 mistari ya utunzaji wa kikundi
- **Darasa la GraphRag**: Ongeza safu ya caching (~40 mistari)
- **Darasa la Processor**: Badilisha ili utumie instance ya GraphRag iliyodumu (~20 mistari)
- **Jumla**: ~140 mistari ya mabadiliko iliyolengwa, haswa ndani ya madarasa yaliyopo
**Kidhibiti cha Ufikiaji:**
Endeleza kutengwa kwa watumiaji na ukusanyaji iliyopo
Ongeza uandikaji wa ukaguzi kwa operesheni zinazoathiri utendaji
Tekeleza kikomo cha kiwango kwa operesheni ghali
## Mawasilisho ya Utendaji
### Maboresho Yanayotarajiwa ya Utendaji
**Upunguzaji wa Swali:**
Sasa: ~9,000+ maswali kwa ombi la kawaida
Yaliyoboreshwa: ~50-100 maswali yaliyunganishwa (upunguzaji wa 98%)
**Maboresho ya Muda wa Jibu:**
Ufuatiliaji wa grafu: 15-20s → 3-5s (haraka 4-5x)
Utatuzi wa lebo: 8-12s → 2-4s (haraka 3x)
Swali kamili: 25-35s → 6-10s (maboresho ya 3-4x)
**Ufanisi wa Kumbukumbu:**
Saizi zilizokadiriwa za kumbukumbu inazuia uvujaji wa kumbukumbu
Miundo ya data inayofaa hupunguza athari ya kumbukumbu kwa ~40%
Urekebishaji wa taka bora kupitia usafi sahihi wa rasilimali
**Mataifa ya Kweli ya Utendaji:**
**Kumbukumbu ya lebo**: Upunguzaji wa 10-20% wa swali kwa grafu zilizo na uhusiano wa kawaida
**Uboreshaji wa uunganisho**: Upunguzaji wa 50-80% wa swali (uboresho mkuu)
**Uboreshaji wa maisha ya kitu**: Ondoa gharama ya kila ombi
**Maboresho ya jumla**: Maboresho ya 3-4x ya muda wa jibu hasa kutoka kwa uunganisho
**Maboresho ya Uwezo wa Kupanuka:**
Usaidizi wa grafu za maarifa kubwa 3-5x (vikomo na mahitaji ya ulinganishaji wa utendaji)
Uwezo wa juu 3-5x wa ombi la wakati mmoja
Matumizi bora ya rasilimali kupitia matumizi ya upya ya muunganisho
### Ufuatiliaji wa Utendaji
**Hesabu za Muda Halisi:**
Muda wa utekelezaji wa swali kwa aina ya operesheni
Viwango vya hit na ufanisi wa kumbukumbu
Matumizi ya kikundi cha muunganisho wa hifadhidata
Matumizi ya kumbukumbu na athari ya urekebishaji wa taka
**Ufuatiliaji wa Utendaji:**
Mtihirika wa kiotomatiki wa utendaji
Mtihirika wa mzigo ukitumia data halisi
Viwango vya utendaji dhidi ya utekelezaji wa sasa
## Mkakati wa Mtihirika
### Mtihirika wa Vitengo
Mtihirika wa vipengele vya mtu binafsi kwa ajili ya utekelezaji, kuhifadhi, na utatuzi wa lebo
Mwingiliano wa bandarini ya bandarini kwa ajili ya mtihirika wa utendaji
Mtihirika wa kuondoa data kutoka kwa kumbukumbu na muda wa kumalizika
Usimamizi wa makosa na hali za muda
### Mtihirika wa Uunganisho
Mtihirika wa mwisho hadi mwisho wa swali la GraphRAG ukiwa na uboreshaji
Mtihirika wa mwingiliano wa bandarini ya bandarini ukitumia data halisi
Usimamizi wa ombi la wakati mmoja na rasilimali
Udagano wa uvujaji wa kumbukumbu na uthibitisho wa kusafisha rasilimali
### Mtihirika wa Utendaji
Mtihirika dhidi ya utekelezaji wa sasa
Mtihirika wa mzigo ukitumia saizi na utata tofauti wa grafu
Mtihirika wa shinikizo kwa mipaka ya kumbukumbu na uunganisho
Mtihirika wa utendaji kwa uboreshaji
### Mtihirika wa Ulinganishi
Thibitisha ulinganishi wa API ya GraphRAG iliyopo
Mtihirika ukitumia bandarini ya bandarini tofauti za bandarini ya grafu
Thibitisha usahihi wa matokeo ikilinganishwa na utekelezaji wa sasa
## Mpango wa Utendaji
### Mbinu ya Utendaji Moja kwa Moja
Kwa kuwa API zinaweza kubadilika, tekeleza uboreshaji moja kwa moja bila utata wa uhamishaji:
1. **Badilisha `follow_edges` mbinu**: Andika upya ukitumia utekelezaji wa kikundi
2. **Boresha `get_labelgraph`**: Tepeleza utatuzi wa lebo kwa wingi
3. **Ongeza GraphRag ya muda mrefu**: Badilisha Processor ili kudumisha mfano wa kudumu
4. **Tepeleza uhifadhi wa lebo**: Ongeza kumbukumbu ya LRU na TTL kwa darasa la GraphRag
### Wigo wa Mabadiliko
**Darasa la swali**: Badilisha mistari ~50 katika `follow_edges`, ongeza mistari ~30 ya utunzaji wa kikundi
**Darasa la GraphRag**: Ongeza safu ya kuhifadhi (~mistari 40)
**Darasa la Processor**: Badilisha ili kutumia mfano wa kudumu wa GraphRag (~mistari 20)
**Jumla**: ~mistari 140 ya mabadiliko, hasa ndani ya madarasa yaliyopo
## Ratiba
**Wiki ya 1: Utumizi wa Msingi**
- Badilisha `follow_edges` na utafutaji wa kikundi wa iterative
- Implement utatuzi wa sambamba wa lebo katika `get_labelgraph`
- Ongeza instance ya GraphRag iliyodumu kwa Processor
- Implement safu ya caching ya lebo
**Wiki ya 1: Utendaji wa Msingi**
Badilisha `follow_edges` ukitumia utekelezaji wa kikundi
Tepeleza utatuzi wa lebo kwa wingi katika `get_labelgraph`
Ongeza mfano wa GraphRag wa muda mrefu kwa Processor
Tepeleza safu ya uhifadhi
**Wiki ya 2: Kujaribu na Kuunganisha**
- Kujaribu kawaida kwa mantiki mpya ya utafutaji na caching
- Kujaribu utendaji dhidi ya utumizi wa sasa
- Kujaribu kuunganisha na data ya grafu ya kweli
- Tathmini ya msimamizi wa msimamizi wa msimamizi wa msimamizi wa msimamizi
- Kujaribu utangamano
**Wiki ya 2: Mtihirika na Uunganisho**
Mtihirika wa vitengo kwa ajili ya utekelezaji mpya wa utekelezaji na uhifadhi
Ufuatiliaji wa utendaji dhidi ya utekelezaji wa sasa
Mtihirika wa uunganisho ukitumia data halisi ya grafu
Mtihirika wa msimamizi na uboreshaji
**Wiki ya 3: Utekelezaji**
- Tepeleza utumizi uliorekebishwa
- Fuatilia uboreshaji wa utendaji
- Rekebisha TTL ya cache na saizi za kikundi kulingana na matumizi halisi
Tepeleza utekelezaji ulioboreshwa
Fuatilia uboreshaji wa utendaji
Punguza muda wa TTL wa kumbukumbu na saizi za kikundi kulingana na matumizi halisi
## Maswali Yaliyofungwa
## Maswali ya Funguo
- **Pooli ya Muunganisho wa Database**: Je, tunapaswa kutumia pooli ya muunganisho ya database maalum au kutegemea pooli ya mteja wa database iliyopo?
- **Usaidizi wa Kumbukumbu**: Je, cache ya lebo na ya embedding inapaswa kuendelea katika kuchelewesha huduma?
- **Kumbukumbu Iliyosambaa**: Kwa usimamizi wa idadi nyingi, je, tunapaswa kutumia kumbukumbu iliyosambaa kwa Redis/Memcached?
- **Umbizo la Matokeo ya Swali**: Je, tunapaswa kuongeza ufanisi wa uwakilishi wa ndani wa triple kwa ufanisi bora wa kumbukumbu?
- **Uunganisho wa Ufuatiliaji**: Metriki gani zinapaswa kuonyeshwa kwenye mifumo ya ufuatiliaji iliyopo (Prometheus, n.k.)?
**Uunganisho wa Bandarini**: Je, tunapaswa kutekeleza uunganisho wa bandarini maalum au kutegemea uunganisho wa bandarini wa bandarini ya bandarini iliyopo?
**Ukurasa wa Kumbukumbu**: Je, kumbukumbu za lebo na uwekaji wa kumbukumbu zinapaswa kudumu katika kuanzishwa upya za huduma?
**Ukurasa Uliogawanyika**: Kwa matoleo mengi, je, tunapaswa kutekeleza ukurasa uliogawanyika ukitumia Redis/Memcached?
**Muundo wa Matokeo ya Swali**: Je, tunapaswa kuboresha uwakilishi wa ndani wa triple ili kuboresha ufanisi wa kumbukumbu?
**Uunganisho wa Ufuatiliaji**: Vipimo vipi vinapaswa kuonyeshwa kwa mifumo ya ufuatiliaji iliyopo (Prometheus, n.k.)?
## Marejeleo
- [Utekelezaji wa awali wa GraphRAG](trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py)
- [Kanuni za Usanifu za TrustGraph](architecture-principles.md)
- [Maelezo ya Usimamizi wa Mkusanyiko](collection-management.md)
[Utekelezaji Asili wa GraphRAG](trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py)
[Kanuni za Usanifu wa TrustGraph](architecture-principles.md)
[Maelekezo ya Usimamizi wa Mkusanyiko](collection-management.md)