qdrant-migration-tool

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Qdrant Migration Tool

The tool is a Docker container (

registry.cloud.qdrant.io/library/qdrant-migration

), not a library you import. It streams data in batches through the machine it runs on rather than connecting source and target directly, and it resumes by default rather than restarting from scratch. Migrate to Qdrant

该工具是一个 Docker 容器（

registry.cloud.qdrant.io/library/qdrant-migration

），而不是需要 import 的库。它通过运行该工具的机器按批次流式传输数据，而不是直接连接源数据库和目标数据库；并且默认从中断处恢复，而不是从头重新开始。迁移到 Qdrant

Picking the Right Subcommand

选择合适的子命令

Use when: starting a new migration and choosing the source-specific CLI subcommand.

Match the source to its subcommand:
```
pinecone
```
,
```
weaviate
```
,
```
milvus
```
,
```
elasticsearch
```
,
```
opensearch
```
,
```
pg
```
(pgvector),
```
s3
```
(S3 Vectors),
```
azure
```
(Azure AI Search),
```
chroma
```
,
```
redis
```
,
```
mongodb
```
,
```
faiss
```
,
```
solr
```
, or
```
qdrant
```
. Migrate to Qdrant
Weaviate, Redis, MongoDB, and Apache Solr do not auto-create the target collection; create it in Qdrant first with matching vector size and distance metric before running the migration. All other sources auto-create it.
Each source has its own credential and mapping guide; read it before running the migration, since concept mapping (namespaces, indexes, metadata fields) is source-specific. Pinecone Weaviate Milvus Elasticsearch OpenSearch Azure AI search pgvector S3 Vectors Chroma Redis MongoDB FAISS Apache Solr Qdrant-to-Qdrant
Source not listed? Point to the GitHub issue tracker rather than improvising a custom pipeline. Open an issue

适用于：开始新的迁移并选择与源数据库对应的 CLI 子命令。

将源数据库与对应的子命令匹配：
```
pinecone
```
、
```
weaviate
```
、
```
milvus
```
、
```
elasticsearch
```
、
```
opensearch
```
、
```
pg
```
（pgvector）、
```
s3
```
（S3 Vectors）、
```
azure
```
（Azure AI Search）、
```
chroma
```
、
```
redis
```
、
```
mongodb
```
、
```
faiss
```
、
```
solr
```
或
```
qdrant
```
。迁移到 Qdrant
Weaviate、Redis、MongoDB 和 Apache Solr 不会自动创建目标 collection；运行迁移前，必须先在 Qdrant 中创建 collection，并确保向量大小和距离度量与源数据库一致。其他源数据库都会自动创建 collection。
每个源数据库都有自己的凭证和映射指南；运行迁移前应先阅读相应指南，因为概念映射（namespace、index 和 metadata field）因源数据库而异。Pinecone Weaviate Milvus Elasticsearch OpenSearch Azure AI Search pgvector S3 Vectors Chroma Redis MongoDB FAISS Apache Solr Qdrant-to-Qdrant
未列出源数据库？应引导用户前往 GitHub issue tracker，而不是临时设计自定义 pipeline。提交 issue

Running Against Local Instances

针对本地实例运行

Use when: either the source or target database runs on the same machine as the migration container.

Add
```
--net=host
```
to the
```
docker run
```
command; without it, the container cannot resolve
```
localhost
```
on the host machine. Migrate to Qdrant
Run the container on a machine with low latency to both databases. Direct source-target connectivity is not required since the tool streams through wherever it runs, but round trips from the migration host to each database still add up.

适用于：源数据库或目标数据库与 migration container 运行在同一台机器上。

在
```
docker run
```
命令中添加
```
--net=host
```
；否则，容器无法解析宿主机上的
```
localhost
```
。迁移到 Qdrant
应在与两个数据库延迟都较低的机器上运行容器。该工具通过其运行位置流式传输数据，因此不要求源数据库与目标数据库直接连通，但迁移主机分别访问两个数据库时产生的往返延迟仍会累积。

Migration Was Interrupted

迁移被中断

Use when: a migration stopped partway through and needs to continue, or needs to be re-run from zero.

Re-run the exact same command. Progress is tracked in the
```
_migration_offsets
```
collection in Qdrant, so it resumes automatically rather than re-copying already-migrated points.
Pass
```
--migration.restart
```
to discard saved progress and start over, e.g. after fixing a bad source-side filter or changing collection schema mid-migration.
Custom offsets-collection name only matters if you're running multiple concurrent migrations into the same Qdrant instance; otherwise leave
```
--migration.offsets-collection
```
at its default to avoid tracking state you'll forget to look for later.

适用于：迁移中途停止后需要继续，或需要从头重新运行。

重新运行完全相同的命令。迁移进度会记录在 Qdrant 的
```
_migration_offsets
```
collection 中，因此工具会自动恢复，而不会重新复制已经迁移的 point。
传入
```
--migration.restart
```
可丢弃已保存的进度并从头开始，例如修正了源端的 filter，或在迁移过程中更改了 collection schema。
仅当同时向同一个 Qdrant 实例执行多个迁移任务时，才需要自定义 offsets collection 名称；其他情况下应保留
```
--migration.offsets-collection
```
的默认值，避免以后需要排查问题时才想起还有一份状态记录。

