导入与解析

导入不是一次简单的文件上传。SAG 会把不同来源规范化为 Markdown，随后执行分块、向量化与 event-entity 抽取，并用后台任务记录整个过程。

支持的来源

当前参考应用包含文件上传与网页连接器。常见可解析内容包括 Markdown、纯文本、PDF、Word、PowerPoint 与 Excel；具体格式能力由 MarkItDown 和可选的 MinerU 共同决定。

API 还支持直接写入一段文本或一批消息，适合持续同步对话、笔记和其他应用数据。

处理流水线

source
  -> normalize to Markdown
  -> semantic chunks
  -> chunk embeddings
  -> one event per chunk
  -> entities per chunk
  -> relational + vector indexes
  -> ready

每个 chunk 的原文始终保留。Event 与 entity 用于定位和扩展候选，最终展示、生成和引用仍回到 chunk。

文档解析器

默认 SAG_DOCUMENT_PARSER=auto：

• PDF 在 MinerU 配置完整时优先使用 MinerU 2.5。
• MinerU 未配置、超时或失败时回退到本地 MarkItDown。
• Office 与文本格式默认使用 MarkItDown。

MinerU 任务状态和结果可以续跑与缓存，避免后台重试或并发处理导致重复计费。

分块设置

默认分块上限为 1000 tokens，模式为 standard：

SAG_DOCUMENT_CHUNK_MAX_TOKENS=1000
SAG_DOCUMENT_CHUNK_MODE=standard

更小的块通常提高局部定位精度，但会增加向量、抽取和关系记录数量；更大的块保留更多上下文，但可能降低精确定位能力。修改策略后应对已有文档执行重新处理，不能只改环境变量后继续沿用旧索引。

后台任务

文档写入会返回文档记录，处理由后台任务继续执行。默认最多尝试 3 次：

SAG_JOB_MAX_ATTEMPTS=3
SAG_DOCUMENT_EXTRACT_CONCURRENCY=5

任务可暂停、恢复和重新处理。出现错误时优先查看文档状态与 API 日志，不要连续重复上传同一文件。

更新与删除

重新处理会基于当前解析和模型设置重建文档索引。删除文档时，应用适配层会同步清理相关 chunk、event、entity 关联与上传文件，避免残留可检索内容。

需要批量或自动化写入时，使用 POST /api/v1/sources/{source_id}/documents/ingest。完整请求结构见REST API 参考。