LlamaIndex + LightRAG 数据治理知识库实施计划

状态：技术方案已确认，尚未进入代码实施。

目标：在不替换 DataOps 控制面、治理 Neo4j 和现有 PostgreSQL 的前提下，交付权限安全、可追溯、可评测、可降级，并能随治理事实变化进行知识点级增量更新的治理知识库。

2026-07-22 修订：将知识点版本、语义 Diff、依赖影响传播、增量索引、缓存失效和原子发布纳入正式实施范围；不再把“对象级文档重建”视为动态更新的完整实现。

1. 交付结论

本计划采用：

LlamaIndex：Flask 内部唯一 RAG 主框架；
LightRAG：内部图增强检索侧车；
PostgreSQL/pgvector：规范化文档、分块、向量和控制状态；
现有 Neo4j：治理对象与血缘源真相，只读检索；
独立 LightRAG Neo4j：可重建的抽取图；
Qwen：embedding；
独立 reranker：候选精排；
DeepSeek：最终问答。

知识动态更新采用：

稳定 point_key：标识跨版本不变的知识语义位置；
knowledge_points：保存知识点版本和有效期；
knowledge_point_dependencies：保存治理事实和确定性规则形成的依赖；
knowledge_change_sets：记录一次变更的 Diff、影响范围、发布和回滚状态；
语义快照 + Diff：区分 added、modified、deleted、unchanged；
有边界的影响传播：只重建受影响的 chunk、embedding、LightRAG 投影和缓存；
prepare/validate/activate：新版本校验通过后原子切换，失败时保留旧 active 版本。

不采用：

Haystack 与 LlamaIndex 双框架；
LightRAG WebUI 作为 DataOps 用户入口；
LightRAG 直接生成最终用户答案；
LightRAG 直接写入现有治理 Neo4j；
新增 Milvus、Elasticsearch、Qdrant 或 Redis 作为首期必需依赖。

2. 当前基线与必须补齐的缺口

已存在

deploy/docker/docker-compose.yml 已使用 PostgreSQL 16 + pgvector 和 Neo4j 5。
20260716_40_governance_knowledge.py 已创建文档、分块和同步任务表。
app/core/knowledge/document_builder.py 已提供确定性 JSON 文档和基础脱敏。
app/services/embedding/qwen.py 已提供 Qwen Embedding 客户端。
app/core/events/outbox.py 已提供 Outbox、幂等消费和失败状态。
app/core/system/permissions.py 已提供管理员、编辑者、查看者的服务端 RBAC。
前端 /knowledge-base-product 已保留“数据治理知识库”入口。

缺口

当前文档是紧凑 JSON，固定按 1200 字符切分，可能切断字段和关系语义。
governance_chunks 没有词法索引、结构化 metadata、section path 和 token 数。
没有向量索引 generation，模型切换无法安全影子重建。
没有检索、重排、引用和回答实现。
没有治理对象变更事件的完整生产者。
当前 Outbox 是全局 claim 状态，不能假设同一个事件会被多个独立消费者依次处理。
Web 身份只有角色，没有持久化的用户—业务域授权。
没有 LightRAG 投影状态、来源映射、删除补偿和隔离存储。
没有黄金问题集、离线评测和发布门禁。
没有稳定知识点模型，无法判断治理对象内部具体哪些事实发生变化。
没有知识点依赖和影响传播，字段、标准、指标、血缘之间的联动只能全量重建或留下陈旧内容。
没有 change set、缓存依赖和知识新鲜度契约，不能证明一次动态变更已经完整发布。

3. 实施原则

源真相不变。 治理对象在 Neo4j，身份/授权/索引控制状态在 PostgreSQL， LightRAG 只保存投影。
先过滤，再召回，再复核。 权限不依赖前端和 Prompt。
最终回答只有一个出口。 DataOps Answer Synthesizer 负责 DeepSeek 和引用。
旧索引持续可用。 新版本或新模型失败不覆盖 active generation。
外部组件可关闭。 关闭 LightRAG 后仍有完整的标准检索和问答闭环。
所有外部写入幂等。 使用稳定对象 UID、版本、内容哈希和 generation。
先评测后放量。 LightRAG 先影子运行，不因接入完成就默认进入正式答案。
知识点是最小变更单元。 对象和文档仍是来源及授权边界，但更新、影响分析、缓存失效和新鲜度判断下沉到稳定 point_key。
变化先 Diff 再构建。 相同知识点内容不重复 embedding；删除和权限收紧先使 canonical 内容不可见，再异步清理外部投影。
影响传播必须有界。 依赖传播限定关系类型、最大 hop 和最大对象/知识点数；超过阈值时升级为新 generation 的影子重建。
发布状态可证明。 每次变化都形成 change set，只有 canonical 产物、权限和引用通过校验后才标记 active；LightRAG 等异步投影单独报告 ready/degraded，部分成功不能被报告为投影完成。

4. 运行时架构

flowchart TB
    subgraph Write["索引写链路"]
        SOURCE["Neo4j / PostgreSQL 治理对象"] --> EVENT["governance.* Outbox 事件"]
        EVENT --> SNAP["规范化语义快照"]
        SNAP --> DIFF["知识点级 Diff"]
        DIFF --> IMPACT["有界依赖影响传播"]
        IMPACT --> INDEXER["Knowledge Indexer"]
        INDEXER --> DOC["知识点 + 结构化分块"]
        DOC --> EMB["仅对变化内容生成 Qwen Embedding"]
        EMB --> CANON["Canonical Index\nPostgreSQL + pgvector"]
        CANON --> ACTIVATE["校验 + 原子切换"]
        ACTIVATE --> INVALIDATE["精准缓存失效"]
        CANON --> PROJ["knowledge_index_projections"]
        PROJ --> LRWORKER["LightRAG Projection Worker"]
        LRWORKER --> LRSVC["LightRAG Service"]
        LRSVC --> LRPG["LightRAG PostgreSQL"]
        LRSVC --> LRNEO["LightRAG Neo4j"]
    end

    subgraph Read["查询读链路"]
        API["/api/knowledge"] --> ACCESS["KnowledgeAccessContext"]
        ACCESS --> PIPE["LlamaIndex Retrieval Pipeline"]
        PIPE --> LEX["Lexical / Alias"]
        PIPE --> VEC["pgvector"]
        PIPE --> GRA["治理 Neo4j"]
        PIPE --> LRC["LightRAG Client"]
        LEX --> RRF["RRF"]
        VEC --> RRF
        GRA --> RRF
        LRC --> AUTHZ["Canonical Source Re-authorization"]
        RRF --> AUTHZ
        AUTHZ --> RERANK["Reranker"]
        RERANK --> QA["DeepSeek Answer Synthesizer"]
    end

写链路中的 canonical active 版本是查询可见性的唯一开关。LightRAG 投影可以在 canonical 发布后异步完成；但任何 LightRAG 上下文在进入答案前仍必须映射到当前 active 的 point_key、来源对象和版本。

5. 数据模型

5.1 新迁移

建议新增：

migrations/versions/20260720_100_llamaindex_lightrag_knowledge.py

revision = "20260720_100"
down_revision = "20260719_90"
V100 是 Alembic revision，不是产品版本。

5.2 用户—业务域授权

新增 user_business_domain_grants：

字段	说明
`user_id UUID`	FK `users.id`
`business_domain_uid UUID`	稳定治理 UID
`grant_type VARCHAR(20)`	`read` / `manage`
`granted_by UUID`	管理员
`created_at TIMESTAMPTZ`	授权时间

约束：

