# GeneralParsers

ปลั๊กอินตัวแยกวิเคราะห์ (parser) อย่างเป็นทางการของ LangBot ที่ดึงข้อความที่มีโครงสร้างจากไฟล์เพื่อใช้สำหรับปลั๊กอิน KnowledgeEngine (เช่น LangRAG)

## รูปแบบที่รองรับ

| รูปแบบ | ประเภท MIME | ตัวแยกวิเคราะห์ |
|--------|-----------|--------|
| PDF | `application/pdf` | การดึงข้อมูลตามเลย์เอาต์โดยใช้ PyMuPDF พร้อมตาราง มาร์กเกอร์หน้า และการเพิ่มประสิทธิภาพด้วยวิสัยทัศน์ (Vision) |
| DOCX | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | การดึงข้อมูลด้วย python-docx พร้อมการแยกวิเคราะห์ย่อหน้า/ตาราง และการรับรู้รูปภาพที่ฝังอยู่ |
| Markdown | `text/markdown` | แปลงเป็น HTML แล้วดึงข้อมูลที่มีโครงสร้าง (หัวข้อ, รายการ, บล็อกโค้ด, ตาราง) |
| HTML | `text/html` | การดึงข้อมูลด้วย BeautifulSoup (ลบ script/style อัตโนมัติ) |
| TXT | `text/plain` | ตรวจจับการเข้ารหัสอัตโนมัติ (chardet) |
| รูปภาพ | `image/png`, `image/jpeg`, `image/webp`, `image/gif`, `image/bmp`, `image/tiff` | การรับรู้ภาพโดยตรงเมื่อมีการกำหนดค่าโมเดลวิสัยทัศน์ (Vision) |

## สถาปัตยกรรม

```
┌──────────────────────────────────────────────┐
│   KnowledgeEngine Plugin (เช่น LangRAG)      │
│  Chunk → Embedding → Store → Retrieve        │
└──────────────────┬───────────────────────────┘
                   │ invoke_parser (RPC)
┌──────────────────▼───────────────────────────┐
│          GeneralParsers                      │
│                                              │
│  File bytes → Format detection → Parse       │
│                                              │
│  ParseResult:                                │
│    ├── text: ข้อความที่ดึงออกมาทั้งหมด         │
│    ├── sections: ส่วนที่แยกตามหัวข้อ           │
│    │   └── TextSection(เนื้อหา, หัวข้อ,        │
│    │                   ระดับ)                 │
│    └── metadata: ชื่อไฟล์, ประเภท MIME ฯลฯ     │
└──────────────────────────────────────────────┘
```

## คุณสมบัติ

- **รองรับโมเดลวิสัยทัศน์ (Vision) เสริม** - กำหนดค่า LLM ที่มีความสามารถด้านวิสัยทัศน์เพื่อทำ OCR หน้า PDF ที่สแกนมา, จดจำรูปภาพที่ฝังอยู่ใน PDF/DOCX และแยกวิเคราะห์รูปภาพที่อัปโหลดโดยตรง
- **การแยกวิเคราะห์ PDF ที่ปรับปรุงแล้ว** - การดึงข้อมูลโดยใช้ PyMuPDF จะรักษาขอบเขตหน้า รวมตารางเข้ากับผลลัพธ์ และให้เมทาดาตาของเอกสารที่สมบูรณ์ยิ่งขึ้น
- **การจัดการ PDF ที่สแกนมา** - ตรวจจับหน้าที่น่าจะเป็นการสแกนและใช้โมเดลวิสัยทัศน์สำหรับ OCR เมื่อมีการกำหนดค่า
- **การรับรู้ภาพข้ามรูปแบบ** - รูปภาพที่ฝังใน PDF/DOCX และรูปภาพที่อัปโหลดโดยตรงสามารถเปลี่ยนเป็นข้อความการรับรู้ในบรรทัดสำหรับการเรียกคืนข้อมูลในลำดับถัดไป
- **การกรองหัวกระดาษ/ท้ายกระดาษ** - ตรวจจับและลบหัวกระดาษและท้ายกระดาษที่ซ้ำกันออกจากผลลัพธ์ PDF
- **การจดจำโครงสร้างส่วน** - ตรวจจับหัวข้อสไตล์ Markdown (`# ~ ######`) และแบ่งผลลัพธ์ออกเป็นส่วนๆ ตามระดับ
- **ตารางเป็น Markdown** - ตารางใน PDF/HTML/Markdown จะถูกแปลงเป็นรูปแบบตาราง Markdown
- **การแยกวิเคราะห์แบบอะซิงโครนัส** - การแยกวิเคราะห์ไฟล์ทำงานใน Thread Pool เพื่อหลีกเลี่ยงการปิดกั้น Event Loop
- **การตรวจจับการเข้ารหัสอัตโนมัติ** - ใช้ chardet สำหรับการตรวจจับการเข้ารหัส รองรับ GBK, UTF-8 และอื่นๆ
- **การรองรับรูปแบบสำรอง** - รูปแบบที่ไม่รองรับจะถูกลองแยกวิเคราะห์เป็นข้อความธรรมดาโดยอัตโนมัติ

