Docling యొక్క ఏకీకృత మల్టీ-ఫార్మాట్ parser ఉపయోగించి డాక్యుమెంట్లను ఎక్స్‌ట్రాక్ట్ చేయండి

పరిచయం

Retrieval-augmented generation పైప్‌లైన్‌లను నిర్మించే టీమ్‌లు మొదటి రోజే ఒకే అడ్డంకిని ఎదుర్కొంటాయి: ప్రతి ఇన్‌పుట్ ఫార్మాట్ — PDF, DOCX, HTML, PPTX, స్కాన్ చేసిన ఇమేజ్‌లు — దానికి సొంత పార్సర్, సొంత విచిత్రాలు, సొంత బగ్ సర్ఫేస్ అవసరం, మరియు వాటి చుట్టూ ఉన్న రాపర్‌లు అవుట్‌పుట్ స్కీమాపై అరుదుగా ఏకాభిప్రాయానికి వస్తాయి. Docling దాన్ని ఎప్పుడూ ఒకే విధంగా ఆకృతి చేసిన ట్రీని తిరిగి ఇచ్చే ఒకే ఎక్స్‌ట్రాక్షన్ ఇంటర్‌ఫేస్‌గా కుదిస్తుంది. ఈ లేయర్‌ను తప్పుగా చేస్తే, డౌన్‌స్ట్రీమ్‌లోని ప్రతి కన్స్యూమర్ (chunker, embedder, retriever, evaluator) ఆ అస్థిరతను వారసత్వంగా పొందుతుంది, అందువల్ల ఒకే చెడ్డ పార్సర్ మొత్తం RAG స్టాక్‌ను పాడు చేస్తుంది. ఈ పాఠం ముగిసే సమయానికి, మీరు OCR మరియు టేబుల్ డిటెక్షన్‌తో ప్రొడక్షన్-గ్రేడ్ PDF ఎక్స్‌ట్రాక్షన్ కోసం Docling యొక్క DocumentConverter‌ను కాన్ఫిగర్ చేయగలరు, వ్యక్తిగత విఫలతలపై ఆగిపోకుండా మిక్స్‌డ్-ఫార్మాట్ బ్యాచ్‌లపై దాన్ని రన్ చేయగలరు, మరియు డౌన్‌స్ట్రీమ్ దశల కోసం కంటెంట్ బ్లాక్‌లు, టేబుల్‌లు, మరియు provenance మెటాడేటాను బయటకు తీయడానికి ఫలితంగా వచ్చే DoclingDocument ట్రీలో నావిగేట్ చేయగలరు.

కీలక పదజాలం

• DocumentConverter: ఇన్‌పుట్ ఫైల్‌లను ఫార్మాట్-నిర్దిష్ట పైప్‌లైన్‌లకు పంపి, సోర్స్ ఫార్మాట్ ఏదైనా ఒకే విధంగా ఆకృతి చేసిన DoclingDocument‌ను తిరిగి ఇచ్చే Docling యొక్క ఏకైక ఎంట్రీ-పాయింట్ క్లాస్.
• DoclingDocument: Docling ఉత్పత్తి చేసే కంటెంట్ ఎలిమెంట్‌ల (TextItem, SectionHeaderItem, TableItem, PictureItem) టైప్ చేసిన ట్రీ; గ్రౌండింగ్ కోసం ప్రతి ఒక్కటి పేజీ నంబర్ మరియు bounding box ఉన్న prov మెటాడేటాను కలిగి ఉంటుంది.
• TableFormer: Docling యొక్క టేబుల్-స్ట్రక్చర్ రికగ్నిషన్ మోడల్; టేబుల్‌లు ఎక్కువగా ఉన్న PDFలపై ఎక్స్‌ట్రాక్షన్ నాణ్యతను వేగంతో మార్చుకోవడానికి TableFormerMode (FAST లేదా ACCURATE) ద్వారా కాన్ఫిగర్ చేయవచ్చు.
• PdfPipelineOptions: ఒక DocumentConverter ఇన్‌స్టాన్స్‌పై OCR, టేబుల్-స్ట్రక్చర్ డిటెక్షన్, ఇమేజ్ స్కేలింగ్, మరియు ఇతర PDF-నిర్దిష్ట ఎక్స్‌ట్రాక్షన్ ప్రవర్తనను టోగుల్ చేసే ప్రతి-ఫార్మాట్ కాన్ఫిగరేషన్ ఆబ్జెక్ట్.
• ConversionStatus: ఒకే చెడ్డ ఇన్‌పుట్‌పై ఆగిపోకుండా బ్యాచ్ జాబ్‌లు ఫలిత నాణ్యత ఆధారంగా బ్రాంచ్ చేయగలిగేలా convert_all() తిరిగి ఇచ్చే ప్రతి-డాక్యుమెంట్ ఫలితం (SUCCESS, PARTIAL_SUCCESS, FAILURE).