主键 (user_id, business_domain_uid, grant_type)；
admin 可解析为 *，但不写伪造的全局业务域 UID；
删除用户时级联删除授权；
非管理员没有授权记录时返回空范围，而不是默认全量。

5.3 知识点、版本与有效期

新增 knowledge_points。一行表示一个知识点的一个版本，不把覆盖更新当作版本管理：

字段	说明
`id UUID`	知识点版本 ID
`point_key VARCHAR(500)`	跨源版本稳定的语义位置标识
`point_revision BIGINT`	同一 `point_key` 内单调递增的知识点版本
`source_type VARCHAR(50)`	`BusinessDomain` / `DataFlow` / `DataMeta` / `DataStandard` / `Label`
`source_uid UUID`	来源治理对象稳定 UID
`source_revision BIGINT`	来源对象单调版本
`semantic_path VARCHAR(500)`	对象内部字段或关系路径
`content TEXT`	脱敏、规范化后的知识内容
`content_hash CHAR(64)`	规范化内容 SHA-256
`metadata JSONB`	名称、关系端点、权限范围和 source locator
`status VARCHAR(20)`	`building` / `active` / `superseded` / `deleted` / `failed`
`valid_from/valid_to TIMESTAMPTZ`	业务有效期；`valid_to` 可空
`created_at/activated_at TIMESTAMPTZ`	构建与发布时刻

约束和索引：

UNIQUE(point_key, point_revision)；
对 status='active' 建部分唯一索引，保证同一 point_key 最多一个 active 版本；
(source_type, source_uid, source_revision) 普通索引；
(content_hash) 普通索引，用于复用未变化内容；
删除使用 deleted tombstone，审计保留期内不物理删除版本历史。

source_revision 表示来源对象版本，point_revision 表示知识点自身版本。一个对象 revision 可以同时改变多个 point；依赖传播只要求重建某个 point 的派生产物时，可以保留其 point revision，并通过新的 chunk hash/generation 体现派生索引变化。

point_key 只由稳定 UID、固定语义路径和稳定关系类型构成，不包含显示名称、数组下标、文本内容或内容哈希。例如：

BusinessDomain/{domain_uid}/definition
DataFlow/{flow_uid}/owner
DataFlow/{flow_uid}/reads_from/{metadata_uid}
DataMeta/{table_uid}/fields/{field_uid}/definition
DataStandard/{standard_uid}/rules/{rule_uid}

如果源系统没有字段/规则的稳定 UID，必须先建立确定性 surrogate key 和迁移映射；不得用列表位置生成 point_key，否则重排会被误判为批量删除与新增。

5.4 知识点依赖、Change Set 与缓存依赖

新增 knowledge_point_dependencies：

字段	说明
`from_point_key`	依赖发起方
`to_point_key`	被依赖知识点
`relation_type`	`uses` / `defines` / `derived_from` / `governs` / `lineage`
`source`	`governance` / `deterministic_rule`
`generation`	关系所属 generation
`status`	`active` / `superseded` / `deleted`

约束：

主键 (from_point_key, to_point_key, relation_type, source, generation)；
governance 和 deterministic_rule 可驱动正式影响传播；
传播规则必须配置关系白名单，禁止沿任意抽取边无限扩散。

LightRAG 模型抽取关系继续只保存在隔离的 LightRAG 图和投影诊断中，不写入 knowledge_point_dependencies。这样依赖传播的输入始终来自治理事实或确定性代码，不会把模型推断边升级成 canonical 依赖。

新增 knowledge_change_sets：

字段	说明
`id UUID` / `correlation_id UUID`	变更和全链路追踪标识
`source_type/source_uid/source_revision`	来源对象与目标版本
`change_type`	`create` / `update` / `delete` / `permission` / `rebuild`
`source_snapshot_hash`	本次规范化快照哈希
`added/modified/deleted_count`	直接 Diff 统计
`impacted_point_count`	依赖传播后的影响数量
`impact_truncated BOOLEAN`	是否因边界升级为 generation 重建
`status`	`pending` / `diffed` / `building` / `validating` / `canonical_active` / `projecting` / `complete` / `degraded` / `failed` / `rolled_back`
`target_generation`	目标索引 generation
`last_error`	脱敏错误与阶段
`created_at/activated_at`	生命周期

新增 knowledge_change_items，按 change_set_id + point_key 保存：

change_kind：added / modified / deleted / impacted；
old/new point version 和 content hash；
影响来源 caused_by_point_key 与传播 hop；
canonical、embedding、cache、LightRAG 各阶段状态；
重试次数和脱敏错误。

新增 knowledge_cache_dependencies：

字段	说明
`cache_key_hash`	不记录原始查询文本的缓存键哈希
`point_key`	回答或检索结果依赖的知识点
`point_revision`	生成缓存时使用的知识点版本
`generation`	索引 generation
`expires_at`	最大生存时间

任何 modified、deleted、权限收紧或 active generation 切换都按 point_key 删除相关缓存；依赖记录缺失时必须失效整个业务域缓存，不能继续返回无法证明新鲜度的结果。

5.5 规范化分块

扩展 governance_chunks：

字段	说明
`chunk_kind`	`summary`、`definition`、`field`、`relation`、`attachment`
`section_path`	标题/字段路径
`metadata JSONB`	对象类型、别名、责任人、业务域、关系端点等
`token_count`	使用固定 tokenizer 计算
`lexical_text`	名称、编码、别名和正文的规范化检索文本
`search_vector TSVECTOR`	PostgreSQL 词法索引
`source_locator JSONB`	Neo4j UID、MinIO object key、页码/表格定位

索引：

GIN(search_vector)；
GIN(metadata jsonb_path_ops)；
(document_id, chunk_no) 保留唯一；
document_id 普通索引；
常用范围 (chunk_kind) 与文档上的 (business_domain_uid, object_type, status) 联合索引。

首期中文精确检索不只依赖 PostgreSQL 自带分词：

对对象名、英文名、表名、字段名、编码和显式别名建立 normalized alias；
精确匹配、前缀匹配和 pg_trgm 召回独立计分；
语义召回由 pgvector 负责；
是否引入 zhparser 必须经过独立镜像、许可证和部署验证，不作为首期前置条件。

每个 chunk 新增：

primary_point_key：该 chunk 的主要知识点；
point_keys JSONB：chunk 覆盖的全部知识点；
point_set_hash：知识点集合和版本哈希；
change_set_id：生成本 chunk 的 change set。

同一知识点可以映射到多个 chunk，一个 chunk 也可以包含多个紧密相关知识点；但每个 chunk 必须能反查其知识点依赖，支持精准重建、缓存失效和引用新鲜度校验。

5.6 Embedding profile 与 generation

新增 knowledge_embedding_profiles：

字段	说明
`id UUID`	profile ID
`provider`	`qwen`
`model`	模型名
`dimension`	首期固定 1024
`distance`	`cosine`
`status`	`building`、`active`、`retired`、`failed`
`config_hash`	不包含密钥的配置哈希
`created_at/activated_at`	生命周期

新增 knowledge_chunk_embeddings：

字段	说明
`id UUID`	embedding ID
`chunk_id UUID`	FK `governance_chunks.id`
`profile_id UUID`	FK profile
`embedding vector(1024)`	向量
`embedding_hash`	输入、模型和维度哈希
`created_at`	创建时间

约束和索引：

UNIQUE(chunk_id, profile_id)；
active profile 使用 HNSW cosine 索引；
小语料验收阶段保留 exact scan 基线；
ANN 与业务域过滤组合必须测 Recall；必要时启用 pgvector iterative scan 或 oversampling，不能只看延迟。

