人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载UpdateEmbeddingDimensionOperation是 openJiuwen agent-core-java 记忆迁移框架com.openjiuwen.memory.migration.operation中用于更新向量字段 embedding 维度的迁移操作对应仓库中 UpdateEmbeddingDimensionOperation.java 的实现其 Python 原型位于openjiuwen/core/memory/migration/operation/operations.py。本文围绕该类的字段、构造方法与公开方法展开并结合VectorMigrator、VectorStoreUtils与测试用例讲解如何将记忆库中已持久化的 embedding 向量从旧维度平滑迁移到新维度扩大、缩减或零填充重建覆盖完整调用链、批处理参数、recompute 回调的底层行为与最佳实践。一、类定位向量 Schema 迁移中的维度变更操作1.1 为什么需要更新 embedding 维度在长期记忆Long-Term Memory场景中向量数据以FloatVector类型字段如embedding存储在向量集合collection中其维度在创建集合时即被固定。当出现以下情况时需要原地升级维度切换了 embedding 模型如从 4 维升级到 768 维新旧模型产出的向量维度不一致需要压缩向量存储成本将维度下调需要在保留既有记忆数据的前提下重算向量。直接重建集合会丢失历史记忆而手动逐条改写向量既慢又容易出错。UpdateEmbeddingDimensionOperation正是为此设计的声明式迁移操作它只描述目标数据类型、目标字段、新维度、批大小这组变更意图实际执行由向量迁移器完成。1.2 类声明与继承关系public class UpdateEmbeddingDimensionOperation extends BaseOperation该类继承自 BaseOperation.java。BaseOperation是所有迁移操作的抽象基类持有OperationMetadata metadata字段并提供int getSchemaVersion()返回本次操作对应的 schema 版本号String getDescription()返回元数据中的描述为空时回退到当前类名如UpdateEmbeddingDimensionOperation。也就是说每一个维度更新操作都必须绑定一个schemaVersion迁移框架据此判断集合当前版本与目标版本之间需要执行哪些操作。二、字段与构造方法一条维度更新操作包含什么2.1 字段一览字段类型说明dataTypeString目标向量数据类型记忆类型用于定位要迁移的集合。fieldNameString目标向量字段名通常是embedding。newDimensionint更新后的 embedding 维度。recomputeEmbeddingFuncFunctionObject, Object可选逐文档重算 embedding 的回调函数。batchSizeint批量迁移时使用的批大小。说明API 文档中的字段表列出的四个字段是操作的核心配置项源码中还额外持有可选的recomputeEmbeddingFunc见 UpdateEmbeddingDimensionOperation.java用于自定义向量重算逻辑下文会重点展开。2.2 两个构造方法// 简洁构造不提供 recompute 回调batchSize 默认 1000 public UpdateEmbeddingDimensionOperation( OperationMetadata metadata, String dataType, String fieldName, int newDimension ) // 完整构造自定义向量重算回调 自定义批大小 public UpdateEmbeddingDimensionOperation( OperationMetadata metadata, String dataType, String fieldName, int newDimension, FunctionObject, Object recomputeEmbeddingFunc, int batchSize )第一个构造方法内部委托给完整构造recomputeEmbeddingFunc传null、batchSize默认1000第二个构造方法把四个核心配置原样保存并通过super(metadata)将元数据交给BaseOperation。2.3 公开方法签名说明String getDataType()返回目标记忆数据类型如vector_summary。String getFieldName()返回目标向量字段名如embedding。int getNewDimension()返回新的 embedding 维度。FunctionObject, Object getRecomputeEmbeddingFunc()返回重算回调未提供时为null。int getBatchSize()返回批处理大小。需要强调的是UpdateEmbeddingDimensionOperation是一个纯 DTO数据传输对象自身不包含任何执行逻辑——正如BaseOperation源码注释所声明的 Pure DTO, no execution logic。它只是把迁移意图描述清楚真正的执行由迁移器负责。三、数据流向从注册到执行的完整调用链要理解batchSize、dataType等字段如何生效需要把它放进整个记忆迁移框架中看。3.1 注册按实体键维护严格递增的版本链迁移操作先注册进 OperationRegistry.java按entityKey实体键组织成有序操作链。register(entityKey, operation)会校验同一实体下新操作的schemaVersion必须严格大于当前已注册的最大版本否则抛出MEMORY_REGISTER_OPERATION_VALIDATION_INVALID异常。getOperations(entityKey, fromVersion, toVersion)返回闭区间[fromVersion, toVersion]内的操作列表供迁移器按版本区间提取要执行的操作。3.2 执行VectorMigrator 按集合版本增量应用VectorMigrator.java 负责向量集合的迁移其执行过程findCollections(entityKey)对dataType做规范化去掉vector_前缀并校验其属于 SupportMemoryType.java 中定义的记忆类型当前为user_profile、summary然后按_类型后缀匹配集合名如user1_scope1_summary读取集合元数据中的schema_version过滤出schemaVersion currentVersion的操作调用vectorStore.updateSchema(collectionName, operationsToApply)应用 schema 变更把最大版本号写回集合元数据schema_version。在 ChromaVectorMigratorMissingTest.java 中可以看到多版本连续迁移的验证v1 加字段、v2 重命名字段、v3 通过UpdateEmbeddingDimensionOperation把embedding维度从 4 升到 6最终断言schema_version 3、schema 中embedding字段的dim等于 6、每条文档的 embedding 长度均为 6。3.3 统一入口RunMigrationsRunMigrations.java 是迁移的统一执行入口从MigrationPlan中读取各注册表SQL、向量、KV、消息、索引五类按实体键逐个调度对应迁移器任一实体失败则抛MEMORY_MIGRATE_MEMORY_EXECUTION_ERROR。典型的启动流程是// 应用启动阶段执行向量迁移示例代码示意 RunMigrations.runVectorMigrations(vectorStore).join();四、recomputeEmbeddingFunc 与 batchSize 的底层行为batchSize与recomputeEmbeddingFunc不会在 DTO 内部生效而是被底层的向量存储工具消费理解这一点才能真正用好这两个参数。4.1 逐文档重算与零向量兜底VectorStoreUtils.java 中的buildTransformFuncForOperations(...)会把操作列表编译成一个逐文档转换函数其中对UpdateEmbeddingDimensionOperation的处理逻辑applyEmbeddingDimensionUpdate见 VectorStoreUtils.java是若recomputeEmbeddingFunc为null直接生成newDimension长度的全0.0d零向量zeroVector若提供了Function调用该函数基于原文档计算新向量长度校验无论哪种方式生成向量的长度必须等于newDimension否则抛出STORE_VECTOR_SCHEMA_INVALID错误信息形如Generated vector length X does not match new_dim Y。对应的测试用例在 VectorStoreUtilsTest.java 中覆盖了三种行为无回调时默认生成[0.0, 0.0, 0.0]回调返回正确长度时直接采用回调返回错误长度如 3 维却返回 2 维时抛出BaseError。4.2 三种典型维度变换模式来自测试的实战证据ChromaVectorMigratorMissingTest.java 给出了三种可直接借鉴的模式维度扩大用concat(oldEmbedding, oldEmbedding)把 4 维扩到 8 维new UpdateEmbeddingDimensionOperation( new OperationMetadata(1), vector_summary, embedding, 8, doc - concat(embedding(doc), embedding(doc)), 1000)维度缩减subList(0, 2)取前 2 维new UpdateEmbeddingDimensionOperation( new OperationMetadata(1), vector_summary, embedding, 2, doc - embedding(doc).subList(0, 2), 1000)零填充重建不传回调4 维向量原地变成全 0 的 6 维向量new UpdateEmbeddingDimensionOperation( new OperationMetadata(1), vector_summary, embedding, 6)4.3 batchSize 的约定从源码看batchSize默认值为1000由简洁构造方法固定传入UpdateEmbeddingDimensionOperation.java。测试代码中的典型取值是1000或128例如 UpdateEmbeddingDimensionOperationTest.java 用batchSize 128验证了取值会被原样保存并读取。当数据量较大时可结合后端实际吞吐能力适当调小该值避免单批处理过大造成内存压力。五、实操示例注册一条 embedding 维度升级迁移5.1 基本用法// 1. 构造元数据schema 版本 3附描述 OperationMetadata metadata new OperationMetadata(3, update embedding dimension); // 2. 构造维度更新操作将 vector_summary 的 embedding 从旧维度升到 768 UpdateEmbeddingDimensionOperation operation new UpdateEmbeddingDimensionOperation( metadata, vector_summary, embedding, 768 ); // 3. 注册到向量注册表entityKey 通常与 dataType 保持一致 MigrationPlan.getVectorRegistry().register(vector_summary, operation); // 4. 启动迁移 RunMigrations.runVectorMigrations(vectorStore).join();5.2 带重算回调的完整用法UpdateEmbeddingDimensionOperation operation new UpdateEmbeddingDimensionOperation( new OperationMetadata(3, rebuild embedding with new model), vector_summary, embedding, 768, doc - callNewEmbeddingModel(doc), // 用新模型逐文档重算向量 128 // 自定义批大小 ); MigrationPlan.getVectorRegistry().register(vector_summary, operation);5.3 单元测试验证UpdateEmbeddingDimensionOperationTest.java 是最直接的验证参考覆盖了两类关键行为完整构造所有字段原样保存getRecomputeEmbeddingFunc()返回同一函数实例assertSamegetBatchSize()返回传入值简洁构造getRecomputeEmbeddingFunc()为nullgetBatchSize()默认1000。六、注意事项与约束版本必须严格递增同一实体下注册操作的schemaVersion必须大于当前最大值否则注册阶段直接报错见 OperationRegistry.java。dataType 必须合法VectorMigrator会校验dataType支持带vector_前缀不在SupportMemoryType枚举user_profile、summary内会抛MEMORY_MIGRATE_MEMORY_EXECUTION_ERROR。目标字段必须是向量字段schema 层校验要求fieldName指向FloatVector类型字段字段不存在或不是向量字段都会抛STORE_VECTOR_SCHEMA_INVALID见 VectorStoreUtils.java。重算结果长度必须精确匹配回调产出的向量长度不等于newDimension会直接失败务必在回调内保证长度一致不传回调则自动零填充。失败场景有回滚保障测试用例验证了迁移过程中 recompute 抛异常时schema、集合元数据版本与文档数据均保持原样不会留下_migration_残留集合见 ChromaVectorMigratorMissingTest.java。操作是纯声明式 DTO它本身不执行任何逻辑必须配合VectorMigrator/RunMigrations使用超出迁移器支持范围的操作类型会在运行期报错。七、小结UpdateEmbeddingDimensionOperation用一组简洁字段dataType、fieldName、newDimension、batchSize及可选recomputeEmbeddingFunc把记忆库 embedding 维度升级这一高频迁移诉求声明化配合OperationRegistry的版本管理、VectorMigrator的增量应用与VectorStoreUtils的逐文档变换形成了一条完整、可回滚、可验证的迁移链路。无论是切换 embedding 模型、压缩向量成本还是零填充重建都可以用它快速落地并借助仓库中 UpdateEmbeddingDimensionOperationTest.java、ChromaVectorMigratorMissingTest.java 与 VectorStoreUtilsTest.java 完成行为验证。赞分享人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载相关推荐RenameColumnOperation 深度解析openJiuwen agent-core-java 记忆库 SQL 列重命名迁移实战RenameColumnOperation 深度解析openJiuwen agent core java 记忆库 SQL 列重命名迁移实战 本文围绕 open人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习openJiuwen 记忆引擎 SQL 迁移AddColumnOperation 新增列操作实战指南openJiuwen 记忆引擎 SQL 迁移AddColumnOperation 新增列操作实战指南 AddColumnOperation 是 openJiu人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习openJiuwen 记忆存储迁移框架深度解析从 MigrationPlan 注册到 RunMigrations 执行openJiuwen 记忆存储迁移框架深度解析从 MigrationPlan 注册到 RunMigrations 执行 导读 openJiuwenopenJ人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考