lili 9ad619fcd6 docs(ai): AI 生成链↔knowledge RAGFlow 检索串联评审版(专题-03 核心)

2 路调研(反假绿 file:line)裁定 AI 检索消费链路:
- 缺口=中间层非基建:两端齐备(executionPrompt 明文"Source text not included this phase";
  knowledge retrieveChunks 已被真实 RAGFlow IT 验收 chunksCount>0、但 0 对外暴露、生产调用方 0),
  缺 knowledge-api 检索端口 + AI 侧 Context Assembly 层
- 外部全在线可真验(RAGFlow status:ok + New-API MiniMax-M2.5 实证)
- 专题-03 §4 四层上下文 + §5.3 检索结果合同 + §4.3 按用途授权过滤为硬约束(fail-closed)
- 建议分 3 期:P-A 最小检索串联真验 → P-B 授权过滤 fail-closed → P-C 质量门控快照

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-23 01:22:44 -07:00

9.9 KiB

Raw Blame History

AI 生成链 ↔ knowledge RAGFlow 检索串联 — 架构评审版

版本:v0.1 · 日期:2026-06-23 · 目标读者:架构/产品拍板人 + 实现 agent · 类型:评审版(结论 + 拍板点 + blast radius + 验收,不预写代码) 前置:handoff 三 owner token 红线已交付;market 资产物化评审=暂缓(伪缺口)。本主线是用户在"AI 检索消费链路(物化前置)"方向下确认的真实主线。

〇、本版定位与结论先行

这是专题-03「AI 编排上下文」的核心落地:让作品 AI 生成真正用上绑定的知识库内容(检索增强生成 RAG)。 两路反假绿调研(file:line 实证)结论一致:

缺口是「中间层」不是「基建」——两端能力齐备,缺一个 knowledge-api 检索端口 + AI 侧上下文组装层。 AI 生成链当前 executionPrompt 明文 "Source text is not included in this phase"(零正文零检索);knowledge 域已有完整 RAGFlow 检索 client(retrieveChunks,且已被真实 RAGFlow IT 验收 chunksCount>0),但从未对外暴露、生产调用方=0;外部依赖(RAGFlow status:ok + New-API 真生成 MiniMax-M2.5)全在线、可反假绿真验。

可做、可真验、是高价值创作命脉(把"绑了知识库"变成"AI 真的参考知识库写作")。因体量大 + 涉及授权/质量门控硬合同,建议分 3 期(详见 §五 Q1),先打通最小检索串联真验,再叠授权过滤 fail-closed、质量门控快照。

一、现状(两端基建 + 断裂点,file:line)

AI 生成链:零检索(确证)

CreateAiTaskReqVO:intent/workId/blockId/agentSlotKey,故意无 kbId(行34 注释"只表达用户想做什么,不承载已授权上下文事实"→ 服务端按 workId 自推、防前端绕授权)。
主链 MuseAiTaskServiceImpl.createAiTask:98-141:buildSourceSnapshot(纯 ID/revision 脱敏)→ issuePermissionEnvelope → 入队 → 异步 MuseAiRuntimeJobExecutor。
MuseAiRuntimeJobExecutor.executionPrompt:156-180(load-bearing):prompt = metadata + userInstruction,行171-174 明写 "Source text is not included in this phase; use metadata only"。零正文、零 kb 检索。
读 agent slot binding,不读 Knowledge Source Binding。

knowledge 检索:能力齐、0 暴露(确证)

RagFlowKnowledgeRuntimeClient.retrieveChunks(入参 RetrieveChunksCommand:kbId/ragflowDatasetIds/question/topK/threshold/metadataFilter)→ POST /api/v1/retrieval;HttpRagFlowKnowledgeRuntimeClient 真实实现 + RagFlowKnowledgeRedactor 脱敏。
kb→dataset 映射:muse_knowledge_ragflow_binding(kb_id+ragflow_dataset_id,懒创建于首次文档上传,dataset 名 kb-{kbId}-v{ver});作品链路 work_id→muse_knowledge_binding→kb_id→muse_knowledge_ragflow_binding(active)→ragflow_dataset_id,无现成 work→datasetId 聚合查询。
检索 0 对外暴露:knowledge-api 仅 package-info+ErrorCodeConstants;retrieveChunks/listChunks/runGraphRag 生产调用方=0(仅测试);AI 模块与 knowledge 零依赖;AI 自带 service/knowledge 是 yudao 遗留 pgvector RAG,与 muse RAGFlow 两套不通。

