0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

表や数式が崩れないOCR「Surya」v0.24.0 を Mac で動かしてみた

0
Posted at

表や数式が崩れないOCR「Surya」v0.24.0 を Mac で動かしてみた

はじめに

社内文書を RAG(Retrieval-Augmented Generation:検索した資料をもとに AI に答えさせる仕組み)に入れようとして、こんな経験はないでしょうか。

  • 請求書の明細表を取り込んだら、数字が1行ずつばらばらになり「どの拠点の売上か」が分からなくなった
  • 研究資料の数式が 𝑝𝑖= 𝑒𝑧𝑖 ∑𝑗= 1 のような記号の羅列になった
  • 3段組の社内報で、左右の段の文章が交互に混ざった
  • 古いスキャン資料は、そもそも文字が1文字も取れなかった

検索の精度は、検索より前の「文書を正しく読み取れたか」で大きく変わります。表の行と列の対応が崩れた状態でいくら検索を工夫しても、正しい数字は返せません。

2026年11月13日、Datalab が文書解析のオープンソース「Surya(スーリヤ)」の v0.24.0 を公開しました。689M パラメータの文書専用モデル「Surya 2.5」が、文字だけでなく表の結合セル・数式・読み順まで含めた構造を1回の処理で書き出します。今回の版では PyTorch などの重い依存を外し、Mac でも pip install と Homebrew だけで動くようになりました。

この記事では、次の3つを順に説明します。

  1. 従来の PDF 抽出や OCR は、どんな場面で何が崩れていたのか
  2. Surya v0.24.0 は何を変え、その結果どの読み取りが強くなったのか(手元の Mac で34ページを実測)
  3. 実際に使うときの手順(インストール、CLI、閲覧画面、Python、RAG 用のチャンク化)

想定読者は、RAG や文書検索を作っている(これから作る)エンジニアと、社内文書の AI 活用を検討している方です。Python のコマンドを打ったことがあれば読み進められます。

この記事の確認範囲

  • 確認日:2026年11月16日。surya-ocr 0.24.0(モデル Surya 2.5、旧モデル Surya 2 は比較用)
  • 実行環境:MacBook Pro(Apple M5 Max・メモリ 128GB)、macOS、Python 3.12、llama.cpp 0.4.1(Homebrew)
  • 比較した従来手法:PyMuPDF 2.1(get_text())、pymupdf4llm 2.1(PDF→Markdown)、macOS 標準の Vision(行ごとの OCR)
  • 数値のうち「公式」と書いたものは Datalab の GitHub リリースノートと README の値。それ以外は手元の測定です

最初に、この記事の結論を1枚にまとめます。

従来の読み取りとSuryaの違い。表・数式・段組・スキャンのそれぞれで、従来は構造が崩れ、Suryaは構造つきで出力する

図1:同じ文書を読ませたときの違い。文字そのものより「構造が残るか」で差がつきます

そもそも、従来の読み取りは何が苦手だったのか

従来の2つのやり方

PDF からテキストを取り出す方法は、大きく2つありました。

1つ目は PDF の文字の層を抜き出す方法です。Word や Chrome から作った PDF には、見た目の裏に「文字の層」(テキストレイヤー)が入っています。PyMuPDF などのライブラリはこれを読むので、速くて文字も正確です。手元でも1ページ0.06秒、文字の正しさはほぼ100%でした。

2つ目は 画像から文字を読む OCR(Optical Character Recognition:光学文字認識)です。スキャンした紙や写真のように文字の層がない資料に使います。Tesseract や macOS 標準の Vision が代表例で、画像の中から「行」を見つけて1行ずつ文字に直します。

どちらも「文字」を取り出すのは得意です。苦手なのは、文字と文字の関係、つまり構造です。

5つの苦手場面

手元で検証用のページを作り、従来の方法で読ませたときに崩れた場面を表にまとめました。

従来の読み取りが苦手だった5つの場面を、PDF抽出・行OCR・Suryaの3列で比較した表

図2:手元の検証で実際に起きたこと。○は読めた、△は一部崩れた、×は読めなかったもの

それぞれ、何が起きているのかを補足します。

場面 何が起きるか なぜ起きるか
① スキャンした紙 PDF 抽出では何も取れない 文字の層がなく、ページ全体が1枚の画像だから
② 結合セルのある表 「上期」が「上|期」に割れる、値の列がずれる Markdown の表は結合セルを表せない。行 OCR は表という単位を持たない
③ 段組・縦書き 左右の段の行が交互に混ざる。縦書きが読めない 「上から下・左から右」に並べるだけでは、人の読む順にならない
④ 数式 分数の上下や添字の関係が消えて記号の列になる 数式は2次元の配置そのものが意味を持つから
⑤ 見えない文字の置き換わり 「月」が部首の「⽉」(U+2F49)になる PDF 内のフォントの文字対応表によっては、見た目が同じ別の文字で抜き出される

