Skip to content
Lv3向量数据库进度 3 / 7

第 3 章:最小可用,三十行跑通 ​

这一章不追求效果,只追求"跑通并看见结果"。能查到东西,后面所有调优才有参照。


学习目标 ​

  • 用 Docker 起一个 Qdrant,并能打开它的 Web 面板
  • 建一个集合,写清维度与距离度量
  • 灌入 1000 条带元数据的片段,做一次真实查询
  • 看懂返回结果里的分数,判断召回是好还是坏

3.1 起服务 ​

和 Redis 课一样,用 compose,四行就够:

yaml
services:
  qdrant:
    image: qdrant/qdrant:v1.12.4      # 版本号请按官方最新核对
    ports:
      - "6333:6333"                   # REST + Web 面板
      - "6334:6334"                   # gRPC
    volumes:
      - ./qdrant_storage:/qdrant/storage
bash
docker compose up -d
curl http://localhost:6333/health          # 返回 OK 之类

浏览器打开 http://localhost:6333/dashboard,能看到集合列表、点数、简单的查询界面。这个面板在调试时非常有用——不用写代码就能确认"到底有没有数据"。

一次查询,经过四个环节1. 文本"孩子发烧怎么办"用户原话2. Embedding512 个浮点数与入库同一个模型3. 向量库检索HNSW 走近似最近邻按分数排序返回 Top-K4. 结果id + 分数 + payload交给下一步使用第 2 步和第 3 步是最常见的出错点:模型不一致、维度不一致、距离度量写错。一次查询失败时,按这个顺序查:服务活着吗 → 集合有数据吗 → 维度对吗 → 查询向量是同一个模型吗。docker compose ps | curl :6333/collections | dashboard 看 points_count | 对比 len(vec)这四步能定位 90% 的"查不到东西"。

3.2 建集合 ​

集合(collection)要定两件事,建完不能改:

参数说明
size向量维度,必须与 embedding 模型输出一致
distanceCosine / Euclid / Dot / Manhattan
python
from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams

client = QdrantClient(url="http://localhost:6333")
client.create_collection(
    collection_name="books__bge_small_zh_v15",     # 把模型版本写进名字
    vectors_config=VectorParams(size=512, distance=Distance.COSINE),
)

集合名带模型版本,是个很土但很有效的习惯:以后换模型,新集合叫另一个名字,两套可以并存,切换时不用停机。


3.3 灌 1000 条 ​

我们的数据还是"小书店"那套:8 本书的正文切成 1000 个片段,每段带书名、章节、页码做 payload。

python
from qdrant_client.models import PointStruct
from sentence_transformers import SentenceTransformer

model = SentenceTransformer("BAAI/bge-small-zh-v1.5")

chunks = load_chunks()          # [{ "text": ..., "book": ..., "page": ... }, ...]
texts = [c["text"] for c in chunks]
vecs = model.encode(texts, batch_size=32, normalize_embeddings=True, show_progress_bar=True)

points = [
    PointStruct(id=i, vector=vecs[i].tolist(), payload={
        "text": chunks[i]["text"],
        "book": chunks[i]["book"],
        "page": chunks[i]["page"],
    })
    for i in range(len(chunks))
]
client.upsert(collection_name="books__bge_small_zh_v15", points=points, wait=True)

两个细节:

  • wait=True:等真正写入完成再返回,脚本里用它才不会被"数据还没进去就查询"骗到;
  • payload 里存原文。检索完直接能拼进提示词,不用再回数据库查一次。

3.4 查一次 ​

python
qvec = model.encode(["孩子发烧怎么办"], normalize_embeddings=True)[0].tolist()

res = client.query_points(
    collection_name="books__bge_small_zh_v15",
    query=qvec,
    limit=5,
    with_payload=True,
)
for p in res.points:
    print(round(p.score, 4), p.payload["book"], p.payload["page"], p.payload["text"][:40])

客户端版本差异:query_points 是较新的统一入口,旧版客户端用 client.search(...) 返回结构略有不同。跑之前先 pip show qdrant-client 看一眼版本。

输出大概长这样:

0.8123  《育儿手册》 第 3 章 婴幼儿体温异常的判断与处理…
0.7741  《家庭急救》 第 1 章 孩子突然发热,先看精神状态…
0.6502  《育儿手册》 第 5 章 退烧药的使用间隔…
0.5830  《营养指南》 第 2 章 儿童免疫力与饮食…
0.4117  《旅行随笔》 第 7 章 带孩子出门要准备什么…

怎么判断这套召回是好是坏?

  1. 前两条必须真的相关(这里是"体温异常"和"发热"),说明链路通了;
  2. 第 4、5 条开始跑偏(营养、旅行),说明 Top-K 给到 5 条已经掺了噪声;
  3. 分数从 0.81 掉到 0.41,中间有个明显的断崖——这个断崖位置,就是更合理的 K。

3.5 一个能复用的检索函数 ​

python
def search(query: str, k: int = 5, book: str | None = None):
    qvec = model.encode([query], normalize_embeddings=True)[0].tolist()
    flt = None
    if book:
        from qdrant_client.models import Filter, FieldCondition, MatchValue
        flt = Filter(must=[FieldCondition(key="book", match=MatchValue(value=book))])

    res = client.query_points(
        collection_name="books__bge_small_zh_v15",
        query=qvec, limit=k, query_filter=flt, with_payload=True,
    )
    return [(p.score, p.payload["text"]) for p in res.points]

那个 book 参数就是过滤:只在某一本书里搜。第 4 章会接着讲——过滤用不好,会让召回质量断崖式下跌。


3.6 首次建库的完整顺序 ​


本章小结 ​

要点说明
起服务compose 起 Qdrant,6333 是 REST 与面板
集合两件事维度、距离,建完不能改
集合命名带模型版本,方便并存与切换
灌数据批量 encode、wait=True、payload 存原文
查询query_points,看 Top-K 与分数
判断好坏前几条相关、分数断崖位置决定 K
过滤payload + Filter,下一章展开

下一章 ​

能查了,但"查得准不准、快不快"由参数决定。下一章讲 HNSW 的三个参数、过滤的坑,以及什么时候必须重建索引。

本文阅读--次|全站访问--次|访客--人