Sistem OCR
Sistem OCR mengonversi PDF hasil pemindaian, gambar, halaman dengan banyak tulisan tangan, dan dokumen identitas Indonesia terstruktur menjadi teks yang dapat dibaca mesin sebelum teks masuk ke retrieval. Sistem ini di-host sendiri di Huawei Cloud dan tidak memanggil API OCR eksternal.
Halaman ini menjelaskan bagaimana OCR terintegrasi dalam ingesti. Kontrak publik untuk unggah, batch, ingesti teks, status dokumen, dan error ditentukan dalam Referensi API Ingesti dan Dokumen. Jangan menganggap tabel arsitektur di bawah sebagai skema request atau response yang lengkap.
Tanggung Jawab
- Menerima dokumen yang akan diproses OCR dari API backend dan layanan ingesti yang sama seperti dokumen born-digital.
- Mengonversi file yang diunggah menjadi gambar halaman jika diperlukan.
- Menjalankan OCR melalui endpoint OCR yang dikonfigurasi.
- Mempertahankan nomor halaman, jenis blok, rentang teks, confidence, nama model OCR, dan metadata keterbandingan confidence.
- Mengarahkan output OCR dengan confidence rendah atau yang tidak dapat dibandingkan ke status review alih-alih membuat embedding sebagai konten terindeks.
- Menyimpan teks dan metadata hasil OCR di PostgreSQL/pgvector serta file mentah/sumber di object storage yang kompatibel dengan OBS.
- Mengaudit operasi OCR dan hasil review setelah workflow human review diterapkan.
Titik Masuk Unggah
Pengguna tidak mengunggah langsung ke subsistem OCR. Mereka mengunggah ke permukaan ingesti backend, lalu backend mengarahkan file ke OCR ketika parser mendeteksi jalur gambar/pindaian. Tabel ini hanya merangkum tanggung jawab perutean; gunakan Referensi API Ingesti dan Dokumen untuk field, kode status, body error, perintah curl, dan contoh TypeScript.
| Titik masuk | Kasus penggunaan | Perilaku arsitektur |
|---|---|---|
POST /documents | Unggah multipart manual dari frontend, tool unggah batch, atau klien API | Menyimpan file mentah melalui batas ingesti, melacak status dokumen/job, dan menjadwalkan satu jalur pemrosesan untuk setiap file |
POST /documents/txt | Ingesti teks inline untuk teks born-digital | Melewati OCR dan mengindeks teks langsung melalui layanan ingesti normal |
POST /ocr | Ekstraksi khusus OCR tanpa ingesti | Menjalankan pipeline parse-first→OCR-fallback yang sama pada file yang diunggah dan mengembalikan teks hasil ekstraksi, confidence per blok, nama model, dan keterbandingan confidence secara inline — tidak ada yang disimpan, di-chunk, dibuatkan embedding, atau diindeks. Memungkinkan operator memeriksa secara persis hasil OCR untuk sebuah dokumen sebelum memutuskan untuk mengingestinya. |
POST /ingestion/batch | Ingesti massal dari prefix atau manifest object storage | Mengantrekan pekerjaan berdasarkan object key yang sudah ada; worker mengambil byte dari storage |
| Source connectors | Ingesti JDIH, OpenData, PPID, SatuData | Connector memanggil layer API/service yang sama, bukan melewati ingesti |
Jalur POST /ocr menggunakan kembali keputusan parse/OCR pada ingesti (parse-first, lalu render-and-OCR ketika output parser tidak dapat digunakan), tetapi berhenti pada ekstraksi — jalur ini adalah permukaan inspeksi read-only di balik tab OCR pada console. Field dan bentuk error tersedia dalam Referensi API Ingesti dan Dokumen.
Workflow OCR End-to-end
Detail pipeline pemrosesan
1. Validasi dan penyimpanan unggahan
Jalur unggah memvalidasi file sebelum penyimpanan, menolak jenis yang tidak didukung, menegakkan batas ukuran file dan batch, serta melindungi dari input archive-bomb. Untuk storage yang kompatibel dengan S3, seam yang sama berfungsi untuk MinIO lokal dan Huawei OBS. Kegagalan unggah multipart sebagian memicu penghapusan objek sebagai kompensasi sehingga objek yang sudah tersimpan tidak menjadi storage yatim.
2. Strategi parse-first
Layanan ingesti menggunakan parser born-digital terlebih dahulu. Docling Slim adalah boundary yang dipilih untuk PDF, DOCX, PPTX, XLSX, CSV, MD, dan HTML; TXT diuraikan secara lokal; gambar terpindai dan konten yang akan diproses OCR diarahkan ke layanan OCR.
3. Pemicu fallback OCR
OCR berjalan ketika dokumen berupa gambar, parser tidak dapat menangani format gambar, hasil parse PDF/gambar kosong, atau teks PDF/gambar hasil parse berada di bawah ambang kualitas rendah yang dikonfigurasi. Format tak didukung yang bukan gambar gagal sebagai tidak dapat diindeks, bukan dikirim ke OCR.
4. Eksekusi OCR PDF dan gambar
Halaman PDF dirender ke PNG dan diproses satu per satu. Unggahan gambar diproses sebagai satu gambar. Klien OCR menerima payload gambar base64 dan mengembalikan teks, confidence rata-rata, nama model, keterbandingan confidence, dan blok opsional.
5. Persistensi chunk hasil OCR
Teks OCR dinormalisasi menjadi blok dokumen terurai. Chunk membawa ocr_confidence, page_number, metadata.ocr_model, metadata.ocr_confidence_comparable_with_prod, dan metadata.ocr_confidence_threshold. Chunk yang ditandai needs_ocr_review tidak memiliki embedding dan dikecualikan dari retrieval semantik dan leksikal.
Model dan teknologi
| Komponen | Teknologi | Catatan |
|---|---|---|
| Model OCR | PaddleOCR-VL-0.9B (produksi: CPU, 1 worker, ~12–13 dtk per halaman pindaian — audit produksi firstmate 2026-10-07) | Perubahan model adalah event validasi berversi karena skor confidence OCR dapat berubah antarversi model. |
| Rendering PDF | PDFium | Mengonversi halaman PDF menjadi byte gambar sebelum OCR. |
| Wrapper OCR | Layanan OCR FastAPI di balik endpoint yang dapat dikonfigurasi | Menjaga kode aplikasi dikonfigurasi melalui environment, bukan di-hardcode. |
| Penyajian model | CPU di produksi; profil GPU berbasis vLLM untuk OCR-VL jika dikonfigurasi secara lokal | OCR produksi berjalan CPU (peralihan GPU disetujui untuk window sepi; #829 merged, belum deployed). |
| Storage | Huawei OBS / seam yang kompatibel dengan S3 | File mentah dan artefak yang diproses berada di object storage. |
| Penyimpanan metadata | PostgreSQL + pgvector | Menyimpan metadata dokumen/chunk, confidence OCR, status, embedding, data indeks leksikal, percakapan, dan log audit. |
Penilaian confidence
Setiap hasil OCR mengekspos mean_confidence. Sebuah chunk diindeks hanya ketika confidence gerbangnya berada pada atau di atas ocr_confidence_threshold, yang secara default bernilai 0.85; semua yang berada di bawah diarahkan ke review.
Skor yang diberikan ke gerbang tersebut harus tetap dapat dibandingkan lintas versi model OCR. Ketika confidence milik backend sendiri tidak dapat dibandingkan dengan produksi — profil PaddleOCR-VL yang dipatok melaporkan confidence_scores_comparable_with_prod=false dan confidence blok 0.0 untuk setiap halaman — jalur ingesti menghitung confidence gerbang dari teks output OCR (src/aceh_rag/ocr_quality.py), dan mencatat skor mentah backend sebagai ocr_raw_mean_confidence untuk provenansi. ADR-0005 mengatur sumbu sinyal turunan, kalibrasinya, dan batasan yang telah diketahui.
Penanganan error
Tabel ini menjelaskan penanganan arsitektural di dalam OCR dan ingesti. Kode status HTTP publik, payload error, dan transisi status yang terlihat saat retry merupakan bagian dari Referensi API Ingesti dan Dokumen.
| Kegagalan | Penanganan |
|---|---|
| Format non-OCR yang tidak didukung | Request atau dokumen gagal sebelum pengindeksan |
| Teks kosong setelah parse/OCR | Dokumen gagal sebagai tidak dapat diindeks |
| Input archive-bomb atau terlalu besar | Ditolak sebelum parsing/OCR menghabiskan sumber daya |
| Kegagalan object storage | Kegagalan unggah dipetakan melalui kontrak API ingesti, dan objek yang sudah tersimpan dihapus berdasarkan upaya terbaik |
| OCR dengan confidence rendah | Status chunk/dokumen menjadi needs_ocr_review; tidak ada embedding yang disimpan |
| Confidence backend yang tidak dapat dibandingkan | Confidence gerbang dihitung dari teks output OCR dan dinilai terhadap ambang batas yang sama (ADR-0005) |
| Kegagalan sementara worker | Loop drain mencatat log, melakukan backoff, dan berlanjut alih-alih mati diam-diam |
Verifikasi manusia dan workflow review
Backend menghasilkan status yang dapat ditinjau: job unggah dapat melaporkan needs_review, chunk dapat berstatus needs_ocr_review, dan chunk tersebut dikecualikan dari retrieval hingga disetujui.
Workflow review yang ditargetkan:
Persetujuan harus mempertahankan provenansi. Chunk yang dikoreksi mempertahankan confidence OCR dan metadata model asli, menambahkan metadata review, serta menulis event audit dengan detail aktor, tindakan, entitas, permintaan, metadata, dan timestamp.
Arsitektur OCR
Layer engine OCR diisolasi dari klien publik. Klien publik berinteraksi dengan API unggah/status/query; worker dan layanan OCR berkomunikasi di dalam jaringan backend/cloud.