7.5 · 向量数据库集成（Vector Database Integration）

向量数据库集成（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/7.5-vector-database-integration

翻译时间：2026-06-09T16:09:27.802Z

翻译模型：deepseek-chat

原文字符数：13747

项目：Open WebUI (open-webui)

---

向量数据库集成

相关源文件

以下文件为本 wiki 页面的生成提供了上下文：

• backend/open_webui/models/memories.py
• backend/open_webui/retrieval/loaders/datalab_marker.py
• backend/open_webui/retrieval/loaders/main.py
• backend/open_webui/retrieval/loaders/mineru.py
• backend/open_webui/retrieval/loaders/paddleocr_vl.py
• backend/open_webui/retrieval/utils.py
• backend/open_webui/retrieval/vector/dbs/chroma.py
• backend/open_webui/retrieval/vector/dbs/elasticsearch.py
• backend/open_webui/retrieval/vector/dbs/milvus.py
• backend/open_webui/retrieval/vector/dbs/milvus_multitenancy.py
• backend/open_webui/retrieval/vector/dbs/opensearch.py
• backend/open_webui/retrieval/vector/dbs/oracle23ai.py
• backend/open_webui/retrieval/vector/dbs/pgvector.py
• backend/open_webui/retrieval/vector/dbs/pinecone.py
• backend/open_webui/retrieval/vector/dbs/qdrant.py
• backend/open_webui/retrieval/vector/dbs/qdrant_multitenancy.py
• backend/open_webui/retrieval/vector/dbs/s3vector.py
• backend/open_webui/retrieval/vector/dbs/weaviate.py
• backend/open_webui/retrieval/vector/utils.py
• backend/open_webui/routers/memories.py
• backend/open_webui/routers/retrieval.py
• src/lib/apis/retrieval/index.ts
• src/lib/components/admin/Settings/Documents.svelte
• src/lib/components/admin/Settings/WebSearch.svelte

本文档描述了 Open WebUI 中的向量数据库抽象层，该层提供了统一的接口，用于在多个向量数据库后端之间存储和检索文档嵌入。该抽象层支持语义搜索，并构成了 RAG（检索增强生成）系统的核心存储机制。

---

支持的向量数据库

Open WebUI 通过可插拔架构支持多种向量数据库后端。系统使用工厂模式根据配置实例化相应的客户端。

可用后端

数据库	实现类	主要特性
ChromaDB	ChromaClient	默认本地存储，支持持久化模式和 HTTP 模式 backend/open_webui/retrieval/vector/dbs/chroma.py:31-32。
Qdrant	QdrantClient	支持 gRPC、HNSW 配置和磁盘存储 backend/open_webui/retrieval/vector/dbs/qdrant.py:35-36。
Milvus	MilvusClient	社区支持，支持多种索引类型（HNSW、IVF_FLAT、DISKANN）backend/open_webui/retrieval/vector/dbs/milvus.py:36-37。
PGVector	PgvectorClient	PostgreSQL 扩展支持，可选的 PGCrypto 加密用于文本/元数据 backend/open_webui/retrieval/vector/dbs/pgvector.py:88-89。
Pinecone	PineconeClient	无服务器云集成，支持 gRPC 和指数退避重试 backend/open_webui/retrieval/vector/dbs/pinecone.py:46-47。
OpenSearch	OpenSearchClient	企业搜索集成，使用 k-NN 插件和 FAISS 引擎 backend/open_webui/retrieval/vector/dbs/opensearch.py:25-26。
Elasticsearch	ElasticsearchClient	使用 dense_vector 类型和余弦相似度 backend/open_webui/retrieval/vector/dbs/elasticsearch.py:29-30。
Weaviate	WeaviateClient	支持自定义向量和大写类名清理 backend/open_webui/retrieval/vector/dbs/weaviate.py:57-58。
Oracle 23ai	Oracle23aiClient	原生向量相似度搜索，支持连接池和健康监控 backend/open_webui/retrieval/vector/dbs/oracle23ai.py:64-65。
S3Vector	S3VectorClient	基于 AWS S3 的向量存储，元数据键限制（最多 10 个键）backend/open_webui/retrieval/vector/dbs/s3vector.py:20-21。

来源：

