大模型应用开发 / 系统课时
补充片段元数据
补充片段元数据
只有文本内容的片段很难支持权限过滤、来源追踪和增量更新。本课将为每个片段设计一组最小元数据,并用可运行示例演示如何生成片段记录和按权限筛选检索结果。
学习目标
- 识别 RAG 片段应携带的关键元数据
- 能生成结构一致、可检索的片段记录
- 能利用元数据完成权限过滤和来源追踪
元数据解决什么问题
片段正文回答“这段内容说了什么”,元数据回答“它来自哪里、谁能看、何时更新”。两者必须一起写入向量库或检索索引。
没有元数据时,系统通常会遇到三个问题:无法在答案中标注来源,无法按用户权限过滤结果,也无法在原文更新后准确删除或重建受影响片段。
设计最小字段集合
一个可用的片段记录通常包含以下字段:
| 字段 | 作用 | 示例 |
|---|---|---|
chunk_id |
唯一标识片段 | doc-1001-0003 |
document_id |
关联原始文档 | doc-1001 |
chapter_path |
保留层级位置 | 产品手册/退款/退款时限 |
page_number |
定位 PDF 页码 | 12 |
permission |
检索前权限过滤 | internal |
updated_at |
判断是否需要重建 | 2026-08-02T06:00:00+08:00 |
text |
实际参与检索的正文 | 退款申请应在…… |
字段名称可以调整,但同一索引中的结构应保持稳定。页码不存在时可使用 null,不要用 0 混淆“第一页”和“无页码”。
生成带元数据的片段
下面示例把文档信息与切分结果组合成标准记录。时间使用带时区的 ISO 8601 字符串,便于跨系统比较和审计。
from datetime import datetime
from typing import Any
def build_chunk_records(
document_id: str,
chapter_path: str,
permission: str,
page_number: int | None,
texts: list[str],
) -> list[dict[str, Any]]:
updated_at = datetime.fromisoformat("2026-08-02T06:00:00+08:00").isoformat()
records = []
for index, text in enumerate(texts, start=1):
records.append(
{
"chunk_id": f"{document_id}-{index:04d}",
"document_id": document_id,
"chapter_path": chapter_path,
"page_number": page_number,
"permission": permission,
"updated_at": updated_at,
"text": text,
}
)
return records
if __name__ == "__main__":
chunks = ["退款申请应在交易完成后提交。", "审核通过后,系统将原路退回资金。"]
records = build_chunk_records(
document_id="doc-1001",
chapter_path="产品手册/退款",
permission="internal",
page_number=12,
texts=chunks,
)
for record in records:
print(record["chunk_id"], record["permission"], record["text"])预期输出:
doc-1001-0001 internal 退款申请应在交易完成后提交。
doc-1001-0002 internal 审核通过后,系统将原路退回资金。实际项目中,document_id、页码和更新时间应来自采集或解析流程,不能在切分阶段临时猜测。
在检索前执行权限过滤
权限字段必须在召回前参与过滤,而不是先召回敏感片段再交给模型判断。否则敏感内容可能进入提示词、日志或缓存。
例如,普通用户只能检索 public 片段,内部员工可以检索 public 和 internal。若权限更复杂,可以把单值字段改为角色数组、组织编号或访问控制列表,但应保持检索引擎可过滤。
下面是片段级过滤的片段示例,依赖上一个示例生成的 records:
allowed_permissions = {"public"}
visible_records = [
record
for record in records
if record["permission"] in allowed_permissions
]
print(len(visible_records))预期输出:
0因为示例中的两个片段权限都是 internal,普通用户不会看到它们。
保持可追溯与可更新
回答引用来源时,可以用 document_id、chapter_path 和 page_number 生成可读出处;文档更新时,则通过 document_id 找到旧片段并批量删除或重建。
updated_at 适合判断新旧版本,但不要单独把它当作唯一版本标识。更稳妥的做法是再保存内容哈希或文档版本号,用于识别内容是否真正发生变化。
常见错误:把权限、页码或章节路径拼进正文后再向量化。这样会污染语义向量,也不利于精确过滤。正文负责语义检索,元数据负责过滤、定位和治理。
本课总结
- 片段正文与元数据应作为同一条检索记录保存
- 文档编号、章节路径、页码、权限和更新时间构成常用最小字段集
- 权限过滤应在召回前完成,来源与版本字段用于追溯和增量更新
下一课预告
下一课将进入切分结果验证,检查片段长度、边界完整性、重复率和元数据一致性,确保数据可以安全写入索引。