From 117185869670e62639378d0bc37c7c07a1e3f55d Mon Sep 17 00:00:00 2001 From: Codex_Lin_Lay Date: Mon, 7 Sep 2026 22:35:21 +0900 Subject: [PATCH] fix(docs): make doc-path index migration conditional MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit fresh install向け10枠割当と既存deploymentの実在indexを分離し、list確認後にだけ必要なmutationを行う手順へ修正した。 --- docs/0-requirements.ja.md | 2 +- docs/0-requirements.md | 2 +- docs/installation.ja.md | 16 +++++++++++++++- docs/installation.md | 16 +++++++++++++++- 4 files changed, 32 insertions(+), 4 deletions(-) diff --git a/docs/0-requirements.ja.md b/docs/0-requirements.ja.md index 15207c2..de05cce 100644 --- a/docs/0-requirements.ja.md +++ b/docs/0-requirements.ja.md @@ -286,7 +286,7 @@ Vectorize は hybrid retrieval の dense 側を担う。次の metadata を伴 - documentation path - commit SHA / file path / file status / commit date / commit author / blob SHA（diff only） -Metadata index（10/10 枠使用）: +fresh install向けmetadata index割当（platform上限10枠）: - Pre-filter 対応: repo, type, state, milestone, doc_path - 将来の pre-filter 用に格納: label_0, label_1, label_2, label_3, assignee_0 diff --git a/docs/0-requirements.md b/docs/0-requirements.md index f771acf..8ce3cd8 100644 --- a/docs/0-requirements.md +++ b/docs/0-requirements.md @@ -292,7 +292,7 @@ Vectorize is the dense side of hybrid retrieval. It stores semantic embeddings a - wiki page slug + extension (wiki_doc rows) - commit SHA, file path, file status, commit date, commit author, blob SHA (diff only) -Metadata indexes (10/10 slots used): +Fresh-install metadata index allocation (10/10 platform slots): - Pre-filter capable: repo, type, state, milestone, doc_path - Stored for future pre-filter: label_0, label_1, label_2, label_3, assignee_0 diff --git a/docs/installation.ja.md b/docs/installation.ja.md index c0fe6ee..36518b7 100644 --- a/docs/installation.ja.md +++ b/docs/installation.ja.md @@ -182,13 +182,27 @@ wrangler deploy vector 作成後に metadata index を追加した場合、stored hash を reset して次回 cron で全件 re-embed させる。 -既存 deployment が `assignee_1` を index 済みなら、`path_prefix` 対応の deploy 前に未使用の将来用 filter 枠を置き換える。 +既存 deployment はmetadata indexを変更する前に実在一覧を確認する。 + +```bash +wrangler vectorize list-metadata-index github-rag-issues +``` + +`doc_path` がすでに存在すれば変更不要。存在せず、一覧が10件未満なら何も削除せず追加する。 + +```bash +wrangler vectorize create-metadata-index github-rag-issues --type string --property-name doc_path +``` + +10枠すべて使用済みで、かつ `assignee_1` が一覧に実在する場合だけ、未使用の将来用 filter 枠を置き換える。 ```bash wrangler vectorize delete-metadata-index github-rag-issues --property-name assignee_1 wrangler vectorize create-metadata-index github-rag-issues --type string --property-name doc_path ``` +10枠使用済みでも `assignee_1` が実在しない場合は、別の未使用な将来用 index を明示的に選ぶ。production pre-filterを推測で削除しない。 + `doc_path` index 作成前に upsert 済みの vector は path filter の対象にならない。既存 doc に `path_prefix` を使う repository ごとに reset する。metadata index 作成後に追加する新しい固定コーパスには過去分の再 index は不要。 Admin endpoint: diff --git a/docs/installation.md b/docs/installation.md index aa450c8..52495a8 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -182,13 +182,27 @@ Recommended verification flow: If metadata indexes were created after vectors already existed, reset stored hashes so the next cron run re-embeds everything. -For an existing deployment that still indexes `assignee_1`, replace that unused future-filter slot before deploying `path_prefix` support: +Inspect an existing deployment before changing its metadata indexes: + +```bash +wrangler vectorize list-metadata-index github-rag-issues +``` + +If `doc_path` is already listed, no index mutation is needed. If it is absent and fewer than ten properties are listed, create it without deleting anything: + +```bash +wrangler vectorize create-metadata-index github-rag-issues --type string --property-name doc_path +``` + +Only when all ten slots are occupied **and** `assignee_1` is actually listed, replace that unused future-filter slot: ```bash wrangler vectorize delete-metadata-index github-rag-issues --property-name assignee_1 wrangler vectorize create-metadata-index github-rag-issues --type string --property-name doc_path ``` +If all ten slots are occupied but `assignee_1` is not listed, choose another unused future-filter index deliberately; do not delete a production pre-filter by assumption. + Vectors upserted before `doc_path` was indexed are not path-filterable. Reset each existing repository whose old docs must support `path_prefix`; a new fixed corpus added after the metadata index exists needs no historical re-index. Admin endpoint: