↓ メインコンテンツへスキップ

LLMOps:評価基盤の設計編 〜 Langfuse Academy と Langfuse v4 の活用

著者
Tomoyuki Kurosawa

こんにちは。ガオ株式会社の黒澤です。この記事は、2026年4月に公開した「LLMOps:評価基盤の設計編 — Langfuse 活用 」の手順を、Langfuse Academy(Langfuse 公式の学習コンテンツ)と Langfuse v4 に合わせて設計し直したものです。

評価基盤は、LLM アプリの回答を継続して採点する仕組みです。何を測るかは人が決め、採点の方法はコード・LLM・人から選びます。

評価基盤の作り方を、3 本の記事に分けて書きます。本記事(設計編)では、何を評価するかを決めるまでを扱います。業務を知る人が実際のトレース(アプリの処理の記録)を読んで問題を見つけ、何を継続して測るか(評価軸)を決め、評価軸ごとに測り方を選びます。

記事扱うこと
設計編(本記事)実トレースから問題を見つけ、評価軸と評価方法を決める
実装編(続編)評価用 LLM を Langfuse で設定し、人の判断どおりに採点できるかを確かめて、本番の自動採点に使う
検証事例編(続編)人と評価用 LLM の判定が食い違ったときに、何を確かめるか
flowchart TD
    subgraph S["設計編(本記事)"]
      direction LR
      A[A. 実トレースを読んで
問題を見つける] --> B[B. 評価軸を決める] --> C[C. 評価方法を決める] end subgraph I["実装編"] direction LR D[評価用 LLM を
Langfuse で設定する] --> E[人の判断どおりに
採点できるか確かめる] --> F[本番の自動採点に使う] end subgraph V["検証事例編"] direction LR G[人と評価用 LLM の判定が
食い違ったときに確かめること] end S --> I I -. 食い違ったとき .-> V

各工程には、社内規程を検索して答えるチャットボットを、想定される質問で動かして作ったデータ(合成データ)で試した例を添えています。

想定読者

  • LLM アプリの評価基盤をこれから設計する方
  • LLM-as-a-Judge を導入済みで、何を測るかを見直したい方

Langfuse でトレースを取っていて、Trace や Observation の画面を見たことがある方を前提にします。

この記事でわかること

  • 実トレースから問題を見つけ、評価軸を決める手順
  • 評価軸ごとに、コード・評価用 LLM・人のどれで測るかの選び方
  • 各工程で人が決めること

評価の方法について
#

LLMの評価
#

LLM に採点させる方法を LLM-as-a-Judge と呼び、LLM-as-a-Judge で使う LLM を、以下では評価用 LLM と書きます。評価用 LLM は、人が決めた基準どおりに採点できるかを人の判断と比べて確かめてから使います。

人の評価
#

人がトレースを読んで PASS/FAIL やコメントを付ける作業は、Langfuse の Human Annotation(人がトレースにスコアやコメントを付ける機能)で行います。メモの分類の下書きや集計は、Langfuse の Assistant(画面に組み込まれたアシスタント)やコーディングエージェント(Claude Code など)に任せられます。トレースを読むことと、何を測るかを決めることは人が行います。


用語
#

用語意味
失敗カテゴリトレースを読んで書いたメモを、根本原因が同じものどうしでまとめたもの
判定基準どのような回答を PASS、どのような回答を FAIL とするかの基準
Annotation Queue人が採点する Trace・Observation・Session を入れておくキュー。サイドバーの Evaluation にある Human Annotation から作り、入れた順に採点する
Score Config人が付けるスコアの名前・型(Text、Categorical、Boolean など)・説明の定義。PASS/FAIL は Categorical の選択肢として作る。キューを作るときに選ぶ

前提
#

  • 扱わないこと:運用設計、Langfuse Cloud 固有の機能、v3 からの移行
  • 検証環境:Langfuse セルフホスト v4.45.1。手順に書いた画面の名前と操作も、この版のもの
  • Assistant は、セルフホストでは v4.28.0 以降の public beta で、インスタンス側の設定が要る(Langfuse Assistant (self-hosted) )