భావనలు

Docling విలువ ఏమిటంటే, అది ఫార్మాట్-నిర్దిష్ట పార్సింగ్‌ను ఒకే కన్వర్టర్ మరియు ఒకే అవుట్‌పుట్ స్కీమా వెనుక దాచిపెడుతుంది, అందువల్ల RAG పైప్‌లైన్‌లోని మిగిలిన భాగాన్ని ఒకే ట్రీ ఆకృతికి అనుగుణంగా రాయవచ్చు. ఈ పాఠాన్ని మూడు ఆలోచనలు నడిపిస్తాయి:

1. ఒకే కాన్ఫిగర్ చేసిన కన్వర్టర్, అనేక ఫార్మాట్‌లు. ఒక DocumentConverter ప్రతి InputFormat‌కు ఒక పైప్‌లైన్‌ను (OCR సెట్టింగ్‌లు, టేబుల్-స్ట్రక్చర్ మోడ్, ఇమేజ్ స్కేల్) అనుసంధానించే format_options మ్యాప్‌తో ఒక్కసారి ఇనిషియలైజ్ అవుతుంది. ఆ తర్వాత అదే ఇన్‌స్టాన్స్ కాలర్ కోడ్‌లో ప్రతి-కాల్ బ్రాంచింగ్ లేకుండా PDF, DOCX, HTML, PPTX, మరియు ఇమేజ్ ఇన్‌పుట్‌లను హ్యాండిల్ చేస్తుంది.
2. వేరుచేసిన విఫలతలతో బ్యాచ్ ప్రాసెసింగ్. convert_all(..., raises_on_error=False) ప్రతి ఇన్‌పుట్‌కు ఒక ConversionResult‌ను అందిస్తుంది, దీనివల్ల ఒక చెడిపోయిన PDF ConversionStatus.FAILUREగా బయటపడుతుంది, అయితే బ్యాచ్‌లోని మిగిలినవి రన్ అవుతూనే ఉంటాయి — భిన్నమైన డాక్యుమెంట్ కార్పస్‌లను పెద్ద స్థాయిలో ఇన్‌జెస్ట్ చేసేటప్పుడు ఇది అత్యవసరం.
3. Provenance ఉన్న ఒకే విధమైన ట్రీ. ప్రతి విజయవంతమైన ఎక్స్‌ట్రాక్షన్ ఒక DoclingDocument‌ను ఉత్పత్తి చేస్తుంది, దాని iterate_items() నడక prov మెటాడేటా ఉన్న టైప్ చేసిన నోడ్‌లను (TextItem, SectionHeaderItem, TableItem, PictureItem) అందిస్తుంది. డౌన్‌స్ట్రీమ్ chunkerలు మరియు retrieverలు ఒకే ఆకృతిని వినియోగిస్తాయి, మరియు provenance సమాధానాలు అవి వచ్చిన ఖచ్చితమైన పేజీ మరియు bounding boxను ఉదహరించడానికి వీలు కల్పిస్తుంది.

కోడ్ వాక్‌త్రూ

ఈ వాక్‌త్రూ పైప్‌లైన్‌లోని రెండు దశలను వరుసగా కవర్ చేస్తుంది. మొదటి దశ కాన్ఫిగర్ చేసిన DocumentConverter‌ను నిర్మించి, దాని ద్వారా మిక్స్‌డ్-ఫార్మాట్ బ్యాచ్‌ను రన్ చేస్తుంది; రెండవ దశ ఫలితంగా వచ్చే DoclingDocument ట్రీలో నావిగేట్ చేసి, సోర్స్ ఫార్మాట్ ఏదైనా డౌన్‌స్ట్రీమ్ chunkerలు స్థిరమైన నిర్మాణాన్ని చూసేలా హెడింగ్ హైరార్కీలను నార్మలైజ్ చేస్తుంది.

కన్వర్టర్‌ను కాన్ఫిగర్ చేసి రన్ చేయడం

