┌─────────────────────────────────────────────────────────────┐
│  上游服务层（Indexing/Retrieval/RAG Service）               │
│  - 通过 VectorStoreClient 统一调用                          │
└─────────────────────────────────────────────────────────────┘
                            ▼ HTTP
┌─────────────────────────────────────────────────────────────┐
│  API 层（FastAPI）                                          │
│  - HTTP 接口：insert/search/delete/count/stats             │
│  - 参数校验、错误处理、Prometheus 指标                     │
└─────────────────────────────────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  管理层（VectorStoreManager）                                │
│  - 后端路由：根据 backend 参数选择适配器                    │
│  - 健康检查：定期检查后端可用性                             │
│  - 统计信息：汇总各后端状态                                 │
└─────────────────────────────────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  适配器层（VectorStoreBackend）                              │
│  - MilvusBackend：Milvus 适配器                             │
│  - PgVectorBackend：pgvector 适配器                         │
│  - 统一接口：insert/search/delete/count/create/drop         │
└─────────────────────────────────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  向量数据库层                                                │
│  - Milvus：高性能向量数据库（HNSW 索引）                    │
│  - PostgreSQL + pgvector：SQL 兼容向量存储（IVF 索引）     │
└─────────────────────────────────────────────────────────────┘

flowchart TB
    subgraph "上游服务层"
        IndexingService[Indexing Service<br/>文档索引服务]
        RetrievalService[Retrieval Service<br/>检索服务]
        RAGEngine[RAG Engine<br/>生成式检索引擎]
    end

    subgraph "统一客户端层"
        VectorStoreClient[VectorStoreClient<br/>统一向量存储客户端<br/>HTTP调用封装]
    end

    subgraph "Vector Store Adapter 服务"
        direction TB

        subgraph "API 层"
            FastAPI[FastAPI 服务<br/>端口: 8003]
            HealthCheck["/health, /ready<br/>健康检查"]
            InsertAPI["/collections/{name}/insert<br/>插入接口"]
            SearchAPI["/collections/{name}/search<br/>检索接口"]
            DeleteAPI["/collections/{name}/documents/{id}<br/>删除接口"]
            CountAPI["/collections/{name}/count<br/>统计接口"]
            StatsAPI["/stats<br/>监控指标"]
        end

        subgraph "管理层"
            VectorStoreManager[VectorStoreManager<br/>后端管理器<br/>Backend选择/健康检查]
        end

        subgraph "适配器层"
            BaseBackend[VectorStoreBackend<br/>抽象基类]
            MilvusAdapter[MilvusBackend<br/>Milvus适配器]
            PgVectorAdapter[PgVectorBackend<br/>pgvector适配器]
        end

        subgraph "连接池层"
            ConnectionPool[ConnectionPool<br/>连接池管理<br/>复用/健康检查/自动重连]
        end
    end

    subgraph "向量数据库层"
        Milvus[(Milvus<br/>高性能向量数据库<br/>HNSW索引)]
        PostgreSQL[(PostgreSQL<br/>pgvector扩展<br/>IVF索引)]
    end

    subgraph "监控层"
        Prometheus[Prometheus<br/>指标收集]
    end

    IndexingService -->|HTTP POST<br/>批量插入向量| VectorStoreClient
    RetrievalService -->|HTTP POST<br/>向量检索| VectorStoreClient
    RAGEngine -->|HTTP POST<br/>混合检索| VectorStoreClient

    VectorStoreClient -->|HTTP Request| FastAPI

    FastAPI --> HealthCheck
    FastAPI --> InsertAPI
    FastAPI --> SearchAPI
    FastAPI --> DeleteAPI
    FastAPI --> CountAPI
    FastAPI --> StatsAPI

    InsertAPI --> VectorStoreManager
    SearchAPI --> VectorStoreManager
    DeleteAPI --> VectorStoreManager
    CountAPI --> VectorStoreManager
    StatsAPI --> VectorStoreManager

    VectorStoreManager --> BaseBackend
    BaseBackend --> MilvusAdapter
    BaseBackend --> PgVectorAdapter

    MilvusAdapter --> ConnectionPool
    PgVectorAdapter --> ConnectionPool

    MilvusAdapter -->|pymilvus SDK| Milvus
    PgVectorAdapter -->|asyncpg + pgvector| PostgreSQL

    FastAPI -->|/metrics| Prometheus
    VectorStoreManager -->|健康检查指标| Prometheus

    style VectorStoreClient fill:#e1f5ff
    style VectorStoreManager fill:#fff4e1
    style MilvusAdapter fill:#e8f5e9
    style PgVectorAdapter fill:#e8f5e9
    style Milvus fill:#ffebee
    style PostgreSQL fill:#ffebee

