大模型应用开发 / 系统课时
建立向量索引
建立向量索引
学习目标
完成本课后,你将能够:
- 批量调用 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
validWindows PowerShell 也可以运行同一 Python 命令。
批量大小
批量请求可以减少 HTTP 往返,但批次过大会增加请求体、内存和失败重试成本。建议:
- 按文本总 Token 或字符数控制批次。
- 每批保存进度。
- 失败时只重试当前批次。
- 为每条文本保留原始顺序。
- 检查返回向量数量。
- 记录模型和维度。
生产向量存储
JSON 文件只适合教学和小数据。生产可选择支持向量索引的数据库或专用向量存储,并考虑:
- 相似度类型
- 元数据过滤
- 索引构建时间
- 增量写入
- 删除与更新
- 备份和恢复
- 多租户隔离
- 数据规模和延迟
存储选型不能改变嵌入模型的一致性要求。
重建条件
以下变化通常需要重建全部或部分向量:
- 更换嵌入模型
- 模型版本或维度变化
- 修改清洗和切分策略
- 文档内容变化
- 权限元数据变化
- 归一化方式变化
- 删除文档
索引清单应记录这些版本,避免新旧向量混用。
本课练习
练习 1:索引 100 个文本块
任务目标:实现批量和进度。输入或初始条件:准备 100 条测试数据。实现要求:分批生成并断点保存。验收条件:中途失败后从未完成批次继续。
练习 2:验证维度一致性
任务目标:防止混合模型。输入或初始条件:准备两个嵌入模型。实现要求:尝试混合写入并主动拒绝。验收条件:索引只包含一种模型与维度。
练习 3:实现文档删除
任务目标:维护索引生命周期。输入或初始条件:一个文档对应多个块。实现要求:按 document_id 删除全部记录。验收条件:检索不再返回该文档。
按自己的节奏,确认真正理解。