端口范式现成(确证)

ContentMuseWorkOwnerApi(content-api 定义、ai-server adapter 消费)= knowledge→ai 应复制的接缝。BC 规则:.agents/rules/bc-boundaries.md §一"本域定义端口、他域提供适配器";ArchUnit BcBoundaryArchTest(禁跨域 .dal/.application)+ AiGrantRuntimeBoundaryArchTest(runtime 侧只消费 envelope、不自授权)会卡死任何捷径。

外部依赖在线(2026-06-23 curl 实证)

RAGFlow 100.64.0.8:9380 status:ok+storage:ok;New-API :3000 真返 MiniMax-M2.5 completion;凭据 scripts/dev/p1r-external-acceptance.env。
已被真实 RAGFlow 验收的操作:health/createDataset/upload/startParse/pollStatus/listChunks/retrieveChunks(chunksCount>0);GraphRAG 仅 attribution 就绪时(默认 fail-closed)。

二、SSOT 合同(专题-03,硬约束不可省)

§4 四层上下文:L0 当前输入 / L1 近邻正文 / L2 作品事实(只读 Canonical)/ L3 授权资料(用户·全局·已安装 kb + 市场资产摘要,必须绑 Authorization Snapshot + 来源状态);token 预算 L1>L2>L3,超限省略入 omittedSources(枚举 token_budget/not_authorized/stale_source/...)。
§2.1 检索位置:权限预检 → Permission Envelope → 上下文组装(检索在此填 L3) → 子智能体运行。
§5.3 检索结果合同:每条 chunk 须含 sourceOwner/sourceObject+version/evidence/confidence/authorizationSnapshot/sourceStatus/allowedPurpose;缺任一不得进 Prompt。
§4.3 按用途授权:"阅读"授权 ≠ "上下文检索"授权;状态∈{revoked,delisted,recalled,blocked,owner_missing,unauthorized}一律拒。
§8 质量门控:输入须绑 Context Assembly Snapshot(检索快照可追溯)。
双轨佐证 架构-02:102/290:Knowledge Source Binding"只授予检索/生成来源可用性,不写作品事实"(=绑定即检索授权,但不物化、不写 Canonical)。

三、设计骨架(最小落点,实现期对齐真实契约)

flowchart LR
  A[AI 生成链<br/>MuseAiRuntimeJobExecutor] -->|workId+query+envelope| B[Context Assembly<br/>新建·ai-server runtime]
  B -->|KnowledgeRetrievalApi| C[knowledge-api 检索端口<br/>新建]
  C --> D[MuseKnowledgeRetrievalService<br/>新建·权限边界]
  D -->|work→binding→kb→dataset| E[muse_knowledge_binding<br/>+ ragflow_binding]
  D -->|retrieveChunks| F[(RAGFlow<br/>已就绪)]
  D -->|§5.3 合同 + 脱敏| B
  B -->|L3 填充 + omittedSources| G[executionPrompt → New-API]

五件待建(agent 调研按必要性排序):

结构化 Chunk 模型(knowledge-api):RuntimeResult 当前无强类型 chunk(正文/score/归因仅在未脱敏 summary map),须按 §5.3 合同建 KnowledgeChunk DTO。
knowledge-api 检索端口 KnowledgeRetrievalApi(入参 workId/query/topK + envelope 授权域,出参 chunk 列表)。
应用层 MuseKnowledgeRetrievalService(权限边界:解析 work→binding→kb→active dataset + 来源状态校验 + 调 retrieveChunks + §5.3 归一 + 脱敏)。
AI 侧 Context Assembly 组件 + 检索 adapter(ai-server 加 knowledge-api 依赖,executionPrompt 前填 L3,用 RuntimePermissionEnvelope.allowedContextScopes 授权门)。
(可选/后置)GraphRAG attribution 开启 + 图检索串联。

四、blast radius

