大模型应用开发 / 系统课时
设计文档数据模型
设计文档数据模型
这一节把知识文档整理成一个稳定、可追踪、可过滤的数据结构。完成后,每条文档都拥有唯一编号、标题、来源、正文、更新时间和权限标识,后续切块、索引、增量更新与权限过滤都能复用这些字段。
学习目标
- 定义 RAG 文档最小必需字段及其职责
- 设计稳定的唯一编号、时间与权限字段
- 用校验代码阻止缺字段或错误类型的数据进入索引
先确定最小字段集合
文档模型应先解决“内容是什么、从哪里来、是不是同一条、什么时候更新、谁能看”这五个问题。字段不宜一开始就堆得过多,否则采集端和索引端都会承担不必要的兼容成本。
| 字段 | 建议类型 | 作用 |
|---|---|---|
id |
string | 文档稳定唯一编号,更新时保持不变 |
title |
string | 检索展示与人工定位标题 |
source |
string | 原始来源标识,例如文件路径、页面地址或业务系统键 |
content |
string | 可进入切块与检索流程的正文 |
updatedAt |
string | ISO 8601 时间,用于增量同步和新旧判断 |
permissions |
string[] | 可见范围标识,用于检索前或检索时过滤 |
这里的 id 应由业务稳定键或可重复计算规则产生,不要在每次导入时随机生成新值,否则同一文档会被误判成新增记录。updatedAt 建议统一使用带时区的 ISO 8601 字符串,避免不同采集源之间无法比较时间。
写出一条标准文档
下面的 JSON 可以直接作为采集层与索引层之间的数据契约。permissions 使用数组,是为了同时表达多个角色、租户或知识域。
{
"id": "kb-refund-policy",
"title": "退款规则",
"source": "help-center/refund-policy",
"content": "订单支付后七天内且未使用服务时,可以申请原路退款。",
"updatedAt": "2026-09-04T00:00:00Z",
"permissions": ["customer", "support"]
}这个结构本身不产生控制台输出。验证方式是检查所有必需字段都存在、字符串字段非空、permissions 为字符串数组,并确认相同来源再次同步时仍然复用原 id。
在进入索引前做校验
采集数据通常来自文件、CMS 或数据库,最常见的问题不是检索算法,而是空正文、缺少编号或权限类型错误。可以在写入索引前加一道轻量校验。
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))预期输出:
True校验通过只说明结构满足约定,不代表权限策略已经安全生效。权限过滤必须在检索链路中真正参与候选集筛选,不能只把 permissions 当作展示字段。
为切块和更新保留稳定语义
后续把一篇文档切成多个 chunk 时,文档级 id 仍应保持稳定,chunk 可以另外派生自己的编号,例如由“文档 id + 块序号”组成。这样删除、重建和追踪来源时都能回到原文档,而不会把块编号误当成业务主键。
增量同步时,应先根据 id 找到已有文档,再比较 updatedAt 或上游版本信息决定是否重建索引。只要这六个基础字段定义清楚,后续增加作者、标签、语言或内容哈希,都可以作为扩展字段逐步引入,而不必推翻最初的数据契约。