Craft RAG 実践ガイド

このページでは、Craft RAGを使ったシステムを設計・評価・改善・運用する際の実践知を説明します。

内容は、次の3つに分かれています。

Part 1｜設計・改善ナレッジ：RAGをどのように考え、何を評価するか
Part 2｜運用オペレーション：導入前後に、誰が・いつ・何を確認して改善するか
Part 3｜Craft RAG実装リファレンス：設計・評価の考え方をCraft RAGの機能へどのように対応させるか

Part 1｜設計・改善ナレッジ

検索性能、回答生成、ナレッジ整備、評価方法に関する考え方と判断基準を説明します。

1. RAGの品質を分解して考える

RAGの最終的な品質は、主に次の2つの要素で決まります。

必要な情報を検索できるか × 取得した情報に基づき、Ground Truthで定義した内容と表現で回答を生成できるか

期待した回答が得られない場合は、次の順番で原因を確認します。

回答に必要な情報がナレッジに存在するか
検索結果に必要な情報が含まれているか
取得した情報を生成AIが正しく解釈しているか
期待する形式や表現で回答しているか

必要な情報を検索できていない状態では、回答生成用のプロンプトだけを調整しても改善しません。検索結果と最終回答を分けて評価します。

2. Ground Truthを作成する

評価を始める前に、質問に対する期待回答と根拠をまとめたGround Truthを作成します。

項目	内容
想定質問	実際にユーザーが入力すると想定される質問
期待回答	回答に含める必要がある情報
根拠ナレッジ	期待回答を導くために必要なファイルや記述
回答不可条件	情報が不足している場合に断定してはいけない範囲
期待する表現	回答の長さ、語彙、トーン、案内順序
評価結果	正解、一部正解、不正解と、その理由

リリース前は、代表的な質問だけでなく、回答せずに聞き返したり、有人対応へ切り替えたりするべき質問も用意します。リリース後は、低評価や未解決となった実際の質問を追加します。

3. 検索の評価：必要な情報を取得できているか

検索側で最初に確認する指標がRecallです。Recallは、回答に必要な情報のうち、検索結果に含まれていた情報の割合を示します。

Recall ＝検索結果に含まれる必要情報 ÷ 回答に必要な情報

たとえば、回答に必要な情報が3つあり、検索結果に2つ含まれていた場合、Recallは約67%です。

評価するときは、文書、チャンク、事実など、何を情報の1単位として数えるかを固定します。また、取得件数によって結果が変わるため、比較するときは同じ取得件数にそろえます。

Recallが低い場合は、主に次の項目を見直します。

取得件数
ナレッジの言葉や文書の分け方
検索用の質問文
検索条件
キーワード検索やRerankとの組み合わせ

初期段階では、不要な情報を多少含んでいても、回答に必要な情報を取得できる状態を優先します。

4. 検索の評価：不要な情報を減らせているか

必要な情報を取得できる状態を作った後は、Precisionを確認します。Precisionは、検索結果のうち、回答に必要な情報が占める割合です。

Precision ＝検索結果に含まれる必要情報 ÷ 取得した情報の総数

たとえば、検索結果が5つあり、そのうち必要な情報が2つの場合、Precisionは40%です。

検索結果を増やすと必要な情報を取得しやすくなる一方で、次の問題が発生しやすくなります。

入力トークン数が増える
応答が遅くなる
費用が増える
無関係な情報が回答に影響する
矛盾する情報を取得しやすくなる

必要な情報を取得できる状態を作った後で、不要な情報を減らします。RecallとPrecisionだけでなく、回答の正しさ、応答時間、費用も同じ条件で比較します。

5. 小規模なナレッジでは広い取得をベースラインにする

ナレッジ量が少ない段階では、複雑な検索条件を設定する前に、全件または広い範囲を取得する構成も比較対象にします。

広い範囲を取得し、必要な情報を取りこぼさない状態を作る
ナレッジ量が増えたら、検索条件やRerankを比較する
トークン数、応答時間、費用、情報の競合状態を計測する
同じGround Truthで変更前後を評価する

特定の件数を一律の基準にはせず、1件あたりの文字数、更新頻度、応答時間、費用を計測して判断します。

6. 検索条件の必要性を検証する

検索対象を絞り込む条件は、次のような場合に有効です。