## การกำหนดค่า

ปลั๊กอินเปิดเผยรายการกำหนดค่าเสริมหนึ่งรายการ:

- `vision_llm_model_uuid`: LLM ที่มีความสามารถด้านวิสัยทัศน์ที่ใช้สำหรับ OCR หน้าที่สแกนมา, การจดจำรูปภาพที่ฝังใน PDF/DOCX และการแยกวิเคราะห์รูปภาพโดยตรง

หากปล่อยว่างไว้ GeneralParsers จะยังคงทำงานได้ตามปกติ แต่การทำความเข้าใจรูปภาพจะใช้ข้อความตัวแทนแทน และการแยกวิเคราะห์ PDF จะใช้การดึงข้อความ/เลย์เอาต์เพียงอย่างเดียว

## การใช้งาน

1. ติดตั้งปลั๊กอินนี้ใน LangBot
2. กำหนดค่าโมเดลวิสัยทัศน์ (ทางเลือก) หากคุณต้องการ OCR สำหรับ PDF ที่สแกนมา, การจดจำรูปภาพ DOCX/PDF หรือการแยกวิเคราะห์รูปภาพโดยตรง
3. เมื่ออัปโหลดไฟล์ไปยังฐานความรู้ ให้เลือก GeneralParsers เป็นตัวแยกวิเคราะห์
4. ผลลัพธ์การแยกวิเคราะห์จะถูกส่งไปยังปลั๊กอิน KnowledgeEngine โดยอัตโนมัติเพื่อประมวลผลต่อไป

## โครงสร้างผลลัพธ์

GeneralParsers ส่งคืนโครงสร้าง `ParseResult` ที่ประกอบด้วย:

- `text`: ข้อความที่ดึงออกมาทั้งหมด
- `sections`: ส่วนของข้อความที่รับรู้หัวข้อสำหรับกลยุทธ์การแบ่งส่วน (chunking) ที่เน้นโครงสร้าง
- `metadata`: เมทาดาตาของเอกสาร เช่น ชื่อไฟล์, ประเภท MIME, จำนวนหน้า, การมีตาราง, แฟล็กหน้าที่สแกน และสถิติการใช้วิสัยทัศน์

เมทาดาตาของตัวแยกวิเคราะห์ PDF ล่าสุดประกอบด้วยฟิลด์ต่างๆ เช่น:

- `page_count` (จำนวนหน้า)
- `word_count` (จำนวนคำ)
- `has_tables` (มีตาราง)
- `has_scanned_pages` (มีหน้าที่สแกน)
- `headers_footers_removed` (ลบหัวกระดาษ/ท้ายกระดาษแล้ว)
- `vision_used` (ใช้วิสัยทัศน์)
- `vision_tasks_count` (จำนวนงานวิสัยทัศน์)
- `vision_scanned_pages_count` (จำนวนหน้าที่สแกนด้วยวิสัยทัศน์)
- `vision_images_described_count` (จำนวนรูปภาพที่อธิบายด้วยวิสัยทัศน์)

## การพัฒนา

```bash
pip install -r requirements.txt
cp .env.example .env
```

กำหนดค่า `DEBUG_RUNTIME_WS_URL` และ `PLUGIN_DEBUG_KEY` ใน `.env` จากนั้นเปิดใช้งานด้วยตัวแก้จุดบกพร่อง (debugger) ของ IDE ของคุณ