目标#

• 双入库管线，按「格式 + 内容形态」路由：Knowhere（语义骨架：类型化 chunk、doc_nav 章节树、知识图谱边）处理文本类文档；PixelRAG（视觉切片，2048 维）处理扫描件/图片文档。见 eagle_rag/ingest/router.py。
• 多模态融合，通过 eagle_visual 上的四个锚点字段（chunk_type、parent_section、content_summary、source_chunk_id）锚定到 Knowhere 语义树，支持父文档召回（先 type="section_summary"，再按 path 前缀下钻）。
• 双层多租户：plugin_namespace（Milvus Database + PG 仓储过滤）把一次部署绑定到单一领域；kb_name 在该领域内对标量检索做知识库过滤。
• 路由查询引擎（auto / text / visual / hybrid），由 FallbackChain 选择器链 + 插件可扩展的 collection 计划构成，随后做逐计划重排、RRF 融合、跨 collection 去重与最终重排。
• 插件微内核：Core 与领域插件共用同一套 Hook/MCP 扩展路径；热路径 Hook（PARSE / CHUNK / QUERY_ASSEMBLE）只做增强、绝不重新切块。
• 可靠性：Celery 三队列（router / knowhere / pixelrag）+ with_retry + 死信；解析器 fail-closed（无 mock 兜底）。
• 统一对外接口：REST + SSE 流式（/query/stream、/search/stream）与 FastMCP 工具（core_ingest、core_query、core_retrieve_text、core_retrieve_visual）。

非目标#

• 不做 Agent 工作流，不做副作用型 MCP 工具（ADR-008 红线）。规划、工具循环与决策属于下游 Agent 宿主。
• 不做运行时领域切换——每个实例一个 default_namespace（ADR-002）。多行业 = 多套部署（EAGLE_RAG_PROFILE），而非运行时切换。
• 不做格式转换/Office 渲染——已移除 LibreOffice 与 pixelrag-serve；Excel 直接走 Knowhere。
• 无 FAISS、无 OpenAI / Cohere / 其他供应商——视觉存储由 Milvus HNSW/DiskANN 承载；模型仅 DeepSeek + Qwen。
• 不是向量数据库、工作流引擎或通用 Web 服务——产品是只读为主的 RAG 数据层。
• 不做跨存储强一致——入库是异步任务管线，带审计轨迹；MinIO / Milvus / PG 之间接受最终一致。

3.1 技术选型与取舍#

3.2 模块划分（核心）#

3.3 业务流：入库#

1
POST /ingest (file | bytes | object_key | URL)
2
  └─ runner.ingest()
3
       ├─ 生成 job/document id
4
       ├─ 按 (sha256, kb_name, plugin_namespace) 去重
5
       ├─ 上传 MinIO（kb_name 前缀隔离）
6
       ├─ 创建审计 + 注册文档
7
       └─ app.send_task(ingest_router)            # router_queue
8
            └─ ingest.router.ingest_router
9
                 └─ FallbackChain 路由               # 格式 + 内容形态
10
                      前缀 knowhere:/pixelrag:
11
                      → settings.router.mode (text/visual/hybrid)
12
                      → http(s) URI → PixelRAG
13
                      → PDF 形态探测 (pypdf/pdfplumber)
14
                      → 扩展名 → content_type
15
                 ├─ knowhere → knowhere_parse     # knowhere_queue
16
                 │    └─ 解析（api SDK :5005 | parser SDK 进程内）
17
                 │       ├─ 文本节点 + section_summary 节点
18
                 │       ├─ doc_nav 章节树
19
                 │       ├─ 关键词目录（document_keywords）
20
                 │       └─ 视觉分发 → knowhere_visual_chunks / pixelrag_build
21
                 └─ pixelrag → pixelrag_build      # pixelrag_queue（并发 1）
22
                      └─ 渲染切片 → Qwen3-VL 2048 维 → upsert eagle_visual

文本管线用 Qwen text-embedding-v4（1536 维）写入 eagle_text；视觉切片带四个融合锚点字段落入 eagle_visual。热路径 PARSE / CHUNK Hook 只增强节点，必须保留 Knowhere 的 doc_nav / path / 类型化 chunk（ADR-005）。

3.4 业务流：查询#

1
POST /query | /search | /query/stream | /search/stream
2
  └─ EagleRouterQueryEngine
3
       ├─ 解析附件（惰性解析；不写 Milvus）
4
       ├─ route_query: FallbackChain
5
       │    ForcedModeSelector → AttachmentSelector → LLMIntentSelector → HeuristicSelector
6
       ├─ _plan_query_route: CLASSIFY_QUERY Hook → QueryRouteDecision（collection 计划）
7
       │    + scope 感知并集（scope_filter: kb_names ∪ document_ids ∪ tags）
8
       ├─ RetrieverOrchestrator.retrieve
9
       │    每个计划：ANN（Qwen 文本 | Qwen3-VL 视觉 | 插件编码器）
