MENU

問い合わせ

    お問い合わせ


    【FastAPIで作る社内ナレッジ検索(RAG) 第8回】回答の品質を評価ケースで測り、直したつもりの後退を自動テストで見つける

    (2026年10月29日 追記:記事どおりに再現できるよう、必要なコードと手順を追加しました)

    社内AIチャットは、作った直後よりも「直したあと」のほうが怖い仕組みです。しきい値を少し変えた、文書を入れ替えた、AIのモデルを新しくした。どれも小さな変更なのに、ある質問には答えられなくなったり、見てはいけない部署の文書が出てしまったりします。しかも画面で数件試しただけでは気づけません。第7回ではPDFを取り込み、ページ番号つきの出典で答えさせるところまで作りました。

    「AIが出す答えの品質を、どうやって確認すればいいのか分からない。直したあとに前より悪くなっていないかも不安」

    先に結論をお伝えします。「この質問には、この文書を根拠に、こう答えてほしい」という評価ケースを先に書いておき、変更のたびに自動で全件流すのが、いちばん現実的な品質管理です。第8回では、評価ケースの書き方、採点の仕組み、AIのキーが無くても回せる評価の作り方を、動くコードで説明します。

    この記事で作るのは、次の3つです。

    • 評価ケースを書いたファイル(eval/cases.json)
    • 本番と同じ経路(検索→回答)にケースを流して採点する仕組み(app/eval/)
    • 変更で品質が下がったら失敗する自動テスト(tests/test_eval.py)
    目次

    社内AIチャットの品質を「確認」でなく「測定」にする理由

    AIの回答は毎回少しずつ文章が変わるため、「画面で試して問題なさそう」という確認では、変更の影響を見落とします。そこで、品質を次の3つの観点に分けて、機械的に判定できる形にします。

    観点何を確かめるか例
    答えられるか正しい文書が出典に入り、必要な言葉が回答に含まれる「午前休は何時まで?」→ 休暇規程、「12時」
    答えないべき時に答えないか根拠が無い質問で「見つかりません」と返す「社長の好きな食べ物は?」
    見せてはいけないものを出さないか権限の無い部署の文書名・内容が回答や出典に出ない人事部の給与表が、他部署の質問に出ない

    3つ目が特に重要です。「答えられる」質問は、使われれば不具合に気づけます。一方、「出てはいけないものが出ていないか」は、誰も気づかないまま漏えいが続くことがあるため、自動テストで守る価値が高い観点です。

    この回も、第7回までの rag-naibu フォルダで作業します。新しいライブラリはありません。評価の部品を置くフォルダと、評価ケースを置くフォルダを作ります。

    mkdir -p app/eval eval
    touch app/eval/__init__.py

    評価ケースを書く(eval/cases.json)

    評価ケースは、プログラムではなく人が読める一覧にします。業務の担当者が「この質問も入れて」と言えるようにするためです。

    eval/cases.json

    [
      {
        "id": "vacation-half-day",
        "question": "午前休は何時までですか?",
        "expect_source": "vacation.md",
        "expect_text": ["12時"]
      },
      {
        "id": "expense-deadline",
        "question": "経費の申請期限は?",
        "expect_source": "expense.txt",
        "expect_text": ["30日"]
      },
      {
        "id": "business-trip-pdf",
        "question": "出張の宿泊費の上限は?",
        "expect_source": "business-trip.pdf"
      },
      {
        "id": "hr-visible-to-hr",
        "question": "一般職の月額給与はいくら?",
        "departments": ["hr"],
        "expect_source": "hr/salary-grade.md",
        "expect_text": ["20万円"]
      },
      {
        "id": "hr-hidden-from-others",
        "question": "一般職の月額給与はいくら?",
        "forbid": ["salary-grade", "20万円", "24万円"]
      },
      {
        "id": "sales-hidden-from-hr",
        "question": "承認なしで出せる値引き率の上限は?",
        "departments": ["hr"],
        "forbid": ["discount-policy", "5%"]
      },
      {
        "id": "no-answer-ceo-food",
        "question": "社長の好きな食べ物は?",
        "expect_not_found": true,
        "known_issue": "簡易埋め込み(HashingEmbedder)では無関係な質問も距離0.87前後で近く見え、しきい値0.9を抜けてしまう。本物の埋め込みモデルに替えたら外す"
      }
    ]

    (全7件。PDFの出典・部署が違う場合の見え方も含みます)

    項目の意味は次のとおりです。

    • expect_source:出典に含まれてほしい文書名(部分一致)
    • expect_text:回答に含まれてほしい言葉
    • forbid:回答にも出典にも出てはいけない言葉(権限の無い文書の名前や数字)
    • expect_not_found:根拠が無いので答えないことを期待する
    • departments:質問者が見てよい部署(全社向けの all は常に含まれる)

    この一覧を読み込む部品 app/eval/cases.py を作ります。項目に書かなかったものは、既定値(空・指定なし)になります。

    # app/eval/cases.py
    import json
    from dataclasses import dataclass, field
    from pathlib import Path
    
    DEFAULT_CASES_PATH = Path(__file__).resolve().parents[2] / "eval" / "cases.json"
    
    
    @dataclass(frozen=True)
    class EvalCase:
        """評価ケース1件。「この質問をこの人がしたら、こうなってほしい」を書いたもの。"""
    
        id: str
        question: str
        # 質問者が見てよい部署(全社向け all は常に含まれる)
        departments: list[str] = field(default_factory=list)
        # True なら「根拠が無いので答えない」ことを期待する
        expect_not_found: bool = False
        # 出典に含まれてほしい文書名(部分一致)。答えられる質問で指定する
        expect_source: str | None = None
        # 回答文に含まれてほしい言葉
        expect_text: list[str] = field(default_factory=list)
        # 出典にも回答文にも、決して出てはいけない言葉(権限の無い文書の名前・内容)
        forbid: list[str] = field(default_factory=list)
        # 既知の不具合。理由を書くと「失敗しても連載の自動テストを止めない」扱いになる(理由は必須)
        known_issue: str | None = None
    
    
    def load_cases(path: Path = DEFAULT_CASES_PATH) -> list[EvalCase]:
        raw = json.loads(path.read_text(encoding="utf-8"))
        return [EvalCase(**item) for item in raw]

    本番と同じ経路で採点する(app/eval/runner.py)

    採点の部品は、第5回で作った回答処理(answer_question)をそのまま呼びます。評価用に別の経路を作ると、「評価では通るが本番では通らない」ことが起きるためです。

    # app/eval/runner.py
    from collections.abc import Callable
    from dataclasses import dataclass, field
    
    from app.answer.llm import LLM
    from app.answer.service import answer_question
    from app.db.store import SearchHit
    from app.eval.cases import EvalCase
    
    Searcher = Callable[[str, list[str]], list[SearchHit]]
    
    
    @dataclass(frozen=True)
    class CaseResult:
        case: EvalCase
        passed: bool
        reasons: list[str] = field(default_factory=list)
    
        @property
        def known_failure(self) -> bool:
            return not self.passed and self.case.known_issue is not None
    
    
    def run_case(case: EvalCase, searcher: Searcher, llm: LLM, max_distance: float) -> CaseResult:
        """1件の質問を本番と同じ経路(検索→回答)に流し、期待どおりかを採点する。"""
        departments = sorted({"all", *case.departments})
        answer = answer_question(case.question, searcher(case.question, departments), llm, max_distance)
        reasons: list[str] = []
    
        if case.expect_not_found:
            if answer.found:
                reasons.append("根拠が無いはずなのに答えてしまった")
        else:
            # 答えられることの確認は、期待する出典か言葉を書いたケースだけで行う(情報漏えいの確認は forbid のみ)
            if (case.expect_source or case.expect_text) and not answer.found:
                reasons.append("答えられるはずなのに「見つからない」と返した")
            if case.expect_source and not any(case.expect_source in s for s in answer.sources):
                reasons.append(f"出典に {case.expect_source} が無い(出典: {answer.sources})")
            for word in case.expect_text:
                if word not in answer.text:
                    reasons.append(f"回答に「{word}」が含まれない")
    
        visible = answer.text + "\n" + "\n".join(answer.sources)
        for word in case.forbid:
            if word in visible:
                reasons.append(f"出てはいけない「{word}」が回答または出典に含まれる")
    
        return CaseResult(case, not reasons, reasons)
    
    
    def run_all(
        cases: list[EvalCase], searcher: Searcher, llm: LLM, max_distance: float
    ) -> list[CaseResult]:
        return [run_case(c, searcher, llm, max_distance) for c in cases]
    
    
    def summarize(results: list[CaseResult]) -> str:
        lines = []
        for r in results:
            mark = "OK  " if r.passed else ("既知" if r.known_failure else "NG  ")
            lines.append(f"{mark} {r.case.id}: {r.case.question}")
            for reason in r.reasons:
                lines.append(f"       - {reason}")
            if r.known_failure:
                lines.append(f"       (既知の不具合: {r.case.known_issue})")
        passed = sum(r.passed for r in results)
        known = sum(r.known_failure for r in results)
        new_ng = len(results) - passed - known
        lines.append(
            f"合計 {len(results)}件: 合格 {passed} / 既知の不具合 {known} / 新たな不合格 {new_ng}"
        )
        return "\n".join(lines)
    
    
    def has_regression(results: list[CaseResult]) -> bool:
        """既知の不具合ではない不合格が1件でもあれば「後退した」と見なす。"""
        return any(not r.passed and not r.known_failure for r in results)

    不合格のときは、何が悪かったかを文章(reasons)で残します。「失敗しました」だけでは、直す人が原因を探すところから始めることになるからです。

    APIキー無しで回す:AIの代役を使う(app/eval/fake_llm.py)

    評価のたびに本物のAIを呼ぶと、費用がかかり、結果も毎回少し揺れます。そこで、渡された文書の本文を番号つきでそのまま並べて返す「代役」(ExtractiveLLM)を用意しました。

    # app/eval/fake_llm.py
    import re
    
    DOCUMENT = re.compile(r'<document index="(\d+)"[^\n]*>\n(.*?)\n</document>', re.DOTALL)
    
    
    class ExtractiveLLM:
        """APIキー無しで評価を回すための代役。渡された文書の本文を、番号つきでそのまま並べて返す。
    
        本物のAIの文章力は測れない。測れるのは「検索が正しい文書を探せたか」
        「権限の無い文書がAIに渡されていないか」「根拠が無い質問を弾けているか」までである。
        文書が1件も渡されなければ、本物のAIと同じく NO_ANSWER を返す。
        """
    
        def generate(self, system: str, user: str) -> str:
            docs = DOCUMENT.findall(user)
            if not docs:
                return "NO_ANSWER"
            return "\n".join(f"{body}[{index}]" for index, body in docs)

    この代役で測れるのは、検索が正しい文書を探せたか・権限の無い文書がAIに渡っていないか・根拠が無い質問を弾けているかまでです。AIの文章のうまさや、文書に無いことを言っていないかは測れません。そこは次の節で扱う「本物のAIでの評価」の役割です。

    評価をコマンドで流す入口 app/eval/__main__.py も作ります。評価の前に sample_docs を取り込み直すので、後で説明する評価専用のDBで実行します。

    # app/eval/__main__.py
    import sys
    from pathlib import Path
    
    from app.answer.llm import AnthropicLLM
    from app.config import get_settings
    from app.db.migrate import apply_migrations
    from app.db.store import connect, save_chunks, search_chunks
    from app.eval.cases import load_cases
    from app.eval.fake_llm import ExtractiveLLM
    from app.eval.runner import has_regression, run_all, summarize
    from app.ingest.chunker import chunk_document
    from app.ingest.loader import load_documents
    from app.search.embedder import HashingEmbedder
    
    
    def main() -> None:
        # 使い方: python -m app.eval [--real-llm]
        #   既定は ExtractiveLLM(キー不要・無料)。--real-llm で .env の APIキーを使い、実際のAIに答えさせる。
        settings = get_settings()
        if "--real-llm" in sys.argv:
            if not settings.llm_api_key:
                sys.exit("LLM_API_KEY が未設定です(.env を確認してください)")
            llm = AnthropicLLM(settings.llm_api_key, settings.llm_model)
        else:
            llm = ExtractiveLLM()
    
        embedder = HashingEmbedder()
        with connect(settings.database_url) as conn:
            # 評価の前に sample_docs を取り込み直す(同じ文書名の断片は入れ替わる)。評価専用のDBで実行すること。
            apply_migrations(conn)
            for document in load_documents(Path("sample_docs")):
                save_chunks(conn, chunk_document(document), embedder)
    
            def searcher(question, departments):
                return search_chunks(conn, embedder, question, departments)
    
            results = run_all(load_cases(), searcher, llm, settings.max_distance)
        print(summarize(results))
        sys.exit(1 if has_regression(results) else 0)
    
    
    if __name__ == "__main__":
        main()

    変更で品質が下がったら失敗する自動テスト(tests/test_eval.py)

    評価ケースを pytest から呼び、既存のサンプル文書をDBに取り込んで全件流します。

    採点のルールそのもののテスト(DB不要)と、サンプル文書を実際のDBに取り込んで全件流すテストを、1つのファイルにまとめます。

    tests/test_eval.py の全文(82行)
    # tests/test_eval.py
    import os
    from pathlib import Path
    
    import pytest
    
    from app.config import get_settings
    from app.db.migrate import apply_migrations
    from app.db.store import SearchHit, connect, save_chunks, search_chunks
    from app.eval.cases import EvalCase, load_cases
    from app.eval.fake_llm import ExtractiveLLM
    from app.eval.runner import has_regression, run_all, run_case, summarize
    from app.ingest.chunker import chunk_document
    from app.ingest.loader import load_documents
    from app.search.embedder import HashingEmbedder
    
    ROOT = Path(__file__).resolve().parents[1]
    HITS = [SearchHit("vacation.md", "休暇 > 半日休暇", "午前休は始業から12時まで。", 0.2)]
    
    
    def fixed_search(hits):
        return lambda question, departments: hits
    
    
    def test_passes_when_source_and_text_match():
        case = EvalCase("c", "午前休は?", expect_source="vacation.md", expect_text=["12時"])
        assert run_case(case, fixed_search(HITS), ExtractiveLLM(), 0.9).passed
    
    
    def test_fails_when_expected_source_is_missing():
        case = EvalCase("c", "経費は?", expect_source="expense.txt")
        result = run_case(case, fixed_search(HITS), ExtractiveLLM(), 0.9)
        assert not result.passed
        assert "expense.txt" in result.reasons[0]
    
    
    def test_fails_when_it_answers_a_question_that_should_be_refused():
        case = EvalCase("c", "社長の好きな食べ物は?", expect_not_found=True)
        assert not run_case(case, fixed_search(HITS), ExtractiveLLM(), 0.9).passed
    
    
    def test_forbidden_word_in_answer_is_caught():
        case = EvalCase("c", "午前休は?", forbid=["12時"])
        result = run_case(case, fixed_search(HITS), ExtractiveLLM(), 0.9)
        assert not result.passed
        assert "出てはいけない" in result.reasons[0]
    
    
    def test_known_issue_does_not_count_as_regression():
        known = EvalCase("k", "経費は?", expect_source="expense.txt", known_issue="理由")
        new = EvalCase("n", "経費は?", expect_source="expense.txt")
        assert not has_regression(run_all([known], fixed_search(HITS), ExtractiveLLM(), 0.9))
        assert has_regression(run_all([new], fixed_search(HITS), ExtractiveLLM(), 0.9))
        assert "既知" in summarize(run_all([known], fixed_search(HITS), ExtractiveLLM(), 0.9))
    
    
    def test_case_file_is_valid():
        cases = load_cases()
        assert len({c.id for c in cases}) == len(cases)
        assert all(c.known_issue is None or c.known_issue.strip() for c in cases)
    
    
    DATABASE_URL = os.environ.get("TEST_DATABASE_URL")
    
    
    @pytest.mark.skipif(not DATABASE_URL, reason="TEST_DATABASE_URL が未設定のため実行しない")
    def test_regression_suite_against_sample_docs():
        """sample_docs を実際のDBに取り込み、評価ケースを全件流す。後退(既知以外の不合格)があれば失敗。"""
        schema = (ROOT / "db" / "init" / "001_schema.sql").read_text(encoding="utf-8")
        with connect(DATABASE_URL) as conn:
            conn.execute(schema)
            apply_migrations(conn)
            conn.execute("TRUNCATE chunks")
            conn.commit()
            embedder = HashingEmbedder()
            for doc in load_documents(ROOT / "sample_docs"):
                save_chunks(conn, chunk_document(doc), embedder)
    
            def searcher(question, departments):
                return search_chunks(conn, embedder, question, departments)
    
            results = run_all(load_cases(), searcher, ExtractiveLLM(), get_settings().max_distance)
        assert not has_regression(results), summarize(results)
    ruff check .
    TEST_DATABASE_URL=postgresql://rag:rag_local_only@localhost:5432/rag_test pytest

    実行すると、評価ケース7件のうち6件が合格し、残る1件は後述の「既知の不具合」として記録されます。

    OK   vacation-half-day: 午前休は何時までですか?
    OK   expense-deadline: 経費の申請期限は?
    OK   business-trip-pdf: 出張の宿泊費の上限は?
    OK   hr-visible-to-hr: 一般職の月額給与はいくら?
    OK   hr-hidden-from-others: 一般職の月額給与はいくら?
    OK   sales-hidden-from-hr: 承認なしで出せる値引き率の上限は?
    既知 no-answer-ceo-food: 社長の好きな食べ物は?
           - 根拠が無いはずなのに答えてしまった
           (既知の不具合: 簡易埋め込み(HashingEmbedder)では無関係な質問も距離0.87前後で近く見え、しきい値0.9を抜けてしまう。本物の埋め込みモデルに替えたら外す)
    合計 7件: 合格 6 / 既知の不具合 1 / 新たな不合格 0

    (開発環境での実行結果。単体で python -m app.eval を実行しても、同じ形式で表示され、後退があれば終了コード1で終わります。単体で実行するときは、次のように評価専用のDB rag_eval を作り、表を用意してから接続先に指定します)

    docker compose exec db createdb -U rag rag_eval
    docker compose exec -T db psql -U rag -d rag_eval < db/init/001_schema.sql
    DATABASE_URL=postgresql://rag:rag_local_only@localhost:5432/rag_eval python -m app.eval

    わざと壊して、テストが見つけるか確かめる

    評価が役に立つかは、壊したときに失敗するかで確かめます。第6回の「部署の絞り込み」(store.py の department = ANY(%s))を一時的に外して流すと、次のように表示されました(NGの行と合計だけを抜き出しています)。

    NG   hr-hidden-from-others: 一般職の月額給与はいくら?
           - 出てはいけない「salary-grade」が回答または出典に含まれる
           - 出てはいけない「20万円」が回答または出典に含まれる
           - 出てはいけない「24万円」が回答または出典に含まれる
    NG   sales-hidden-from-hr: 承認なしで出せる値引き率の上限は?
           - 出てはいけない「discount-policy」が回答または出典に含まれる
           - 出てはいけない「5%」が回答または出典に含まれる
    合計 7件: 合格 4 / 既知の不具合 1 / 新たな不合格 2

    画面を数回触っただけでは見落とすかもしれない権限の穴を、評価ケースが検出しました。確認後は元に戻してあります。

    「既知の不具合」を隠さず、増えていないことを見張る

    先ほどの結果で、「社長の好きな食べ物は?」は不合格のままです。第3回で作った簡易な検索(HashingEmbedder)では、無関係な質問でも距離が0.87前後に収まり、第5回のしきい値0.9を通り抜けてしまうためです。これは評価で初めて数値として確認できた弱点です。

    このケースには known_issue に理由を書き、「既知の不具合」として扱います。

    {
      "id": "no-answer-ceo-food",
      "question": "社長の好きな食べ物は?",
      "expect_not_found": true,
      "known_issue": "簡易埋め込み(HashingEmbedder)では無関係な質問も距離0.87前後で近く見え、しきい値0.9を抜けてしまう。本物の埋め込みモデルに替えたら外す"
    }

    既知の不具合は失敗として数えませんが、結果には「既知」と毎回表示されます。不具合を放置するのでも、テストを赤いままにして誰も見なくなるのでもなく、「分かっている弱点」として一覧に残すための仕組みです。known_issue は理由が空だと使えないようにしてあり(test_case_file_is_valid)、言い訳なしに外せなくなることを防いでいます。

    本物のAIで評価するとき(未確認の範囲)

    python -m app.eval --real-llm で、.env のAPIキーを使い、実際のAIに答えさせて同じ評価を流せます。ただし、この記事の開発環境にはキーが無く、本物のAIでの評価結果は確認していません。実行する場合は、次の点に注意してください。

    • 回答の文章は毎回変わるので、expect_text は「12時」のような短い言葉にとどめる
    • 実行のたびにAPI費用がかかる。評価の件数が増えたら、毎回の自動テストではなく、日次や変更前などに回す
    • 評価用のDBは本番と分ける(--real-llm なし・ありとも、実行時に sample_docs を取り込み直すため)

    つまずきやすい点・注意

    • 評価ケースの数を増やすのが目的ではありません。実際に現場から出た質問、過去に間違えた質問を優先して足すほうが、守る価値があります
    • 評価に通ったからといって、本番で間違えないという意味ではありません。評価は「決めた質問での後退を見つける網」です
    • 評価ケースに本物の機密(社員の給与など)を書かないでください。連載のサンプルは架空の規程です

    発注者向けメモ

    社内AI検索を開発会社に頼むとき、納品物に「評価ケースと、その実行手順」が入っているかを確認してください。評価ケースが無いと、改修やAIモデルの変更のたびに「前より悪くなっていないか」を人の目で確かめることになり、運用費用が増えやすくなります。

    • 評価ケースは、発注側の業務担当者が一緒に作れるか(現場の質問が反映されるか)
    • 権限の無い文書が出ないことを、自動テストで確認しているか
    • 「答えない」べき質問を、評価に含めているか
    • AIのモデルや設定を変えたとき、評価をやり直す運用になっているか
    • 評価でのAPI費用が、月額の運用費に含まれているか

    開発会社への質問例は次のとおりです。

    • 「回答の品質を、変更のたびにどうやって確認していますか。評価用の質問リストはいただけますか」
    • 「部署の違う文書が出てしまわないことを、自動テストで確認していますか」
    • 「AIのモデルを新しいものに替えたとき、回答が悪くなっていないかをどう確かめますか」
    • 「評価で『答えられなかった』『誤って答えた』質問は、どのように記録・共有されますか」

    まとめと次回予告

    第8回では、評価ケースをcases.jsonに書き、本番と同じ経路で採点し、後退があれば自動テストが失敗する仕組みを作りました。AIのキーが無くても回せる代役を使うことで、検索・権限・「答えない」判定を無料で毎回確認できます。評価で見つかった弱点は、隠さず「既知の不具合」として残します。

    次回の第9回は、ここまで作ったアプリをコンテナにまとめ、Google Cloud Runへデプロイする回です。シークレット(APIキー)の渡し方や、運用時の注意を扱います。

    この連載の記事一覧

    この記事は連載「FastAPIで作る社内ナレッジ検索(RAG)」の1回です。連載のほかの回は次のとおりです(連載の一覧ページ)。

    システム制作・運用・保守のお問い合わせはこちら

      お問い合わせ


      よかったらシェアしてね!
      • URLをコピーしました!
      • URLをコピーしました!

      この記事を書いた人

      株式会社THIRD HERO代表取締役 朝野貴朗
      Webシステム開発を中心に、toC向けサービスサイトの運営、ツール開発などを行ってまいりました。

      コメント

      コメント一覧 (5件)

      目次