向量与入库:接口、维度与索引元数据
结论
向量入库不是“调一次模型再 INSERT”。这里用统一 Embeddings 接口隔离提供方,先把全部切片和向量准备好,确认 provider / model / dimension 与现有索引一致,最后在一个事务里替换索引。模型失败时旧索引仍然可用。
问题与设计
入库和查询必须使用同一模型、同一维度,否则向量距离没有意义。换模型也不能只改环境变量,因为数据库里的旧向量仍属于旧空间。
另一个问题是外部模型可能超时。如果先删旧索引再请求模型,服务端一失败就会把可检索数据清空。因此顺序必须是:内容加载、切片、embedding 全部完成之后,才进入数据库替换。
关键代码
统一接口继承 LangChain 的 Embeddings:
class EmbeddingProvider(Embeddings):
name: str
model: str
dimension: int
两个实现:
FakeEmbeddingProvider:SHA-256 确定性向量,只用于验证管线。OpenAIEmbeddingProvider:包装OpenAIEmbeddings,对接 OpenAI 兼容服务。
真实提供方关闭 check_embedding_ctx_length,直接发送原文,避免非 OpenAI 服务不接受客户端 tokenizer 生成的 token ID。
入库向量不是直接使用 chunk.text,而是补上文章标题和章节路径:
def embedding_text(document: Document, chunk: Chunk) -> str:
headings = " / ".join(chunk.heading_path)
return f"{document.title}\n{headings}\n{chunk.text}"
维度校验在 provider 返回后立即执行:
def check_dimensions(vectors, *, expected: int, model: str = "") -> list[list[float]]:
for vector in vectors:
if len(vector) != expected:
raise EmbeddingDimensionError(
f"{model or '当前模型'} 返回 {len(vector)} 维向量,配置为 {expected} 维"
)
return vectors
索引元信息只有一行,记录当前向量空间:
if tuple(row) != (provider_name, model, dimension):
raise IndexMismatchError(
f"索引由 {row[0]} / {row[1] or '未记录模型'}({row[2]} 维)建立;"
"请使用 --recreate 重建索引"
)
入库顺序:
load_documents → chunk_document → embedding_text → 分批 embed
→ connect → init_schema → 检查 index_meta → 替换 chunks/documents → commit
_replace_index() 删除旧 chunks,更新 documents,再插入新 chunks 与 vectors。zip(chunks, vectors, strict=True) 保证切片数与向量数一致。
三张表分工:
documents:一篇内容一行,存 slug、标题、URL、日期、标签、正文 hash。chunks:一段内容一行,存文本、标题路径、位置、hash 和 vector。index_meta:整个索引一行,存 provider / model / dimension。
前端视角:把 dataclass 当 DTO,把这三张表当持久化 schema;当前项目没有 ORM,也没有 migration 工具,建表逻辑就是 db.py 里的 CREATE TABLE IF NOT EXISTS。
验证
用假向量重建测试库:
DATABASE_URL=postgresql://ednotes:ednotes@127.0.0.1:5432/ednotes_test \
EMBEDDING_PROVIDER=fake CONTENT_DIR=../content \
uv run python -m backend.ingest --recreate
入库完成:18 篇文档,131 个切片,fake-hash-v1 / 未记录模型 / 1024 维,耗时 0.25s
这里 1024 维来自测试库现有 schema;假 provider 也必须匹配维度,或通过 --recreate 重建。
边界
- 假向量不具备语义相似度,不能用来证明检索质量。
- 维度相同不代表向量空间相同,所以 provider 和 model 也写入
index_meta。 index_meta不记录 embedding 文本格式;修改embedding_text()后必须重新入库,否则会继续使用旧向量。--recreate会删表,是破坏性操作;只对本地或明确指定的测试/开发库执行。- 当前每次入库全量重写,不是增量索引;内容量大时要另做差异更新和回滚策略。
- 外部调用发生在数据库事务之前,避免长时间持锁;代价是全部向量暂存在内存。
下一篇看检索:向量写进去后,一条 SQL 怎样把最相近的切片和可引用信息取回来。