คู่มือการดึงรูปภาพจาก PDF และสร้าง Markdown พร้อม Alternative Text ด้วย Docling#

PDF Document
    │
    ▼
Docling Pipeline (PdfPipelineOptions)
    ├── generate_picture_images=True → ดึงรูปภาพ
    ├── images_scale=2.0 → ความละเอียดสูง
    └── do_picture_description=True → AI สร้าง description
    │
    ▼
DoclingDocument
    │
    ├── export_to_markdown(image_mode=ImageRefMode.REFERENCED)
    │ → Markdown พร้อม ![alt](path/to/image.png)
    │
    └── save_as_markdown(...)
            → บันทึกไฟล์ .md พร้อมโฟลเดอร์รูปภาพ

pip install docling

pipeline_options = PdfPipelineOptions(
    generate_picture_images=True # Default: False
)

pipeline_options = PdfPipelineOptions(
    generate_picture_images=True,
    images_scale=2.0 # Default: 1.0, CLI default: 2.0
)

pipeline_options = PdfPipelineOptions(
    generate_picture_images=True,
    do_picture_description=True # Default: False
)

pipeline_options = PdfPipelineOptions(
    do_picture_description=True,
    picture_description_preset="granite_vision"
)

pipeline_options = PdfPipelineOptions(
    do_picture_description=True,
    picture_description_area_threshold=0 # อธิบาย *ทุก* รูป (default: 0.05 = 5%)
)

from pathlib import Path
from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.datamodel.base_models import InputFormat
from docling_core.types.doc import ImageRefMode

# 1. ตั้งค่า Pipeline Options
pipeline_options = PdfPipelineOptions(
    generate_picture_images=True, # ดึงรูปภาพออกมา
    images_scale=2.0, # ความละเอียดสูงขึ้น 2×
    do_picture_description=True, # สร้าง AI description
    picture_description_preset="granite_vision", # ใช้ Granite Vision
    picture_description_area_threshold=0, # อธิบายทุกรูป
)

# 2. สร้าง DocumentConverter
converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_options=pipeline_options
        )
    }
)

# 3. แปลงเอกสาร
result = converter.convert("document.pdf")

# 4. Export เป็น Markdown
output_dir = Path("output")
output_dir.mkdir(exist_ok=True)

# วิธีที่ 1: บันทึกไฟล์ .md พร้อมโฟลเดอร์รูปภาพ (แนะนำ)
result.document.save_as_markdown(
    output_dir / "document.md",
    image_mode=ImageRefMode.REFERENCED # รูปภาพอยู่ในโฟลเดอร์แยก
)

# วิธีที่ 2: ดึง Markdown string โดยตรง (รูปภาพเป็น base64)
markdown_str = result.document.export_to_markdown(
    image_mode=ImageRefMode.EMBEDDED # รูปภาพอยู่ใน Markdown เลย
)
print(markdown_str[:500]) # แสดง 500 ตัวอักษรแรก

from docling_core.transforms.serializer.markdown import (
    MarkdownDocSerializer,
    MarkdownParams,
    ImageAltTextMode,
)

serializer = MarkdownDocSerializer(
    doc=result.document,
    params=MarkdownParams(
        image_mode=ImageRefMode.REFERENCED,
        image_alt_mode=ImageAltTextMode.STATIC, # default
    )
)
output = serializer.serialize().text

![Image](images/image_001.png)

params = MarkdownParams(
    image_mode=ImageRefMode.REFERENCED,
    image_alt_mode=ImageAltTextMode.CAPTION,
)

![Figure 1: Revenue growth comparison 2020-2024](images/image_001.png)

params = MarkdownParams(
    image_mode=ImageRefMode.REFERENCED,
    image_alt_mode=ImageAltTextMode.DESCRIPTION,
)

![A bar chart showing revenue growth from 2020 to 2024, with values increasing from $2M to $5M](images/image_001.png)

# ติดตั้งพื้นฐาน
pip install docling-serve

# ติดตั้งพร้อม UI สำหรับทดสอบ
pip install "docling-serve[ui]"

# รัน server พื้นฐาน (port 5001 โดย default)
docling-serve run

# รันพร้อม UI สำหรับทดสอบที่ http://localhost:5001/ui
docling-serve run --enable-ui

curl -X POST "http://localhost:5001/v1/convert/file" \
  -H "accept: application/json" \
  -F "files=@document.pdf;type=application/pdf" \
  -F "to_formats=md" \
  -F "generate_picture_images=true" \
  -F "images_scale=2.0" \
  -F "do_picture_description=true" \
  -F "picture_description_preset=granite_vision" \
  -F "picture_description_area_threshold=0" \
  -F "image_export_mode=referenced"