现有 governance_chunks.embedding* 字段首期保留兼容，不在同一迁移中删除。完成双读、回填和切换后再单独下线。

维度变化不允许写入同一个 vector(1024) 表。必须建立新维度的 shadow 表和新 profile，完整重建并切换。

knowledge_chunk_embeddings.embedding_hash 必须包含规范化 chunk hash、模型、维度和 tokenizer profile。知识点集合与内容均未变化时复用现有 embedding；只改变责任人等独立知识点时，不重算无关 definition/relation chunk。

5.7 外部引擎投影

新增 knowledge_index_projections：

字段	说明
`id UUID`	投影记录
`document_id UUID`	canonical document
`change_set_id UUID`	触发投影的 change set
`engine`	`canonical_vector` / `lightrag`
`generation`	索引 generation
`workspace`	安全分区
`external_document_id`	LightRAG 幂等文档 ID
`content_hash`	投影输入哈希
`status`	`pending`、`processing`、`ready`、`failed`、`deleting`、`deleted`
`attempts/available_at`	有上限重试
`last_error`	脱敏错误
`updated_at`	健康与巡检

唯一键：

(document_id, engine, generation, workspace)

LightRAG external_document_id 固定使用：

dataops:{object_type}:{object_uid}:v{object_version}:{content_hash前12位}

对支持知识点级外部 ID 的适配层，首选：

dataops:point:{point_key的SHA256前24位}:p{point_revision}:{content_hash前12位}

如果 LightRAG 只能以文档为最小删除单位，则按“来源对象 + 业务域 + generation”维护投影包：任一知识点变化时删除旧包并重插该对象的当前 active 知识点。该限制必须通过 K0 契约测试确认，不能假设底层支持不存在的局部更新语义。

5.8 查询审计与评测

新增：

knowledge_query_audits
knowledge_evaluation_sets
knowledge_evaluation_cases
knowledge_evaluation_runs
knowledge_evaluation_results

查询审计默认只保存：

query hash，不保存完整问题正文；
用户、角色、授权业务域摘要；
路由模式和各 Retriever 命中数量；
最终引用的 object UID/version；
最终引用的 point_key、point revision、source update time 和 index generation；
延迟、模型、token、降级状态和 correlation ID。

如需保存问题/答案样本，必须由管理员显式标记并进入有保留期限的评测集。

6. 规范化文档协议

替换紧凑 JSON + 固定字符切割，按对象类型使用确定性模板。

每个 canonical document 至少包含：

object_type: DataFlow
object_uid: 019...
object_version: 7
object_name: 客户主数据同步
aliases:
  - customer_master_sync
business_domain_uid: 019...
owner: 数据治理组
source_updated_at: 2026-07-20T...
definitions:
  purpose: ...
  inputs: ...
  outputs: ...
relations:
  - type: READS_FROM
    target_uid: 019...
    target_name: 客户表
knowledge_points:
  - point_key: DataFlow/019.../purpose
    semantic_path: definitions/purpose
    content_hash: sha256:...
  - point_key: DataFlow/019.../reads_from/019...
    semantic_path: relations/READS_FROM/019...
    content_hash: sha256:...
permission_scope:
  business_domains:
    - 019...

构建规则：

字段、关系和别名排序稳定；
时间统一 UTC ISO-8601；
secret key 使用递归、大小写不敏感和模式匹配脱敏；
每类对象使用黄金 fixture；
summary、definition、field 和 relation 分块不跨类型切断；
超长字段在 token 边界切分并保留父标题和对象摘要；
每个 chunk 都携带 object UID、version、domain、kind 和 source locator；
每个知识点携带稳定 point_key、semantic path、content hash 和依赖端点；
同一来源快照产生相同 document、point set 和 chunk hash；
只改变字段顺序、JSON 键顺序或无语义格式时，Diff 必须为 unchanged；
显示名称变化不改变已有 point_key，但名称知识点内容和依赖它的检索别名会更新；
point/chunk 的 permission scope 从 canonical 来源计算，不接受模型抽取值。

每类对象必须实现 KnowledgePointBuilder，输出排序稳定的：

KnowledgeSnapshot(
    source_type=...,
    source_uid=...,
    source_revision=...,
    source_snapshot_hash=...,
    permission_scope=...,
    points=tuple[KnowledgePointDraft, ...],
    dependencies=tuple[KnowledgeDependencyDraft, ...],
)

Builder 是确定性领域代码，不使用 LLM 判断 point identity。LLM 只能在 LightRAG 投影中抽取辅助关系，不能生成 canonical point_key、权限或版本。

7. 同步与一致性

7.1 事件类型

治理写路径在同一业务事务中产生：

governance.business_domain.changed
governance.dataflow.changed
governance.metadata.changed
governance.standard.changed
governance.label.changed
governance.object.deleted

payload 只包含：

object type/UID/version；
source update time；
correlation ID；
变更类型；
可选的 changed field/relationship hints，仅用于优化，不能作为完整 Diff 的事实源；
不包含完整附件或密钥。

事件处理规则：

以 (source_type, source_uid, source_revision) 幂等；
revision 小于当前 active revision 的乱序事件记录为 stale 并跳过，不允许回退；
revision 相同但 snapshot hash 不同视为源版本协议错误，进入人工检查；
事件 hint 与实际语义快照不一致时以重新读取的源快照为准。

7.2 单消费者协调

当前 Outbox 的 event status 是全局状态，不能让 canonical indexer 与 LightRAG 各自 claim 同一个事件。

首期采用：

governance.* 只注册一个 KnowledgeIndexHandler；
Handler 创建或恢复一个 knowledge_change_sets，执行快照、Diff、影响分析和 canonical 发布；
同一 PostgreSQL 事务写 change items、缓存失效任务和 knowledge_index_projections(status='pending')；
独立 LightRAG Projection Worker 只 claim projection 表；
缓存失效 worker 只 claim cache invalidation 任务，删除操作和权限收紧使用高优先级；
不把当前 Outbox 伪装成多订阅消息总线。

同一 (source_type, source_uid) 的 Diff 与 activate 必须串行。实现使用数据库行锁或 transaction-scoped advisory lock；锁内再次读取当前 active source revision，防止两个 worker 分别基于同一旧快照发布出相互覆盖的版本。不同来源对象可以并行处理。

未来若其他业务也需要 fan-out，再独立增加 outbox_deliveries，不在本阶段扩大。

7.3 语义快照与知识点 Diff

KnowledgeIndexHandler 对每个事件执行：

在一致性读取边界内重新读取治理对象、稳定子对象 UID、关系和权限范围；
使用对应 KnowledgePointBuilder 构建新 KnowledgeSnapshot；
读取该对象当前 active point set；
按 point_key 对比 old/new snapshot；
写入 change set 和 change items；
对 unchanged point 复用 active point/chunk/embedding；
对 added、modified、deleted 进入影响分析。

Diff 判定：

情况	change kind	后续动作
新快照有、旧快照无	`added`	新建 point、chunk、embedding 和投影
两边都有、content/metadata/permission hash 变化	`modified`	建新版本，重建相关产物
旧快照有、新快照无	`deleted`	准备 tombstone，删除相关产物
key 和所有语义 hash 相同	`unchanged`	复用，不调用 embedding

权限 hash 单独比较。权限扩大按普通修改发布；权限收紧进入高优先级安全路径，不等待 LightRAG 或 embedding 完成后才禁止旧内容查询。

7.4 有界依赖影响传播

