ローカル論文閲覧・修正アシスタントのチュートリアル：Linuxにプライバシー優先のCLI Agentを導入

プロジェクト概要

ローカル論文閲覧・修正アシスタントは、Linux向けの軽量な論文支援CLI Agentです。ユーザーが質問を入力すると、モデルはローカルツールと論文検索機能を呼び出し、ローカルに保存された論文の読解、要約、分析を支援します。

プロジェクトではデフォルトでQwen3-14B-AWQを使用し、モデルの重みは約9.4 GBです。ローカルでモデルを実行し、論文や質問のプライバシーを保護したいNVIDIA GPU搭載環境のユーザーに適しています。デフォルトではウェブ検索を有効にせず、回答は主にモデル自身の能力と、ユーザーが構築したローカルナレッジベースに基づきます。

プロジェクトはMCPプロトコルに対応しており、ツール登録機構を通じてMCPサービスを接続できます。入力予算、システムプロンプト、ツール出力の長さを設定できるため、用途は論文支援に限定されません。

主な機能

• Linux環境でローカル論文支援Agentを実行。
• デフォルトでQwen3-14B-AWQローカルモデルを使用。
• テキスト形式のPDF、Markdown、TXTファイルをローカル検索ナレッジベースに登録。
• 対話形式の質問に対応し、コマンドラインから単発の質問も実行。
• 質問と回答の履歴をMarkdown形式で保存。
• MCPプロトコルとツール登録機構に対応。
• オプションのLangGraphセッションチェックポイントにより、別のウィンドウからセッションを継続。
• 環境、GPU、モデル設定を確認するスクリプトを提供。

インストール前の準備

本プロジェクトはLinux向けで、NVIDIA GPUを搭載したマシンの使用を推奨します。モデルの重みは約9.4 GBで、実行時にはモデル推論用に十分なVRAMも必要です。モデル、入力予算、出力長を調整する際は、VRAM容量も考慮してください。

現在、スキャンPDFのOCRには対応していません。スキャン論文を検索する場合は、あらかじめ内容をテキストに変換するか、プロジェクトが対応するテキスト形式のPDF、Markdown、TXTファイルを使用してください。

プロジェクトのダウンロードとインストール

まずGitHubリポジトリをクローンし、プロジェクトディレクトリをlocal-agentという名前にします。

git clone https://github.com/Ayi914/paperchecker.git local-agent
cd local-agent

Gitを使用しない場合は、GitHubページでCode → Download ZIPを選択し、解凍後にプロジェクトディレクトリでターミナルを開いてください。

プロジェクトディレクトリでインストールスクリプトを実行します。

bash scripts/install.sh

インストール完了後、起動スクリプトを実行します。

bash scripts/start.sh

初回起動時はモデルの読み込みを待つ必要があります。ターミナルに>>>プロンプトが表示されたら、質問を入力できます。例：

>>> 残差接続はどのような問題を解決するのか説明してください

次回以降は、プロジェクトディレクトリで通常bash scripts/start.shを実行するだけで起動できます。

初回実行とモデル設定

モデルディレクトリが不完全な場合や、モデルを再選択する場合は、次のコマンドを実行します。

bash scripts/setup.sh

モデルのダウンロードに失敗した場合は、まずネットワークを確認してください。ネットワークに接続できるマシンでモデルディレクトリ全体をダウンロードし、対象マシンにコピーして、設定時に既存のモデルを選択することもできます。

モデルの起動に失敗した場合は、ターミナルに表示されたログファイルを確認してください。ログは通常、次の場所にあります。

logs/cli-vllm-*.log

併せて、GPUのVRAMが他のプログラムに使用されていないことを確認してください。

自分の論文をインポートしてインデックスを作成

Agentに自分の論文に基づいて回答させるには、テキスト形式のPDF、Markdown、TXTファイルをdata/knowledge/ディレクトリに配置します。たとえば、ディレクトリには複数の論文や関連メモを保存できます。

ファイルの準備ができたら、ナレッジベースのインデックス作成コマンドを実行します。

bash scripts/start.sh rag-index

初回のインデックス作成時には、独立した検索モデルがダウンロードされるため、ネットワーク接続が必要です。インデックス作成後、対話型Agentを再起動します。

bash scripts/start.sh

これで、ローカル論文に基づく質問ができるようになります。例：

ローカル論文に基づいてYOLOv1の主要な革新を要約し、出典を列挙してください。

論文を配置していない場合やインデックスを作成していない場合、回答はローカル論文の内容ではなく、主にモデル自身の知識に基づきます。プロジェクトではデフォルトでウェブ検索を有効にしていません。

対話形式での使用

起動後、>>>プロンプトの後に質問を入力してEnterキーを押します。連続した追加質問、論文の主張の比較、同じテーマの段階的な分析に適しています。

次の組み込みコマンドで対話を管理できます。

