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

补充片段元数据

补充片段元数据

只有文本内容的片段很难支持权限过滤、来源追踪和增量更新。本课将为每个片段设计一组最小元数据,并用可运行示例演示如何生成片段记录和按权限筛选检索结果。

学习目标

  • 识别 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 字符串,便于跨系统比较和审计。

python
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"])

预期输出:

text
doc-1001-0001 internal 退款申请应在交易完成后提交。
doc-1001-0002 internal 审核通过后,系统将原路退回资金。

实际项目中,document_id、页码和更新时间应来自采集或解析流程,不能在切分阶段临时猜测。

在检索前执行权限过滤

权限字段必须在召回前参与过滤,而不是先召回敏感片段再交给模型判断。否则敏感内容可能进入提示词、日志或缓存。

例如,普通用户只能检索 public 片段,内部员工可以检索 public 和 internal。若权限更复杂,可以把单值字段改为角色数组、组织编号或访问控制列表,但应保持检索引擎可过滤。

下面是片段级过滤的片段示例,依赖上一个示例生成的 records:

python
allowed_permissions = {"public"}

visible_records = [
    record
    for record in records
    if record["permission"] in allowed_permissions
]

print(len(visible_records))

预期输出:

text
0

因为示例中的两个片段权限都是 internal,普通用户不会看到它们。

保持可追溯与可更新

回答引用来源时,可以用 document_id、chapter_path 和 page_number 生成可读出处;文档更新时,则通过 document_id 找到旧片段并批量删除或重建。

updated_at 适合判断新旧版本,但不要单独把它当作唯一版本标识。更稳妥的做法是再保存内容哈希或文档版本号,用于识别内容是否真正发生变化。

常见错误:把权限、页码或章节路径拼进正文后再向量化。这样会污染语义向量,也不利于精确过滤。正文负责语义检索,元数据负责过滤、定位和治理。

本课总结

  • 片段正文与元数据应作为同一条检索记录保存
  • 文档编号、章节路径、页码、权限和更新时间构成常用最小字段集
  • 权限过滤应在召回前完成,来源与版本字段用于追溯和增量更新

下一课预告

下一课将进入切分结果验证,检查片段长度、边界完整性、重复率和元数据一致性,确保数据可以安全写入索引。

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

目录与阅读设置

阅读设置

17

记录一个想法

补充片段元数据

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

登录哪都通