直接 Diff 完成后，从 added、modified、deleted point 沿 knowledge_point_dependencies 计算受影响集合：

只沿配置白名单中的确定性关系传播；
默认最大 hop 为 3，具体值由黄金用例调优；
限制单 change set 最大知识点数和最大来源对象数；
每个 impacted item 记录根因 point、关系路径和 hop；
到达边界或发现循环时停止，不重复处理已访问 point；
超过阈值将 impact_truncated=true，为相关业务域创建新 generation 影子重建，不发布不完整的局部结果。

impacted 只表示“需要重新验证或重建”，不表示依赖方的治理事实已经变化。对依赖方：

如果其 canonical 内容由该依赖确定性派生，重新读取依赖方来源并运行 point builder，再次计算实际 Diff；
如果只影响组合 chunk、检索别名、图路径或缓存，则保留 point revision，只重建对应派生产物；
禁止因为传播结果直接改写治理 Neo4j 或凭模型推断创建 canonical 事实。

首期传播规则至少覆盖：

字段定义/类型变化 → 引用字段的数据标准、DataFlow 输入输出说明；
数据标准规则变化 → 绑定该标准的元数据定义和检索别名；
血缘关系变化 → 对应 relation point、上下游 chunk 和图投影；
业务域归属变化 → 该对象全部 point 的 permission scope、缓存和 workspace 投影；
责任人变化 → owner point 和相关检索 chunk，不重建无关 definition/relation embedding。

7.5 增量构建、校验与原子发布

每个 change set 使用 prepare -> validate -> activate：

Prepare

为 added/modified point 写 building 版本；
为 deleted point 准备 tombstone；
对 impacted point 重新验证 canonical 来源，只在实际 Diff 后创建新 point revision；
只重建 point set、依赖集合或检索表现发生变化的 chunks；
按 embedding hash 复用未变化向量，只批量生成缺失向量；
准备新 canonical document、chunk、embedding 和依赖边；
写 LightRAG 投影任务，但不把 projection ready 作为 canonical 可见性的前置条件。

Validate

至少检查：

point key 唯一、source revision 单调、point set hash 可复现；
每个新 chunk 都能反查 active/building point 和 canonical source；
embedding profile、维度和覆盖率正确；
permission scope 来自服务端 canonical 来源；
删除/修改后不存在仍指向旧 point revision 的待发布引用；
影响传播未被静默截断；
change item 各阶段状态完整。

Activate

在单个 PostgreSQL 事务中：

将旧 active point/document/chunk 标记 superseded 或 deleted；
将新 point/document/chunk 标记 active；
更新 source active revision 和 point set hash；
创建/确认缓存失效任务和 LightRAG projection；
将 change set 标记 canonical_active 并提交；投影 worker 开始后转为 projecting，异步投影完成后转为 complete，超过重试或 SLA 时转为 degraded，但不回滚已正确发布的 canonical 版本。

Qwen、校验或事务失败时，旧 active 版本保持不变，building 产物可重试或清理。禁止逐 point 提交后再补偿，因为这会暴露半新半旧的对象快照。

7.6 删除、权限收紧与紧急撤销

删除对象：

在 canonical 事务中将对象及其 active points 发布为 tombstone，查询立即不可见；
删除相关缓存依赖；
projection 进入 deleting；
LightRAG 按 point ID 或投影包 ID 删除；
删除成功标记 deleted，失败有上限重试并告警；
每日 audit 对孤儿 projection 重试或隔离。

权限收紧、敏感级别提升和业务域移出使用相同的高优先级撤销通道：先在 canonical 授权层拒绝访问并失效缓存，再异步修正 embedding metadata 和 LightRAG workspace。紧急撤销 SLA 需要在 K1D 确认；在 SLA 未验证前不得声称外部投影已实现实时删除。

7.7 缓存失效与回答新鲜度

检索结果缓存和答案缓存都必须记录 point_key + point revision + generation 依赖。

point modified/deleted：失效直接依赖缓存；
影响传播：失效所有 impacted point 缓存；
permission change：按用户/角色/业务域安全范围失效；
generation 切换：失效旧 generation 缓存；
依赖写入失败：回退为整个业务域缓存失效；
高风险治理内容可以配置最大允许陈旧时间，超时后不返回旧缓存。

首期若尚未实现跨 worker 的依赖失效广播，则关闭可跨请求复用的答案缓存；允许的短期进程内缓存必须把 generation/point set hash 纳入键并使用保守 TTL。不能先上线不可精准失效的长生命周期缓存，再依赖人工清理保证新鲜度。

回答和引用响应增加：

point_key、point_revision；
source_updated_at；
index_generation；
freshness_status：fresh / updating / degraded；
可选 active_change_set_id，仅管理员可见。

fresh 表示引用 point set 已对应最新成功处理的 source revision；updating 表示存在更高 source revision 的未完成 change set，当前回答仍基于旧 active 快照；degraded 表示巡检发现 source/canonical/projection 不一致，或无法证明缓存依赖完整。

7.8 LightRAG 增量投影与 Generation 重建

LightRAG 的实际更新粒度由 K0 契约测试决定：

支持可靠 point/document delete：删除旧外部 ID，再插入新 active 内容；
只支持文档级删除：重建该对象投影包；
无法证明删除一致性：新建 workspace generation，影子构建、评测后整体切换；
embedding、抽取模型、抽取 Prompt、实体关系 Schema 变化：强制新 generation；
影响传播超过阈值或跨业务域大规模重分区：强制新 generation。

新 workspace 激活前必须验证 active point 覆盖率、孤儿来源数、删除残留、权限分区和黄金集结果。旧 workspace 保留到回滚窗口结束后再异步回收。

7.9 每日全量巡检

巡检比较：

Neo4j/PostgreSQL 源对象 UID、版本和 source snapshot hash；
canonical active document hash 和 point set hash；
每个 active point 的 source revision、content hash 和有效期；
chunk 到 point 的映射完整性；
active embedding profile 覆盖率和陈旧 embedding；
LightRAG projection generation、hash、状态和孤儿外部 ID；
deleted/superseded point 的残留 chunk、缓存和投影；
业务域授权与 point/document permission scope 的合法性；
长时间停留在 pending/building/validating 的 change set。

默认 report-only；只有显式 --repair 才修复派生数据差异，不删除源治理数据。 repair 必须创建独立 change set，保留修复前后审计记录。

8. LlamaIndex 主检索链路

8.1 代码边界

新增：

app/core/knowledge/
├── access.py
├── contracts.py
├── document_builder.py
├── point_builder.py
├── chunking.py
├── diff.py
├── impact.py
├── publish.py
├── cache_invalidation.py
├── sync.py
├── audit.py
├── qa.py
├── evaluation.py
├── llamaindex/
│   ├── node_mapper.py
│   ├── vector_store.py
│   └── synthesizer.py
├── retrieval/
│   ├── lexical.py
│   ├── vector.py
│   ├── governance_graph.py
│   ├── fusion.py
│   ├── rerank.py
│   ├── router.py
│   └── pipeline.py
└── lightrag/
    ├── client.py
    ├── projection.py
    └── health.py

8.2 KnowledgeAccessContext

每次查询在 API 层构建不可变上下文：

KnowledgeAccessContext(
    subject_id=...,
    roles=frozenset(...),
    permissions=frozenset(...),
    business_domain_uids=frozenset(...),
    correlation_id=...,
)

禁止 Retriever 自己从请求 JSON 接受任意业务域。客户端 filters 只能缩小服务端已计算范围，不能扩大范围。

8.3 Retriever

ExactLexicalRetriever

