fix: make OCR portable and reliable across AMD64 and ARM64 (#519)

* fix: make OCR portable and reliable

* fix: harden OCR installation portability

* fix: pin OCR partials across downloads

* fix: make OCR execution reliably asynchronous

* fix: harden OCR portability and docs routes

* fix: preserve decoder and docs safeguards

apps/docs/th/api/ai.md

@@ -1,18 +1,26 @@
 ---
 description: "เอกสารอ้างอิงเอนจิน AI พร้อมเครื่องมือ ML ในเครื่องทั้งหมด การลบพื้นหลัง การขยายภาพ OCR การตรวจจับใบหน้า การกู้คืนภาพถ่าย และอื่น ๆ"
-i18n_source_hash: 14728c1dcd05
-i18n_provenance: machine
-i18n_output_hash: 76c10fa3ca33
+i18n_output_hash: ebf48f7a0230
+i18n_source_hash: aa9a56cdddc7
+i18n_provenance: human
 ---
 
 # เอกสารอ้างอิงเอนจิน AI {#ai-engine-reference}
 
-แพ็กเกจ `@snapotter/ai` เชื่อมโยง Node.js เข้ากับ **Python sidecar แบบถาวร** สำหรับการดำเนินการ ML ทั้งหมด กระบวนการ dispatcher จะคงอยู่ระหว่างคำขอเพื่อประสิทธิภาพการเริ่มต้นแบบ warm-start ที่รวดเร็ว NVIDIA CUDA จะถูกตรวจจับโดยอัตโนมัติเมื่อเริ่มต้นและใช้งานเมื่อพร้อมใช้งาน มิฉะนั้นเครื่องมือ AI จะทำงานบน CPU
+แพ็คเกจ `@snapotter/ai` ประสานเครื่องมือดั้งเดิมและรันไทม์ Python สำหรับการดำเนินการ ML ในเครื่อง เครื่องมือ ML ส่วนใหญ่ใช้ Python sidecar แบบถาวรเพื่อการวอร์มสตาร์ทที่รวดเร็ว OCR ถูกแยกออกจากกันโดยเจตนา: `fast` เรียกใช้ไบนารี Tesseract ดั้งเดิม ในขณะที่ `balanced` และ `best` ใช้ JSONL dispatcher แบบถาวรที่ปักหมุดไว้กับรุ่น RapidOCR ที่ไม่เปลี่ยนรูปที่ใช้งานอยู่ภายใต้ `/data/ai/v3` แต่ละคำขอจะมี generation lease ในระหว่างการอัพเกรด SnapOtter รัน smoke test บนตัวเลือกก่อนเปิดใช้งาน โดยจะสลับไปที่ dispatcher ใหม่แบบอะตอมมิก จากนั้นจึงระบายรุ่นเก่าก่อน garbage collection
+
+NVIDIA CUDA ถูกตรวจพบโดยอัตโนมัติและใช้งานโดยรันไทม์ที่รองรับ OCR ใช้ CPU บนทุกโฮสต์ รวมถึงระบบที่มี GPU NVIDIA โดยหลีกเลี่ยง CUDA และการเชื่อมต่อไดรเวอร์สำหรับเครื่องมือนี้
 
 การเร่งความเร็ว iGPU ของ Intel/AMD ผ่าน VA-API, Quick Sync หรือ OpenCL ยังไม่รองรับสำหรับการอนุมาน AI ในปัจจุบัน การแมป `/dev/dri` เข้าไปในคอนเทนเนอร์ไม่ได้เร่งความเร็วเครื่องมือ Python sidecar เหล่านี้ เว้นแต่จะมี NVIDIA GPU ที่รองรับ CUDA พร้อมใช้งาน
 
 เครื่องมือ AI แบบ Python sidecar จำนวน 19 รายการครอบคลุมสี่โมดาลิตี (ภาพ เสียง วิดีโอ เอกสาร) พร้อมด้วยเครื่องมืออีก 2 รายการที่มีความสามารถ AI เสริม โมเดลทั้งหมดทำงานในเครื่อง ไม่ต้องใช้อินเทอร์เน็ตหลังจากดาวน์โหลดโมเดลครั้งแรก
 
+
+<!-- korean-ocr-contract:start -->
+::: info ความเข้ากันได้ของ OCR ภาษาเกาหลี
+OCR แบบเร็วรองรับ `auto`, `en`, `de`, `es`, `fr`, `zh` และ `ja` แต่ไม่รองรับภาษาเกาหลี (`ko`) ภาษาเกาหลีต้องใช้แพ็ก OCR แบบแม่นยำและ `balanced` หรือ `best` แพ็กทำงานบนคอนเทนเนอร์ Linux amd64 และ arm64 อย่างเป็นทางการ รวมถึงโฮสต์ NVIDIA ซึ่ง OCR ยังคงทำงานบน CPU ระบบที่ไม่รองรับจะส่งคืนข้อผิดพลาดความเข้ากันได้อย่างชัดเจนและไม่ย้อนกลับไปใช้ `fast` โดยเงียบ ๆ ภาษาเกาหลีร่วมกับ `fast` หรือนามแฝงเดิม `tesseract` จะถูกปฏิเสธก่อนเข้าคิวด้วย `FEATURE_INCOMPATIBLE` และ `fast-korean-unsupported`
+:::
+<!-- korean-ocr-contract:end -->
 ## สถาปัตยกรรม {#architecture}
 
 ```
@@ -22,15 +30,17 @@ Node.js Tool Route
  @snapotter/ai bridge.ts
       | (stdin/stdout JSON + stderr progress events)
       v
- Python dispatcher (persistent process, "ai" profile)
+ +-- Native Tesseract + Ghostscript (fast image/PDF OCR)
+ |
+ +-- Isolated OCR runtime (persistent JSONL dispatcher)
+ |     `-- RapidOCR + ONNX Runtime CPU + pinned PP-OCR models
+ |
+ `-- Python dispatcher (persistent process, "ai" profile)
       |
       |-- remove_bg.py        (rembg / BiRefNet)
       |-- upscale.py          (RealESRGAN)
       |-- inpaint.py          (LaMa ONNX)
       |-- outpaint.py         (LaMa canvas expansion)
-      |-- ocr.py              (PaddleOCR / Tesseract)
-      |-- ocr_pdf.py          (page-by-page document OCR)
-      |-- ocr_preprocess.py   (image enhancement for OCR)
       |-- detect_faces.py     (MediaPipe)
       |-- face_landmarks.py   (MediaPipe landmarks)
       |-- enhance_faces.py    (GFPGAN / CodeFormer)
@@ -52,7 +62,7 @@ Node.js Tool Route
 
 Docker image มาพร้อมกับแอปพลิเคชันบวกกับรันไทม์ทั่วไป ไฟล์เก็บถาวรของโมเดลขนาดใหญ่จะถูกดาวน์โหลดตามความต้องการลงในโวลุ่ม `/data/ai` แบบถาวร แล้วนำกลับมาใช้ซ้ำโดยทุกเครื่องมือที่ต้องการ หากติดตั้งชุดฟีเจอร์แล้วเนื่องจากมีเครื่องมืออื่นต้องการใช้ การเปิดใช้งานเครื่องมือใหม่ที่ต้องพึ่งพาชุดนั้นจะไม่ดาวน์โหลดชุดฟีเจอร์นั้นซ้ำอีก
 
-เครื่องมือ AI แต่ละรายการต้องมีชุดฟีเจอร์ตั้งแต่หนึ่งชุดขึ้นไปก่อนจึงจะทำงานได้ UI ของผู้ดูแลระบบติดตั้งตามเครื่องมือผ่าน `POST /api/v1/admin/tools/:toolId/features/install` ซึ่งจะแยกรายการชุดฟีเจอร์ทั้งหมด ข้ามชุดที่ติดตั้งแล้ว และจัดคิวเฉพาะการดาวน์โหลดที่ขาดหายไปเท่านั้น ตัวอย่างเช่น การเปิดใช้งาน Passport Photo บนอินสแตนซ์ใหม่จะจัดคิว `background-removal` และ `face-detection` แต่การเปิดใช้งานหลังจากติดตั้ง Background Removal แล้วจะจัดคิวเฉพาะ `face-detection` เท่านั้น
+เครื่องมือ AI ส่วนใหญ่จำเป็นต้องมีชุดคุณลักษณะตั้งแต่หนึ่งชุดขึ้นไปก่อนจึงจะสามารถทำงานได้ UI ผู้ดูแลระบบจะติดตั้งโดยใช้เครื่องมือผ่าน `POST /api/v1/admin/tools/:toolId/features/install` ซึ่งจะแก้ไขรายการบันเดิลทั้งหมด ข้ามบันเดิลที่ติดตั้งไว้แล้ว และจัดคิวเฉพาะการดาวน์โหลดที่ขาดหายไป ตัวอย่างเช่น การเปิดใช้งาน Passport Photo บนอินสแตนซ์คิวใหม่ `background-removal` และ `face-detection` เปิดใช้งานได้หลังจากติดตั้งการลบพื้นหลังแล้วเท่านั้น คิว `face-detection` OCR เป็นข้อยกเว้น เนื่องจาก `fast` ไม่ต้องการแพ็ก ติดตั้งรันไทม์ที่แม่นยำซึ่งเป็นทางเลือกผ่าน UI หรือ `POST /api/v1/admin/features/ocr/install`
 
 | ชุดฟีเจอร์ | ขนาด | กลุ่ม dependency ที่ใช้ร่วมกัน | เครื่องมือที่ใช้ |
 |--------|------|-------------------------|-------------------|
@@ -61,7 +71,7 @@ Docker image มาพร้อมกับแอปพลิเคชันบ
 | `object-eraser-colorize` | 1-2 GB | LaMa inpainting/outpainting และ DDColor | erase-object, colorize, ai-canvas-expand |
 | `upscale-enhance` | 5-6 GB | RealESRGAN, GFPGAN / CodeFormer, denoising | upscale, enhance-faces, noise-removal |
 | `photo-restoration` | 4-5 GB | ไปป์ไลน์ซ่อมรอยขีดข่วนและกู้คืน | restore-photo |
-| `ocr` | 5-6 GB | สแตก PaddleOCR / Tesseract OCR | ocr, ocr-pdf |
+| `ocr` | ~208-234 ดาวน์โหลด MiB / ~409-488 ติดตั้ง MiB แล้ว | อุปกรณ์เสริม RapidOCR 3.9.1, ONNX Runtime 1.20.1 และรุ่น PP-OCR ที่ปักหมุดไว้ | ocr, ocr-pdf (`balanced` และ `best` เท่านั้น) |
 | `transcription` | ~600 MB | โมเดลแปลงเสียงเป็นข้อความ faster-whisper | transcribe-audio, auto-subtitles |
 
 เครื่องมือที่มี dependency ข้ามชุดฟีเจอร์:
@@ -71,7 +81,17 @@ Docker image มาพร้อมกับแอปพลิเคชันบ
 | `passport-photo` | `background-removal`, `face-detection` | ลบพื้นหลัง แล้วใช้จุดสังเกตใบหน้าจัดกรอบการครอปให้เป็นไปตามกฎของรูปหนังสือเดินทางและรูปบัตรประจำตัว |
 | `enhance-faces` | `upscale-enhance`, `face-detection` | ตรวจจับใบหน้าก่อนรันการปรับปรุงด้วย GFPGAN หรือ CodeFormer บนบริเวณใบหน้าที่เลือก |
 
-เครื่องมือจะพร้อมใช้งานเฉพาะเมื่อติดตั้งชุดฟีเจอร์ที่จำเป็นครบทุกชุดแล้ว การติดตั้งบางส่วนถือว่าใช้ได้และจัดการแบบเพิ่มทีละส่วน ชุดที่ติดตั้งแล้วจะถูกนำกลับมาใช้ซ้ำ ชุดที่ขาดหายไปจะแสดงเป็นการดาวน์โหลด และการติดตั้งที่จัดคิวไว้จะทำงานทีละรายการเพื่อไม่ให้มีการแก้ไขสภาพแวดล้อม Python ที่ใช้ร่วมกันพร้อมกัน
+เครื่องมือจะใช้งานได้เมื่อมีการติดตั้งบันเดิลที่จำเป็นทั้งหมดแล้ว ยกเว้น OCR: ระดับ `fast` ในตัวยังคงใช้งานได้โดยไม่มีแพ็กเสริม OCR การติดตั้งบางส่วนนั้นถูกต้องและได้รับการจัดการทีละส่วน: บันเดิลที่ติดตั้งจะถูกนำมาใช้ซ้ำ บันเดิลที่ขาดหายไปจะแสดงเป็นการดาวน์โหลด และการติดตั้งที่เข้าคิวจะทำงานทีละรายการ ดังนั้นสภาพแวดล้อม Python ที่ใช้ร่วมกันจะไม่ถูกแก้ไขพร้อมกัน
+
+### การติดตั้งรันไทม์ OCR ที่แม่นยำ {#accurate-ocr-runtime-installation}
+
+แพ็ก OCR ที่แม่นยำคือรันไทม์เฉพาะแพลตฟอร์มสำหรับคอนเทนเนอร์ Linux amd64 หรือ Linux arm64 อย่างเป็นทางการ รุ่น amd64 ใช้ Python 3.12; รุ่น arm64 ใช้ Python 3.11 ทั้งสองบิลด์รัน RapidOCR ผ่าน ONNX Runtime's `CPUExecutionProvider` ดังนั้นแพ็กเดียวกันจึงใช้ได้กับโฮสต์ CPU เท่านั้นและ NVIDIA Docker รันไทม์ที่ถูกต้องต้องใช้หน่วยความจำที่มีประสิทธิภาพอย่างน้อย 4 GiB: ขีดจำกัดคอนเทนเนอร์ cgroup ที่กำหนดค่าไว้ ไม่เช่นนั้นหน่วยความจำโฮสต์ ระบบที่ต่ำกว่าความเข้ากันได้ขั้นต่ำที่ลงนามไว้จะถูกปฏิเสธก่อนที่จะดาวน์โหลด ข้อกำหนดนี้ใช้ไม่ได้กับ Fast OCR ในตัว การสร้าง Bare-metal ถูกปฏิเสธเนื่องจาก libc และ Python ABI ไม่สามารถอนุมานได้อย่างปลอดภัย Fast OCR ยังคงใช้งานได้เมื่อโฮสต์จัดเตรียม Tesseract และ Ghostscript
+
+อาร์ติแฟกต์ทางเลือกมีการบีบอัดประมาณ 208-234 MiB และแตก 409-488 MiB ขึ้นอยู่กับสถาปัตยกรรม ดัชนีที่เซ็นชื่อจะผูกจำนวนไบต์ที่ถูกบีบอัดและแยกออกมาที่แน่นอนซึ่งบังคับใช้โดยโปรแกรมติดตั้ง Tesseract ในตัวเพิ่ม MiB ประมาณ 25 ภาพให้กับอิมเมจอย่างเป็นทางการ และไม่ต้องใช้ไฟล์ใน `/data/ai`
+
+การติดตั้งแบบออนไลน์จะดึงดัชนีการเผยแพร่ที่ลงนามและส่วนที่ระบุถึงเนื้อหาที่แน่นอนสำหรับแพลตฟอร์มปัจจุบัน SnapOtter ตรวจสอบลายเซ็นดัชนี Ed25519 ขนาดอาร์ติแฟกต์ การย่อย SHA-256 การย่อยโมเดล เส้นทาง โหมดไฟล์ และ smoke test ที่จัดฉาก ก่อนที่จะเปิดใช้งานเจเนอเรชั่นใหม่แบบอะตอมมิก การติดตั้งที่ล้มเหลวจะทำให้รุ่นที่มีประสิทธิภาพก่อนหน้านี้ใช้งานได้
+
+สำหรับการติดตั้งแบบ air-gapped ให้อัปโหลดทั้ง `ocr-runtime-index.json` ของรีลีสและไฟล์รันไทม์ OCR ที่ตรงกันไปยัง `POST /api/v1/admin/features/import` โดยใช้ฟิลด์หลายส่วนที่ชื่อ `index` และ `archive` การนำเข้าแบบออฟไลน์จะใช้การตรวจสอบลายเซ็น แฮช การดึงข้อมูล ความเข้ากันได้ และการทดสอบควันแบบเดียวกันกับการติดตั้งแบบออนไลน์ ไฟล์เก็บถาวรที่ไม่มีดัชนีที่ลงนามที่เชื่อถือได้จะถูกปฏิเสธ
 
 ---
 
@@ -143,16 +163,16 @@ Docker image มาพร้อมกับแอปพลิเคชันบ
 ## OCR / การแยกข้อความ {#ocr-text-extraction}
 
 **เส้นทางเครื่องมือ:** `ocr`  
-**โมเดล:** Tesseract (เร็ว), PaddleOCR PP-OCRv5 (สมดุล), PaddleOCR-VL 1.5 (ดีที่สุด)
+**รุ่น:** Tesseract (`fast`); RapidOCR พร้อม PP-OCRv6 รุ่นเล็ก (`balanced`); รุ่นกลาง PP-OCRv6 พร้อมการให้คะแนนตัวแปรที่ปรับเทียบแล้ว (`best`)
 
 | พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
 |-----------|------|---------|-------------|
-| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | ระดับการประมวลผล |
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | พลวัต | เมื่อไม่ระบุ `quality` และ `engine` SnapOtter จะเลือกระดับที่ดีที่สุดที่ใช้ได้ตามลำดับ `best`, `balanced`, `fast` สำหรับภาษาเกาหลีจะไม่เลือก `fast` แต่จะใช้ `best` แล้วจึง `balanced` หรือส่งคืนข้อผิดพลาดการติดตั้งหรือความเข้ากันได้ของรันไทม์แบบแม่นยำ |
 | `language` | string | `"auto"` | ภาษา: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
-| `enhance` | boolean | `true` | ประมวลผลภาพล่วงหน้าเพื่อเพิ่มความแม่นยำของ OCR |
-| `engine` | string | - | เลิกใช้แล้ว แมป `tesseract` เป็น `fast`, `paddleocr` เป็น `balanced` |
+| `enhance` | บูลีน | ขึ้นอยู่กับระดับ | ปรับปรุงความคมชัดในท้องถิ่น ใช้งานได้อย่างรวดเร็วโดยตรง ระดับที่แม่นยำจะคงตัวแปรไว้เฉพาะเมื่อคะแนนที่ปรับเทียบแล้วปรับปรุง OCR ค่าเริ่มต้นเป็นดีที่สุด |
+| `engine` | เชือก | - | นามแฝงความเข้ากันได้ที่เลิกใช้แล้ว แมป `tesseract` กับ `fast` และค่า `paddleocr` ดั้งเดิมกับ `balanced` มันไม่โหลด PaddlePaddle |
 
-ส่งคืนผลลัพธ์ที่มีโครงสร้างพร้อมกล่องขอบเขต คะแนนความเชื่อมั่น และบล็อกข้อความที่แยกออกมา
+ส่งคืนข้อความที่แยกออกมาพร้อมข้อมูลเมตาแหล่งที่มา: เครื่องยนต์ คุณภาพที่ร้องขอและตามจริง อุปกรณ์ ผู้ให้บริการ สถานะการเสื่อมสภาพ คำเตือน และเวอร์ชันรันไทม์/รุ่นที่แม่นยำ หากมี คำขอคุณภาพที่ชัดเจนจะไม่ถอยกลับไปยังระดับอื่น ถ้า `balanced` หรือ `best` ไม่พร้อมใช้งาน API จะส่งกลับ `FEATURE_NOT_INSTALLED` หรือ `FEATURE_INCOMPATIBLE` แทนที่จะรัน `fast` แบบเงียบๆ
 
 ## PDF OCR {#pdf-ocr}
 
@@ -163,9 +183,13 @@ Docker image มาพร้อมกับแอปพลิเคชันบ
 
 | พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
 |-----------|------|---------|-------------|
-| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | ระดับการประมวลผล |
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | พลวัต | เมื่อไม่ระบุ `quality` และ `engine` SnapOtter จะเลือกระดับที่ดีที่สุดที่ใช้ได้ตามลำดับ `best`, `balanced`, `fast` สำหรับภาษาเกาหลีจะไม่เลือก `fast` แต่จะใช้ `best` แล้วจึง `balanced` หรือส่งคืนข้อผิดพลาดการติดตั้งหรือความเข้ากันได้ของรันไทม์แบบแม่นยำ |
 | `language` | string | `"auto"` | ภาษา: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
 | `pages` | string | `"all"` | การเลือกหน้า: `"all"`, `"1-3"`, `"1,3,5"` |
+| `enhance` | บูลีน | ขึ้นอยู่กับระดับ | ปรับปรุงความคมชัดในท้องถิ่น ใช้งานได้อย่างรวดเร็วโดยตรง ระดับที่แม่นยำจะคงตัวแปรไว้เฉพาะเมื่อคะแนนที่ปรับเทียบแล้วปรับปรุง OCR ค่าเริ่มต้นเป็นดีที่สุด |
+| `engine` | เชือก | - | นามแฝงความเข้ากันได้ที่เลิกใช้แล้ว แมป `tesseract` กับ `fast` และค่า `paddleocr` ดั้งเดิมกับ `balanced` มันไม่โหลด PaddlePaddle |
+
+กฎการไม่ดาวน์เกรดเดียวกันนี้ใช้กับ PDF OCR หน้า PDF จะถูกแรสเตอร์ก่อนที่จะจดจำ และคำขอหนึ่งรายการสามารถเลือกได้สูงสุด 50 หน้า
 
 ## เบลอใบหน้า / PII {#face-pii-blur}