qdrant-multitenancy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Qdrant Multitenancy

Qdrant 多租户架构

Multitenancy is how you isolate data across multiple users or tenants within a single Qdrant deployment.

The question to ask is: how many tenants, and how unevenly sized are they? That answer picks the isolation strategy.
Understand the three isolation levels before choosing: payload-based, shard-based and collection-based.
For almost everyone the right default is a single collection partitioned by payload, NOT a collection per tenant.

多租户（Multitenancy）指的是在单个Qdrant部署中实现多用户或多租户之间的数据隔离。

核心问题是：租户数量有多少，各租户的数据量差异有多大？ 答案将决定应采用哪种隔离策略。
在选择策略前，需了解三种隔离级别：基于负载（payload-based）、基于分片（shard-based）和基于集合（collection-based）。
对于绝大多数用户，默认的正确选择是采用单集合并通过负载分区，而非为每个租户创建单独集合。

Many Small Tenants (Default: Payload Partitioning)

大量小型租户（默认方案：负载分区）

Use when: you have many tenants of roughly similar, modest size. This is the recommended default for most users.

One collection holds every tenant. A payload field marks ownership, and a filter on that field at query time is what isolates each tenant's results.

适用场景：拥有大量数据量相近、规模适中的租户。这是推荐给大多数用户的默认方案。

单个集合存储所有租户的数据。通过一个负载字段标记数据所属租户，查询时通过该字段的过滤器实现各租户结果的隔离。

How It Works

实现方式

Create a keyword payload index on the tenant field with
```
is_tenant=true
```
(the flag requires v1.11+).
```
is_tenant
```
tells Qdrant the field identifies tenants, so each tenant's vectors are stored together and served by sequential reads. Check .
At query time, isolate each tenant with a
```
must
```
filter on the tenant field. Without it, a query searches every tenant's data. Check Payload-based multitenancy.
With this strategy, the indexing speed might become a bottleneck at scale because every tenant indexes into the same collection. To avoid this, you can disable the global HNSW creation (for the entire collection) and only build per-tenant indexes: set
```
m=0
```
and
```
payload_m
```
to a non-zero value. Although this accelerates the indexing process, keep in mind that requests without a tenant filter will become slower as they must scan all groups. So only make this trade if you hit the bottleneck and cross-tenant search is rare. Calibrate performance.

在租户字段上创建关键字负载索引，并设置
```
is_tenant=true
```
（该标记需要v1.11及以上版本）。
```
is_tenant
```
用于告知Qdrant该字段用于标识租户，因此每个租户的向量会被存储在一起，并通过顺序读取提供服务。详情请查看创建字段索引。
查询时，通过对租户字段设置
```
must
```
过滤器来隔离各租户。如果不设置该过滤器，查询会检索所有租户的数据。详情请查看基于负载的多租户。
采用该策略时，当规模扩大后，索引速度可能会成为瓶颈，因为所有租户都在同一个集合中建立索引。为避免此问题，你可以禁用全局HNSW索引（针对整个集合），仅构建租户级索引：设置
```
m=0
```
并将
```
payload_m
```
设为非零值。虽然这会加快索引过程，但需注意，未设置租户过滤器的请求会变慢，因为必须扫描所有分组。因此仅当遇到瓶颈且跨租户搜索很少发生时，才建议进行此权衡。详情请查看性能校准。

A Few Large Tenants Plus a Long Tail (Tiered Multitenancy)

少量大型租户加大量小型租户（分层多租户）

Use when: you have a realistic SaaS distribution: a few large customers and many small ones, possibly with small tenants that grow over time. Available in v1.16+. It avoids the noisy-neighbor problem, where one big tenant forces the whole cluster to scale, raising costs and degrading performance for everyone else.

Tiered multitenancy keeps small tenants together in a shared fallback shard while isolating large tenants in their own dedicated shards, all in one collection. It layers two isolation levels: payload-based tenancy for logical isolation, and custom sharding for physical/ resource-based isolation of the large tenants. A tenant that outgrows the shared shard can be promoted to a dedicated shard later with no downtime.

适用场景：符合典型SaaS分布模式：少量大型客户和大量小型客户，部分小型租户可能会随时间增长。该方案适用于v1.16及以上版本。它可以避免“噪声邻居”问题，即某个大型租户迫使整个集群扩容，从而增加成本并降低其他租户的性能。

分层多租户将小型租户集中存储在一个共享的备用分片，同时将大型租户隔离在各自的专用分片，所有数据都位于同一个集合中。它融合了两种隔离级别：基于负载的租户隔离实现逻辑隔离，自定义分片实现大型租户的物理/资源隔离。当某个租户的数据量超出共享分片的承载能力时，可以将其升级到专用分片，且过程中不会中断服务。

