第 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/storagebash
docker compose up -d
curl http://localhost:6333/health # 返回 OK 之类浏览器打开 http://localhost:6333/dashboard,能看到集合列表、点数、简单的查询界面。这个面板在调试时非常有用——不用写代码就能确认"到底有没有数据"。
3.2 建集合
集合(collection)要定两件事,建完不能改:
| 参数 | 说明 |
|---|---|
size | 向量维度,必须与 embedding 模型输出一致 |
distance | Cosine / 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 章 带孩子出门要准备什么…怎么判断这套召回是好是坏?
- 前两条必须真的相关(这里是"体温异常"和"发热"),说明链路通了;
- 第 4、5 条开始跑偏(营养、旅行),说明 Top-K 给到 5 条已经掺了噪声;
- 分数从 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 的三个参数、过滤的坑,以及什么时候必须重建索引。