MinerU JS/TS SDK 深度指南：JavaScript/TypeScript 开发者的 PDF/文档解析利器

MinerU 是什么

MinerU 是上海人工智能实验室开源的一站式文档解析工具，基于视觉语言模型（VLM）架构，能够将 PDF、图片、Word、PPT、Excel 等任意格式的文档转换为结构化的 Markdown 输出。最新版本 MinerU2.5-Pro 仅用 1.2B 参数即在 OmniDocBench v1.6 基准上取得 95.69 分，大幅超越 GPT-4o、Qwen2.5-VL-72B 等数十倍参数规模的模型，稳居当前文档解析榜首。

MinerU 的核心能力包括：

• PDF 转 Markdown：保留原始版式、标题层级、段落结构
• 公式识别：复杂 LaTeX 公式准确率高达 98%
• 表格提取：复杂表格识别准确率 92%
• 多语言 OCR：支持 109 种语言的文档识别
• 图片提取：将文档内嵌图片独立导出
• 网页抓取：将任意 URL 网页转换为 Markdown

MinerU 生态包含六大模块：CLI 命令行工具、SDK 多语言开发包、API 云端服务、RAG 知识检索、MCP 协议支持，以及 SKILL 跨语言知识 API。其中 SDK 模块覆盖 Python、.NET、JavaScript/TypeScript 等主流技术栈，大幅降低了开发者的集成门槛。

本文聚焦 JavaScript/TypeScript SDK（包名 mineru-open-sdk），面向需要在前端工程、Node.js 后端服务或 AI Agent 中集成文档解析能力的开发者。

---

安装与环境要求

环境要求

SDK 主要面向 Node.js 18+ 开发，Bun 和 Deno 在提供 Node 兼容 API 时也可使用。浏览器并非一等支持目标（因为 SDK 导入了 Node 的 fs 和 path 模块），但如果你的构建工具链能够完成打包，仅处理 URL 输入和内存结果在技术上可行。

安装

npm install mineru-open-sdk

鉴权配置

SDK 支持两种鉴权方式：

方式一：环境变量

export MINERU_TOKEN="your-api-token"

之后初始化客户端时无需传入 token：

import { MinerU } from "mineru-open-sdk";
const client = new MinerU(); // 自动读取 MINERU_TOKEN

方式二：代码中显式传入

import { MinerU } from "mineru-open-sdk";
const client = new MinerU("your-api-token");

如果没有传入 token 且找不到 MINERU_TOKEN 环境变量，客户端自动进入 flash-only 模式——flashExtract() 可用，但需要 token 的精准解析方法会抛出 NoAuthClientError。

---

快速上手：两种解析模式

MinerU SDK 提供两种解析模式，分别对应不同的使用场景。

模式一：Flash Extract（轻量解析，免登录）

适合快速预览场景，无需 API token，直接调用。输出为纯 Markdown（图片、表格、公式以占位符形式呈现）。

import { MinerU } from "mineru-open-sdk";

const client = new MinerU();
const result = await client.flashExtract(
  "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
);

console.log(result.markdown);

Flash Extract 的限制：

• 文件大小上限：10 MB
• 页数上限：20 页
• 支持格式：PDF、图片、Docx、PPTx、Excel
• 输出内容：Markdown（公式/表格/图片仅显示占位符）

模式二：Precision Extract（精准解析，需登录）

适合生产环境，支持大文件、完整资源（图片/表格/公式全部保留）以及多格式输出（Markdown、DOCX、LaTeX、HTML、JSON）。

import { MinerU } from "mineru-open-sdk";

const client = new MinerU("your-api-token");
const result = await client.extract(
  "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
);

console.log(result.markdown);     // Markdown 内容
console.log(result.images);        // 提取的图片列表
console.log(result.contentList);  // 结构化内容列表

Precision Extract 的能力：

• 文件大小上限：200 MB
• 页数上限：600 页
• 支持格式：PDF、图片、Doc/x、Ppt/x、HTML
• 输出格式：MD、DOCX、LaTeX、HTML、JSON

两种模式的核心对比：

特性	Flash Extract	Precision Extract
身份认证	免登录	需 API Token
速度	极速	标准
文件大小上限	10 MB	200 MB
页数上限	20 页	600 页
资源保留	占位符	完整资源（图片/表格/公式）

---

完整参数配置

extract() 方法支持丰富的解析参数：

const result = await client.extract("./paper.pdf", {
  model: "vlm",       // 解析模型："vlm" | "pipeline" | "html"
  ocr: true,          // 启用 OCR 识别
  formula: true,      // 启用公式识别（默认开启）
  table: true,        // 启用表格识别（默认开启）
  language: "en",     // 文档语言，默认中文 "ch"
  pages: "1-20",      // 只解析指定页码范围
  extraFormats: ["docx", "latex"],  // 额外输出格式
  timeout: 600,       // 超时时间（秒），默认 300
});

model 参数说明：

• "vlm"：基于视觉语言模型的解析（默认，推荐）
• "pipeline"：Pipeline 流水线解析
• "html"：网页解析（crawl() 默认使用）