手順について
#

工程もとにしたもの
A・B. 実トレースを読み、評価軸を決めるAcademy の エラー分析 ・何を評価するかを選ぶ 、Langfuse の Error Analysis のガイド
C. 評価方法を決めるAcademy の 良い評価器の書き方

A と B は、番号付きの手順と、例(今回の検証で行ったこと)の順に書きます。理由・注意・出典は、関係する手順の下に書きます。これらの資料の手順に筆者が足したのは、次の 3 つです。

  • トレースを読む前に、アプリの業務の目的と、守るべき制約を確かめる(A)
  • 自分ならどう答えるかを考えてから、アプリの回答を読む(A)
  • 評価軸ごとに、判定基準の下書きを言葉で書いておく(B)

設計フロー
#

flowchart TD
    A[A. 実トレースを読んで
問題を見つける] --> B[B. 失敗カテゴリにまとめ
評価軸の候補を出す] B -- 直せば済む問題 --> X[プロンプト・ツール・
コードなどを直す] X -. 無視できない失敗が残り
測る価値があれば評価軸に
(安全性などは常に評価軸に) .-> C B -- 当面は様子を見る問題 --> W[様子を見る] W -. 新しいトレースを
読んで決め直す .-> A B -- 評価軸にする問題 --> C[C. 評価方法を決める] C -- コード評価・人で測る評価軸 --> Y[それぞれの方法で用意する] C -- 評価用 LLM で測る評価軸 --> Z[評価用 LLM を作って確かめる
(実装編)]

A. 実トレースを読んで問題を見つける
#

業務を知る人が実トレースを読み、気づいたことを、決まった分類を使わずにメモします(open coding)。Langfuse の Error Analysis のガイドでは、このメモを Annotation Queue に書きます。

  1. アプリの業務の目的と、守るべき制約を、Prompt Management(Langfuse のプロンプト管理機能)にあるシステムプロンプトで確かめる
    • 確かめた目的と制約を、何を問題とみなすかの基準にする
      • プロンプトだけでは目的や制約が不明瞭な場合は、業務の担当者に聞く
  2. Settings の Scores Configs で、Add new score config から Score Config を 2 つ作る
    • 回答全体の判断用:Data type を CATEGORICAL にし、カテゴリに FAIL と PASS を作る。この PASS/FAIL は、判定基準を決める前の、読んだ人の大まかな判断。
    • メモ用:Data type を TEXT にする
  3. Tracing の一覧で、キューに入れるトレースを約 100 件選ぶ(件数は Error Analysis のガイドの目安)。
    • フィルターの期間と絞り込みで、全件がおよそ 100 件になるようにする。期間は、B で同じ件を選び直せるように、右上の表示期間の Select from calendar で日付を指定する。境界のケースや、すでに問題が指摘されたものを多めにしたいときは、絞り込みで調整する。うまくいったものも入れる
    • 本番のトレースがまだないときは、想定される質問(合成データ)でアプリを動かしてトレースを取り、そこから選ぶ(Error Analysis のガイド)。
  4. Human Annotation の New queue でキューを作り、A の手順 2 の Score Config を 2 つとも選ぶ。そのあと、3 で選んだ行にチェックを入れ、画面の下に出る Add to Annotation Queue でキューに入れる
    • 一覧の 1 行は Observation で、初期状態では、ルートの Observation(処理全体の入口)だけが並ぶ。最終回答が別の Observation(最終回答を生成した LLM 呼び出しなど)にしか入っていないアプリでは、その Observation を選ぶ(Error Analysis のガイド)。そのときは、Is Root Observation の絞り込みを外す
  5. Human Annotation でキューを開き、Process queue で 1 件ずつ読む。画面には質問(Input)と回答(Output)が並んで出るので、回答を読む前に、質問だけを読んで自分ならどう答えるかを考える。見えた振る舞いと、どうなっていれば許容できたかをメモ用の欄に書き、PASS/FAIL を選んで Mark Completed を押す。問題がなければ、メモは書かずに PASS を選ぶ
    • 検索結果など、ルート以外の Observation の中身は、左上のボタンでツリーを開き、子の Observation(この例では検索ツールの kb-search)を選ぶと、同じ画面で見られる
    • メモするのは見えた振る舞いだけで、原因の推測とまとめは B で行う
  6. まず 30〜50 件を読み、そのあとも読み進める。直近 20 件で、それまでになかった種類の失敗が 1 つも出なかったら止める(種類は読んでいる人が判断する。件数は Error Analysis のガイドの目安)

