LLM統合コードの品質を損なう5つの「悪習慣」

本記事では、LLMをソフトウェアシステムに組み込む際に問題となりやすい五つの「コードスメル」を検出する方法を紹介します。

LLMのAPIを自社のサービスに取り入れる企業が急速に増えていますが、LLMは使い方によって振る舞いが大きく変わるため、コードの書き方を誤ると、システムの保守性や信頼性を損ねてしまうおそれがあります。

背景

ここ数年でLLMは急速に広まり、私たちの日常生活や仕事の進め方に大きな影響を与えるようになりました。それに合わせて、LLMのAPIを自社のソフトウェアシステムに組み込み、実際の業務で活用する企業も増えています。

ただし、LLMは何にでも使える万能な存在ではありません。同じモデルを利用していても、呼び出し方や設定の違いによって、出力の質や安定性が大きく変わることがあります。そのため、LLMをシステムに組み込む際にコードの書き方を誤ると、保守しにくくなったり、信頼性が下がったりするリスクが生じます。

ここで重要になるのが「コードスメル」という考え方です。コードスメルとは、ソフトウェア開発の分野で使われる言葉で、すぐにバグを引き起こすわけではないものの、そのままにしておくとシステムの品質を徐々に悪化させてしまうような、好ましくない書き方や習慣を指します。たとえば、同じ処理を何度もコピーして使っているコードは、修正が必要になったときに見落としが起きやすく、典型的なコードスメルの例とされています。
コードスメルという考え方そのものは従来のソフトウェア開発では広く知られており、機械学習の分野でも似たような問題パターンが整理されてきました。しかし、LLMをシステムに組み込む場合に特有の「悪い習慣」については、これまで十分に体系化されていません。

そこで本記事では、LLMを統合する際に陥りがちな「悪い習慣」を整理した事例をもとに、体系的にまとめました。実際に200件のオープンソースプロジェクトが調査された結果、6割以上のシステムで何らかの問題パターンが確認されています。

LLMのAPIを使った開発に関わる人にとって、自分のコードを見直すための実践的なチェックリストとして参考になる内容を目指します。

5つのLLMコードスメル

まず研究者らは、LLMをシステムに組み込む際に起こりやすい五つのコードスメルを定義しています。対象はPythonコードですが、考え方そのものは他のプログラミング言語にも当てはめることができます。それぞれの内容を順に見ていきます。

LLMコードスメル①　上限値が設定されていない

OpenAIやAnthropicなどが提供するLLMのAPIには、1回のリクエストで処理できるトークン数や、一定時間内に送信できるリクエスト数に制限があります。（トークンとは、LLMがテキストを扱う際の最小単位で、単語や文字のまとまりのようなもの）

このコードスメルは、API呼び出し時に出力トークン数の上限やタイムアウト時間、リトライ回数といった設定を明示していない場合を指します。こうした設定がないと、応答が途中で途切れたり、リクエストが長時間返ってこなかったり、想定外の利用料金が発生したりする可能性があります。また、API提供側がデフォルト値を変更した場合、気づかないうちにシステムの挙動が変わってしまうおそれもあります。

対策としては、max_output_tokensやtimeout、max_retriesなどのパラメータを必ず明示的に指定し、入力トークン数もあわせて管理することが推奨されています。

LLMコードスメル②　モデルバージョンが固定されていない

OpenAIなどのAPIでは、モデル指定に「gpt-4o」のような汎用的な名前を使う方法と、「gpt-4o-2024-11-20」のように特定のバージョンを明示する方法があります。汎用名は手軽ですが、モデルが更新されると、同じ名前でも中身が変わってしまうことがあります。

このコードスメルは、こうしたエイリアス名だけでモデルを指定しているケースを指します。その結果、ある日突然出力の品質が変わったり、安全に関する挙動が変化したりする可能性があります。また、過去の実行結果を再現できなくなり、デバッグや品質管理が難しくなるという問題も生じます。