How It Works

实现方式

Create the collection with custom (user-defined) sharding, and configure payload-based tenancy. A single shared fallback shard holds all the small tenants. If you have large tenants, create dedicated shards (one per tenant). Check Tiered multitenancy.
When to promote a tenant? If a tenant becomes large enough to warrant dedicated resources (a reasonable promotion trigger is when a tenant approaches the indexing threshold), promote it to a dedicated shard. Qdrant moves its data into a new shard transparently, serving reads and writes throughout. Check how to promote tenant to dedicated shard.
Keep in mind that re-sharding can be an expensive and time-consuming process, so consider your tenant growth patterns carefully when deciding which tenants should receive dedicated shards.
It's not recommended to exceed ~1000 dedicated shards per cluster (resource overhead).
The fallback shard (small tenants) must fit on a single node.
Sharding method is fixed at collection creation: an auto-sharded collection (default) cannot be converted to custom sharding in place. If there is any realistic chance you will need to isolate a large tenant later, create the collection with custom sharding up front and put every tenant in the fallback shard.

创建集合时启用自定义（用户定义）分片，并配置基于负载的租户隔离。单个共享备用分片存储所有小型租户的数据。如果存在大型租户，则为每个大型租户创建专用分片。详情请查看分层多租户。
何时升级租户？当租户的数据量足够大，需要专用资源时（合理的升级触发条件是租户数据量接近索引阈值），将其升级到专用分片。Qdrant会透明地将数据迁移到新分片，迁移过程中仍可正常处理读写请求。详情请查看如何将租户升级到专用分片。
需注意，重新分片是一项成本高且耗时的操作，因此在决定为哪些租户分配专用分片时，需仔细考虑租户的增长模式。
不建议每个集群的专用分片数量超过约1000个（会产生资源开销）。
备用分片（存储小型租户数据）必须能容纳在单个节点上。
分片方式在集合创建时即固定：默认的自动分片集合无法就地转换为自定义分片。如果未来有可能需要隔离大型租户，建议在创建集合时直接启用自定义分片，并将所有租户初始放在备用分片。

Few Non-Homogenous Tenants (Collection per Tenant)

少量非同质化租户（每个租户一个集合）

Use when: you have a limited number of tenants with different per-tenant embedding models or collection schemas.

You should only create multiple collections when your data is not homogenous or if users' vectors are created by different embedding models.

适用场景：租户数量有限，且各租户使用不同的嵌入模型或集合 schema。

仅当数据非同质化，或用户的向量由不同嵌入模型生成时，才应创建多个集合。

Data Residency and Geographic Isolation (Custom Sharding)

数据驻留与地理隔离（自定义分片）

Use when: data must be physically pinned to a location, e.g. regional compliance for healthcare industry (one region's data in Canada, another's in Germany). This is not only a tenant concern, a single tenant may also need to separate its own data by region.

Like tiered multitenancy, this uses custom sharding; the difference is what you shard by. Here the shard key is a region. Each key's data lands on specific shards you can place in specific locations, while everything stays in one collection. Combine it with payload partitioning if you also need per-tenant isolation within a region. Check User-defined sharding for setup.
Geographic residency follows only if your cluster's nodes are actually in the target regions.
Qdrant Cloud deploys a cluster in a single region and has no managed multi-region today.

适用场景：数据必须物理存储在特定位置，例如医疗行业的区域合规要求（某一区域的数据存放在加拿大，另一区域的数据存放在德国）。这不仅是租户隔离的问题，单个租户也可能需要按区域分隔自己的数据。

与分层多租户类似，该方案使用自定义分片；不同之处在于分片的依据。这里的分片键是区域。每个区域对应的数据会存储在特定分片，你可以将这些分片部署在特定位置，所有数据仍位于同一个集合中。如果还需要在区域内实现租户隔离，可以结合负载分区方案。详情请查看用户定义分片进行设置。
只有当集群节点实际部署在目标区域时，才能实现数据的地理驻留。
Qdrant Cloud 当前仅支持在单个区域部署集群，暂无托管多区域集群服务。

What NOT to Do

注意事项

Treat a payload filter as your whole security model. In Qdrant, (unless you're using per-tenant collections), tenant isolation is payload-based. It is an application-layer responsibility, and the filter is only one small part of it.

不要将负载过滤器视为完整的安全模型。在Qdrant中（除非使用每个租户一个集合的方案），租户隔离是基于负载的，这属于应用层的责任，而过滤器只是其中一小部分。