大模型应用开发 / 系统课时

设计文档数据模型

设计文档数据模型

这一节把知识文档整理成一个稳定、可追踪、可过滤的数据结构。完成后,每条文档都拥有唯一编号、标题、来源、正文、更新时间和权限标识,后续切块、索引、增量更新与权限过滤都能复用这些字段。

学习目标

  • 定义 RAG 文档最小必需字段及其职责
  • 设计稳定的唯一编号、时间与权限字段
  • 用校验代码阻止缺字段或错误类型的数据进入索引

先确定最小字段集合

文档模型应先解决“内容是什么、从哪里来、是不是同一条、什么时候更新、谁能看”这五个问题。字段不宜一开始就堆得过多,否则采集端和索引端都会承担不必要的兼容成本。

字段 建议类型 作用
id string 文档稳定唯一编号,更新时保持不变
title string 检索展示与人工定位标题
source string 原始来源标识,例如文件路径、页面地址或业务系统键
content string 可进入切块与检索流程的正文
updatedAt string ISO 8601 时间,用于增量同步和新旧判断
permissions string[] 可见范围标识,用于检索前或检索时过滤

这里的 id 应由业务稳定键或可重复计算规则产生,不要在每次导入时随机生成新值,否则同一文档会被误判成新增记录。updatedAt 建议统一使用带时区的 ISO 8601 字符串,避免不同采集源之间无法比较时间。

写出一条标准文档

下面的 JSON 可以直接作为采集层与索引层之间的数据契约。permissions 使用数组,是为了同时表达多个角色、租户或知识域。

json
{
  "id": "kb-refund-policy",
  "title": "退款规则",
  "source": "help-center/refund-policy",
  "content": "订单支付后七天内且未使用服务时,可以申请原路退款。",
  "updatedAt": "2026-09-04T00:00:00Z",
  "permissions": ["customer", "support"]
}

这个结构本身不产生控制台输出。验证方式是检查所有必需字段都存在、字符串字段非空、permissions 为字符串数组,并确认相同来源再次同步时仍然复用原 id。

在进入索引前做校验

采集数据通常来自文件、CMS 或数据库,最常见的问题不是检索算法,而是空正文、缺少编号或权限类型错误。可以在写入索引前加一道轻量校验。

python
def validate_document(doc):
    required = ["id", "title", "source", "content", "updatedAt", "permissions"]
    missing = [name for name in required if name not in doc]
    if missing:
        raise ValueError(f"missing fields: {missing}")
    if not all(isinstance(doc[name], str) and doc[name].strip()
               for name in ["id", "title", "source", "content", "updatedAt"]):
        raise ValueError("string fields must be non-empty")
    if not isinstance(doc["permissions"], list) or not all(
        isinstance(item, str) and item for item in doc["permissions"]
    ):
        raise ValueError("permissions must be a non-empty string list")
    return True

document = {
    "id": "kb-refund-policy",
    "title": "退款规则",
    "source": "help-center/refund-policy",
    "content": "订单支付后七天内且未使用服务时,可以申请原路退款。",
    "updatedAt": "2026-09-04T00:00:00Z",
    "permissions": ["customer", "support"],
}

print(validate_document(document))

预期输出:

text
True

校验通过只说明结构满足约定,不代表权限策略已经安全生效。权限过滤必须在检索链路中真正参与候选集筛选,不能只把 permissions 当作展示字段。

为切块和更新保留稳定语义

后续把一篇文档切成多个 chunk 时,文档级 id 仍应保持稳定,chunk 可以另外派生自己的编号,例如由“文档 id + 块序号”组成。这样删除、重建和追踪来源时都能回到原文档,而不会把块编号误当成业务主键。

增量同步时,应先根据 id 找到已有文档,再比较 updatedAt 或上游版本信息决定是否重建索引。只要这六个基础字段定义清楚,后续增加作者、标签、语言或内容哈希,都可以作为扩展字段逐步引入,而不必推翻最初的数据契约。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计文档数据模型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通