Migration Is Too Slow

迁移速度太慢

Use when: throughput is too low for the size of the source dataset.

Raise
```
--migration.batch-size
```
from the default of 50 to 256 or 512 for large migrations; small batches under-use each upsert round trip.
```
--migration.num-workers
```
only exists for the
```
pg
```
and
```
qdrant
```
subcommands; other sources have no parallel-worker flag, so throughput there is bounded by batch size and network proximity alone.
```
--migration.batch-delay
```
defaults to 0; only raise it deliberately to throttle load on a source database that can't absorb full-speed reads, not as a default tuning knob.
Run the container close to both databases rather than over a slow network path, since the tool has no way to compensate for source/target latency.

适用于：源数据集规模较大，但迁移吞吐量过低。

对于大型迁移，可将
```
--migration.batch-size
```
从默认值 50 提高到 256 或 512；较小的批次无法充分利用每次 upsert 往返。
```
--migration.num-workers
```
仅适用于
```
pg
```
和
```
qdrant
```
子命令；其他源数据库没有并行 worker 参数，因此其吞吐量仅受 batch size 和网络距离限制。
```
--migration.batch-delay
```
的默认值为 0；只有在需要降低无法承受全速读取的源数据库负载时，才应有意提高该值，不应将其作为默认调优项。
应让容器靠近两个数据库运行，避免经过高延迟网络路径，因为该工具无法补偿源数据库或目标数据库的延迟。

After Migration

迁移完成后

Use when: the migration command finished and data needs to be trusted before cutting over traffic.

Run through the verification framework rather than spot-checking a few points: it covers pre-migration baselines, data integrity checks, and search-quality validation, not just point counts. Migration Verification Guide
If Postgres/pgvector stays live alongside Qdrant post-migration, set up an ongoing sync strategy (event-driven, batch, or dual-write) instead of treating the migration as a one-time cutover. Keeping Postgres in Sync

适用于：迁移命令已经完成，需要在切换流量前确认数据可信。

应执行完整的验证流程，而不是只抽查少量 point；该流程涵盖迁移前 baseline、数据完整性检查和搜索质量验证，不只是检查 point 数量。迁移验证指南
如果迁移后 Postgres/pgvector 仍与 Qdrant 并行运行，应建立持续同步策略（事件驱动、批量或 dual-write），而不是将迁移视为一次性切换。保持 Postgres 同步

What NOT to Do

不要执行的操作

Assume Weaviate, Redis, MongoDB, or Solr auto-create the target collection; these sources don't expose vector dimensions or distance metric to the tool, so the collection must be created manually first with settings that exactly match the source. Migrate to Qdrant
Point the
```
faiss
```
subcommand at a quantized FAISS index; only
```
IndexFlatL2
```
,
```
IndexFlatIP
```
,
```
IndexHNSWFlat
```
, and
```
IndexIVFFlat
```
are supported, since quantized indexes don't retain the original vectors. FAISS
Assume every Pinecone index can be migrated; only serverless indexes support the list operation the tool needs to enumerate vectors.Pinecone
Run a
```
qdrant
```
-to-
```
qdrant
```
migration into an existing target collection without checking its vector size first; source and target dimensions must match exactly, only replication and shard settings are allowed to differ.
Connect over TLS to a source or target signed by a private or self-signed CA without mounting it via
```
SSL_CERT_FILE
```
; the migration fails on certificate verification instead of degrading gracefully, and
```
--skip-tls-verification
```
should be a deliberate override, not a default fix.
Pass
```
--migration.restart
```
out of caution on a healthy resume; it discards saved progress and re-streams data that already migrated.
Treat a completed migration run as verified without running data integrity and search quality checks.

不要假设 Weaviate、Redis、MongoDB 或 Solr 会自动创建目标 collection；这些源数据库不会向该工具提供向量维度或距离度量，因此必须先手动创建 collection，并确保其设置与源数据库完全一致。迁移到 Qdrant
不要将
```
faiss
```
子命令指向量化后的 FAISS index；仅支持
```
IndexFlatL2
```
、
```
IndexFlatIP
```
、
```
IndexHNSWFlat
```
和
```
IndexIVFFlat
```
，因为量化后的 index 不会保留原始向量。FAISS
不要假设所有 Pinecone index 都可以迁移；只有 serverless index 支持该工具枚举向量所需的 list 操作。Pinecone
在将
```
qdrant
```
到
```
qdrant
```
的数据迁移到已有目标 collection 前，不要跳过向量大小检查；源数据库和目标数据库的向量维度必须完全一致，仅 replication 和 shard 设置可以不同。
如果源数据库或目标数据库使用由私有 CA 或自签名 CA 签发的证书，不要在未通过
```
SSL_CERT_FILE
```
挂载证书的情况下建立 TLS 连接；迁移会在证书验证阶段直接失败，而不会优雅降级。
```
--skip-tls-verification
```
应作为有意采用的覆盖选项，而不应作为默认修复方式。
不要因担心恢复出错就在健康的恢复流程中传入
```
--migration.restart
```
；该参数会丢弃已保存的进度，并重新传输已经迁移的数据。
不要在未运行数据完整性和搜索质量检查的情况下，将已完成的迁移视为已验证。