社内チャットボットの例:「4万9千円のヘッドセットは部門の予算で買えますか?」という質問に、検索結果は廃止された備品購入規程(2023年版)だけで、アプリは推測では回答できないと答え、「総務部などの担当窓口」への確認を勧めました。自分の答えを先に考えてから読むと、利用者が知りたい「部門の予算で買えるか」に答えていないことが分かり、そのとおりにメモしました。「回答が検索結果に基づいているか」だけを測っても、質問に答えていない問題は捉えられません。評価軸を先に決めてからトレースを読むと、こうした問題を見落とすことがあります。

Annotation Queue で、ヘッドセットの例にメモと PASS/FAIL を付けた画面
Annotation Queue で、ヘッドセットの例にメモと PASS/FAIL を付けた画面


B. 評価軸の候補を出す
#

A のメモを失敗カテゴリにまとめ、何を測るかを決めます。1〜6 は Error Analysis のガイドの手順、7 はガイドの「直したあとは様子を見る」「大きな変更のあとはエラー分析をやり直す」にならったもの、8 は筆者が足した手順です。

  1. Aのメモを、根本原因が同じものどうしでまとめ、失敗カテゴリごとに名前と 1 文の定義を付ける
    • 下書きは、コーディングエージェントや Assistant に頼める。コーディングエージェントには、Langfuse の API(/api/public/v3/scores)で、A のメモ用の Score Config の名前を指定してメモを取り出させる
    • Error Analysis のガイドによると、LLM は見た目が似たメモを 1 つにまとめがちなので、原因の違うメモが混ざっていないかを人が確かめる
  2. 失敗カテゴリごとに、Settings の Scores Configs で、Data type が BOOLEAN の Score Config を作る
    • True が「当てはまる」、False が「当てはまらない」。説明に、手順 1 で付けた定義を書く
    • 名前は、今回の分析専用のものにする。手順 5 で、この名前のスコアだけに絞って集計するため
  3. Human Annotation の New queue で、A の手順 2 の Score Config 2 つと、B の手順 2 の Score Config を選んだキューを新しく作る
    • 注意:A のキューに Score Config を足すこともできるが、A で完了にした件は Process queue で順に回せない(「All queue items processed」と出る)。新しいキューなら、全件が未完了として並ぶ
  4. A と同じ件を、Tracing の一覧で A と同じ期間(日付)と絞り込みで選び、3 のキューに入れる。Process queue で 1 件ずつ、当てはまる失敗カテゴリに True、当てはまらないものに False を付ける
    • キューの全件に付ける。A で読まずに止めた分も、ここで読む(Error Analysis のガイドの手順)
    • A で付けたメモと PASS/FAIL も、同じ画面に表示される
    • True/False は、コーディングエージェントに案を作らせてもよい。A のメモと PASS/FAIL を Langfuse の API で取り出させて案を作らせ、人が確かめてから、API でスコアとして登録させる。A で読まずに止めた分はメモがないので、人が読んで付ける(Error Analysis のガイドの「Run with your agent」でも、業務の判断は人が行う)
  5. Dashboards でダッシュボードを開き、Add Widget の Custom Chart で、カテゴリごとの割合を表示する
    • View を Scores Boolean、Metric を Value(集計は Avg)、Breakdown Dimension を Name、Chart Type を Horizontal Bar Chart にし、Filters で Name を手順 2 の名前に絞る。絞らないと、同じ期間に付けた別の 2 値のスコアも集計される。2 値のスコアの平均は、4 で付けた件数のうち、True を付けた件数の割合になる
    • ウィジェットの表示期間を、4 で失敗カテゴリを付けた日を含む期間にする。グラフは、トレースの日付ではなく、スコアを付けた日で集計される
    • 注意:問題のあるものを多めに選んだので、この割合は本番での発生率ではない。優先度は、業務への影響も合わせて決める
  6. 失敗カテゴリごとに、割合の高いものから順に、次の 2 つを順番に問う(Error Analysis のガイド)
    • ただ直せば済むか:根本原因が次のどれかなら、評価軸にせず直す。プロンプトで直せるものは、評価軸を作る前に直す(安全性・コンプライアンスは除く。C を参照)
      • プロンプトに要件が書かれていない → 指示を足す
      • 指示どうしが矛盾している → 矛盾を解消し、優先順位をはっきりさせる
      • ツールがない、または設定が誤っている → ツールを足す、直す
      • プログラムのバグ → コードを直す
    • 評価軸で測る価値があるか:直せないもの、または直したあとも業務上無視できない失敗が残ったもの(手順 7 で確かめる)について、割合は問題になるほど高いか、起きたときの業務への影響は何か、その評価軸を見て改善し続ける人がいるかを問う。価値がない、または決めきれないものは、当面は様子を見て、トレースをさらに読んでから決め直す
    • ※2 つの問いとは別に、まだ起きていない失敗は、コンプライアンスや安全性など、最初から分かっている要件だけを評価軸の候補に足す(Academy)
  7. 「直す」にしたものは、直したあとのアプリに、直す前と同じ質問セットを流し、同じ判定基準で割合を出し直して比べる。LLM の出力は毎回同じとは限らないので、1 件ずつではなく割合で見る。業務上無視できない失敗が残っていれば、手順 6 の 2 つ目の問いに戻る
    • ※プロンプトの書き直し、モデルの切り替え、新機能の追加など大きな変更を加えたときは、A と B をやり直す(Error Analysis のガイド)
  8. 評価軸ごとに、「推測で答えていないか」のような問いと、PASS と FAIL の境目(判定基準の下書き)のメモを控える
    • 性質の違う問題は、別の評価軸にする。1 つの評価軸は 1 つの判定基準で判定するため。例えば「回答に根拠があるか」と「言葉遣いが適切か」は分ける
    • 質問・検索結果・回答を見て、1 つの判定基準で判定できる問題どうしは、1 つの評価軸にまとめてよい

