Fix embedding vector dimension mismatch (768 -> 2560) #157

Merged

forgejo_admin merged 1 commit from 156-fix-embedding-vector-dimension-mismatch into main

2026-03-14 17:03:14 +00:00

forgejo_admin commented

2026-03-14 15:10:18 +00:00

Owner

Summary

The qwen3-embedding:4b model produces 2560-dimensional vectors, but the blocks.embedding column was defined as vector(768) from the initial setup. This caused every embedding attempt to fail with "expected 768 dimensions, not 2560". This PR updates the column type and resets errored blocks for retry.

Changes

alembic/versions/o5j6k7l8m9n0_fix_embedding_vector_dimension.py -- New Alembic migration that ALTERs blocks.embedding from vector(768) to vector(2560) and resets all embedding_status = 'error' blocks back to 'pending'
src/pal_e_docs/models.py -- Updated Block.embedding column definition from Vector(768) to Vector(2560)
src/pal_e_docs/embedding_worker.py -- Updated docstring from "768 floats" to "2560 floats"

Test Plan

pytest tests/ -v -- 497 passed
ruff check + ruff format --check -- all clean
Grep for remaining 768 in src/ and tests/ -- none found
After deploy: verify embedding worker processes blocks without dimension errors

Review Checklist

No unrelated changes
Migration is safe (all existing embeddings are NULL)
Downgrade path documented (will fail if 2560-dim data exists)
Old Alembic migration left untouched (historical record)

Plan: plan-pal-e-docs (Phase 5a)
Forgejo issue: #156

Closes #156

## Summary The `qwen3-embedding:4b` model produces 2560-dimensional vectors, but the `blocks.embedding` column was defined as `vector(768)` from the initial setup. This caused every embedding attempt to fail with "expected 768 dimensions, not 2560". This PR updates the column type and resets errored blocks for retry. ## Changes - **`alembic/versions/o5j6k7l8m9n0_fix_embedding_vector_dimension.py`** -- New Alembic migration that ALTERs `blocks.embedding` from `vector(768)` to `vector(2560)` and resets all `embedding_status = 'error'` blocks back to `'pending'` - **`src/pal_e_docs/models.py`** -- Updated `Block.embedding` column definition from `Vector(768)` to `Vector(2560)` - **`src/pal_e_docs/embedding_worker.py`** -- Updated docstring from "768 floats" to "2560 floats" ## Test Plan - [x] `pytest tests/ -v` -- 497 passed - [x] `ruff check` + `ruff format --check` -- all clean - [x] Grep for remaining `768` in `src/` and `tests/` -- none found - [ ] After deploy: verify embedding worker processes blocks without dimension errors ## Review Checklist - [x] No unrelated changes - [x] Migration is safe (all existing embeddings are NULL) - [x] Downgrade path documented (will fail if 2560-dim data exists) - [x] Old Alembic migration left untouched (historical record) ## Related - Plan: `plan-pal-e-docs` (Phase 5a) - Forgejo issue: #156 Closes #156

forgejo_admin added 1 commit

2026-03-14 15:10:18 +00:00

Fix embedding vector dimension mismatch (768 -> 2560)

ci/woodpecker/pr/woodpecker Pipeline was successful

Details

4884eda9c5

qwen3-embedding:4b produces 2560-dim vectors, but the blocks.embedding
column was vector(768) from initial setup. This caused all embedding
attempts to error with "expected 768 dimensions, not 2560".

- Alembic migration: ALTER blocks.embedding to vector(2560)
- Alembic migration: reset errored blocks to pending for retry
- models.py: Vector(768) -> Vector(2560)
- embedding_worker.py: docstring 768 -> 2560

Closes #156

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

forgejo_admin commented

2026-03-14 15:10:45 +00:00

Author

Owner

Self-Review: LGTM

Files reviewed: 3/3

Migration -- correct down_revision chain, safe ALTER (all embeddings NULL), errored blocks reset to pending. Downgrade documented.
models.py -- Vector(768) -> Vector(2560), single-line change.
embedding_worker.py -- docstring accuracy fix only.

Checks passed:

497 tests pass
ruff lint + format clean
No remaining 768 references in src/ or tests/
HNSW index will auto-rebuild on ALTER column type change
No files touched outside issue scope

## Self-Review: LGTM **Files reviewed:** 3/3 1. **Migration** -- correct `down_revision` chain, safe ALTER (all embeddings NULL), errored blocks reset to pending. Downgrade documented. 2. **models.py** -- `Vector(768)` -> `Vector(2560)`, single-line change. 3. **embedding_worker.py** -- docstring accuracy fix only. **Checks passed:** - 497 tests pass - ruff lint + format clean - No remaining `768` references in `src/` or `tests/` - HNSW index will auto-rebuild on ALTER column type change - No files touched outside issue scope

