trustgraph/docs/tech-specs/large-document-loading.sw.md

layout	title	parent
default	Vipimo vya Utekelezaji wa Teknolojia ya Kupakia Hati Kubwa	Swahili (Beta)

<<<<<<< HEAD

Vipimo vya Utekelezaji wa Teknolojia ya Kupakia Hati Kubwa

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.

Muhtasari

Maelekezo haya yanaeleza masuala ya uwezo wa kufanya kazi na uzoefu wa mtumiaji wakati wa kupakia hati kubwa katika TrustGraph. Muundo wa sasa hutumia kupakia hati kama operesheni moja, na kusababisha shinikizo la kumbukumbu katika hatua nyingi za mchakato na kutoa maelezo au chaguo za kurejesha kwa watumiaji.

Utaratibu huu unalenga matumizi yafuatayo:

1. Uchakataji wa Hati za PDF Kubwa: Kupakia na kuchakata faili za PDF zenye mamia ya megabytes bila kutumia kumbukumbu yote.
2. Kupakia Ambayo Inaweza Kuendelea: Kuruhusu kupakia ambacho kimetokea kukatika kuendelea kutoka ambapo kilisimama badala ya kuanza tena.
3. Maelezo ya Maendeleo: Kutoa kwa watumiaji maelezo ya muda halisi kuhusu maendeleo ya kupakia na uchakataji.
4. Uchakataji Wenye Ufanisi wa Kumbukumbu: Kuchakata hati kwa njia ya mtiririko =======

Vipimo vya Utekelezaji wa Uteuzi wa Hati Kubwa

Muhtasari

Maelekezo haya yanaeleza masuala ya uwezo wa kutosha na uzoefu wa mtumiaji wakati wa kupakia hati kubwa katika TrustGraph. Muundo wa sasa hutibu kupakia hati kama operesheni moja na kamili, na kusababisha shinikizo la kumbukumbu katika sehemu nyingi za mchakato na kutoa hakikisho au chaguo za urejesho kwa watumiaji.

Utendaji huu unalenga matumizi yafuatayo:

1. Uchakataji wa PDF Kubwa: Pakia na uchakata faili za PDF zenye mamia ya megabytes bila kutumia kumbukumbu.
2. Uipakaji Unaoweza Kuendelea: Ruhusu uipakaji ambao umevunjika kuendelea kutoka ambapo ulikuwa umeacha badala ya kuanza tena.
3. Hakikisho la Maendeleo: Toa watumiaji maoni ya wakati halisi kuhusu maendeleo ya uipakaji na uchakataji.
4. Uchakataji Wenye Ufanisi wa Kumbukumbu: Chakata hati kwa njia ya mtiririko

82edf2d (New md files from RunPod) bila kuhifadhi faili zilizokamilika katika kumbukumbu.

Lengo

<<<<<<< HEAD Kupakia kwa Awamu: Kusaidia kupakia hati kwa sehemu kupitia REST na WebSocket Uhamisho Unaoweza Kuendelea: Kuruhusu kurejesha kutoka kupakia ambacho kimetokea kukatika Uonekana wa Maendeleo: Kutoa maelezo ya maendeleo ya kupakia/uchakataji kwa wateja Ufanisi wa Kumbukumbu: Kuondoa uhifadhi wa hati zilizokamilika katika mchakato wote Ulinganifu na Mifumo ya Zamani: Mchakato wa sasa wa hati ndogo unaendelea bila mabadiliko Uchakataji wa Mtiririko: Ufichuzi na uainishaji wa maandishi hufanywa kwa kutumia mitiririko

Uipakaji wa Hatua-Hatua: Unga uipakaji wa hati kwa sehemu kupitia REST na WebSocket Uhamisho Unaoweza Kuendelea: Ruhusu urejesho kutoka uipakaji ambao umevunjika Uonekana wa Maendeleo: Toa watumiaji maoni ya maendeleo ya uipakaji/uchakataji Ufanisi wa Kumbukumbu: Ondoa kuhifadhi hati zilizokamilika katika mchakato Ulinganifu na Mifumo ya Zamani: Mchakato wa sasa wa hati ndogo unaendelea bila mabadiliko Uchakataji wa Mtiririko: Uvunjaji wa PDF na maandishi hufanya kazi kwenye mitiririko

82edf2d (New md files from RunPod)

Asili

Muundo wa Sasa

<<<<<<< HEAD Hati zinatumiwa kupitia njia ifuatayo:

1. Mteja hutuma hati kupitia REST (POST /api/v1/librarian) au WebSocket

2. Lango la API linapokea ombi kamili lenye maudhui ya hati yaliyokuzwa kwa msingi 64

3. LibrarianRequestor huongeza ombi kwenye ujumbe wa Pulsar

4. Huduma ya Librarian inapokea ujumbe, huondoa maudhui ya hati katika kumbukumbu

5. BlobStore huhamisha hati kwenye Garage/S3

6. Cassandra huhifadhi metadata pamoja na rejea ya kitu

7. Kwa uchakataji: hati inavyolewa kutoka S3, huondoa maudhui, huainishwa—yote katika kumbukumbu ======= Mchakato wa kuwasilisha hati hufuatilia njia ifuatayo:

8. Mteja huwasilisha hati kupitia REST (POST /api/v1/librarian) au WebSocket

9. Lango la API hupokea ombi kamili na maudhui ya hati iliyosimbwa kwa base64

10. LibrarianRequestor huongeza ombi kwenye ujumbe wa Pulsar

11. Huduma ya Librarian hupokea ujumbe, huondoa usimbaji wa hati katika kumbukumbu

