Qdrant Cloud 免费单节点向量库额度申请教程与 RAG 接入指南

接口形态与鉴权

Qdrant Cloud 是向量数据库的托管服务，本身不提供对话补全接口：它对外是检索 API，REST 默认走 6333 端口，gRPC 走 6334 端口，base_url 形如 https://集群标识.区域.cloud.qdrant.io:6333，完整地址请直接在控制台集群概览页复制。鉴权方式是请求头带上控制台生成的 API Key。先把地址和密钥写进环境变量，后续所有调用都复用：

export QDRANT_URL="https://集群标识.区域.cloud.qdrant.io:6333"
export QDRANT_API_KEY="在控制台生成的 API Key"

用一条最简单的请求验证连通性与密钥是否有效：

curl -s "$QDRANT_URL/collections" \
  -H "api-key: $QDRANT_API_KEY"

返回 JSON 中带 result 字段即为正常；返回 403 说明密钥错误或没有该集群权限，返回连接超时则多半是集群处于暂停状态。

嵌入模型从哪里来

Qdrant 只存向量、不强制你用它生成的向量。免费档附带一定额度的 Cloud Inference，可以在控制台的推理（Inference）页面查看当前免费可用的模型清单与调用方式，具体模型名与额度以控制台实际显示为准；也可以完全绕开它，用任意第三方嵌入接口或本地 sentence-transformers 在客户端算好向量再写入。无论哪种方式，集合的向量维度必须和所选嵌入模型的输出维度一致，例如 all-MiniLM-L6-v2 输出 384 维，其他模型以官方模型卡为准。

建集合、写数据与检索调用

先安装官方客户端，再跑下面这段最小可用示例。真正影响检索质量的参数集中在 query_points 这一层：collection_name 指定集合，query 传入查询向量，limit 控制返回条数，with_payload 决定是否回传原文，score_threshold 用来过滤低分结果，避免把噪声塞进大模型上下文。

pip install qdrant-client

import os
from qdrant_client import QdrantClient, models

client = QdrantClient(
    url=os.environ["QDRANT_URL"],
    api_key=os.environ["QDRANT_API_KEY"],
    timeout=60,
)

client.create_collection(
    collection_name="docs",
    vectors_config=models.VectorParams(size=384, distance=models.Distance.COSINE),
)

client.upsert(
    collection_name="docs",
    points=[
        models.PointStruct(
            id=1,
            vector=[0.01] * 384,
            payload={"text": "示例文档正文", "source": "manual"},
        ),
    ],
)

hits = client.query_points(
    collection_name="docs",
    query=[0.01] * 384,
    limit=5,
    with_payload=True,
    score_threshold=0.3,
).points

for hit in hits:
    print(hit.score, hit.payload["text"])

接到对话链路时，标准做法是：用户提问 → 用同一个嵌入模型把问题转成向量 → 调 query_points 取前若干条原文 → 把原文拼进提示词 → 再交给大模型生成回答。检索返回的 score 只用于排序和过滤，不参与提示词。

额度耗尽与限流的典型表现与排查顺序

1. 先看集群状态：控制台显示暂停（Suspended）是最常见原因，免费集群闲置约一周会被暂停，登录控制台手动恢复即可，数据仍在；若已超过保留期则可能已被删除。
2. 再看返回码：403 多为 API Key 填错或权限不足；429 表示触发速率或并发限制，需要降低并发、加退避重试；503 或连接超时多看集群是否在恢复中。
3. 核对地址与端口：REST 用 6333、gRPC 用 6334，混用会直接连不上；地址要从控制台复制，不要手工拼区域名。
4. 检查资源是否打满：免费档只有 0.5 vCPU 与 1 GB 内存，批量写入过大容易写入失败或超时，改为每批几百条并降低并发。
5. 最后看用量页：推理额度与存储用量在控制台查看，接近上限时先降级到客户端本地算向量，或清理无用集合。

免费档的额度和保留策略可能调整，接入前请以定价页与控制台实际显示为准；重要数据务必自己定期导出备份。