MinerU TypeScript (VLM 模式)

本项目是对 MinerU Python 客户端 VLM 模式 的 TypeScript 复刻。
目标：在不依赖 Python 的情况下，尽量复现 Python VLM 的 Markdown 输出结构与格式。

目前仅支持 VLM 模式，其他模式暂不支持。

✨ 特性

• 纯 TypeScript 实现
• VLM 驱动的布局检测与内容提取
• Python VLM 输出链路复刻（middle_json → Markdown）
• 表格 OTSL → HTML 转换
• 并发批量推理与重试机制
• 页级并发控制与页级重试
• 单页可重试错误可自动跳过（避免整文件失败）

📖 文档导航

• 入口说明：CLAUDE.md
• 快速上手：docs/quickstart.md
• 当前状态：docs/status.md
• 架构说明：docs/architecture.md
• 需求与差异：docs/requirements.md
• 测试指南：docs/guides/testing.md

📦 安装

从 npm 安装（推荐）

# 使用 npm
npm install mineru-ts

# 使用 pnpm
pnpm add mineru-ts

# 使用 yarn
yarn add mineru-ts

从源码安装（开发）

git clone https://github.com/weidwonder/mineru_ts.git
cd mineru_ts
npm install
npm run build

🚀 快速开始

import { MinerUClient } from 'mineru-ts';

const client = new MinerUClient({
  serverUrl: 'http://localhost:30000',
  dpi: 200,
  layoutImageSize: [1036, 1036],
  maxConcurrency: 10,
  outputDir: './output',  // 可选：指定输出目录保存提取的图像
});

await client.initialize();
const result = await client.parseFile('/path/to/document.pdf');

// 生成 Markdown 输出
const markdown = client.resultToMarkdown(result);

// 或获取结构化内容列表
const contentList = client.resultToContentList(result);

解析结果说明

parseFile() 返回的 ParseResult 对象包含：

interface ParseResult {
  pages: Array<{              // 每页的内容块
    pageIndex: number;
    blocks: ContentBlock[];   // 文本、标题、表格、图像、公式等块
  }>;
  markdown?: string;          // 可选：生成的 Markdown 文本
  middleJson?: any;           // 可选：中间 JSON 结构（Python VLM 兼容格式）
  metadata: {
    totalPages: number;       // PDF 总页数
    processingTime: number;   // 处理耗时（毫秒）
  };
}

输出说明

Markdown 输出:

• resultToMarkdown(result) 将解析结果转为 Markdown 格式
• 图像引用格式：![](images/hash.png)
• 表格转为 HTML 嵌入

结构化内容:

• resultToContentList(result) 返回内容列表（Python VLM 兼容格式）
• 包含文本、标题、表格、图像等元素的结构化数组

图像文件:

• 如果设置了 outputDir，提取的图像将保存到 {outputDir}/images/ 目录
• 图像文件名为内容的 SHA-256 哈希值（如 abc123...def.png）
• 未设置 outputDir 时不会保存图像文件

🔧 关键配置

interface MinerUClientConfig {
  serverUrl: string;
  dpi?: number;
  layoutImageSize?: [number, number];
  minImageEdge?: number;
  maxImageEdgeRatio?: number;
  cropImageFormat?: 'jpeg' | 'png';
  cropImageQuality?: number;
  usePageCropCache?: boolean;
  maxConcurrency?: number;      // 默认 10
  maxRetries?: number;
  pageConcurrency?: number;     // 默认 2
  pageRetryLimit?: number;
  skipFailedPages?: boolean;
  keepAlive?: boolean;          // 默认 true
  performanceLogging?: boolean;
}

默认性能策略：

• pageConcurrency 默认从 1 调整为 2，避免全页串行，同时保持保守。
• maxConcurrency 默认 10，避免对 VLM 服务盲目打满请求。
• VLM HTTP client 默认启用 HTTP/HTTPS keep-alive agent。
• 内容裁剪默认复用页级 RGB buffer，并以 JPEG 0.75 发送给 VLM，减少重复整页解码与 payload。

常用环境变量：

• MINERU_SERVER_URL、MINERU_VL_MODEL_NAME、MINERU_OUTPUT_DIR
• MINERU_PAGE_CONCURRENCY、MINERU_MAX_CONCURRENCY
• MINERU_PAGE_LIMIT、MINERU_PERFORMANCE_LOGGING
• MINERU_CROP_IMAGE_FORMAT、MINERU_CROP_IMAGE_QUALITY、MINERU_USE_PAGE_CROP_CACHE

🧪 测试

MINERU_TEST_PDF=/path/to/your.pdf npm test

📊 Benchmark

MINERU_TEST_PDF=/path/to/your.pdf MINERU_BENCHMARK_CONCURRENCY=1,2,4 npm run benchmark

脚本会输出 render、layout、content、crop/save、middle_json、markdown 等阶段耗时。

📄 许可证

MIT License