12. BlobStore huipakia hati kwenye Garage/S3

13. Cassandra huhifadhi metadata na rejea la kitu

14. Kwa uchakataji: hati hupelekwa kutoka S3, huondoa usimbaji, huainishwa—yote katika kumbukumbu

82edf2d (New md files from RunPod)

Faili muhimu: Ingizo la REST/WebSocket: trustgraph-flow/trustgraph/gateway/service.py Msingi wa Librarian: trustgraph-flow/trustgraph/librarian/librarian.py Uhifadhi wa blob: trustgraph-flow/trustgraph/librarian/blob_store.py Jedwali la Cassandra: trustgraph-flow/trustgraph/tables/library.py Mpango wa API: trustgraph-base/trustgraph/schema/services/library.py

Mapungufu ya Sasa

<<<<<<< HEAD Muundo wa sasa una masuala kadhaa ambayo huathiri kumbukumbu na uzoefu wa mtumiaji:

1. Operesheni ya Kupakia ya Atomiki: Hati nzima lazima ihamishwe katika ombi moja. Hati kubwa zinahitaji ombi linalodumu kwa muda mrefu bila maelezo ya maendeleo na hakuna njia ya kujaribu tena ikiwa muunganisho utakatika.

2. Muundo wa API: API za REST na WebSocket zinatarajia hati nzima katika ujumbe mmoja. Mpango (LibrarianRequest) una content ambayo ina maudhui ya hati nzima yaliyokuzwa kwa msingi 64.

3. Kumbukumbu ya Librarian: Huduma ya librarian huondoa maudhui ya hati katika kumbukumbu kabla ya kuihamisha kwenye S3. Kwa PDF ya 500MB, hii inamaanisha kuhifadhi 500MB+ katika kumbukumbu ya mchakato.

4. Kumbukumbu ya Kufichua PDF: Wakati wa uchakataji, programu ya kufichua PDF huhamisha hati nzima katika kumbukumbu ili kuchimbua maandishi. Maktaba kama vile PyPDF zinaweza kuhitaji upataji wa hati nzima.

5. Kumbukumbu ya Kifaa cha Kuchakata: Kifaa cha kuchakata maandishi hupokea maandishi yaliyochimbuliwa na kuhifadhi katika kumbukumbu huku huchakata na kuunda sehemu.

Mfano wa Athari ya Kumbukumbu (PDF ya 500MB): Lango: ~700MB (maudhui yaliyokuzwa) Librarian: ~500MB (bytes zilizofichuliwa) Kifaa cha Kufichua PDF: ~500MB + buffers za uchimbaji Kifaa cha Kuchakata: maandishi yaliyochimbuliwa (hubadilika, inaweza kuwa 100MB+)

Muundo wa sasa una masuala kadhaa yanayoathiri kumbukumbu na uzoefu wa mtumiaji:

1. Operesheni ya Uipakaji Kamili: Hati nzima lazima iwasilishwe katika ombi moja. Hati kubwa zinahitaji ombi linalodumu kwa muda mrefu bila hakikisho ya maendeleo na hakuna njia ya kujaribu tena ikiwa muunganisho utavunjika.

2. Muundo wa API: API za REST na WebSocket zinatarajia hati nzima katika ujumbe mmoja. Mpango (LibrarianRequest) una content sehemu inayohifadhi maudhui ya hati iliyosimbwa kwa base64.

3. Kumbukumbu ya Librarian: Huduma ya librarian huondoa usimbaji wa hati nzima katika kumbukumbu kabla ya kuipeleka kwenye S3. Kwa PDF ya 500MB, hii inamaanisha kuhifadhi 500MB+ katika kumbukumbu ya programu.

4. Kumbukumbu ya Dekoda ya PDF: Wakati uchakataji unaanza, dekoda ya PDF hupakia hati nzima katika kumbukumbu ili kuchimbua maandishi. Maktabu kama PyPDF na zile kama hizo kawaida zinahitaji upataji wa hati nzima.

5. Kumbukumbu ya Chunker: Chunker hupokea maandishi yaliyochimbuliwa na kuhifadhi katika kumbukumbu huku inazalisha sehemu.

Mfano wa Athari ya Kumbukumbu (PDF ya 500MB): Lango: ~700MB (ghairi ya usimbaji) Librarian: ~500MB (bytes zilizopunguzwa) Dekoda ya PDF: ~500MB + buffers za uchimbaji Chunker: maandishi yaliyopatikana (hubadilika, inaweza kuwa 100MB+)

82edf2d (New md files from RunPod)

Kumbukumbu ya juu inaweza kuzidi 2GB kwa hati kubwa moja.

Muundo wa Kiufundi

Kanuni za Muundo

<<<<<<< HEAD

1. Uhusiano wa API: Mwingiliano wote wa mteja hupitia API ya librarian. Wateja hawana upataji wa moja kwa moja au kujua kuhusu uhifadhi wa S3/Garage.

2. Kupakia kwa Sehemu ya S3: Tumia kupakia kwa sehemu ya S3. Hii inasaidiwa kwa mfumo wowote unaolingana na S3 (AWS S3, MinIO, Garage, Ceph, DigitalOcean Spaces, Backblaze B2, n.k.) kuhakikisha uwezekano wa kuhamishwa.

3. Kukamilika kwa Atomiki: Kupakia kwa sehemu ya S3 kunaweza kukamilika kwa atomiki - sehemu zilizopakiwa hazionekani hadi CompleteMultipartUpload itakapopigwa. Hakuna faili za muda au operesheni za kubadilisha.