常用结果字段：

result.taskId      // 任务 ID
result.state       // 状态："pending" | "running" | "done" | "failed"
result.progress    // 进度信息
result.markdown    // Markdown 文本
result.images      // 图片数组
result.contentList // 结构化内容列表
result.docx        // DOCX 格式（需 extraFormats）
result.html        // HTML 格式（需 extraFormats）
result.latex       // LaTeX 格式（需 extraFormats）
result.filename    // 原始文件名
result.error       // 错误信息

---

批量处理

批量提取（AsyncGenerator 方式）

for await (const result of client.extractBatch(["a.pdf", "b.pdf"])) {
  console.log(`${result.filename}: ${result.state}`);
}

批量提交 + 轮询

适合大文件或需要自定义处理逻辑的场景：

// 提交批量任务
const batchId = await client.submitBatch(["a.pdf", "b.pdf"], {
  fileParams: {
    "a.pdf": { pages: "1-5" },    // a.pdf 只解析前 5 页
    "b.pdf": { pages: "10-20" },  // b.pdf 只解析 10-20 页
  },
});

// 轮询直到完成
while (true) {
  const results = await client.getBatch(batchId);
  const done = results.find(r => r.state === "done" || r.state === "failed");
  if (done) {
    console.log(done.markdown);
    break;
  }
}

submit() 和 submitBatch() 都返回 batch ID，这是 SDK 的统一设计——所有提交内部都通过 batch endpoint 处理。getTask(taskId) 仅在你从其他渠道获得了真实 task ID 时才使用，不能假定它来自 submit() 的返回值。

---

网页抓取

将任意网页转换为 Markdown：

const result = await client.crawl("https://www.baidu.com");
console.log(result.markdown);

crawl() 等价于 extract(url, { model: "html" })，即使用 MinerU-HTML 模型进行网页结构化提取。

批量网页抓取：

for await (const result of client.crawlBatch([
  "https://example.com/page1",
  "https://example.com/page2",
])) {
  console.log(result.markdown);
}

---

结果保存

SDK 内置多个保存辅助方法，直接将解析结果写出为文件：

import {
  MinerU,
  saveMarkdown,
  saveDocx,
  saveHtml,
  saveLatex,
  saveAll,
} from "mineru-open-sdk";

const client = new MinerU("your-api-token");
const result = await client.extract("./document.pdf");

// 保存为 Markdown（图片默认嵌入）
await saveMarkdown(result, "./output/document.md");

// 保存为 DOCX
await saveDocx(result, "./output/document.docx");

// 保存为 HTML
await saveHtml(result, "./output/document.html");

// 保存为 LaTeX
await saveLatex(result, "./output/document.tex");

// 一键保存所有格式
await saveAll(result, "./output/");

注意：Flash Extract 结果只包含 Markdown。saveDocx()、saveHtml()、saveLatex()、saveAll() 都需要 Precision Extract 的完整结果。

---

AI Agent 集成

SDK 为 AI Agent 提供了完整的状态跟踪能力，通过 result.state 和 result.progress 可轻松接入 Agent 循环：

const batchId = await client.submit("https://example.com/large-report.pdf");

// 在 Agent 循环中查询状态
const [result] = await client.getBatch(batchId);
if (result?.state === "done") {
  // 将解析结果注入 Agent 上下文
  const context = result.markdown;
  // ... 后续 RAG 处理
} else if (result?.state === "failed") {
  console.error(`解析失败: ${result.error}`);
}

---

代码示例：从安装到保存的完整流程

import { MinerU, saveAll } from "mineru-open-sdk";

// 1. 初始化客户端（建议使用环境变量存储 token）
const client = new MinerU(process.env.MINERU_TOKEN);

// 2. 选择解析模式
// 快速预览用 flashExtract，生产环境用 extract
const useFlash = !process.env.MINERU_TOKEN;

if (useFlash) {
  // 免登录快速解析
  const flash = await client.flashExtract(
    "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
    { language: "en" }
  );
  console.log(flash.markdown);
} else {
  // 精准解析（支持更多格式和完整资源）
  const result = await client.extract("./document.pdf", {
    model: "vlm",
    ocr: true,
    formula: true,
    table: true,
    language: "en",
    extraFormats: ["docx"],
  });

  // 3. 查看结果
  console.log(`状态: ${result.state}`);
  console.log(`Markdown 长度: ${result.markdown.length}`);
  console.log(`图片数量: ${result.images?.length ?? 0}`);

  // 4. 保存所有格式到 output 目录
  await saveAll(result, "./output/");
  console.log("已保存到 ./output/");
}

---

相关链接

• 官方网站：mineru.net
• SDK 源码：github.com/opendatalab…
• API 文档：mineru.net/apiManage/d…
• npm 包：www.npmjs.com/package/min…
• GitHub Stars：56.9K+

---

一句话总结：只需一行代码，mineru-open-sdk 即可将任意文档转换为结构化的 Markdown，配合 Precision Extract 的多格式输出和 AI Agent 状态跟踪能力，是构建文档处理流水线、RAG 系统和 AI Agent 工作流的利器。