కన్వర్టర్ OCR, టేబుల్ డిటెక్షన్, మరియు ఇమేజ్ రిజల్యూషన్‌ను నియంత్రించే ప్రతి-ఫార్మాట్ పైప్‌లైన్ ఆప్షన్‌లను తీసుకుంటుంది, ఆ తర్వాత బ్యాచ్ ప్రాసెసింగ్ కోసం convert_all()‌ను అందిస్తుంది. కింది స్నిప్పెట్ born-digital మరియు స్కాన్ చేసిన ఇన్‌పుట్‌లు రెండింటికీ PDF ఎక్స్‌ట్రాక్షన్‌ను కాన్ఫిగర్ చేసి, PDFల డైరెక్టరీపై దాన్ని రన్ చేస్తుంది, బ్యాచ్‌ను ఆపకుండా వ్యక్తిగత విఫలతలను హ్యాండిల్ చేస్తుంది:

Code snippetpython
1from pathlib import Path
2from docling.document_converter import DocumentConverter, PdfFormatOption
3from docling.datamodel.pipeline_options import (
4    PdfPipelineOptions,
5    EasyOcrOptions,
6    TableFormerMode,
7)
8from docling.datamodel.base_models import InputFormat, ConversionStatus
9
10ocr_options = EasyOcrOptions(
11    lang=["en"],
12    force_full_page_ocr=False,
13)
14
15pipeline_options = PdfPipelineOptions(
16    do_ocr=True,
17    ocr_options=ocr_options,
18    do_table_structure=True,
19    table_structure_options={"mode": TableFormerMode.ACCURATE},
20    images_scale=2.0,
21)
22
23converter = DocumentConverter(
24    format_options={
25        InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options),
26    }
27)
28
29pdf_files = list(Path("/data/incoming/").glob("**/*.pdf"))
30results = converter.convert_all(pdf_files, raises_on_error=False)
31
32for result in results:
33    if result.status == ConversionStatus.SUCCESS:
34        doc = result.document
35        markdown = doc.export_to_markdown()
36        print(f"Processed {result.input.file}: {len(doc.pages)} pages")
37    elif result.status == ConversionStatus.PARTIAL_SUCCESS:
38        print(f"Partial: {result.input.file} - {len(result.errors)} errors")
39    else:
40        print(f"Failed: {result.input.file} - {result.errors}")

• EasyOcrOptions(force_full_page_ocr=False) ఎక్స్‌ట్రాక్ట్ చేయగల టెక్స్ట్ లేయర్ లేని పేజీలపై మాత్రమే OCRను రన్ చేస్తుంది, అందువల్ల born-digital PDFలు OCR భారాన్ని పూర్తిగా దాటవేస్తాయి, అయితే స్కాన్ చేసిన పేజీలు ఇంకా ప్రాసెస్ అవుతాయి.
• PdfPipelineOptions OCRను, accurate మోడ్‌లో TableFormer‌ను ఉపయోగించి టేబుల్-స్ట్రక్చర్ డిటెక్షన్‌ను, మరియు 2× ఇమేజ్ రిజల్యూషన్ స్కేలింగ్‌ను ఎనేబుల్ చేస్తుంది. ఎక్కువ images_scale విలువలు చిన్న టెక్స్ట్‌పై OCR నాణ్యతను మెరుగుపరుస్తాయి, కానీ మెమరీ వినియోగాన్ని మరియు ప్రతి-పేజీ ప్రాసెసింగ్ సమయాన్ని పెంచుతాయి.
• format_options dict ఇన్‌పుట్ ఫార్మాట్‌లను ఫార్మాట్-నిర్దిష్ట పైప్‌లైన్‌లకు మ్యాప్ చేస్తుంది. అదే కన్వర్టర్ ఇన్‌స్టాన్స్‌ను ఇతర ఇన్‌పుట్‌లకు విస్తరించడానికి వాటి సొంత ఆప్షన్‌లతో InputFormat.DOCX లేదా InputFormat.HTML ఎంట్రీలను జోడించండి.
• convert_all(..., raises_on_error=False) ప్రతి డాక్యుమెంట్‌కు ఒక ConversionResult‌ను అందిస్తుంది మరియు విఫలతలను వేరుచేస్తుంది, అందువల్ల ఒక చెడిపోయిన PDF బ్యాచ్‌ను ఆపదు. శుభ్రమైన ఎక్స్‌ట్రాక్షన్‌లను పాక్షికమైనవాటి నుంచి వేరు చేయడానికి ConversionStatus.{SUCCESS, PARTIAL_SUCCESS}పై బ్రాంచ్ చేయండి, మరియు హెడింగ్ లెవెల్స్, టేబుల్ ఫార్మాటింగ్, మరియు ఫిగర్ రిఫరెన్స్‌లను కాపాడుకుంటూ డాక్యుమెంట్ ట్రీని సీరియలైజ్ చేయడానికి **export_to_markdown()**‌ను కాల్ చేయండి.