forgejo_admin commented

2026-03-14 15:12:01 +00:00

Author

Owner

PR #157 Review

BLOCKERS

None.

NITS

Downgrade does not reset embedding_status -- The upgrade resets embedding_status = 'error' back to 'pending', but the downgrade only reverts the column type without reversing this status change. This is non-blocking because (a) downgrades are rare, (b) the status reset is idempotent and harmless even if the column reverts, and (c) the downgrade already carries a NOTE about failure if 2560-dim data exists. But for completeness, the downgrade could include UPDATE blocks SET embedding_status = 'error' WHERE embedding_status = 'pending' -- though this would incorrectly hit legitimately pending blocks, so leaving it out is arguably the right call. Noting for awareness only.

SOP COMPLIANCE

Branch named after issue -- 156-fix-embedding-vector-dimension-mismatch references issue #156
PR body follows template -- Has ## Summary, ## Changes, ## Test Plan, ## Related
Related references plan slug -- References plan-pal-e-docs (Phase 5a)
Closes #156 present -- Will auto-close the issue on merge
No secrets committed -- No .env files, credentials, or tokens in the diff
No scope creep -- Exactly 3 files changed, all directly related to the dimension fix
Old migration untouched -- l2g3h4i5j6k7_add_vector_embeddings.py is not modified (correct -- historical record)

Verification Summary

Migration correctness: ALTER TYPE is the correct Postgres operation for changing vector dimensions. Safe because all existing embeddings are NULL (worker was erroring on dimension mismatch before any could be stored).
Model matches migration: models.py line 207 now reads Vector(2560), consistent with the migration target.
No stale 768 references: Grep of src/ and tests/ returns zero hits for 768. All remaining 768 occurrences are in Alembic migration files only (historical + downgrade), which is correct.
Alembic chain valid: down_revision = "n4i5j6k7l8m9" correctly points to the latest migration (n4i5j6k7l8m9_replace_sprints_with_boards.py).
Test plan adequate: 497 tests passed, ruff clean, grep verification done. Post-deploy verification of the embedding worker is appropriately listed as a remaining step.

VERDICT: APPROVED

## PR #157 Review ### BLOCKERS None. ### NITS 1. **Downgrade does not reset `embedding_status`** -- The upgrade resets `embedding_status = 'error'` back to `'pending'`, but the downgrade only reverts the column type without reversing this status change. This is non-blocking because (a) downgrades are rare, (b) the status reset is idempotent and harmless even if the column reverts, and (c) the downgrade already carries a NOTE about failure if 2560-dim data exists. But for completeness, the downgrade could include `UPDATE blocks SET embedding_status = 'error' WHERE embedding_status = 'pending'` -- though this would incorrectly hit legitimately pending blocks, so leaving it out is arguably the right call. Noting for awareness only. ### SOP COMPLIANCE - [x] **Branch named after issue** -- `156-fix-embedding-vector-dimension-mismatch` references issue #156 - [x] **PR body follows template** -- Has ## Summary, ## Changes, ## Test Plan, ## Related - [x] **Related references plan slug** -- References `plan-pal-e-docs` (Phase 5a) - [x] **`Closes #156` present** -- Will auto-close the issue on merge - [x] **No secrets committed** -- No `.env` files, credentials, or tokens in the diff - [x] **No scope creep** -- Exactly 3 files changed, all directly related to the dimension fix - [x] **Old migration untouched** -- `l2g3h4i5j6k7_add_vector_embeddings.py` is not modified (correct -- historical record) ### Verification Summary - **Migration correctness**: ALTER TYPE is the correct Postgres operation for changing vector dimensions. Safe because all existing embeddings are NULL (worker was erroring on dimension mismatch before any could be stored). - **Model matches migration**: `models.py` line 207 now reads `Vector(2560)`, consistent with the migration target. - **No stale 768 references**: Grep of `src/` and `tests/` returns zero hits for `768`. All remaining `768` occurrences are in Alembic migration files only (historical + downgrade), which is correct. - **Alembic chain valid**: `down_revision = "n4i5j6k7l8m9"` correctly points to the latest migration (`n4i5j6k7l8m9_replace_sprints_with_boards.py`). - **Test plan adequate**: 497 tests passed, ruff clean, grep verification done. Post-deploy verification of the embedding worker is appropriately listed as a remaining step. ### VERDICT: APPROVED