sequenceDiagram
    autonumber
    participant Main as main.py<br/>应用入口
    participant App as FastAPI App<br/>应用实例
    participant VM as VectorStoreManager<br/>管理器
    participant MB as MilvusBackend<br/>Milvus适配器
    participant PB as PgVectorBackend<br/>PgVector适配器
    participant MV as Milvus<br/>向量数据库
    participant PG as PostgreSQL<br/>关系数据库

    Note over Main: 启动服务<br/>uvicorn main:app

    Main->>App: lifespan 上下文管理器<br/>启动阶段
    activate App

    App->>VM: VectorStoreManager()<br/>创建管理器实例
    activate VM

    App->>VM: initialize()<br/>初始化所有后端

    Note over VM: 初始化 Milvus 后端

    VM->>MB: MilvusBackend(config)<br/>创建适配器实例
    activate MB

    VM->>MB: initialize()<br/>初始化连接

    MB->>MV: connections.connect()<br/>建立连接
    activate MV

    alt 连接成功
        MV-->>MB: 连接建立成功
        deactivate MV
        MB-->>VM: initialized=True
    else 连接失败
        MV-->>MB: 连接异常
        deactivate MV
        MB-->>VM: 记录错误，继续初始化
    end

    deactivate MB

    Note over VM: 初始化 pgvector 后端

    VM->>PB: PgVectorBackend(config)<br/>创建适配器实例
    activate PB

    VM->>PB: initialize()<br/>初始化连接池

    PB->>PG: asyncpg.create_pool()<br/>创建连接池（2-10个连接）
    activate PG

    alt 连接成功
        PG-->>PB: Pool 创建成功
        PB->>PG: register_vector()<br/>注册向量类型
        PG-->>PB: 注册成功
        deactivate PG
        PB-->>VM: initialized=True
    else 连接失败
        PG-->>PB: 连接异常
        deactivate PG
        PB-->>VM: 记录错误，继续初始化
    end

    deactivate PB

    VM-->>App: 初始化完成<br/>可用后端列表
    deactivate VM

    Note over App: 注册路由、中间件、监控

    App-->>Main: 服务就绪<br/>监听端口 8003
    deactivate App

    Note over Main: 服务运行中<br/>等待请求

@asynccontextmanager
async def lifespan(app: FastAPI):
    """应用生命周期管理"""
    global vector_store_manager

    logger.info("Starting Vector Store Adapter Service...")

    try:
        # 初始化向量存储管理器
        from app.core.vector_store_manager import VectorStoreManager

        vector_store_manager = VectorStoreManager()
        await vector_store_manager.initialize()

        logger.info("Vector Store Adapter Service started successfully")

        yield  # 应用运行

    finally:
        logger.info("Shutting down Vector Store Adapter Service...")

        # 清理资源
        if vector_store_manager:
            await vector_store_manager.cleanup()

        logger.info("Vector Store Adapter Service shut down complete")

async def initialize(self):
    """初始化所有后端"""
    logger.info("Initializing vector store backends...")

    # 初始化 Milvus
    try:
        milvus_config = settings.get_backend_config("milvus")
        milvus_backend = MilvusBackend(milvus_config)
        await milvus_backend.initialize()
        self.backends["milvus"] = milvus_backend
        logger.info("Milvus backend initialized")
    except Exception as e:
        logger.error(f"Failed to initialize Milvus backend: {e}")

    # 初始化 pgvector
    try:
        pgvector_config = settings.get_backend_config("pgvector")
        pgvector_backend = PgVectorBackend(pgvector_config)
        await pgvector_backend.initialize()
        self.backends["pgvector"] = pgvector_backend
        logger.info("pgvector backend initialized")
    except Exception as e:
        logger.error(f"Failed to initialize pgvector backend: {e}")

    logger.info(f"Vector store manager initialized with {len(self.backends)} backend(s)")

async def initialize(self):
    """初始化 Milvus 连接"""
    try:
        connections.connect(
            alias=self.alias,
            host=self.config["host"],
            port=self.config["port"],
            user=self.config.get("user", ""),
            password=self.config.get("password", ""),
        )
        self.initialized = True
        logger.info(f"Connected to Milvus at {self.config['host']}:{self.config['port']}")
    except Exception as e:
        logger.error(f"Failed to connect to Milvus: {e}")
        raise