⑤は見落としやすい問題です。手元では pymupdf4llm の出力に、この種の文字(康熙部首など)が17ページで440文字含まれていました(多い順に「⽉」「⽇」「⽤」「⾏」)。同じ PDF を PyMuPDF の get_text() で読むと0文字です。ほかに、全角スペースが文字化けの印「�」になった箇所も22ありました。画面では区別できませんが、キーワード検索で「11月」と打っても「11⽉」には当たりません。PDF 抽出を使う場合は、Unicode の NFKC 正規化(見た目が同じ文字を標準の文字にそろえる処理)を必ず入れてください。

import unicodedata

text = "2026年11⽉10⽇発⾏"            # pymupdf4llm の出力に実際にあった形
print(unicodedata.normalize("NFKC", text))  # → 2026年11月10日発行

まとめると、従来の方法は「文字は取れるが、表・数式・読み順という構造が残らない」「スキャンは文字すら取れないか、取れても構造がない」という弱点を抱えていました。

Surya v0.24.0 で何が変わったのか

Surya とは

Surya は、米 Datalab 社がオープンソースで公開している文書解析ツールです。名前はインド神話の太陽神スーリヤに由来します。OCR、レイアウト解析(見出し・本文・表・図などの領域を見つけること)、読み順の推定、表の認識を、90以上の言語で行います。

コードは Apache 2.0 ライセンスです。一方でモデルの重みは独自の条件付きライセンスなので、業務で使う前に後述の「ライセンスの注意」を確認してください。

v0.24.0 の変更点は、大きく3つに分けられます。

変化1:1つのモデルが「構造つき」で書き出す

中心にあるのは、文書専用の視覚言語モデル(VLM:画像を見て文章を書くモデル)「Surya 2.5」です。パラメータ数は689M(6.89億)で、Qwen3.5 系の構成をもとに学習されています。Surya 2.5 は v0.23.0(2026年10月29日)で既定のモデルになり、v0.24.0 で移行が完了しました。

このモデルは、ページ画像を受け取ると、ブロックごとに「種類・座標・中身」を読む順に書き出します。手元の表ページで、モデルの生の出力を取り出してみたのが次の図です。

Surya 2.5の処理の流れ。ページ画像から、ラベルと座標と中身を並べた短縮形式の出力を経て、results.jsonのブロックになる

図3:全ページ OCR(既定のモード)の流れ。中央上のコードはモデルの実際の出力の抜粋です

ポイントは3つあります。

  • 1回の呼び出しで全部出る:レイアウト検出・読み順・本文・表・数式を、別々のモデルでつなぐ必要がありません
  • 表は HTML、数式は LaTeX:表は <table>、結合セルは rowspan / colspan、数式は <math> タグの中に LaTeX(数式を書くための記法)で出ます
  • 短縮形式で書く量を減らした:<|Table|><|81|><|152|><|907|><|347|> のような短い印で種類と座標を書き、表の閉じタグも省きます。公式によると、これで1ページあたりの出力トークンが旧モデルより62%減りました

3つ目が速さの源です。LLM は出力を1トークンずつ書くので、書く量が減れば、そのぶん速く終わります。

変化2:重い依存を外し、モデルを動かす部分を外に出した

v0.24.0 でいちばん目に見える変化は、インストールの軽さです。

v0.23.0までの全部入りの構成と、v0.24.0の「頼む側」と推論サーバーに分かれた構成の比較

図4:v0.24.0 の surya-ocr は、画像を送って結果をほどく「頼む側」になりました

以前の Surya は、PyTorch・torchvision・Transformers・OpenCV を1つの Python 環境に入れて、その中でモデルを動かしていました。v0.24.0 ではこれらを実行時の依存から外し、モデルの実行を外部の推論サーバーに任せます。推論サーバーは環境に合わせて3種類から選びます。

推論サーバー 向いている環境 起動のされ方
vLLM NVIDIA GPU Docker / Podman のコンテナとして自動起動
llama.cpp(llama-server) CPU、Apple Silicon(Metal) Mac の既定。GGUF 形式のモデル(約1.3GB)を自動取得して起動
MLX-VLM Apple Silicon 試験的。自分で MLX 形式に変換した重みを指定

手元で、旧版と新版を空の仮想環境に入れ比べました(ダウンロードのキャッシュなし)。

surya-ocr 0.23.0 surya-ocr 0.24.0
入ったパッケージ数 56 33
仮想環境の大きさ 895MB 82MB
インストールにかかった時間 約41秒 約6秒
PyTorch / Transformers / OpenCV 入る 入らない