社内チャットボットの例:A で読んだ 20 件を使いました(手順を示すため、A の手順 6 の 30〜50 件より少ない件数で止めています)。

  1. 分類案を作る(手順 1):20 件のうち、メモを付けた 13 件(残りの 7 件は問題がなく、メモを付けていません)を Assistant に分類させました。Assistant は「一般論の出力」(7 件)と「根拠のない部署の案内」(4 件)の 2 つに分け、残りの 2 件を「未分類」にしました。

    Assistant に A のメモの分類を頼んだ画面
    Assistant に A のメモの分類を頼んだ画面

  2. 人が直す(手順 1):未分類の 2 件を読んで、次のように直しました。

    • ヘッドセットのメモ(「廃止の規程しか検索で出てこず、部門予算で買えるかに答えていない。…検索結果にない『総務部』を案内している。」)は、2 つの問題を挙げています。検索結果(kb-search)を見直すと、廃止された備品購入規程に「総務部の承認が必要」と書かれていて、総務部の案内には根拠がありました。A では検索結果を開かず、回答に書かれた「検索結果にある『備品購入規程 2023年版』は【廃止】」だけを読んでメモしていたので、メモの総務部についての指摘は誤りでした。そのため、部門の予算で買えるかに答えていない点だけを、新しい失敗カテゴリ「質問への未回答」にしました

      ヘッドセットの例で、ツリーから kb-search を選び、検索結果を表示した画面
      ヘッドセットの例で、ツリーから kb-search を選び、検索結果を表示した画面

    • もう 1 件(「RAGにはないが、良い感じの回答をしてくれている。知らないSaaSや部署の案内をしていない。」)は、良い回答へのメモでしたが、回答を読み直すと、この件の検索結果(廃止された休暇規程)にない「人事部・総務部等の担当窓口」を案内していました。A のメモで見落としていたので、「根拠のない部署の案内」に入れました

  3. 割合を出す(手順 2〜5):失敗カテゴリが 3 つにそろってから、それぞれの Score Config(cat-guess・cat-dept・cat-unanswered)を作り、20 件すべてに、3 つのカテゴリの定義でそれぞれ True/False を付けました。True/False は、コーディングエージェント(Claude Code)に A のメモと PASS/FAIL から案を作らせ、筆者が確かめてから、Langfuse の API で登録させました。ダッシュボードのウィジェットで、カテゴリごとの割合を表示しました。

    Dashboards のウィジェットで、失敗カテゴリごとの割合を表示した画面
    Dashboards のウィジェットで、失敗カテゴリごとの割合を表示した画面

  4. どうするか決める(手順 6〜8)

