MinerU-HTML-v1.1-hunyuan0.5B-compact

MinerU-HTML 是一款基于小型语言模型（SLM）的高级 HTML 主内容提取工具。它能够精准识别并提取复杂网页 HTML 中的主要内容，自动过滤导航栏、广告、元数据等辅助元素。

MinerU-HTML-v1.1-hunyuan0.5B-compact 是 腾讯混元 0.5B 的模型衍生版本。该模型支持 256k 上下文长度，因此能够处理更复杂的网页。我们采用了更紧凑的输出格式，有效降低了推理延迟，提升了网页处理速度。

前往官网试用 -> Mineru-Extractor

欢迎试用我们的在线文档提取工具！支持 HTML 主内容提取以及多种文档格式的 OCR 识别。

或

克隆到本地使用 -> MinerU-HTML —— 现已更新至 v1.1 版本！

✨ 特性

🎯 LLM 驱动提取：采用最先进的语言模型，智能识别主要内容
⚡ 紧凑格式：模型采用紧凑格式替代原始 JSON 格式，实现更快的推理速度
⚡ 正则结构化输出：模型采用正则结构化输出替代自定义 logits 处理器，因此可使用 vLLM v1 后端进行推理
🔄 完整处理流程：包含 HTML 简化、提示词构建、LLM 推理、结果解析、主内容提取等完整流程
🚀 多推理后端支持：支持 VLLM、Transformers 和 OpenAI API 三种推理后端
🛡️ 容错机制：支持降级机制（trafilatura、绕过或空值），确保处理失败时仍能进行内容提取
🔌 模块化设计：架构设计清晰，易于扩展和定制
🧪 完善测试：包含全面的单元测试和集成测试

评估结果

我们在 WebMainBench v1.1 基准数据集上对 MinerU-HTML 进行了评估。该数据集包含 7,809 个（v1.0 版本为 7,887 个，我们移除了部分低质量网页）经过精心标注的网页，以及使用 html2text 转换得到的对应 Markdown 格式主内容。该基准通过计算提取结果与真实内容之间的 ROUGE-N 分数来衡量内容提取器的提取准确性。主要评估结果如下表所示：

提取工具	ROUGE-N.f1
DeepSeek-V3*	0.9098
GPT-5*	0.9024
MinerU-HTML-v1.1	0.9001
Magic-HTML	0.7138
Readability	0.6542
Trafilatura	0.6402
Resiliparse	0.6290
html2text	0.6042
BoilerPy3	0.5434
GNE	0.5171
news-please	0.5032
justText	0.4782
Goose3	0.4371
ReaderLM-v2	0.2279

其中 * 表示在 MinerU-HTML 框架中使用 GPT-5/Deepseek-V3 提取主要 HTML，而非我们微调的模型。

🚀 快速开始

下载模型

请访问我们的模型 MinerU-HTML-v1.1-compact 并进行下载，您可以使用以下命令下载模型：

huggingface-cli download opendatalab/MinerU-HTML-v1.1-hunyuan0.5B-compact

安装

基础安装（核心功能）

若仅需使用 MinerU-HTML 的基础功能，克隆仓库并仅安装核心依赖即可：

# Clone the repository
git clone https://github.com/opendatalab/MinerU-HTML
cd MinerU-HTML

# Install the package with core dependencies only
pip install .

安装特定的后端依赖项

根据您的使用场景，您可以选择安装不同的后端依赖项：

# Install VLLM backend dependencies (Default)
pip install .[vllm]

# Install OpenAI backend dependencies
pip install .[openai]

# Install all dependencies
pip install .[all]

基本用法

默认用法（GPU 上的 VLLM 后端）

from mineru_html import MinerUHTML, MinerUHTMLConfig


config = MinerUHTMLConfig(
    use_fall_back='trafilatura',    # optional 'trafilatura','bypass' or 'empty'
    prompt_version='short_compact', # only support 'short_compact' for v1.1
    response_format='compact',      # only support 'compact' for v1.1
    early_load=True
)

# initialize MinerUHTML
extractor = MinerUHTML(
    model_path='path/to/your/model',
    config=config
)

# process single HTML
html_content = '<html>...</html>'
result = extractor.process(html_content)
print(result[0].main_html)

# process multi HTML
html_list = ['<html>...</html>', '<html>...</html>']
results = extractor.process(html_list)
for result in results:
    print(result.main_html)
    print(result.case_id)
