一、数据导入的三阶段模型：准备 → 上传 → 索引
将企业存量数据导入 EIOS 知识库以赋能 Agent 的检索增强生成（RAG）能力，是大多数客户上线 EIOS 的第一步。这个过程分为三个清晰的阶段。第一阶段：数据准备（Prepare）——开发者将原始数据（数据库导出、文件服务器中的 PDF/Word/Excel 文档、API 抓取的结构化数据）整理为 EIOS 支持的格式。支持的源格式包括 CSV、JSON Lines、Parquet（用于大规模结构化数据）和 PDF、DOCX、XLSX、TXT、Markdown（用于非结构化文档）。准备阶段还包括数据清洗——去重、脱敏、格式统一、嵌入必要的元数据（如文档来源、创建日期、所属部门、权限标签）。第二阶段：批量上传（Upload）——通过 POST /v1/imports/batch 端点提交上传任务。单个任务支持最多 100 万条记录或 10GB 原始文件。上传是一个异步操作，API 立即返回一个任务 ID，后续通过轮询或 Webhook 追踪进度。第三阶段：向量化索引（Index）——上传完成后，系统自动启动向量化流水线，将文档内容分割为语义块（Chunk，可自定义大小和重叠度），使用指定的嵌入模型（支持 text-embedding-3-large、bge-m3 等）生成向量，存储至向量数据库，并建立全文索引（支持中文分词）。向量化完成后，数据即可被 Agent 通过 RAG 检索使用。
二、批量上传 API 详解：参数、选项与最佳配置
POST /v1/imports/batch 是数据导入的核心端点。一个典型的请求结构如下：
POST /v1/imports/batch
Content-Type: multipart/form-data
fields:
knowledge_base_id: "kb_prod_main"
source_type: "csv" # csv | jsonl | parquet | pdf | docx | mixed
chunk_size: 1024 # 每个语义块的最大 Token 数（256-4096）
chunk_overlap: 128 # 相邻语义块之间的重叠 Token 数
embedding_model: "text-embedding-3-large"
metadata_schema: { "source": "string", "department": "string" }
dedup_strategy: "content_hash" # content_hash | metadata_key | none
pii_detection: true # 是否启用敏感信息自动检测与告警
callback_url: "https://myapp.com/webhooks/eios-import"
file: @data_export_2026_06.csv关键参数解析：chunk_size 和 chunk_overlap 直接影响 RAG 检索的质量。chunk_size 越大，每个块包含的上下文越完整，但检索的相关性可能降低；chunk_size 越小，检索精确度越高，但大文档可能需要更多轮检索。一般建议从 1024 开始，根据 RAG 的评估结果迭代调整。重叠度一般设为 chunk_size 的 10-20%。dedup_strategy 的 content_hash 模式计算每个文档块的 SHA-256 哈希值，与知识库中已有的向量对比，跳过重复内容，避免浪费存储和 Token 成本。metadata_key 模式则基于元数据中的指定字段（如"文档编号"）判断是否重复，适用于有明确唯一标识的结构化数据。pii_detection 在导入前扫描数据中的身份证号、手机号、银行卡号等敏感信息，生成一份 PII 报告供数据负责人审核。
三、异步任务管理与进度追踪
百万级数据的导入可能需要数分钟到数小时（取决于文档复杂度和向量化模型的吞吐量），因此所有导入操作采用 异步任务模型。提交导入任务后，API 返回：
{
"task_id": "import_7d3a9f2e1b",
"status": "queued",
"estimated_duration_seconds": 420,
"status_url": "/v1/imports/batch/import_7d3a9f2e1b",
"ws_endpoint": "wss://api.eios.isoftbao.com/v1/ws/imports/import_7d3a9f2e1b"
}开发者有三种方式追踪进度。方式一：轮询状态端点——周期性地 GET /v1/imports/batch/{task_id}，响应包含当前状态（queued/parsing/embedding/indexing/completed/failed）、已处理记录数/总记录数、已用时间/预估剩余时间、和各阶段的详细进度。方式二：WebSocket 实时推送——连接返回的 WebSocket 端点，接收阶段变更、进度更新和错误日志的实时推送，适合需要在前端 UI 中展示进度条的交互式场景。方式三：Webhook 回调通知——导入任务完成或失败时，平台向创建任务时指定的 callback_url 发送通知事件，适合后台批处理场景。任务在任意阶段失败时，系统生成一份 错误详情报告——列出失败的记录、失败原因（如文件格式错误、向量化超时、内容安全拦截）和建议的修复操作。开发者可以修复数据后，使用 POST /v1/imports/batch/{task_id}/retry 从失败点断点续传，而不是重新导入全部数据。
四、数据清洗与预处理：导入质量决定 RAG 效果
"垃圾进，垃圾出"在 RAG 场景中体现得尤为突出。导入前的数据清洗是决定 Agent 检索质量的关键前置步骤。EIOS 在导入流水线中内置了 多层次数据清洗能力。文本规范化：自动移除空行、修复乱码字符、统一全角/半角标点符号、标准化日期和数字格式。文档结构提取：对于 PDF 和 Word 文档，自动识别标题层级（H1-H4）、列表、表格和图片说明，将这些结构信息嵌入到块的元数据中。检索时可以利用这些结构信息提升相关性（如标题匹配的块优先加权）。表格处理：对于 Excel 和 CSV 文件，系统自动识别表头行，将每行的列名-值对转换为自然语言描述（如"产品名称：工业传感器 X200，单价：380 元，库存：1200 件"），比原始的行列矩阵更适合向量检索。语言识别与翻译：自动检测文档的主语言，对于混合中英文的内容，可选择性地启用机器翻译将英文部分统一为中文（或反之），保持知识库的语言一致性。数据清洗规则可通过 清洗配置文件（cleanup.yaml） 灵活定制——定义哪些字段需要清洗、使用什么清洗策略（正则替换、LLM 改写、结构化提取），并支持在处理前预览清洗效果。
五、向量化策略与存储优化
向量化是数据导入中最消耗计算资源（和成本）的环节。EIOS 提供了多种策略帮助开发者在质量、速度和成本之间找到平衡。模型选择方面：text-embedding-3-large 质量最优（3072 维），适合对检索精度要求极高的法律、医疗等场景；bge-m3 支持中英双语，维度 1024，性价比卓越，适合大多数企业场景；text-embedding-3-small 维度 512，速度最快成本最低，适合对精度要求不高的 FAQ 匹配或内部文档粗筛场景。向量存储方面：EIOS 采用 分层存储策略——热数据（最近 30 天导入或高频检索的知识库）存储在高性能的 pgvector 中（P99 检索延迟 < 10ms），温数据（30-180 天）迁移至成本更低的 Qdrant 集群（P99 检索延迟 < 50ms），冷数据（180 天以上未检索）归档至对象存储（检索时按需加载，延迟稍高但存储成本极低）。开发者可以在控制台中按知识库维度自定义冷热迁移规则。批量向量化的并发度可通过 workers 参数控制（默认 4，最大 16），更高的并发度加速导入但消耗更多平台资源。对于超大规模导入（如超过 500 万条记录），建议联系 EIOS 技术支持开通专属向量化通道。
六、大规模迁移实战案例
理论需要实践验证。以下是一个真实的大规模数据迁移案例。某国资背景的装备制造集团需要将过去 15 年积累的 技术文档、工艺规范和质量检测标准 导入 EIOS，赋能一线工程师的智能问答和故障排查。数据概况：87 万份文档（PDF/Word/DWG 图纸），总大小约 380GB，涉及 12 个专业分类，其中约 30% 为扫描件（需要 OCR）。迁移方案分四步走。第一步，文档扫描与 OCR：使用 EIOS 内置的 OCR 引擎（基于 PaddleOCR）对扫描件进行文字识别，识别准确率 96.2%，中文手写体识别准确率 89.5%。第二步，结构化预处理：按文档类型（技术标准、工艺规范、质检报告）分别配置清洗规则——技术标准提取"标准编号 + 标题 + 适用范围 + 条款内容"四段式结构；质检报告提取"产品型号 + 检测项目 + 标准值 + 实测值 + 结论"的表格化数据。第三步，分批次导入：将 87 万份文档按分类拆分为 12 个批次，每批次独立提交导入任务，并行向量化（16 Workers），全流程耗时约 52 小时。第四步，质量验证：随机抽取每批次 100 份文档，人工对比原始文档和 EIOS 检索结果的一致性，整体准确率 94.7%，经两轮迭代优化后提升至 98.2%。迁移完成后，一线工程师通过 EIOS 进行技术查询的采纳率从上线首周的 62% 稳步提升至第三个月的 89%。
