trustgraph/docs/tech-specs/extraction-flows.sw.md

layout	title	parent
default	Mchakato wa Utoaji	Swahili (Beta)

Mchakato wa Utoaji

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.

Hati hii inaeleza jinsi data inapita katika mfumo wa utoaji wa TrustGraph, kuanzia utoaji wa hati hadi uhifadhi katika hifadhia za maarifa.

Muhtasari

┌──────────┐     ┌─────────────┐     ┌─────────┐     ┌────────────────────┐
│ Librarian│────▶│ PDF Decoder │────▶│ Chunker │────▶│ Knowledge          │
│          │     │ (PDF only)  │     │         │     │ Extraction         │
│          │────────────────────────▶│         │     │                    │
└──────────┘     └─────────────┘     └─────────┘     └────────────────────┘
                                          │                    │
                                          │                    ├──▶ Triples
                                          │                    ├──▶ Entity Contexts
                                          │                    └──▶ Rows
                                          │
                                          └──▶ Document Embeddings

Hifadhi ya Maudhui

Uhifadhi wa Data (S3/Minio)

Maudhui ya nyaraka huhifadhiwa katika uhifadhi wa data unaolingana na S3: Muundo wa njia: doc/{object_id} ambapo object_id ni UUID Aina zote za nyaraka huhifadhiwa hapa: nyaraka za asili, kurasa, sehemu

Uhifadhi wa MetaData (Cassandra)

MetaData ya nyaraka iliyohifadhiwa katika Cassandra ni pamoja na: Kitambulisho cha nyaraka, kichwa, aina (aina ya MIME) Rejea ya object_id kwa uhifadhi wa data parent_id kwa nyaraka za watoto (kurasa, sehemu) document_type: "chanzo", "ukurasa", "sehemu", "jibu"

Kigezo cha Kwanza na la Kuendelea

Usafirishaji wa maudhui hutumia mkakati unaotegemea saizi: < 2MB: Maudhui yajumuishwa ndani ya ujumbe (yamekodishwa kwa base64) ≥ 2MB: document_id pekee hutumwa; mchakato hupata kupitia API ya msimamizi

Hatua ya 1: Uwasilishaji wa Nyaraka (Msimamizi)

Kifaa cha Kuanzia

Nyaraka huingia katika mfumo kupitia operesheni ya add-document ya msimamizi:

1. Maudhui yamepakuliwa kwenye uhifadhi wa data
2. Rekodi ya metaData imeundwa katika Cassandra
3. Inarudisha kitambulisho cha nyaraka

Kuanzisha Utoaji

Operesheni ya add-processing inaanzisha utoaji: Inaonyesha document_id, flow (kitambulisho cha mnyororo), collection (hifadhi inayolengwa) Msimamizi wa load_document() hupata maudhui na huyaweka kwenye folyo ya ingizo

Muundo: Nyaraka

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)

Uelekezaji: Kulingana na sehemu kind: application/pdf → Kundi document-load → Kipangishi cha PDF text/plain → Kundi text-load → Kipande

Hatua ya 2: Kipangishi cha PDF

Hubadilisha hati za PDF kuwa kurasa za maandishi.

Mchakato

1. Pata maudhui (moja kwa moja data au kupitia document_id kutoka kwa msimamizi)
2. Toa kurasa kwa kutumia PyPDF
3. Kwa kila ukurasa: Hifadhi kama hati ndogo kwa msimamizi ({doc_id}/p{page_num}) Toa matoleo ya asili (ukurasa ulichukuliwa kutoka hati) Peleka kwa kipande

Mpango: 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")

Hatua ya 3: Kugawanya maandishi

Hugawanya maandishi katika sehemu ndogo kulingana na ukubwa uliopangwa.

Vigezo (vielekezi ambavyo vinaweza kusanidiwa)

chunk_size: Ukubwa unaolengwa wa sehemu ndogo kwa herufi (kiwango chachilia: 2000) chunk_overlap: Mzunguko kati ya sehemu ndogo (kiwango chachilia: 100)

Mchakato

1. Pata maudhui ya maandishi (moja kwa moja au kupitia mfumo wa kumbukumbu)
2. Gawanya kwa kutumia mgawaji wa herufi unaojielekeza
3. Kwa kila sehemu ndogo: Hifadhi kama hati ndogo katika mfumo wa kumbukumbu ({parent_id}/c{index}) Toa taarifa za asili (sehemu ndogo ilitokana na ukurasa/hati) Peleka kwa vichakavu vya utoaji

Muundo: Sehemu Ndogo

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")

Hierarkia ya Kitambulisho cha Hati

Hati za chini huandika urithi wao katika kitambulisho: Chanzo: doc123 Ukurasa: doc123/p5 Sehemu kutoka ukurasa: doc123/p5/c2 Sehemu kutoka maandishi: doc123/c2

Hatua ya 4: Utokaji wa Maarifa

Mfumo mbalimbali wa utokaji unapatikana, unaochaguliwa na usanidi wa mtiririko.

Mfumo A: Basic GraphRAG

Wasindikaji wawili sambamba:

kg-extract-definitions Ingizo: Sehemu Patoto: Triples (ufafanuzi wa vitu), EntityContexts Hutokaje: lebo za vitu, ufafanuzi

kg-extract-relationships Ingizo: Sehemu Patoto: Triples (uhusiano), EntityContexts Hutokaje: uhusiano wa subjekti-kivumbe-kijisumu

Mfumo B: Inayoendeshwa na Ontolojia (kg-extract-ontology)

Ingizo: Sehemu Patoto: Triples, EntityContexts Hutumia ontolojia iliyosanidiwa ili kuongoza utokaji

Mfumo C: Inayoendeshwa na Wakala (kg-extract-agent)

Ingizo: Sehemu Patoto: Triples, EntityContexts Hutumia mfumo wa wakala kwa utokaji

Mfumo D: Utokaji wa Mistari (kg-extract-rows)

Ingizo: Sehemu Patoto: Mistari (data iliyopangwa, si triples) Hutumia ufafanuzi wa schema ili kutokaje rekodi zilizopangwa

Schema: Triples

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

Mfumo: EntityContexts

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)

Mfumo: Safu

Rows
├── metadata: Metadata
├── row_schema: RowSchema
│   ├── name: str
│   ├── description: str
│   └── fields: list[Field]
└── rows: list[dict[str, str]]   # Extracted records

Hatua ya 5: Uzalishaji wa Uelekezo (Embeddings)

Uelekezo wa Grafu

Hubadilisha muktadha wa vitu katika uelekezo wa vector.

Mchakato:

1. Pokea Muktadha wa Vitu (EntityContexts)
2. Piga simu kwa huduma ya uelekezo (embeddings) kwa kutumia maandishi ya muktadha
3. Toa Uelekezo wa Grafu (ramani ya kitu hadi vector)

Muundo: Uelekezo wa Grafu (GraphEmbeddings)

GraphEmbeddings
├── metadata: Metadata
└── entities: list[EntityEmbeddings]
    └── EntityEmbeddings
        ├── entity: Term         # Entity identifier
        ├── vector: list[float]  # Embedding vector
        └── chunk_id: str        # Source chunk (provenance)

Uelekezaji wa Hati

Hubadilisha maandishi ya sehemu moja moja kwa uelekezaji wa vector.

Mchakato:

1. Pokea Sehemu
2. Piga simu kwa huduma ya uelekezaji kwa kutumia maandishi ya sehemu
3. Toa Uelekezaji wa Hati

Muundo: Uelekezaji wa Hati

DocumentEmbeddings
├── metadata: Metadata
└── chunks: list[ChunkEmbeddings]
    └── ChunkEmbeddings
        ├── chunk_id: str        # Chunk identifier
        └── vector: list[float]  # Embedding vector

