表格存储：使用建议

Embedding 模型选型

Embedding 模型决定了向量检索的语义理解能力，创建后不可修改，是创建知识库前最重要的决策。

Metadata Schema 设计

metadata 字段在创建知识库时定义，创建后不可增删。设计时遵循以下原则：

• 提前规划：梳理所有可能用于过滤检索结果的维度（分类、时间、作者、版本、部门等），创建时一次性定义。

• 选择正确的类型：日期用 date 类型（而非 string），数值用 long 或 double，以支持范围过滤（greaterThanOrEquals 等）。

  说明

  date支持的格式：yyyy-MM-dd、yyyy-MM-dd HH:mm:ss、yyyy-MM-dd HH:mm:ss.SSS、yyyyMMdd HHmmss、yyyy-MM-dd'T'HH:mm:ss

• 控制字段数量：最多支持 200 个字段，但建议只定义实际需要的字段。

• 注意总大小限制：所有 metadata 的 key + value 合计不超过 4KB。避免在 metadata 中存储大段文本。

Subspace 规划

大批量文档导入

单次 AddDocuments 最多 10 个文档。大批量导入时建议：

• 分批上传：每批 10 个文档，按批次串行调用 AddDocuments。

• 控制并发：注意 QPS 限制，避免触发限流。

• 异步等待：所有批次上传完成后，统一轮询文档状态，而非每上传一批就等待完成。

• 错误处理：逐个检查每个文档的 status，对 failed 的文档记录失败原因，修正后重试。

OSS 文件准备

• 确保 OSS Bucket 已授权给知识库服务读写权限。授权方式参见快速开始中的前置准备。

• 单文件不超过 50MB。

• 使用 inclusionFilters 和 exclusionFilters 在 OSS 目录级别批量导入，支持首尾 * 通配符（如 *.pdf、*report*）。

文档状态轮询

正常情况下文档上传后无需主动轮询，系统会自动完成索引。如需严格确认文档是否已索引完成，建议采用指数退避策略。

文档处理时间受文件大小、类型和数量影响，小文件通常几秒完成，大文件或批量导入可能需要数分钟。退避策略在等待时间不确定时比固定间隔更合理：短文件快速返回，长文件不会频繁轮询浪费资源。

检索类型选择

Rerank 策略选择

numberOfResults 调优

检索流程中有三层 numberOfResults：

• N1（denseVectorSearchConfiguration.numberOfResults）：向量检索召回数

• N2（fullTextSearchConfiguration.numberOfResults）：全文检索召回数

• N3（rerankingConfiguration.numberOfResults）：Rerank 后最终返回数

N1 和 N2 决定候选池大小，N3 决定最终返回的结果数。推荐起始配置：N1 = N2 = 20，N3 = 5–10。

Metadata Filter 使用建议

• Filter 在检索前缩小候选范围，同时提升精度和性能。

• 过滤字段必须在创建知识库时定义为 metadata。

• 对日期范围过滤，使用 date 类型以支持范围比较。

日期格式

metadata 中 date 类型支持以下格式：

使用不支持的日期格式会导致 AddDocuments 时文档状态为 failed。