用于：

表名、字段名、对象编码；
中文名、英文名和别名；
前缀和轻微拼写差异。

DataOpsVectorRetriever

查询 active profile；
在 SQL 中应用 active document、业务域和对象类型过滤；
exact scan 和 HNSW 路径均可配置；
返回 canonical chunk ID、point_keys、point revisions 和 generation，不返回框架生成的临时 ID。

GovernanceGraphRetriever

只读查询现有 Neo4j：

上下游血缘；
业务域—DataFlow—元数据关系；
数据标准/标签关联；
限定最大 hop、最大节点和最大关系数量；
使用参数化 Cypher；
仅返回稳定 UID，不依赖 Neo4j internal ID。

LightRAGRetriever

只对允许 workspace 调用；
首期使用 mix 和 only_need_context；
强制超时、最大上下文和 circuit breaker；
把返回来源映射为当前 active canonical document/chunk/point；
映射失败的上下文丢弃并计数。

8.4 Query Router

首期使用可测试的确定性规则，不用 LLM 决定权限或任意路由。

模式	触发条件	Retriever
`exact`	编码、表名、字段名、显式引号	lexical + vector
`semantic`	定义、含义、用途、负责人	lexical + vector
`relationship`	上游、下游、依赖、关联、经过	vector + governance graph
`global`	整体、主要主题、跨域总结	vector + LightRAG
`auto`	服务端确定性分类	上述之一

用户可请求更窄模式，但不能强制访问未授权 LightRAG workspace。

8.5 融合和重排默认值

初始可调参数：

lexical top 20；
vector top 40；
governance graph top 20；
LightRAG context top 20；
RRF k=60；
RRF 后保留 30；
reranker 后保留 8；
每对象最多 3 个 chunk；
最终 evidence token 预算 8,000。

这些只是起始配置，必须由黄金问题集调优，不能写死为“最佳参数”。

8.6 无答案与引用

回答必须满足：

至少一个通过授权和版本核验的来源；
reranker/融合分数超过已校准阈值；
每个事实引用 object_uid + object_version + point_key + point_revision + chunk_id；
引用的 point、chunk 和 generation 在回答提交时仍为 active；
来源内容不足时明确返回“不足以回答”；
不允许模型生成不存在的引用。

9. LightRAG 侧车

9.1 部署

新增 Compose 服务：

lightrag
lightrag-projector
lightrag-neo4j

存储：

PostgreSQL：同一 PostgreSQL 集群内独立数据库 dataops_lightrag 和独立账号；
Neo4j：本地使用独立 Community 容器与卷；
不使用 DataOps public schema；
不使用治理 Neo4j 凭据；
服务不暴露宿主机公网端口，只有后端/worker 内部网络可访问。

镜像和 Python 包必须固定版本或 digest。不得使用 floating latest。

9.2 Workspace 与权限

workspace 使用稳定安全分区：

dataops-{tenant_or_global}-{business_domain_uid}-g{generation}

首期如果没有 tenant，固定使用 global，但仍按业务域分区。

由于官方 LightRAG Server 的 workspace 是实例级配置，实施顺序为：

PoC 只选择一个非敏感业务域；
验证共享服务是否能安全管理多个 workspace；
若不能按请求硬隔离，使用 DataOps LightRAG Gateway 管理 workspace 实例，或按安全分区部署服务实例；
在多业务域隔离验收前，禁止将混合权限语料放入一个正式 workspace。

9.3 模型配置

embedding 与 DataOps active Qwen profile 保持同模型、同维度；
extraction/query/final 模型分别配置；
LightRAG final generation 对 DataOps 请求禁用，只返回 context；
reranker 配置独立，失败可以由 DataOps 统一 reranker 补偿；
任何模型切换创建新 generation/workspace，全量重建后再切换。

9.4 接口适配

LightRAGClient 对上层暴露稳定接口：

insert(document_contract, idempotency_key) -> ProjectionReceipt
delete(external_document_id, idempotency_key) -> DeleteReceipt
query_context(query, workspace, mode, limits) -> list[ExternalEvidence]
status(external_document_id) -> ProjectionStatus
health() -> DependencyHealth

insert 输入必须包含 active point keys/revisions，delete 必须返回可核验的删除回执。如果官方接口无法证明旧内容已删除，client 将 projection 标记为 unverified，并触发新 generation 重建或人工隔离，不能把 HTTP 2xx 直接等同于语义删除完成。

官方 REST 路径变化只影响 client，不进入领域代码和前端。

10. Knowledge API

新增蓝图：

app/api/knowledge_base/

注册前缀：

/api/knowledge

10.1 用户接口

方法	路径	权限	用途
POST	`/search`	`governance:read`	只检索，不生成
POST	`/ask`	`governance:read`	检索并生成有引用答案
GET	`/sources/<uid>`	`governance:read` + domain	查看 active 来源
GET	`/sources/<uid>/versions/<version>`	同上	查看指定引用版本
GET	`/capabilities`	`governance:read`	模型与降级状态

注意：当前全局权限策略会把普通 POST 视为编辑操作。必须为 /search 和 /ask 增加显式 read-only 分类，不能要求 viewer 拥有 governance:edit。

10.2 管理接口

新增权限：

knowledge:manage

仅 admin 默认拥有。

方法	路径	用途
GET	`/admin/sync`	同步、投影、失败和 lag
POST	`/admin/reindex`	创建新 generation
POST	`/admin/retry-projection`	重试指定失败投影
POST	`/admin/audit`	启动 report/repair
GET	`/admin/change-sets`	查询知识点 Diff、影响范围和发布状态
GET	`/admin/change-sets/<id>`	查看 change items 和失败阶段
POST	`/admin/change-sets/<id>/retry`	从安全检查点重试失败变更
POST	`/admin/change-sets/<id>/rollback`	回退未完成或新激活的 change set
GET	`/admin/evaluations`	评测运行与门禁结果

10.3 响应契约

统一包含：

{
  "query_id": "uuid",
  "mode": "relationship",
  "answer": "...",
  "answer_status": "grounded",
  "degraded_components": [],
  "citations": [
    {
      "object_uid": "uuid",
      "object_type": "DataFlow",
      "object_name": "客户同步",
      "object_version": 7,
      "point_key": "DataFlow/019.../purpose",
      "point_revision": 7,
      "chunk_id": "uuid",
      "section_path": "relations/READS_FROM",
      "source_updated_at": "2026-07-22T02:10:00Z",
      "index_generation": 3,
      "retrievers": ["vector", "governance_graph"],
      "score": 0.91
    }
  ],
  "freshness_status": "fresh"
}

11. 前端

修改：

frontend/src/views/knowledgeBaseProduct/index.vue
新建 frontend/src/api/governanceKnowledge.js
新建 frontend/src/views/knowledgeBaseProduct/components/

首期页面：

搜索/提问输入；
auto / 精确 / 语义 / 关系 / 全局 模式；
对象类型和已授权业务域过滤；
答案与逐条引用；
点击引用回到治理对象；
降级、无答案和索引更新时间；
答案来源版本、更新时间和 freshness 状态；
管理员 change set、知识点 Diff、同步状态、失败重试和评测结果。

前端不得：

直接访问 LightRAG；
自行决定用户业务域；
隐藏后仍调用无权限来源接口；
渲染模型返回的任意 HTML；
显示内部 Prompt、模型密钥或原始堆栈。

12. 配置与依赖

12.1 Python 依赖

将知识库依赖与核心依赖分组并锁定：

llama-index-core
PostgreSQL/Neo4j 所需的最小 LlamaIndex integration
tokenizer
reranker client

