コンテンツにスキップ

未翻訳のページは英語で開き、英語と表示されます。

このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 Machine-translated from the English page, which is authoritative.

Loom のパフォーマンスをチューニングする

このページで扱う調整項目は、すべて設定またはリクエストのフィールドです。各設定のデフォルト値と意味については、設定リファレンスを参照してください。トレードオフを計測できる項目については、計測に使うコマンドを併記しています。

まず計測する

知りたいこと コマンド 必要なもの
並行数 N での 1 つの op の p50 / p95 / p99 と RPS make bench OP=memory.search C=5 D=60 (scripts/ops/benchmark.py) 稼働中のサーバー。書き込みは bench-… 名前空間に入る
ランキングや embedder の変更で再現率が下がったか make bench-quick (回答ジャッジ付きの、公開されている長期メモリベンチマークの一部) 実際のプロバイダー、OPENAI_API_KEY
記録済みベースラインに対する再現率 make bench-quality-gate MIN_RECALL=… 実際のプロバイダー
検索モード × rerank × プール幅 make bench-matrix (bench/MATRIX_RESULTS.md に書き出す) 稼働中のサーバー
抽出およびグラフ抽出のリグレッション make bench-algorithm-gate 稼働中のサーバー
コードプレーンのシンボル、呼び出し元、再現率、トークンコスト make bench-code-intel, make bench-code-legs 実際の embedder
デプロイ後に何が変わったか loom deploy-delta (入れ替えの前後での、台帳と ClickHouse ステートメントの形) var/deployed.json

警告: fake embedder で測定した再現率は、実際の検索について何も示しません。品質ゲートが CI に含まれていないのはこのためです。デプロイ予定のプロバイダーを使うサーバーに対して実行し、embedder を変更したらベースラインを取り直してください。

遅いリクエストを 1 件調べる場合は、設定に手を加える前に、その Server-Timing ヘッダー (app と ch) と system.query_log の行を確認してください (デバッグ)。デプロイ全体での操作ごとのコストは、log_comment に対する 1 つのクエリで取得できます。

SELECT splitByChar(' ', log_comment)[1] AS source,
       count() AS queries, sum(read_bytes) AS bytes, sum(query_duration_ms) AS ms
FROM system.query_log
WHERE type = 'QueryFinish' AND event_time > now() - INTERVAL 1 HOUR AND log_comment != ''
GROUP BY source ORDER BY ms DESC LIMIT 20;

入れ替え直後のベンチマークトラフィックはキャッシュが冷えた状態で読み込まれます。デプロイ後のレイテンシーを以前のビルドと比較する前に、しばらく待ってください。

ランキングとしきい値

memory.search は第 1 段階の候補プールをランク付けし、その後にランク項とゲートを適用します(検索とランキング)。ほとんどの項はデプロイごとに設定でき、リクエストごとに上書きもできるため、変更をまず 1 つの呼び出し元で A/B テストできます。