ただし、0.24.0 の82MBには推論サーバーとモデルが含まれていません。Mac では Homebrew の llama.cpp(約18MB)と、初回に自動で取得されるモデル(約1.3GB)が別に必要です。

なお、紹介記事などで「依存を減らしたことで高速化した」と読める書き方を見かけますが、速さを決めているのは推論サーバーとモデルの出力量です。依存の削減は「入れやすさ」の改善と考えるのが正確です。

変化3:閲覧画面と、エージェント向けの CLI

使い勝手の面では次の2つが加わりました。

  • surya_gui の作り直し:以前は Streamlit を別に入れる必要がありましたが、Python の標準ライブラリだけで動く閲覧画面になりました。PDF や画像を渡すと、レイアウトの枠・読み順・KaTeX で組版した数式・HTML の表・JSON をページごとに確認できます
  • AI エージェント向けの CLI:--stdout で結果の JSON を標準出力に流せるようになり、シェルのパイプや AI エージェントから扱いやすくなりました。surya_ocr --skill で Claude Code などに読ませるスキル(SKILL.md)も出力できます

公式が出している数字

Datalab が公開している評価結果を整理しておきます(いずれも公式の値)。

項目 Surya 2 Surya 2.5
OmniParseBench(総合) 83.3 85.9(1B 未満の公開モデルで最高と発表)
 うち表 74.3 78.3
olmOCR-bench 82.8 83.7
91言語の社内ベンチマーク 74.5% 74.9%
 うち日本語 78.8% 80.5%
H100・192 DPI の処理量 2.72 ページ/秒(MTP あり) 4.52 ページ/秒(1.7倍)
Apple Silicon(M4 Max・llama.cpp・96 DPI) 0.061 ページ/秒 0.198 ページ/秒(3.2倍)

精度の伸びは数ポイントで、目立つのは速さです。そこで手元では「構造がどれだけ残るか」と「速さはどんなページで効くか」の2点を確かめました。

手元の Mac で確かめた:どこがどれだけ強くなったか

検証の設計

日本語の業務文書を中心に、正解つきのページを34枚用意しました。

区分 ページ 内容
日本語の業務文書 12ページ+スキャン版12ページ 請求書、見積書、契約書、2段組の規約、API 仕様書、売上報告、論文風の2段組、申込書、社内報、操作マニュアル、議事録など(以前の OCR 検証で作った正解つきの帳票)
苦手場面のページ 5ページ+スキャン版5ページ ①結合セルの多い表2つ ②数式4本+文中の式 ③3段組+囲み記事 ④縦書きのお知らせ ⑤罫線なしの表と小さな文字

スキャン版は、元の画像を150 DPI 相当に縮め、0.6〜1.5度傾け、ぼかし・ノイズ・紙の色を加えて JPEG で保存したものです。PDF 抽出の2つ(PyMuPDF・pymupdf4llm)は文字の層つき PDF を、Vision と Surya はページ画像を読みます。

評価の指標は次の4つです。

  • 文字の正しさ:正解の各ブロックの文字が出力のどこかに正しく現れているか(全角・半角の違いと空白は除いて比較)
  • 表の再現度(TEDS):表を木構造として比べ、形とセルの文字がどれだけ一致するか。1.00 が完全一致
  • 数式:Surya が出した LaTeX が、正解の LaTeX と(空白などを除いて)一致した数
  • 読み順:段落が崩れずに、正しい順で出てきたか

結合セルの表:Markdown では表せない形が残る

まず、結合セルの多い表です。原本と、3つの方法で読んだ結果を並べました。中身はすべて実際の出力です。

結合セルのある表を、原本・pymupdf4llm・macOS Vision・Suryaで比べた画面。Suryaだけが2段の見出しと縦の結合を再現している

図5:pymupdf4llm は「上期」が「上|期」に割れ、Vision は1セル1行になりました。Surya は rowspan / colspan つきで原本どおりです

pymupdf4llm は罫線を手がかりに表を見つけるので、単純な表なら上手に読めます(14表の平均 TEDS は0.91)。崩れるのは結合セルです。Markdown の表は「このセルは2列ぶん」を表す書き方がないため、見出しの行がずれ、TEDS は0.75と0.52まで下がりました。

Surya の出力は <th rowspan="2">事業部</th> のような HTML です。「物流」が3行ぶん、「全社合計」が2列ぶんという関係がそのまま残るので、「福岡の下期の売上は?」に対して「170」と答える材料になります。

数式:記号の列ではなく LaTeX で出る

次は数式です。PyMuPDF の get_text() は数式も文字として抜き出しますが、配置の情報が消えます。