4. Hali Inayoweza Kufuatiliwa: Vipindi vya kupakia hufuatiliwa katika Cassandra, kutoa uonevu kuhusu kupakia ambacho hakikamilika na kuruhusu uwezo wa kuanza tena.

Mchakato wa Kupakia kwa Sehemu

=======

1. Kifurushi cha API: Mwingiliano wote wa mteja hupitia API ya librarian. Wateja hawana upataji wa moja kwa moja au kujua kuhusu uhifadhi wa S3/Garage.

2. Uipakaji wa Sehemu wa S3: Tumia uipakaji wa sehemu wa S3. Hii inasaidiwa sana katika mifumo inayolingana na S3 (AWS S3, MinIO, Garage, Ceph, DigitalOcean Spaces, Backblaze B2, n.k.) kuhakikisha uwezekano wa kuhamishwa.

3. Uhakikisho Kamili: Uipakaji wa sehemu wa S3 ni wa uhakikisho kamili - sehemu zilizopakiwa hazionekani hadi CompleteMultipartUpload itakapopigwa. Hakuna faili za muda au operesheni za kubadilisha.

4. Hali Inayoweza Kufuatiliwa: Vipindi vya uipakaji hufuatiliwa katika Cassandra, kutoa uonevu kuhusu uipakaji usio kamili na kuwezesha uwezo wa kuanza tena.

Mchakato wa Uipakaji wa Sehemu

82edf2d (New md files from RunPod)

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

Mteja hawezi kuwasiliana na S3 moja kwa moja. Msimamizi (librarian) hutafsiri kati ya API yetu ya kupakia vipande na operesheni za S3 za sehemu nyingi (multipart) kwa ndani.

Operesheni za API ya Msimamizi (Librarian)

begin-upload

Anzisha kipindi cha kupakia vipande.

Ombi:

{
  "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
}

Jibu:

{
  "upload-id": "upload-abc-123",
  "chunk-size": 5242880,
  "total-chunks": 100
}

Msimamizi wa maktaba:

1. Huunda nambari ya kipekee upload_id na object_id (UUID kwa uhifadhi wa data).
2. Huita CreateMultipartUpload ya S3, na kupokea s3_upload_id.
3. Huunda rekodi ya kikao katika Cassandra.
4. Hurudisha upload_id kwa mteja.

upload-chunk

<<<<<<< HEAD Pakia kipande kimoja.

Pakia sehemu moja.

82edf2d (New md files from RunPod)

Ombi:

{
  "operation": "upload-chunk",
  "upload-id": "upload-abc-123",
  "chunk-index": 0,
  "content": "<base64-encoded-chunk>"
}

Jibu:

{
  "upload-id": "upload-abc-123",
  "chunk-index": 0,
  "chunks-received": 1,
  "total-chunks": 100,
  "bytes-received": 5242880,
  "total-bytes": 524288000
}

Msimamizi wa maktaba: <<<<<<< HEAD

1. Tafuta kikao kwa kutumia upload_id
2. Thibitisha umiliki (mtumiaji lazima awe yule aliyeunda kikao)
3. Piga simu kwa S3 UploadPart pamoja na data ya sehemu, na upokee etag
4. Sasisha rekodi ya kikao na fahirisi ya sehemu na etag
5. Rejesha maelezo ya maendeleo kwa mteja

Sehemu ambazo hazijafaulu zinaweza kujaribiwa tena - tuma tu chunk-index tena.

1. Tafuta kipindi kwa upload_id
2. Thibitisha umiliki (mtumiaji lazima awe yule aliyeunda kipindi)
3. Piga S3 UploadPart na data ya sehemu, pokea etag
4. Sasisha rekodi ya kipindi na fahirisi ya sehemu na etag
5. Rejesha maendeleo kwa mteja

Sehemu ambazo hazijafaulu zinaweza kujaribiwa tena - tuma tu chunk-index ile ile tena.

82edf2d (New md files from RunPod)

complete-upload

Hakisha upakiaji na uunde hati.

Ombi:

{
  "operation": "complete-upload",
  "upload-id": "upload-abc-123"
}

Jibu:

{
  "document-id": "doc-123",
  "object-id": "550e8400-e29b-41d4-a716-446655440000"
}

Msimamizi wa maktaba: <<<<<<< HEAD

1. Tafuta kikao, thibitisha kwamba vipande vyote vimepokelewa
2. Anapiga S3 CompleteMultipartUpload na etags za sehemu (S3 huunganisha sehemu ndani - hakuna gharama ya kumbukumbu kwa msimamizi)
3. Huunda rekodi ya hati katika Cassandra na metadata na rejeleo la kitu
4. Huondoa rekodi ya kikao cha kupakia
5. Hurudisha kitambulisho cha hati kwa mteja =======
6. Angalia kikao, thibitisha kwamba vipande vyote vimepokelewa.
7. Anapiga S3 CompleteMultipartUpload na etags za sehemu (S3 huunganisha sehemu ndani - hakuna gharama ya kumbukumbu kwa msimamizi).
8. Huunda rekodi ya hati katika Cassandra na metadata na rejea la kitu.
9. Huondoa rekodi ya kikao cha kupakia.
10. Anarudisha kitambulisho cha hati kwa mteja.

82edf2d (New md files from RunPod)

abort-upload

Kuacha kupakia ambacho kinaendelea.

Ombi:

{
  "operation": "abort-upload",
  "upload-id": "upload-abc-123"
}

Msimamizi wa maktaba:

1. Anapiga simu kwa S3 AbortMultipartUpload ili kusafisha sehemu.
2. Anafuta rekodi ya kikao kutoka Cassandra.

get-upload-status

