2026-07-11 13:52:47 +08:00
---
description : "เอกสารอ้างอิงเอนจิน AI พร้อมเครื่องมือ ML ในเครื่องทั้งหมด การลบพื้นหลัง การขยายภาพ OCR การตรวจจับใบหน้า การกู้คืนภาพถ่าย และอื่น ๆ"
2026-07-15 03:34:24 +08:00
i18n_output_hash : ebf48f7a0230
i18n_source_hash : aa9a56cdddc7
i18n_provenance : human
2026-07-11 13:52:47 +08:00
---
# เอกสารอ้างอิงเอนจิน AI {#ai-engine-reference}
2026-07-15 03:34:24 +08:00
แพ็คเกจ `@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 และการเชื่อมต่อไดรเวอร์สำหรับเครื่องมือนี้
2026-07-11 13:52:47 +08:00
การเร่งความเร็ว iGPU ของ Intel/AMD ผ่าน VA-API, Quick Sync หรือ OpenCL ยังไม่รองรับสำหรับการอนุมาน AI ในปัจจุบัน การแมป `/dev/dri` เข้าไปในคอนเทนเนอร์ไม่ได้เร่งความเร็วเครื่องมือ Python sidecar เหล่านี้ เว้นแต่จะมี NVIDIA GPU ที่รองรับ CUDA พร้อมใช้งาน
เครื่องมือ AI แบบ Python sidecar จำนวน 19 รายการครอบคลุมสี่โมดาลิตี (ภาพ เสียง วิดีโอ เอกสาร) พร้อมด้วยเครื่องมืออีก 2 รายการที่มีความสามารถ AI เสริม โมเดลทั้งหมดทำงานในเครื่อง ไม่ต้องใช้อินเทอร์เน็ตหลังจากดาวน์โหลดโมเดลครั้งแรก
2026-07-15 03:34:24 +08:00
<!-- 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 -->
2026-07-11 13:52:47 +08:00
## สถาปัตยกรรม {#architecture}
```
Node.js Tool Route
|
v
@snapotter/ai bridge.ts
| (stdin/stdout JSON + stderr progress events)
v
2026-07-15 03:34:24 +08:00
+-- 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)
2026-07-11 13:52:47 +08:00
|
|-- remove_bg.py (rembg / BiRefNet)
|-- upscale.py (RealESRGAN)
|-- inpaint.py (LaMa ONNX)
|-- outpaint.py (LaMa canvas expansion)
|-- detect_faces.py (MediaPipe)
|-- face_landmarks.py (MediaPipe landmarks)
|-- enhance_faces.py (GFPGAN / CodeFormer)
|-- colorize.py (DDColor)
|-- noise_removal.py (SCUNet / tiered denoising)
|-- red_eye_removal.py (landmark + color analysis)
|-- restore.py (scratch repair + enhancement + denoising)
|-- transcribe.py (faster-whisper speech-to-text)
+-- install_feature.py (on-demand bundle installer)
```
โปรไฟล์ dispatcher แบบ "docs" ที่แยกต่างหากจะแทนที่รายการอนุญาต AI ด้วยสคริปต์ประมวลผลเอกสาร (`doc_pagecount` , `doc_health` , `doc_flatten` , `doc_redact` , `doc_text` , `doc_to_word` , `doc_metadata` , `doc_html_pdf` ) และข้ามการอิมพอร์ต ML ขนาดใหญ่
**เวลาหมดเวลา:** ค่าเริ่มต้น 300 วินาที OCR และการลบพื้นหลัง BiRefNet ได้ 600 วินาที
## ชุดฟีเจอร์ (Feature Bundles) {#feature-bundles}
โมเดล AI ถูกจัดแพ็กเกจตามชุด dependency ที่ใช้ร่วมกัน ไม่ใช่หนึ่งไฟล์เก็บถาวรต่อหนึ่งเครื่องมือ ชุดฟีเจอร์หนึ่งชุดสามารถเปิดใช้งานเครื่องมือได้หลายรายการเมื่อเครื่องมือเหล่านั้นใช้ตระกูลโมเดล, Python wheel หรือไลบรารีเนทีฟเดียวกัน วิธีนี้ทำให้ Docker image สำหรับรีลีสมีขนาดเล็กลงและหลีกเลี่ยงการเก็บสำเนาซ้ำของโมเดล background matting, การตรวจจับใบหน้า, OCR, การกู้คืน และโมเดลเสียงพูดเดียวกัน
Docker image มาพร้อมกับแอปพลิเคชันบวกกับรันไทม์ทั่วไป ไฟล์เก็บถาวรของโมเดลขนาดใหญ่จะถูกดาวน์โหลดตามความต้องการลงในโวลุ่ม `/data/ai` แบบถาวร แล้วนำกลับมาใช้ซ้ำโดยทุกเครื่องมือที่ต้องการ หากติดตั้งชุดฟีเจอร์แล้วเนื่องจากมีเครื่องมืออื่นต้องการใช้ การเปิดใช้งานเครื่องมือใหม่ที่ต้องพึ่งพาชุดนั้นจะไม่ดาวน์โหลดชุดฟีเจอร์นั้นซ้ำอีก
2026-07-15 03:34:24 +08:00
เครื่องมือ 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`
2026-07-11 13:52:47 +08:00
| ชุดฟีเจอร์ | ขนาด | กลุ่ม dependency ที่ใช้ร่วมกัน | เครื่องมือที่ใช้ |
|--------|------|-------------------------|-------------------|
| `background-removal` | 4-5 GB | rembg / BiRefNet background matting | remove-background, passport-photo, transparency-fixer, background-replace, blur-background |
| `face-detection` | 200-300 MB | การตรวจจับใบหน้าและจุดสังเกต MediaPipe | blur-faces, red-eye-removal, smart-crop |
| `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 |
2026-07-15 03:34:24 +08:00
| `ocr` | ~208-234 ดาวน์โหลด MiB / ~409-488 ติดตั้ง MiB แล้ว | อุปกรณ์เสริม RapidOCR 3.9.1, ONNX Runtime 1.20.1 และรุ่น PP-OCR ที่ปักหมุดไว้ | ocr, ocr-pdf (`balanced` และ `best` เท่านั้น) |
2026-07-11 13:52:47 +08:00
| `transcription` | ~600 MB | โมเดลแปลงเสียงเป็นข้อความ faster-whisper | transcribe-audio, auto-subtitles |
เครื่องมือที่มี dependency ข้ามชุดฟีเจอร์:
| เครื่องมือ | ชุดฟีเจอร์ที่ต้องใช้ | เหตุผล |
|------|------------------|-----|
| `passport-photo` | `background-removal` , `face-detection` | ลบพื้นหลัง แล้วใช้จุดสังเกตใบหน้าจัดกรอบการครอปให้เป็นไปตามกฎของรูปหนังสือเดินทางและรูปบัตรประจำตัว |
| `enhance-faces` | `upscale-enhance` , `face-detection` | ตรวจจับใบหน้าก่อนรันการปรับปรุงด้วย GFPGAN หรือ CodeFormer บนบริเวณใบหน้าที่เลือก |
2026-07-15 03:34:24 +08:00
เครื่องมือจะใช้งานได้เมื่อมีการติดตั้งบันเดิลที่จำเป็นทั้งหมดแล้ว ยกเว้น 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` การนำเข้าแบบออฟไลน์จะใช้การตรวจสอบลายเซ็น แฮช การดึงข้อมูล ความเข้ากันได้ และการทดสอบควันแบบเดียวกันกับการติดตั้งแบบออนไลน์ ไฟล์เก็บถาวรที่ไม่มีดัชนีที่ลงนามที่เชื่อถือได้จะถูกปฏิเสธ
2026-07-11 13:52:47 +08:00
---
## การลบพื้นหลัง {#background-removal}
**เส้นทางเครื่องมือ:** `remove-background`
**โมเดล:** rembg พร้อม BiRefNet (ค่าเริ่มต้น) หรือรุ่นย่อย U2-Net
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `model` | string | - | รุ่นย่อยของโมเดล (การแทนที่แบบเสริม) |
| `backgroundType` | string | `"transparent"` | หนึ่งใน: `transparent` , `color` , `gradient` , `blur` , `image` |
| `backgroundColor` | string | - | สีเลขฐานสิบหกสำหรับพื้นหลังสีทึบ |
| `gradientColor1` | string | - | สีไล่ระดับสีแรก |
| `gradientColor2` | string | - | สีไล่ระดับสีที่สอง |
| `gradientAngle` | number | - | มุมไล่ระดับสีเป็นองศา |
| `blurEnabled` | boolean | - | เปิดใช้งานเอฟเฟกต์เบลอพื้นหลัง |
| `blurIntensity` | number (0-100) | - | ความเข้มของการเบลอ |
| `shadowEnabled` | boolean | - | เปิดใช้งานเงาตกกระทบบนวัตถุ |
| `shadowOpacity` | number (0-100) | - | ความทึบของเงา |
| `outputFormat` | string | - | รูปแบบเอาต์พุต: `png` , `webp` หรือ `avif` |
| `edgeRefine` | integer (0-3) | - | ระดับการปรับแต่งขอบ |
| `decontaminate` | boolean | - | ลบสีที่ซึมออกจากขอบ |
## แทนที่พื้นหลัง {#background-replace}
**เส้นทางเครื่องมือ:** `background-replace`
**โมเดล:** rembg / BiRefNet (ใช้ร่วมกับ remove-background)
ลบพื้นหลังและแทนที่ด้วยสีทึบหรือสีไล่ระดับ
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `backgroundType` | `"color"` \| `"gradient"` | `"color"` | โหมดพื้นหลัง |
| `color` | string | `"#ffffff"` | สีเลขฐานสิบหกของพื้นหลัง (เมื่อ `backgroundType` เป็น `color` ) |
| `gradientColor1` | string | - | สีเลขฐานสิบหกไล่ระดับสีแรก |
| `gradientColor2` | string | - | สีเลขฐานสิบหกไล่ระดับสีที่สอง |
| `gradientAngle` | integer (0-360) | `180` | มุมไล่ระดับสีเป็นองศา |
| `feather` | integer (0-20) | `0` | รัศมีการเกลี่ยขอบ |
| `format` | `"png"` \| `"webp"` | `"png"` | รูปแบบเอาต์พุต |
## เบลอพื้นหลัง {#blur-background}
**เส้นทางเครื่องมือ:** `blur-background`
**โมเดล:** rembg / BiRefNet (ใช้ร่วมกับ remove-background)
เบลอพื้นหลังในขณะที่ยังคงความคมชัดของวัตถุ
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `intensity` | integer (1-100) | `50` | ความเข้มของการเบลอ |
| `feather` | integer (0-20) | `0` | รัศมีการเกลี่ยขอบ |
| `format` | `"png"` \| `"webp"` | `"png"` | รูปแบบเอาต์พุต |
## การขยายภาพ {#image-upscaling}
**เส้นทางเครื่องมือ:** `upscale`
**โมเดล:** RealESRGAN (พร้อม Lanczos สำรองเมื่อไม่พร้อมใช้งาน)
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `scale` | number | `2` | ตัวคูณการขยาย |
| `model` | string | `"auto"` | รุ่นย่อยของโมเดล |
| `faceEnhance` | boolean | `false` | ใช้รอบการปรับปรุงใบหน้า GFPGAN |
| `denoise` | number | `0` | ความแรงในการลดสัญญาณรบกวน |
| `format` | string | `"auto"` | การแทนที่รูปแบบเอาต์พุต |
| `quality` | number | `95` | คุณภาพเอาต์พุต (1-100) |
## OCR / การแยกข้อความ {#ocr-text-extraction}
**เส้นทางเครื่องมือ:** `ocr`
2026-07-15 03:34:24 +08:00
**รุ่น:** Tesseract (`fast` ); RapidOCR พร้อม PP-OCRv6 รุ่นเล็ก (`balanced` ); รุ่นกลาง PP-OCRv6 พร้อมการให้คะแนนตัวแปรที่ปรับเทียบแล้ว (`best` )
2026-07-11 13:52:47 +08:00
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
2026-07-15 03:34:24 +08:00
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | พลวัต | เมื่อไม่ระบุ `quality` และ `engine` SnapOtter จะเลือกระดับที่ดีที่สุดที่ใช้ได้ตามลำดับ `best` , `balanced` , `fast` สำหรับภาษาเกาหลีจะไม่เลือก `fast` แต่จะใช้ `best` แล้วจึง `balanced` หรือส่งคืนข้อผิดพลาดการติดตั้งหรือความเข้ากันได้ของรันไทม์แบบแม่นยำ |
2026-07-11 13:52:47 +08:00
| `language` | string | `"auto"` | ภาษา: `auto` , `en` , `de` , `fr` , `es` , `zh` , `ja` , `ko` |
2026-07-15 03:34:24 +08:00
| `enhance` | บูลีน | ขึ้นอยู่กับระดับ | ปรับปรุงความคมชัดในท้องถิ่น ใช้งานได้อย่างรวดเร็วโดยตรง ระดับที่แม่นยำจะคงตัวแปรไว้เฉพาะเมื่อคะแนนที่ปรับเทียบแล้วปรับปรุง OCR ค่าเริ่มต้นเป็นดีที่สุด |
| `engine` | เชือก | - | นามแฝงความเข้ากันได้ที่เลิกใช้แล้ว แมป `tesseract` กับ `fast` และค่า `paddleocr` ดั้งเดิมกับ `balanced` มันไม่โหลด PaddlePaddle |
2026-07-11 13:52:47 +08:00
2026-07-15 03:34:24 +08:00
ส่งคืนข้อความที่แยกออกมาพร้อมข้อมูลเมตาแหล่งที่มา: เครื่องยนต์ คุณภาพที่ร้องขอและตามจริง อุปกรณ์ ผู้ให้บริการ สถานะการเสื่อมสภาพ คำเตือน และเวอร์ชันรันไทม์/รุ่นที่แม่นยำ หากมี คำขอคุณภาพที่ชัดเจนจะไม่ถอยกลับไปยังระดับอื่น ถ้า `balanced` หรือ `best` ไม่พร้อมใช้งาน API จะส่งกลับ `FEATURE_NOT_INSTALLED` หรือ `FEATURE_INCOMPATIBLE` แทนที่จะรัน `fast` แบบเงียบๆ
2026-07-11 13:52:47 +08:00
## PDF OCR {#pdf-ocr}
**เส้นทางเครื่องมือ:** `ocr-pdf`
**โมเดล:** ระบบระดับเดียวกับ OCR ภาพ
แยกข้อความจากเอกสาร PDF ที่สแกนโดยใช้ OCR ที่ขับเคลื่อนด้วย AI ทีละหน้า
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
2026-07-15 03:34:24 +08:00
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | พลวัต | เมื่อไม่ระบุ `quality` และ `engine` SnapOtter จะเลือกระดับที่ดีที่สุดที่ใช้ได้ตามลำดับ `best` , `balanced` , `fast` สำหรับภาษาเกาหลีจะไม่เลือก `fast` แต่จะใช้ `best` แล้วจึง `balanced` หรือส่งคืนข้อผิดพลาดการติดตั้งหรือความเข้ากันได้ของรันไทม์แบบแม่นยำ |
2026-07-11 13:52:47 +08:00
| `language` | string | `"auto"` | ภาษา: `auto` , `en` , `de` , `fr` , `es` , `zh` , `ja` , `ko` |
| `pages` | string | `"all"` | การเลือกหน้า: `"all"` , `"1-3"` , `"1,3,5"` |
2026-07-15 03:34:24 +08:00
| `enhance` | บูลีน | ขึ้นอยู่กับระดับ | ปรับปรุงความคมชัดในท้องถิ่น ใช้งานได้อย่างรวดเร็วโดยตรง ระดับที่แม่นยำจะคงตัวแปรไว้เฉพาะเมื่อคะแนนที่ปรับเทียบแล้วปรับปรุง OCR ค่าเริ่มต้นเป็นดีที่สุด |
| `engine` | เชือก | - | นามแฝงความเข้ากันได้ที่เลิกใช้แล้ว แมป `tesseract` กับ `fast` และค่า `paddleocr` ดั้งเดิมกับ `balanced` มันไม่โหลด PaddlePaddle |
กฎการไม่ดาวน์เกรดเดียวกันนี้ใช้กับ PDF OCR หน้า PDF จะถูกแรสเตอร์ก่อนที่จะจดจำ และคำขอหนึ่งรายการสามารถเลือกได้สูงสุด 50 หน้า
2026-07-11 13:52:47 +08:00
## เบลอใบหน้า / PII {#face-pii-blur}
**เส้นทางเครื่องมือ:** `blur-faces`
**โมเดล:** การตรวจจับใบหน้า MediaPipe
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `blurRadius` | number (1-100) | `30` | รัศมีการเบลอแบบเกาส์เซียน |
| `sensitivity` | number (0-1) | `0.5` | เกณฑ์ความเชื่อมั่นในการตรวจจับ |
## การปรับปรุงใบหน้า {#face-enhancement}
**เส้นทางเครื่องมือ:** `enhance-faces`
**โมเดล:** GFPGAN, CodeFormer
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `model` | `"auto"` \| `"gfpgan"` \| `"codeformer"` | `"auto"` | โมเดลการปรับปรุง |
| `strength` | number (0-1) | `0.8` | ความแรงของการปรับปรุง |
| `sensitivity` | number (0-1) | `0.5` | เกณฑ์การตรวจจับใบหน้า |
| `onlyCenterFace` | boolean | `false` | ปรับปรุงเฉพาะใบหน้าที่อยู่กึ่งกลางที่สุด |
## การลงสีด้วย AI {#ai-colorization}
**เส้นทางเครื่องมือ:** `colorize`
**โมเดล:** DDColor (พร้อม OpenCV DNN สำรอง)
แปลงภาพถ่ายขาวดำหรือโทนสีเทาเป็นภาพสีเต็มรูปแบบ
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `intensity` | number (0-1) | `1.0` | ความแรงของความอิ่มตัวของสี |
| `model` | `"auto"` \| `"ddcolor"` \| `"opencv"` | `"auto"` | รุ่นย่อยของโมเดล |
## การลบสัญญาณรบกวน {#noise-removal}
**เส้นทางเครื่องมือ:** `noise-removal`
**โมเดล:** SCUNet (ไปป์ไลน์ลดสัญญาณรบกวนแบบหลายระดับ)
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `tier` | `"quick"` \| `"balanced"` \| `"quality"` \| `"maximum"` | `"balanced"` | ระดับการประมวลผล |
| `strength` | number (0-100) | `50` | ความแรงในการลดสัญญาณรบกวน |
| `detailPreservation` | number (0-100) | `50` | จำนวนรายละเอียดที่จะเก็บรักษา ยิ่งสูงยิ่งเก็บพื้นผิวไว้มาก |
| `colorNoise` | number (0-100) | `30` | ความแรงในการลดสัญญาณรบกวนสี |
| `format` | string | `"original"` | รูปแบบเอาต์พุต: `original` , `png` , `jpeg` , `webp` , `avif` , `jxl` |
| `quality` | number (1-100) | `90` | คุณภาพการเข้ารหัสเอาต์พุต |
## การลบตาแดง {#red-eye-removal}
**เส้นทางเครื่องมือ:** `red-eye-removal`
ตรวจจับจุดสังเกตใบหน้า ระบุตำแหน่งบริเวณดวงตา และแก้ไขการอิ่มตัวเกินของช่องสีแดง
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `sensitivity` | number (0-100) | `50` | เกณฑ์การตรวจจับพิกเซลสีแดง |
| `strength` | number (0-100) | `70` | ความแรงในการแก้ไข |
| `format` | string | - | การแทนที่รูปแบบเอาต์พุต (เสริม) |
| `quality` | number (1-100) | `90` | คุณภาพเอาต์พุต |
## การกู้คืนภาพถ่าย {#photo-restoration}
**เส้นทางเครื่องมือ:** `restore-photo`
ไปป์ไลน์หลายขั้นตอนสำหรับภาพถ่ายเก่าหรือเสียหาย: การตรวจจับและซ่อมรอยขีดข่วน/รอยฉีก การปรับปรุงใบหน้า การลดสัญญาณรบกวน และการลงสีเสริม
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `scratchRemoval` | boolean | `true` | ตรวจจับและซ่อมรอยขีดข่วน รอยฉีก |
| `faceEnhancement` | boolean | `true` | ใช้รอบการปรับปรุงใบหน้า |
| `fidelity` | number (0-1) | `0.7` | ความแรงในการปรับปรุงใบหน้า (สูงกว่า = อนุรักษ์นิยมมากกว่า) |
| `denoise` | boolean | `true` | ใช้รอบการลดสัญญาณรบกวน |
| `denoiseStrength` | number (0-100) | `25` | ความแรงในการลดสัญญาณรบกวน |
| `colorize` | boolean | `false` | ลงสีหลังการกู้คืน |
| `colorizeStrength` | number (0-100) | `85` | ความเข้มของการลงสี |
## รูปถ่ายหนังสือเดินทาง {#passport-photo}
**เส้นทางเครื่องมือ:** `passport-photo`
**โมเดล:** จุดสังเกตใบหน้า MediaPipe + การลบพื้นหลัง BiRefNet
เวิร์กโฟลว์สองเฟส: วิเคราะห์ (ตรวจจับใบหน้า + ลบพื้นหลัง) จากนั้นสร้าง (ครอป ปรับขนาด เรียงเป็นแผ่น) รองรับกว่า 37 ประเทศใน 6 ภูมิภาค
### เฟส 1: วิเคราะห์ {#phase-1-analyze}
`POST /api/v1/tools/image/passport-photo/analyze`
รับไฟล์ภาพ (multipart) ส่งคืนข้อมูลจุดสังเกตใบหน้า ตัวอย่างแบบ base64 และขนาดของภาพ
### เฟส 2: สร้าง {#phase-2-generate}
`POST /api/v1/tools/image/passport-photo/generate`
รับ JSON body ที่มีผลลัพธ์จากเฟส 1 พร้อมด้วยการตั้งค่าการสร้าง:
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `jobId` | string | (จำเป็น) | Job ID จากเฟส 1 |
| `filename` | string | (จำเป็น) | ชื่อไฟล์ต้นฉบับจากเฟส 1 |
| `countryCode` | string | (จำเป็น) | รหัสประเทศ ISO (เช่น `US` , `GB` , `IN` ) |
| `documentType` | string | `"passport"` | ประเภทเอกสาร |
| `bgColor` | string | `"#FFFFFF"` | สีเลขฐานสิบหกของพื้นหลัง |
| `printLayout` | string | `"none"` | เลย์เอาต์การพิมพ์: `none` , `4x6` , `a4` , `letter` |
| `maxFileSizeKb` | number | `0` | ขนาดไฟล์สูงสุดเป็น KB (0 = ไม่จำกัด) |
| `dpi` | number (72-1200) | `300` | DPI เอาต์พุต |
| `customWidthMm` | number | - | ความกว้างกำหนดเองเป็นมิลลิเมตร (แทนที่ข้อกำหนดของประเทศ) |
| `customHeightMm` | number | - | ความสูงกำหนดเองเป็นมิลลิเมตร (แทนที่ข้อกำหนดของประเทศ) |
| `zoom` | number (0.5-3) | `1` | ตัวคูณการซูม |
| `adjustX` | number | `0` | การปรับตำแหน่งแนวนอน |
| `adjustY` | number | `0` | การปรับตำแหน่งแนวตั้ง |
| `landmarks` | object | (จำเป็น) | จุดสังเกตจากเฟส 1 |
| `imageWidth` | number | (จำเป็น) | ความกว้างของภาพจากเฟส 1 |
| `imageHeight` | number | (จำเป็น) | ความสูงของภาพจากเฟส 1 |
## การลบวัตถุ (Inpainting) {#object-erasing-inpainting}
**เส้นทางเครื่องมือ:** `erase-object`
**โมเดล:** LaMa ผ่าน ONNX Runtime
มาสก์จะถูกส่งเป็น **ส่วนไฟล์ที่สอง** (fieldname `mask` ) ไม่ใช่แบบ base64 พิกเซลสีขาวในมาสก์บ่งชี้บริเวณที่จะลบ การตั้งค่า `format` และ `quality` จะถูกส่งเป็นฟิลด์ฟอร์มระดับบนสุด
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `file` | file | (จำเป็น) | ภาพต้นฉบับ (multipart) |
| `mask` | file | (จำเป็น) | ภาพมาสก์ (multipart, fieldname `mask` , สีขาว = ลบ) |
| `format` | string | `"auto"` | รูปแบบเอาต์พุต: `auto` , `png` , `jpg` , `jpeg` , `webp` , `tiff` , `gif` , `avif` , `heic` , `heif` , `jxl` |
| `quality` | integer (1-100) | `95` | คุณภาพเอาต์พุต |
เร่งความเร็วด้วย CUDA เมื่อมี NVIDIA GPU พร้อมใช้งาน
## AI Canvas Expand {#ai-canvas-expand}
**เส้นทางเครื่องมือ:** `ai-canvas-expand`
**โมเดล:** outpainting ที่ใช้ LaMa
ขยายพื้นที่แคนวาสของภาพในทิศทางใดก็ได้ และเติมบริเวณใหม่ด้วยเนื้อหาที่สร้างโดย AI ให้เข้ากับภาพที่มีอยู่
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `extendTop` | integer | `0` | จำนวนพิกเซลที่จะขยายด้านบน |
| `extendRight` | integer | `0` | จำนวนพิกเซลที่จะขยายด้านขวา |
| `extendBottom` | integer | `0` | จำนวนพิกเซลที่จะขยายด้านล่าง |
| `extendLeft` | integer | `0` | จำนวนพิกเซลที่จะขยายด้านซ้าย |
| `tier` | `"fast"` \| `"balanced"` \| `"high"` | `"balanced"` | ระดับคุณภาพ |
| `format` | string | `"auto"` | รูปแบบเอาต์พุต: `auto` , `png` , `jpg` , `jpeg` , `webp` , `tiff` , `gif` , `avif` , `heic` , `heif` , `jxl` |
| `quality` | integer (1-100) | `95` | คุณภาพเอาต์พุต |
อย่างน้อยหนึ่งทิศทางในการขยายต้องมากกว่า 0
## Smart Crop {#smart-crop}
**เส้นทางเครื่องมือ:** `smart-crop`
**โมเดล:** การตรวจจับใบหน้า MediaPipe (โหมดใบหน้าเท่านั้น)
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `mode` | string | `"subject"` | กลยุทธ์การครอป: `subject` , `face` , `trim` |
| `strategy` | `"attention"` \| `"entropy"` | `"attention"` | กลยุทธ์สำหรับโหมดวัตถุ |
| `width` | integer | - | ความกว้างเอาต์พุต |
| `height` | integer | - | ความสูงเอาต์พุต |
| `padding` | integer (0-50) | `0` | เปอร์เซ็นต์ระยะขอบรอบวัตถุ |
| `facePreset` | string | `"head-shoulders"` | การจัดกรอบสำเร็จรูปเมื่อ `mode=face` |
| `sensitivity` | number (0-1) | `0.5` | เกณฑ์การตรวจจับใบหน้า |
| `threshold` | integer (0-255) | `30` | เกณฑ์การตรวจจับพื้นหลัง (โหมด trim) |
| `padToSquare` | boolean | `false` | เพิ่มระยะขอบผลลัพธ์ที่ตัดแล้วให้เป็นสี่เหลี่ยมจัตุรัส |
| `padColor` | string | `"#ffffff"` | สีพื้นหลังสำหรับการเพิ่มระยะขอบแบบสี่เหลี่ยมจัตุรัส |
| `targetSize` | integer | - | ขนาดเป้าหมายสำหรับเอาต์พุตที่เพิ่มระยะขอบ (พิกเซล) |
| `quality` | integer (1-100) | - | คุณภาพเอาต์พุต |
ค่า `mode` แบบเดิม `attention` และ `content` ยังคงรับได้และแมปไปเป็น `subject` และ `trim` ตามลำดับ
**การจัดกรอบใบหน้าสำเร็จรูป:**
| สำเร็จรูป | เหมาะสำหรับ |
|--------|---------|
| `closeup` | ภาพศีรษะ |
| `head-shoulders` | ภาพโปรไฟล์ |
| `upper-body` | LinkedIn / ทางการ |
| `half-body` | ครึ่งตัวบนเต็มตัว |
## ถอดเสียงเป็นข้อความ {#transcribe-audio}
**เส้นทางเครื่องมือ:** `transcribe-audio`
**โมเดล:** faster-whisper
แปลงเสียงพูดเป็นข้อความ รองรับรูปแบบเอาต์พุตข้อความธรรมดา, SRT และ VTT
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `language` | string | `"auto"` | ภาษา: `auto` , `en` , `de` , `fr` , `es` , `zh` , `ja` , `ko` , `id` , `th` , `vi` |
| `outputFormat` | `"txt"` \| `"srt"` \| `"vtt"` | `"txt"` | รูปแบบเอาต์พุต |
## คำบรรยายอัตโนมัติ {#auto-subtitles}
**เส้นทางเครื่องมือ:** `auto-subtitles`
**โมเดล:** faster-whisper (แยกเสียงจากวิดีโอ แล้วถอดเสียงเป็นข้อความ)
สร้างไฟล์คำบรรยายจากแทร็กเสียงของวิดีโอ
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `language` | string | `"auto"` | ภาษา: `auto` , `en` , `de` , `fr` , `es` , `zh` , `ja` , `ko` , `id` , `th` , `vi` |
| `format` | `"srt"` \| `"vtt"` | `"srt"` | รูปแบบคำบรรยายเอาต์พุต |
## เครื่องมือแก้ไขความโปร่งใส PNG {#png-transparency-fixer}
**เส้นทางเครื่องมือ:** `transparency-fixer`
**โมเดล:** BiRefNet HR-matting (ความละเอียด 2048x2048)
แก้ไขไฟล์ PNG แบบ "โปร่งใสปลอม" ที่พื้นหลังถูกลบออกไปแล้วแต่ทิ้งขอบซ่อน, รัศมีเงา หรือสิ่งแปลกปลอมกึ่งโปร่งใสไว้ ใช้โมเดล matting ความละเอียดสูงของ BiRefNet เพื่อสร้างช่องอัลฟาที่สะอาด แล้วใช้การประมวลผล defringe ที่กำหนดค่าได้เพื่อลบการปนเปื้อนของสีตามขอบ
**สายสำรองกรณี OOM:** หาก BiRefNet HR-matting ใช้หน่วยความจำเกินที่มี เครื่องมือจะถอยกลับไปใช้ `birefnet-general` โดยอัตโนมัติ จากนั้นไปที่ `u2net`
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `defringe` | number (0-100) | `30` | ความแรงของ defringe ขอบเพื่อลบการปนเปื้อนของสี |
| `outputFormat` | `"png"` \| `"webp"` | `"png"` | รูปแบบภาพเอาต์พุต |
| `removeWatermark` | boolean | `false` | ใช้การประมวลผลล่วงหน้าเพื่อลบลายน้ำ (median filter) |
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/transparency-fixer \
-H "Authorization: Bearer <token>" \
-F "file=@fake-transparent.png" \
-F 'settings={"defringe":30,"outputFormat":"png"}'
```
---
## เครื่องมือที่มีความสามารถ AI เสริม {#tools-with-optional-ai-capabilities}
เครื่องมือต่อไปนี้ไม่ใช่เครื่องมือ Python sidecar แต่ใช้ฟีเจอร์ AI เมื่อเปิดใช้งานตัวเลือกบางอย่าง
### การปรับปรุงภาพ {#image-enhancement}
**เส้นทางเครื่องมือ:** `image-enhancement`
**เอนจิน:** อิงการวิเคราะห์ (ฮิสโทแกรมและสถิติของ Sharp)
วิเคราะห์ภาพและใช้การแก้ไขอัตโนมัติสำหรับการเปิดรับแสง คอนทราสต์ สมดุลแสงขาว ความอิ่มตัวของสี ความคมชัด และสัญญาณรบกวน รองรับโหมดเฉพาะฉาก
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `mode` | `"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"` | `"auto"` | โหมดฉากสำหรับการปรับจูนการแก้ไข |
| `intensity` | number (0-100) | `50` | ความแรงในการแก้ไขโดยรวม |
| `corrections.exposure` | boolean | `true` | ใช้การแก้ไขการเปิดรับแสง |
| `corrections.contrast` | boolean | `true` | ใช้การแก้ไขคอนทราสต์ |
| `corrections.whiteBalance` | boolean | `true` | ใช้การแก้ไขสมดุลแสงขาว |
| `corrections.saturation` | boolean | `true` | ใช้การแก้ไขความอิ่มตัวของสี |
| `corrections.sharpness` | boolean | `true` | ใช้การแก้ไขความคมชัด |
| `corrections.denoise` | boolean | `true` | ใช้การลดสัญญาณรบกวน |
| `deepEnhance` | boolean | `false` | เปิดใช้งานการลบสัญญาณรบกวนด้วย AI ผ่าน SCUNet (ต้องใช้ชุดฟีเจอร์ `upscale-enhance` ) |
มีปลายทางการวิเคราะห์เพิ่มเติมที่ `POST /api/v1/tools/image/image-enhancement/analyze` ซึ่งส่งคืนการแก้ไขที่ตรวจพบโดยไม่นำมาใช้จริง
### การปรับขนาดตามเนื้อหา (Seam Carving) {#content-aware-resize-seam-carving}
**เส้นทางเครื่องมือ:** `content-aware-resize`
**เอนจิน:** ไบนารี Go `caire` (ไม่ใช่ Python จึงไม่ได้ประโยชน์จาก GPU)
ปรับขนาดภาพอย่างชาญฉลาดด้วยการลบ seam ที่มีพลังงานต่ำ โดยรักษาเนื้อหาสำคัญไว้
| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
|-----------|------|---------|-------------|
| `width` | number | - | ความกว้างเป้าหมาย |
| `height` | number | - | ความสูงเป้าหมาย |
| `protectFaces` | boolean | `false` | ปกป้องบริเวณใบหน้าที่ตรวจพบ (ต้องใช้ชุดฟีเจอร์ `face-detection` ) |
| `blurRadius` | number (0-20) | `4` | การเบลอล่วงหน้าสำหรับการคำนวณพลังงาน |
| `sobelThreshold` | number (1-20) | `2` | เกณฑ์ความไวของขอบ |
| `square` | boolean | `false` | บังคับเอาต์พุตเป็นสี่เหลี่ยมจัตุรัส |
