阶跃AI知识库迁移这件事，操作起来未必复杂，但稍有不慎就容易出现疏漏。关键在于，必须确保旧文档系统中的结构化数据、附件、权限关系以及操作记录，全部完整无缺地迁移至新平台。倘若迁移过程中丢失了原始文档的创建时间、修改人、版本链路或标签体系，新平台的价值将大打折扣——合规审计与知识回溯都将面临严重障碍。

确认源系统导出格式与字段映射

首先，登录旧文档系统后台，进入「系统管理→数据导出」模块，选择「全量知识库导出」。这一步至关重要：务必勾选“包含操作日志”和“保留原始时间戳”两项，否则新平台将无法还原编辑链路与责任归属，导致后续追溯困难。

导出格式仅支持.zip压缩包——其中必须包含JSON元数据以及/attachments子目录，CSV或Excel格式均不被接受。若强行导出其他格式，阶跃AI新平台的解析器会直接跳过所有附件，并返回一个406错误提示。

打开导出包中的metadata.json文件，检查是否包含以下7个必填字段：id、title、content、created_at、updated_at、creator_id、tags。缺少任何一个字段，该文档在新平台中将显示为空白页，严重影响使用体验。

清洗与校验导出数据

数据导出完成后，如果直接导入新平台，很可能出现各类异常。此时需要先进行数据清洗与校验，通常有两种方法。

方法一：使用阶跃AI最新校验工具（v2.3.1+）自动扫描

下载工具并解压，双击run_check.bat，将导出的.zip文件直接拖入窗口。工具会自动逐项检查附件路径是否正确、JSON完整性是否达标、时间格式是否符合ISO 8601标准（例如2025-03-17T09:22:14+08:00这样的写法）。发现错误时，工具会高亮显示行号并暂停等待处理，不可跳过。

方法二：手动校验关键字段

用VS Code打开metadata.json，按Ctrl+Shift+P，输入「JSON Validate」并回车。如果提示schema mismatch，说明creator_id字段在旧系统中导出为字符串，而新平台要求为整数。此时需要全局替换，将"creator_id": "1024"改为"creator_id": 1024。注意，引号内的数字必须去掉引号，否则导入后所有文档的作者都会显示为“未知”，导致文档归属混乱，影响团队协作。

执行导入并验证映射结果

首先，登录阶跃AI新平台的管理员后台，进入「知识库→批量导入」，点击「上传ZIP包」按钮。

上传成功后，页面会跳转到字段映射界面。左侧显示旧系统的字段名，右侧下拉框需要手动匹配到新平台对应的字段。例如，旧系统的tags如果映射到新平台的system_tags而非keyword_tags，那么全文检索将无法命中关键字，导致知识库的搜索功能失效，相当于搬了一个无法使用的哑巴知识库。

接着，勾选「启用历史版本继承」，然后点击「开始导入」。导入过程中请勿关闭浏览器或刷新页面，否则中途中断会直接丢失已导入文档的版本链路，造成不可逆的损失。

最后，导入完成页面如果显示「100%成功，共处理2,841条文档」，先别高兴太早。务必点击「查看导入报告」，下载report.csv，用Excel打开，筛选status列为failed的行。针对attachment_missing这类错误，需返回旧系统重新导出对应文档的附件子目录，并单独补传。