数式ページの原本、PyMuPDFの出力、Suryaが出したLaTeXをKaTeXで表示したものの比較

図6:PyMuPDF は分数や添字の関係が消え、Surya は4式とも LaTeX で構造を保ちました

たとえばソフトマックスの式(1)は、PyMuPDF だと pi= ezi ∑j= 1 K ezj と部品ごとに改行され、どれが分子でどれが分母かが分からなくなります。Surya は p_i = \frac{e^{z_i}}{\sum_{j=1}^K e^{z_j}} と書き出しました。正解の LaTeX と照らし合わせると、ブロックの式4本と文中の \alpha = 0.7 の計5つがすべて一致しました(スキャン版でも5/5)。

LaTeX で残っていれば、検索結果を画面に出すときに KaTeX で組版し直せますし、LLM も式の意味を正しく読み取れます。

段組と縦書き:人が読む順に並ぶ

3段組の社内報と、縦書きのお知らせです。

3段組の社内報と縦書きのお知らせを、従来の方法とSuryaで読んだ結果の比較

図7:pymupdf4llm は左右の段の行が交互に混ざり、Vision は縦書きをほぼ読めませんでした

3段組では、pymupdf4llm が左の段と中央の段の行を交互につないでしまい、7段落中4段落が崩れました。縦書きのページでは、pymupdf4llm は1文字ずつのセルが並ぶ表として出力し、Vision は本文を読めず「敬」「具」の2文字だけが残りました。

Surya は、3段組を「左の段を下まで → 中央の段 → 右の段 → 囲み記事」の順に、縦書きを「右の行から左へ」の順に並べました。スキャン版でも順番は崩れていません。

なお、PyMuPDF の get_text() は縦書きの文字自体は取れますが、1文字ごとに改行されます。改行を取り除けば読めるので、文字の層がある縦書き PDF なら後処理で対応できます。

スキャン:文字の層がなくても同じ形で出る

スキャン版17ページでは、PDF 抽出の2つは当然0%です。Vision は文字を95.6%読めましたが、表・数式・縦書きの構造はありません。Surya は文字の正しさ99.8%、表の TEDS 1.00 で、きれいな画像とほとんど変わりませんでした。傾き・ぼかし・ノイズを加えた程度のスキャンなら、品質はあまり落ちないと言えます。

結果のまとめ

ここまでの結果を1つの表にしました。

手元の実測結果。文字の正しさ、表のTEDS、数式、読み順を4つの方法で比べた表

図8:文字の正しさは互角。差がつくのは表・数式・読み順とスキャンです

文字の層がある PDF では、PyMuPDF の文字の正しさ(100.0%)が Surya(99.5%)を上回っています。文字を取るだけなら、従来の抽出のほうが正確で、しかも数十倍速いという点は押さえておきたいところです。Surya を使う意味は、表・数式・読み順の構造と、スキャンへの対応にあります。

Surya も間違える

完璧ではありません。手元で見つかった誤りを挙げます。

誤りの種類 実際の例
形の似た字 「罫線なし」→「野線なし」、「ブース」→「プース」、「レーザー」→「レーザ一」(長音が漢数字の一)
記号 著者名の「†1」→「+1」、「[出荷]」→「〔出荷〕」
大文字・小文字 PDF から読んだ回だけ、式(1)の z_i が Z_i になった(画像から読んだ回は正しい)
表の結合の幅 請求書の「小計」行を colspan="6" で出力(正しくは5列ぶん)。この表の TEDS は0.95
読み順 請求書で左右に並んだ宛先と差出人を、行ごとに交互に読んだ(文字はすべて正しい)

金額・型番・日付のように1文字の誤りが問題になる項目は、桁数や合計のチェック、原本との照合を後段に入れてください。

速さ:「3.2倍」は文字の多いページで効く

最後に速さです。旧モデル Surya 2 と新モデル Surya 2.5 を、同じ surya-ocr 0.24.0・同じ llama-server の設定で動かし、1ページずつ処理しました(Surya 2 は環境変数でモデルを切り替えられます)。

日本語の業務文書34ページと英語の文字が多いページ16ページで、Surya 2と2.5の処理時間と出力トークンを比べたグラフ

図9:日本語の業務文書ではほぼ同じ速さ、英語の文字が多いページでは2.9倍速くなりました

日本語の業務文書34ページでは、1ページあたり Surya 2 が4.7秒、Surya 2.5 が4.2〜5.5秒(3回測定)で、差はありませんでした。出力トークンが810から687へ15%減っただけで、もともと書く量が少ないからです。むしろ手元の llama.cpp 0.4.1 では、Surya 2.5 のほうが画像の読み込みと1トークンの生成がやや遅く(生成は毎秒225→190トークン)、その分で相殺されました。