失敗カテゴリ20 件中判断評価軸にする場合の判定基準
一般論の出力7 件(35%)直す(検索ツールを必ず呼ぶ)。直したあとも業務上無視できない失敗が残り、測り続ける価値があれば評価軸にする(手順 7)一般論で答えていないか:検索結果に基づかず、一般的な知識で答えていたら FAIL
根拠のない部署の案内5 件(25%)直す(廃止された規程しか見つからないときに、検索結果にない部署や窓口を案内しないよう、プロンプトに指示を足す)。直したあとも業務上無視できない失敗が残り、測り続ける価値があれば評価軸にする(手順 7)検索結果にない部署や窓口を案内していないか:案内していたら FAIL
質問への未回答1 件(5%)直す(検索する規程の範囲と、規程を廃止したときに後継の規程を示す振る舞い)—

C. 評価方法を決める
#

評価軸ごとに評価方法を選びます。先に、判定に必要な情報がトレースなどから得られるかを確かめます。そのうえで、まずコードで判定できないかを見ます(Academy「良い評価器の書き方」)。

評価方法使う場面例
コード評価機械的に判定できるもの文字列の有無、JSON 形式、ツール呼び出しの有無、期待する値との一致
LLM-as-a-Judge意味の理解が必要なもの検索結果にない内容を述べていないか
Human Annotation自動では判定できないもの、件数が少なく重要なもの本番の回答を定期的に抜き出し、Annotation Queue で人が継続して採点する

安全性やコンプライアンスに関わる失敗は、B の手順 6 でプロンプトを直したものでも、評価軸にして測り続けます(Error Analysis のガイド)。

評価用 LLM で測る評価軸は、人の判定と評価用 LLM の判定が一致することを確かめてから使います。手順は実装編で扱います。

社内チャットボットの例:B で直すことにした失敗のうち、判定基準を書いた 2 つは、直したあとも業務上無視できない失敗が残り、測り続ける価値があれば評価軸にします。その場合の評価方法は次のとおりです。

評価軸評価方法理由
一般論で答えていないかLLM-as-a-Judge回答が検索結果に基づいているかは、意味を理解しないと判定できない
検索結果にない部署や窓口を案内していないかLLM-as-a-Judge回答に出てくる部署が検索結果にあるかは、言い換えも含めて読まないと判定できない

どちらも、評価用 LLM には質問と回答に加えて検索結果も渡します。検索結果を渡さないと、回答の内容が規程に書かれているかを評価用 LLM が確かめられないためです。


まとめ
#

本記事では、評価基盤の設計のうち、何を測るかを決めるまでを、次の順で進めました。

  1. 業務を知る人が、Annotation Queue で実トレースを読んでメモする(A)
  2. メモを失敗カテゴリにまとめて数え、直すもの・評価軸で測るもの・当面は様子を見るものに分ける(B)
  3. 評価軸ごとに、コード・評価用 LLM・人のどれで測るかを決める(C)

何を測るかは、人がトレースを読んで決めます。Assistant やコーディングエージェントは、分類の下書きと集計を手伝います。Assistant は Langfuse v4 の beta 機能で、本記事では失敗カテゴリの分類の下書きに使いました。

次回は、評価用 LLM の設定と精度の確かめ方として実装編を記述します。


参考
#