async def initialize(self):
    """初始化 PostgreSQL 连接池"""
    try:
        self.pool = await asyncpg.create_pool(
            host=self.config["host"],
            port=self.config["port"],
            database=self.config["database"],
            user=self.config["user"],
            password=self.config["password"],
            min_size=2,
            max_size=10,
        )

        # 注册 vector 类型
        async with self.pool.acquire() as conn:
            await register_vector(conn)

        self.initialized = True
        logger.info(f"Connected to PostgreSQL at {self.config['host']}:{self.config['port']}")
    except Exception as e:
        logger.error(f"Failed to connect to PostgreSQL: {e}")
        raise

sequenceDiagram
    autonumber
    participant IS as Indexing Service<br/>文档索引服务
    participant VSC as VectorStoreClient<br/>统一客户端
    participant API as FastAPI<br/>HTTP 接口
    participant VM as VectorStoreManager<br/>后端管理器
    participant MA as MilvusBackend<br/>Milvus 适配器
    participant MV as Milvus<br/>向量数据库
    participant PM as Prometheus<br/>监控指标

    Note over IS: 文档分块和向量化完成

    IS->>VSC: insert_batch(data_list)<br/>批量插入向量数据
    activate VSC

    Note over VSC: 构建 HTTP 请求<br/>POST /collections/{name}/insert

    VSC->>API: HTTP POST<br/>body: {backend, data[]}
    activate API

    Note over API: 路由到插入接口<br/>insert_vectors()

    API->>API: 参数校验<br/>- collection_name<br/>- data 非空<br/>- backend 类型

    API->>VM: insert_vectors()<br/>(collection, backend, data)
    activate VM

    VM->>VM: _get_backend(backend)<br/>选择后端实例

    VM->>MA: insert_vectors()<br/>(collection, data)
    activate MA

    Note over MA: 自动创建 Collection<br/>（如不存在）

    MA->>MA: _get_or_create_collection()<br/>检查/创建 Collection

    alt Collection 不存在
        MA->>MA: _create_collection()<br/>定义 Schema + 创建索引
        MA->>MV: create_collection(schema)
        activate MV
        MV-->>MA: Collection 对象
        deactivate MV
        MA->>MV: create_index(HNSW)
        activate MV
        MV-->>MA: 索引创建成功
        deactivate MV
        MA->>MV: collection.load()
        activate MV
        MV-->>MA: 加载到内存
        deactivate MV
    end

    Note over MA: 准备批量数据<br/>转换为 Milvus 格式

    MA->>MA: 构建 entities 列表<br/>- chunk_id[]<br/>- document_id[]<br/>- content[]<br/>- embedding[]<br/>- tenant_id[]<br/>- created_at[]

    MA->>MV: collection.insert(entities)
    activate MV

    Note over MV: 批量插入<br/>HNSW 索引构建

    MV-->>MA: insert_result<br/>(ids, count)
    deactivate MV

    MA->>MV: collection.flush()<br/>持久化到磁盘
    activate MV
    MV-->>MA: flush 完成
    deactivate MV

    MA-->>VM: insert_result
    deactivate MA

    VM-->>API: insert_result
    deactivate VM

    API->>PM: VECTOR_OPERATIONS.inc()<br/>operation=insert, status=success

    API-->>VSC: HTTP 200 OK<br/>{status, inserted, result}
    deactivate API

    VSC-->>IS: 插入完成<br/>返回插入数量
    deactivate VSC

    Note over IS: 更新索引状态<br/>发布事件

async def process_document(self, document_id: str, job_id: str, options: Dict[str, Any]):
    # 1. 下载文档内容
    content = await self.storage_service.download(document_id)

    # 2. 解析文档
    parsed_content = await self.parser_service.parse(content, format=options.get("format", "txt"))

    # 3. 文本分块
    chunks = await self.chunk_service.create_chunks(
        document_id=document_id,
        content=parsed_content,
        chunk_size=options.get("chunk_size", settings.MAX_CHUNK_SIZE),
        overlap=options.get("overlap", settings.CHUNK_OVERLAP),
    )

    # 4. 向量化（调用 Embedding Service）
    chunk_texts = [chunk["content"] for chunk in chunks]
    embeddings = await self.embedding_service.embed_batch(chunk_texts)

    # 5. 调用 Vector Store Adapter 存储向量
    vectors_inserted = await self.vector_service.insert_vectors(
        document_id=document_id,
        chunks=chunks,
        embeddings=embeddings,
    )