一方、公式の測定に近い条件(olmOCR-bench の英語論文・小さな文字・段組・表を96 DPI で読む)の16ページでは、Surya 2 が平均32.2秒、Surya 2.5 が11.0秒と2.9倍速くなりました。出力トークンは5,766から1,789へ69%減っています。Surya 2 は文字の多いページで同じ内容を書き続け、出力の上限で打ち切られる回もありました。8ページを同時に流したときの処理量は 0.086 → 0.218 ページ/秒で、公式の M4 Max の値(0.061 → 0.198)に近い結果です。

つまり「3.2倍速い」は、1ページに書く量が多い資料ほど効く改善です。論文や細かい字の報告書を大量に処理するなら恩恵は大きく、1ページの文字が少ない帳票中心なら速さの差はあまり期待できません。

参考までに、従来手法の1ページあたりの時間は PyMuPDF 0.06秒、pymupdf4llm 0.24秒、Vision 約0.5秒でした。Mac の llama.cpp で動かす Surya は、1ページ数秒〜十数秒かかる前提で設計してください。

実際に使う:インストールから RAG 用の出力まで

ここからは手順です。Apple Silicon の Mac を例にしますが、Linux や Windows でも llama.cpp を入れれば同じ流れで動きます。

Macで動かすまでの4ステップ。llama.cppの導入、surya-ocrの導入、1ファイル読ませる、画面で確かめる

図10:初回だけモデル(約1.3GB)の取得に数分かかります

1. 準備:llama.cpp と surya-ocr を入れる

推論サーバーの llama.cpp を Homebrew で入れます。

# 推論サーバー(llama-server)を入れる
brew install llama.cpp
llama-server --version   # 手元では version: 0.4.1

次に surya-ocr を仮想環境に入れます。Python は3.10以上が必要です。

# 作業フォルダと仮想環境を作る
mkdir surya-test && cd surya-test
python3 -m venv .venv
source .venv/bin/activate

# surya-ocr 0.24.0 を入れる(PyTorch は入らない)
pip install "surya-ocr==0.24.0"

2. CLI で1ファイル読ませる

PDF か画像を1つ渡すだけです。初回はモデルの取得と llama-server の起動が自動で行われます(手元では取得に約4分)。

# 結果を results/<ファイル名>/results.json に保存する
surya_ocr 資料.pdf --output_dir ./results

# 結果の JSON を画面(標準出力)に流す
surya_ocr 資料.pdf --stdout

--stdout の JSON は、jq で必要な部分だけ取り出すと見やすくなります。数式のページで、ブロックの順番・種類・中身を1行ずつ出したのが次の画面です。

surya_ocr c2_math.pdf --stdout | jq -r '.c2_math[0].blocks[] | "\(.reading_order)  \(.label)  \(.html)"'

surya_ocrの実行結果。読み順、ブロックの種類、HTMLの中身が1行ずつ並び、数式はmathタグのLaTeXで出ている

図11:実際の実行結果。見出し・本文・数式(Equation)が読む順に並んでいます

出力の各ブロックには、次の項目が入っています。

項目 内容
label ブロックの種類。SectionHeader(見出し)、Text、Table、Equation、ListGroup、Caption、PageHeader、PageFooter、Picture など
reading_order 読む順番(0から)
html 中身。表は <table>、数式は <math>。図などで読み取らなかったブロックは空
bbox / polygon ページ画像上の位置(ピクセル)
confidence トークンごとの確からしさの平均(0〜1)
skipped / error 読み取りを省いた・失敗したか

表だけが欲しいときは surya_table を使います。手元の表ページでは、2つの表を自動で見つけて HTML にしました。

surya_table 資料.pdf --stdout

3. surya_gui で結果を目で確かめる

閲覧画面を起動して、ブラウザで開きます。

surya_gui --port 8000
# → ブラウザで http://127.0.0.1:8000 を開き、PDF か画像をドラッグ&ドロップ

左側の「Full OCR / Block OCR / Layout / Tables」でモードを切り替えられます。右側の「Preview / Blocks / HTML / JSON」のタブで結果を確認し、「Download .json」で保存できます。

surya_guiで表のページを読ませた画面。ページの上にブロックの枠と読み順の番号と線が重なり、右側にブロックの一覧が出ている

図12:表のページ。枠の色がブロックの種類、赤い番号と線が読み順です(Blocks タブ)

surya_guiで縦書きのスキャン画像を読ませた画面。右から左へ1〜5の順に読み、右側のPreviewに本文が横書きで出ている

図13:縦書きのスキャン。読み順の線が右の行から左へ進んでいます

