microsoft / microsoft/markitdown

Title: Expose model_id and analysis features as configurable parameters in DocumentIntelligenceConverter

Open
#2,273 0 comments 8 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
186k
Forks
13.7k
Avg merge
1d 4h
Merged PRs (30d)
49

Description

Summary

DocumentIntelligenceConverter currently hardcodes the Azure Document Intelligence model to prebuilt-layout and hardcodes three billable add-on features (FORMULAS, OCR_HIGH_RESOLUTION, STYLE_FONT) for OCR-eligible file types (PDF, JPEG, PNG, BMP, TIFF). There is no constructor parameter or other supported way to select a different model (e.g. prebuilt-read) or to disable the add-on features.

This makes MarkItDown significantly more expensive than necessary for use cases that only need plain-text OCR, with no way to opt out short of bypassing MarkItDown's Document Intelligence integration entirely and calling azure-ai-documentintelligence directly.

Where this happens

packages/markitdown/src/markitdown/converters/_doc_intel_converter.py:

The convert() method calls begin_analyze_document with the model passed as the literal string "prebuilt-layout".
The feature-selection helper returns a fixed list (FORMULAS, OCR_HIGH_RESOLUTION, STYLE_FONT) for any OCR-eligible input, unconditionally.
The constructor only accepts endpoint, api_version, credential, and file_types — no model_id or features parameter exists.
Why this matters (cost impact)

Per Azure's pay-as-you-go pricing:

prebuilt-read, no add-ons: ~$1.50 / 1,000 pages
prebuilt-layout + the three add-ons above: ~$16–28+ / 1,000 pages

That's roughly a 10–19x cost difference for the same input, with no way to select the cheaper path through MarkItDown's public API. On our own workload (batch OCR of scanned PDFs where we only needed plain text), this hardcoded default drove Document Intelligence costs to several thousand dollars more than a prebuilt-read-based approach would have — validated by reprocessing a sample of our documents with prebuilt-read and confirming identical extracted text.

We recognize prebuilt-layout + full add-ons may be the right default for MarkItDown's stated goal of high-fidelity Markdown conversion. The ask here isn't to change the default — it's to expose the choice.

Proposed change

Add optional constructor parameters to DocumentIntelligenceConverter (and the corresponding MarkItDown(...) kwargs, e.g. docintel_model_id, docintel_features), defaulting to today's behavior (prebuilt-layout + the three add-ons) for backward compatibility, but allowing callers to override both:

python
md = MarkItDown(
docintel_endpoint="...",
docintel_model_id="prebuilt-read",
docintel_features=[], # disable add-ons
)

This would let cost-sensitive use cases (plain-text OCR, high page volumes) opt into a cheaper path without forking or bypassing the converter.

Alternatives considered
Bypassing MarkItDown's Document Intelligence integration and calling azure-ai-documentintelligence directly. This works — and is what we ultimately did — but it means giving up the convenience this converter provides: requesting output_content_format="markdown" from Azure (so Azure generates the Markdown, not MarkItDown) and stripping HTML comments from the result before wrapping it in a DocumentConverterResult. Small on its own, but it meant our application took on its own client construction, model/feature configuration, and (in our case) per-page OCR gating and text reconstruction from returned page spans — logic MarkItDown's converter doesn't need since it always analyzes the whole document with a fixed configuration.

Happy to submit a PR for this if the maintainers are open to the approach above.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in packages/markitdown/src/markitdown/converters/_doc_intel_converter.py, inspecting the constructor, convert(), and feature-selection helper, then trace the corresponding MarkItDown(...) kwargs. Done means callers can override the model and features while the existing prebuilt-layout and add-on defaults remain unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
azure, python
Domain
api, backend
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.