curl -X POST "http://localhost:5001/v1/convert/source" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "to_formats": ["md"],
      "do_picture_description": true,
      "picture_description_preset": "granite_vision",
      "picture_description_area_threshold": 0,
      "image_export_mode": "referenced"
    },
    "sources": [
      { "kind": "http", "url": "https://example.com/document.pdf" }
    ]
  }'

# Encode ไฟล์เป็น base64 ก่อน
BASE64_PDF=$(base64 -w0 document.pdf)

curl -X POST "http://localhost:5001/v1/convert/source" \
  -H "Content-Type: application/json" \
  -d "{
    \"options\": {
      \"to_formats\": [\"md\"],
      \"do_picture_description\": true,
      \"picture_description_preset\": \"granite_vision\",
      \"picture_description_area_threshold\": 0,
      \"image_export_mode\": \"embedded\"
    },
    \"file_sources\": [{
      \"base64_string\": \"$BASE64_PDF\",
      \"filename\": \"document.pdf\"
    }]
  }"

curl -X POST "http://localhost:5001/v1/convert/source" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "to_formats": ["md"],
      "do_picture_description": true,
      "picture_description_preset": "granite_vision",
      "picture_description_area_threshold": 0,
      "image_export_mode": "referenced",
      "image_alt_mode": "description"
    },
    "sources": [
      { "kind": "http", "url": "https://example.com/document.pdf" }
    ]
  }'

curl -X POST "http://localhost:5001/v1/convert/source" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "to_formats": ["md"],
      "do_picture_description": true,
      "picture_description_preset": "granite_vision",
      "picture_description_area_threshold": 0,
      "image_export_mode": "referenced",
      "image_alt_mode": "description",
      "classification_allow": ["photograph", "bar_chart", "pie_chart", "line_chart"],
      "classification_min_confidence": 0.7
    },
    "sources": [
      { "kind": "http", "url": "https://example.com/document.pdf" }
    ]
  }'

{
  "document": {
    "md_content": "# เนื้อหาเอกสาร\n\n![AI description here](images/img_001.png)\n\n..."
  },
  "status": "success"
}

# Annual Report 2024

The following chart shows our growth trajectory.

<!-- image -->

Table 1 below compares performance metrics...

# Annual Report 2024

The following chart shows our growth trajectory.

![Image](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...)

Table 1 below compares performance metrics...

# Annual Report 2024

The following chart shows our growth trajectory.

![Image](document_artifacts/pictures/picture_001.png)

Table 1 below compares performance metrics...

output/
├── document.md
└── document_artifacts/
    └── pictures/
        ├── picture_001.png
        ├── picture_002.png
        └── picture_003.png

![Image](document_artifacts/pictures/picture_001.png)

![A bar chart showing quarterly revenue growth from Q1 2020 to Q4 2024. Revenue increased steadily from $2.1M in Q1 2020 to $5.4M in Q4 2024, with the highest growth rate occurring between 2022 and 2023.](document_artifacts/pictures/picture_001.png)

![Figure 3: Quarterly Revenue Growth 2020-2024 (Source: Finance Department)](document_artifacts/pictures/picture_001.png)

# ผลประกอบการประจำปี 2024

## บทสรุปผู้บริหาร

รายได้รวมในปี 2024 อยู่ที่ 5.4 ล้านดอลลาร์ เติบโต 23% จากปีก่อนหน้า

![A bar chart showing quarterly revenue growth from Q1 2020 to Q4 2024. Values range from $2.1M to $5.4M with consistent upward trend.](document_artifacts/pictures/picture_001.png)

ดังแสดงในแผนภูมิ รายได้เติบโตต่อเนื่องทุกไตรมาส โดยเฉพาะในช่วงปี 2022-2023

## ตลาดหลัก

![Pie chart showing market distribution: Asia Pacific 45%, Americas 30%, Europe 20%, Others 5%](document_artifacts/pictures/picture_002.png)

ตลาด Asia Pacific ยังคงเป็นตลาดหลักที่สำคัญที่สุด คิดเป็น 45% ของรายได้รวม

pipeline_options = PdfPipelineOptions(
    generate_picture_images=True,
    images_scale=2.0, # แนะนำ: 2.0 สำหรับงานทั่วไป
)

# Python SDK (ผ่าน custom_config - ต้องการ admin permission ใน docling-serve)
from docling.datamodel.pipeline_options import PictureDescriptionApiOptions

pipeline_options = PdfPipelineOptions(
    do_picture_description=True,
    picture_description_preset="granite_vision",
    picture_description_area_threshold=0.02, # รูปที่ใหญ่กว่า 2% ของหน้า
)

