feat(migrations): HNSW index for 1024-dim embeddings (bge-m3)

Upstream's 000002 only adds HNSW partial indexes for dim=3584 (OpenAI
text-embedding-3-large) and dim=798. Any deployment binding bge-m3 (the
default local embedder · 1024 dim · what localhub-embedder ships) falls
back to a sequential scan of the entire embeddings table on every vector
query. Functionally correct, but ~100-500ms per query depending on KB
size · dominates p50 latency on chat/agent paths.

Add a partial HNSW index targeting dim=1024 with the same expression and
opclass as the other two (embedding::halfvec(1024) halfvec_cosine_ops).
Matches the SearchEmbedding query in repository.go verbatim so the
planner picks it up automatically.

Local measurement on a 63k-row embeddings table (Robustel_Support KB):
  before · seq scan: ~100-500ms per vector query (varies)
  after  · index scan: ~28-30ms

CONCURRENTLY is skipped because plpgsql DO blocks open an implicit
transaction and CREATE INDEX CONCURRENTLY cannot run inside one. On
fresh installs the embeddings table is empty so this is instant. For
production backfill the operator should build the index manually using
CONCURRENTLY first; the IF NOT EXISTS guard then makes this migration a
no-op.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
toy0116
2026-06-05 08:06:44 +08:00
committed by lyingbug
parent bbf7ac29bf
commit 3fee3a454d
2 changed files with 41 additions and 0 deletions
@@ -0,0 +1,2 @@
-- Down migration: drop the 1024-dim HNSW partial index added in 000044.
DROP INDEX IF EXISTS embeddings_embedding_idx_1024;
@@ -0,0 +1,39 @@
-- Migration 000044: HNSW index for bge-m3 / 1024-dim embeddings
--
-- Upstream's 000002 only created HNSW partial indexes for dim=3584 (OpenAI
-- text-embedding-3-large) and dim=798. Both queries fall through to a
-- sequential scan on the 1024-dim halfvec column when the bound embedder
-- is bge-m3 — which is the default for any on-device deployment using
-- localhub-embedder.
--
-- Symptom: vector recall stays "correct but slow" (seq scan of all rows in
-- the embeddings table per query, ~100-500ms by KB size). Downstream agents
-- that probe latency-sensitive endpoints assumed degradation.
--
-- Fix: same partial-index pattern, dim=1024. Matches the exact expression
-- used in repository.go SearchEmbedding query (embedding::halfvec(1024) <=>
-- $1::halfvec(1024)) so the planner picks it up automatically.
--
-- Note: CONCURRENTLY is not used here because plpgsql DO blocks open an
-- implicit transaction and CREATE INDEX CONCURRENTLY can't run inside one.
-- For a fresh install this is a no-op (empty table); for production
-- backfill the operator should build the index manually using
-- CREATE INDEX CONCURRENTLY before applying this migration, then this
-- block becomes idempotent via IF NOT EXISTS.
DO $$
BEGIN
IF EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'vector') THEN
IF NOT EXISTS (SELECT 1 FROM pg_indexes WHERE indexname = 'embeddings_embedding_idx_1024' OR indexname LIKE 'embeddings_embedding%1024%') THEN
CREATE INDEX embeddings_embedding_idx_1024 ON embeddings
USING hnsw ((embedding::halfvec(1024)) halfvec_cosine_ops)
WITH (m = 16, ef_construction = 64)
WHERE (dimension = 1024);
RAISE NOTICE '[Migration 000044] Created HNSW index for dimension 1024 (bge-m3)';
ELSE
RAISE NOTICE '[Migration 000044] HNSW index for dimension 1024 already exists';
END IF;
ELSE
RAISE NOTICE '[Migration 000044] pgvector extension not installed · skipping';
END IF;
END $$;