get_paper_inf5.py ドキュメント

プログラムの動作

get_paper_inf5.py は、学術論文のPDFファイルからメタデータ(著者、論文題目、ジャーナル、発行日、DOIなど)をAI(OpenAI、Google Gemini、LM Studioなど)を利用して抽出し、その情報をExcelファイルにまとめるツールです。また、抽出した情報に基づいてPDFファイルの名前を自動的に変更する機能も提供します。

主な機能:

  • PDFからのテキスト抽出: PDFファイルから論文本文のテキストを抽出し、AIモデルへ送るテキスト量を制御します。

  • AIによるメタデータ抽出: 抽出したテキストを、設定されたAI(OpenAI, Google Gemini, LM Studio)に送信し、論文のメタデータ(著者、題目、ジャーナル名、発行年、DOIなど)をJSON形式で抽出させます。

  • 推奨ファイル名の生成: 抽出されたメタデータに基づき、ユーザー定義のテンプレートに従った推奨ファイル名をAIが生成します。

  • Excelサマリーの生成: 抽出されたすべてのメタデータをExcelファイル (summary.xlsx など) に追記し、論文の管理を容易にします。

  • PDFファイルのリネーム: AIが生成した推奨ファイル名に従って、元のPDFファイルをリネーム(またはコピー)する機能があります。

  • 柔軟なファイル検索: 単一のPDFファイルだけでなく、ワイルドカードを使用した複数のファイルや、サブディレクトリを含む再帰的なファイル検索に対応します。

解決する課題: 学術論文の管理において、手作業でメタデータを抽出したり、一貫性のないファイル名で論文が保存されたりする問題を解決します。このプログラムは、大量の論文を効率的に整理し、必要な情報に素早くアクセスできる環境を構築するのに役立ちます。

原理

このプログラムの核となる原理は、大規模言語モデル(LLM)を用いた情報抽出です。PDFからテキストを抽出し、それを整形されたプロンプトとしてLLMに送信することで、特定の情報(論文のメタデータ)を構造化された形式(JSON)で取得します。

  1. PDFテキスト抽出: PyPDF2 ライブラリを使用してPDFファイルからテキストコンテンツを読み取ります。PDF全体ではなく、指定された最大バイト数(max_bytes)に制限してテキストを抽出し、AIへの送信コストと処理時間を最適化します。これは、論文全体をAIに送る必要がない場合や、AIのトークン制限に合わせる場合に特に有効です。

  2. AIプロンプトの構築: 抽出されたテキストは、あらかじめ定義されたプロンプトテンプレートに埋め込まれます。このプロンプトは、AIに対して「学術論文のテキストから特定の情報をJSON形式で抽出すること」および「推奨ファイル名を特定の形式で生成すること」を明確に指示します。例えば、著者名、論文題目、ジャーナル名、発行日、DOIなどの項目が具体的にリストアップされます。

    以下の学術論文のテキストから、指定された情報をJSON形式で抽出してください。
    また、first author、last author、短縮したtitle (short_title)、shortest_name、発行年から
    推奨ファイル名 {{template}} を作ってください。
    ...
    

    上記のような指示をAIに与えることで、期待する形式での回答を促します。

  3. AIモデルの選択とクエリ: tkai_lib_litellm モジュールを介して、--api オプションで指定されたAIモデル(OpenAIのGPTシリーズ、GoogleのGeminiシリーズ、またはLM Studioでホストされているローカルモデルなど)にプロンプトを送信します。各AIプロバイダーに応じて、temperature(創造性)、reasoning_effort(推論強度)、max_tokens(応答の最大トークン数)などのパラメータが調整されます。特に、JSON形式での応答を強制する response_format={"type": "json_object"} オプションが使用され、AIの出力が確実に構造化されるようにします。

  4. AI応答の解析とメタデータ抽出: AIからの応答はテキスト形式で返されますが、その中にJSONオブジェクトが含まれています。response_to_metadata 関数は、AIの応答テキストからJSONオブジェクトを抽出し、Pythonの辞書形式に変換します。AIが応答の前後に追加の説明文を付与した場合でも、JSON部分を適切に特定して解析するロジックが含まれています。

  5. Excelへの書き込み: 抽出されたメタデータは、openpyxl ライブラリを使用してExcelファイルに追記されます。ファイルが存在しない場合は新しいワークブックが作成され、ヘッダー行が追加されます。これにより、複数の論文のメタデータを一元的に管理できます。

  6. ファイルのリネーム: AIによって生成された filename_rename の値が取得できた場合、rename_file 関数が呼び出されます。この関数は、input_file を新しいファイル名にリネームするか、または元のファイルを保持しつつ新しいファイル名でコピーします。これは、--delete_original オプションによって制御されます。