అవుట్‌పుట్‌లో నావిగేట్ చేయడం మరియు ఫార్మాట్‌ల మధ్య నార్మలైజ్ చేయడం

DoclingDocument ఆబ్జెక్ట్ కంటెంట్‌ను టైప్ చేసిన ఎలిమెంట్‌ల ట్రీగా అందిస్తుంది. ఆ ట్రీని నడవడం వల్ల మీకు chunkerలు, embedderలు, లేదా evaluatorలకు అందించగల ఫ్లాట్, టైప్ చేసిన బ్లాక్‌ల జాబితా లభిస్తుంది — మరియు ట్రీ చేతికి వచ్చాక, ఫార్మాట్‌ల మధ్య చొరబడే నిర్మాణాత్మక తేడాలను (PDF ఫాంట్-సైజ్ హ్యూరిస్టిక్స్, DOCX హెడింగ్ స్టైల్స్, <h2> వద్ద మొదలయ్యే HTML) కూడా మీరు సర్దుబాటు చేయవచ్చు:

Code snippetpython
1from docling.datamodel.document import DoclingDocument
2
3def extract_content_blocks(doc: DoclingDocument) -> list[dict]:
4    blocks = []
5    for item, level in doc.iterate_items():
6        block = {
7            "type": item.__class__.__name__,
8            "text": item.text if hasattr(item, "text") else "",
9            "level": level,
10            "page": item.prov[0].page_no if item.prov else None,
11            "bbox": item.prov[0].bbox.as_tuple() if item.prov else None,
12        }
13        if item.__class__.__name__ == "TableItem":
14            block["table_data"] = item.export_to_dataframe().to_dict()
15        blocks.append(block)
16    return blocks
17
18def normalize_heading_levels(doc: DoclingDocument) -> DoclingDocument:
19    """Shift headings so the document always starts at h1."""
20    heading_levels_seen = {
21        item.level
22        for item, _ in doc.iterate_items()
23        if item.__class__.__name__ == "SectionHeaderItem"
24    }
25    if heading_levels_seen and min(heading_levels_seen) > 1:
26        offset = min(heading_levels_seen) - 1
27        for item, _ in doc.iterate_items():
28            if item.__class__.__name__ == "SectionHeaderItem":
29                item.level = max(1, item.level - offset)
30    return doc

• iterate_items() డాక్యుమెంట్ హైరార్కీలో దాని డెప్త్ లెవెల్‌తో పాటు ప్రతి కంటెంట్ ఎలిమెంట్‌ను అందిస్తుంది. ఎలిమెంట్ రకాల్లో TextItem (పేరాగ్రాఫ్‌లు), SectionHeaderItem (హెడింగ్‌లు), TableItem (టేబుల్‌లు), మరియు PictureItem (ఫిగర్‌లు) ఉన్నాయి. ప్రతి ఎలిమెంట్ పేజీ నంబర్, bounding box, మరియు confidence ఉన్న prov (provenance) మెటాడేటాను కలిగి ఉంటుంది — ఉదహరణలు, retrieval, మరియు గ్రౌండింగ్‌కు ఇది అత్యవసరం.
• టేబుల్‌లకు ప్రత్యేక ట్రీట్‌మెంట్ లభిస్తుంది: export_to_dataframe() Docling యొక్క అంతర్గత టేబుల్ ప్రాతినిధ్యాన్ని pandas DataFrameగా మారుస్తుంది, దాన్ని మీరు డౌన్‌స్ట్రీమ్ కన్స్యూమర్‌ల కోసం JSON, CSV, లేదా Parquetకు సీరియలైజ్ చేయవచ్చు.
• normalize_heading_levels ఉపయోగించిన కనిష్ట హెడింగ్ లెవెల్ కోసం ట్రీని స్కాన్ చేసి, డాక్యుమెంట్ h1 వద్ద మొదలయ్యేలా ప్రతి హెడింగ్‌ను కిందికి షిఫ్ట్ చేస్తుంది. ఇది ఫార్మాట్‌ల మధ్య నిర్మాణం-ఆధారిత chunkingను డిటర్మినిస్టిక్‌గా చేస్తుంది — ఇది లేకపోతే, <h2> వద్ద మొదలయ్యే HTML పేజీ మరియు h1 వద్ద మొదలయ్యే PDF సూక్ష్మంగా భిన్నమైన chunk సరిహద్దులను ఉత్పత్తి చేస్తాయి.