async def insert_batch(self, data_list: List[Dict]):
    """
    批量插入数据

    Args:
        data_list: 数据列表 [
            {
                "chunk_id": "doc1-chunk-0",
                "document_id": "doc1",
                "content": "文本内容",
                "embedding": [0.1, 0.2, ...],  # 1024维向量
                "tenant_id": "tenant-123"
            },
            ...
        ]
    """
    if not data_list:
        logger.warning("Empty data list for insertion")
        return

    try:
        # 构建 HTTP POST 请求
        response = await self.client.post(
            f"/collections/{self.collection_name}/insert",
            json={
                "backend": self.backend,  # "milvus" 或 "pgvector"
                "data": data_list,
            },
        )

        response.raise_for_status()
        result = response.json()

        logger.info(f"Inserted {len(data_list)} vectors via adapter service")
        return result

    except httpx.HTTPError as e:
        logger.error(f"Error inserting vectors: {e}")
        raise

@app.post("/collections/{collection_name}/insert")
async def insert_vectors(collection_name: str, request: dict):
    """
    插入向量（单条或批量）

    Args:
        collection_name: 集合名称（如 "document_chunks"）
        request:
            backend: 后端类型 (milvus/pgvector)
            data: 向量数据（单条或列表）
    """
    global vector_store_manager

    if not vector_store_manager:
        raise HTTPException(status_code=503, detail="Service not initialized")

    backend = request.get("backend", "milvus")
    data = request.get("data")

    if not data:
        raise HTTPException(status_code=400, detail="Data is required")

    try:
        # 确保是列表
        if isinstance(data, dict):
            data = [data]

        # 调用管理器
        result = await vector_store_manager.insert_vectors(
            collection_name=collection_name,
            backend=backend,
            data=data,
        )

        # 记录 Prometheus 指标
        VECTOR_OPERATIONS.labels(
            operation="insert",
            backend=backend,
            status="success",
        ).inc(len(data))

        return {
            "status": "success",
            "collection": collection_name,
            "backend": backend,
            "inserted": len(data),
            "result": result,
        }

    except Exception as e:
        logger.error(f"Error inserting vectors: {e}", exc_info=True)
        VECTOR_OPERATIONS.labels(
            operation="insert",
            backend=backend,
            status="error",
        ).inc()
        raise HTTPException(status_code=500, detail=str(e))

async def insert_vectors(
    self,
    collection_name: str,
    backend: str,
    data: List[Dict],
) -> Any:
    """
    插入向量

    Args:
        collection_name: 集合名称
        backend: 后端类型
        data: 向量数据列表

    Returns:
        插入结果
    """
    backend_instance = self._get_backend(backend)
    return await backend_instance.insert_vectors(collection_name, data)

def _get_backend(self, backend: str) -> VectorStoreBackend:
    """获取后端实例"""
    if backend not in self.backends:
        raise ValueError(f"Backend {backend} not available. Available: {list(self.backends.keys())}")

    return self.backends[backend]

async def insert_vectors(
    self,
    collection_name: str,
    data: List[Dict],
) -> Any:
    """插入向量"""
    if not data:
        logger.warning("Empty data list for insertion")
        return None

    # 1. 获取或创建 Collection
    dimension = len(data[0]["embedding"])
    collection = self._get_or_create_collection(collection_name, dimension)

    # 2. 准备数据（转换为 Milvus 格式）
    entities = [
        [item["chunk_id"] for item in data],           # VARCHAR 字段
        [item["document_id"] for item in data],        # VARCHAR 字段
        [item["content"] for item in data],            # VARCHAR 字段
        [item["embedding"] for item in data],          # FLOAT_VECTOR 字段
        [item.get("tenant_id", "default") for item in data],  # VARCHAR 字段
        [int(time.time() * 1000) for _ in data],       # INT64 字段（created_at）
    ]

    # 3. 批量插入
    result = collection.insert(entities)

    # 4. 刷新到磁盘
    collection.flush()

    logger.info(f"Inserted {len(data)} vectors into Milvus collection {collection_name}")

    return result

# 输入数据格式（行式）：
data = [
    {
        "chunk_id": "doc1-chunk-0",
        "document_id": "doc1",
        "content": "文本内容1",
        "embedding": [0.1, 0.2, ...],  # 1024维
        "tenant_id": "tenant-123"
    },
    {
        "chunk_id": "doc1-chunk-1",
        "document_id": "doc1",
        "content": "文本内容2",
        "embedding": [0.3, 0.4, ...],
        "tenant_id": "tenant-123"
    }
]

# 转换后格式（列式）：
entities = [
    ["doc1-chunk-0", "doc1-chunk-1"],  # chunk_id 列
    ["doc1", "doc1"],                  # document_id 列
    ["文本内容1", "文本内容2"],          # content 列
    [[0.1, 0.2, ...], [0.3, 0.4, ...]],  # embedding 列
    ["tenant-123", "tenant-123"],      # tenant_id 列
    [1704067200000, 1704067200000]     # created_at 列（时间戳）
]