extractor.llm.cleanup()

使用 OpenAI API 后端

from mineru_html import MinerUHTML_OpenAI, MinerUHTMLConfig


config = MinerUHTMLConfig(
    use_fall_back='trafilatura',
    prompt_version='v2',          # 'v2' is the best version up to v1.1
    response_format='json',       # only support 'json' for 'v2' prompt version
    early_load=True
)

# initialize MinerUHTML_OpenAI
extractor = MinerUHTML_OpenAI(
    base_url='https://api.openai.com/v1',
    sk='your-api-key',
    model='gpt-4',
    config=config,
    retry_times=3
)

# process HTML
html_content = '<html>...</html>'
result = extractor.process(html_content)
print(result[0].main_html)

使用 Transformers 后端

from mineru_html import MinerUHTML_Transformers, MinerUHTMLConfig

config = MinerUHTMLConfig(
    use_fall_back='trafilatura',
    prompt_version='short_compact',  # only support 'short_compact' for v1.1
    response_format='compact',       # only support 'compact' for v1.1
    early_load=True
)

# initialize MinerUHTML_Transformers
extractor = MinerUHTML_Transformers(
    model_path='path/to/your/model',
    config=config,
    model_init_kwargs={
        'device_map': 'auto',
        'dtype': 'auto',
    },
    model_gen_kwargs={
        'max_new_tokens': 16 * 1024,
    }
)

# process HTML
html_content = '<html>...</html>'
result = extractor.process(html_content)
print(result[0].main_html)

📖 核心概念

处理流程

MinerU-HTML 处理流程包括以下步骤：

HTML 简化（simplify_html）：将原始 HTML 简化为结构化格式，为每个元素分配唯一的 _item_id 属性
提示构建（build_prompt）：基于简化后的 HTML 构建 LLM 提示词，以指导模型进行内容分类
LLM 推理（inference）：使用 LLM 对每个元素进行分类，将其标记为“main”（主要内容）或“other”（辅助内容）
结果解析（parse_result）：解析 LLM 返回的分类结果
主要内容提取（extract_main_html）：根据分类结果从原始 HTML 中提取主要内容
回退处理：如果上述流程失败，则使用回退机制（trafilatura、bypass 或 empty）进行内容提取

配置选项

MinerUHTMLConfig 支持以下配置：

use_fall_back：回退类型，可选 'trafilatura'、'bypass' 或 'empty'
early_load：是否提前加载模型（默认 True）
prompt_version：提示词版本，可选 'v0'、'v1'、'v2'、'compact'、'short_compact'。MinerUHTML 和 MinerUHTML_Transformers 接口默认使用 'short_compact'；MinerUHTML_OpenAI 接口默认使用 'v2'
response_format：模型的输出格式。仅允许 'json' 或 'compact'。VLLM/Transformers 默认使用 'compact'；OpenAI 默认使用 'json'。

不同 prompt_version 的使用说明

'compact'：用于本地模型推理，返回更简洁的结果（仅保留 JSON 字典中的键和值）。建议使用 'compact' 模型以获得更快的推理速度。
'v2'：用于 OpenAI API 推理，是经过提示词优化后的结果。

🔧 高级用法

使用工厂函数创建后端

您也可以直接使用工厂函数创建后端，然后将其传递给 MinerUHTMLGeneric：

from mineru_html import MinerUHTMLGeneric, MinerUHTMLConfig
from mineru_html.inference.factory import create_vllm_backend, create_openai_backend, create_transformers_backend

# Create VLLM backend using factory function
llm = create_vllm_backend(
    model_path='path/to/model',
    response_format='compact',
    max_context_window=32 * 1024,
    model_init_kwargs={'tensor_parallel_size': 1}
)

# Create Transformers backend using factory function
llm = create_transformers_backend(
    model_path='path/to/model',
    max_context_window=32 * 1024,
    response_format='compact',
    model_init_kwargs={
        'device_map': 'auto',
        'dtype': 'auto',
    },
    model_gen_kwargs={
        'max_new_tokens': 8192,
    }
)

# Create OpenAI backend using factory function
llm = create_openai_backend(
    base_url='https://api.openai.com/v1',
    sk='your-api-key',
    model='gpt-5',
    max_context_window=128 * 1000,
    response_format='json'
)

# Use the created backend
config = MinerUHTMLConfig()
extractor = MinerUHTMLGeneric(llm=llm, config=config)

错误处理