テナント、契約プラン、権限など、混在させてはいけない境界がある
同じ言葉が異なる業務領域で使われている
ナレッジ量が多く、広い範囲の取得が現実的ではない
質問から検索対象を高い精度で判定できる

一方、質問が複数のカテゴリにまたがる場合や、カテゴリ判定を誤る可能性がある場合は、必要な情報を検索対象外にするおそれがあります。同じGround Truthを使い、検索条件の有無を比較します。

テナントや権限の境界は、検索精度の調整とは分けて扱います。生成AIによるカテゴリ判定や任意の検索条件だけに依存せず、認証済みユーザーの権限に基づいて、アプリケーションやデータストア側でアクセス可能な範囲を制限してください。

7. ナレッジを改善する

検索方式だけでなく、検索対象となるナレッジの品質も回答精度に影響します。

1つのファイルやレコードに複数の論点を詰め込まない
ユーザーが質問に使う言葉と、正式な用語の両方を含める
結論、条件、例外、手順、問い合わせ先を分ける
古い情報や重複する情報を削除する
回答してよい範囲と、断定してはいけない範囲を明示する
URLだけでなく、そのリンク先を案内する条件も記載する
更新担当者と更新日を管理する

8. システムプロンプトは回答の加工に使う

システムプロンプトには、検索対象となる事実ではなく、回答方法のルールを設定します。

対象ユーザー
回答の順序、長さ、語彙、文体
不明な場合に断定しないルール
回答対象外の範囲
問い合わせ窓口へ案内する条件
MarkdownやHTMLの使用可否

基本的には、回答のルールはシステムプロンプト、回答の根拠となる事実はナレッジに分けます。検索できなかった事実をシステムプロンプトに追加して補うと、情報の更新や評価が難しくなります。

最終回答は、正解か不正解かだけでなく、次の観点を分けて確認します。

観点	確認内容
Faithfulness	回答内の主張が、取得した根拠に基づいているか
Answer Relevance	ユーザーの質問に直接回答しているか
Context Relevance	取得した情報が、回答に必要な内容へ絞られているか

自動評価を利用する場合も、評価用のプロンプトやモデルによって結果が変わります。定期的に人による評価と比較してください。

Part 2｜運用オペレーション

RAGを継続的に改善するための作業、役割、実施タイミングを説明します。

1. 評価と改善を継続運用にする

リリース前後で、次のサイクルを繰り返します。

想定質問とGround Truthを作成する
RAGへ質問する
検索結果と最終回答を分けて評価する
エラーの原因を分類する
原因に対応する箇所だけを修正する
既存の評価ケースをすべて再実行する
低評価や未解決となった質問をGround Truthへ追加する

症状	主な改善対象
正解となる情報が登録されていない	ナレッジの追加
登録済みだが検索されない	文書の分け方、検索条件、Recall
情報は取得できたが誤った回答になる	システムプロンプト、矛盾する情報、モデル
内容は正しいが読みにくい	システムプロンプト、UI
情報が不足しているのに断定する	回答不可条件、問い合わせ導線
実際の利用者の期待とずれる	Ground Truth、フィードバックの収集方法

2. UIに評価ループを組み込む

実際の質問と回答を継続的な改善へ利用するため、UIに次の仕組みを用意します。

「解決した／解決しなかった」の評価
自由記述によるフィードバック
有人問い合わせへの導線
参照した根拠ページの表示
未解決となった質問を運用担当者へ通知する仕組み
質問、回答、評価結果の保存

3. 運用体制を決める

初期構築だけでなく、リリース後の改善を誰が担当するか決めます。

役割	主な担当
業務担当者	Ground Truth、業務上の正解、回答不可条件、ナレッジの更新
構築担当者	検索、システムプロンプト、UIの実装、エラー原因の分析
運用担当者	低評価や未解決となった質問の収集、改善対象の管理、再評価
案件責任者	リリース判定、改善範囲、スケジュールの決定

初期構築時のチェックリスト

対象ユーザーと回答する範囲を決める
想定質問、期待回答、根拠ナレッジをまとめたGround Truthを作成する
回答せずに聞き返す質問や、有人対応へ切り替える条件を用意する
検索結果と最終回答を分けて評価する
同じGround Truthで検索条件を比較する
ナレッジの更新担当者と更新方法を決める
権限に基づくアクセス制御を実装する
コーパスへ登録できる情報源を限定する
回答不可条件や問い合わせ導線を確認する