convert_all() కనీసం ఒక ConversionStatus.SUCCESS ఫలితాన్ని తిరిగి ఇచ్చినప్పుడు, extract_content_blocks(doc) నింపబడిన page మరియు bbox ఫీల్డ్‌లతో TextItem మరియు SectionHeaderItem ఎంట్రీలను కలిగి ఉన్న ఖాళీ-కాని జాబితాను తిరిగి ఇచ్చినప్పుడు, మరియు normalize_heading_levels(doc) సోర్స్ ఫార్మాట్ ఏదైనా మొదటి హెడింగ్ లెవెల్ 1 ఉన్న డాక్యుమెంట్‌ను ఉత్పత్తి చేసినప్పుడు, అది పనిచేస్తుందని మీకు తెలుస్తుంది.

విభాగ అనువర్తనం

చేయవలసినవి మరియు చేయకూడనివి

ఇప్పుడు మీరు ఇంప్లిమెంటేషన్‌ను పూర్తి చేశారు కాబట్టి, కింది పద్ధతులు మన్నికైన విధానాన్ని బలహీనమైన విధానం నుంచి వేరు చేస్తాయి.

చేయవలసినవి

1. ప్రతి వర్కర్ ప్రాసెస్‌కు ఒక DocumentConverter‌ను ఇనిషియలైజ్ చేసి, డాక్యుమెంట్‌ల మధ్య దాన్ని మళ్లీ ఉపయోగించండి — TableFormer మరియు OCR మోడల్ లోడింగ్ మొదటి-కాల్ లేటెన్సీలో ప్రధాన భాగం, అందువల్ల ప్రతి-కాల్ నిర్మాణం బ్యాచ్ జాబ్‌లను అనేక రెట్లు నెమ్మదిగా చేస్తుంది.
2. convert_all()‌కు raises_on_error=False పాస్ చేసి, ConversionStatus.{SUCCESS, PARTIAL_SUCCESS, FAILURE}పై స్పష్టంగా బ్రాంచ్ చేయండి, దీనివల్ల ఒక పాడైన PDF వేల డాక్యుమెంట్‌ల ఇన్‌జెస్ట్‌ను ఆపదు.
3. chunkerలు మరియు embedderలకు బ్లాక్‌లను పంపేటప్పుడు item.prov (పేజీ నంబర్ మరియు bounding box)ను కాపాడండి — డౌన్‌స్ట్రీమ్ retrieval మరియు సమాధాన-గ్రౌండింగ్ ఉదహరణల కోసం దానిపై ఆధారపడతాయి.

చేయకూడనివి

1. కాలర్ కోడ్‌లో ప్రతి-ఫార్మాట్ if pdf … elif docx … బ్రాంచ్‌లను రాయకండి — format_optionsలో ఫార్మాట్-నిర్దిష్ట PdfFormatOption / DocxFormatOption ఎంట్రీలను రిజిస్టర్ చేసి, convert()‌ను పాలిమార్ఫిక్‌గా కాల్ చేయండి.
2. డిఫాల్ట్‌గా images_scale‌ను 2–3 కంటే పైకి పెంచకండి; అది మెమరీని మరియు ప్రతి-పేజీ సమయాన్ని రెట్టింపు చేస్తుంది, మరియు ఇప్పటికే చదవగలిగే టెక్స్ట్‌పై OCR నాణ్యతను అరుదుగా మెరుగుపరుస్తుంది.
3. ConversionStatus.PARTIAL_SUCCESS ఫలితాలను నిశ్శబ్దంగా వదిలేయకండి — result.errors‌ను పరిశీలించి, పాక్షిక కంటెంట్ ఉపయోగపడుతుందా లేదా క్వారంటైన్ చేయాలా అని ప్రతి పైప్‌లైన్‌కు నిర్ణయించండి.