不安装 llama-index 全量 starter，避免引入未使用 provider。

实施前做 Python 3.11、SQLAlchemy 2.0、NumPy 和现有 OpenAI SDK 的兼容性 spike。通过后将精确版本写入锁定文件；不得仅使用宽松 >=。

LightRAG 保持独立镜像，不安装进 Flask backend，避免依赖冲突和扩大镜像。

12.2 配置项

新增但不提供生产默认密钥：

KNOWLEDGE_ENABLED
KNOWLEDGE_ACTIVE_EMBEDDING_PROFILE
KNOWLEDGE_VECTOR_TOP_K
KNOWLEDGE_RRF_K
KNOWLEDGE_RERANK_TOP_K
KNOWLEDGE_EVIDENCE_TOKEN_BUDGET
KNOWLEDGE_IMPACT_MAX_HOPS
KNOWLEDGE_IMPACT_MAX_POINTS
KNOWLEDGE_IMPACT_MAX_OBJECTS
KNOWLEDGE_FULL_REBUILD_THRESHOLD
KNOWLEDGE_HIGH_RISK_MAX_STALENESS_SECONDS
KNOWLEDGE_CHANGESET_RETRY_LIMIT
KNOWLEDGE_LIGHTRAG_ENABLED
KNOWLEDGE_LIGHTRAG_SHADOW_ONLY
KNOWLEDGE_LIGHTRAG_BASE_URL
KNOWLEDGE_LIGHTRAG_API_KEY
KNOWLEDGE_LIGHTRAG_TIMEOUT_SECONDS
KNOWLEDGE_LIGHTRAG_CANARY_PERCENT
QWEN_EMBEDDING_BASE_URL
QWEN_EMBEDDING_API_KEY
QWEN_EMBEDDING_MODEL
QWEN_EMBEDDING_DIMENSION
RERANK_BASE_URL
RERANK_API_KEY
RERANK_MODEL

日志只能记录配置是否存在、模型名和配置哈希，不能记录密钥。

13. 可观测性与降级

指标

canonical index backlog、失败数、最老事件年龄；
change set pending/building/validating/failed 数、处理时延和最老年龄；
每次变更 added/modified/deleted/impacted point 数；
impact propagation hop、截断次数和 generation 重建升级次数；
embedding 复用率与因知识点变化实际重算的 chunk 数；
缓存精准失效数、业务域回退失效数和 stale cache 拒绝数；
LightRAG projection pending/failed/lag；
active 文档和 embedding 覆盖率；
各 Retriever latency、candidate count、empty rate；
reranker latency 和降级次数；
search/ask P50/P95/P99；
no-answer rate；
citation count 和 stale citation 拒绝数；
point/chunk/source 版本映射失败数和 freshness 状态分布；
LightRAG source mapping failure；
模型 token、费用和超时；
ACL 拒绝与跨域候选丢弃数。

降级矩阵

故障	行为
LightRAG 不可用	标准链路继续，标记 graph enhanced degraded
治理 Neo4j 不可用	lexical + vector
pgvector 不可用	lexical；ask 默认不生成或明确证据不足
reranker 不可用	RRF 结果，降低置信度
Qwen 不可用	停止新索引；旧 active index 可查
DeepSeek 不可用	search 可用；ask 返回来源和模型不可用状态
新 generation 构建失败	保留旧 active generation

14. 评测与发布门禁

14.1 黄金问题集

首期 150–300 条，包含：

30% 对象名、表名、字段、编码和别名；
25% 定义、用途、责任人和数据标准；
25% 上下游、依赖和两至三跳关系；
10% 跨对象/全局主题；
10% 无答案、旧版本、删除对象、Prompt Injection 和跨域越权。

每条至少标注：

允许的业务域；
相关 object UID/version；
相关 chunk 或关系；
预期答案要点；
是否必须拒答。

14.2 对照组

固定比较：

lexical only；
pgvector only；
LlamaIndex standard；
LlamaIndex + governance graph；
LlamaIndex + governance graph + LightRAG。

14.3 门禁指标

初始验收目标：

精确对象 Recall@5 ≥ 0.98；
语义问题 Recall@10 ≥ 0.90；
多跳 source Recall@10 ≥ 0.80；
Citation Precision ≥ 0.95；
权限负向用例泄漏 = 0；
deleted/superseded 来源进入答案 = 0；
无答案问题拒答准确率 ≥ 0.90；
search P95 ≤ 1.5 秒（不含外部模型生成）；
LightRAG 故障时标准检索可用率 = 100%。

LightRAG 正式放量还必须满足：

多跳 Recall@10 相对 LlamaIndex + governance graph 提升至少 10 个百分点；
精确问题 Recall@5 下降不超过 2 个百分点；
P95、token 和索引成本在批准预算内；
workspace 隔离和 canonical source re-authorization 全部通过。

14.4 动态更新专项评测

黄金集必须增加“变更前问题 + 变更操作 + 变更后预期”的时序用例，至少覆盖：

修改字段定义，只更新对应 definition point 和确定性依赖；
修改责任人，不重算无关 relation/definition embedding；
新增/删除血缘边，二至三跳问题引用新关系且不再返回旧关系；
数据标准变化，绑定对象和缓存按依赖传播更新；
删除治理对象，canonical 立即不可见且 LightRAG 残留可检测；
权限收紧，旧缓存和外部投影不能造成跨域泄漏；
重复、乱序和并发事件最终收敛到最高合法 source revision；
Qwen、LightRAG、缓存 worker 或数据库事务失败时旧 active 版本持续可用；
影响范围超过阈值时升级为 generation 重建，不发布截断的局部结果；
新 generation 失败或效果退化时能够回滚。

新增门禁指标：

知识点 Diff 准确率 = 1.00（黄金 fixture）；
删除/权限收紧后 canonical 不可见延迟满足批准的安全 SLA；
unchanged point 的 embedding 重算率 = 0；
change set 部分发布导致的混合版本命中 = 0；
stale point/chunk/citation 进入答案 = 0；
change set 最终收敛率 ≥ 0.999，失败项全部可观测、可重试或可回滚；
依赖传播漏更新 = 0（已声明规则的黄金用例）；
LightRAG 删除残留必须被巡检发现，不能静默通过发布门禁。

15. 分阶段交付

flowchart LR
    K0["K0\n兼容性与评测基线"] --> K1A["K1A\n事件与授权"]
    K1A --> K1B["K1B\n知识点与版本"]
    K1B --> K1C["K1C\nDiff 与影响传播"]
    K1C --> K1D["K1D\n原子发布与新鲜度"]
    K1D --> K2["K2\nLlamaIndex 标准检索"]
    K2 --> K3["K3\nLightRAG 影子侧车"]
    K3 --> K4["K4\n融合问答与引用"]
    K4 --> K5["K5\n前端与运维"]
    K5 --> K6["K6\n评测、Canary 与发布"]

K0：兼容性与评测基线

实施：

建立 30–50 条小型黄金集；
验证 LlamaIndex 最小依赖与 Python 3.11；
验证自定义 VectorStore/Retriever 可读取现有表；
验证 LightRAG REST、PostgreSQL 16.6+、Neo4j 和 1024 维 embedding；
验证 insert/query/delete、context source mapping 和 workspace 隔离；
验证 LightRAG 的真实最小删除粒度、删除回执、重复插入语义和孤儿内容发现方式；
用两个版本的 DataFlow fixture 验证 point/document external ID 更新策略。

退出门槛：

