跳到主要内容
Ed. notes

向量与入库:接口、维度与索引元数据

长文 · 2026-11-11 · 合集第 7 / 11 篇

  • Embedding
  • pgvector
  • RAG
第 7 / 11 篇 · 查看全部章节 → 当前:向量与入库:接口、维度与索引元数据

结论

向量入库不是“调一次模型再 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 怎样把最相近的切片和可引用信息取回来。