本项目是对 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 install mineru-ts
# 使用 pnpm
pnpm add mineru-ts
# 使用 yarn
yarn add mineru-tsgit clone https://github.com/weidwonder/mineru_ts.git
cd mineru_ts
npm install
npm run buildimport { 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 格式- 图像引用格式：
 - 表格转为 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_DIRMINERU_PAGE_CONCURRENCY、MINERU_MAX_CONCURRENCYMINERU_PAGE_LIMIT、MINERU_PERFORMANCE_LOGGINGMINERU_CROP_IMAGE_FORMAT、MINERU_CROP_IMAGE_QUALITY、MINERU_USE_PAGE_CROP_CACHE
MINERU_TEST_PDF=/path/to/your.pdf npm testMINERU_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