RadFact は、グラウンディングの有無にかかわらず、モデルで生成された放射線医学レポートを、グラウンドトゥルース レポートに基づいて評価するためのフレームワークです。大規模な言語モデルの論理推論機能を活用する RadFact は、単一の数値ではなく一連のメトリクスであり、テキストのみおよびテキストと根拠のレベルで精度と再現率の側面を捉えます。
RadFact は、MAIRA-2: グラウンデッド放射線レポート生成で導入されました。ここでは、メトリクスの使用と開発を容易にするために、メトリクスのオープンソース実装を提供します。
LLMEngineによる並列処理RadFact を実行するには、このリポジトリのクローンを作成し、次のコマンドを実行するだけです。
pip install .これにより、 radfactパッケージとそのすべての依存関係がインストールされます。
あるいは、すべての依存関係を含む conda 環境をセットアップするためのMakefileを提供します。以下を使用して環境を作成できます。
make miniconda
make mamba
make env
conda activate radfact最初のステップでは miniconda をインストールし、2 番目のステップでは依存関係を迅速に解決するために mamba をインストールし、3 番目のステップではすべての依存関係を含むradfactという conda 環境を作成します。これにより、 setup_packages_with_depsレシピ (Makefile を参照) を介して、デフォルトで radfact パッケージが編集可能モードでインストールされます。最後に、RadFact を実行するための環境をアクティブ化します。プロジェクトに貢献するつもりであれば、これを強くお勧めします。
RadFact を使用するには、大規模な言語モデルにアクセスする必要があります。まず認証を使用してエンドポイントを設定し、次にテスト スクリプトを使用してエンドポイントが期待どおりに動作していることを確認する必要があります。
LLM は API エンドポイントとして利用可能であり、 langchain (バージョン 0.1.4) によってサポートされている必要があります。 AzureChatOpenAI モデルと ChatOpenAI モデルの 2 種類のモデルをサポートしています。前者は Azure で利用可能な GPT モデルに適しており、後者は Azure の Llama-3 などのカスタム デプロイされたモデルに適しています。
次の認証方法がサポートされています。
API_KEY環境変数をエンドポイントの API キーに設定します。デフォルトの環境変数名としてAPI_KEY使用します。別の名前を使用する場合は、 api_key_env_var_nameを介してエンドポイント構成で指定できます。これは、異なる API キーを持つ複数のエンドポイントを使用する場合に特に便利です。config.jsonプロジェクトのルート ディレクトリに追加します。この構成には、キーsubscription_id 、 resource_group 、およびworkspace_nameが必要です。これは、ポータル経由で AzureML ワークスペースからダウンロードできます。このファイルは、誤ったコミットを避けるために.gitignoreに追加されます。エンドポイント クラスで期待されるとおり、ファイルをconfig.jsonという名前でプロジェクトのルート ディレクトリに保存してください。key_vault_secret_nameを指定します。AzureChatOpenAIモデルのazure_ad_token_providerパラメーターに設定されます。これは、 AzureChatOpenAIモデルでのみサポートされます。 RadFact 内で enpoint を統合する方法の詳細については、endpoint.py のEndpointクラスのエンドポイント オブジェクトを使用する、arguments.py のLLMAPIArgumentsクラスを参照してください。
構成管理には hydra を使用します。エンドポイント構成はパスconfigs/endpointsにあります。
これは構成ファイルの例です。
ENDPOINT_EXAMPLE : type : " CHAT_OPENAI " url : "" deployment_name : " llama3-70b " api_key_env_var_name : "" keyvault_secret_name : "" speed_factor : 1.0 num_parallel_processes : 10
type: "CHAT_OPENAI"とtype: "AZURE_CHAT_OPENAI"の 2 種類があります。 Azure で利用可能な GPT モデルの場合は、 type: "AZURE_CHAT_OPENAI"を使用します。 Azure 上の Llama-3 などのカスタム デプロイされたモデルの場合は、 type: "CHAT_OPENAI"を使用します。urlおよびおそらくdeployment_nameフィールドを適切な値で更新する必要があります。keyvault_secret_nameはオプションであり、環境変数を介して API を設定する場合は必須ではありません。 API キーにデフォルトの"API_KEY"とは異なる環境変数名を使用する場合は、 api_key_env_var_name更新します。複数のエンドポイントを使用する場合は、エンドポイントごとに異なるapi_key_env_var_nameを指定します。speed_factorは、複数のエンドポイントが使用可能な場合に使用されます。これにより、エンドポイント間でデータを比例的にシャーディングするために使用される、他のエンドポイントと比較したエンドポイントの相対速度を指定できます。num_parallel_processesは、特定のエンドポイントをクエリするときに使用する並列プロセスの数を指定するために使用されます。 num_parallel_processesが並列処理を可能にする 1 より大きい値に設定されていない限り、すべてのリクエストは順次処理されます。上記のように、RadFact を根拠のないレポート、たとえばナラティブ レポートの評価に使用する場合、RadFact はまずレポートを語句のリストに変換します。このステップでは LLM を使用しますが、含意検証に使用される LLM と同じである必要はありません。次の構成のoverride endpoints: で、各タスクにどのエンドポイント (つまり LLM) を使用するかを指定できます。
configs/report_to_phrases.yaml -- レポートをフレーズのリストに変換します。 MAIRE-2 では、これに AzureChatOpenAI モデルとしてクエリできる GPT-4 を使用しました。configs/radfact.yaml -- 含意の検証。 MAIRA-2 では、ChatOpenAI モデルとしてクエリできるLLama-3-70B-Instructこれに使用しました。 異なるバックエンド LLM は異なる動作をし、異なるメトリック結果を生成する場合があります。特に、含意検証のパフォーマンスが低いモデルは RadFact に使用すべきではありません。含意検証が期待どおりに動作していることを確認するには、 python src/radfact/cli/run_radfact_test_examples.pyを実行し、結果が期待どおりであることを確認します。 LLama-3-70b-Instructモデルを使用すると、期待どおりの結果が得られました。
これはレポートからフレーズへのステップの動作をテストするものではないことに注意してください。
LLMEngineクラスを使用すると、複数のエンドポイントにわたる並列処理が可能になります。スループットが異なる複数のエンドポイントにアクセスできる場合、エンジンは速度に比例してエンドポイント間でデータをシャード化できます。このエンジンでは、単一のエンドポイントへのリクエストの並列処理も可能です。これは、エンドポイントの数に関係なく、デフォルトで使用されます。 speed_factorおよびnum_parallel_processesオプションについては、エンドポイント構成ファイルを参照してください。さらに、エンジンはバッチ処理と結果の中間キャッシュを処理します。すべての中間結果は、開始タイムスタンプがタグ付けされた実行 ID フォルダーの下のoutputs/radfactディレクトリに保存されます (例: outputs/radfact/run_20240814_075225 )。フォルダー構造は次のとおりです。
outputs/radfact/run_20240814_075225
├── batch_outputs
│ ├── outputs_0_100.json
| ├── .
| ├── .
| ├── .
│ └── outputs_1000_1100.json
├── progress
│ ├── subset_0_240.csv
| ├── .
| ├── .
| ├── .
│ └── subset_800_1100.csv
├── skipped
│ ├── subset_0_240.csv
| ├── .
| ├── .
| ├── .
│ └── subset_800_1100.csv
├── outputs.json
├── progress.csv
└── skipped.csv
outputs.jsonは、すべてのデータ ポイントの最終結果が含まれています。 progress.csvは、各エンドポイントの処理の進行状況が含まれます。 batch_outputsは、バッチ サイズごとの中間結果が含まれます。 skippedエラーによりスキップされたデータ ポイントが含まれます。
Getting_started ノートブックを参照して、独自のデータに対して RadFact を実行する方法を確認できます。 RadFact ワークフローとその使用方法を理解するために、最初にノートブックを読むことを強くお勧めします。データに対して RadFact を実行するスクリプトも提供します。スクリプトを実行する前に、上記のようにエンドポイントが設定されていることを確認してください。 run_radfactコマンドはpython src/radfact/cli/run_radfact.pyスクリプトを内部で実行します。 run_radfact --helpを実行すると、以下で説明するコマンドライン引数を介してデフォルトの動作をオーバーライドできます。スクリプトを実行するには、パッケージをローカルにインストールする必要があります。
$ run_radfact --help
usage: run_radfact [-h] [--radfact_config_name RADFACT_CONFIG_NAME] [--phrases_config_name PHRASES_CONFIG_NAME] --input_path INPUT_PATH [--is_narrative_text] [--output_dir OUTPUT_DIR] [--bootstrap_samples BOOTSTRAP_SAMPLES]
Compute RadFact metric for a set of samples and saves the results to a json file.
options:
-h, --help show this help message and exit
--input_path INPUT_PATH
The path to the csv or json file containing the samples to compute RadFact for. For finding generation samples, the csv file should have columns ' example_id ' ,
' prediction ' , and ' target ' similar to the example in ` examples/findings_generation_examples.csv ` . For grounded reporting samples, provide a json file in the
same format as ` examples/grounded_reporting_examples.json ` .
--is_narrative_text Whether the input samples are narrative text or not. If true, the input samples are expected to be narrative text, otherwise they are expected to be grounded
phrases.
--radfact_config_name RADFACT_CONFIG_NAME
The name of the config file for RadFact processing. We use the default config file but you can provide a custom config. Make sure the config follows the same
structure as ` configs/radfact.yaml ` and is saved in the ` configs ` directory. This is necessary for hydra initialization from the ` configs ` directory.
--phrases_config_name PHRASES_CONFIG_NAME
The name of the config file for reports to phrases conversion. We use the default config file but you can provide a custom config. Make sure the config follows
the same structure as ` configs/report_to_phrases.yaml ` and is saved in the ` configs ` directory. This is necessary for hydra initialization from the ` configs `
directory.
--output_dir OUTPUT_DIR
Path to the directory where the results will be saved as a json file.
--bootstrap_samples BOOTSTRAP_SAMPLES
Number of bootstrap samples to use for computing the confidence intervals. Set to 0 to disable bootstrapping. run_radfact --input_path < path_to_input_file.csv > --is_narrative_text run_radfact --input_path < path_to_input_file.json >入力ファイルの予期される形式については、 examplesディレクトリ内のサンプル入力ファイルを参照してください。入力ファイルは、根拠のないレポートの場合は CSV ファイルの形式である必要があります。
スクリプトはブートストラップを使用してメトリクスの信頼区間を計算します。ブートストラップ サンプルの数は、 --bootstrap_samples引数を使用して制御できます。デフォルト値は 500 です。ブートストラップを無効にするには、 --bootstrap_samples 0を設定します。
num_llm_failuresの下にそのようなスキップされたクエリの数が含まれています。スクリプトは、実行の最後にスキップされたクエリの数を出力し、実行 ID フォルダーの下のskippedディレクトリに保存します。また、失敗したクエリごとにログに警告メッセージが表示されます。 WARNING: No response for example {query_id}. Setting as NOT ENTAILED 。
レポートをフレーズに変換するスクリプトも提供します。これは、説明レポートがあり、それを RadFact 評価用のフレーズのリストに変換したい場合に便利です。このステップをオフラインで実行し、出力ファイルを RadFact への入力として使用できます。スクリプトを実行する前に、上記のようにエンドポイントが設定されていることを確認してください。 run_report_to_phrasesコマンドはpython src/radfact/cli/run_report_to_phrases.pyスクリプトを内部で実行します。
run_report_to_phrases dataset.csv_path= < your_path_to_cxr_reports >このスクリプトは、 report_to_phrases.yaml構成ファイルを使用して構成できます。変換に使用する入力ファイル、出力ファイル、およびエンドポイントを指定できます。
必要に応じて、RadFact はまずレポートを最大 1 つの発見事項を説明する個々の文に分割します。次に、大規模な言語モデルの論理推論機能を使用して、これらの文が参照レポートを考慮して論理的にサポートされる (「含意される」) かどうかを判断します。これを 2 つの方向で計算します。まず、グラウンド トゥルース (元の) レポートを参照として使用し、その逆に、モデルで生成されたレポートを参照として使用します。これにより、正確さと完全性の両方を定量化することができます。
全体として、RadFact は、(根拠のある) レポート品質の 6 つの尺度を提供します。
| メトリック | 意味 | それは私たちに何を教えてくれるでしょうか？ | 接地？ |
|---|---|---|---|
| 論理精度 | 生成された文のうち、グラウンド トゥルース レポートに伴う部分。 | モデルの世代がどれほど真実であるか: 不正確な世代にペナルティが課せられます。 | ❌ |
| 論理リコール | 生成されたレポートに含まれるグラウンド トゥルース センテンスの部分。 | 生成されたレポートがどの程度完全であるか。省略にはペナルティが課されます。 | ❌ |
| 接地精度 | 論理的に含意され、空間的に含意される、根拠のある生成文の一部。 | 正しく生成された結果が正しく根拠に基づいていることがどのくらいあるでしょうか? | ✔️ |
| 接地リコール | 論理的に含意され、空間的にも含意される、根拠のあるグラウンドトゥルースの文の一部。 | 正しく捉えられた結果が正しく根拠付けられていることがどのくらいあるでしょうか? | ✔️ |
| 空間精度 | すべての根拠に基づいて生成された文のうち、論理的および空間的両方を伴う部分。 | スコアが低い場合は、モデルが不必要なボックスまたは間違った文に対してボックスを生成したことを意味します。 | ✔️ |
| 空間想起 | すべての根拠のあるグラウンドトゥルース文のうち、論理的および空間的両方を伴う部分。 | スコアが低い場合は、モデルが参照内の所見に対するボックスの生成に失敗したことを意味します。これは、所見が間違って記述されているか、まったく記述されていない可能性があります。 | ✔️ |
空間的な {精度、再現率} は他の指標ほどすぐには解釈できませんが、グラウンディング {精度、再現率} に暗黙的に含まれる分母を制御するためにそれらを含めます。グラウンディングによって測定される、論理的に内包された文のボックスの品質のみを評価する場合{精度、再現率}、誤った文に関連する無関係なボックス（例、完全に捏造された所見）、または見逃した所見に関連する欠落したボックスに起因する接地不良は捕捉しません。
RadFact は LLM を 2 つのステップで使用します。どちらの場合も、約 10 個の数ショットのサンプルを使用します。
単方向含意検証 (ステップ 2 の一部) は次のように機能します。
これにより、すべての文を論理的に含意している (または含んでいないか) および空間的に含意している (または含んでいないか) としてラベル付けできるため、上記の RadFact メトリクスを計算できます。空間含意はボックスのある文に対してのみ定義されることに注意してください。
レポートを個々の文に変換するために、 FINDINGSセクションを使用して MIMIC-CXR レポートのスタイルで合成例を生成しました。オリジナルの MIMIC レポートは、再配布を禁止するデータ使用契約に基づいて保護されています。ナラティブレポートを手動で個々の文に分割します。例とシステム メッセージはllm_utils.report_to_phrases.promptsで確認できます。
含意を検証するために、少数のショットの例はプライベート データセット (「USMix」) から取得されます。各例には 2 つのレポートからの文が含まれており、tf-idf 統計を使用して類似しているが同一ではないものを選択しました。その後、コンサルタントの放射線科医と協力して、それらに関与ステータスと証拠を手動でラベル付けしました。論理的推論タスクであるにもかかわらず、含意検証には、特定の概念がどのように厳密に解釈されるかによって生じる、ある程度の主観性が存在します。したがって、これらの例のいくつかは異議を唱える可能性があります。例とシステム メッセージはllm_utils.nli.promptsで入手できます。
RadFact を引用するには、次を使用できます。
@article { Bannur2024MAIRA2GR ,
title = { MAIRA-2: Grounded Radiology Report Generation } ,
author = { Shruthi Bannur and Kenza Bouzid and Daniel C. Castro and Anton Schwaighofer and Sam Bond-Taylor and Maximilian Ilse and Fernando P'erez-Garc'ia and Valentina Salvatelli and Harshita Sharma and Felix Meissen and Mercy Prasanna Ranjit and Shaury Srivastav and Julia Gong and Fabian Falck and Ozan Oktay and Anja Thieme and Matthew P. Lungren and Maria T. A. Wetscherek and Javier Alvarez-Valle and Stephanie L. Hyland } ,
journal = { arXiv } ,
year = { 2024 } ,
volume = { abs/2406.04449 } ,
url = { https://arxiv.org/abs/2406.04449 }
}RadFact は研究用途のみに提供されています。 RadFact は、病気や病状の診断、予防、緩和、または治療に使用すること、または医療機能を実行するために設計、意図されておらず、また、そのような目的での RadFact のパフォーマンスは確立されていません。医療目的を目的とした製品への組み込みを含め、RadFact の使用についてはお客様が単独で責任を負います。
このプロジェクトは貢献と提案を歓迎します。ほとんどの投稿では、投稿を使用する権利をお客様が有しており、実際に当社に付与することを宣言する投稿者ライセンス契約 (CLA) に同意する必要があります。詳細については、https://cla.opensource.microsoft.com をご覧ください。
プル リクエストを送信すると、CLA ボットが CLA を提供する必要があるかどうかを自動的に判断し、PR を適切に装飾します (ステータス チェック、コメントなど)。ボットが提供する指示に従ってください。 CLA を使用するすべてのリポジトリでこれを 1 回行うだけで済みます。
このプロジェクトはマイクロソフトのオープンソース行動規範を採用しています。詳細については、「行動規範に関するよくある質問」を参照するか、追加の質問やコメントがあれば [email protected] までお問い合わせください。
このプロジェクトには、プロジェクト、製品、またはサービスの商標またはロゴが含まれている場合があります。 Microsoft の商標またはロゴの許可された使用には、Microsoft の商標およびブランド ガイドラインが適用され、それに従わなければなりません。このプロジェクトの修正バージョンで Microsoft の商標またはロゴを使用することは、混乱を引き起こしたり、Microsoft のスポンサーであることを暗示したりしてはなりません。第三者の商標またはロゴの使用には、それらの第三者のポリシーが適用されます。