knowledge:新增 -api 端口 + DTO + 1 应用 service(复用现成 retrieveChunks/binding 投影);不改现有摄入链。
ai:新增 Context Assembly 组件 + adapter + pom 加 knowledge-api;改 executionPrompt(填 L3)+ 产 Context Assembly Snapshot。
DB:可能加 muse_ai_context_assembly_snapshot(质量门控追溯,P-C 期)或 work→dataset 聚合无需新表(两表 join)。
ArchUnit:新增跨模块走 knowledge-api(合规),BcBoundary/AiGrantRuntime 须保持绿。
不碰:handoff/market/content 已交付链路;前端(本主线后端为主,前端仅"生成时显示引用来源"可选增强)。

五、拍板点(请你定)

#	拍板点	选项	评审建议
Q1	范围/分期	一次全做 / 分 3 期	分 3 期:P-A 最小检索串联(work→binding→kb→dataset→retrieveChunks→填 L3→New-API 真生成,happy-path 真验)→ P-B 授权过滤 fail-closed(§4.3/§5.3 全合同 + omittedSources)→ P-C 质量门控快照(§8 Context Assembly Snapshot)
Q2	检索类型	仅 retrieveChunks / +GraphRAG	先 retrieveChunks(向量检索,已验收);GraphRAG 默认 attribution fail-closed,列 P-C 之后
Q3	P-A 授权口径	完全裸跑 / 最小授权门 / 一步到位全合同	最小授权门:P-A 即校验 binding active + 来源状态非阻断(绑定即检索授权,架构-02:102),§4.3 按用途/§5.3 全字段合同放 P-B。不允许完全裸跑(违 fail-closed 底线)
Q4	e2e 真验前置	复用 IT 摄入前置 / 预置 dataset	复用 IT 摄入前置:e2e global-setup 摄入种子 kb→createDataset→parse 到 searchable→真 retrieveChunks + 真 New-API 生成(muse_slice_live 无现成 kb+dataset 种子,须先摄入)

六、验收(P-A 最小检索串联)

真后端 e2e(48080 + 真 PG + 真 RAGFlow + 真 New-API):种子 kb 摄入 searchable → 作品绑定该 kb → AI 生成任务 → 断言生成 prompt/结果含检索 chunk 证据(反假绿:chunk 真来自 RAGFlow retrieveChunks、非 mock)。
单测:检索 service 权限边界(无 binding 拒/来源阻断拒)+ Context Assembly 填 L3 + envelope 授权门。
ArchUnit:BcBoundary(AI 只走 knowledge-api)+ AiGrantRuntime(只消费 envelope)保持绿。
无回归:现有 e2e 52/53 + 知识摄入链。

七、风险/失败路径

R1 授权绕过:前端传 kbId 绕过授权 → 已被 CreateAiTaskReqVO 无 kbId 设计挡住(服务端按 workId 自推),实现须坚持。
R2 假绿:用 mock chunk 冒充真检索 → 验收强制真 RAGFlow retrieveChunks(已有 IT 范式)。
R3 检索结果合同不全:RuntimeResult 无强类型 chunk → P-A 即建 KnowledgeChunk DTO,缺 source/version/evidence/confidence/authorizationSnapshot/sourceStatus 的不进 prompt。
R4 token 失控:L3 检索内容撑爆 prompt → 按 §4 token 预算 + omittedSources(P-B)。

八、开放项(实现前确认)

O1:work→kb→active dataset 的聚合查询不存在,P-A 需新建(两表 join);确认 binding active 语义 + 一作品多 kb 时检索合并策略。
O2:Permission Envelope 的 allowedContextScopes 当前签发内容(是否已含 kb 范围)——P-A 授权门依赖它,须确认 issuePermissionEnvelope 现状。
O3:Context Assembly Snapshot 落表(P-C)vs 仅内存——质量门控 §8 要求可追溯,倾向落表。

下一步:请定 Q1 分期(尤其是否认同"P-A 先最小检索串联真验")+ Q3 授权口径。确认后按 P-A 出执行版(端口契约 + Context Assembly + e2e 摄入前置),走后端→串联→真验→回写。

9.9 KiB Raw Blame History