> Source: https://clickhouse.github.io/loom/ja/getting-started/evaluate/ (Markdown: https://clickhouse.github.io/loom/ja/getting-started/evaluate.md)

<!-- i18n: source=docs/getting-started/evaluate.md blob=882e7d370aa195573ce2e4029995fa1f32beadc9 model=claude-sonnet-5-5 -->
> このページは[英語の原文](https://clickhouse.github.io/loom/getting-started/evaluate/)の機械翻訳です。内容は英語の原文が優先されます。
> Machine-translated from the [English page](https://clickhouse.github.io/loom/getting-started/evaluate/), which is authoritative.

<a id="evaluate-loom"></a>

# Loom を評価する

評価の対象は、リポジトリ内のすべてのハーネスではなく、これから下す必要がある判断です。このガイドでは、まずコストのかからないプロダクトのスモークテストを行い、次にワークロード固有の品質テストへ進みます。公開ベンチマークスイートは、公表されている主張を監査または再現する必要がある場合の最後のステップです。

<a id="choose-an-evaluation"></a>

## 評価を選ぶ

| 判断したいこと | データ | プロバイダー | 典型的な出力 |
| ----------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| Loom は正しくインストールされ、接続できているか | 4 件のテスト用ファクトと 1 件のドキュメント | 標準のフェイクプロバイダーで十分 | 新しいセッションでもファクトが残り、ソース、履歴、監査の行がダッシュボードに表示される |
| メモリは自分たちのエージェントに役立つか | 期待するメモリキーを付けた実際の質問 25～50 件 | 実際の埋め込みモデル。抽出または `memory.ask` には実際の LLM | recall@k、rank@1、回答の差し控え、回答精度、レイテンシ、コスト |
| コードインテリジェンスは自分たちのリポジトリに役立つか | 代表的なシンボル、呼び出し元の集合、issue 形式の質問 | 実際の埋め込みモデル。インデックス済みのリポジトリ | 定義の完全一致、呼び出し元の F1、ファイル再現率、回答の差し控え、トークン数、レイテンシ |
| 公開された結果を再現できるか | 名前の挙がっている公開データセットと、コミット済みの結果アーティファクト | 固定されたモデル、または文書化された代替モデル | 同じスライス、リーダー、ジャッジ、検索モードによる比較可能な実行結果 |

品質の判断にフェイク埋め込みモデル（チェックアウトした `.env`）やフェイク LLM を使わないでください。これらは、認証情報なしでスタックを起動し、統合テストを決定的にするためのものです。リリース版スタックのローカル埋め込みモデルは実際に検索を行うため、検索の最初の確認にはそれで意味のある結果が得られます。回答と抽出の評価には、実際の LLM を使ってください。

<a id="before-you-run"></a>

## 実行前に

まず、次の5つを書き出してください。

1. **ワークロード。** 判断の対象となるユーザー、リポジトリ、質問の種類。
2. **ベースライン。** Loom を使わない場合に、同じユーザーまたはエージェントが行うこと。全コンテキスト、grep、BM25、別のメモリシステム、または検索なし。
3. **精度ゲート。** 許容する最低限の再現率、回答精度、またはタスク成功率。品質はコストより優先します。
4. **経済性ゲート。** p95 レイテンシ、トークン、モデルコスト、インデックス作成時間、ストレージの上限。
5. **計測環境。** Loom のコミット、ClickHouse のデプロイ、プロバイダーのモデル、モデルのパラメータ、ハードウェア、データセットのバージョン、乱数シード。

ゲートを事前に登録しておくと、実行後に都合のよい指標やスライスが結果にすり替わることを防げます。失敗や回答の棄権は見える状態で残してください。リクエストエラーは、検索ミスとして黙って数えたり除外したりせず、別に報告します。

<a id="1-product-smoke-test"></a>

## 1. プロダクトのスモークテスト

このテストは約 15 分で完了し、配線、永続化、可視性を確認します。意味的な品質は確認できません。

1. [ローカルスタックを起動](https://clickhouse.github.io/loom/ja/getting-started/quickstart/#1-boot-the-stack)し、`/v1/health` が `status: ok` を返すことを確認します。
2. [ファクトを書き込んで検索](https://clickhouse.github.io/loom/ja/getting-started/quickstart/#4-first-memory-over-http)します。
3. [コーディングエージェントを接続](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/connect-a-coding-agent.md)し、永続的な設定を伝えてから、新しいセッションを開いてその設定を尋ねます。
4. ファクトを修正し、ダッシュボードにそのソースとバージョン履歴が表示されることを確認します。
5. ドキュメントを指定して `loom demo` を実行し、返されたチャンクがそのドキュメントを引用していることを確認します（[ドキュメントのスモークテスト](https://clickhouse.github.io/loom/ja/getting-started/quickstart/#optional-ask-a-question-about-a-document)）。

合格となるのは、新しいセッションがそのファクトを想起し、修正が現在の回答を置き換え、無関係な質問には回答を控え、ダッシュボードに書き込み元と履歴が表示された場合のみです。ヘルスチェックが `fake_embedding` または `fake_llm` を報告している間は、この結果から本番環境での想起精度は判断できません。

<a id="2-evaluate-your-workload"></a>

## 2. ワークロードを評価する

[実際のプロバイダー](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#providers)を設定し、ベクトル幅が変わった場合はデータをリセットまたは再埋め込みして、解決されたモデルを `/v1/health` から記録します。分離した名前空間を使い、対になるすべてのアームで同じインデックス済みデータを保ってください。

<a id="memory-and-rag"></a>

### メモリと RAG

実際のタスクから、少なくとも 25〜50 件の質問セットを作成します。次のものを含めてください。

- 直接的な事実、言い換え、マルチホップの質問、時間に依存する更新
- 回答が新しい情報で置き換えられているはずの質問
- もっともらしいが回答できない質問（誤答と回答の差し控えを測定するため）
- 重要な値だけが異なる、ほぼ重複した紛らわしい候補

回答可能な各メモリの質問には、実行前に期待される `memory_key` をラベル付けします。ドキュメントの RAG では、期待されるドキュメントとチャンクをラベル付けし、`knowledge.search` にクエリを送り、同じ検索メトリクスでそれらの識別子を採点します。検索と合成は別々に測定します。

- **検索：** recall@k、rank@1、MRR、偽陽性率、abstain の適合率と再現率。
- **回答：** 固定した 1 つのリーダーとジャッジによる正答性、および引用の正確性。
- **コスト効率：** p50/p95 レイテンシ、入出力トークン、モデルコスト、構築コスト、保存された行数。

既存のメモリコーパスについては、次の形式で JSON データセットを保存します（付属のハーネスは `memory.search` を対象とします。`knowledge.search` には同等のスコアラーを使ってください）。

```json
{
  "org": "acme",
  "namespace": "support-eval",
  "questions": [{ "query": "When can we deploy?", "gold_keys": ["deploy_window"] }]
}
```

その後、コーパスを変更せずに検索を実行します。

```bash
export PYTHONPATH=$PWD LOOM_API_KEY=<token>
.venv/bin/python bench/retrieval_recall.py \
  --dataset /path/to/retrieval_qa.json --base-url http://localhost:7777 \
  --top-k 10 --out /tmp/loom-retrieval.csv
```

`--min-recall` と `--min-mrr` は、事前登録した基準からのみ設定してください。回答精度には、同じ質問に対して `memory.ask` または本番のリーダーを使います。recall と回答精度は異なる測定です。

<a id="code-intelligence"></a>

### コードインテリジェンス

本番のリポジトリに近いリポジトリをインデックスします。Loom のチューニングに使われたリポジトリだけで始めてはいけません。次をラベル付けします。

- 期待されるファイルと修飾シンボルを持つ定義
- 期待される呼び出し元の完全な集合を持つ呼び出し元
- 上位 5 件と上位 10 件で許容されるファイルを持つ、概念的な質問や issue 形式の質問
- 回答を差し控えるべき、リポジトリ外の質問
- 影響クエリから期待される、変更されたシンボルやコードに依存する側（逆方向の依存先、影響を受ける呼び出し元）のコンポーネント、またはテスト

インデックス済みのリポジトリに対して、コードエージェントの受け入れレポートを実行します。

```bash
export PYTHONPATH=$PWD
.venv/bin/python bench/acceptance/code_agent.py \
  --base-url http://localhost:7777 --token-file /path/to/token \
  --namespace <code-namespace>
```

組み込みのフィクスチャは ClickHouse を対象としており、デプロイの確認に役立ちます。製品判断のためには、これを自分のラベル付き質問で置き換えるか拡張し、同じエージェントタスクを通常のリポジトリツールのみの場合と比較してください。まずタスクの成功を報告し、その後にターン数、トークン、コスト、実時間を報告します。ツールスキーマのオーバーヘッドはクライアントに依存するため、MCP ツール定義を遅延させるかどうかを記録してください。

<a id="keep-the-comparison-fair"></a>

### 比較を公平に保つ

- 対になるアームでは、同じモデル、プロンプト、データスナップショット、質問順序を使います。
- 抽出とインデックス構築のコストは質問ごとのコストと分けて扱い、構築コストを償却するのに必要な質問数を明記します。
- 評価用の読み取りからの学習（`auto_touch: false`、`reinforce: false`）を無効にし、先のクエリが後のクエリを改善しないようにします。
- サンプルサイズ、カテゴリ別の結果、不確実性を報告します。小規模なスモークテストの結果を一般的な主張に昇格させないでください。
- 集計スコアだけでなく、エラーや見逃しを含む質問ごとの出力を保存します。

<a id="3-audit-or-reproduce-published-results"></a>

## 3. 公開された結果の監査と再現

README はスコアカードであり、証跡の台帳ではありません。公開されている各数値について、次の手順で確認します。

1. [ベンチマーク結果](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/results.md)の該当セクションを開きます。
2. [`bench/results/`](https://github.com/ClickHouse/loom/blob/main/bench/results) にコミットされているアーティファクトを確認します。
3. データセットのスライス、Loom のコミット、モデル、リーダー、ジャッジ、検索モード、シードを確認します。
4. 結果セクションに記載されている再現コマンドをそのまま実行します。
5. [方法論](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/methodology.md)に従って差分を解釈します。ジャッジのキャリブレーション、ブートストラップ区間、既知のバイアスも考慮してください。

サードパーティのデータセットのすべてが、このリポジトリで再配布されているわけではありません。入手元とライセンスは[データセット](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/running.md#datasets)に記載されています。公開されている実行全体には数時間かかることがあり、プロバイダーの料金が発生する場合があります。まずドキュメントに記載されているスモークスライスから始め、比較結果を公開する前に完全なプロトコルを実行してください。

<a id="what-to-publish"></a>

## 公開する内容

README に結果を掲載するのは、その結果が代表的であり、1 行で理解でき、コミット済みのアーティファクトと再現コマンドの裏付けがある場合に限ります。カテゴリ別の完全な表、モデル、プロンプト、不確かさ、コスト、失敗の分析、制約事項は、[結果台帳](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/results.md)に記載します。安定した評価ルールは[評価方法](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/methodology.md)に、コマンドとデータセットの入手方法は[実行方法](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/running.md)に記載します。

公開するすべての主張には、次の内容を明記してください。

- タスクとサンプルサイズ。
- 指標、およびそれが検索、回答品質、エンドツーエンドの成功のいずれであるか。
- ベースラインと対応のあるデルタ（存在する場合）。
- モデルとジャッジ、または LLM ジャッジを使用していないこと。
- 不確かさ、または 1 問の変化による粒度。
- 構築コストとクエリコストを分けて記載すること。
- コミット済みのアーティファクトと正確な再現コマンド。
- 重要な否定的な知見と、その結果が一般化できない範囲。

利用できるすべての数値を README に載せないでください。長いスコアボードは製品上の判断を見えにくくし、ベンチマーク間の不適切な比較を助長し、古くなった主張を見つけにくくします。README は読者を根拠へ導くものとし、根拠そのものはドキュメントに記載します。

<a id="next"></a>

## 次のステップ

- [ベンチマークのカバレッジ](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/coverage.md)：公開された測定結果があるもの、ハーネスのみがあるもの、公開された根拠がまだないもの。
- [ベンチマークの概要](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/overview.md)：測定するシグナルに応じてハーネスを選びます。
- [ベンチマークの実行](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/running.md)：プロバイダー、トークン、コマンド、データセット。
- [ベンチマークの方法論](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/methodology.md)：比較のルールと制限事項。
- [ベンチマークの結果](https://github.com/ClickHouse/loom/blob/main/docs/benchmarks/results.md)：コミット済みの測定結果とアーティファクト。
