大模型应用开发 / 系统课时

建立向量索引

建立向量索引

学习目标

完成本课后,你将能够:

  • 批量调用 Ollama 嵌入接口生成向量
  • 把向量、文本和元数据一并保存
  • 验证向量数量、维度和模型版本
  • 为更新、删除和重建建立索引清单

索引记录的最小结构

每条索引记录至少包含:

  • chunk_id
  • 原始文本
  • 来源和权限元数据
  • 向量
  • 嵌入模型名称
  • 向量维度
  • 内容摘要
  • 索引时间

只保存向量而不保存原文和来源,无法组装上下文或展示引用。

准备嵌入模型

执行:

bash
ollama pull embeddinggemma

预期输出最终包含:

text
success

验证:

bash
ollama show embeddinggemma

预期结果:

text
返回嵌入模型详情和 embedding 能力。

建立本地 JSON 索引

保存为 build_index.py:

python
import hashlib
import json
from pathlib import Path
import urllib.request

MODEL = "embeddinggemma"
URL = "http://localhost:11434/api/embed"
OUTPUT = Path("vector-index.json")

chunks = [
    {
        "chunk_id": "ollama-001",
        "source": "ollama-guide",
        "title": "默认 API",
        "text": "Ollama 本地 API 默认地址是 http://localhost:11434。",
    },
    {
        "chunk_id": "ollama-002",
        "source": "ollama-guide",
        "title": "模型列表",
        "text": "使用 ollama list 可以查看本地已经下载的模型。",
    },
    {
        "chunk_id": "ollama-003",
        "source": "ollama-guide",
        "title": "运行状态",
        "text": "使用 ollama ps 可以查看当前加载到内存的模型。",
    },
]

payload = {
    "model": MODEL,
    "input": [item["text"] for item in chunks],
    "truncate": False,
}

request = urllib.request.Request(
    URL,
    data=json.dumps(payload).encode("utf-8"),
    headers={"Content-Type": "application/json"},
)

with urllib.request.urlopen(request, timeout=180) as response:
    result = json.load(response)

vectors = result["embeddings"]
if len(vectors) != len(chunks):
    raise RuntimeError("向量数量与文本块数量不一致")

dimensions = {len(vector) for vector in vectors}
if len(dimensions) != 1:
    raise RuntimeError(f"向量维度不一致: {dimensions}")

records = []
for chunk, vector in zip(chunks, vectors, strict=True):
    records.append(
        {
            **chunk,
            "content_hash": hashlib.sha256(
                chunk["text"].encode("utf-8")
            ).hexdigest(),
            "embedding_model": MODEL,
            "dimensions": len(vector),
            "embedding": vector,
        }
    )

OUTPUT.write_text(
    json.dumps(records, ensure_ascii=False),
    encoding="utf-8",
)
print(f"records={len(records)}")
print(f"dimensions={records[0]['dimensions']}")
print(f"output={OUTPUT}")

运行:

bash
python build_index.py

预期输出结构:

text
records=3
dimensions=<DIMENSIONS>
output=vector-index.json

验证索引文件

执行:

bash
python -m json.tool vector-index.json > /dev/null && echo valid

预期输出:

text
valid

Windows PowerShell 也可以运行同一 Python 命令。

批量大小

批量请求可以减少 HTTP 往返,但批次过大会增加请求体、内存和失败重试成本。建议:

  • 按文本总 Token 或字符数控制批次。
  • 每批保存进度。
  • 失败时只重试当前批次。
  • 为每条文本保留原始顺序。
  • 检查返回向量数量。
  • 记录模型和维度。

生产向量存储

JSON 文件只适合教学和小数据。生产可选择支持向量索引的数据库或专用向量存储,并考虑:

  • 相似度类型
  • 元数据过滤
  • 索引构建时间
  • 增量写入
  • 删除与更新
  • 备份和恢复
  • 多租户隔离
  • 数据规模和延迟

存储选型不能改变嵌入模型的一致性要求。

重建条件

以下变化通常需要重建全部或部分向量:

  • 更换嵌入模型
  • 模型版本或维度变化
  • 修改清洗和切分策略
  • 文档内容变化
  • 权限元数据变化
  • 归一化方式变化
  • 删除文档

索引清单应记录这些版本,避免新旧向量混用。

本课练习

练习 1:索引 100 个文本块

任务目标:实现批量和进度。输入或初始条件:准备 100 条测试数据。实现要求:分批生成并断点保存。验收条件:中途失败后从未完成批次继续。

练习 2:验证维度一致性

任务目标:防止混合模型。输入或初始条件:准备两个嵌入模型。实现要求:尝试混合写入并主动拒绝。验收条件:索引只包含一种模型与维度。

练习 3:实现文档删除

任务目标:维护索引生命周期。输入或初始条件:一个文档对应多个块。实现要求:按 document_id 删除全部记录。验收条件:检索不再返回该文档。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立向量索引

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通