不需要第二套业务源表；
LightRAG context 能映射回 DataOps stable source；
已明确 LightRAG 使用 point 级更新、对象投影包重建或 generation 重建中的哪一种；
依赖锁可重复安装；
无密钥进入镜像、日志或测试 fixture。

回滚：

删除 PoC 容器和测试数据库；
不改变当前生产路径。

K1A：对象级事件、授权与快照边界

主要文件：

V100 migration；
app/core/knowledge/access.py
document_builder.py
sync.py
governance 写路径 Outbox 事件。

测试：

schema/migration；
每类对象 golden document；
secret redaction；
user-domain grants；
source revision 单调性；
duplicate/out-of-order/restart；
权限扩大与权限收紧事件。

退出门槛：

业务域为空时 fail closed；
每类首期治理对象均有同步事件和稳定 source revision；
事件能重新读取完整、一致的 canonical source snapshot；
changed-field hint 不会代替实际快照比较；
权限收紧事件进入高优先级处理队列。

K1B：知识点模型、稳定键与版本

主要文件：

V100 中 knowledge_points、knowledge_point_dependencies、 knowledge_change_sets、knowledge_change_items、knowledge_cache_dependencies；
app/core/knowledge/point_builder.py
app/core/knowledge/contracts.py
app/core/knowledge/chunking.py

实施：

先支持 BusinessDomain 和 DataFlow 的 point builders；
为 DataMeta 字段、标准规则、标签和关系确认稳定子对象 UID；
定义 point → chunk 和 point → dependency 的确定性映射；
生成 point set hash、chunk point set hash 和 permission hash；
旧文档回填为初始 point generation，但不凭文本相似度猜测稳定 ID。

测试：

stable point_key golden fixtures；
字段/关系重排不改变 point identity；
名称变化只修改预期 point；
point/document/chunk hash 可重复；
同一 point 最多一个 active 版本；
模型抽取关系不能写入 canonical dependency source。

退出门槛：

五类首期治理对象均能产生稳定、可复现 point set；
每个 chunk 能反查来源 point 和版本；
权限和版本不由 LLM 决定；
初始回填有审计报告和可回滚 generation。

K1C：语义 Diff 与有界影响传播

主要文件：

app/core/knowledge/diff.py
app/core/knowledge/impact.py
app/core/knowledge/sync.py

实施：

按 point_key 计算 added/modified/deleted/unchanged；
记录 change set 和逐 point change items；
实现关系白名单、最大 hop、最大 point/object 数和循环检测；
超阈值自动升级为业务域 generation 重建；
只为 changed/impacted point 生成待构建 chunk 集合。

测试：

新增、修改、删除和无语义格式变化；
字段、标准、血缘、责任人和业务域变更；
多级依赖、环、孤儿依赖和超阈值传播；
duplicate/out-of-order/concurrent events；
传播路径和根因审计可复现。

退出门槛：

黄金 fixture 的知识点 Diff 准确率为 1.00；
已声明传播规则不存在漏更新；
unchanged point 不进入 embedding 队列；
影响被截断时不允许局部 change set 进入 canonical_active。

K1D：增量构建、原子发布、缓存失效与审计

主要文件：

app/core/knowledge/publish.py
app/core/knowledge/cache_invalidation.py
app/core/knowledge/audit.py
Qwen embedding batch/reuse；
projection 与 cache invalidation worker。

实施：

prepare/validate/activate 状态机；
unchanged embedding 复用和 changed chunk 批量生成；
point/document/chunk 的事务级 active 切换；
point dependency 精准缓存失效及业务域回退失效；
删除/权限收紧的紧急撤销路径；
LightRAG 增量投影能力探测与 generation 重建策略；
report-only audit、显式 repair 和 rollback。

测试：

Qwen/事务/cache/LightRAG 任一步失败；
部分构建不可见和旧 active 持续可用；
delete/permission 紧急撤销 SLA；
stale cache、stale citation 和孤儿 projection；
retry/restart/rollback；
generation 切换和回退。

退出门槛：

不存在半新半旧的可查询对象快照；
Qwen 失败不覆盖旧 active；
删除和权限收紧满足批准的 canonical 不可见 SLA；
unchanged point embedding 重算率为 0；
change set 可从任何失败阶段安全重试或回滚；
每日 audit 能发现 source/canonical/cache/LightRAG 差异。

K2：LlamaIndex 标准检索

主要文件：

llamaindex/node_mapper.py
llamaindex/vector_store.py
lexical/vector/governance graph/fusion/router/pipeline；
/api/knowledge/search。

测试：

metadata filter；
active version；
active point revision 和 generation 过滤；
exact/vector/graph/RRF；
Neo4j 和 pgvector 故障降级；
viewer 的 POST search 仍按 read 权限；
负向跨域检索。

退出门槛：

不使用 LlamaIndex 默认持久化表；
返回稳定 UID/version/chunk；
返回稳定 point key/revision 和 freshness metadata；
标准链路达到 Recall 和延迟基线；
search 不依赖 DeepSeek。

K3：LightRAG 影子侧车

主要文件：

Compose LightRAG 服务与独立存储；
lightrag/client.py
lightrag/projection.py
projector command/service；
projection admin 状态。

测试：

insert/update/delete 幂等；
point/object 投影包更新与删除残留检测；
workspace 隔离；
mapping failure 丢弃；
LightRAG timeout/circuit breaker；
generation 重建；
change set 到 projection 的状态关联；
每日 audit 修复孤儿。

退出门槛：

默认 shadow_only=true；
不影响正式答案；
现有治理 Neo4j 没有 LightRAG 标签、索引或关系；
多跳评测数据完整；
canonical change set 发布不依赖 LightRAG ready，且旧投影上下文无法通过来源复核。

K4：融合问答与引用

主要文件：

LightRAGRetriever；
rerank；
qa/synthesizer；
/api/knowledge/ask；
source/version API。

测试：

context-only；
canonical re-authorization；
Prompt Injection；
stale/deleted citations；
point modified/impacted 后 stale citation 拒绝；
no-answer；
model timeout；
citation fabrication rejection。

退出门槛：

最终答案只由 DataOps 生成；
每个引用能打开合法源对象；
每个引用能定位 active point revision 和 generation；
模型不可用时不伪造答案；
权限负向用例零泄漏。

K5：前端与运维

实施：

搜索、问答、模式和过滤；
引用与回跳；
降级提示；
管理员同步/重试/评测；
管理员 change set、Diff、影响范围和 freshness 状态；
system health 增加 knowledge 组件。

退出门槛：

viewer/editor/admin 页面与 API 权限一致；
前端不直连 LightRAG；
无内部错误、密钥和 Prompt 暴露；
浏览器验收通过。

K6：评测、Canary 与发布

实施：

扩展到 150–300 条黄金集；
保存各对照组结果；
LightRAG 先按业务域和百分比 Canary；
观察 no-answer、投诉、延迟、成本和引用反馈；
达标后逐步关闭 shadow-only。

退出门槛：

全部质量和安全门禁通过；
LightRAG 有明确收益；
关闭 LightRAG 的回滚演练通过；
新旧 generation 切换和回退通过；
动态更新专项门禁、紧急撤销 SLA 和缓存失效门禁通过；
形成 docs/validation/knowledge-k6.md。

16. 测试布局

新增建议：