調整項目 設定(リクエストフィールド) トレードオフ
類似度ゲート LOOM_ADAPTIVE_THRESHOLDS(デフォルトはオン) オン:起動時にエンベッダー自身のコサイン分布からゲートを導出します。オフ:下記のスカラーゲートを自分で管理します。
スカラーゲート(フォールバック) LOOM_MEMORY_SEARCH_MIN_SIMILARITY, LOOM_MEMORY_SEARCH_ABSTAIN_THRESHOLD, LOOM_MEMORY_SEARCH_HYDE_FALLBACK_THRESHOLD, LOOM_MEMORY_SEARCH_QUERY_REWRITE_THRESHOLD text-embedding-3-small 向けに調整されています。偽のエンベッダー、プローブの失敗、適応機能がオフの場合に使われます。
フロア未満のヒット LOOM_MEMORY_SEARCH_FLOOR_MODE(floor_mode) readmit は top_k を満たすまで補充し、below_floor のタグを付けます。ids_only は本文が空の行で補充します。drop は少ない件数を返します。
候補プール LOOM_MEMORY_SEARCH_POOL_MULTIPLIER_STANDARD, _RERANK, _DEEP。上限は LOOM_MEMORY_SEARCH_MAX_POOL_TOP_K プールを広げると再現率とリランクの入力が増えます。その分、読み取るベクトル行とリランクのトークンが増えます。
リランクのスキップ LOOM_LLM_RERANK_SKIP_ABOVE(適応ゲートにプローブがない場合のフォールバック) ベクトル検索の最上位ヒットがすでに強い場合、リランク呼び出しをスキップします。
フォールバックカスケード LOOM_MEMORY_SEARCH_FALLBACK_MAX_ROUNDS, _MAX_WALL_MS, _MAX_LLM_CALLS, _MAX_VECTOR_QUERIES 1 回目の結果が弱い場合に費やせる再試行(クエリ書き換え、HyDE)を制限します。
強化 LOOM_MEMORY_SEARCH_REINFORCEMENT_WEIGHT(reinforcement_weight), _HALF_LIFE_DAYS 再呼び出しと良好な結果が行をどれだけ押し上げるかを決めます。0 で無効になります。関連度より低く抑えられます。
出所 LOOM_MEMORY_SEARCH_TRUST_WEIGHT(デフォルトは 0) 証明済みのソースを優遇する、上限付きの項です。
新しさ LOOM_MEMORY_SEARCH_RECENCY_POOL_WEIGHT(recency_pool_weight) 新しさを意図したクエリで、プールを新しい行寄りに再ランク付けします。0 でオフです。
コード形状クエリでの字句レッグ rrf_adaptive_lexical(リクエスト), LOOM_MEMORY_RRF_CODE_SHAPE_LO / _HI RRF において、パス形状やコード形状のクエリで字句レッグの重みを下げます。
デフォルトモード LOOM_MEMORY_SEARCH_DEFAULT_MODE(search_mode) 呼び出し元がモードもレシピも指定しない場合に使われます。
キーごとの重複 LOOM_MEMORY_SEARCH_PER_KEY_CAP 1 つのキーが 1 ページに寄与できる行数です。

警告: あるエンベッダーで調整したしきい値は、別のエンベッダーでは適切ではありません。LOOM_ADAPTIVE_THRESHOLDS=false の場合や偽のエンベッダーを使う場合は、エンベッダーを変更するたびにベンチマークをやり直してください(make bench-quick、make bench-quality-gate)。calibration.get を使うと、名前空間で有効なゲートをどのティアが生成したかを確認できます。

ベクトル読み取り

ベクトル列は Array(BFloat16) です。enable_quantized_codec を有効にできる場合、マイグレータは列をコード化した形式で作成します(ClickHouse)。

調整項目 設定 トレードオフ
コード優先スキャン LOOM_VECTOR_SEARCH_QUANTIZED_CODES(デフォルトはオン)、LOOM_MEMORY_SEARCH_FACT_CODES_FIRST(auto) 量子化コードを読み取り、その後フル精度で再スコアリングします。auto は、memory_embeddings にパッチパートがある間はオフになります。この場合、再スコアリングがスキップされるためです。
コードのオーバーフェッチ LOOM_VECTOR_SEARCH_QUANTIZED_FETCH_MULTIPLIER、LOOM_MEMORY_SEARCH_FACT_CODES_FETCH_MULTIPLIER 再スコアリングの前に、コード距離で残す行数です。値を小さくするとコストは下がりますが、上位ヒットが変わる頻度が高くなります。
ファクト文ごとのスレッド数 LOOM_MEMORY_SEARCH_FACT_LEG_MAX_THREADS(0 = 固定なし) スレッド数を固定すると、文ごとの CPU とピークメモリが制限されますが、レイテンシが多少増えます。
一括書き込みのピア読み取り LOOM_MEMORY_BULK_PEER_READ(デフォルトは batched、per_fact) per_fact は、memory.set と同様に、一括書き込みの各ファクトについて、競合ピアと値更新ピアをコード優先で読み取ります。大規模な名前空間向けです。バッチ化されたピア文が MEMORY_LIMIT_EXCEEDED で失敗し(サーバーログでは batched conflict candidates failed)、さらにファクトごとのフォールバックも失敗した場合、そのエントリは未チェックのまま書き込まれます。距離が同点の場合、ピアが異なることがあります。

既存のテーブルをコーデックやレイアウトに移行するには、scripts/ops/vector_codec_rebuild.py を使用します(ツインテーブル、整合性ゲートと再現率ゲート、EXCHANGE。手順)。マイグレーション内で ALTER を使用しないでください。

ClickHouse の接続とデッドライン