def _get_or_create_collection(self, collection_name: str, dimension: int = 1024) -> Collection:
    """获取或创建集合"""
    # 检查缓存
    if collection_name in self.collections:
        return self.collections[collection_name]

    # 检查是否存在
    if utility.has_collection(collection_name):
        logger.info(f"Collection {collection_name} exists, loading...")
        collection = Collection(collection_name)
        collection.load()
    else:
        logger.info(f"Creating collection: {collection_name}")
        collection = self._create_collection(collection_name, dimension)

    # 缓存
    self.collections[collection_name] = collection
    return collection

def _create_collection(self, collection_name: str, dimension: int) -> Collection:
    """创建集合"""
    # 定义 Schema
    fields = [
        FieldSchema(name="id", dtype=DataType.INT64, is_primary=True, auto_id=True),
        FieldSchema(name="chunk_id", dtype=DataType.VARCHAR, max_length=128),
        FieldSchema(name="document_id", dtype=DataType.VARCHAR, max_length=64),
        FieldSchema(name="content", dtype=DataType.VARCHAR, max_length=65535),
        FieldSchema(name="embedding", dtype=DataType.FLOAT_VECTOR, dim=dimension),
        FieldSchema(name="tenant_id", dtype=DataType.VARCHAR, max_length=64),
        FieldSchema(name="created_at", dtype=DataType.INT64),
    ]

    schema = CollectionSchema(fields=fields, description=f"{collection_name} collection")

    # 创建集合
    collection = Collection(name=collection_name, schema=schema)

    # 创建索引 (HNSW)
    index_params = {
        "metric_type": "IP",  # Inner Product (Cosine Similarity)
        "index_type": "HNSW",
        "params": {"M": 16, "efConstruction": 256},
    }

    collection.create_index(field_name="embedding", index_params=index_params)

    # 加载到内存
    collection.load()

    logger.info(f"Collection {collection_name} created successfully")

    return collection

index_params = {
    "metric_type": "IP",        # 度量类型：内积（Inner Product）
    "index_type": "HNSW",       # 索引类型：HNSW（Hierarchical Navigable Small World）
    "params": {
        "M": 16,                # 每个节点的邻居数（影响精度和构建时间）
        "efConstruction": 256   # 构建时的候选集大小（影响构建时间和查询精度）
    }
}

sequenceDiagram
    autonumber
    participant RS as Retrieval Service<br/>检索服务
    participant VSC as VectorStoreClient<br/>统一客户端
    participant API as FastAPI<br/>HTTP 接口
    participant VM as VectorStoreManager<br/>后端管理器
    participant MA as MilvusBackend<br/>Milvus 适配器
    participant MV as Milvus<br/>向量数据库
    participant PM as Prometheus<br/>监控指标

    Note over RS: 用户查询：<br/>"什么是机器学习？"

    RS->>RS: embed_query()<br/>查询文本向量化

    Note over RS: 生成 query_vector<br/>1024 维向量

    RS->>VSC: search(query_vector, top_k=10)
    activate VSC

    Note over VSC: 构建 HTTP 请求<br/>POST /collections/{name}/search

    VSC->>API: HTTP POST<br/>body: {backend, query_vector, top_k, filters}
    activate API

    Note over API: 路由到检索接口<br/>search_vectors()

    API->>API: 参数校验<br/>- query_vector 非空<br/>- top_k 合法范围 [1, 1000]<br/>- filters 格式

    API->>VM: search_vectors()<br/>(collection, backend, query_vector, top_k, filters)
    activate VM

    VM->>VM: _get_backend(backend)<br/>选择后端实例

    VM->>MA: search_vectors()<br/>(collection, query_vector, top_k, tenant_id, filters)
    activate MA

    Note over MA: 获取 Collection<br/>（必须已存在）

    MA->>MA: _get_or_create_collection()<br/>加载 Collection

    MA->>MA: _build_expression()<br/>构建过滤表达式<br/>tenant_id == "xxx"

    Note over MA: 配置搜索参数<br/>metric_type=IP<br/>ef=128

    MA->>MV: collection.search()<br/>data=[query_vector]<br/>anns_field="embedding"<br/>limit=top_k<br/>expr=filters
    activate MV

    Note over MV: HNSW 索引检索<br/>- 构建候选集（ef=128）<br/>- 计算内积（IP）<br/>- 排序取 top-k

    MV-->>MA: search_results<br/>hits: [{id, score, distance, entity}]
    deactivate MV

    Note over MA: 转换结果格式<br/>提取字段

    MA->>MA: 遍历 hits<br/>构建返回结果<br/>- chunk_id<br/>- document_id<br/>- content<br/>- score<br/>- distance

    MA-->>VM: results: List[Dict]
    deactivate MA

    VM-->>API: results
    deactivate VM

    API->>PM: VECTOR_OPERATIONS.inc()<br/>operation=search, status=success

    API->>PM: VECTOR_OPERATION_DURATION.observe()<br/>延迟统计

    API-->>VSC: HTTP 200 OK<br/>{status, results[], count}
    deactivate API

    VSC-->>RS: results: List[Dict]
    deactivate VSC

    Note over RS: 后处理<br/>- 去重<br/>- 重排序（可选）<br/>- 返回给 RAG Engine