tests/knowledge/
├── test_access_context.py
├── test_document_builder.py
├── test_point_builder.py
├── test_chunking.py
├── test_knowledge_diff.py
├── test_impact_propagation.py
├── test_atomic_publish.py
├── test_cache_invalidation.py
├── test_sync.py
├── test_audit.py
├── test_lexical_retriever.py
├── test_vector_retriever.py
├── test_governance_graph_retriever.py
├── test_fusion.py
├── test_router.py
├── test_reranker.py
├── test_lightrag_client.py
├── test_lightrag_projection.py
├── test_qa.py
└── test_evaluation.py

tests/integration/
├── test_knowledge_pgvector.py
├── test_knowledge_neo4j.py
├── test_lightrag_contract.py
├── test_knowledge_outbox_projection.py
├── test_knowledge_dynamic_update.py
├── test_knowledge_generation_switch.py
├── test_knowledge_emergency_revoke.py
└── test_knowledge_degraded_modes.py

tests/e2e/
└── governance-knowledge.spec.js

验证分层：

L1：纯单元和 golden fixtures；
L2：迁移、权限、API 和适配器契约；
L3：PostgreSQL + Neo4j + backend；
L4：增加 LightRAG 与模型 mock；
L5：有显式密钥时运行真实模型评测，不作为普通 CI 前置。

17. 风险与控制

风险	控制
LlamaIndex 依赖膨胀/冲突	只装 core + 最小 integrations，精确锁版本
LightRAG 升级破坏 API	client 适配层 + 契约测试 + 固定 digest
LightRAG 图污染治理图	独立 Neo4j 凭据、服务、卷/数据库
多业务域泄漏	workspace 分区 + 查询前授权 + 来源重新授权
ANN 过滤降低召回	exact baseline、iterative scan/oversampling 和分域评测
embedding 模型切换	profile + shadow generation + 原子切换
`point_key` 不稳定导致伪变化	稳定子对象 UID、golden fixtures、禁止名称/下标/hash 入键
依赖传播爆炸或形成环	关系白名单、visited set、hop/point/object 上限、升级 generation 重建
依赖规则漏更新	时序黄金集、change path 审计、每日 source/point/chunk 巡检
事件重复、乱序或并发	source revision 单调、幂等 change set、同源对象串行激活
增量发布暴露混合版本	prepare/validate/activate，事务级切换全部 point/document/chunk
缓存保留旧知识或旧权限	point dependency、权限范围失效、缺依赖时整域失效
LightRAG 删除残留	tombstone、projection 状态、每日 audit
LightRAG 不支持可靠局部删除	对象投影包重建或新 workspace generation 影子切换
LLM 抽取产生错误关系	LightRAG 图只作召回投影，最终证据回到 canonical source
Prompt Injection	evidence 隔离、系统指令、来源复核、负向测试
查询内容进入日志	默认只存 query hash 和来源 UID
模型/侧车不可用	标准链路和 retrieval-only 降级
Outbox 被误当多消费者	单 KnowledgeIndexHandler + projection queue

18. 完成定义

只有同时满足以下条件才算知识库落地完成：

五类治理对象都能生成稳定、可复现的知识点集合和依赖关系；
新增、修改、删除和权限变化都形成可审计 change set，并正确区分 added/modified/deleted/unchanged/impacted；
已声明依赖规则能够有界传播，超过阈值时自动升级为 generation 重建而不是发布不完整结果；
unchanged point 不重复生成 embedding，changed/impacted point 只重建必要产物；
point/document/chunk/embedding 使用 prepare/validate/activate 原子切换，失败时旧 active 版本持续可用；
删除和权限收紧在批准 SLA 内使 canonical 内容不可见，缓存和 LightRAG 残留可检测、可清理；
五类治理对象均可增量同步、删除、每日校验和安全回滚；
新旧索引 generation 可影子构建、原子切换和回退；
viewer/editor/admin 与业务域授权均由服务端执行；
search、ask、source、change set 和 admin API 契约稳定；
精确、语义、治理图、LightRAG、Diff、影响传播和缓存失效路径可观测；
LightRAG 下线不影响标准检索，且旧投影上下文不能绕过 canonical 复核；
所有回答有合法 UID/version/point revision/generation 引用，或明确拒答；
权限、Prompt Injection、stale/deleted、动态更新和模型失败测试通过；
静态黄金集、时序变更黄金集、质量指标和性能门禁全部通过；
前端、后端、迁移、worker、相关容器和浏览器验收留下验证记录。

19. 推荐的首个实现切片

实施开始时不要先部署完整 LightRAG。首个切片固定为：

V100 业务域授权、知识点/change set 表和 embedding profile；
DataFlow/BusinessDomain 两类规范化文档与稳定 point builders；
用“修改 purpose、修改 owner、增删 READS_FROM、权限收紧、删除对象”验证 Diff、影响传播、原子切换和缓存失效；
lexical + pgvector 的 LlamaIndex /search，引用返回 point revision 和 generation；
30–50 条静态黄金集 + 10–20 条时序变更黄金集；
单业务域 LightRAG shadow PoC，实测删除粒度和残留检测；
达到动态更新、来源映射和权限门槛后再进入 K3。

这样可以先证明 DataOps 自身的知识身份、变化传播、发布一致性和检索基础正确，再判断 LightRAG 的真实增益，避免把知识点错配、陈旧缓存、基础分块、授权或引用问题误判为图算法问题。

2026-07-20-llamaindex-lightrag-knowledge-base.md 58 KB تاريخچه خام

LlamaIndex + LightRAG 数据治理知识库实施计划

1. 交付结论

2. 当前基线与必须补齐的缺口

已存在

缺口

3. 实施原则

4. 运行时架构

5. 数据模型

5.1 新迁移

5.2 用户—业务域授权

5.3 知识点、版本与有效期

5.4 知识点依赖、Change Set 与缓存依赖

5.5 规范化分块

5.6 Embedding profile 与 generation

5.7 外部引擎投影

5.8 查询审计与评测

6. 规范化文档协议

7. 同步与一致性

7.1 事件类型

7.2 单消费者协调

7.3 语义快照与知识点 Diff

7.4 有界依赖影响传播

7.5 增量构建、校验与原子发布

Prepare

Validate

Activate

7.6 删除、权限收紧与紧急撤销

7.7 缓存失效与回答新鲜度

7.8 LightRAG 增量投影与 Generation 重建

7.9 每日全量巡检

8. LlamaIndex 主检索链路

8.1 代码边界

8.2 KnowledgeAccessContext

8.3 Retriever

ExactLexicalRetriever

DataOpsVectorRetriever

GovernanceGraphRetriever

LightRAGRetriever

8.4 Query Router

8.5 融合和重排默认值

8.6 无答案与引用

9. LightRAG 侧车

9.1 部署

9.2 Workspace 与权限

9.3 模型配置

9.4 接口适配

10. Knowledge API

10.1 用户接口

10.2 管理接口

10.3 响应契约

11. 前端

12. 配置与依赖

12.1 Python 依赖

12.2 配置项

13. 可观测性与降级

指标

降级矩阵

14. 评测与发布门禁

14.1 黄金问题集

14.2 对照组

14.3 门禁指标

14.4 动态更新专项评测

15. 分阶段交付

K0：兼容性与评测基线

K1A：对象级事件、授权与快照边界

K1B：知识点模型、稳定键与版本

K1C：语义 Diff 与有界影响传播

K1D：增量构建、原子发布、缓存失效与审计

K2：LlamaIndex 标准检索

K3：LightRAG 影子侧车

K4：融合问答与引用

K5：前端与运维

K6：评测、Canary 与发布

16. 测试布局

17. 风险与控制

18. 完成定义

19. 推荐的首个实现切片

2026-07-20-llamaindex-lightrag-knowledge-base.md 58 KB

تاريخچه خام