ベクトルIDの設計方針

1. なぜ「ベクトル ID」が重要か

Pinecone では ID がプライマリキーとして機能し、次の 3 つのオペレーションで必須となります。

ID 設計を誤ると 重複・更新漏れ・運用コスト増 が発生するため、スキーマ設計の最初に方針を固めることが推奨されます。

---

2. Pinecone が課す仕様・制約

---

3. 設計ガイドライン

1. 構造化 ID を採用する

   • 推奨形式: documentId#chunkNo など、人間が読めるプレフィックスを含める

   • Pinecone 公式も「接頭辞付きの可読 ID」をベストプラクティスとして挙げている docs.pinecone.io

2. 区切り文字を決めて固定する

   • # / _ / : など、ID 本体に現れない文字を 1 つ選択し全レコードで統一

   • リスト API の prefix パラメータと組み合わせると tenant1# だけを一括取得できる

3. ドキュメント単位のチャンク管理

   目的	ID 例	効果
   同一文書のチャンク特定	doc42#chunk3	list→fetch で一括取得
   版管理	doc42@v2#chunk3	旧版と新板を共存させロールバック容易
   マルチテナンシ	tenantA#doc42#chunk3	テナントごとに list で区切れる

4. 衝突回避戦略

   • URL や外部 ID など「自然キー」を流用する場合は ハッシュ化して長さを一定に

   • ランダムに生成する場合は UUIDv4 だけでなく、用途プレフィックスを付ける
     例: img_5f0488d9-…, user_0031d4b4-…

5. 更新・削除を前提にした粒度

   • Pinecone の検索 (query) は ID をキーに厳密ヒットさせる保証がないため（類似度検索）
     確実に 1 件を取得したい場合は fetch を使う docs.pinecone.io

   • したがって ID で fetch ⇒ vector 差し替え というワークフローを取れるよう ID を安定化させる

6. セキュリティ・プライバシ

   • PII を含めない（例: メールアドレスそのものを ID にしない）

   • どうしても自然キーを使うなら、暗号学的ハッシュ＋プレフィックスで可逆性を排除する

---

4. よくあるアンチパターン

---

5. 実装イメージ（Python SDK）

python
import uuid, hashlib
from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")
index = pc.Index(host="INDEX_HOST")

def gen_doc_id(url: str) -> str:
    """URL を SHA-256 → 16 進 32 桁に圧縮し doc_ プレフィックスを付与"""
    digest = hashlib.sha256(url.encode()).hexdigest()[:32]
    return f"doc_{digest}"

def upsert_chunks(url: str, chunks: list[str]):
    base_id = gen_doc_id(url)
    vectors = []
    for i, chunk in enumerate(chunks, start=1):
        vectors.append({
            "id": f"{base_id}#chunk{i}",
            "values": embed(chunk),            # 任意の埋め込み関数
            "metadata": {
                "source_url": url,
                "chunk_no": i,
            }
        })
    index.upsert(namespace="prod", vectors=vectors)

---

6. まとめチェックリスト

この方針を採用することで、更新・削除の容易さ、スケールアウト時の運用性、セキュリティ をすべて担保した ID 設計が実現できます。