Angalia hali ya kupakia (kwa uwezo wa kuendelea).

Ombi:

{
  "operation": "get-upload-status",
  "upload-id": "upload-abc-123"
}

Jibu:

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

Orodha ya vipakuliwa ambavyo havijakamilika kwa mtumiaji.

Ombi:

{
  "operation": "list-uploads"
}

Jibu:

{
  "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"
    }
  ]
}

Hifadhi ya Kipindi cha Uipakaji

Fuatilia uipakaji unaoendelea katika Cassandra:

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

<<<<<<< HEAD Tabia ya TTL: Vikao hupotea baada ya saa 24 ikiwa havijakamilika. Wakati TTL ya Cassandra inapita, rekodi ya kikao inafutwa. Sehemu zisizo na uhusiano za S3 huondolewa na sera ya maisha ya S3 (sanidi kwenye ndoo).

Usimamizi wa Hitilafu na Uadilifu

Hitilafu ya kupakia sehemu: Mteja hurudia kupakia sehemu iliyoshindwa (na upload_id na chunk-index sawa).

Tabia ya Muda (TTL): Vikao hupotea baada ya saa 24 ikiwa havijakamilika. Wakati muda (TTL) wa Cassandra unapita, rekodi ya kikao inafutwa. Sehemu zisizo na uhusiano za S3 huondolewa na sera ya maisha ya S3 (sanidi kwenye ndoo).

Usimamizi wa Hitilafu na Umoja

Hitilafu ya kupakia sehemu: Mteja hujaribu tena sehemu iliyoshindwa (na upload_id na chunk-index sawa).

82edf2d (New md files from RunPod) UploadPart ya S3 ni sawa kwa nambari sawa ya sehemu. Kikao kinafuatilia sehemu zipi zilizofanikiwa.

Mteja hukatika wakati wa kupakia: Kikao kinaendelea katika Cassandra na sehemu zilizopokelewa zimeandikwa. Mteja anaweza kupiga get-upload-status ili kuona nini kinakosekana. Anza tena kwa kupakia sehemu ambazo hazijapakiwa, kisha complete-upload.

Hitilafu ya kupakia kikamilifu: <<<<<<< HEAD CompleteMultipartUpload ya S3 ni ya uadilifu - inaweza kufanikiwa kikamilifu au kushindwa. Katika hali ya kushindwa, sehemu zinaendelea na mteja anaweza kujaribu tena complete-upload. Hati yoyote ya nusu haionekani.

Kumalizika kwa kikao: TTL ya Cassandra inafuta rekodi ya kikao baada ya saa 24. Sera ya maisha ya ndoo ya S3 husafisha kupakia kwa sehemu nyingi ambazo hazijakamilika. Hakuna usafishaji wa mwongozo unaohitajika.

Uadilifu wa Sehemu Nyingi za S3

Kupakia kwa sehemu nyingi za S3 hutoa uadilifu uliopo:

1. Sehemu hazionekani: Sehemu zilizopakuliwa haziwezi kupatikana kama vitu. Zipo tu kama sehemu za kupakia kwa sehemu nyingi ambazo hazijakamilika.

2. Kukamilisha kwa uadilifu: CompleteMultipartUpload inaweza kufanikiwa (kitu kinaonekana kwa uadilifu) au kushindwa (hakuna kitu kilichoanzishwa). Hakuna hali ya nusu.

3. Hakuna jina tena linalohitajika: Ufunguo wa mwisho wa kitu unaonyeshwa wakati CreateMultipartUpload. Sehemu huunganishwa moja kwa moja kwenye ufunguo huo.

4. Uunganishaji wa upande wa seva: S3 inaunganisha sehemu ndani. Msimamizi ======= CompleteMultipartUpload ya S3 ni ya umoja - inaweza kufanikiwa kikamilifu au kushindwa. Katika hali ya kushindwa, sehemu zinaendelea na mteja anaweza kujaribu tena complete-upload. Hati yoyote isiyo kamili haionekani.

Muda wa kikao: Muda (TTL) wa Cassandra hufuta rekodi ya kikao baada ya saa 24. Sera ya maisha ya ndoo ya S3 husafisha kupakia kwa sehemu nyingi ambazo hazijakamilika. Hakuna usafishaji wa mwongozo unaohitajika.

Umoja wa Kupakia Sehemu ya S3

Kupakia sehemu nyingi za S3 hutoa umoja uliopo:

1. Sehemu hazionekani: Sehemu zilizopakuliwa haziwezi kupatikana kama vitu. Zipo tu kama sehemu za kupakia sehemu nyingi ambazo hazijakamilika.

2. Uhakikisho wa umoja: CompleteMultipartUpload inaweza kufanikiwa (kitu kinaonekana kikamilifu) au kushindwa (kitu hakitengenezwi). Hakuna hali ya nusu.

3. Hakuna haja ya kubadilisha jina: Ufunguo wa mwisho wa kitu unaonyeshwa wakati CreateMultipartUpload. Sehemu huunganishwa moja kwa moja kwenye ufunguo huo.

4. Uunganishaji wa upande wa seva: S3 huunganisha sehemu ndani. Msimamizi

82edf2d (New md files from RunPod) haisomi sehemu - hakuna gharama ya kumbukumbu bila kujali ukubwa wa hati.

Upanuzi wa BlobStore

Faili: trustgraph-flow/trustgraph/librarian/blob_store.py

Ongeza mbinu za kupakia sehemu nyingi:

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

<<<<<<< HEAD

Mambo Yanayohusiana na Ukubwa wa Sehemu