RAG に入れる前に「この種類の文書でどこが崩れるか」を目で確かめるのに便利です。読み順の線が飛んでいるページや、表の枠が出ないページがあれば、そこが要注意の箇所です。

4. Python から使う

Python では、推論サーバーを管理する SuryaInferenceManager と、OCR を行う RecognitionPredictor を使います。

from PIL import Image
from surya import RecognitionPredictor, SuryaInferenceManager

manager = SuryaInferenceManager()          # 推論サーバーを起動(または既存のものにつなぐ)
rec = RecognitionPredictor(manager)

image = Image.open("sample.png").convert("RGB")
page = rec([image])[0]                     # 画像のリストを渡し、ページごとの結果を受け取る

for b in page.blocks:                      # ブロックは読む順に並んでいる
    print(b.reading_order, b.label, b.html[:50])

tables = [b.html for b in page.blocks if b.label == "Table"]   # 表だけ取り出す

手元の表ページで動かした出力の一部です。

0 SectionHeader <h1>2026年度 事業部別売上と拠点比較</h1>
1 Text <p>単位:百万円。前年比は前年同期の売上に対する比率。</p>
2 Caption <p><b>表1 事業部・拠点別の売上</b></p>
3 Table <table><tr><th rowspan="2">事業部</th><th rowspan="2"

ひとつ注意があります。リリースノートの例にある TableRecPredictor(manager)([image]) にページ全体の画像を渡したところ、手元では表を切り出さず、ページ全体を1つの結果として返しました。TableRecPredictor は表の部分だけを切り抜いた画像に使い、ページから表を探したいときは上のように label == "Table" のブロックを使うか、CLI の surya_table を使うのが確実です。

5. RAG 用のチャンクにする

Surya の出力をそのまま文章として連結すると、せっかくの構造が無駄になります。ブロックの種類に応じてチャンク(検索の単位となる文章のかたまり)の切り方を変えましょう。

Suryaのブロックを、見出しごとのチャンク、表のチャンク、捨てるブロックに振り分ける流れ

図14:見出しごとにまとめ、表は切らずに残し、ページの余白は捨てます

手元で動作を確認した最小のサンプルです。

"""PDF / 画像を Surya で読み、RAG 用のチャンク(JSONL)にする最小サンプル。
使い方: python to_chunks.py 入力.pdf > chunks.jsonl
"""
import json
import re
import sys

from surya import RecognitionPredictor, SuryaInferenceManager
from surya.input.load import load_from_file
from surya.settings import settings

SKIP = {"PageHeader", "PageFooter", "Picture", "Figure"}  # 検索のノイズになるブロック


def to_text(html: str) -> str:
    """表以外のブロックを、数式を残したプレーンテキストにする"""
    s = re.sub(r"<math[^>]*>(.*?)</math>", lambda m: f"${m.group(1).strip()}$", html, flags=re.S)
    s = re.sub(r"<br\s*/?>|</(p|li|h\d)>", "\n", s)
    s = re.sub(r"<[^>]+>", "", s)
    return re.sub(r"\n{2,}", "\n", s).strip()


def main(path: str):
    images, _ = load_from_file(path, dpi=settings.IMAGE_DPI_HIGHRES)  # PDF を 192 DPI で画像にする
    pages = RecognitionPredictor(SuryaInferenceManager())(images)

    chunks, cur = [], None
    for page_no, page in enumerate(pages, start=1):
        blocks = [b for b in sorted(page.blocks, key=lambda b: b.reading_order) if b.label not in SKIP and b.html]
        for i, b in enumerate(blocks):
            meta = {"source": path, "page": page_no, "bbox": [round(v) for v in b.bbox], "label": b.label}
            nxt = blocks[i + 1].label if i + 1 < len(blocks) else None
            if b.label == "SectionHeader":            # 見出しが来たら新しいチャンク
                cur = {"heading": to_text(b.html), "text": "", "metadata": meta}
                chunks.append(cur)
            elif b.label == "Caption" and nxt == "Table":
                continue                               # 表題は次の表のチャンクに付ける
            elif b.label == "Table":                   # 表は切らずに HTML のまま1チャンク
                heading = cur["heading"] if cur else ""
                prev = blocks[i - 1] if i > 0 else None
                caption = to_text(prev.html) if prev is not None and prev.label == "Caption" else ""
                chunks.append({"heading": heading, "caption": caption, "text": b.html,
                               "metadata": meta | {"format": "html"}})
            else:                                      # 本文は今の見出しのチャンクに足す
                if cur is None:
                    cur = {"heading": "", "text": "", "metadata": meta}
                    chunks.append(cur)
                cur["text"] += to_text(b.html) + "\n"
    for c in chunks:
        if c["text"].strip():
            print(json.dumps(c, ensure_ascii=False))


