Qdrant向量搜索引擎的Python客户端库。
Python Qdrant客户端
Qdrant向量搜索引擎的客户端库和SDK。
该库包含所有Qdrant API的类型定义,并允许进行同步和异步请求。
客户端允许直接调用所有Qdrant API方法。 它还为一些常用操作提供了额外的辅助方法,例如初始集合上传。
更多详情请参阅快速入门!
API文档
Python客户端API文档可在python-client.qdrant.tech查看
安装
pip install qdrant-client
特性
- 所有API方法的类型提示
- 本地模式 - 无需运行服务器即可使用相同的API
- 支持REST和gRPC
- 最小化依赖
- 广泛的测试覆盖
本地模式
Python客户端允许您在不运行Qdrant服务器的情况下以本地模式运行相同的代码。
只需像这样初始化客户端:
from qdrant_client import QdrantClient
client = QdrantClient(":memory:")
# 或
client = QdrantClient(path="path/to/db") # 将更改持久化到磁盘
本地模式对于开发、原型设计和测试非常有用。
- 您可以在CI/CD管道中使用它来运行测试。
- 在Colab或Jupyter Notebook中运行,无需额外依赖。查看示例
- 当需要扩展时,只需切换到服务器模式。
快速嵌入 + 更简单的API
pip install qdrant-client[fastembed]
FastEmbed是一个用于在CPU上创建快速向量嵌入的库。它基于ONNX Runtime,允许在CPU上以类似GPU的性能运行推理。
Qdrant客户端可以使用FastEmbed创建嵌入并将其上传到Qdrant。这使得API更简单、更直观。
from qdrant_client import QdrantClient
# 初始化客户端
client = QdrantClient(":memory:") # 或 QdrantClient(path="path/to/db")
# 准备文档、元数据和ID
docs = ["Qdrant有Langchain集成", "Qdrant还有Llama Index集成"]
metadata = [
{"source": "Langchain-docs"},
{"source": "Linkedin-docs"},
]
ids = [42, 2]
# 使用新的add方法
client.add(
collection_name="demo_collection",
documents=docs,
metadata=metadata,
ids=ids
)
search_result = client.query(
collection_name="demo_collection",
query_text="这是一个查询文档"
)
print(search_result)
FastEmbed还可以利用GPU进行更快的嵌入。要启用GPU支持,请安装
pip install 'qdrant-client[fastembed-gpu]'
from qdrant_client import QdrantClient
# 初始化客户端
client = QdrantClient(":memory:") # 或 QdrantClient(path="path/to/db")
client.set_model(client.DEFAULT_EMBEDDING_MODEL, providers=["CUDAExecutionProvider", "CPUExecutionProvider"])
注意:
fastembed-gpu
和fastembed
是互斥的。您只能安装其中一个。如果您之前安装了
fastembed
,可能需要从一个全新的环境开始安装fastembed-gpu
。
连接到Qdrant服务器
要连接到Qdrant服务器,只需指定主机和端口:
from qdrant_client import QdrantClient
client = QdrantClient(host="localhost", port=6333)
# 或
client = QdrantClient(url="http://localhost:6333")
您可以使用Docker在本地运行Qdrant服务器:
docker run -p 6333:6333 qdrant/qdrant:latest
在Qdrant仓库中查看更多启动选项。
连接到Qdrant云
您可以注册并使用Qdrant云获得1GB RAM的免费账户。
一旦您有了集群和API密钥,您可以像这样连接:
from qdrant_client import QdrantClient
qdrant_client = QdrantClient(
url="https://xxxxxx-xxxxx-xxxxx-xxxx-xxxxxxxxx.us-east.aws.cloud.qdrant.io:6333",
api_key="<your-api-key>",
)
示例
创建新集合
from qdrant_client.models import Distance, VectorParams
client.create_collection(
collection_name="my_collection",
vectors_config=VectorParams(size=100, distance=Distance.COSINE),
)
向集合中插入向量
import numpy as np
from qdrant_client.models import PointStruct
vectors = np.random.rand(100, 100)
# 注意:考虑将数据分成多个块以避免超出服务器的有效负载大小限制
# 或使用`upload_collection`或`upload_points`方法,它们会为您处理这个问题
# 警告:逐个上传点不推荐,因为会产生请求开销
client.upsert(
collection_name="my_collection",
points=[
PointStruct(
id=idx,
vector=vector.tolist(),
payload={"color": "red", "rand_number": idx % 10}
)
for idx, vector in enumerate(vectors)
]
)
搜索相似向量
query_vector = np.random.rand(100)
hits = client.search(
collection_name="my_collection",
query_vector=query_vector,
limit=5 # 返回5个最接近的点
)
使用过滤条件搜索相似向量
from qdrant_client.models import Filter, FieldCondition, Range
hits = client.search(
collection_name="my_collection",
query_vector=query_vector,
query_filter=Filter(
must=[ # 这些条件是搜索结果所必需的
FieldCondition(
key='rand_number', # 基于`rand_number`字段值的条件
range=Range(
gte=3 # 只选择`rand_number` >= 3的结果
)
)
]
),
limit=5 # 返回5个最接近的点
)
在我们的文档中查看更多示例!
gRPC
要启用(通常更快的)使用gRPC的集合上传,请使用以下初始化:
from qdrant_client import QdrantClient
client = QdrantClient(host="localhost", grpc_port=6334, prefer_grpc=True)
异步客户端
从1.6.1版本开始,所有Python客户端方法都有异步版本可用。
要使用它,只需导入AsyncQdrantClient
而不是QdrantClient
:
from qdrant_client import AsyncQdrantClient, models
import numpy as np
import asyncio
async def main():
# 您的使用QdrantClient的异步代码可以放在这里
client = AsyncQdrantClient(url="http://localhost:6333")
await client.create_collection(
collection_name="my_collection",
vectors_config=models.VectorParams(size=10, distance=models.Distance.COSINE),
)
await client.upsert(
collection_name="my_collection",
points=[
models.PointStruct(
id=i,
vector=np.random.rand(10).tolist(),
)
for i in range(100)
],
)
res = await client.search(
collection_name="my_collection",
query_vector=np.random.rand(10).tolist(), # type: ignore
limit=10,
)
print(res)
asyncio.run(main())
在异步模式下,gRPC和REST API都受支持。 更多示例可以在这里找到。
开发
这个项目使用git hooks来运行代码格式化程序。
使用pip3 install pre-commit
安装pre-commit
,并使用pre-commit install
设置钩子。
pre-commit需要python>=3.8