項目 設定 トレードオフ
プールサイズ LOOM_CH_POOL_MAXSIZE(デフォルトはプロセスあたり 64) 想定されるリクエストの同時実行数にワーカー数を加え、さらにバッチ挿入が待機中に保持する接続数を足してサイズを決めます。ドライバー自体のデフォルト値は、大量の書き込みでは使い切られます。
バッチ挿入 LOOM_CH_BATCHED_INSERTS(デフォルトで有効)、LOOM_CH_BATCHED_INSERT_WAIT_MIN_MS(10)、LOOM_CH_BATCHED_INSERT_WAIT_MAX_MS(50)、LOOM_CH_BATCHED_INSERT_BACKGROUND_WAIT_MAX_MS(200) 同時に行われる挿入は 1 つのパートを共有し、それぞれ最大でウィンドウ分のレイテンシが加わります。単独の挿入は最小値だけ待機します。待機中の挿入はそれぞれプール内の接続を 1 つ保持するため、書き込みレートに応じてプールを大きくする必要があります(バッチ挿入)。
プール待機 LOOM_CH_POOL_WAIT_MS(デフォルト 500) これを超えると、リクエストはキューに入らず 503 OVERLOADED で即座に失敗します。0 の場合はゲートなしです。
キープアライブ LOOM_CH_KEEPALIVE_TIMEOUT(デフォルト 5 秒) ロードバランサーのアイドル切断時間より短くしておく必要があります。これにより、Loom がプール内の接続を先に閉じます。
ステートメントのデッドライン LOOM_CH_TIMEOUT_READ_S、LOOM_CH_TIMEOUT_WRITE_S、LOOM_CH_TIMEOUT_DDL_S max_execution_time として、またプールのスロットを解放するクライアント側の上限として適用されます。0 の場合、そのクラスは無制限です。
トラフィッククラスごとの優先度 LOOM_CH_SETTINGS_BY_TRAFFIC_CLASS(JSON) クラス(production、interactive、bench、background)ごとの priority と max_threads を指定します。これにより、ベンチとワーカーが本番の読み取りに道を譲ります。
Read-your-writes LOOM_CH_READ_YOUR_WRITES、LOOM_CH_READ_YOUR_WRITES_WINDOW_S 書き込み後に逐次一貫性のある読み取りを行います。レプリケーションされたサービスではコストがかかり、単一ノードでは何もしません。
オペレーションの予算 LOOM_LATENCY_BUDGET_MULTIPLIER すべての op の budget_p99_ms を拡大します。ClickHouse への WAN 経由のホップでは約 20 が必要です。予算は budget.violated イベントを発生させるだけで、リクエストを打ち切ることはありません。

Web の処理能力は、コンテナあたりの LOOM_WEB_WORKERS にコンテナ数を掛けた値です。レートリミッターは、loom.instances で数えた稼働中のレプリカ数で上限を割りますが、LOOM_REPLICA_COUNT を下回ることはありません(レプリカ)。

プロバイダー

調整項目 設定 トレードオフ
クエリ埋め込みの上限 LOOM_MEMORY_SEARCH_EMBED_BOUND_S, LOOM_MEMORY_SEARCH_EMBED_BOUND_RETRIES クエリ埋め込みの1回ごとの試行に上限を設けます。リトライ後も完了しない場合、検索は 503 EMBED_TIMEOUT を返します。
クエリの綴り LOOM_MEMORY_SEARCH_QUERY_SPELLING_MAX_WORDS この語数以下のクエリは、埋め込みと並行して名前空間を1回読み取り、小文字の単語をコーパスの綴りで埋め込みます。40k 行の名前空間で 100–300 ms かかり、結果は1分間再利用されます。0 で無効になります。
クエリ埋め込みのキャッシュ LOOM_EMBEDDING_CACHE_SIZE, LOOM_EMBEDDING_CACHE_TTL_S, LOOM_EMBEDDING_CACHE_SHARED, LOOM_EMBEDDING_CACHE_SHARED_MAX_CHARS 共有の loom.embedding_cache の手前にプロセスごとの LRU を置きます。繰り返されるクエリはプロバイダー呼び出しを省略します。
クラスごとの LLM レスポンスキャッシュ LOOM_LLM_POLICY_BY_TRAFFIC_CLASS (JSON) LLM のレスポンスをキャッシュし(bench ではデフォルトで有効)、クラスごとに strong ティアや mid ティアの利用を禁止できます。
フォールバックモデル LOOM_LLM_FALLBACK_MODEL リトライ後もプライマリが利用できない場合、op を失敗させる代わりにこのモデルが応答します。
支出上限 LOOM_DEFAULT_DAILY_COST_CAP_USD(名前空間ごとの daily_cost_cap_usd) 上限を超えると、LLM を使うワーカーはその名前空間をスキップし、memory.ask は budget_capped で回答を控えます。通常の読み取りと書き込みは継続します。

