mixedbread-parsing

Mixedbread 解析

Parsing API を使用してドキュメントを解析し、構造化コンテンツを抽出して、OCR を実行します。PDF、Word ドキュメント、PowerPoint プレゼンテーション、画像に対応しています。

ドキュメント：https://www.mixedbread.com/docs/parsing/overview.md エージェント向けドキュメント：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 が含まれます。bbox はページのピクセル座標で表されたバウンディングボックス [x1, y1, x2, y2] です。bbox を使うと、OCR の出力をページ上の位置に対応付けられます（例：根拠箇所のハイライト表示）。

チャンク化：chunking_strategy のデフォルトは page（現在、唯一の戦略）で、1 ページにつき 1 つのチャンクになります。

ワークフロー

ドキュメントから表を抽出する

表要素に絞り込んで、レポートから構造化データを抽出します。

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モードを試してください。
信頼度スコアが低い	スキャン画像、または解像度の低いソース	OCR の精度を高めるには、high_qualityモードを使用してください。
表や図が見つからない	要求された要素タイプに含まれていない	element_typesにtableとfigureを明示的に含めてください。
upload_and_poll()がタイムアウトする	文書が非常に大きい、または処理に時間がかかっている	poll_timeout_msを増やすか、より細かく制御できるようにupload()とpoll()を別々に使用してください。