Cherry Studio 知识库向量迁移器（KnowledgeVectorMigrator）深度解析：从 V1 embedjs 到 V2 better-sqlite3 向量存储的完整迁移方案

Cherry Studio 知识库向量迁移器KnowledgeVectorMigrator深度解析从 V1 embedjs 到 V2 better-sqlite3 向量存储的完整迁移方案【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本文围绕 CherryHQ/cherry-studio 的 V2 知识库向量迁移器KnowledgeVectorMigrator展开系统讲解它如何把 V1embedjs旧向量库读取、转换并重建为 V2 的 better-sqlite3-backed 多表向量存储index.sqlite并确保迁移结果与已迁移完成的 V2knowledge_base/knowledge_item业务表稳定关联。读完本文你将掌握该迁移器的职责边界、四类数据来源、字段转换规则、目录向量重新归属策略、文件安全与内存控制契约、校验与跳过规则以及它如何与当前 runtime 的向量检索体系直接衔接。本文对应的核心文档为 v2-refactor-temp/docs/knowledge/knowledge-vector-migrator.md实现代码位于 KnowledgeVectorMigrator.ts约 1474 行配套的工程说明见 README-KnowledgeVectorMigrator.md。1. 迁移器的职责边界业务主数据与向量数据分离V2 知识库迁移由两个迁移器协同完成二者分工明确、互不越界迁移器负责范围核心产出KnowledgeMigrator业务主数据迁移V2knowledge_base/knowledge_item业务表行KnowledgeVectorMigrator向量数据迁移每个 base 的index.sqlite向量存储KnowledgeVectorMigrator的职责不是迁移知识库业务主数据而是聚焦于三件事读取 V1 每个 knowledge base 对应的 legacyembedjs向量库将旧的 chunk 向量数据转换为新的 better-sqlite3-backedvectorstores布局保证新向量数据能稳定关联回已经迁移完成的 V2knowledge_base/knowledge_item。由此得到一个贯穿全文的关键原则source of truth 永远是 V2 业务表而不是向量库。向量库只是业务数据派生的可重建索引迁移器的所有取舍映射、跳过、校验都以能否被 V2 业务表证明合法归属为判据。从源码看KnowledgeVectorMigrator继承自BaseMigrator声明为readonly id knowledge_vector、readonly name KnowledgeVector、readonly description Rebuild legacy knowledge vectors into the per-base index.sqlite store执行顺序order 3.5在业务主数据迁移KnowledgeMigrator之后运行并实现了prepare()/execute()/validate()三段式迁移生命周期KnowledgeVectorMigrator.ts。2. 数据来源迁移器依赖的四类输入迁移器运行时依赖四类输入各自来源与作用如下KnowledgeVectorMigrator.ts 的prepare()中对这些输入进行了统一装载2.1 已迁移的 knowledge baseSQLiteknowledge_base表提供 base 身份提供 embeddingdimensions决定哪些 base 需要尝试迁移向量库。prepare()中通过ctx.db.select().from(knowledgeBaseTable)读取全部已迁移 base。dimensions必须满足typeof dimensions number Number.isInteger(dimensions) dimensions 0否则该 base 会被以invalid_dimensions原因跳过KnowledgeVectorMigrator.ts。这一规则与 knowledge-schema.md 中dimensions为必填字段、解析失败则跳过整个 base的约束一致。2.2 已迁移的 knowledge itemSQLiteknowledge_item表作为新的业务 item 身份来源为 legacy loader identity 映射提供目标itemId。prepare()从knowledgeItemTable中读取id、baseId、groupId、type、data五个字段并按baseId归组成migratedItemsByBaseId供后续使用KnowledgeVectorMigrator.ts。2.3 Legacy loader metadataReduxknowledge.bases[].items[]从 V1uniqueId/uniqueIds[]反查到已经迁移后的knowledge_item.id建立旧向量记录与新业务 item 的映射关系。prepare()通过ctx.sources.reduxState.getCategory(knowledge)读取 V1 遗留 Redux 状态KnowledgeVectorMigrator.ts。同时从ctx.sharedData中读取三个由KnowledgeMigrator写入的共享映射KNOWLEDGE_BASE_ID_REMAP_SHARED_DATA_KEYlegacy base id → migrated base idKNOWLEDGE_ITEM_ID_REMAP_SHARED_DATA_KEYlegacy item id → migrated item idKNOWLEDGE_DIRECTORY_CHILD_LOADER_REMAP_SHARED_DATA_KEY目录展开产生的 loader id → 子项 item id。这些共享数据是旧 loader identity → 新业务 item映射的桥梁KnowledgeVectorMigrator.ts。2.4 Legacy vector database${getDataPath()}/KnowledgeBase/baseId读取 V1embedjs的vectors表提供原始 chunk 文本、source、vector。迁移器不直接拼接向量库路径而是通过MigrationContext初始化的KnowledgeVectorSourceReader抽象读取README 明确要求must read from the migration-resolved v1 userData path, not from the v2 path registry orapp.getPath()。该读取器位于 KnowledgeVectorSourceReader.ts负责路径解析{knowledgeBaseDir}/{sanitizeFilename(baseId, _)}embedjs 格式探测通过sqlite_master检查是否存在vectors表isEmbedjsDatabase打开失败分类返回invalid_path/missing/directory/not_embedjs四种非 OK 状态KnowledgeVectorSourceReader.ts提供三种有界内存的读取形态详见第 9 节内存契约。3. 目标存储V2 的 per-base 多表 index store迁移目标不是继续保留旧embedjs格式而是生成新的 vectorstores 兼容存储。3.1 目标文件路径迁移后 base 的 runtime 路径为{knowledgeBaseDir}/{migratedBaseId}/.cherry/index.sqlite路径常量在源码中明确声明KnowledgeVectorMigrator.tsKNOWLEDGE_META_DIR .cherryKNOWLEDGE_VECTOR_STORE_FILE index.sqliteKNOWLEDGE_MATERIAL_ROOT_DIR raw由于迁移后 base 使用全新 uuidV2 store 落在{migratedBaseId}/.cherry/index.sqlite与 legacy 的扁平路径{knowledgeBaseDir}/{legacyBaseId}不同名、不冲突因此 v1 源文件无需腾挪。3.2 目标 schema目标 schema 是schema.ts定义的多表 index storemeta/content/material/search_unit/search_text/embedding六个主表外加外部内容 FTS5 表search_text_fts。旧的 embedjs/langchain 单表布局id、external_id、collection、document、metadata、embeddings 普通索引 FTS 触发器已被上述多表 schema 取代。目标存储通过createKnowledgeIndexStoreAtPath工厂创建——这正是 runtimeKnowledgeVectorStoreService打开存储所用的同一个工厂因此迁移产出的 store 与运行时自己构建的 store 逐字节等价。工厂的标准打开序列为driver → 版本感知 schemacreateKnowledgeIndexSchema或版本不一致时resetKnowledgeIndexSchema→ meta 身份ensureIndexMeta→KnowledgeIndexStorecreateIndexStore.ts。ensureIndexMeta会写入唯一的meta身份行schema 版本 base id这样 runtime 打开 store 时无需重新引导并且会在base_id不匹配时拒绝一个被替换/串库的index.sqlite。值得注意构建契约快照embedding 模型、dimensions、切块器配置 hash有意不存储——模型/维度变化会创建新 base切块器变化则重建派生索引。4. 核心转换规则4.1 Loader identity 映射V1 的向量记录使用uniqueLoaderId关联 loader。V2 迁移时不保留这个旧字段作为最终业务标识而是把它映射成新的knowledge_item.id并写入external_id。映射规则的优先级见 KnowledgeVectorMigrator.ts 的buildLoaderTargetMap优先使用 legacy item 的uniqueIds[]每个非空uniqueId都建立映射如果不存在uniqueIds[]再回退到 legacy item 的uniqueId只有已经成功迁移到 V2knowledge_item的 item 才能参与映射。这里有一个贯穿始终的重要约束只有能够映射到 V2knowledge_item.id的 legacy 向量记录才属于有效可迁移数据无法映射到knowledge_item.id的 legacy 向量即使仍存在于旧embedjsDB 中也视为无效残留数据因此迁移器的目标不是尽量保留旧向量文件中的所有内容而是只保留能被当前 V2 业务表证明合法归属的向量数据。4.2 目录directory向量的特殊处理重新归属而非丢弃V1 把目录下每个文件都登记在该目录 item 的 loader id 上没有 per-file item。迁移时不再把这些容器级向量直接丢弃而是KnowledgeMigrator.expandLegacyDirectoryItem为每个嵌入文件合成一个file子项一个 loader id 对应一个子项目录向量被重新归属re-attribute到这些子项上目录因此保持可检索且无需重新 embedding。KnowledgeVectorMigrator侧通过共享数据中的目录子项 loader 映射把 loader id 指向子项 material而不是目录容器否则会因non_indexable_container被跳过。同时它处理了一个隐蔽的冲突场景一个 loader id 可能同时被目录展开和独立添加的 standalone item 认领v1 的 loader id 是 path/content 哈希md5(path) 可能让独立添加的文件与文件夹内同路径文件撞 id。collectStandaloneLoaderOwners会优先把向量归属权判给 standalone item并对冲突记录 warning 而不是静默窃取KnowledgeVectorMigrator.ts。只有在 fallback 情况下——legacy 向量源不可读或某个嵌入文件没有可迁移向量——才会跳过容器级向量并把目录保留为directory_not_migrated失败墓碑此时knowledge_item中目录行本身不会被删除只是容器级向量不写入 V2 store。4.3 Chunk 内容映射旧向量记录中的内容字段按以下规则转换旧字段新字段pageContentdocumentknowledge_item.idmetadata.itemId与external_idknowledge_item.typemetadata.itemTypesourcemetadata.sourcechunk 顺序metadata.chunkIndexchunk 文本 token 估算metadata.tokenCount当前实现不会保留所有旧 metadata只保留迁移和检索必需的最小信息。迁移后的 metadata 必须满足 runtimeKnowledgeChunkMetadataSchemaitemId、itemType、source、chunkIndex、tokenCount都是必填字段。无法补出合法source的 legacy row 会被跳过而不是写入不完整 metadata。4.4 内容装配Route A保留 V1 切分迁移采用Route A策略——保留 v1 的切分结果而不是重新切块每个迁移 item 生成一个material其relative_path通过共享的toMaterialRelativePath辅助函数从迁移后的knowledge_item派生与 runtime 索引任务完全一致文件使用存储的relativePath有处理产物时用处理后 artifact 路径url 则固定指向在raw/下为其物化的快照文件item 的 legacy chunk 文本按 legacy 读取顺序用文档分隔符\n\nDOCUMENT_SEPARATOR拼接成一个规范的content.text每个 chunk 成为一条search_unit其[char_start, char_end)区间精确切回该 chunk 的原文并配一条 body 的search_text行unit_index为 per-item 读取顺序buildMigratedUnits函数按游标累加DOCUMENT_SEPARATOR.length保证content.text.slice(charStart, charEnd) body的不变量在构造上成立KnowledgeVectorMigrator.ts。这是一种合成的拼接不是新鲜的重新切分第一次真正的 reindex 会用线上 splitter 重新切块并收敛。4.5 Embedding 复用不重新 embedding迁移器不会重新做 embedding直接复用 V1 已存在的向量从 legacyvector字段读取原始 little-endian float32 BLOB 字节反序列化为Float32Array端到端使用Float32Array而非number[]驻留内存减半通过encodeVectorBlob原始 little-endian float32写入新表的embedding表以 body 的embedding_text_hash为键。这意味着迁移成本更低、不依赖在线模型调用、迁移阶段不会触发重新切块或重新嵌入且迁移产出的字节与 runtime 编码完全一致store 具备引擎可移植性。细节上还有两个亮点重复 body 折叠相同 chunk bodymaterial 内或跨 material会折叠成一条embedding行hash 键 INSERT OR IGNORE无需预去重fail-closed 漂移检测若pageContent在文本 pass 后发生变更会产生没有 unit 引用的 hashstore 的 embedding 覆盖检查会将其转为回滚KnowledgeVectorMigrator.ts。4.6 Chunk identity 重建旧 chunk row 的id不会直接复用。每一条迁移后的向量记录都会生成新的 UUID v4id实际上unit_id/content_hash/search_text_id由 store 从 material id、内容和偏移量确定性派生。因此迁移的稳定关联语义不依赖旧 chunk id而是依赖baseIdexternal_idknowledge_item.idchunk 文本与 source 对应的向量记录。5. 文件安全策略从临时文件 原子替换演进到原地构建这一节需要特别说明一个重要的实现演进。原设计文档 knowledge-vector-migrator.md 第 6 节描述的策略是临时文件重建 目标路径原子替换 v1 源原地不动先写{targetDbPath}.vectorstore.tmp临时文件校验成功后删除目标路径上空 store再原子 rename 到目标路径EBUSY时重试recursive maxRetries retryDelay。但当前实现已演进为直接原地构建——README 与源码均明确说明The migrator builds each rebuilt storedirectlyat its runtime path — no temp file, no renameKnowledgeVectorMigrator.ts。演进的原因是index store 以 WAL 模式打开index.sqlite在 Windows 上 WAL 模式已知会在close()之后仍对主 db 文件保持锁wal_checkpoint(TRUNCATE)、PERSIST_WAL、数秒等待都无法可靠释放叠加杀毒软件/搜索索引器以无DELETE共享方式打开刚写入的文件MoveFileEx需要源文件的DELETE权限于是 rename 会抛EBUSY/EPERM导致 base 丢失 store重试只能等待瞬态 AV 扫描无法等待一个永不释放的句柄原地构建彻底移除了 move 操作close()后残留的锁无害因为这里不再移动或重新打开文件runtime 只在 bootstrap 之后迁移早已结束打开它。原地构建的代价是放弃了 rename 的崩溃原子性中断的构建会在 runtime 路径留下部分索引但这个代价是安全的因为迁移门控在任何未完成运行后都会从头重跑verifyAndClearNewTables()清空行KnowledgeMigrator重新铸造全新 uuid 目录runtime 在迁移中途绝不打开 storeper-base catch 在捕获失败时会清掉部分产物崩溃遗留的目录不被任何knowledge_base行引用因此永远不会被挂载。不变的安全铁律依然是v1 legacyembedjsDB{knowledgeBaseDir}/{legacyBaseId}在整个迁移过程中不被移动也不被删除——迁移失败、放弃或成功后回退 v1知识库都可正常使用retry 天然幂等legacy 源一直在原路径retry 直接通过KnowledgeVectorSourceReader重新读取原始 legacy DB写入前的清理removeIndexStoreFiles删除index.sqlite{,-wal,-shm}家族使用{ recursive: true, force: true, maxRetries: 5, retryDelay: 100 }以在EBUSY下幸存writeFile/mkdir同样面临 Windows 瞬态锁Defender/Search Indexer源码用retryOnTransientFsLock包装最多 8 次尝试、指数退避、上限 1500ms覆盖EPERM/EACCES/EBUSYKnowledgeVectorMigrator.ts构建完成后执行store.checkpoint()将 WAL 折叠回主文件PRAGMA wal_checkpoint(TRUNCATE)让 runtime 打开的是一个自包含的 store。5.1 全有或全无的发布all-or-nothing publication一个 base 只有在构建、close、以及快照 pin 事务全部成功后才算已发布源码中的storePromoted标志。url/note 行 pin 到其快照路径是发布的最后一步任何更早的抛错构建、关闭或 pin 事务都会清掉索引并把 base 标记为可恢复的failed零 pin 不能被当作成功一个completed的 url/note item 没有relativePath就违反了deriveConceptId守护的不变量而没有任何机制能修复它runtime 的 index-documents 跳过completeditem已完成的迁移也永远不会重跑失败的 base 会浮现 restore 流程将 items 重新加入新 base新行的状态不是completed因此会真正被索引。这个恢复仅在一个场景下有损url item 会重新抓取线上页面而不是读取迁移写入的raw/快照因此已失效的链接无法恢复。6. 当前已接受的局限不应误读为未来理想方案6.1 base 级执行失败的处理重要变更说明原设计文档第 6 节曾表述base 级执行失败属于迁移失败execute()直接返回success: false。当前实现已改为单 base 失败非致命当一个 base 的向量 store 无法重建时prepare()无法读取/映射其 legacy 源或execute()在重建/发布中途失败该 base 会被跳过并标记为可恢复的failed/missing_vector_store行UI 显示 re-index 入口失败以 warning 形式呈现execute()仍返回success: true其余 base 继续迁移KnowledgeVectorMigrator.ts。唯一的例外如果 base 自身的failed/missing_vector_store标记无法写入应用数据库迁移器会抛出并使整个迁移失败。因为该标记是唯一把 base 挡在 runtime 打开路径之外的东西——一个被记录为completed但没有该标记的 base 将永远不可搜索且没有回头路此时失败可以让下次启动从头重跑。整个迁移只会在结构性/完整性错误上整体失败迁移器抛出或validate()的对账失败绝不会因为单个 base 的数据无法迁移而整体失败。6.2 磁盘占用翻倍与孤儿文件迁移成功后 v1 legacy 向量库会作为孤儿文件留在磁盘上连同已复制的 v1 上传文件知识库磁盘占用大致翻倍。这是保证 v1 可回退的预期代价如需在用户确认放弃 v1 后回收磁盘需要单独的 cleanup 策略、实现和测试。6.3 迁移前完整备份仍然必要迁移器只保证单个 knowledge base 的 v1 向量 DB 原地完好不等于完整 V1 备份。完整迁移失败后的全局恢复 source of truth 仍然是迁移前备份。7. 校验规则validate()的四重对账当前实现会做至少以下校验不满足即视为该 base 迁移失败KnowledgeVectorMigrator.ts计数对账每个成功 base 的重建 store 行数必须与 prepared 值一致material数 每个迁移 item 一个search_unit数 这些 item 保留的 chunk 总数embedding数 整个 base 的不同 embedding-text hash 数非空external_id每条迁移后的记录必须有非空external_idmetadata.itemId一致性每条记录必须有metadata.itemId且与external_id保持一致embedding 覆盖检查每条search_text行都必须能解析到已存储的embedding零 uncovered units——这是迁移期对rebuild self-heal 不变量的验证形式没有底层向量的 unit 会静默缺席于向量检索快照文件存在性url/note 的物化快照文件必须真实存在于{materialDirPath}/{relativePath}验证时按plan.snapshotRelativePathByItemId逐一检查fs.existsSync。此外validate()通过createKnowledgeIndexStoreAtPath而非裸new Database重新打开刚构建的 store——该工厂的 driver 设置了busy_timeout5000可以等待瞬态 Windows 锁且 schema/meta 步骤在刚构建的 store 上是幂等的不会改变计数结果。8. 跳过规则什么情况会被跳过而非强行写入8.1 base 级跳过以下情况整个 base 被跳过不产出任何 store并标记为可恢复的failed/missing_vector_store而不是completedknowledge_base中不存在对应 baseprepare()遍历的是已迁移行因此无行可标base 已被标记failed或embeddingModelId null缺 embedding 模型/已有失败原因不覆盖其自身错误dimensions无效非正整数legacy DB 文件缺失 / 路径实际是目录 / 不是 embedjs 格式无vectors表/ 扫描中途不可读迁移后的 base id 无法映射回 legacy knowledge base id重映射后的 legacy id 在 legacy Redux 状态中不存在。源码中 base 级 skip 分类包括invalid_dimensions、unmapped_base、legacy_base_missing、invalid_path、missing、directory、not_embedjs、read_error、missing_embedding_model、already_failedKnowledgeVectorMigrator.ts。8.2 row 级跳过以下情况的单条向量记录会被跳过classifyVectorRow的分类逻辑见 KnowledgeVectorMigrator.ts原因触发条件unmapped_loaderuniqueLoaderId无法映射回已迁移的knowledge_item.idnon_indexable_container向量映射到不可索引的容器类型如directory且仅在 fallback 路径触发unsupported_vector_encodingvector 载荷存在但暴露为不受支持的 runtime 编码missing_vector_payload向量记录缺少vector或vector为空dimension_mismatchvector 长度与 base 记录的dimensions不一致避免破坏整个 base 的暴力余弦扫描这些跳过通常会记录 warning而不是让整个迁移流程中断。为控制内存跳过按原因聚合计数并只保留最多 3 个样本SKIP_WARNING_SAMPLE_LIMIT 3绝不对每一条被拒行打一条日志。8.3 补充说明全部跳过后 base 的预期结果如果某个 base 的 legacy 向量记录最终全部被跳过则该 base 在 V2 中会被重建为空 vector store只有 schema meta行这不是回滚保留旧 DB的场景而是预期的数据清洗结果原因是这些被跳过的记录无法稳定关联到当前 V2knowledge_item因此不再被视为有效业务向量数据。注意区分被跳过的 base 不产出 store不是空 store与规划了但内容为空是两回事。9. 内存契约如何在超大语料下不 OOM迁移器的内存设计是经过真实 OOM 事故迭代出来的。历史沿革初版把所有 base 的 materials 从 prepare 保留到 execute峰值是全部 base 向量之和——28 个 base 的语料就耗尽了 V8 堆改进版per-base 重读但仍一次性加载整个 base——单个大 base六位数 chunk × 高维度就能单独耗尽堆导致迁移崩溃循环每次重启从头再来。当前实现的契约是任何时刻最多驻留一个 item 的文本 一个批次≤500 行的向量prepare()通过openBase().reader.iterateRows()流式扫描每个 base 的 legacy 行一次只保留 per-item 的 rowid 列表、计数、按原因聚合的跳过统计封顶样本以及每个 url/note item 预保留的快照路径。PreparedBasePlan刻意不持有任何向量或 chunk 文本KnowledgeVectorMigrator.ts扫描每 1024 行STREAM_ROW_YIELD_INTERVAL让出一次事件循环避免六位数行的 base 冻结迁移 UIexecute()逐 item 重读文本通过无向量列投影loadTextRowsByRowids整体读取content schema 每个 material 一条文本行拼接后的文本不可再分向量通过loadRowsByRowids以固定 ≤500 行VECTOR_STREAM_BATCH_SIZE与读取器ROWID_BATCH_SIZE对齐的点读批次流式拉取由rebuildMaterial在写事务内惰性消费——每个 pull 恰好是一次索引化SELECTKnowledgeVectorMigrator.ts解码后的向量端到端保持Float32Array驻留大小为number[]的一半url/note 快照文件在对应 item 的轮次内写入绝不跨 base 缓冲。rowid 列表是唯一刻意保留的 per-chunk 结构它随迁移总 chunk 数线性增长单 chunk 成本是一个压缩 SMI 数组中的一个 JS number在 1M chunks 时约 10.5 B/chunk10M 时约 8.0 B/chunknode --expose-gc堆增量实测。这是对典型语料的估算而非代码强制上限——迁移器只要求dimensions是正整数不约束pageContent长度或 base 的 chunk 数。对普通语料一个 chunk 在 legacy DB 中占 ≥5 KB1024 维 float32 向量 4 KB 约 1 KB 文本plan 约为 legacy 文件磁盘大小的 1/500100 MB 的 plan 意味着约 50 GB 的 v1 向量 DB耗尽 V8 的 4 GB old-space 需要约 4 亿 chunks约 2 TB 源而观测到的最重语料约 7.5 万 chunks≈ 0.7 MB plan。OOM 回归守卫测试会钉死PreparedBasePlan的确切键集和每个阶段的读取形态prepare 流式execute 文本走投影、向量走 ≤500-rowid 批次——501-chunk 的 item 必须以 500 1 的形式到达。10. 与当前 Runtime 的衔接迁移后的向量数据不是孤立的一次性产物而是会被当前 runtime 直接按 knowledge base 打开和查询。runtime 向量侧实现位于注文档中的src/main/services/...旧路径在当前仓库中已迁移至src/main/features/...KnowledgeRuntimeService.ts 对应的运行时服务KnowledgeVectorStoreService.ts按base.id获取 storeBetterSqlite3VectorIndex.ts实际 store provider。当前已确认的衔接点runtime 通过KnowledgeVectorStoreService按base.id获取 store实际 store provider 是BetterSqlite3VectorIndexruntime 检索和写入都基于 better-sqlite3 vector store迁移器与 runtime 共用同一个createKnowledgeIndexStoreAtPath工厂因此迁移产出的 store 与 runtime 自建的 store 字节等价createIndexStore.ts 的注释明确写道Shared by the runtime (KnowledgeVectorStoreService.openIndexStore) and the v1→v2 vector migrator so the sequence lives in exactly one place。因此迁移器与 runtime 的共同前提是V2 业务真相来自knowledge_base/knowledge_item运行时向量文件与迁移后的向量文件都属于同一类 better-sqlite3-backed vector store 体系运行时关联业务 item 仍应以knowledge_item.id为稳定标识而不是继续依赖 V1 loader identity。11. 当前边界、限制与对后续实现的影响11.1 边界与定位当前迁移器只负责向量数据重建不负责重新切块重新 embedding重新生成业务 item校正旧知识库的业务配置设计最终 retrieval service 的 API。因此它的定位是一次性的迁移工具不等同于运行时知识库索引服务。11.2 对后续实现的影响基于当前迁移器行为后续 V2 运行时设计需要遵守以下前提V2 业务真相仍然来自knowledge_base/knowledge_item新向量记录必须能通过external_id稳定关联到knowledge_item.id运行时不应继续依赖 V1embedjs的uniqueLoaderId如果未来需要重建索引应按 V2 业务表重新生成而不是继续依赖旧迁移逻辑。12. 相关文档的定位关系V2 知识库迁移与运行时设计由三份文档共同定义各有分工文档定义内容knowledge-schema.mdV2 业务 schemaknowledge_base/knowledge_item的列、groupId语义、dimensions解析规则、item 状态迁移规则knowledge-backend-decisions.md当前KnowledgeRuntimeService、data services、queue 和 runtime/vector 边界knowledge-vector-migrator.md本文主题旧向量数据如何迁移进新体系三者的关系可以简化为schema 定义业务结构backend decisions 文档定义当前运行时边界vector migrator 文档定义旧向量数据如何迁移进新体系。13. 小结KnowledgeVectorMigrator是一个克制的迁移器它不重新切块、不重新 embedding、不迁移业务主数据只做一件事——把 V1embedjs向量库中能被 V2 业务表证明合法归属的 chunk 向量转换为与 runtime 完全同构的 per-base better-sqlite3 index store。它的关键设计决策可以总结为归属优先于保留无法映射到 V2knowledge_item.id的旧向量一律视为无效残留宁可得到空 store 也不写入不可证明归属的数据复用优先于重建embedding 字节原样复用Float32Array端到端、切分结果以 Route A 拼接保留迁移全程零在线模型调用安全优先于整洁v1 源永不移动/删除、原地构建规避 Windows WAL 锁、全有或全无发布、单 base 失败隔离为可恢复状态磁盘翻倍是可回退的预期代价有界内存优先于简单实现流式扫描 rowid 计划 分批点读把峰值内存钉死在一个 item 文本 500 行向量。这套设计使迁移既可作为一次性工具安全执行又能让产出的向量数据无缝接入 V2 运行时检索体系是 Cherry Studio V2 知识库升级链路中承上启下的关键一环。如需深入源码建议按 KnowledgeVectorMigrator.ts → KnowledgeVectorSourceReader.ts → createIndexStore.ts 的顺序阅读并结合 README-KnowledgeVectorMigrator.md 对照实现契约。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考