qdrant-migration-tool

Qdrant 迁移工具

该工具是一个 Docker 容器（registry.cloud.qdrant.io/library/qdrant-migration），而不是可导入的库。它会通过运行所在的机器分批传输数据，而不是直接连接源和目标；并且默认会从中断处继续，而不是从头开始。迁移到 Qdrant

选择合适的子命令

适用场景：开始新的迁移，并选择特定于源的 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 不会自动创建目标集合；运行迁移前，请先在 Qdrant 中创建集合，并确保向量大小和距离度量相匹配。其他所有数据源都会自动创建集合。
• 每种数据源都有对应的凭据和映射指南；运行迁移前请先阅读，因为概念映射（命名空间、索引、元数据字段）因数据源而异。Pinecone Weaviate Milvus Elasticsearch OpenSearch Azure AI search pgvector S3 Vectors Chroma Redis MongoDB FAISS Apache Solr Qdrant-to-Qdrant
• 如果列表中没有你的数据源，请前往 GitHub 问题跟踪器提交问题，而不是自行设计自定义管道。提交问题

针对本地实例运行

适用场景：源数据库或目标数据库在与迁移容器相同的机器上运行。

• 在 docker run 命令中添加 --net=host；否则，容器无法解析主机上的 localhost。迁移到 Qdrant
• 在与两个数据库的延迟都较低的机器上运行容器。由于该工具会通过其运行所在的位置传输数据，因此源和目标无需直接连通；但迁移主机与每个数据库之间的往返延迟仍会累积。

迁移中断

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

• 使用完全相同的命令重新运行。进度会记录在 Qdrant 的 _migration_offsets 集合中，因此迁移会自动从中断处继续，而不会重新复制已迁移的点。
• 传入 --migration.restart 可丢弃已保存的进度并重新开始，例如修复源端筛选条件错误，或在迁移期间更改集合架构后。
• 仅当你同时向同一个 Qdrant 实例运行多个迁移时，才需要自定义偏移集合名称；否则，请将 --migration.offsets-collection 保持为默认值，以免记录下之后会忘记查找的状态。

迁移速度太慢

适用场景：对于源数据集的规模，吞吐量过低。

• 大规模迁移时，将 --migration.batch-size 从默认值 50 提高到 256 或 512；批次过小会导致每次 upsert 往返未得到充分利用。
• --migration.num-workers 仅适用于 pg 和 qdrant 子命令；其他数据源没有并行工作线程标志，因此其吞吐量仅受批次大小和网络距离限制。
• --migration.batch-delay 默认为 0；只有在有意限制负载时，才提高该值，以免源数据库无法承受全速读取。不要将其作为默认调优选项。
• 将容器部署在靠近两个数据库的位置，而不是让它经由缓慢的网络路径运行，因为该工具无法补偿源端或目标端的延迟。

迁移后

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

• 通过验证框架进行检查，而不是只抽查几个点：它涵盖迁移前基线、数据完整性检查和搜索质量验证，不只是统计点数。迁移验证指南
• 如果迁移后 Postgres/pgvector 仍与 Qdrant 同时运行，请设置持续同步策略（事件驱动、批处理或双写），不要将迁移视为一次性切换。保持 Postgres 同步

不要这样做

• 不要假设 Weaviate、Redis、MongoDB 或 Solr 会自动创建目标集合；这些数据源不会向该工具提供向量维度或距离度量，因此必须先手动创建集合，并确保设置与源端完全一致。迁移到 Qdrant
• 不要将 faiss 子命令指向量化的 FAISS 索引；仅支持 IndexFlatL2、IndexFlatIP、IndexHNSWFlat 和 IndexIVFFlat，因为量化索引不会保留原始向量。FAISS
• 不要假设所有 Pinecone 索引都可以迁移；只有无服务器索引支持该工具枚举向量所需的列表操作。Pinecone
• 不要在未先检查目标集合向量维度的情况下，将 qdrant 到 qdrant 的迁移运行到已有目标集合中；源端和目标端的维度必须完全匹配，只有复制和分片设置可以不同。
• 如果源端或目标端的 TLS 证书由私有或自签名 CA 签发，不要在未通过 SSL_CERT_FILE 挂载 CA 证书的情况下连接；迁移会因证书验证失败而中止，不会自动降级处理。应有意使用 --skip-tls-verification 覆盖验证，而不要将其作为默认解决方案。
• 在健康续传时，不要出于谨慎而传入 --migration.restart；它会丢弃已保存的进度，并重新传输已迁移的数据。
• 不要在未运行数据完整性和搜索质量检查的情况下，就将已完成的迁移视为已验证。