from mineru_html.exceptions import MinerUHTMLError

try:
    result = extractor.process(html_content)
except MinerUHTMLError as e:
    print(f"Processing failed: {e}")
    print(f"Case ID: {e.case_id}")

基线评估

若要运行评估，您需要先安装 baselines.txt 中的依赖项。

pip install -r baselines.txt

然后您可以使用以下命令：


BENCHMARK_DATA=benchmark/WebMainBench_100.jsonl
RESULT_DIR=benchmark_results
mkdir $RESULT_DIR

# For MinerU-HTML
EXTRACTORS=(
"mineru_html_fallback-html-md"
)
MODEL_PATH=YOUR_MINERUHTML_MODEL_PATH

for extractor in ${EXTRACTORS[@]}; do
    python eval_baselines.py --bench $BENCHMARK_DATA --task_dir $RESULT_DIR/$extractor --extractor_name  $extractor --model_path $MODEL_PATH --default_config gpu
done

# For CPU Extractors
EXTRACTORS=(
"magichtml-html-md"
"readability-html-md"
"trafilatura-html-md"
"resiliparse-text"
"trafilatura-md"
"trafilatura-text"
"fullpage-html-md"
"boilerpy3-text"
"gne-html-md"
"newsplease-text"
"justtext-text"
"boilerpy3-html-md"
"goose3-text"
)

for extractor in ${EXTRACTORS[@]}; do
    python eval_baselines.py --bench $BENCHMARK_DATA --task_dir $RESULT_DIR/$extractor --extractor_name $extractor
done

# For ReaderLM
extractor=readerlm-text
MODEL_PATH=YOUR_READERLM_MODEL_PATH

python eval_baselines.py --bench $BENCHMARK_DATA --task_dir $RESULT_DIR/$extractor --extractor_name  $extractor --model_path $MODEL_PATH --default_config gpu

MinerU-HTML 支持多种基线提取器用于对比：

MinerU-HTML（mineru_html-html-md、mineru_html-html-text）：基于 LLM 的主要提取器
Magic-HTML：仅支持 CPU 的 HTML 提取工具，同样来自OpenDatalab
Trafilatura：快速且准确的内容提取工具
Readability：Mozilla 的可读性算法
BoilerPy3：Boilerpipe 的 Python 移植版
NewsPlease：新闻文章提取器
Goose3：文章提取器
GNE：通用新闻提取器
ReaderLM：基于 LLM 的文本提取器

许可证

本模型是 Tencent Hunyuan 0.5B 的模型衍生品，并根据腾讯混元社区许可协议进行许可。完整条款请参见 LICENSE 文件。

引用

如果您在研究中使用了本项目，请引用：

@misc{liu2025drippertokenefficientmainhtml,
      title={Dripper: Token-Efficient Main HTML Extraction with a Lightweight LM},
      author={Mengjie Liu and Jiahui Peng and Pei Chu and Jiantao Qiu and Ren Ma and He Zhu and Rui Min and Lindong Lu and Wenchang Ning and Linfeng Hou and Kaiwen Liu and Yuan Qu and Zhenxiang Li and Chao Xu and Zhongying Tu and Wentao Zhang and Conghui He},
      year={2025},
      eprint={2511.23119},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2511.23119},
}

如果您使用提取的 AICC 数据集，请引用：

@misc{ma2025aiccparsehtmlfiner,
      title={AICC: Parse HTML Finer, Make Models Better -- A 7.3T AI-Ready Corpus Built by a Model-Based HTML Parser},
      author={Ren Ma and Jiantao Qiu and Chao Xu and Pei Chu and Kaiwen Liu and Pengli Ren and Yuan Qu and Jiahui Peng and Linfeng Hou and Mengjie Liu and Lindong Lu and Wenchang Ning and Jia Yu and Rui Min and Jin Shi and Haojiong Chen and Peng Zhang and Wenjian Zhang and Qian Jiang and Zengjie Hu and Guoqiang Yang and Zhenxiang Li and Fukai Shang and Runyuan Ma and Chenlin Su and Zhongying Tu and Wentao Zhang and Dahua Lin and Conghui He},
      year={2025},
      eprint={2511.16397},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2511.16397},
}

致谢

基于vLLM构建，以实现高效的LLM推理
使用Trafilatura进行备用提取
在Hunyuan基础上进行微调
受多种HTML内容提取研究的启发
由dingo提供的LLM作为评判器的 pairwise 胜率