対策としては、常にバージョン番号付きのモデル識別子を使用し、モデルを切り替える場合には、変更内容を管理するプロセスをきちんと踏むことが望ましいとされています。

LLMコードスメル③　システムメッセージが省略されていない

ChatGPTのような対話型のAPIでは、「システムメッセージ」と呼ばれる特別な指示を設定できます。LLMに対して役割や基本的なルールを与え、どのような方針で回答すべきかを定めるためのものです。

このコードスメルは、システムメッセージを設定せずにAPIを利用している場合を指します。システムメッセージがないと、LLMは全体的な指針を持たないまま応答を生成するため、出力の一貫性が下がり、守ってほしい制約を徹底させることが難しくなります。その結果、期待通りの回答を得るために、余分なやり取りや長いプロンプトが必要になることがあります。

対策としては、役割や目的、制約条件を明確にしたシステムメッセージを必ず設定し、タスク固有の細かい指示はユーザーメッセージ側に書く、という役割分担が推奨されています。

LLMコードスメル④　構造化出力が使われていない

LLMを組み込んだシステムでは、出力結果をそのまま表示するだけでなく、プログラムで処理するケースが多くあります。たとえば、LLMに情報を抽出させてデータベースに保存したり、次の処理に引き渡したりする場合です。このような場面では、JSONなど決まった形式での出力が求められます。

このコードスメルは、構造化されたデータが必要にもかかわらず、LLMに自由形式のテキストを出力させているケースを指します。LLMは指示通りの形式を守らないことがあり、項目が抜け落ちたり、型が異なったり、出力が途中で切れたりすることがあります。その結果、後続処理でエラーが起きたり、不正なデータが蓄積されたりするリスクが高まります。

対策としては、APIの機能を利用してJSONスキーマなどを強制し、得られた出力を必ず検証することが推奨されています。たとえばOpenAIのAPIでは、response_formatパラメータを使ってJSON形式を指定できます。

LLMコードスメル⑤　temperatureが明示されていない

LLMのAPIには、temperatureと呼ばれるパラメータがあります。これは出力のばらつきを制御するもので、値が低いほど安定した決定論的な出力になり、値が高いほど多様で創造的な出力になります。

このコードスメルは、temperatureを明示せず、デフォルト設定に任せているケースを指します。問題となるのは、このデフォルト値がプロバイダーやモデルごとに異なり、将来的に変更される可能性がある点です。その結果、同じコードでも環境によって挙動が変わったり、ある時点を境に出力の傾向が変化したりすることがあります。

対策としては、temperatureを常に明示的に指定し、その値をドキュメントに残しておくことが推奨されています。一般には、正確さや再現性が求められるタスクでは0から0.3程度の低い値を、文章生成など創造性を重視する場合には0.7から1.0程度の高い値を使うことが多いとされています。

調査の進め方

研究者らは、上記コードスメルを自動的に検出するツールであるSpecDetect4LLMを開発しています。
そのツールを用いて200件のオープンソースプロジェクトを調査し、コードスメルの普及状況を分析しました。

検出ツールSpecDetect4LLMについて

SpecDetect4LLMは、既存のオープンソースツールであるSpecDetect4AIを拡張する形で作られた静的解析ツールです。静的解析とは、プログラムを実際に動かさずにソースコードそのものを調べる方法で、自動化されたコードレビューに近いものと考えるとわかりやすいです。GitHub上で公開されており、Dockerを使って動かせるWebアプリ版と、コマンドラインから利用できる版の両方が提供されています。

調査対象のデータセット

調査では、LLMを組み込んだ200件のプロジェクトを対象としました。内訳は、GitHub APIを用いて「openai」や「llama」といったキーワードで検索し抽出したPythonプロジェクト100件と、先行研究で使われていた代表的なプロジェクト100件です。比較的新しく活発に開発されているものと、広く利用されている定番のプロジェクトの両方を調査対象に含めています。

精度の検証

ツールによる検出結果が正確かどうかは、人の目によって確認されています。各コードスメルについて少なくとも20件以上の検出例を抽出し、それが本当にコードスメルに該当するかを判断することで、検出精度を評価しました。