Kiwango cha chini cha S3: 5MB kwa kila sehemu (isipokuwa sehemu ya mwisho) Kiwango cha juu cha S3: Sehemu 10,000 kwa kila upakiaji Kiwango cha kawaida kinachopendekezwa: Sehemu za 5MB Hati ya 500MB = sehemu 100 Hati ya 5GB = sehemu 1,000 Ufuatiliaji wa maendeleo: Sehemu ndogo = taarifa za maendeleo bora Ufanisi wa mtandao: Sehemu kubwa = safari ndogo

Ukubwa wa sehemu unaweza kupangwa na mtumiaji ndani ya mipaka (5MB - 100MB).

Ufuatiliaji wa Hati: Upakiaji wa Kiasi

Mchakato wa upakiaji unalenga kuweka hati kwenye hifadhi kwa ufanisi. Mchakato wa ufuatiliaji unalenga kuchuja na kugawanya hati bila kuzipakia zote kwenye kumbukumbu.

Kanuni ya Ubunifu: Kitambulisho, Sio Yaliyomo

Kwa sasa, wakati mchakato unaanza, yaliyomo kwenye hati huhamishwa kupitia ujumbe wa Pulsar. Hii inapakia hati zote kwenye kumbukumbu. Badala yake:

Ujumbe wa Pulsar unaonyesha tu kitambulisho cha hati Vifaa vya ufuatiliaji hupata yaliyomo kwenye hati moja kwa moja kutoka kwa mfumo Kupata hufanyika kama mtiririko kwenye faili ya muda Ufuatiliaji maalum wa hati (PDF, maandishi, n.k.) hufanya kazi na faili, sio mipaka ya kumbukumbu

Hii inahakikisha kwamba mfumo wa hati hautegemei muundo wa hati. Ufuatiliaji wa PDF, ufuatiliaji wa maandishi, na mantiki nyingine maalum ya muundo inabaki katika vichujio husika.

Mambo Yanayohusiana na Ukubwa wa Kifurushi

Kiwango cha chini cha S3: 5MB kwa kila sehemu (isipokuwa sehemu ya mwisho) Kiwango cha juu cha S3: Sehemu 10,000 kwa kila upakiaji Kiwango cha kawaida kinachopendekezwa: Kifurushi cha 5MB Hati ya 500MB = Kifurushi 100 Hati ya 5GB = Kifurushi 1,000 Ufuatiliaji wa maendeleo: Kifurushi kidogo = Taarifa za maendeleo bora Ufanisi wa mtandao: Kifurushi kikubwa = Safari ndogo

Ukubwa wa kifurushi unaweza kusanidiwa na mtumiaji ndani ya mipaka (5MB - 100MB).

Ufuatiliaji wa Hati: Upakiaji wa Kwenye Mtiririko

Mchakato wa upakiaji unahusu kuweka hati kwenye hifadhi kwa ufanisi. Mchakato wa ufuatiliaji unahusu kuchuja na kugawanya hati bila kuiziba yote kwenye kumbukumbu.

Kanuni ya Ubunifu: Kitambulisho, Sio Yaliyomo

Kwa sasa, wakati mchakato unaanza, yaliyomo kwenye hati huhamishwa kupitia ujumbe wa Pulsar. Hii huweka hati zilizokamilika kwenye kumbukumbu. Badala yake:

Ujumbe wa Pulsar unaonyesha tu kitambulisho cha hati Vifaa hupata yaliyomo kwenye hati moja kwa moja kutoka kwa mfumo wa kumbukumbu Kupata hufanyika kama mtiririko kwenye faili ya muda Ufuatiliaji maalum wa hati (PDF, maandishi, n.k.) hutumia faili, sio mipaka ya kumbukumbu

Hii huweka mfumo wa kumbukumbu usio na kujua muundo wa hati. Ufuatiliaji wa PDF, ufuatiliaji wa maandishi, na mantiki nyingine maalum ya muundo huendelea katika vichujio husika.

Mchakato wa Ufuatiliaji

82edf2d (New md files from RunPod)

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                          │

<<<<<<< HEAD

API ya Mfumo wa Maktaba

Ongeza operesheni ya upataji wa hati kwa njia ya mtiririko:

API ya Mto wa Huduma za Maktaba

Ongeza operesheni ya kupata hati kwa mtiririko:

82edf2d (New md files from RunPod)

stream-document

Ombi:

{
  "operation": "stream-document",
  "document-id": "doc-123"
}

Jibu: Vipande vya binary vilivyotumwa (si jibu moja).

Kwa API ya REST, hii hurudisha jibu linaloendelea kwa kutumia Transfer-Encoding: chunked.

<<<<<<< HEAD Kwa simu za ndani kati ya huduma (kwa mfumo wa uprosesa hadi mfumo wa kumbukumbu), hii inaweza kuwa: Uhamisho wa moja kwa moja wa S3 kupitia URL iliyosainiwa (ikiwa mtandao wa ndani unaruhusu). Majibu yaliyogawanywa kupitia itifaki ya huduma. Kituo maalum cha utumaji wa data.

Kwa simu za ndani kati ya huduma (kwa mfumo wa usindikaji hadi kwa mfumo wa kumbukumbu), hii inaweza kuwa: Uhamisho wa moja kwa moja wa S3 kupitia URL iliyosainiwa (ikiwa mtandao wa ndani unaruhusu). Majibu yaliyogawanywa kupitia itifaki ya huduma. Kifaa maalum cha utumaji wa data.

82edf2d (New md files from RunPod)

Mahitaji muhimu: data inatiririka kwa vipande, haijahifadhiwa kikamilifu katika mfumo wa kumbukumbu.

