unstructured を採用する前に見るべき分割設計と依存の重さ

unstructured が埋めるのは前処理の一段目である

LLMに文書を読ませるとき、最初に詰まるのはモデルではなく入力の整形である。PDFから抜いたテキストは段落と表とヘッダが混ざり、DOCXはスタイル情報を持ち、HTMLはナビゲーションが本文に紛れる。unstructured はこの一段目を担う。README は「ingesting and pre-processing images and text documents」という表現で対象を広く取り、用途を「streamlining and optimizing the data processing workflow for LLMs」と説明している。つまり検索やRAGの品質を決めるチャンク化の前段、文書を要素の並びに分解する工程が主戦場である。向いているのは、社内に形式の異なる文書が溜まっていて、それを同じスキーマで下流に流したい開発者だ。逆に、単一形式のテキストを数件処理するだけなら、このライブラリを持ち出す理由は薄い。

partition 系関数という分割の単位

中心にあるのは partition と呼ばれる関数群で、README は対応形式の一覧を docs.unstructured.io の partitioning ページに委ねている。設計の要点は、文書全体を1本の文字列にするのではなく、タイトル、本文、リスト、表といった要素の列として返すことにある。この粒度が後段のチャンク化と埋め込みの品質を左右する。ここで読者に判断してほしいのは対応形式の広さではなく、返ってくる要素の種類が自分の下流処理に合うかどうかだ。表を1要素として扱いたいのか、セルに分解したいのかで、必要な前処理は変わる。README が示す範囲では要素スキーマの詳細までは分からないため、採用前に自分の代表的な文書3種類ほどで出力を目視するのが現実的な確認方法になる。

インストールと最初の partition 呼び出し

配布は PyPI の unstructured パッケージで、README のバッジは pypi.org/pypi/unstructured を指している。基本の導入は pip install unstructured。ただし PDF や画像の処理は外部ツールに依存する部分があり、README の本文には extras の指定までは書かれていない。ここは推測で埋めず、docs.unstructured.io の該当ページで形式ごとの要件を確認してほしい。呼び出しは partition 系の関数にファイルパスを渡す形が基本で、戻り値は要素のリストになる。MCP 経由で使う場合は手順が変わり、README は CLI の mcp add コマンド、またはクライアントの MCP 設定ファイルに Transform サーバーを追加し、初回に認証する流れを示している。対応クライアントとして Claude Code、Cursor、Codex CLI が名指しされている。

MCP の案内とオープンソース部分は同じものではない

README の目立つ位置に Transform MCP の節があり、60以上のファイル形式をエージェントのセッション内で処理できると書かれている。しかし同じ README の冒頭は、本番向けの partitioning、enrichment、chunking、embedding を提供する Platform 製品を別途案内している。つまり MCP の説明は、Apache-2.0 のリポジトリに含まれる機能なのか、有料側への導線なのかが文面だけでは判別できない。認証ステップが入ることからも、少なくとも無認証で完結するローカルライブラリとは性質が違うと見るべきだ。OSS版を評価するつもりで README を読むと、この節で期待値がずれる。評価の出発点は partition 系関数に置き、MCP は別製品として切り分けるのが安全である。

スキャン文書と表で露呈する限界

このライブラリは万能の抽出器ではない。PDF がテキスト層を持たず画像としてスキャンされている場合、抽出品質はOCRの精度にそのまま依存する。トピックに ocr や document-image-analysis が並んでいることは、画像系の処理が守備範囲に含まれることを示すが、精度の保証を意味しない。表についても、複雑な結合セルや段組みのある学術PDFでは、要素の並びが崩れる可能性を前提に組むべきだ。もう一つの制約は依存の重さで、PDF、画像、OCR系のライブラリを抱えるため、コンテナイメージが大きくなりやすい。サーバーレス環境でコールドスタートを気にする構成では、処理を別サービスに切る判断も要る。手書き中心の文書や、契約書の条項番号を厳密に保持したい用途は、このライブラリ単体より専用の抽出製品のほうが向いている。

LlamaIndex や自前パーサーとの違い

比較対象として分かりやすいのは LlamaIndex の SimpleDirectoryReader のような取り込み層だ。あちらはインデックス構築までを一つの枠組みで扱うことを狙い、パース結果はその枠組みの都合に合わせて整えられる。unstructured は逆で、パース結果を要素のリストとして返し、その後の保存先や検索方式を決めない。ベクトルDBでも全文検索でも、同じ出力を流し込める。この差は、既に検索基盤を持っていて入力だけ差し替えたいチームには有利に働く。一方、取り込みから検索までを一気に組みたい場合は、unstructured を挟むと配線が増える。もう一つの対抗策は自前のパーサーだが、形式ごとの分岐を保守するコストを考えれば、対応形式の広さ自体には意味がある。

更新頻度とライセンスの扱い

リリースは 0.27.x 系が短い間隔で続いており、0.27.0 と 0.27.1 は同じ日に、0.27.5 はその一週間後に出ている。活発である一方、マイナーバージョン内でも挙動が変わりうる前提でバージョンを固定したい。要素のスキーマや依存パッケージの更新は、下流のチャンク化ロジックに直接影響するため、lock ファイルで固定し、更新時は代表文書の出力差分を取る運用が現実的だ。ライセンスは Apache-2.0 で、リポジトリの LICENSE.md が参照されている。商用利用や改変の余地は広いが、同梱する外部ツールやモデルのライセンスは別に確認が必要になる。ここは法的助言ではないので、配布形態が決まっている場合は法務に確認してほしい。

どのチームが採用し、どのチームが避けるべきか

採用が向くのは、形式混在の文書群をローカルまたは自前のクラウド環境で前処理し、要素単位のメタデータを自分のパイプラインで制御したいチームだ。検索基盤が既にあり、入力の正規化だけを外注したい場合に噛み合う。避けるべきなのは、抽出精度をSLAで縛る必要がある案件、スキャン文書が主体の案件、そしてサーバーレスで依存サイズを極小にしたい案件である。最初に確認するのは、partition の対応形式一覧に対象が載っているか、素の pip install でどこまで動くか、MCP の Transform が有料 Platform 側の機能かどうかの3点。この3点が自分の要件と合わなければ、README の印象がどれほど良くても採用は見送るべきだ。

編集部の結論

採用すべきなのは、PDFやDOCXの混在した文書群をローカルで前処理し、要素単位のメタデータを自前のパイプラインで扱いたいチーム。逆に、スキャン画像中心の文書や手書き、複雑な表構造の抽出精度を最優先する用途では、オープンソース版だけでは足りない可能性が高い。導入前に確認すべきは3点。第一に、対象ファイル形式が partitioning の対応表に載っているか。第二に、pip install unstructured の素の状態でどこまで動き、どの形式に extras が必要か。第三に、MCP 経由で案内されている Transform が有料の Platform 側機能なのか、Apache-2.0 のリポジトリに含まれるのか。この切り分けをせずに「無料で60形式以上」と読むと、後で構成をやり直すことになる。

公式情報源

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. Unstructured-IO/unstructured on GitHub