• backend/open_webui/retrieval/vector/dbs/chroma.py:31-60
• backend/open_webui/retrieval/vector/dbs/pgvector.py:88-172
• backend/open_webui/retrieval/vector/dbs/milvus.py:36-170
• backend/open_webui/retrieval/vector/dbs/pinecone.py:46-86
• backend/open_webui/retrieval/vector/dbs/s3vector.py:20-46
• backend/open_webui/retrieval/vector/dbs/qdrant.py:35-70
• backend/open_webui/retrieval/vector/dbs/opensearch.py:25-33
• backend/open_webui/retrieval/vector/dbs/elasticsearch.py:29-50
• backend/open_webui/retrieval/vector/dbs/weaviate.py:57-70
• backend/open_webui/retrieval/vector/dbs/oracle23ai.py:64-107

---

向量数据库客户端架构

系统将数据库特定的逻辑抽象在 VectorDBBase 类之后。VECTOR_DB_CLIENT 和 ASYNC_VECTOR_DB_CLIENT 通过工厂模式实例化 backend/open_webui/retrieval/vector/factory.py:1-49。

工厂模式与自然语言到代码的映射

下图将概念性的"向量数据库"需求桥接到处理数据流的具体代码实体。

graph TB
    subgraph "自然语言空间（需求）"
        Req1["存储文档嵌入"]
        Req2["按相似度搜索"]
        Req3["多租户隔离"]
    end

    subgraph "代码实体空间（实现）"
        Factory["VECTOR_DB_CLIENT in factory.py"]
        Base["VectorDBBase in main.py"]

        subgraph "具体客户端"
            Chroma["ChromaClient (chroma.py)"]
            Qdrant["QdrantClient (qdrant.py)"]
            QdrantMT["QdrantClient (qdrant_multitenancy.py)"]
            Milvus["MilvusClient (milvus.py)"]
            MilvusMT["MilvusClient (milvus_multitenancy.py)"]
            PGV["PgvectorClient (pgvector.py)"]
            Pinecone["PineconeClient (pinecone.py)"]
            OpenSearch["OpenSearchClient (opensearch.py)"]
            Elasticsearch["ElasticsearchClient (elasticsearch.py)"]
            Weaviate["WeaviateClient (weaviate.py)"]
            Oracle23ai["Oracle23aiClient (oracle23ai.py)"]
            S3Vector["S3VectorClient (s3vector.py)"]
        end

        subgraph "数据模型"
            VItem["VectorItem (TypedDict)"]
            SRes["SearchResult (TypedDict)"]
            GRes["GetResult (TypedDict)"]
        end
    end

    Req1 --> Factory
    Req2 --> Factory
    Req3 --> Factory

    Factory -->|实例化| Base
    Base <|-- Chroma
    Base <|-- Qdrant
    Base <|-- QdrantMT
    Base <|-- Milvus
    Base <|-- MilvusMT
    Base <|-- PGV
    Base <|-- Pinecone
    Base <|-- OpenSearch
    Base <|-- Elasticsearch
    Base <|-- Weaviate
    Base <|-- Oracle23ai
    Base <|-- S3Vector

    Chroma -->|返回| SRes
    QdrantMT -->|接受| VItem
    PGV -->|映射到| DocChunk["DocumentChunk (SQLAlchemy)"]

图：将向量数据库需求映射到代码实体

来源：

• backend/open_webui/retrieval/vector/factory.py:1-49
• backend/open_webui/retrieval/vector/main.py:10-50
• backend/open_webui/retrieval/vector/dbs/pgvector.py:73-86
• backend/open_webui/retrieval/vector/dbs/qdrant_multitenancy.py:46-88

---

数据流与持久化

每个后端以不同的方式处理数据映射，以满足其底层引擎的需求。例如，PgvectorClient 使用 DocumentChunk SQLAlchemy 模型 backend/open_webui/retrieval/vector/dbs/pgvector.py:73-86，而 MilvusClient 使用 DataType.JSON 创建动态模式以存储元数据 backend/open_webui/retrieval/vector/dbs/milvus.py:98-116。

插入流程（代码层面）

sequenceDiagram
    participant App as 检索路由器
    participant Client as VectorDBClient（例如 PgvectorClient）
    participant DB as 数据库引擎（例如 PostgreSQL）

    App->>Client: insert(collection_name, items: List[VectorItem])
    Note over Client: items 包含 'id'、'vector'、'text'、'metadata'

    alt PGVector 实现
        Client->>Client: check_vector_length()
        Client->>DB: INSERT INTO document_chunk (id, vector, text, vmetadata)
    else Milvus 实现
        Client->>Client: _create_collection(name, dimension)
        Client->>DB: client.insert(collection_name, entities)
    else Pinecone 实现
        Client->>Client: _create_points(items, collection_name_with_prefix)
        Client->>DB: index.upsert(vectors=points)
    else Qdrant 实现
        Client->>Client: _create_collection_if_not_exists(collection_name, dimension)
        Client->>Client: _create_points(items)
        Client->>DB: client.upsert(collection_name_with_prefix, points)
    else Oracle23ai 实现
        Client->>Client: _initialize_database(connection)
        Client->>DB: INSERT INTO {table_name} (id, vector, text, metadata)
    end

    Client-->>App: 成功/失败