Mabadiliko ya Kipanguli cha PDF

Utendaji wa sasa (unaotumia kumbukumbu nyingi):

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

Utekelezaji mpya (faili ya muda, hatua kwa hatua):

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

Profaili ya kumbukumbu: Faili ya muda kwenye diski: ukubwa wa faili ya PDF (diski ni rahisi). Katika kumbukumbu: ukurasa mmoja wa maandishi kwa wakati. Kumbukumbu ya juu: imepunguzwa, haitegemei saizi ya hati.

Mabadiliko ya Kipanguli cha Hati za Nakshata

Kwa hati za nakshata, rahisi zaidi - hakuna faili ya muda inayohitajika:

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

Hati za maandishi zinaweza kutiririka moja kwa moja bila faili ya muda kwa sababu zina muundo wa mstari.

<<<<<<< HEAD

Jumuisho la Kifaa cha Kugawa (Chunker)

Kifaa cha kugawa hupokea mfuatiliaji wa maandishi (kurasa au aya) na hutoa

Jumuisho la Kichungia (Chunker)

Kichungia hupokea mfuatiliaji wa maandishi (kurasa au aya) na hutoa

82edf2d (New md files from RunPod) vipande kwa hatua kwa hatua:

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

Mchakato Kamili wa Uendeshaji

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)

<<<<<<< HEAD Katika hakuna hatua, hati kamili au maandishi yaliyotolewa kamili hayahifadhiwi kwenye kumbukumbu.

Katika hakuna hatua, hati kamili au maandishi yaliyochukuliwa kamili hayahifadhiwi kwenye kumbukumbu.

82edf2d (New md files from RunPod)

Mambo Yanayohusiana na Faili za Muda

Mahali: Tumia saraka ya muda ya mfumo (/tmp au sawa). Kwa matumizi yaliyojumuishwa, hakikisha saraka ya muda ina nafasi ya kutosha na iko kwenye uhifadhi wa haraka (si iliyounganishwa kwenye mtandao, ikiwezekana).

Usafishaji: Tumia menejeria wa muktadha (with tempfile...) ili kuhakikisha usafishaji hata wakati wa hitilafu.

Uchakataji sambamba: Kazi kila moja ya uchakataji hupata faili yake ya muda. Hakuna migogoro kati ya uchakataji wa hati sambamba.

Nafasi ya diski: Faili za muda zina muda mfupi (muda wa uchakataji). Kwa <<<<<<< HEAD hati ya PDF ya 500MB, inahitaji nafasi ya muda ya 500MB wakati wa uchakataji. Kikomo cha ukubwa kinaweza kutekelezwa wakati wa kupakia ikiwa nafasi ya diski ni mdogo.

Kiolesura Kimoja cha Uchakataji: Hati za Mtoto

Uchimbaji wa hati za PDF na uchakataji wa hati za maandishi lazima ziingie katika mstari mmoja wa baadaye (kugawanya → embeddings → uhifadhi). Ili kufanikisha hili kwa "kupata kwa ID" kiolesura, vipande vya maandishi vilivyochimbwa huhifadhiwa tena kwenye mfumo kama hati za mtoto.

Mchakato wa Uchakataji na Hati za Mtoto

======= hati ya PDF ya 500MB, inahitaji nafasi ya muda ya 500MB wakati wa uchakataji. Kizuia cha ukubwa kunaweza kutekelezwa wakati wa kupakia ikiwa nafasi ya diski ni mdogo.

Kiolesura Kimoja cha Uchakataji: Hati za Watoto

Uchimbaji wa hati za PDF na uchakataji wa maandishi unahitaji kuingia kwenye mstari mmoja wa baadaye (kugawanya → maandishi → uhifadhi). Ili kufanikisha hili kwa "kupata kwa ID" kiolesura, vipande vya maandishi vilivyochimbwa huhifadhiwa tena kwenye mfumo kama hati za watoto.

Mchakato wa Uchakataji na Hati za Watoto

82edf2d (New md files from RunPod)

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]

Kifaa cha kuainisha (chunker) kina muundo mmoja wa kiungo: Pokea kitambulisho cha hati (kupitia Pulsar) Pumua yaliyomo kutoka kwa mfumo wa kumbukumbu (librarian) Igawanye katika sehemu ndogo

Haijulishi au hajali kama kitambulisho kinarejelea: Hati ya maandishi iliyopakiwa na mtumiaji Sehemu ya maandishi iliyochimbwa kutoka kwa ukurasa wa PDF Aina yoyote ya hati ya siku zijazo

<<<<<<< HEAD

Meta-data ya Hati Ndogo

=======

Meta Data ya Hati Ndogo

82edf2d (New md files from RunPod)

Panua muundo wa hati ili kufuatilia uhusiano wa mzazi/mtoto:

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

Aina za nyaraka:

document_type	Maelezo
source	Nyaraka zilizopakiwa na mtumiaji (PDF, maandishi, n.k.)
<<<<<<< HEAD
extracted	Zilizotokana na nyaraka asili (k.m., maandishi ya ukurasa wa PDF)

Nafasi za metadata:

Nafasi	Nyaraka Asili	Nyaraka Zilizotokana
id	Zilizotolewa na mtumiaji au zilizoundwa	Zilizoundwa (k.m., {parent-id}-page-{n})
parent_id	NULL	Kitambulisho cha nyaraka asili
document_type	source	extracted
kind	application/pdf, n.k.	text/plain
title	Zilizotolewa na mtumiaji	Zilizoundwa (k.m., "Ukurasa wa 3 wa Ripoti.pdf")
user	Mtumiaji aliyeidhinishwa	Sawa na nyaraka asili