{
  "options": {
    "do_picture_description": true,
    "picture_description_preset": "granite_vision",
    "picture_description_area_threshold": 0.02,
    "classification_allow": ["photograph", "bar_chart", "pie_chart", "line_chart", "scatter_plot"],
    "classification_min_confidence": 0.7
  }
}

# แนะนำสำหรับงาน production ส่วนใหญ่
result.document.save_as_markdown(
    output_dir / "document.md",
    image_mode=ImageRefMode.REFERENCED
)

# สำหรับ portable single file
markdown_text = result.document.export_to_markdown(
    image_mode=ImageRefMode.EMBEDDED
)

# ต้องเปิดใช้งานก่อน:
export DOCLING_SERVE_ALLOW_CUSTOM_PICTURE_DESCRIPTION_CONFIG=true
export DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true

{
  "options": {
    "to_formats": ["md"],
    "do_picture_description": true,
    "picture_description_custom_config": {
      "engine_options": { "engine_type": "api" },
      "model_spec": {
        "name": "GPT-4o Vision",
        "default_repo_id": "openai/gpt-4o",
        "prompt": "Describe this image concisely in 1-2 sentences for use as alt text.",
        "response_format": "text"
      },
      "api_overrides": {
        "api": {
          "url": "https://api.openai.com/v1/chat/completions",
          "headers": { "Authorization": "Bearer YOUR_OPENAI_API_KEY" },
          "params": { "model": "gpt-4o" }
        }
      }
    },
    "image_alt_mode": "description",
    "image_export_mode": "referenced"
  },
  "sources": [{ "kind": "http", "url": "https://example.com/document.pdf" }]
}

from pathlib import Path
from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.datamodel.base_models import InputFormat
from docling_core.types.doc import ImageRefMode

pipeline_options = PdfPipelineOptions(
    generate_picture_images=True,
    images_scale=2.0,
    do_picture_description=True,
    picture_description_preset="granite_vision",
    picture_description_area_threshold=0.05, # ข้ามรูปเล็กเพื่อประหยัดเวลา
)

converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)}
)

pdf_files = list(Path("pdfs/").glob("*.pdf"))
output_dir = Path("output")
output_dir.mkdir(exist_ok=True)

# Batch convert
for pdf_path in pdf_files:
    print(f"Processing: {pdf_path.name}")
    result = converter.convert(str(pdf_path))
    out_path = output_dir / pdf_path.stem
    out_path.mkdir(exist_ok=True)
    result.document.save_as_markdown(
        out_path / f"{pdf_path.stem}.md",
        image_mode=ImageRefMode.REFERENCED
    )
    print(f" → Saved to {out_path}")

pipeline_options = PdfPipelineOptions(
    generate_picture_images=True, # ✅ ต้องตั้งเป็น True
)

result.document.save_as_markdown(
    "output.md",
    image_mode=ImageRefMode.REFERENCED # ✅ ไม่ใช่ PLACEHOLDER
)

# ชั่วคราว: ใช้ scale=1.0 แล้ว upscale เองทีหลัง
pipeline_options = PdfPipelineOptions(
    generate_picture_images=True,
    images_scale=1.0 # ✅ ใช้ 1.0 หากพบ cropping bug
)

pipeline_options = PdfPipelineOptions(
    do_picture_description=True, # ✅ ต้องเป็น True
    picture_description_preset="granite_vision",
)

# รูปอาจเล็กกว่า threshold (default 0.05 = 5%)
pipeline_options = PdfPipelineOptions(
    do_picture_description=True,
    picture_description_area_threshold=0, # ✅ อธิบายทุกรูป
)

# ดู log ขณะรัน
python -c "
from docling.datamodel.pipeline_options import PdfPipelineOptions
opts = PdfPipelineOptions(do_picture_description=True, picture_description_preset='granite_vision')
print('Options created successfully')
"

# 1. Download model บนเครื่องที่มี internet
huggingface-cli download ibm-granite/granite-vision-3.3-2b

# 2. ระบุ path ใน environment variable
export HF_HOME=/path/to/local/models
export TRANSFORMERS_OFFLINE=1

# ตรวจสอบ JSON ก่อนส่ง
echo '{"options": {...}}' | jq .

# เพิ่ม timeout ใน curl
curl --max-time 300 -X POST ...

# หรือใช้ async endpoint
POST /v1/convert/file/async
POST /v1/convert/source/async

# ติดตั้งใหม่แบบ clean
pip uninstall docling docling-core docling-ibm-models -y
pip install docling

# ตรวจสอบ dependencies
pip show docling