このプログラムは、特定の数式や物理式は使用せず、主に自然言語処理とデータ構造の処理によって機能します。

必要な非標準ライブラリとインストール方法

このプログラムを実行するには、以下のPython非標準ライブラリが必要です。

  1. openpyxl: Excelファイルの読み書きに使用します。

    pip install openpyxl
    
  2. PyPDF2: PDFファイルからテキストを抽出するために使用します。

    pip install pypdf2
    
  3. tkai_lib_litellm: 大規模言語モデル(LLM)APIとの連携に使用されるモジュールです。 このライブラリは、標準の pip でインストールできるものではなく、本プログラムの実行環境に別途提供されていることを想定しています。もし ModuleNotFoundError が発生した場合は、プログラム提供元にお問い合わせください。 なお、PDFテキスト抽出時に PyCryptodome が必要というエラーメッセージが表示された場合は、以下のコマンドでインストールしてください。

    pip install pycryptodome
    

必要な入力ファイル

プログラムは以下の入力ファイルを必要とします。

  1. PDFファイル:

    • 形式: 学術論文が記述されたPDFファイル (.pdf)。

    • 内容: プログラムがテキストを抽出し、AIに送信してメタデータを解析します。論文のテキストが明確であることが求められます。

    • 指定方法: コマンドライン引数 input_file でパスを指定します。ワイルドカード (*.pdf) や再帰検索 (--recursive 1) にも対応しています。

  2. ai.env 設定ファイル:

    • 形式: テキストファイル。

    • 内容: 各AIサービス(OpenAI, Google Geminiなど)へのアクセスに必要なAPIキー、使用するモデル名、その他の設定(例: temperature, max_tokens, reasoning_effort)が含まれます。このファイルは、スクリプトと同じディレクトリに配置するか、環境変数として設定する必要があります。

    • 例:

      OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      openai_model="gpt-4o"
      openai_model5="gpt-5.4"
      temperature="0.3"
      
      GOOGLE_API_KEY="AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      gemini_model="gemini-3.1-pro-preview"
      
      lmstudio_model="qwen/qwen3.8-27b"
      
      max_tokens="2000"
      reasoning_effort="low"
      

      OPENAI_API_KEY や GOOGLE_API_KEY は、各AIサービスの公式ウェブサイトで取得できるAPIキーに置き換える必要があります。

生成される出力ファイル

プログラムの実行により、以下のファイルが生成される可能性があります。

  1. Excelサマリーファイル:

    • ファイル名: デフォルトは summary.xlsx ですが、--summary_path 引数で変更できます。

    • 形式: Microsoft Excelワークブック (.xlsx)。

    • 内容: プログラムが処理した各PDFファイルから抽出されたメタデータが1行ずつ追記されます。Excelファイルの1行目には、以下のヘッダーが記述されます。

      • directory: 元のPDFファイルが存在するディレクトリパス。

      • filename_original: 元のPDFファイルのファイル名。

      • filename_rename: AIが推奨する新しいファイル名。

      • authors: 論文の全著者。

      • author_first: 第一著者。

      • author_last: 最終著者。

      • title: 論文題目。

      • short_title: 短縮された論文題目(CapitalFirst形式)。

      • journal: 発行雑誌名。

      • short_name: 発行雑誌名略称。

      • shortest_name: 発行雑誌名の最短略称。

      • date_received: 投稿受理日。

      • date_accepted: 採択日。

      • date_published_online: オンライン発行日。

      • date_published: 発行日。

      • year: 発行年。

      • volume: 巻番号。

      • issue: 号番号。

      • pages: ページ。

      • doi: DOI。 情報が不明な場合は、空文字列 "" が挿入されます。

  2. リネームまたはコピーされたPDFファイル(オプション):

    • ファイル名: AIが生成した filename_rename の値(例: (author_first)_(author_last)_(short_title)_(shortest_name)_(year).pdf 形式)に従います。

    • 形式: PDFファイル (.pdf)。

    • 内容: 元のPDFファイルと同じ内容です。--rename 1 オプションが指定された場合に生成されます。

      • --delete_original 1 の場合: 元のファイルは削除され、この新しいファイル名で置き換えられます。

      • --delete_original 0 の場合: 元のファイルは残され、この新しいファイル名でコピーが作成されます。

コマンドラインでの使用例 (Usage)

get_paper_inf5.py は、以下の基本的な形式でコマンドラインから実行します。

python get_paper_inf5.py [オプション] <input_file>

引数:

  • <input_file>: 処理するPDFファイルへのパス。ワイルドカード(例: *.pdf)やディレクトリ指定が可能です。