Ulinganisho wa Safu

Hubadilisha nambari za safu kuwa ulinganisho wa vekta.

Mchakato:

1. Pokea Safu
2. Linganisha nambari zilizoelezwa za safu
3. Toa kwenye hifadhi ya vekta ya safu

Hatua ya 6: Uhifadhi

Hifadhi ya Triple

Inapokea: Triples Uhifadhi: Cassandra (meza zenye msingi wa vitu) Picha zilizoainishwa zinatenganisha maarifa ya msingi kutoka kwa asili: "" (ya kawaida): Ukweli wa maarifa ya msingi urn:graph:source: Asili ya uondoaji urn:graph:retrieval: Uwezekano wa kufafanua wakati wa kuuliza

Hifadhi ya Vektaja (Ulinganisho wa Picha)

Inapokea: Ulinganisho wa Picha Uhifadhi: Qdrant, Milvus, au Pinecone Imeorodheshwa kwa: IRI ya kitu Meta: chunk_id kwa asili

Hifadhi ya Vektaja (Ulinganisho wa Nyaraka)

Inapokea: Ulinganisho wa Nyaraka Uhifadhi: Qdrant, Milvus, au Pinecone Imeorodheshwa kwa: chunk_id

Hifadhi ya Safu

Inapokea: Safu Uhifadhi: Cassandra Muundo wa meza unaoongozwa na schema

Hifadhi ya Vektaja ya Safu

Inapokea: Ulinganisho wa safu Uhifadhi: Hifadhi ya Vektaja Imeorodheshwa kwa: nambari za safu

Uchunguzi wa Uwanja wa Meta

Uwanja Unaotumika Kwa Kazi

Uwanja	Matumizi
metadata.id	Kitambulisho cha nyaraka/kipande, uandishi wa matukio, asili
metadata.user	Usimamizi wa wateja wengi, uelekezaji wa uhifadhi
metadata.collection	Uchaguzi wa mkusanyiko unaolengwa
document_id	Rejea ya mkusanyaji, kuunganisha asili
chunk_id	Kufuatilia asili kupitia mnyororo

<<<<<<< HEAD

Uwanja Unaowezekana kuwa Ziada

Uwanja	Hali
metadata.metadata	Imepangwa kama [] na vichujio vyote; meta ya kiwango cha nyaraka sasa inashughulikiwa na mkusanyaji wakati wa kuwasilisha

=======

Uwanja Ulioondolewa

Uwanja	Hali
metadata.metadata	Imeondolewa kutoka kwa darasa la Metadata. Triples za meta ya kiwango cha nyaraka sasa hutolewa moja kwa moja na mkusanyaji kwenye hifadhi ya triples wakati wa kuwasilisha, sio kuletwa kupitia mnyororo wa uondoaji.

e3bcbf73 (Uwanja wa meta (orodha ya triples) katika darasa la Mnyororo wa Meta)

Mfumo wa Uwanja wa Bytes

Uwanja wote wa yaliyomo (data, text, chunk) ni bytes lakini huondolewa mara moja kuwa maandishi ya UTF-8 na vichujio vyote. Hakuna kichujio kinachotumia bytes mbichi.

Usanidi wa Mnyororo

Mnyororo huainishwa nje na hutolewa kwa mkusanyaji kupitia huduma ya usanidi. Kila mnyororo unaonyesha:

Ndege za ingizo (text-load, document-load) Mnyororo wa vichujio Vigezo (ukubwa wa kipande, njia ya uondoaji, n.k.)

Mifano ya mnyororo: pdf-graphrag: PDF → Dekoda → Kipande → Maelezo + Mahusiano → Ulinganisho text-graphrag: Nakshata → Kipande → Maelezo + Mahusiano → Ulinganisho pdf-ontology: PDF → Dekoda → Kipande → Uondoaji wa Ontolojia → Ulinganisho text-rows: Nakshata → Kipande → Uondoaji wa Safu → Hifadhi ya Safu