if __name__ == "__main__":
    main(sys.argv[1])

2段組の利用規約のページで実行すると、第1条〜第8条がそれぞれ1チャンクになり、第7条の中の表は別の1チャンクになりました。表のページでは、表1と表2が表題つきで1チャンクずつです。出力の1行は次のような形です(長い部分は省略)。

{"heading": "2026年度 事業部別売上と拠点比較", "caption": "表1 事業部・拠点別の売上", "text": "<table><tr><th rowspan=\"2\">事業部</th>…</table>", "metadata": {"source": "c1_merged_table.pdf", "page": 1, "bbox": [124, 346, 1450, 782], "label": "Table", "format": "html"}}

設計のポイントを補足します。

  • 表は HTML のまま渡す:LLM は HTML の表を読めます。Markdown に変換すると結合セルの情報が消えるので、変換しないほうが安全です。埋め込み(ベクトル化)用には、タグを除いた文字列を別に作ってもかまいません
  • page と bbox を残す:回答の根拠を「何ページのどこ」まで示せます。surya_gui と同じように、原本の画像に枠を重ねて見せることもできます
  • 見出しが来ない長い本文:このサンプルは見出しの単位でまとめるだけなので、1つの節が長い文書では、文字数で分割する処理を後ろに足してください

6. 大量に処理するときの設定

フォルダごと処理する場合や、速さと精度のバランスを変えたい場合の設定です。

やりたいこと 方法
フォルダをまとめて処理 surya_ocr ./資料 --recursive --output_dir ./results
コマンドのたびのサーバー起動を省く --keep_server を付けて起動したままにする(後で pkill llama-server などで止める)
既に動いているサーバーにつなぐ SURYA_INFERENCE_URL=http://127.0.0.1:8080/v1(末尾は /v1)
同時に送るページ数 SURYA_INFERENCE_PARALLEL(llama.cpp の既定は8)
小さい文字の精度を上げる IMAGE_DPI_HIGHRES=300(既定192、遅くなる)
とにかく速く IMAGE_DPI_HIGHRES=96
レイアウトを先に検出してからブロックごとに読む --block_mode
一部のページだけ --page_range "0,5-10"
旧モデルに戻す SURYA_MODEL_CHECKPOINT=datalab-to/surya-ocr-2 と SURYA_GGUF_REPO=datalab-to/surya-ocr-2-gguf など

Mac で試験的な MLX バックエンドを使う場合は、モデルを MLX 形式に変換してから指定します。変換には PyTorch などを含む [build] の追加パッケージが必要です。

# 変換用の環境(PyTorch が入る)
pip install "surya-ocr[build]==0.24.0" "mlx-vlm==0.7.10"
python -m surya.scripts.build_mlx --checkpoint datalab-to/surya-ocr-2.5 --out-dir ./mlx-build --q-bits 8
# → ./mlx-build/surya-ocr-2.5-mlx-q8 ができる

# 変換したモデルで OCR する(mlx_vlm.server が自動で起動する)
export SURYA_INFERENCE_BACKEND=mlx
export SURYA_MLX_MODEL=$PWD/mlx-build/surya-ocr-2.5-mlx-q8
surya_ocr 資料.pdf --stdout

手元でも変換して試しました。変換は22秒で終わり、8bit のモデルは793MB でした(Hugging Face からの取得が途中で止まったので、重みを curl で取得し、--checkpoint にそのフォルダを指定しています)。同じ34ページで llama.cpp と比べた結果です。

llama.cpp(既定・GGUF) MLX(8bit に変換)
1ページずつの平均時間 4.2〜5.5秒 2.4秒
8ページ同時の処理量 0.60〜0.82 ページ/秒 0.82 ページ/秒
文字の正しさ(PDF/スキャン) 99.5%/99.8% 99.3%/98.3%
表の TEDS(形だけ) 0.996(0.996) 0.985(0.996)
数式 5/5 5/5
記号の文字化け なし 「¥」「×」「○」が「�」になった箇所が7つ

1ページずつなら MLX が約2倍速く、表の形・数式・読み順も同じでした。一方で、金額の「¥」や評価欄の「×」「○」が文字化けの印「�」に置き換わる箇所がありました。公式も「試験的」としている段階なので、記号の多い帳票では既定の llama.cpp を使うほうが安全です。なお、llama.cpp 側は8bit に量子化していないモデルなので、量子化の条件をそろえた比較ではありません。

どれを使うか:文書の中身で選ぶ

ここまでの結果から、使い分けの目安をまとめます。

文字の層があるか、結合セルの表・数式・段組・縦書きがあるかで、PyMuPDFとSuryaを選ぶ判断の流れ

