存储参考

本页回答“当前平台的状态最终落在哪种存储里，以及排障时应该先查哪一层”。

存储分层

存储	主要职责	当前承载内容
PostgreSQL	业务真相源	Agent、Session、Knowledge Source、Ingestion Job、Evaluation Run、MCP Audit、Fusion Run 等
MinIO	文件与对象资产	原始文档、source CSV、managed correction 文档、部分中间产物
Qdrant	检索索引	document chunk vectors、payload metadata、source-scoped retrieval index

一句话判断法

想查“这个对象当前是什么状态”：先看 PostgreSQL
想查“原始文件或导出文件还在不在”：看 MinIO
想查“向量是否真的可检索”：看 Qdrant

PostgreSQL 当前承担的职责

1. 平台控制面与业务真相源

实体簇	代表模型
Agent 与版本	`agents.py`
Session 与 turn	`sessions.py`
Knowledge Source 与 mounts	`knowledge.py`
Document / chunk / ingestion	`documents.py`
MCP registry / credential / mount / audit	`mcp.py`
Skill / version / mount	`skills.py`
Evaluation dataset / run / result	`evaluations.py`
Fusion definition / version / run	`fusion.py`
Scheduled task / run history	`scheduled_tasks.py`
Admin access / auth / model config	`admin_access.py` `llm_model_config.py`

2. 运行时可观察性状态

PostgreSQL 不只存业务对象，也存当前系统大量“可排障状态”：

ConversationTurn 的 token usage、trace_id、message_type
RuntimeCheckpoint 的审批与挂起状态
Document.vector_status、expected_point_count、actual_point_count
ManualInspectionRun 与 inspect result
MCPCallAudit
Skill 执行审计
AgentEvaluationRun 的 lease / heartbeat / gate 结果

这也是为什么当前项目的问题通常先查数据库状态，而不是先查日志。

MinIO 当前承担的职责

MinIO 在当前项目里不只是“放上传文件”的桶，它至少承载这些对象类型：

对象类型	来源
知识源原始文档	RAG 上传文档
Evaluation dataset 源 CSV	evaluation import
managed correction 文档	correction publish
部分导出 / 中间对象	由对应业务流程生成

重要边界：

MinIO 保存的是对象资产
这些对象真正如何被系统使用，仍然由 PostgreSQL 中的记录决定

Qdrant 当前承担的职责

Qdrant 当前主要用于 document chunk 向量检索，不承担业务真相源职责。

Qdrant 里最关键的不是“有没有 collection”这么粗的判断，而是：

某个 document 的 point 数是否与预期一致
某个 source 的向量是否可见
retrieval 时到底读了哪些 collection

这也是为什么系统专门持久化了：

expected_point_count
actual_point_count
vector_verified_at
vector_status

RAG 相关状态是怎么分散落库的

状态	存储位置
文档原件	MinIO
parse snapshot	PostgreSQL
chunk 元数据	PostgreSQL
向量	Qdrant
active mount 关系	PostgreSQL
retrieval debug / turn context	PostgreSQL

所以 RAG 排障通常都要跨三层看，不能只盯一个系统。

评测与 Fusion 的存储特点

Evaluation

dataset 与 item 在 PostgreSQL
source CSV 在 MinIO
run、result、judge / gate 汇总在 PostgreSQL

Fusion

definition / version / run 在 PostgreSQL
run input / output 的文本与 JSON 也在 PostgreSQL
如果 input / output 是文件资产，则对象放 MinIO，引用落 PostgreSQL

排障时先查哪层

问题像“配置或控制面没生效”

先查 PostgreSQL 里的主实体与关联表。

问题像“文件丢了或下载失败”

先查 MinIO object key 与下载代理入口。

问题像“检索质量异常或 indexed 但查不到”

先查 PostgreSQL 的 document / source 状态，再查 Qdrant point 数与 retrieval debug。

代码入口

路径	说明
`ai_service/storage/model_domains/`	ORM 真相源
`ai_service/storage/minio_client.py`	MinIO 访问层
`ai_service/storage/qdrant_client.py`	Qdrant 访问层