FDE W3D3 学习手册 · 权限和文档治理（Chunk 级 ACL / 失效删除 / 死信重试）

W3 Day3 · A 级（必须掌握，面试核心）· 5h · 学完能讲透"企业 RAG 的权限闸与文档生命周期：谁能看、旧了怎么退场、错了怎么兜底"

一、权限与文档治理全景：企业 RAG 的"安全闸"

消费级 RAG（如公开文档问答）不用管权限，但企业 RAG 直接关系商业机密与个人隐私：一份《高净值客户特药福利》手册，普通客服不该看到；一个客户的理赔记录，其他客户绝不可检索。文档治理则保证"知识库不是一潭死水"——条款修订、手册下线、解析失败都要有严谨处理，否则检索结果会混入过期/越权内容。

二、Chunk 级 ACL 数据模型设计

权限要到 Chunk 级而非 Document 级——一份 PDF 里可能前 10 页公开、后 5 页仅限理赔审核岗。所以 ACL 要挂在每个 chunk 上。

2.1 三种常见授权维度

2.2 chunk 上的 ACL 字段设计

{
  "chunk_id": "c_8f3a...",
  "content": "高净值客户特药年度额度 50 万...",
  "acl": {
    "allowed_roles": ["claims_auditor", "vip_advisor"],
    "allowed_depts": ["special_drug"],
    "allowed_users": [],
    "visibility": "internal"        // public / internal / restricted
  }
}

2.3 设计要点

• 继承 + 覆盖：chunk 默认继承 document 级 ACL，敏感段落可单独收紧（覆盖）。
• 用位或组合：检索时"用户角色命中 OR 部门命中 OR 显式用户"即放行，避免维度爆炸。
• 默认最小权限：未标注的 chunk 按"仅内部"处理，防止漏配导致公开泄露。

三、检索时的权限过滤（用户 / 角色 / 部门）

权限过滤必须发生在检索阶段（预过滤），确保越权 chunk 根本不进候选集。以 ES 为例：

def build_acl_filter(user):
    return {
      "bool": {
        "should": [
          {"terms": {"acl.allowed_roles": user.roles}},
          {"terms": {"acl.allowed_depts": user.depts}},
          {"terms": {"acl.allowed_users": [user.id]}}
        ],
        "must_not": [ {"term": {"acl.visibility": "restricted_external"}} ],
        "minimum_should_match": 1
      }
    }

# 检索：ACL 过滤 与 BM25/向量 召回 在 bool 内 AND
query = {
  "bool": {
    "filter": [ build_acl_filter(current_user) ],     # 权限硬约束
    "should": [ {"match": {"content": q}},
                {"knn": {"field":"embedding","query_vector":qv,"k":50}} ]
  }
}

3.1 关键原则

• filter 不是 must：用 filter 上下文（不评分、可缓存），权限是硬约束不参与相关性打分。
• 最小权限校验在服务端：不能依赖前端传"用户角色"——要从服务端会话取，防伪造。
• LLM 也要收到过滤后的上下文：即便检索过滤了，传给 LLM 的 chunks 必须是已授权的。

四、文档失效、删除与索引失效处理

4.1 三种"下线"语义

4.2 软失效优于硬删除

医疗合规要求"可追溯"，所以优先 软失效（status 标记）而非物理删。只有确认无审计价值且合规允许才硬删。

五、增量更新与一致性保证

5.1 增量更新流程

文档小改（如某页条款数字调整）不必全量重摄取，只更新受影响 chunk：定位变更 chunk → 重新解析该块 → 重算 embedding → 原子替换旧向量。

5.2 一致性三要素

• 版本一致：chunk 的 doc_version/embedding_version 与实际内容匹配。
• 计数一致：document 的 chunk 数 = 索引中该 doc 的 active chunk 数。
• 引用一致：chunk 的 source/page 指向真实存在的内容。

六、失败重试与死信队列（DLQ）

6.1 重试策略

6.2 死信队列设计

def handle_ingest(task):
    for attempt in range(MAX_RETRY := 5):
        try:
            run_pipeline(task); return mark_success(task)
        except TransientError:
            sleep(backoff(attempt)); continue
        except PermanentError as e:
            send_to_dlq(task, reason=str(e)); return   # 不无限重试
    send_to_dlq(task, reason="exceeded retries")

七、原文件 / 解析结果 / 索引一致性校验

三份数据（原始文件、解析后的结构化文本、向量索引）可能因中途失败而漂移，需要定期/事件触发校验。

def consistency_check(doc_id):
    src_hash = sha256(load_raw(doc_id))
    parsed  = load_parsed(doc_id)
    chunks  = es.count(filter={"document_id": doc_id, "status":"active"})
    vectors = vector_store.count(document_id=doc_id)
    assert parsed.file_hash == src_hash, "解析与源不一致"
    assert chunks == vectors, "chunk 数与向量数不一致"
    # 不一致 → 入修复队列

八、ES Metadata Filter 实现 ACL 过滤

Elasticsearch 的 terms 查询是 ACL 过滤的利器——用服务端用户身份构造过滤条件。

# 服务端取身份（不从前端信任）
user_roles = get_roles_from_session(request)     # ["claims_auditor"]
user_depts = get_depts_from_session(request)     # ["special_drug"]
user_id    = get_user_id(request)                # "u_1001"

acl_filter = {
  "bool": {
    "should": [
      {"terms": {"acl.allowed_roles": user_roles}},
      {"terms": {"acl.allowed_depts": user_depts}},
      {"terms": {"acl.allowed_users": [user_id]}}
    ],
    "minimum_should_match": 1
  }
}
# 与召回 AND：{ "bool": { "filter": [acl_filter], "should": [bm25, knn] } }

九、LangChain 自查询检索器（Self-Query Retriever）

自查询检索器让 LLM 从自然语言问题里自动抽取结构化过滤条件（metadata filter），把"用户口语"转成"ES 过滤+语义查询"。

from langchain.retrievers import SelfQueryRetriever
from langchain.retrievers.self_query.base import AttributeInfo

metadata_field_info = [
    AttributeInfo(name="acl.allowed_roles", description="可访问角色", type="list[string]"),
    AttributeInfo(name="doc_version", description="文档版本", type="string"),
    AttributeInfo(name="section", description="章节", type="string"),
]
retriever = SelfQueryRetriever.from_llm(
    llm, vectorstore, "保险知识库", metadata_field_info,
    search_kwargs={"k": 8}
)
# 用户问"理赔审核岗能看的靶向药报销范围" → LLM 生成 filter: allowed_roles contains claims_auditor
docs = retriever.get_relevant_documents("理赔审核岗能看的靶向药报销范围")

十、文档治理的运维与监控

十一、评测集扩展到 30 Cases 的策略

W3D1 你有 10 个 Golden Case，W3D3 治理主题要把评测集扩到 30，重点是补权限与治理类 case。

十二、面试达标线①：Chunk 级 ACL 实现与检索过滤

十三、面试达标线②：更新/删除一致性与死信重试设计

1. 文档下线三语义：失效（保留审计）/删除（物理+日志）/替换（原子切换新旧）。
2. 一致性三要素：版本一致、计数一致（doc chunk 数=索引 active 数）、引用一致。
3. 增量更新：只更新受影响 chunk，级联更新另两份数据，防索引腐化。
4. 死信重试：区分瞬时/持久错误，持久错误超重试进 DLQ 并告警重放，主流程不被拖死。

十四、W3D3 自测清单

十五、高频面试题速记卡