async def retrieve(
    self,
    query: str,
    top_k: int = 10,
    tenant_id: str = None,
    filters: Dict = None,
) -> List[Dict]:
    """
    向量检索

    Args:
        query: 查询文本
        top_k: 返回结果数
        tenant_id: 租户 ID
        filters: 过滤条件

    Returns:
        检索结果列表
    """
    # 1. 向量化查询（调用 Embedding Service）
    query_embedding = await self.embedder.embed_query(query)

    # 2. 执行向量检索
    results = await self.vector_store_client.search(
        query_vector=query_embedding,
        top_k=top_k,
        tenant_id=tenant_id,
        filters=filters,
    )

    logger.info(f"Vector retrieval: found {len(results)} results")

    return results

async def search(
    self,
    query_vector: List[float],
    top_k: int = 10,
    tenant_id: Optional[str] = None,
    filters: Optional[str] = None,
) -> List[Dict]:
    """
    向量检索

    Args:
        query_vector: 查询向量（1024维）
        top_k: 返回结果数
        tenant_id: 租户 ID（用于过滤）
        filters: 额外过滤条件

    Returns:
        检索结果列表 [
            {
                "chunk_id": "doc1-chunk-0",
                "document_id": "doc1",
                "content": "文本内容",
                "score": 0.95,
                "distance": 0.05,
                "backend": "milvus"
            },
            ...
        ]
    """
    try:
        response = await self.client.post(
            f"/collections/{self.collection_name}/search",
            json={
                "backend": self.backend,
                "query_vector": query_vector,
                "top_k": top_k,
                "tenant_id": tenant_id,
                "filters": filters,
            },
        )

        response.raise_for_status()
        result = response.json()

        logger.info(f"Search returned {result['count']} results via adapter service")
        return result["results"]

    except httpx.HTTPError as e:
        logger.error(f"Error searching vectors: {e}")
        raise

@app.post("/collections/{collection_name}/search")
async def search_vectors(collection_name: str, request: dict):
    """
    向量检索

    Args:
        collection_name: 集合名称
        request:
            backend: 后端类型 (milvus/pgvector)
            query_vector: 查询向量
            top_k: 返回结果数（默认10）
            tenant_id: 租户ID（可选，用于过滤）
            filters: 额外过滤条件（可选）
            search_params: 搜索参数（可选）
    """
    global vector_store_manager

    if not vector_store_manager:
        raise HTTPException(status_code=503, detail="Service not initialized")

    backend = request.get("backend", "milvus")
    query_vector = request.get("query_vector")

    if not query_vector:
        raise HTTPException(status_code=400, detail="query_vector is required")

    try:
        results = await vector_store_manager.search_vectors(
            collection_name=collection_name,
            backend=backend,
            query_vector=query_vector,
            top_k=request.get("top_k", 10),
            tenant_id=request.get("tenant_id"),
            filters=request.get("filters"),
            search_params=request.get("search_params"),
        )

        VECTOR_OPERATIONS.labels(
            operation="search",
            backend=backend,
            status="success",
        ).inc()

        return {
            "status": "success",
            "collection": collection_name,
            "backend": backend,
            "results": results,
            "count": len(results),
        }

    except Exception as e:
        logger.error(f"Error searching vectors: {e}", exc_info=True)
        VECTOR_OPERATIONS.labels(
            operation="search",
            backend=backend,
            status="error",
        ).inc()
        raise HTTPException(status_code=500, detail=str(e))

async def search_vectors(
    self,
    collection_name: str,
    backend: str,
    query_vector: List[float],
    top_k: int = 10,
    tenant_id: Optional[str] = None,
    filters: Optional[str] = None,
    search_params: Optional[Dict] = None,
) -> List[Dict]:
    """
    向量检索

    Args:
        collection_name: 集合名称
        backend: 后端类型
        query_vector: 查询向量
        top_k: 返回结果数
        tenant_id: 租户ID
        filters: 过滤条件
        search_params: 搜索参数

    Returns:
        检索结果列表
    """
    backend_instance = self._get_backend(backend)
    return await backend_instance.search_vectors(
        collection_name=collection_name,
        query_vector=query_vector,
        top_k=top_k,
        tenant_id=tenant_id,
        filters=filters,
        search_params=search_params,
    )

