数据库模式与实体关系

本页是 Chameleon 数据层的“总览入口”，用于回答三个问题：

系统有哪些核心实体
实体之间如何关联
查询与检索如何落在索引和字段设计上

数据层总体设计

当前系统采用三层存储协作：

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

其中 PostgreSQL 是业务真相源，Qdrant 和 MinIO 分别承担检索性能与文件持久化。

ER 图

erDiagram
    AGENTS ||--o{ SESSIONS : "owns"
    SESSIONS ||--o{ MESSAGES : "contains"
    AGENTS ||--o{ AGENT_KNOWLEDGE_LINKS : "mounts"
    KNOWLEDGE_SOURCES ||--o{ AGENT_KNOWLEDGE_LINKS : "mounted_by"
    KNOWLEDGE_SOURCES ||--o{ DOCUMENTS : "contains"
    KNOWLEDGE_SOURCES ||--o{ INGESTION_JOBS : "has_jobs"
    AGENTS ||--o{ INGESTION_JOBS : "scoped_jobs"
    KNOWLEDGE_SOURCES ||--o{ DOCUMENT_CHUNKS : "contains_chunks"
    AGENTS ||--o{ DOCUMENT_CHUNKS : "scoped_chunks"

    AGENTS {
        string id PK
        string name
        string status
        string model_name
        string model_provider
        float model_temperature
        datetime created_at
        datetime updated_at
    }

    SESSIONS {
        string id PK
        string status
        string agent_id FK
        string model_name
        string model_provider
        float model_temperature
        datetime created_at
        datetime updated_at
    }

    MESSAGES {
        string id PK
        string session_id FK
        string role
        text content
        datetime created_at
    }

    KNOWLEDGE_SOURCES {
        string id PK
        string name
        string storage_type
        string status
        string default_chunking_strategy
        text default_chunking_params
        datetime created_at
        datetime updated_at
    }

    AGENT_KNOWLEDGE_LINKS {
        string id PK
        string agent_id FK
        string source_id FK
        bool is_active
        int priority
        datetime created_at
        datetime updated_at
    }

    DOCUMENTS {
        string id PK
        string source_id FK
        string filename
        string content_type
        int size_bytes
        string minio_object_key
        string status
        text error_message
        text metadata_json
        datetime created_at
        datetime updated_at
    }

    INGESTION_JOBS {
        string id PK
        string source_id FK
        string agent_id FK
        string status
        string status_message
        int documents_total
        int documents_done
        int chunks_total
        int chunks_done
        int chunk_size
        int chunk_overlap
        string chunking_strategy
        text chunking_params
        string embedding_model
        text error_message
        datetime created_at
        datetime updated_at
    }

    DOCUMENT_CHUNKS {
        string id PK
        string source_id FK
        string agent_id FK
        string document_name
        int chunk_index
        text content
        text metadata_json
        string chunking_strategy
        datetime created_at
    }

实体分组说明

会话域

sessions：会话主表，保存会话状态与会话级模型覆盖参数。
messages：会话消息流水，按 session_id 聚合历史上下文。

Agent 与知识源域

agents：AI 角色配置，包含系统提示词与默认模型参数。
knowledge_sources：知识库逻辑分组，保存默认分块策略。
agent_knowledge_links：多对多挂载关系，包含 priority 与 is_active。

文档摄取域

documents：上传文件元信息，关联 MinIO 对象键与处理状态。
ingestion_jobs：异步摄取任务状态，记录进度计数与 status_message。
document_chunks：文本分块结果，供向量化和检索回溯使用。

关键索引与约束

名称	类型	作用
`ix_agent_knowledge_unique`	复合唯一索引	防止同一 Agent 重复挂载同一知识源
`ix_documents_source_status`	复合索引	加速按知识源和状态筛选文档
`ix_document_chunks_agent_source`	复合索引	加速按 Agent 与知识源过滤分块
多个 `index=True` 外键索引	普通索引	支撑会话、任务、文档等关联查询

PostgreSQL 与 Qdrant 的映射

摄取时，系统会在 PostgreSQL 写入 document_chunks，并同步向量到 Qdrant。典型 payload 结构如下：

{
  "chunk_id": "uuid",
  "source_id": "knowledge_source_id",
  "document_id": "document_id",
  "document_name": "example.pdf",
  "chunk_index": 0,
  "agent_id": "agent_id"
}

检索阶段可按 source_id、source_ids、agent_id、document_id 做过滤，保证 Agent 级知识隔离。

代码入口

ORM 模型：ai_service/storage/models.py
会话与引擎：ai_service/utils/database.py
向量服务：ai_service/storage/qdrant_client.py
对象存储服务：ai_service/storage/minio_client.py