paperless-gpt: paperless-ngx の OCR とメタデータ生成を LLM に置き換える Go 製サイドカー
Use LLMs and LLM Vision (OCR) to handle paperless-ngx - Document Digitalization powered by AI
ひと目でわかる
- これは何？
- paperless-ngx の文書処理に LLM ベースの OCR とタイトル・タグ・ correspondent の自動生成を足す Go 製アプリケーション。既存 OCR の弱点と、LLM に任せる場合のコスト・検証コストの両方を見る。
- 誰に向いている？
- paperless-ngx をすでに運用していて、スキャン品質のばらつきやタグ付けの手作業に時間を取られているなら、paperless-gpt は試す価値がある。逆に、文書を外部 API に送れない、あるいは OCR 結果を人間が全件確認する運用を崩したくない場合は向かない。
- 商用利用できる？
- できます。MIT は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- されています。直近 1 日以内に新しいコミットがあります。
- 何の言語で書かれている？
- 主に Go です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
paperless-ngx が埋めきれない部分を外から補う
paperless-ngx は文書の保管と検索を担うが、スキャン品質が悪い文書のテキスト化や、タイトル・タグ・ correspondent の付与は利用者の手作業に残りやすい。paperless-gpt はこの後半部分を担当する。README は paperless-ngx と組み合わせて AI によるタイトルとタグを生成し、手作業の整理時間を減らすと説明している。対象読者は paperless-ngx をすでに動かしている人で、新規の文書管理システムを探している人ではない。既存の保管庫はそのままに、取り込み後の処理だけを差し替える位置づけになる。README は LLM で OCR を強化する点を他ツールとの違いとして挙げているが、これは OCR そのものを置き換えるという意味ではなく、抽出したテキストを LLM に渡して文脈を踏まえた整形やメタデータ生成を行うという意味で読むのが正確だろう。
処理の流れ: 文書取得、OCR、LLM 推論、書き戻し
リポジトリの構成から読み取れる範囲では、paperless-gpt は paperless-ngx の API から未処理の文書を取得し、設定された OCR プロバイダに画像または PDF を渡してテキストを得る。次にそのテキストを LLM に渡し、タイトル、タグ、 correspondent、作成日、カスタムフィールドの候補を生成する。生成結果は Web UI で確認でき、手動で承認・修正する経路と、自動処理に回す経路の両方が用意されている。OCR プロバイダは 4 系統あり、OpenAI か Ollama を使う LLM OCR が既定、ほかに Google Document AI、Azure Document Intelligence、自前で動かす Docling Server が選べる。処理モードも画像単位、PDF 単位、PDF 全体の 3 通りがあり、README にはプロバイダごとの互換性表が置かれている。つまり OCR の品質とデータの送信先は、プロバイダとモードの組み合わせで決まる。ここが設計上の中心で、LLM の役割は OCR の代替ではなく、抽出後の解釈と整形にある。
起動方法: Docker Compose と環境変数
README の Installation は Docker Compose を先に示している。paperless-ngx と並べて compose し、いくつかの環境変数を設定する形になる。設定は Configuration の Environment Variables にまとまっており、OCR プロバイダの選択、LLM の接続先、タグ付けの挙動、PDF の扱いなどをここで決める。プロンプトはコードに埋め込まず、default_prompts と prompts のディレクトリ構造で管理され、Web UI の Settings から編集できる。README はこの構造によってカスタマイズが永続化されると説明している。カスタムフィールドを使う場合は設定で機能有効化と対象フィールドの選択が必須で、どちらかが欠けると動作しないと明記されている。書き込みモードは Append、Update、Replace の 3 つで、Append は既存フィールドに一切触れず新規のみ追加する最も安全な選択肢とされる。手動セットアップの手順も README にはあるが、Docker 前提の記述が中心である。
LLM OCR が効く場面と、そうでない場面
README は LLM による OCR を従来手法より高精度と表現し、低品質なスキャンでも文脈を踏まえたテキストが得られるとしている。ただしこれはあくまでプロジェクト側の主張であり、比較用のサンプルが README 内に置かれている構成になっている。判断材料として重要なのは、LLM OCR はページ画像をモデルに送るため、従来の OCR より計算資源と待ち時間を消費する点である。Ollama で reasoning モデルを使う場合、README は qwen3:8b を privacy と performance の妥協点として挙げ、GPU や NPU が十分ならより大きなモデルで精度が上がるとしている。つまり手元のハードウェアが実質的な上限を決める。クラウドの OCR サービスを選べばこの制約からは離れられるが、文書そのものを外部に送ることになる。手書きや特殊なレイアウトが多い文書群では、汎用 LLM OCR より専用 OCR のほうが安定する可能性があり、README が複数プロバイダを用意していること自体が、単一手法ではカバーしきれないという前提の表れだと読める。
PDF テキストレイヤーとメタデータコピーの制約
paperless-gpt は OCR 結果を透明なテキストレイヤーとして各単語の位置に重ねた PDF を生成できる。見た目を保ったまま検索と選択が可能になる仕組みで、生成物はローカル保存か paperless-ngx へのアップロードを選べる。ここで注意すべきは README に Metadata Copying Limitations という節が設けられている点で、元文書のメタデータを完全には引き継げない場合があることが示されている。OCR 済み PDF を paperless-ngx に戻す運用では、タグや correspondent の対応関係を別途確認する必要がある。また README には Safety Features と Usage Recommendations の節もあり、既存 OCR の検出も行われる。すでにテキスト層を持つ文書に対して二重に OCR をかけると、かえって品質を落とす可能性があるため、この検出がどう働くかは導入前に確認しておきたい。テキストレイヤーの位置精度は元スキャンの傾きや解像度に依存し、README はその限界について具体的な数値を示していない。
既存 OCR との役割分担、Docling という選択肢
比較対象として分かりやすいのは、paperless-ngx が標準で使う Tesseract 系の OCR である。Tesseract はローカルで完結し、ページ画像をモデルに送る必要がなく、決まったレイアウトの印刷文書では安定した結果を返す。一方で低品質スキャンや複雑なレイアウトでは精度が落ちやすく、抽出後のタイトルやタグの生成は行わない。paperless-gpt はこの後工程を引き受ける点が違いであり、OCR 自体を置き換えるかどうかはプロバイダ次第である。同じく自前運用の選択肢として README が挙げる Docling Server は、OCR と文書変換を担う自己ホスト型サービスで、クラウドに文書を出さずに LLM OCR 以外の経路を確保できる。Google Document AI と Azure Document Intelligence はマネージドの文書解析で、精度と引き換えに文書が外部に送られる。どの経路を選ぶかは、精度、待ち時間、データの所在のどれを優先するかで決まる。
向く運用と向かない運用
paperless-ngx をすでに動かしていて、取り込んだ文書のタグ付けや命名に毎回時間を取られている場合、paperless-gpt はその作業を候補生成に置き換える。Web UI で承認する経路を残せば、完全自動に踏み切る前の段階導入ができる。逆に、文書を外部 API に一切送れない制約があるなら、Ollama か Docling Server を自前で立てる構成が必須になり、GPU の有無が導入可否を左右する。また、すべての OCR 結果を人間が確認する運用を前提にしている場合、自動処理の利点は小さく、確認対象が paperless-gpt の画面に移るだけになる。カスタムフィールドの Replace モードは既存フィールドを削除するため、既存データを重視する環境では最初から使うべきではない。ライセンスは MIT で、paperless-ngx 本体とは別に管理される。Docker イメージは Docker Hub と GHCR の両方で配布されていると README は示している。
導入前に確かめる 3 点
第一に、OCR プロバイダをどれにするか。LLM OCR を選ぶなら Ollama のモデルとハードウェア、OpenAI を選ぶなら API キーと従量コストの見積もりが先に必要になる。第二に、生成した PDF をローカル保存するか paperless-ngx にアップロードするか。アップロードを選ぶ場合はメタデータの引き継ぎ制約を前提に運用を組む必要がある。第三に、カスタムフィールドを有効にするなら、対象フィールドと書き込みモードを Append から始めること。設定で機能を有効化し、フィールドを 1 つ以上選ばないと動かない点も README に明記されている。プロンプトは default_prompts と prompts の分離構造になっているため、既定を書き換えずに追加する形で調整できる。バージョンは v0.27.0 まで進んでおり、v0.26.0 は Resilience、v0.27.0 は Clarity と名付けられた更新が続いている。
編集部の結論
paperless-ngx をすでに運用していて、スキャン品質のばらつきやタグ付けの手作業に時間を取られているなら、paperless-gpt は試す価値がある。逆に、文書を外部 API に送れない、あるいは OCR 結果を人間が全件確認する運用を崩したくない場合は向かない。導入前に確認すべきは、Ollama か OpenAI か Google Document AI か Azure Document Intelligence か Docling Server のどれを OCR に使うか、そして PDF テキストレイヤーを paperless-ngx に戻すかローカル保存にするかという 2 点。特にカスタムフィールドの Replace モードは既存フィールドを削除するため、まず Append で動かして挙動を確認してから切り替えるのが安全である。
コミュニティノート