存储架构

本页从整体视角说明 Chameleon 的数据存储设计。若你需要表字段与关系细节，请优先阅读「数据库设计」章节。

设计目标

当前存储架构围绕三件事展开：

• 保证业务元数据可追溯
• 保证向量检索可扩展
• 保证 Agent 级知识隔离

三层存储职责

存储层	技术	主要职责
关系型元数据层	PostgreSQL + SQLAlchemy	会话、消息、Agent、知识源、文档、摄取任务、文本块
向量检索层	Qdrant	向量索引与过滤检索
对象文件层	MinIO	原始文档持久化与回溯

关系型层是业务真相源，向量层和对象层围绕它协作。

端到端数据流

文档摄取流

flowchart LR
  Upload[上传文档] --> Minio[MinIO 原始文件]
  Minio --> Parser[解析器]
  Parser --> Chunker[分块服务]
  Chunker --> PgChunks[PostgreSQL 文本块]
  Chunker --> Embedding[Embedding 服务]
  Embedding --> Qdrant[Qdrant 向量索引]
  Chunker --> JobState[摄取任务状态更新]

对话检索流

flowchart LR
  Request[对话请求] --> Orchestrator[编排器]
  Orchestrator --> Filter[按 Agent 与 Source 过滤]
  Filter --> Qdrant[Qdrant 相似度检索]
  Qdrant --> ChunkMeta[返回 chunk payload]
  ChunkMeta --> Postgres[按 chunk_id 回查元数据]
  Postgres --> Context[拼装上下文]
  Context --> Orchestrator

关键设计决策

关系与向量分离

• document_chunks 保存文本内容与业务元信息。
• Qdrant payload 保存 chunk_id、source_id、document_id、agent_id 等过滤维度。
• 更换嵌入模型时只需重建向量，不需要重新上传原始文档。

Agent 作用域隔离

• Agent 与知识源通过 agent_knowledge_links 建立挂载关系。
• 检索时按 agent_id 和 source_id 过滤，限制召回范围。

异步任务可观测

• ingestion_jobs 记录状态机与进度计数。
• status_message 提供当前阶段文本，便于前端实时展示。

代码入口映射

• 数据库连接：ai_service/utils/database.py
• ORM 模型与 CRUD：ai_service/storage/models.py
• 向量服务：ai_service/storage/qdrant_client.py
• 对象存储服务：ai_service/storage/minio_client.py
• 摄取编排：ai_service/services/ingestion.py

延伸阅读

• 模式与关系：docs/database/schema.md
• 迁移与版本：docs/database/migrations.md
• 代码级 API：docs/api/storage.md