async def search_vectors(
    self,
    collection_name: str,
    query_vector: List[float],
    top_k: int = 10,
    tenant_id: Optional[str] = None,
    filters: Optional[str] = None,
    search_params: Optional[Dict] = None,
) -> List[Dict]:
    """向量检索"""
    # 1. 获取 Collection
    dimension = len(query_vector)
    collection = self._get_or_create_collection(collection_name, dimension)

    # 2. 构建过滤表达式
    expr = []
    if tenant_id:
        expr.append(f'tenant_id == "{tenant_id}"')
    if filters:
        expr.append(filters)

    expr_str = " && ".join(expr) if expr else None

    # 3. 配置搜索参数
    if search_params is None:
        search_params = {
            "metric_type": "IP",  # Inner Product (Cosine Similarity)
            "params": {"ef": 128}  # HNSW 搜索时的候选集大小
        }

    # 4. 执行搜索
    results = collection.search(
        data=[query_vector],
        anns_field="embedding",
        param=search_params,
        limit=top_k,
        expr=expr_str,
        output_fields=["chunk_id", "document_id", "content", "tenant_id"],
    )

    # 5. 转换结果
    output = []
    for hits in results:
        for hit in hits:
            output.append({
                "chunk_id": hit.entity.get("chunk_id"),
                "document_id": hit.entity.get("document_id"),
                "content": hit.entity.get("content"),
                "tenant_id": hit.entity.get("tenant_id"),
                "score": hit.score,
                "distance": hit.distance,
                "backend": "milvus",
            })

    logger.info(f"Milvus search returned {len(output)} results")

    return output

sequenceDiagram
    autonumber
    participant KS as Knowledge Service<br/>知识库服务
    participant VSC as VectorStoreClient<br/>统一客户端
    participant API as FastAPI<br/>HTTP 接口
    participant VM as VectorStoreManager<br/>后端管理器
    participant MA as MilvusBackend<br/>Milvus 适配器
    participant MV as Milvus<br/>向量数据库
    participant PM as Prometheus<br/>监控指标

    Note over KS: 用户删除文档<br/>document_id="doc123"

    KS->>VSC: delete_by_document(document_id)
    activate VSC

    Note over VSC: 构建 HTTP 请求<br/>DELETE /collections/{name}/documents/{id}

    VSC->>API: HTTP DELETE<br/>params: {backend}
    activate API

    Note over API: 路由到删除接口<br/>delete_by_document()

    API->>API: 参数校验<br/>- collection_name<br/>- document_id<br/>- backend

    API->>VM: delete_by_document()<br/>(collection, backend, document_id)
    activate VM

    VM->>VM: _get_backend(backend)<br/>选择后端实例

    VM->>MA: delete_by_document()<br/>(collection, document_id)
    activate MA

    Note over MA: 获取 Collection<br/>（必须已存在）

    MA->>MA: _get_or_create_collection()<br/>加载 Collection

    Note over MA: 构建删除表达式<br/>document_id == "doc123"

    MA->>MV: collection.delete(expr)
    activate MV

    Note over MV: 执行删除操作<br/>- 匹配 document_id<br/>- 删除所有分块<br/>- 更新索引

    MV-->>MA: delete_result<br/>(delete_count)
    deactivate MV

    MA-->>VM: delete_result
    deactivate MA

    VM-->>API: delete_result
    deactivate VM

    API->>PM: VECTOR_OPERATIONS.inc()<br/>operation=delete, status=success

    API-->>VSC: HTTP 200 OK<br/>{status, deleted}
    deactivate API

    VSC-->>KS: 删除完成
    deactivate VSC

    Note over KS: 更新文档状态<br/>发布事件

async def delete_document(self, document_id: str, tenant_id: str):
    """
    删除文档

    Args:
        document_id: 文档 ID
        tenant_id: 租户 ID
    """
    # 1. 删除向量数据
    await self.vector_store_client.delete_by_document(document_id)

    # 2. 删除关系数据（PostgreSQL）
    await self.db.execute("DELETE FROM documents WHERE id = $1", document_id)

    # 3. 删除对象存储文件
    await self.storage_service.delete(document_id)

    logger.info(f"Document deleted: {document_id}")

async def delete_by_document(self, document_id: str):
    """
    删除文档的所有分块

    Args:
        document_id: 文档 ID
    """
    try:
        response = await self.client.delete(
            f"/collections/{self.collection_name}/documents/{document_id}",
            params={"backend": self.backend},
        )

        response.raise_for_status()
        result = response.json()

        logger.info(f"Deleted chunks for document: {document_id} via adapter service")
        return result

    except httpx.HTTPError as e:
        logger.error(f"Error deleting vectors: {e}")
        raise

