mixedbread-parsing

Mixedbread 解析

使用 Parsing API 解析文档、提取结构化内容并运行 OCR。支持 PDF、Word 文档、PowerPoint 演示文稿和图像。

文档：https://www.mixedbread.com/docs/parsing/overview.md 面向 Agent 的文档：https://www.mixedbread.com/docs/llms.txt 最新文档搜索：https://www.mixedbread.com/question?q=parsing&section=docs

设置

pip install mixedbread          # Python
npm install @mixedbread/sdk     # TypeScript

export MXBAI_API_KEY=your_api_key

快速开始

Python：

from mixedbread import Mixedbread

mxbai = Mixedbread()

# Upload and parse a document (waits for completion)
job = mxbai.parsing.jobs.upload_and_poll(
    file=open("report.pdf", "rb"),
    return_format="markdown",
)

for chunk in job.result.chunks:
    print(chunk.content)

TypeScript：

import Mixedbread from '@mixedbread/sdk';
import fs from 'fs';

const mxbai = new Mixedbread();

const job = await mxbai.parsing.jobs.uploadAndPoll(
    fs.createReadStream('report.pdf'),
    { return_format: 'markdown' },
);

for (const chunk of job.result.chunks) {
    console.log(chunk.content);
}

决策树

• 使用哪种便捷方法？
  • 磁盘上的文件 → upload_and_poll()（上传文件 + 创建任务 + 轮询）
  • 已通过 Files API 上传的文件 → create_and_poll()（创建任务 + 轮询）
  • 需要异步控制 → 分别调用 upload() 或 create()，然后调用 poll()
• 使用哪种解析模式？（默认为 high_quality）
  • 原生数字 PDF（可选择文本）→ 明确传入 mode="fast"。速度最快、成本最低。提取文本、结构和布局。
  • 扫描文档、图像或复杂布局 → 使用 high_quality 模式（默认）。使用 OCR。提取文本及置信度分数和各元素边界框，可处理旋转或倾斜的页面、多栏布局。
• 使用哪种返回格式？ → return_format：markdown（默认）、html 或 plain
• 只需要特定元素？ → 设置 element_types 以缩短处理时间

支持的文件类型

PDF（.pdf）、Word（.doc、.docx、.dotx、.docm、.dotm、.odt、.rtf）、幻灯片（.ppt、.pptx、.ppsx、.ppam、.pptm、.potm、.ppsm、.odp）、图像（.jpeg、.png、.webp、.avif）。

元素类型：text、title、section-header、header、footer、page-number、list-item、figure、table、form、footnote。（旧值 picture、caption、formula、page-header 和 page-footer 仍可使用，但会分别规范化为 figure/text/header/footer。）

每个提取的元素都包含 type、content、page、confidence（0–1）和 bbox——即页面像素坐标中的边界框 [x1, y1, x2, y2]。使用 bbox 将 OCR 输出映射回其在页面上的位置（例如，用于高亮证据）。

分块：chunking_strategy 默认为 page（目前唯一的策略）——每页一个块。

工作流

从文档中提取表格

筛选表格元素，从报告中提取结构化数据。

Python：

job = mxbai.parsing.jobs.upload_and_poll(
    file=open("financial-report.pdf", "rb"),
    element_types=["table"],
    return_format="html",
    mode="high_quality",
)
for chunk in job.result.chunks:
    for element in chunk.elements:
        if element.type == "table":
            print(f"Page {element.page}, confidence {element.confidence:.2f}, bbox {element.bbox}")
            print(element.content)

TypeScript：

const job = await mxbai.parsing.jobs.uploadAndPoll(
    fs.createReadStream('financial-report.pdf'),
    { element_types: ['table'], return_format: 'html', mode: 'high_quality' },
);
for (const chunk of job.result.chunks) {
    for (const element of chunk.elements) {
        if (element.type === 'table') {
            console.log(`Page ${element.page}, confidence ${element.confidence.toFixed(2)}, bbox ${element.bbox}`);
            console.log(element.content);
        }
    }
}

批量解析多个文件

异步上传多个文件，然后轮询所有任务：

Python：

import os

jobs = []
for filename in os.listdir("./documents"):
    if filename.endswith(".pdf"):
        job = mxbai.parsing.jobs.upload(
            file=open(f"./documents/{filename}", "rb"),
            return_format="markdown",
        )
        jobs.append(job)

# Poll all jobs
for job in jobs:
    completed = mxbai.parsing.jobs.poll(job_id=job.id)
    print(f"{completed.filename}: {len(completed.result.chunks)} chunks")

TypeScript：

import { readdirSync, createReadStream } from 'fs';
import path from 'path';

const files = readdirSync('./documents').filter(f => f.endsWith('.pdf'));
const jobs = await Promise.all(
    files.map(f => mxbai.parsing.jobs.upload(
        createReadStream(path.join('./documents', f)),
        { return_format: 'markdown' },
    )),
);

// Poll all jobs
for (const job of jobs) {
    const completed = await mxbai.parsing.jobs.poll(job.id);
    console.log(`${completed.filename}: ${completed.result.chunks.length} chunks`);
}

规则

关键

• 不要重复解析。 存储上传会自动解析文档。使用 parsing_strategy: "high_quality" 上传的文件会自动提取 OCR 文本（图像）、摘要（图像）和转录文本（音频和视频）。这些内容可作为字段在搜索结果块中获取。对同一文件调用 Parsing API 没有任何好处。仅在存储之外独立提取文档时使用 Parsing API。
• 使用 upload_and_poll() / create_and_poll()，不要手动编写轮询循环。 这些方法会自动处理退避。使用 retrieve() 的手动 while 循环不可靠，还会浪费 API 调用。

高

• 只需要特定元素时，请指定 element_types。 请求所有类型会增加处理时间和响应大小。如果只需要表格，请仅将 element_types 设为 table。
• 对原生数字 PDF 使用 fast 模式。 文本已经可选时，high_quality 模式会增加 OCR 开销，却没有任何收益。
• 检查 OCR 输出的 confidence 分数。 置信度较低的元素（< 0.5）可能包含错误。请对其筛选或标记。

MEDIUM

• 重试失败的任务前，先检查 job.error。 常见原因：不支持的文件类型、文件损坏或文件过大。盲目重试会浪费配额。
• 在嵌入工作流中使用 content_to_embed。 每个分块都提供 content（完整文本）和 content_to_embed（针对嵌入优化的文本）。将内容输入 Mixedbread 之外的向量存储时，请使用后者。
• 解析前验证文件格式。 仅支持 PDF、Word、PowerPoint 和图像。请先转换其他格式。

故障排查

症状	原因	解决方法
任务卡在 pending 状态	队列繁忙	使用 poll() 并设置更长的 poll_timeout_ms。使用 retrieve() 检查任务状态。
任务状态为 failed	文件类型不受支持、文件损坏或文件过大	查看 job.error 了解详情。确认文件格式受支持。
结果中没有分块	文件不含可提取的内容（页面空白）	确认文件包含内容。对于扫描文档，尝试使用 high_quality 模式。
置信度较低	来源为扫描件或分辨率较低	使用 high_quality 模式以提高 OCR 准确度。
缺少表格或图表	未请求相应元素类型	设置 element_types，明确包含 table 和 figure。
upload_and_poll() 超时	文档过大或处理缓慢	增大 poll_timeout_ms，或分别使用 upload() 和 poll()，以获得更多控制。