图：向量插入的内部数据流

来源：

• backend/open_webui/retrieval/vector/dbs/pgvector.py:207-238
• backend/open_webui/retrieval/vector/dbs/milvus.py:228-258
• backend/open_webui/retrieval/vector/dbs/pinecone.py:196-235
• backend/open_webui/retrieval/vector/dbs/qdrant.py:207-212
• backend/open_webui/retrieval/vector/dbs/oracle23ai.py:300-329

---

多租户实现

Open WebUI 为 Qdrant 和 Milvus 提供了专门的多租户客户端。这些实现从"每个文件一个集合"转变为由租户或资源 ID 分区的共享集合。

Qdrant 多租户

qdrant_multitenancy.py 中的 QdrantClient 将传统的集合名称映射到五个主要的共享集合 backend/open_webui/retrieval/vector/dbs/qdrant_multitenancy.py:83-87：

• MEMORY_COLLECTION（{prefix}_memories）
• KNOWLEDGE_COLLECTION（{prefix}_knowledge）
• FILE_COLLECTION（{prefix}_files）
• WEB_SEARCH_COLLECTION（{prefix}_web-search）
• HASH_BASED_COLLECTION（{prefix}_hash-based）

它使用 TENANT_ID_FIELD（从原始 collection_name 映射而来）执行带过滤条件的搜索 backend/open_webui/retrieval/vector/dbs/qdrant_multitenancy.py:98-132。

Milvus 多租户

与 Qdrant 类似，milvus_multitenancy.py 中的 MilvusClient 使用 RESOURCE_ID_FIELD 和共享集合前缀。查询通过布尔表达式 resource_id == '{resource_id}' 进行限制。

来源：

• backend/open_webui/retrieval/vector/dbs/qdrant_multitenancy.py:83-132
• backend/open_webui/retrieval/vector/dbs/milvus_multitenancy.py:36-88

---

各提供商的实现细节

PGVector（PostgreSQL）

• 加密：支持使用 PGCrypto 加密 text 和 vmetadata 列 backend/open_webui/retrieval/vector/dbs/pgvector.py:80-85。
• 索引：支持 hnsw（带有 m 和 ef_construction 参数）或 ivfflat backend/open_webui/retrieval/vector/dbs/pgvector.py:182-202。
• Halfvec：如果启用了 PGVECTOR_USE_HALFVEC，可以使用 halfvec 类型来减少存储空间 backend/open_webui/retrieval/vector/dbs/pgvector.py:52-58。
• 连接池：可通过 PGVECTOR_POOL_SIZE、PGVECTOR_POOL_MAX_OVERFLOW 等配置 backend/open_webui/retrieval/vector/dbs/pgvector.py:96-113。

Pinecone

• 重试：实现了 _retry_pinecone_operation，使用指数退避处理速率限制和网络问题 backend/open_webui/retrieval/vector/dbs/pinecone.py:130-166。
• 批处理：操作使用默认的 BATCH_SIZE 为 100 backend/open_webui/retrieval/vector/dbs/pinecone.py:41。
• gRPC：如果可用，优先使用 PineconeGRPC 以获得更好的性能 backend/open_webui/retrieval/vector/dbs/pinecone.py:62-71。

S3Vector

• 元数据约束：S3 Vector API 将元数据限制为 10 个键。客户端实现了 _filter_metadata 来优先处理重要键 backend/open_webui/retrieval/vector/dbs/s3vector.py:81-123。
• 索引创建：在 insert 操作期间，如果索引不存在，则自动创建索引 backend/open_webui/retrieval/vector/dbs/s3vector.py:157-164。

Oracle 23ai

• 连接管理：具有 start_health_monitor 线程，定期验证连接池 backend/open_webui/retrieval/vector/dbs/oracle23ai.py:167-188。
• 钱包支持：支持基于钱包的 Oracle Autonomous Database（ADB）身份验证 backend/open_webui/retrieval/vector/dbs/oracle23ai.py:108-126。

来源：

• backend/open_webui/retrieval/vector/dbs/pgvector.py:80-202
• backend/open_webui/retrieval/vector/dbs/pinecone.py:41-166
• backend/open_webui/retrieval/vector/dbs/s3vector.py:81-164
• backend/open_webui/retrieval/vector/dbs/oracle23ai.py:108-188