Ingesti Data
Ingesti data mempersiapkan dokumen pemerintah mentah untuk retrieval dan penjawaban berbasis sumber. Ingesti memvalidasi input, menyimpan byte mentah, mem-parse atau menjalankan OCR pada konten, mengekstrak metadata, memecah teks menjadi chunk, membuat embedding untuk chunk yang disetujui, membangun teks leksikal, mempersistenkan baris, dan menyediakan status pemrosesan.
Halaman ini menjelaskan arsitektur ingesti dan keputusan siklus hidup. Untuk field request dan response, kode status, body error, perintah curl, dan contoh TypeScript, gunakan Referensi API Ingesti dan Dokumen. Ringkasan arsitektur di bawah bukan kontrak wire yang lengkap.
Sumber yang didukung
Model data mengenali lima jenis sumber: JDIH, OpenData, PPID,
SatuData, dan upload.
| Sumber | Penanganan saat ini |
|---|---|
| JDIH | Dokumen hukum mengikuti jalur parse → fallback OCR → chunk → embed → index. |
| PPID | Dokumen informasi publik mengikuti jalur ingesti yang sama; ekstraksi PDF mengikuti referensi routing di bawah. |
upload | File manual atau integrasi menggunakan API unggah dan batch. |
| OpenData | Event terstruktur yang kompatibel dengan kontrak dilewati sebelum parse/chunk/embed/index; pembacaan Open Data saat query menjadi sumber kebenaran ketika diaktifkan. |
| SatuData | Event terstruktur yang kompatibel dengan kontrak dilewati sebelum parse/chunk/embed/index; pembacaan Open Data saat query menjadi sumber kebenaran ketika diaktifkan. |
Pelewatan sumber terstruktur ini disengaja: membuat embedding dari snapshot portal akan
menciptakan salinan pesaing yang usang. Worker mencatat hasil terminal skipped
untuk job unggah internal dan memancarkan indexed/skipped di wire (_TERMINAL_INTERNAL_EVENT, src/aceh_rag/kafka/kafka_ingestion.py).
Worker Kafka produksi dibuat ulang pada image API yang di-deploy (2cc9a417,
audit produksi firstmate 2026-10-07); worker menjalankan kontrak consumer
doc.uploaded di partner-events.
Format yang didukung
Docling Slim adalah batas parser born-digital untuk PDF, DOCX, PPTX, XLSX, CSV, MD, dan HTML. TXT ditangani secara lokal. Gambar dan dokumen hasil pemindaian diarahkan melalui OCR.
Untuk routing PDF ke OCR, lihat orkestrasi model. Untuk ekstraksi tabel native-first dan fallback OCR, lihat ADR-0012.
Titik masuk ingesti
Tabel di bawah menyebutkan titik masuk arsitektural dan tanggung jawab setiap jalur. Tabel ini sengaja tidak mencantumkan payload, body response, kode status, dan bentuk error yang tepat; semua itu berada dalam Referensi API Ingesti dan Dokumen.
| Metode | Endpoint atau seam | Tanggung jawab arsitektur |
|---|---|---|
| Unggah multipart manual | POST /documents | Menerima file pengguna atau integrasi, mempersistenkan byte mentah, membuat pekerjaan ingesti yang statusnya dilacak, dan menjadwalkan pemrosesan per file |
| Teks inline | POST /documents/txt | Mengindeks teks yang disediakan langsung oleh caller tepercaya tanpa merutekannya melalui OCR |
| Prefix object storage batch | POST /ingestion/batch dengan prefix | Menemukan objek di bawah prefix yang dikonfigurasi dan mengantrekan objek korpus yang cocok |
| Manifest batch | POST /ingestion/batch dengan key eksplisit | Mengantrekan object key yang dipilih dari object store yang dikonfigurasi |
| Integrasi API | API Ingesti melalui batas FastAPI | Memungkinkan integrasi eksternal memasuki jalur validasi, storage, queueing, dan worker yang sama seperti unggahan frontend |
| Ingesti terjadwal | Scheduler yang memanggil API atau connector batch | Menggunakan kembali API batch/sumber yang sama seperti integrasi lain |
| Ingesti streaming | Pemrosesan worker Kafka/DMS | Mendukung adapter asinkron khusus sumber tanpa melewati aturan validasi dan indexing |
Pipeline end-to-end
Untuk dokumen OCR, setiap halaman di bawah ambang batas atau halaman yang hilang dikecualikan dari pengindeksan.
Verdik tingkat dokumen needs_review menggunakan fraksi halaman gagal yang dikonfigurasi,
sehingga satu halaman sampul yang lemah tidak otomatis mengarantina pindaian yang sebenarnya
masih dapat digunakan; halaman yang hilang selalu memaksa review. GET /documents mengekspos
chunk_count, indexed_chunk_count, dan parked_chunk_count sehingga klien dapat
membedakan hasil review yang masih dapat diambil sebagian dari dokumen tanpa chunk
terindeks.
Validasi
Validasi berlangsung sebelum penyimpanan, sebelum parsing, dan sebelum pengindeksan.
| Tahap | Validasi |
|---|---|
| Request unggah | API key, ekstensi/jenis yang didukung, ukuran file, ukuran batch |
| Object storage | Error backend dipetakan ke error domain; pembersihan unggahan sebagian mencegah objek yatim |
| Pesan worker | Field wajib: ID dokumen, SHA-256 konten, nama file, jenis sumber, versi sumber |
| Byte mentah | Batas archive-bomb dijalankan sebelum parse/OCR |
| Teks hasil parse | Dokumen kosong ditolak |
| Teks chunk | Konten dengan sinyal rendah/sampah diarahkan ke review sebelum embedding |
| Chunk OCR | Gerbang ambang batas pada confidence yang dapat dibandingkan lintas versi model (ADR-0005) |
| Repository | Ordinal duplikat ditolak; chunk terindeks memerlukan embedding; chunk needs_ocr_review dikecualikan dari retrieval |
Ekstraksi dan persistensi metadata
Model ingesti menyimpan metadata tingkat dokumen dan tingkat chunk.
Baris dokumen berisi judul, jenis sumber, format, versi sumber, timestamp ingesti, status, dan JSON metadata. Baris chunk berisi ID dokumen, ordinal, teks, embedding, teks leksikal, lexical_tsv yang dihasilkan, confidence OCR, status chunk, nomor halaman, jalur bagian, referensi hukum, rentang karakter, dan JSON metadata.
Layanan ingesti saat ini mencatat metadata parser, ambang batas confidence OCR, hash konten, source key, model OCR, keterbandingan confidence, serta field rentang halaman/sumber.
Chunking dan indexing
Arsitektur menargetkan jendela sekitar 512 token dengan overlap. Layanan menggunakan ukuran chunk yang dapat dikonfigurasi dan mempertahankan rentang karakter. Chunk yang disetujui mendapatkan embedding dan teks leksikal. PostgreSQL menyimpan data indeks vektor HNSW dan vektor full-text search yang dihasilkan. Aturan penghapusan NUL dan konsistensi offset dijelaskan di referensi persistensi metadata berbahasa Inggris.
Desain storage
| Storage | Data |
|---|---|
| Object storage OBS / yang kompatibel dengan S3 | Unggahan mentah, objek korpus batch, artefak terproses di masa depan |
PostgreSQL documents | Identitas dokumen stabil dan metadata sumber |
PostgreSQL chunks | Teks, embedding, teks leksikal, confidence OCR, metadata sitasi |
| pgvector HNSW | Retrieval semantik atas embedding yang disetujui |
| PostgreSQL GIN FTS | Retrieval leksikal atas teks leksikal yang disetujui |
| Redis / penyimpanan status queue | Status job di jalur lokal/in-memory, target DCS di produksi |
| Kafka / DMS | Event pemrosesan dokumen asinkron dalam arsitektur target |
Idempotensi dan re-ingesti
Pesan worker membawa content_sha256, dan identitas dokumen menggunakan jenis sumber, versi sumber, dan source key yang stabil. Untuk ingesti batch, object key lengkap digunakan sebagai source key sehingga file dengan nama dasar yang sama di folder berbeda tetap disimpan sebagai dokumen terpisah. Mengingesti ulang sumber yang sama menggantikan chunk usang secara transaksional.
Konten yang identik byte dideduplikasi berdasarkan checksum kontennya. Sebelum parse/chunk/embed, layanan mencari content_sha256 yang masuk dan mengembalikan dokumen yang sudah ada ketika menemukannya. Karena worker konkuren dapat sama-sama melewatkan lookup check-then-act tersebut, backstop otoritatif membuat deduplikasi deterministik: partial functional unique index pada documents atas content_sha256 dan sourceVersion yang diekstrak (migration 0006_document_content_sha256_dedup) mengubah insert duplikat yang bersaing menjadi hasil deduplikasi yang sama, bukan dokumen kedua atau 500. Index hanya dibuat pada tabel documents AI-engine milik kita, dan sourceVersion yang berbeda adalah re-ingesti yang disengaja dan boleh hidup berdampingan. Lihat src/aceh_rag/postgres_repository.py.
Ketersediaan bagi layanan AI
Dokumen menjadi tersedia bagi layanan AI hanya setelah setidaknya satu chunk yang disetujui diindeks. Chunk needs_ocr_review dipersistenkan untuk review, tetapi dikecualikan dari retrieval semantik dan leksikal. Permukaan pencarian dan jawaban hanya dapat menggunakan chunk terindeks yang disetujui; field request yang tepat, bentuk sitasi, perilaku status, siklus hidup SSE, dan contoh-contohnya ditentukan dalam Referensi API Query dan Pencarian.
Status operasional
| Status | Makna |
|---|---|
queued | Unggah diterima dan menunggu pemrosesan worker |
processing | Worker telah memulai ingesti |
done | Pemrosesan selesai dan chunk yang disetujui telah dipersistenkan |
needs_review | Review manusia diperlukan, biasanya terkait confidence OCR |
failed / permanently_failed | Pemrosesan gagal dan tidak akan selesai tanpa tindakan operator |
retrying | Worker akan mencoba lagi setelah kegagalan sementara |
skipped | Pekerjaan duplikat atau yang sudah diproses dilewati |