エンベッダーの選択

エンベッダー (LOOM_EMBEDDING_MODEL) トレードオフ
text-embedding-3-large, gemini-embedding-001 Loom のデフォルトである 3072 次元です。品質とコストは、実際のデータで測定する必要があります。
text-embedding-3-small より狭い 1536 次元のベクトルを使う選択肢です。次元を変更すると再埋め込みが必要です。
local, local:bge-small, local:bge-base, local:minilm プロセス内で CPU により埋め込みを行います。プロバイダー呼び出しもキーも不要です。品質と引き換えにレイテンシとコストを抑えます。
fake-ngram-3072 標準の次元で文字 n-gram を使います。テストと配線の確認専用で、再現率の数値には意味がありません。

エンベッダーを変更するとベクトル空間が変わります。LOOM_EMBEDDING_DIM を合わせて設定し、loom reembed を実行してください。適応型しきい値が有効な場合は、起動時のプローブに再較正させます。変更の前後で make bench-quick を実行してください。抽出プロンプトが較正されている LOOM_LLM_MODEL についても同様です。

ワーカーとバッチ

すべてのワーカーには *_ENABLED スイッチと *_INTERVAL_SECONDS による実行間隔があり、多くのワーカーには、何も見つからなかったパスの後にスリープする *_IDLE_INTERVAL_SECONDS もあります(ワーカーのリファレンス)。間隔を短くするとバックグラウンド処理の遅延は小さくなりますが、スキャンの回数が増えます。アイドル間隔により、空のキューの負荷は低く抑えられます。

ワーカー 調整項目
embedding_worker LOOM_EMBEDDING_WORKER_INTERVAL_SECONDS、_IDLE_INTERVAL_SECONDS。LOOM_EMBEDDING_WORKER_ORPHAN_FULL_SCAN_SECONDS / _ORPHAN_RECENT_SECONDS は孤立レコードのアンチジョインの範囲を制限します。
extraction_queue LOOM_EXTRACTION_QUEUE_INTERVAL_SECONDS、_MAX_BATCHES_PER_PASS、_NAMESPACE_CONCURRENCY、_LEASE_SECONDS。LOOM_EXTRACTION_DEFER_AGENTS は、列挙したエージェントの set_from_messages を後回しにし、抽出の前にリクエストが返るようにします。
memory_expiry_sweep LOOM_MEMORY_EXPIRY_SWEEP_BATCH_SIZE。
task_lease_sweep LOOM_TASK_LEASE_SWEEP_INTERVAL_SECONDS、_IDLE_INTERVAL_SECONDS。

ワーカーは background トラフィッククラスで動作するため、LOOM_CH_SETTINGS_BY_TRAFFIC_CLASS でも ClickHouse の優先度とスレッド数が制限されます。ワーカープロセスは必ず 1 つだけ実行してください。LLM を使うワーカーを 2 つ起動すると、スキャンとコストが 2 倍になります。コードプレーンのインジェストワーカーとコンパイラティアのワーカーには、それぞれ独自の調整項目があります(コードインデックスの運用)。

クライアント側の調整項目

大きな効果が得られるものの多くは、リクエスト側にあります。

  • 取得する本文を減らす:memory.search では bodies と body_budget_tokens、context.pack と code.search では token_budget を指定します。
  • ステップごとに検索するのではなく、タスクごとに一度だけコンテキストを読み込む(context.pack)。
  • retrieval_budget を使って、呼び出しごとに低コストな検索プロファイルか、より深い検索プロファイルを選ぶ。
  • 冪等な op は Idempotency-Key ヘッダー付きで再試行する(SDK が自動で生成します)。リプレイすると、op を再実行せずに保存済みのレスポンスが返されます。

関連項目