10
       │    → 计划内重排 → supplement Hook
11
       │    → merge_rrf → dedupe_cross_collection → RRF_POST_MERGE → 最终重排
12
       ├─ 两阶段父文档召回：section_summary → path 前缀下钻
13
       └─ 生成（EagleMultimodalQueryEngine）
14
            文本答案走 DeepSeek；图像推理走 Qwen-VL-Max
15
            SSE 事件：session → step(route/recall/rerank) → sources → token* → done

代码中的关键保证：空召回列表不参与 RRF 产生虚排位（merge_rrf）；跨 collection 重复按 source_chunk_id / (document_id, path) 折叠（dedupe_cross_collection）；单个 collection 计划失败时跳过并记录审计，而不是让整个查询失败（G14）。

3.5 插件微内核#

PluginManager 从 settings.plugins.enabled 加载模块（仅仓库内模块；Core eagle_rag.plugins.core_defaults 永远最先加载）。每个插件声明 namespace 清单；实例绑定 settings.plugins.default_namespace = Milvus Database + PG 仓储过滤。HookBus 支持 invoke_first / invoke_all / invoke_transform；热路径 Hook 是 PARSE / CHUNK / QUERY_ASSEMBLE，编排 Hook 包括 CLASSIFY_*、EMBED_*、UPSERT_VECTORS、CLASSIFY_QUERY、QUERY_DENSE_EXPAND、RETRIEVE_SUPPLEMENT、RRF_POST_MERGE。编码器经 EncoderRegistry 注册；MCP 工具经 mcp_registry.py 注册，带 RAG-only 命名（assert_rag_only_tool_name）与 G3 namespace 过滤（仅暴露 core_* + default_namespace 插件工具）。

REST / SSE#

• POST /ingest——四种来源（文件 / 字节流 / MinIO 对象 / URL）；返回 job id、去重状态与审计日志。经 kb_name 多租户（缺省回退 settings.kb_name）。
• POST /search、POST /search/stream——仅检索；返回 text + image 来源，含路径、分数、chunk_count、关键词、页码。
• POST /query、POST /query/stream——检索 + 生成。SSE 依次发出 session、step（route / recall / rerank）、sources、token*、done。
• POST /attachments——单张 PixelRAG 图片（默认上限 5 MB）；在查询/搜索时惰性解析，从不写入 Milvus。
• 证据类——GET /documents/{id}/structure、/documents/{id}/file、/documents/{id}/chunks/{chunk_id}。
• 知识库/标签/会话/运维——GET /tags、/sessions*、/admin/probes、任务审计。

请求要点（api/schemas/query.py）：mode（auto|text|visual|hybrid）、filters（source_type / pipeline / year）、scope_filter（ScopeSelection{kb_names, document_ids, tags}，并集语义）、attachments（按 id）以及 MCP 的内联图片字节。

MCP（/mcp，HTTP 默认，stdio 兜底）#

工具只允许检索/组装上下文；assert_rag_only_tool_name 禁止副作用命名。领域插件注册 {namespace}_{name} 工具。

设计理由#

• kb_name 贯穿所有 API、MCP 工具、Celery 任务、Milvus 标量过滤与仓储调用——多租户是横切关注点，不是开关。
• 流式是一等公民：检索 + VLM 生成较慢，客户端可以增量看到 route → recall → rerank → sources → tokens。
• scope_filter 把完整并集过滤下推到 Milvus（_resolve_scope_filter），标签经标签目录解析为 document_id，并带文档数量上限保护。
• 按设计不做鉴权（内网）；需要时由网关补。

Milvus 2.6（每个 plugin_namespace 一个 Database）#

• eagle_text——1536 维文本块（HNSW/DiskANN），标量过滤 kb_name、document_id、year、source_type、type、path；去重主键 (sha256, kb_name, plugin_namespace)。
• eagle_visual——2048 维视觉切片，带融合锚点：chunk_type（tile|image|table）、parent_section、content_summary、source_chunk_id。
• 客户端按 DB 名池化（index/milvus_pool.py），永不关闭。

PostgreSQL 16（SQLModel + Alembic）#

表：documents、document_keywords（标签目录）、images、sessions + messages、task_audit（审计/重试）、document_dedup、knowledge_bases、attachments、notifications、mcp_call_log、system_setting、metric_samples。每条注册表数据都带 kb_name + plugin_namespace；仓储按 namespace 过滤（db/repositories/）。

Redis 7 / MinIO#

Redis 是 Celery broker + 结果后端；MinIO 按 kb_name 前缀存储上传文件，worker 按 object key 拉取。

取舍#

选 Milvus 而非 FAISS，因为需要托管 ANN + 标量过滤 + Database 隔离；代价是外部服务依赖以及与 PG 的最终一致。PG 保存关系型事实（注册表、审计、会话）；Milvus 只放可重建的向量（重新解析即可恢复）。