@app.delete("/collections/{collection_name}/documents/{document_id}")
async def delete_by_document(collection_name: str, document_id: str, backend: str = "milvus"):
    """
    删除文档的所有向量

    Args:
        collection_name: 集合名称
        document_id: 文档ID
        backend: 后端类型
    """
    global vector_store_manager

    if not vector_store_manager:
        raise HTTPException(status_code=503, detail="Service not initialized")

    try:
        result = await vector_store_manager.delete_by_document(
            collection_name=collection_name,
            backend=backend,
            document_id=document_id,
        )

        VECTOR_OPERATIONS.labels(
            operation="delete",
            backend=backend,
            status="success",
        ).inc()

        return {
            "status": "success",
            "collection": collection_name,
            "backend": backend,
            "document_id": document_id,
            "result": result,
        }

    except Exception as e:
        logger.error(f"Error deleting vectors: {e}", exc_info=True)
        VECTOR_OPERATIONS.labels(
            operation="delete",
            backend=backend,
            status="error",
        ).inc()
        raise HTTPException(status_code=500, detail=str(e))

async def delete_by_document(
    self,
    collection_name: str,
    backend: str,
    document_id: str,
) -> Any:
    """
    删除文档的所有向量

    Args:
        collection_name: 集合名称
        backend: 后端类型
        document_id: 文档ID

    Returns:
        删除结果
    """
    backend_instance = self._get_backend(backend)
    return await backend_instance.delete_by_document(collection_name, document_id)

async def delete_by_document(
    self,
    collection_name: str,
    document_id: str,
) -> Any:
    """删除文档的所有向量"""
    collection = self._get_or_create_collection(collection_name)

    # 构建删除表达式
    expr = f'document_id == "{document_id}"'

    # 执行删除
    result = collection.delete(expr)

    logger.info(f"Deleted vectors for document {document_id} from Milvus")

    return result

from abc import ABC, abstractmethod
from typing import Any, Dict, List, Optional


class VectorStoreBackend(ABC):
    """向量存储后端抽象基类"""

    def __init__(self, config: Dict[str, Any]):
        """
        初始化后端

        Args:
            config: 后端配置
        """
        self.config = config
        self.initialized = False

    @abstractmethod
    async def initialize(self):
        """初始化连接"""
        pass

    @abstractmethod
    async def cleanup(self):
        """清理资源"""
        pass

    @abstractmethod
    async def health_check(self) -> bool:
        """健康检查"""
        pass

    @abstractmethod
    async def insert_vectors(
        self,
        collection_name: str,
        data: List[Dict],
    ) -> Any:
        """
        插入向量

        Args:
            collection_name: 集合名称
            data: 向量数据列表
                - chunk_id: 分块ID
                - document_id: 文档ID
                - content: 内容
                - embedding: 向量
                - tenant_id: 租户ID
                - metadata: 元数据（可选）

        Returns:
            插入结果
        """
        pass

    @abstractmethod
    async def search_vectors(
        self,
        collection_name: str,
        query_vector: List[float],
        top_k: int = 10,
        tenant_id: Optional[str] = None,
        filters: Optional[str] = None,
        search_params: Optional[Dict] = None,
    ) -> List[Dict]:
        """
        向量检索

        Args:
            collection_name: 集合名称
            query_vector: 查询向量
            top_k: 返回结果数
            tenant_id: 租户ID（用于过滤）
            filters: 额外过滤条件
            search_params: 搜索参数

        Returns:
            检索结果列表
        """
        pass

    @abstractmethod
    async def delete_by_document(
        self,
        collection_name: str,
        document_id: str,
    ) -> Any:
        """
        删除文档的所有向量

        Args:
            collection_name: 集合名称
            document_id: 文档ID

        Returns:
            删除结果
        """
        pass

    @abstractmethod
    async def get_count(self, collection_name: str) -> int:
        """
        获取集合中的向量数量

        Args:
            collection_name: 集合名称

        Returns:
            向量数量
        """
        pass

    @abstractmethod
    async def create_collection(
        self,
        collection_name: str,
        dimension: int,
        **kwargs,
    ):
        """
        创建集合

        Args:
            collection_name: 集合名称
            dimension: 向量维度
            **kwargs: 其他参数
        """
        pass

    @abstractmethod
    async def drop_collection(self, collection_name: str):
        """
        删除集合

        Args:
            collection_name: 集合名称
        """
        pass