API ya Maktaba kwa Nyaraka Zilizotokana

Kuunda nyaraka zilizotokana (ya ndani, hutumiwa na pdf-extractor):

| extracted | Imetokana na nyaraka ya asili (k.m., maandishi ya ukurasa wa PDF) |

Nafasi za metadata:

Nafasi	Nyaraka ya Asili	Mtoto Uliochukuliwa
id	Iliyotolewa na mtumiaji au iliyoundwa	Iliyoundwa (k.m., {parent-id}-page-{n})
parent_id	NULL	Kitambulisho cha nyaraka mama
document_type	source	extracted
kind	application/pdf, n.k.	text/plain
title	Iliyotolewa na mtumiaji	Iliyoundwa (k.m., "Ukurasa wa 3 wa Ripoti.pdf")
user	Mtumiaji aliyeidhinishwa	Sawa na nyaraka mama

API ya Maktaba kwa Nyaraka za Watoto

Kutengeneza nyaraka za watoto (ya ndani, inayotumika na pdf-extractor):

82edf2d (New md files from RunPod)

{
  "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>"
}

<<<<<<< HEAD Kwa maandishi madogo ambayo yamechukuliwa (maandishi ya kawaida ya ukurasa ni chini ya 100KB), kupakia kwa operesheni moja ni sawa. Kwa matamshi makubwa sana ya maandishi, kupakia kwa sehemu kunaweza kutumika.

Kwa maandishi madogo ambayo yamechukuliwa (maandishi ya kawaida ya ukurasa ni chini ya 100KB), kupakia kwa hatua moja ni la kukubalika. Kwa matamshi makubwa sana ya maandishi, kupakia kwa sehemu kunaweza kutumika.

82edf2d (New md files from RunPod)

Orodha ya hati za watoto (kwa ajili ya utatuzi/utawala):

<<<<<<< HEAD

======= Hati ya Matokeo

82edf2d (New md files from RunPod)

{
  "operation": "list-children",
  "parent-id": "doc-123"
}

Jibu:

{
  "children": [
    { "id": "doc-123-page-1", "title": "Page 1", "kind": "text/plain" },
    { "id": "doc-123-page-2", "title": "Page 2", "kind": "text/plain" },
    ...
  ]
}

Tabia inayoonwa na mtumiaji

Tabia ya kawaida ya list-documents:

SELECT * FROM document WHERE user = ? AND parent_id IS NULL;

Tuandishi kuu (vyanzo) pekee ndivyo yanavyoonekana kwenye orodha ya vyanzo vya mtumiaji. Vyanzo vidogo huondolewa kwa chaguo-msingi.

Bendera ya hiari ya kujumuisha-vyanzo-vidogo (kwa wasimamizi/uchunguzi):

{
  "operation": "list-documents",
  "include-children": true
}

<<<<<<< HEAD

Ufutilishaji wa Kuondoa Data kwa Kadirio

Wakati hati mama inapoondolewa, watoto wote lazima waondolewe:

Ufutilishaji Pamoja na Uharibifu wa Data

Wakati hati mama inafutwa, watoto wote lazima waondolewe:

82edf2d (New md files from RunPod)

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)

<<<<<<< HEAD

Mawazo Kuhusu Uhifadhi

Matini yaliyotolewa yana nakala sawa: Nakala asili ya PDF inahifadhiwa katika "Garage" Nakala iliyotolewa kwa kila ukurasa pia inahifadhiwa katika "Garage"

Hii inaruhusu: Kiolesura sawa cha "chunker": "Chunker" daima hupata data kwa kutumia kitambulisho Uendelezaji/jaribio tena: Inaweza kuanza tena katika hatua ya "chunker" bila kuhariri tena PDF Urekebishaji: Nakala iliyotolewa inaweza kuchunguzwa Tofauti ya majukumu: Huduma ya kuchimbua PDF na "chunker" ni huduma tofauti

Mawasilisho ya Uhifadhi

Matini yaliyotolewa yana nakala za maudhui: Nakala ya asili ya PDF inahifadhiwa katika "Garage" Nakala ya matini iliyotolewa kwa kila ukurasa pia inahifadhiwa katika "Garage"

Hii inaruhusu: Kiolesura cha kawaida cha "chunker": "Chunker" daima hupata kwa kitambulisho Uanzishaji upya/jaribio: Inaweza kuanzisha tena katika hatua ya "chunker" bila kuharibu tena PDF Urekebishaji: Matini iliyotolewa inaweza kuchunguzwa Tofauti ya majukumu: Huduma ya kutolea matini kutoka PDF na "chunker" ni huduma tofauti

82edf2d (New md files from RunPod)

Kwa PDF ya 500MB yenye kurasa 200, kwa wastani ya matini ya 5KB kwa kila ukurasa: Uhifadhi wa PDF: 500MB Uhifadhi wa matini iliyotolewa: ~1MB jumla Gharama ya ziada: ndogo sana

<<<<<<< HEAD

Matokeo ya Kuchimbua PDF

Kichunguzi cha kuchimbua PDF, baada ya kuchakata hati:

1. Hupata PDF kutoka kwa "librarian" hadi kwenye faili ya muda
2. Huchimbua matini ukurasa kwa ukurasa =======

Matokeo ya Kutoa Matini kutoka PDF

Kifaa cha kutoa matini kutoka PDF, baada ya kuchakata hati:

1. Hupokea PDF kutoka kwa "librarian" hadi faili ya muda
2. Hutoa matini ukurasa kwa ukurasa

82edf2d (New md files from RunPod)