定常運用のチェックリスト

低評価、未解決、有人対応へ切り替わった質問を収集する
検索結果と最終回答を分けて確認する
失敗例をGround Truthへ追加する
原因に対応する箇所だけを修正する
既存の評価ケースをすべて再実行する
品質、応答時間、費用を変更前後で比較する
古いナレッジ、重複するナレッジ、更新漏れを確認する

Part 3｜Craft RAG実装リファレンス

Part 1とPart 2で説明した考え方を、Craft RAGの機能やパラメータへ対応させます。

Recallを確認する

Craft RAGでは、Craft Functionsでrag.retrieveContexts()を実行すると、回答生成前の検索結果を確認できます。Ground Truthで定義した根拠ナレッジが検索結果にどれだけ含まれるかを確認します。Recallの数値がAPIから直接返るわけではありません。

検索結果の各チャンクには、本文のtext、取得元のfilePath、質問とのベクトル距離を示すscoreが含まれます。scoreは値が小さいほど質問に近いチャンクです。

topKは、検索結果に含めるチャンクの最大数です。Ground Truthで定義した根拠ナレッジが検索結果に含まれない場合は、topKを段階的に増やして再評価します。必要な根拠を取得できるようになったら、それ以上増やしてもRecallが改善しない最小の値を候補にします。

topKを増やしても必要な根拠を取得できない場合は、ナレッジの分け方、検索用の質問文、vectorDistanceThreshold、metadataFilterを確認します。

詳しい使用方法は、ベクトル検索でファイルの中身を取得をご確認ください。

Precisionを確認する

取得件数を指定するtopKと、検索結果をベクトル距離で絞り込むvectorDistanceThresholdを調整します。

vectorDistanceThresholdは、検索結果に含めるベクトル距離の上限です。値を大きくすると取得範囲が広がり、値を小さくすると質問に近いチャンクへ絞り込まれます。

症状	調整例
必要な情報が検索されない	`topK`を増やす、または`vectorDistanceThreshold`を大きくする
無関係な情報が多い	`topK`を減らす、または`vectorDistanceThreshold`を小さくする

同じGround Truthを使い、一度に1つの項目だけを変更します。変更前後でRecall、Precision、回答の正しさ、応答時間、費用を比較してください。

パラメータの詳細は、Craft RAGモジュールリファレンスをご確認ください。

メタデータフィルタを設定する

ファイルにメタデータを付与し、検索時にmetadataFilterを指定すると検索対象を絞り込めます。同じGround Truthを使ってフィルタの有無を比較し、必要な情報を検索対象外にしていないか確認します。

設定方法は、Craft RAG のメタデータフィルタをご確認ください。

Rerankを設定する

必要な情報を広い範囲から取得した後で、質問との関連度に基づいて並び替える場合は、Rerankを利用します。Rerankを使うとレイテンシや費用が増えるため、使用しない場合と同じGround Truthで比較します。

設定方法は、Craft RAG の Rerankをご確認ください。

チャンクの分け方を調整する

topKやvectorDistanceThresholdを調整しても必要な情報を取得できない場合は、インポート時のチャンクサイズと重複サイズを確認します。

1つのチャンクに複数の論点が含まれていないか
結論と条件、例外が別々のチャンクに分かれていないか
見出しと本文の関係が分かる状態になっているか
回答に必要な情報が複数のファイルへ重複していないか

チャンク設定については、管理画面からインポートするをご確認ください。

システムプロンプトを設定する

Craft AI Modulesでは、aiModules.gcpGeminiGenerateContent()のsystemInstructionに、回答順序、文体、回答不可条件などのルールを設定できます。

詳細は、Craft AI Modules Googleをご確認ください。

継続評価できる状態を作る

質問、検索条件、取得したチャンク、最終回答、トークン数、評価結果を記録し、同じ評価ケースを再実行できる状態にします。Craft Functionsの実行ログには、loggerを利用できます。ただし、 logger のログ保持期間には制限があるため、継続的な評価に必要なデータは長期保存・分析可能な基盤への蓄積を検討する。