オプション:

  • --api {openai5,openai,google,lmstudio}: 使用するAI APIを指定します。

    • openai5: OpenAIの最新モデル(デフォルトモデル openai_model5)。推論強度 reasoning_effort を使用。

    • openai: OpenAIのGPTモデル(デフォルトモデル openai_model)。temperature を使用。

    • google: Google Geminiモデル(デフォルトモデル gemini_model)。

    • lmstudio: LM Studioでホストされたローカルモデル(デフォルトモデル lmstudio_model)。推論強度 reasoning_effort を使用。

    • デフォルト: openai5

  • --model <モデル名>: ai.env で設定されているデフォルトモデル名を上書きし、特定のモデルを使用します。

  • --reasoning-effort {low,medium,xhigh}: 推論強度を指定します(lmstudio または openai5 API使用時のみ有効)。

    • デフォルト: ai.env の reasoning_effort または low

  • --summary_path <パス>: 出力されるExcelサマリーファイルのパスを指定します。

    • デフォルト: summary.xlsx

  • --recursive {0,1}: サブディレクトリ内のPDFファイルも処理するかどうかを指定します。1 で有効化されます。

    • デフォルト: 0 (無効)

  • --rename {0,1}: AIが推奨するファイル名に基づいてPDFファイルをリネームするかどうかを指定します。1 で有効化されます。

    • デフォルト: 0 (無効)

  • --delete_original {0,1}: --rename 1 が指定された場合、リネーム後に元のファイルを削除するかどうかを指定します。1 で削除します。

    • デフォルト: 1 (削除する)

  • --max_bytes <バイト数>: AIに送信するPDFテキストの最大バイト数を指定します。

    • デフォルト: 10000

  • --template <テンプレート文字列>: ファイル名を変更する際のテンプレートを指定します。使用可能なプレースホルダーは (author_first), (author_last), (short_title), (shortest_name), (year) などです。

    • デフォルト: (author_first)_(author_last)_(short_title)_(shortest_name)_(year).pdf

コマンドラインでの具体的な使用例

例1: 単一のPDFファイルからメタデータを抽出し、Excelに保存する

docs ディレクトリにある my_paper.pdf というファイルを処理し、my_summary.xlsx というExcelファイルにメタデータを記録します。AIにはOpenAI APIのデフォルトモデルを使用します。

python get_paper_inf5.py --api openai --summary_path my_summary.xlsx "docs/my_paper.pdf"

実行結果の解説: docs/my_paper.pdf の内容からテキストが抽出され、OpenAI APIに送信されます。AIが抽出したメタデータ(著者、題目、発行年など)はコンソールに出力され、my_summary.xlsx に1行のデータとして追記されます。ファイルのリネームは行われません。

例2: 複数のPDFファイルを再帰的に検索し、Google Gemini APIで処理、リネームして元のファイルを削除する

papers ディレクトリとそのすべてのサブディレクトリから全てのPDFファイル (*.pdf) を検索し、Google Gemini API (google``) を使用してメタデータを抽出します。抽出された filename_rename` に従ってPDFファイルをリネームし、元のファイルは削除します。AIに送るテキストは最大50,000バイトに制限します。

python get_paper_inf5.py --api google --recursive 1 --rename 1 --delete_original 1 --max_bytes 50000 "papers/*.pdf"

実行結果の解説: プログラムは papers ディレクトリ以下のPDFファイルをすべて見つけ出し、それぞれについて処理を行います。各ファイルから抽出されたメタデータは summary.xlsx (デフォルトのファイル名) に追記され、PDFファイルは例えば Einstein_A_Relativity_Theory_1905.pdf のように、AIが生成した推奨ファイル名に変わります。リネームが成功した場合、元のPDFファイルはディスクから削除されます。

例3: LM Studioでホストされたローカルモデルを使用し、カスタムテンプレートでファイル名をコピー(削除せず)

articles/2023_research.pdf というファイルを処理します。LM Studioでホストされている local-qwen-model という名前のモデルを使用し、新しいファイル名形式を (year)-(short_title).pdf に設定します。元のファイルは削除せず、新しい名前でコピーを作成します。

python get_paper_inf5.py --api lmstudio --model "local-qwen-model" --template "(year)-(short_title).pdf" --rename 1 --delete_original 0 "articles/2023_research.pdf"

実行結果の解説: articles/2023_research.pdf からテキストが抽出され、local-qwen-model に送信されます。AIがメタデータと新しいファイル名を生成すると、例えば 2023-ResearchOnAI.pdf のような名前でPDFファイルのコピーが articles ディレクトリに作成されます。元の 2023_research.pdf ファイルはそのまま残ります。メタデータは summary.xlsx に記録されます。