• /help：対話コマンドを表示。
• /new：新しいセッションを開始。
• /exit、/quit、またはCtrl+D：プログラムを終了。

各ラウンドの質問と回答は、デフォルトでMarkdownファイルとして保存されます。パスの形式は次のとおりです。

output/月/日/時刻_マイクロ秒.md

コマンドラインで単発タスクを実行

対話型インターフェースを使用する必要がない場合は、起動スクリプトの引数として質問を直接渡せます。

bash scripts/start.sh "アテンション機構を要約してください"

--quietを使用すると、回答のみを出力できます。

bash scripts/start.sh "アテンション機構を要約してください" --quiet

回答ファイルを保存しない場合は、--no-saveを追加します。

bash scripts/start.sh "質問" --no-save

入力予算、出力長、プロンプトの設定

Agentの入力予算とシステムプロンプトはconfig/agent.yamlで変更できます。そのため、本プロジェクトは他のローカルAgent用途にも利用できます。

特に、次の2つのパラメータを区別する必要があります。設定ファイルのtool_output_max_chars: 4000はツール結果を文字単位で切り詰める上限であり、モデル回答のtoken上限ではありません。モデルの最大出力長は環境ファイルのLOCAL_AGENT_MAX_TOKENSで制御され、.env.exampleではデフォルトで2048 tokenに設定されています。

Agentの入力予算はデフォルトで4096 tokenです。入力予算、システムプロンプト、ツール出力長、最大出力tokenを調整する際は、コンテキスト長と利用可能なVRAMを総合的に考慮し、設定が高すぎてモデルが正常に動作しなくなることを避けてください。

ウィンドウをまたいだセッションの保存と復元

デフォルトでは、セッションのコンテキストは現在のプロセス内にのみ保存されます。CLIを終了しても、プログラムはコンテキストを自動的に復元せず、生成済みのMarkdown回答ファイルも自動的には読み込みません。

別のウィンドウから同じセッションを継続する場合は、config/agent.yamlでrun.checkpoint_enabledをtrueに変更し、常に同じセッションIDを使用します。

bash scripts/start.sh -i --thread-id my-paper

セッション状態は次の場所に保存されます。

data/checkpoints/langgraph.sqlite

/newを入力するか、新しい対話ウィンドウの起動時にセッションIDを指定しない場合は、新しいセッションが作成されます。各モデル呼び出しではデフォルトで直近4ラウンドの対話を使用し、4096 tokenの入力予算制限も適用されます。

環境確認とトラブルシューティング

問題が発生した場合は、まず環境確認スクリプトを実行することを推奨します。

bash scripts/doctor.sh

このスクリプトは環境、GPU、モデル設定を確認しますが、大規模モデルの読み込みや推論は行いません。そのため、本格的な起動前やトラブルシューティングに適しています。

• GPUがない：NVIDIA GPUを搭載したLinuxマシンの使用を推奨します。
• モデルディレクトリが不完全：bash scripts/setup.shを実行し、モデルを再選択するかダウンロードを続行します。
• モデルのダウンロードに失敗：ネットワークを確認するか、ネットワークに接続できるマシンでモデルディレクトリ全体をダウンロードし、対象環境にコピーします。
• モデルの起動に失敗：logs/cli-vllm-*.logを確認し、VRAMが他のプログラムに使用されていないことを確認します。
• ローカル論文が使用されない：ファイルがdata/knowledge/にあり、bash scripts/start.sh rag-indexを実行済みであることを確認します。

実用的な使用上のアドバイス

• 初回使用前にbash scripts/doctor.shを実行し、GPU、モデルディレクトリ、設定の問題を早期に発見します。
• 引用や分析が必要な論文をdata/knowledge/にまとめ、インデックス作成後に質問します。
• 質問時に要約の範囲、出力形式、出典の列挙を明確に指定すると、ローカル論文の内容を確認しやすくなります。
• VRAMが不足している場合は、入力予算、ツール出力上限、最大出力tokenをむやみに増やさないでください。
• 同じ研究テーマを継続的に扱う場合は、チェックポイントを有効にし、--thread-idを固定します。
• スキャンPDFは現在のプロジェクトだけでは直接OCRできないため、あらかじめ検索可能なテキストを用意してください。

まとめ

papercheckerは、ローカルモデルの起動から論文のインデックス作成、CLIでの質問応答までを一通り行える環境を提供します。プロジェクトをインストールした後は、デフォルトモデルで一般的な質問を分析できるほか、自分のテキスト形式の論文をナレッジベースに配置してインデックスを作成し、ローカル資料に基づいてAgentに回答させることもできます。agent.yaml、環境変数、セッションチェックポイントを使えば、コンテキスト、出力、セッション管理の方法をさらに調整できます。

プロジェクトのコードはMITライセンスで提供されています。起動やモデルに関する問題が発生した場合は、まず診断スクリプトを実行してログを確認してください。