3. Kwa kila ukurasa, huhifadhi matini iliyotolewa kama hati ndogo kupitia "librarian"
4. Hutuma kitambulisho cha hati ndogo kwa folyo ya "chunker"

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)

<<<<<<< HEAD Kifaa cha kuainisha vitapokea kitambulisho hivi vya watoto na vitawatumia kwa njia ile ile ambayo kingetumia hati ya maandishi iliyopakiwa na mtumiaji.

Sasizi za Mteja

======= Kifaa cha "chunker" hupokea kitambulisho hivi vya watoto na huviweka sawa na jinsi lingeweza kuchakata hati ya maandishi iliyopakiwa na mtumiaji.

Masasisho ya Mteja

82edf2d (New md files from RunPod)

SDK ya Python

SDK ya Python (trustgraph-base/trustgraph/api/library.py) inapaswa kushughulikia <<<<<<< HEAD vipakio vilivyogawanywa kwa njia ya moja kwa moja. Muundo wa umma haubadiliki:

vipakio vilivyogawanywa kwa njia ambayo haionyeshi. Muundo wa umma haubadiliki:

82edf2d (New md files from RunPod)

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

Kwa ndani, SDK hugundua ukubwa wa hati na hubadilisha mkakati:

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)

Arifa za maendeleo (ongezeko la hiari):

def add_document(self, ..., on_progress=None):
    """
    on_progress: Optional callback(bytes_sent, total_bytes)
    """

Hii inaruhusu programu za kiutengenezaji kuonyesha maendeleo ya kupakia bila kubadilisha API ya msingi.

Zana za CLI (Command Line Interface)

tg-add-library-document inaendelea kufanya kazi bila kubadilika:

# Works transparently for any size - SDK handles chunking internally
tg-add-library-document --file large-report.pdf --title "Large Report"

Onyesho la maendeleo la hiari linaweza kuongezwa:

tg-add-library-document --file large-report.pdf --title "Large Report" --progress
# Output:
# Uploading: 45% (225MB / 500MB)

Vifaa vya zamani vimetoolewa:

<<<<<<< HEAD tg-load-pdf - imepitwa na wakati, tumia tg-add-library-document tg-load-text - imepitwa na wakati, tumia tg-add-library-document

tg-load-pdf - yamefutwa, tumia tg-add-library-document tg-load-text - yamefutwa, tumia tg-add-library-document

82edf2d (New md files from RunPod)

Amri za utawala/uchunguzi (hiari, kipaumbele cha chini):

# 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

Haya yanaweza kuwa maboresho kwenye amri iliyopo badala ya zana tofauti.

Masuala ya Mabadiliko ya Vipimo vya API

Vipimo vya OpenAPI (specs/api/paths/librarian.yaml) vinahitaji mabadiliko kwa:

Utendaji mpya:

<<<<<<< HEAD begin-upload - Anzisha kipindi cha kupakia kwa sehemu

begin-upload - Anzisha kipindi cha kupakia sehemu

82edf2d (New md files from RunPod) upload-chunk - Pakia sehemu moja complete-upload - Kamilisha kupakia abort-upload - Ghairi kupakia get-upload-status - Angalia maendeleo ya kupakia list-uploads - Orodha ya kupakia ambayo hayaja kamili kwa mtumiaji stream-document - Kuchukua hati kwa njia ya utiririshaji add-child-document - Hifadhi maandishi yaliyotolewa (ya ndani) list-children - Orodha ya hati za chini (ya msimamizi)

Utendaji uliorekebishwa:

list-documents - Ongeza parameter include-children

<<<<<<< HEAD Muundo mpya:

Vipimo vipya:

82edf2d (New md files from RunPod)

ChunkedUploadBeginRequest ChunkedUploadBeginResponse ChunkedUploadChunkRequest ChunkedUploadChunkResponse UploadSession UploadProgress

Mabadiliko ya vipimo vya WebSocket (specs/websocket/):

Nakala utendaji wa REST kwa wateja wa WebSocket, na kuwezesha <<<<<<< HEAD maendeleo ya muda halisi wakati wa kupakia.

maendeleo ya wakati halisi wakati wa kupakia.

82edf2d (New md files from RunPod)

Mambo ya Kuzingatia ya Uzoefu wa Mtumiaji

Mabadiliko ya vipimo vya API yanawezesha maboresho ya upande wa mbele:

Kiolesura cha maendeleo ya kupakia: Pampu ya maendeleo ya kuonyesha sehemu zilizopakwa Muda uliokadiri wa kupakia Uwezo wa kusitisha/kuendeleza

Kupona kwa makosa: <<<<<<< HEAD Chaguo la "Endeleza kupakia" kwa kupakia ambacho kimekatika Orodha ya kupakia ambayo hayaja kamili wakati wa kuunganisha tena

Ushughulikiaji wa faili kubwa: Uchunguzi wa ukubwa wa faili kwenye upande wa mteja Kupakia kwa sehemu kiotomatiki kwa faili kubwa

Chaguo la "endelea kupakia" kwa kupakia ambacho kimekatika Orodha ya kupakia ambayo hayaja kamili wakati wa kuunganisha tena

Usimamizi wa faili kubwa: Uchunguzi wa ukubwa wa faili kwenye upande wa mteja Kupakia kiotomatiki kwa sehemu kwa faili kubwa

82edf2d (New md files from RunPod) Maelezo wazi wakati wa kupakia kwa muda mrefu

Maboresho haya ya uzoefu wa mtumiaji yanahitaji kazi ya upande wa mbele inayong'wa na vipimo vya API vilivyoboreshwa.