Open AIのAPIを利用したドキュメント一括生成ツールをGitHubに公開
Chat GPTは、文字通りチャットのインタフェースによって、Open AIのサービスからインタラクティブに有効な回答を引き出すツールです。システム開発において、Chat GPTの活用はすでに一般的になっており、開発者が作成したソースコードをレビューしてもらったり、保守のためのドキュメントをリバースしたりする、という用途で使っている人も多いのではないでしょうか。ただしこれらの用途の場合、特段のインタラクションは不要であり、目的に応じてプロンプトのテキストを事前に決めることができれば、1ショットで答えを引き出すことが可能です。
つまり「チャット」である必要性はなく、Open AIが提供するAPIを直接利用すれば、複数のソースコードから一括してドキュメント（レビュー結果であったり仕様書であったり）を生成することができる、というわけです。
今回、特定のディレクトリに格納された複数のソースコード（Java、JS、Pythonなど）を再帰的に読み込み、目的毎に事前定義されたプロンプトを付加してOpen AIのAPIを呼び出すことにより、様々なドキュメントを、一括で生成するツール”brain2doc”を作成しました。
当ツールをGitHub上に公開しましたので、ご紹介します。
このツールとOpen AIのAPIを活用することで、システム開発におけるレビューやドキュメント作成を大幅に効率化することができる！と確信しています。
brain2docとは
brain2docは、Open AIのAPIによって、ソースコードからドキュメントを一括生成するツールです。
利用にあたっては、Open AIの以下のサイトにアクセスし、APIキーを発行してもらう必要があります。
API発行画面は、以下のとおりです。
DEMO英語版 (20秒)
Features
- ソースには、単独のファイルはもちろん、ディレクトリを指定することも可能です。その場合、そこに格納されるファイルに対して再帰的に処理を行います。またZIPファイルを指定すると、ZIPファイル内を再帰的に処理します。
- 生成結果はマークダウン形式で出力されます。ディレクトリやZIPファイルの場合は、各ソースコードの生成結果が1つのマークダウンファイルに連結されます。
- 対応するソースコードには、以下の種類があります。
- Javaのソースコード（拡張子".java"が対象）
- JavaScriptまたはTypeScriptのソースコード（拡張子".js", ".ts"が対象）
- Pythonのソースコード（拡張子".py"が対象）
- SQLコード（拡張子".sql"が対象）
- ページファイル（拡張子"page", ".html", ".htm", ".xhtml", ".jsp"が対象）
- シェルスクリプト（拡張子".sh", ".bash", ".ksh", ".bash"が対象）
- 上記以外の汎用的なリソース
- 対応する生成処理には、以下の種類があります。生成結果はマークダウン形式で出力されます。
- 仕様書
- サマリー
- レビュー結果・改善提案
- 何らかの一覧のテーブル（定数、メッセージ、REST APIなど）
- 上記以外の汎用的な出力（デフォルト）
- API Keyは環境変数"OPENAI_API_KEY"に設定しますが、コマンドにパラメータとして指定することもできます。
- API呼び出し時にトークンリミットに達してエラーが発生すると、自動的にソースを適切なサイズに分割して再送することが可能です。
- API呼び出し時にレートリミットに達してエラーが発生すると、一定間隔を置いてから自動的にリトライします。
- API呼び出しでは、接続タイムアウト時間、読み込みタイムアウト時間、リトライ回数、リトライ間隔、プロキシサーバーなどをパラメータで指定可能です。
- OpenAIのモデルは、デフォルトでは"gpt-4"ですが、"gpt-3.5-turbo"などにパラメータで切り替えることができます。
- 出力結果の大きさを、小、中、大、制限なしの4種類から選択できます。
- 対象のソースファイルの名前を、正規表現で絞り込むことが可能です。
- 言語はデフォルトでは日本語ですが、英語にも対応しています。
Requirement
本ツールを動作させるには、Java 17以上の環境が必要です。
Installation
brain2docの実行に必要なファイルはJARファイルのみであり、依存ライブラリも含めて1つのJARファイルにパッケージングされています。
JARファイルは、releasesディレクトリ下の最新VERをダウンロードして使用してください。
Usage
java -jar <任意の場所>/brain2doc.jar [ソース] [オプション]
- [ソース]には、読み込み対象となるソースのファイルまたはディレクトリを指定する（指定必須）
- ディレクトリを指定すると、再帰的にファイルを一括処理する
- ZIPファイルを指定した場合も、ファイル内を再帰的に処理する
オプションの指定方法は、以下のとおりです。
--help
パラメータの指定方法を表示する
--url
APIのURLを指定する（デフォルトは"https://api.openai.com/v1/chat/completions"）
--model
gptのモデルを指定する（デフォルトは"gpt-4"）
--apikey
APIキーを指定する（指定がない場合は環境変数"OPENAI_API_KEY"より取得）
--temperature
回答に対する「確率分布の散らばり具合」を指定する（デフォルトは0.7F）
--resource
入力となるリソースの種別を指定する（デフォルトは"others"）
以下の種別あり
java : Javaのソースコード（拡張子".java"が対象）
js : JavaScriptまたはTypeScriptのソースコード（拡張子".js", ".ts"が対象）
python : Pythonのソースコード（拡張子".py"が対象）
sql : SQLコード（拡張子".sql"が対象）
page : ページファイル（拡張子"page", ".html", ".htm", ".xhtml", ".jsp"が対象）
shell : シェルスクリプト（拡張子".sh", ".bash", ".ksh", ".bash"が対象）
others : 上記以外の汎用的なリソース
--gen
リソースから何を生成したいかを指定する（"--gen"と"--gen-table"の2つは指定不可）
以下の種別あり
spec : 仕様書
summary : サマリー
review : レビュー結果・改善提案
others : 上記以外の汎用的な出力（"--gen"、"--gen-table"の指定がなかった場合のデフォルト）
--gen-table
リソースから何かの一覧を生成したい場合、その名前を指定する（"--gen"と"--gen-table"の2つは指定不可）
--fields
リソースから一覧を生成する場合、その列名を列挙する（"--gen-table"の場合は指定必須）
--output-scale
出力結果の大きさ（目安）を指定する（デフォルトは"nolimit"）
small : スモールサイズ（50文字程度）
medium : ミディアムサイズ（200文字程度）
large : ラージサイズ（500文字程度）
nolimit : 制限なし
--regex
読み込み対象となるソースを絞り込むための正規表現文字列を指定する（任意指定）
--dest
出力するマークダウンファイルのディレクトリ名またはファイル名をフルパスで指定する
ディレクトリ名を指定した場合は、デフォルトのファイル名は"brain2doc-{リソース名}-{出力種別名}-{yMMddHHmmss}.md"
（例："brain2doc-java-review-20230924104914.md"）
このオプションの指定がなかった場合は、ソースファイルと同じディレクトに、デフォルトのファイル名で出力される
--lang
入出力する言語を指定する（デフォルトは日本語）
ja : 日本語
en : 英語
--template
任意のテンプレートファイルをフルパスで指定する（任意指定）
デフォルトのテンプレートファイルと、差分のみが上書きされる
--max-split-count
最大ファイル分割数を指定する
トークンリミットオーバーやレートリミットオーバーが発生した場合、自動的にファイルを分割するが、
分割数がこのオプションに指定された数値を超えた場合は、当該ソースファイルの処理はスキップする（デフォルト10）
--proxyURL
API呼び出しを行うときのプロキシサーバーのURLを指定する
--connect-timeout
API呼び出しにおける接続タイムアウト時間を秒で指定する（デフォルトは10秒）
--timeout
API呼び出しにおける読み込みタイムアウト時間を秒で指定する（デフォルトは300秒）
--retry-count
API呼び出しでレートリミットオーバーや読み込みタイムアウトが発生した場合の、最大リトライ回数を指定する（デフォルトは3回）
--retry-interval
API呼び出しでレートリミットオーバーや読み込みタイムアウトが発生した場合の、リトライ間隔を秒で指定する（デフォルトは60秒）
--auto-split
このオプションを指定すると、1回のAPI呼び出しがトークンリミットに達した場合に、自動的に適切なサイズに分割して再送するモードに切り替わる
指定がなかった場合は当該ソースをスキップする
投入コマンド例
java -jar brain2doc-0.1.1.jar \
c://src-target/jackson/src/main/java/com/fasterxml/jackson/core/base \
--resource java \
--gen spec \
--dest C:/tmp/output \
--auto-split
コンソール表示内容
本ツールを起動すると、以下の情報がコンソールに表示されます。
-
PROMPT CONTENT (without source)
プロンプトに投入する内容。ただしソースファイルはここでは表示しません（実際にはソースを含むプロンプトが投入されます）。 -
PROGRESS
各ソースファイルの進捗状況がリアルタイムに表示されます。
自動分割モードの場合、トークンリミットオーバーやレートリミットオーバーが発生すると、"[FILE_SPLIT]"と表示されて処理が先に進みます。 -
REPORT
全ファイルの呼び出しが終了すると、レポートを出力します。
レポートの内容は、(1)ソースファイル名、(2)ステータス、(3)リクエストのトークン数、(4)レスポンスのトークン数、(5)処理時間
以下にコンシール表示の例を示します。
##############################
# #
# Welcome to Brain2doc #
# #
##############################
### PROMPT CONTENT (without source)
あなたは『プロのエンジニア』です。
[制約条件]
回答は日本語でお願いします。
回答は50文字以内でお願いします。
マークダウンの見出しは、タイトルにレベル2を使用し、それ以外はレベル4以上にしてください。
[命令書]
制約条件と入力ソースをもとに最高のクラス仕様書を、マークダウン形式で出力してください。
タイトルは「クラス仕様書」でお願いします。
各メンバの仕様はマークダウンのテーブル形式で出力してください。
### PROGRESS
- processing [GeneratorBase.java] ===========> done!
- processing [package-info.java] ========> done!
- processing [ParserBase.java] =[FILE_SPLIT]========================================================> done!
- processing [ParserMinimalBase.java] ==================================================================> done!
### REPORT
|SOURCE|STATUS|REQUEST TOKEN|RESPONSE TOKEN|PROCESS TIME|
|-|-|-|-|-|
|GeneratorBase.java|SUCCESS|4604|272|17|
|package-info.java|SUCCESS|297|169|13|
|ParserBase.java|SUCCESS|5674|919|79|
|ParserBase.java|SUCCESS|7093|883|77|
|ParserMinimalBase.java|SUCCESS|5849|1463|129|
Author
License
"brain2doc" is under MIT license.