60%以上のプロジェクトで問題を検出

開発したSpecDetect4LLMを200件のプロジェクトに適用したところ、合計で6,337件のコードスメルが検出されました。その結果、全体の60.50%にあたる121プロジェクトで、何らかの問題が確認されています。

構造化出力の未使用が最も多くのプロジェクトに蔓延

次に、五種類のコードスメルがそれぞれどの程度見つかったのかを確認します。

最も多くのプロジェクトで検出されたのは、構造化出力が使われていない問題で、200件中81件、割合にして40.50%でした。続いて、上限値が設定されていない問題が38.00%、temperatureが明示されていない問題が36.50%、モデルバージョンが固定されていない問題が36.00%、システムメッセージが省略されている問題が34.50%という結果になっています。

「深く根付く」問題と「広く拡散する」問題に二極化

調査結果を詳しく見ると、いくつか注目すべき特徴が見えてきます。

まず目立つのが、モデルバージョンの未固定の検出のされ方です。検出件数は2,472件と最も多かったものの、影響を受けたプロジェクトは72件に限られていました。これは、「gpt-4o」のようなエイリアス名を一度使い始めると、同じ指定方法がプロジェクト内のさまざまな箇所で繰り返されるためだと考えられます。このタイプの問題は、少数のプロジェクトに深く入り込む傾向があるといえるでしょう。

これとは対照的なのが、構造化出力の未使用と上限値の未設定です。これらは検出件数自体は特別多いわけではありませんが、問題が見つかったプロジェクト数は最も多くなっています。スキーマの設計やパラメータの明示的な指定といった追加作業が必要になるため、対応が後回しにされやすいのかもしれません。結果として、問題が多くのプロジェクトに広く行き渡っている状態になっていると考えられます。

また、システムメッセージの省略は、検出件数が480件と最少でしたが、問題が確認された121プロジェクトのうち半数以上で見つかっています。まずはAPIをつなぐことを優先し、プロンプトの設計は後から検討するという開発の進め方が、この結果からうかがえます。

検出精度は平均86%で実用的な水準

人手による検証の結果、検出精度の平均は86.06%でした。内訳を見ると、モデルバージョンの未固定が95.65%と最も高く、次いで上限値の未設定が86.36%、システムメッセージの省略が85.71%、temperatureの未設定が82.61%、構造化出力の未使用が80.00%となっています。

一部で誤検出が生じた理由としては、SpecDetect4LLMが静的解析ツールであるため、実行時の状態や文脈に依存する判断ができない点が挙げられます。それでも全体として8割を超える精度が確認されており、検出結果は単なるノイズではなく、実際の問題を適切に捉えていると評価できます。

開発初期の規約整備と設計段階からの考慮が鍵

異常の調査結果から、LLMを組み込んだシステムの品質を高めるための示唆が得られます。

モデルバージョンやtemperatureといった設定に関する問題は、一度望ましくない書き方が定着すると、プロジェクト全体に広がりやすい傾向があります。そのため、開発の初期段階でコーディング規約を整備しておくことが有効だと考えられます。

一方で、構造化出力や上限値の設定のように、ある程度の設計や実装作業を伴う対策は、多くのプロジェクトで不足していることがわかりました。これらは後から手を入れようとすると、大規模な修正が必要になりがちです。だからこそ、システム設計の段階から意識して取り入れておくことが重要だといえるでしょう。

まとめ

本記事では、LLMをシステムに組み込む際に注意すべき五つのコードスメルを整理し、それらを検出する研究の内容を紹介しました。

モデルバージョンを固定していないことや、temperatureを明示していないことは、すぐに不具合を引き起こすわけではありません。しかし、長期的にはシステムの保守性や結果の再現性を損なう要因になります。実際に200件のオープンソースプロジェクトを調査したところ、6割を超えるプロジェクトで何らかのコードスメルが見つかっており、こうした問題が決して一部に限られたものではないことが示されました。