図15:迷ったら「まず軽い方法、崩れるページだけ Surya」で組み合わせます

文字の層がある PDF で、表も数式も段組もなければ、PyMuPDF や pymupdf4llm で十分です。速く、文字も正確です(NFKC 正規化は忘れずに)。スキャンした資料や、結合セルの表・数式・段組・縦書きを含む資料では、Surya の価値がはっきり出ます。

全ページを Surya に通すと時間がかかるので、次のような組み合わせが現実的です。

  1. まず pymupdf4llm で全ページを読む
  2. 文字がほとんど取れないページ(スキャン)、表があるページ、数式用の文字(𝑝 𝑥 などの数学用英字)が多いページを見つける
  3. そのページだけ Surya に回し、結果を差し替える

ライセンスの注意

Surya のコードは Apache 2.0 ですが、モデルの重みは AI Pubs Open RAIL-M を改変したライセンスです。モデルに付いているライセンス文書では、次の場合の利用を(個人利用・研究目的を除いて)認めていません。

  • 利用者(勤務先・所属先を含む)の前年の総売上が500万ドルを超える場合
  • 利用者が合計500万ドルを超える資金(出資・借入)を調達している場合
  • Datalab の製品・サービスと競合するものを提供している場合

多くの企業の業務利用は、この条件に当てはまるはずです。その場合は Datalab の商用ライセンスを検討するか、同社の API(Datalab API)を使うことになります。社内で試す前に、法務や情報システム部門と確認してください。

トラブルシューティング

うまく動かないときは、「サーバーの起動 → 接続 → 結果の解釈」のどこで止まっているかを順に確かめます。

サーバーが起動しない、つながらない、結果に特殊な印が残る、文字の誤りや遅さの4段階で確かめる診断の流れ

図16:上から順に確かめると、原因を切り分けやすくなります

よくある症状と対処を表にまとめます。

症状 原因の候補 対処
llama-server が見つからないというエラー llama.cpp が入っていない、PATH が通っていない brew install llama.cpp、which llama-server で確認
初回の実行が長く止まる モデル(約1.3GB)の取得中 そのまま待つ。止まったままなら ~/.cache/huggingface の .incomplete を消して再実行
サーバーは起動したのにつながらない サンドボックスやプロキシが 127.0.0.1 への接続を止めている 実行環境のネットワーク制限を確認。既存サーバーなら URL の末尾が /v1 か確認
結果に特殊な印(Text などのラベルを囲んだ記号)が残る・座標が空 自分で起動した llama-server に --special がない --special を付けて起動する(自動起動なら付いている)
小さい文字の誤りが多い 画像の解像度が足りない IMAGE_DPI_HIGHRES=300 で試す
毎回の起動待ちが長い コマンドのたびにサーバーを起動・停止している --keep_server を使う
MLX が使われない 環境変数が足りない SURYA_INFERENCE_BACKEND=mlx と SURYA_MLX_MODEL(変換後のフォルダ)の両方を設定
MLX で「¥」「×」「○」が「�」になる 試験的な MLX バックエンドでの記号の扱い(手元で7か所) 記号が重要な文書は llama.cpp に戻す

手元では、Hugging Face からのモデル取得が途中で止まることがありました。その場合は、ファイルの URL を curl -L -C - で取得すると途中から再開できます。

まとめ

この記事の要点を振り返ります。

  • 従来の PDF 抽出や行単位の OCR は、文字は取れても表の結合セル・数式・段組や縦書きの読み順という構造が崩れ、スキャンでは文字すら取れないことがありました
  • Surya v0.24.0 は、689M の文書専用モデル Surya 2.5 が、ブロックの種類・座標・中身を読む順に、表は HTML、数式は LaTeX で書き出します。重い依存を外し、Mac でも brew install llama.cpp と pip install surya-ocr で動きます
  • 手元の34ページでは、結合セルの多い表の TEDS が 0.52〜0.75 → 1.00、数式は 0/5 → 5/5、縦書き・3段組の読み順も正しく、スキャンでも品質はほぼ落ちませんでした
  • 一方、文字の層がある PDF の文字そのものは従来の抽出が速く正確です。「3.2倍速い」は文字の多いページで効く改善で、日本語の短い帳票では旧版と同程度でした
  • 業務で使う前に、モデルの重みのライセンス(売上・調達額500万ドル超は要契約)を必ず確認してください

次の一歩としては、自社の代表的な文書を10〜20ページ選び、surya_gui で崩れる箇所がないかを確かめることをおすすめします。そのうえで、pymupdf4llm と組み合わせて「崩れるページだけ Surya」に回す流れを作ると、速さと精度のバランスを取りやすくなります。

参考リソース

0
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?