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

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

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

MinerU 的核心能力包括：

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 的限制：

模式二：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 的能力：

两种模式的核心对比：

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) }

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 的完整结果。

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-open-sdk 即可将任意文档转换为结构化的 Markdown，配合 Precision Extract 的多格式输出和 AI Agent 状态跟踪能力，是构建文档处理流水线、RAG 系统和 AI Agent 工作流的利器。