实验性功能声明索引迁移器目前为实验性特性其 API、CLI 命令以及磁盘存储格式计划、检查点、备份在后续版本中可能发生变更。在生产环境应用迁移前请务必仔细审查迁移计划。本文将介绍如何使用 RedisVL 的迁移工具安全地修改已有索引的结构无论是增加字段、删除字段、重命名还是进行向量量化优化。快速上手4 条命令为索引添加新字段# 1. 查看当前存在的所有索引rvl index listall--urlredis://localhost:6379# 2. 使用交互式向导生成迁移计划rvl migrate wizard--indexmyindex--urlredis://localhost:6379# 3. 执行迁移rvl migrate apply--planmigration_plan.yaml --backup-dir ./migration_backups--urlredis://localhost:6379# 4. 验证迁移结果rvl migrate validate--planmigration_plan.yaml--urlredis://localhost:6379前置条件已安装RedisVLpip install redisvl运行中的Redis 实例推荐 Redis 8.0支持全部功能且已加载 Search 模块Redis Stack、Redis Cloud 或 Redis Software 均可待迁移的已有索引本地开发环境快速启动 Redis 8.0dockerrun-d--nameredis-p6379:6379 redis:8.0注意INT8/UINT8 向量数据类型需要 Redis 8.0SVS-VAMANA 算法需要 Redis 8.2 及 Intel AVX-512 硬件支持。迁移工作原理三阶段流程每一次迁移都遵循相同的三阶段流程描述变更 → 生成计划 → 执行计划。下图清晰展示了单索引迁移的完整链路阶段3: 执行迁移阶段2: 生成迁移计划阶段1: 构建变更描述交互式向导SchemaPatch YAML手动编写Planner.create_planMigrationPlan YAMLExecutor.applyMigrationReport YAML阶段 1构建 SchemaPatch变更描述SchemaPatch 是一个 YAML 文件它声明您想要进行的变更而非完整的最终模式。您可以通过交互式向导生成也可以手动编写。Patch 包含五个可选的变更节节区作用add_fields向索引添加新字段定义remove_fields从索引中移除字段文档数据仍然保留只是不再索引rename_fields重命名字段同时更新索引模式和所有文档执行 HGET→HSET→HDEL 或 JSON 路径更新update_fields修改字段属性算法、数据类型、距离度量、是否可排序、分隔符等index修改索引名称或键前缀例如一个手动编写的schema_patch.yamlversion:1changes:add_fields:-name:categorytype:tagpath:$.categoryattrs:separator:|remove_fields:-legacy_fieldupdate_fields:-name:embeddingattrs:datatype:float16# 向量量化algorithm:HNSW阶段 2生成 MigrationPlan迁移计划Planner 组件连接 Redis对当前在线索引进行快照包括 schema、统计信息、键样本和前缀然后将 Patch 合并到源 schema 中生成merged_target_schema。同时它会分类每个变更是否为支持或阻塞并提取重命名操作。生成的计划 YAML 包含source计划生成时线上索引的冻结快照schema、stats、key sample、prefixesrequested_changes应用的 patchmerged_target_schema源 schema patch → 迁移后的最终 schemadiff_classification是否支持迁移以及阻塞原因如有rename_operations提取出的索引重命名、前缀变更和字段重命名warnings重要提示如是否需要停机、是否有损量化等关键点同一个 Patch 对不同索引会生成不同的计划因为每个索引的源 schema 不同。阶段 3执行迁移Apply执行器读取计划并依次执行以下步骤是否是否开始 Apply枚举所有文档键执行字段重命名如有是否改变哈希向量类型?备份原始向量字节到磁盘跳过向量备份删除源索引FT.DROPINDEX执行键前缀重命名如有是否改变哈希向量类型?逐批读取、转换、写回向量跳过向量量化创建目标索引FT.CREATE等待后台重建完成验证结果生成迁移报告详细说明枚举键修改前使用FT.AGGREGATE WITHCURSOR高效枚举所有文档键若索引有失败记录则回退到SCAN。字段重命名若计划中有rename_fields则在删除原索引前执行文档字段的重命名Hash 用管道 HGET/HSET/HDELJSON 用路径更新。备份原始向量仅当哈希向量类型变更时将原始向量字节写入backup-dir用于崩溃恢复和回滚。删除源索引执行FT.DROPINDEX仅删除索引结构底层文档不受影响。此后索引暂时不可用。键前缀重命名如有前缀变更执行RENAME或集群环境DUMP/RESTORE。量化向量仅当哈希向量类型变更时对每个文档读取旧向量转换数据类型如 float32→float16写回原文档。批量处理默认 500 条/批。创建目标索引用merged_target_schema执行FT.CREATERedis 开始后台索引已有文档。等待索引就绪轮询FT.INFO直到索引完成重建此时索引可正常查询。停机要求关键在drop_recreate迁移模式下索引会暂时不可用。您的应用必须暂停所有读操作因为索引被删除期间任何查询都会失败。暂停所有写操作因为写入的文档不会被索引索引已删除此外若正在量化向量并发写入会与迁移冲突。停机类型读操作写操作是否安全完全静默推荐停止停止✅ 安全只读暂停停止继续❌ 不安全活动状态继续继续❌ 不安全恢复建议若迁移中断重新执行同一命令即可自动从中断点续传要求使用--backup-dir。向量量化的备份与崩溃安全恢复当您将哈希向量从高精度类型如 float32转换为低精度类型如 float16 或 int8时迁移器会在修改前将原始向量保存到磁盘以实现崩溃安全恢复和手动回滚。备份文件结构backup-dir/ migration_backup_index_name.header # JSON: 进度状态、批次计数、字段元数据 migration_backup_index_name.data # 二进制: 按批次存储的原始向量长度前缀pickle migration_backup_index_name.manifest # JSON: 多worker分片恢复元数据workers1时磁盘占用≈ 文档数 × 向量维度 × 每个元素字节数例如100万文档 × 768维 × float32(4字节) ≈ 2.9 GB状态机与续传.header文件记录了一个状态机原子更新每个批次后写入dump → ready → index_dropped → active → completed → target_created → validateddump正在读取并备份原始向量ready备份完成原索引仍在线index_dropped原索引已删但向量尚未全部转换active正在逐批转换向量completed所有向量转换完成等待创建目标索引target_created目标索引已创建正在重建或已就绪validated迁移验证通过若进程崩溃重新运行相同命令迁移器会读取 header跳过已完成批次从下一个未完成批次继续。手动回滚如需撤销量化迁移并恢复原始向量rvl migrate rollback --backup-dir /tmp/backups--urlredis://localhost:6379该命令会将备份中的原始向量写回 Redis但不会恢复索引定义您需要手动重建原索引。支持与阻塞的变更一览变更类型是否支持说明添加 text/tag/numeric/geo 字段✅ 支持移除字段✅ 支持重命名字段✅ 支持同时更新所有文档更改键前缀✅ 支持执行RENAME重命名索引✅ 支持仅索引级别字段设为可排序✅ 支持更改字段选项分隔符、词干提取等✅ 支持更改向量算法FLAT↔HNSW↔SVS-VAMANA✅ 支持仅索引无需改数据更改距离度量COSINE↔L2↔IP✅ 支持仅索引调整 HNSW 参数M、EF_CONSTRUCTION✅ 支持仅索引量化向量float32→float16/bfloat16/int8/uint8✅ 支持自动重新编码若同一键被其他索引共享则不支持更改向量维度❌ 阻塞需要重新嵌入应使用新模型重新生成数据再迁移更改存储类型hash ↔ json❌ 阻塞数据格式不同需导出转换后重新加载添加新向量字段❌ 阻塞要求所有文档已有向量应先填充向量再迁移单索引迁移 CLI 参考命令描述rvl migrate wizard交互式构建迁移推荐rvl migrate plan根据 patch 或目标 schema 生成计划rvl migrate apply执行迁移rvl migrate estimate估算迁移所需磁盘空间干运行rvl migrate validate验证迁移结果rvl migrate rollback回滚向量数据需备份目录常用参数--urlRedis 连接 URL--index待迁移索引名--plan/--plan-out计划文件路径--backup-dir必需的备份目录用于存放恢复数据--batch-size每批处理的键数默认 500--workers并行量化工作线程数默认 1--async使用异步执行适用于大规模迁移--report-out输出验证报告--benchmark-out输出性能指标批量迁移一次 patch 应用于多个索引当需要为多个索引应用相同变更如统一量化所有索引的向量时使用批量迁移。快速开始# 1. 创建共享 patchcatquantize_patch.yamlEOF version: 1 changes: update_fields: - name: embedding attrs: datatype: float16 EOF# 2. 生成批量计划匹配所有后缀为 _idx 的索引rvl migrate batch-plan\--pattern*_idx\--schema-patch quantize_patch.yaml\--plan-out batch_plan.yaml\--urlredis://localhost:6379# 3. 执行批量迁移rvl migrate batch-apply\--planbatch_plan.yaml\--backup-dir ./migration_backups\--accept-data-loss\--urlredis://localhost:6379# 4. 查看状态rvl migrate batch-status--statebatch_state.yaml批量计划生成逻辑批量计划器接受一个共享 patch对每个目标索引测试其适用性若 patch 可应用如字段存在、变更支持则为该索引生成独立的MigrationPlan并标记applicable: true若 patch 不适用如字段缺失标记applicable: false并记录skip_reason跳过该索引前缀冲突检查若两个索引的键前缀有重叠一个为另一个的前缀批量计划器将拒绝生成计划以避免同一键被多次量化导致数据损坏。需将冲突索引分组分别处理。批量执行与恢复batch-apply按顺序逐个执行索引迁移进度保存在batch_state.yaml中若中途中断使用batch-resume继续rvl migrate batch-resume --state batch_state.yaml失败策略fail_fast或continue_on_error在batch-plan时设置Python API 示例同步单索引迁移fromredisvl.migrationimportMigrationPlanner,MigrationExecutor plannerMigrationPlanner()planplanner.create_plan(myindex,redis_urlredis://localhost:6379,schema_patch_pathschema_patch.yaml,)executorMigrationExecutor()reportexecutor.apply(plan,redis_urlredis://localhost:6379,backup_dir/tmp/migration_backups,batch_size500,num_workers4,)print(f迁移结果:{report.result})异步 APIimportasynciofromredisvl.migrationimportAsyncMigrationPlanner,AsyncMigrationExecutorasyncdefmigrate():plannerAsyncMigrationPlanner()planawaitplanner.create_plan(...)executorAsyncMigrationExecutor()reportawaitexecutor.apply(...)print(report.result)asyncio.run(migrate())批量迁移 Python APIfromredisvl.migrationimportBatchMigrationPlanner,BatchMigrationExecutor plannerBatchMigrationPlanner()batch_planplanner.create_batch_plan(redis_urlredis://localhost:6379,pattern*_idx,schema_patch_pathquantize_patch.yaml,)executorBatchMigrationExecutor()reportexecutor.apply(batch_plan,redis_urlredis://localhost:6379,backup_dir/tmp/migration_backups,state_pathbatch_state.yaml,)print(f成功:{report.summary.successful}/{report.summary.total_indexes})性能调优建议批次大小--batch-size默认 500 是良好平衡点增大到 1000 可减少网络往返但增加单次内存占用和延迟视网络和 Redis 性能可调整到 200~1000 之间并行工作线程--workers用于向量量化阶段每个 worker 独立连接 Redis增加 worker 可加速量化但会提高 Redis 连接数和 CPU 负载建议从 2~4 开始测试备份磁盘空间估算使用估计命令提前计算rvl migrate estimate--planmigration_plan.yaml若开启 AOF加上--aof-enabled以获得更精确的磁盘需求。常见问题排查问题可能原因解决方案计划生成失败提示unsupported change变更需要数据转换如改变维度按提示调整策略或采用应用层迁移Apply 失败“source schema mismatch”线上索引在计划生成后发生了改变重新生成计划Apply 超时“timeout waiting for index ready”数据量大重建慢增加超时时间或在低峰期执行验证失败“document count mismatch”计划生成后有文档增删应用写操作暂停期间重新生成计划并执行量化后另一索引中的文档消失共享键导致类型冲突不支持回滚向量使用应用层迁移创建新键或新字段协调所有索引批量计划生成报错overlapping indexes两个索引前缀重叠将冲突索引分开到不同批次或手动处理恢复中断时提示备份不匹配备份目录与当前计划不一致删除旧备份目录重新开始总结RedisVL 的索引迁移器提供了一套安全、可续传、可回滚的机制来演进您的索引结构。核心要点三阶段流程Patch → Plan → Apply必须停机迁移期间索引不可用需暂停读写备份必备--backup-dir为所有迁移强制要求确保可恢复向量量化自动备份原始向量支持崩溃续传和手动回滚批量处理同一 patch 可应用于多个索引但需注意前缀冲突在生产环境操作前建议先在测试索引上演练确认计划无误后再应用。迁移计划中的diff_classification.supported和warnings字段是决策的关键依据。