7.4 · 嵌入向量生成（Embedding Generation）

嵌入向量生成（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/7.4-embedding-generation

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

翻译模型：deepseek-chat

原文字符数：11859

项目：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/routers/memories.py
• backend/open_webui/routers/ollama.py
• backend/open_webui/routers/openai.py
• backend/open_webui/routers/retrieval.py
• backend/open_webui/utils/embeddings.py
• backend/open_webui/utils/misc.py
• backend/open_webui/utils/payload.py
• backend/open_webui/utils/response.py
• src/lib/apis/retrieval/index.ts
• src/lib/components/admin/Settings/Documents.svelte
• src/lib/components/admin/Settings/WebSearch.svelte

本文档介绍 Open WebUI RAG 流水线中的嵌入生成与向量存储子系统。内容涵盖嵌入引擎（本地、Ollama、OpenAI、Azure、Sentence Transformers）、嵌入模型、向量数据库选项以及将它们整合在一起的配置系统。

关于嵌入前的文档处理，请参阅文档处理流水线。关于使用这些嵌入的检索策略，请参阅检索与重排序。

系统架构

嵌入与向量存储系统由三个主要层级组成：嵌入生成层、向量存储层和配置管理层。系统支持多种嵌入引擎和多个向量数据库后端。

嵌入与存储流程

graph TB
    subgraph "文档输入"
        Docs["文档分块<br/>（来自文本分割器）"]
    end

    subgraph "嵌入生成层"
        EmbeddingEngine["get_embedding_function()<br/>open_webui/retrieval/utils.py"]

        LocalEF["SentenceTransformer<br/>本地模型"]
        OllamaEF["Ollama API<br/>嵌入端点"]
        OpenAIEF["OpenAI API<br/>text-embedding-*"]
        AzureEF["Azure OpenAI<br/>嵌入部署"]

        EmbeddingEngine --> LocalEF
        EmbeddingEngine --> OllamaEF
        EmbeddingEngine --> OpenAIEF
        EmbeddingEngine --> AzureEF
    end

    subgraph "main.py 中的嵌入函数"
        EF["app.state.ef<br/>（SentenceTransformer）"]
        EMBEDDING_FUNCTION["app.state.EMBEDDING_FUNCTION<br/>（可调用包装器）"]

        EF --> EMBEDDING_FUNCTION
    end

    subgraph "向量存储层"
        VectorClient["VECTOR_DB_CLIENT<br/>open_webui/retrieval/vector/factory.py"]

        Chroma["ChromaDB"]
        Qdrant["Qdrant"]
        Milvus["Milvus"]
        Pinecone["Pinecone"]
        OpenSearch["OpenSearch"]
        Elastic["Elasticsearch"]

        VectorClient --> Chroma
        VectorClient --> Qdrant
        VectorClient --> Milvus
        VectorClient --> Pinecone
        VectorClient --> OpenSearch
        VectorClient --> Elastic
    end

    subgraph "配置"
        Config["app.state.config<br/>RAG_EMBEDDING_ENGINE<br/>RAG_EMBEDDING_MODEL<br/>VECTOR_DB"]
    end

    Docs --> EMBEDDING_FUNCTION
    EMBEDDING_FUNCTION --> VectorClient
    Config -.->|配置| EmbeddingEngine
    Config -.->|配置| VectorClient

来源：backend/open_webui/retrieval/utils.py:84-95、backend/open_webui/retrieval/vector/factory.py:47-47、backend/open_webui/config.py:22-22

嵌入引擎与模型

嵌入引擎配置

Open WebUI 支持多种嵌入引擎，通过 RAG_EMBEDDING_ENGINE 进行配置。该配置由 PersistentConfig 系统管理，确保设置在重启后仍然持久化。

引擎	值	描述	所需配置
本地	""（空字符串）	本地运行的 SentenceTransformer 模型	模型名称/路径
Ollama	"ollama"	Ollama 嵌入 API	OLLAMA_BASE_URL、OLLAMA_API_KEY
OpenAI	"openai"	OpenAI 嵌入 API	OPENAI_API_BASE_URL、OPENAI_API_KEY
Azure OpenAI	"azure_openai"	Azure OpenAI 部署	AZURE_OPENAI_BASE_URL、AZURE_OPENAI_API_KEY

来源：backend/open_webui/routers/retrieval.py:145-155、src/lib/components/admin/Settings/Documents.svelte:41-45

本地嵌入初始化

backend/open_webui/routers/retrieval.py 中的 get_ef() 函数使用 sentence-transformers 库初始化本地嵌入模型。

graph LR
    subgraph "get_ef() - open_webui/routers/retrieval.py"
        Input["engine: str<br/>embedding_model: str<br/>auto_update: bool"]
        Check{{"engine == '' ?"}}

        GetModel["get_model_path()<br/>（按需自动下载）"]
        CreateST["SentenceTransformer()<br/>device=DEVICE_TYPE<br/>trust_remote_code<br/>backend<br/>model_kwargs"]

        EF["ef: SentenceTransformer<br/>或 None"]
    end

    subgraph "模型存储"
        HF["HuggingFace Hub"]
        Cache["本地缓存<br/>CACHE_DIR"]
    end

    Input --> Check
    Check -->|是| GetModel
    Check -->|否| EF
    GetModel --> CreateST
    CreateST --> EF

    GetModel -.->|按需下载| HF
    HF -.-> Cache
    Cache -.-> GetModel

• 使用 SentenceTransformer 进行本地推理 backend/open_webui/routers/retrieval.py:146-149。
• 通过 DEVICE_TYPE 配置硬件加速 backend/open_webui/routers/retrieval.py:151。
• 支持 RAG_EMBEDDING_MODEL_TRUST_REMOTE_CODE 以加载自定义模型架构 backend/open_webui/routers/retrieval.py:152。
• 通过 SENTENCE_TRANSFORMERS_BACKEND 允许指定特定后端 backend/open_webui/routers/retrieval.py:153。

来源：backend/open_webui/routers/retrieval.py:139-160、backend/open_webui/env.py:116-119

嵌入前缀

系统支持前缀注入，通过区分查询上下文和文档上下文来提高检索质量：

前缀类型	配置变量	用途
查询前缀	RAG_EMBEDDING_QUERY_PREFIX	添加到搜索查询 backend/open_webui/config.py:113-113
内容前缀	RAG_EMBEDDING_CONTENT_PREFIX	在索引期间添加到文档分块 backend/open_webui/config.py:112-112

来源：backend/open_webui/config.py:112-114、backend/open_webui/retrieval/utils.py:50-54

向量数据库集成

向量数据库工厂

向量数据库客户端通过工厂模式初始化为单例。VECTOR_DB_CLIENT（及其异步对应 ASYNC_VECTOR_DB_CLIENT）为 upsert、search 和 delete 等操作提供标准化 API。

graph TB
    subgraph "工厂模式 - open_webui/retrieval/vector/factory.py"
        VectorDB["VECTOR_DB 配置<br/>（来自环境变量/配置）"]
        Factory["VECTOR_DB_CLIENT"]

        VectorDB --> Factory
    end

    subgraph "向量数据库实现"
        Chroma["ChromaDB"]
        Qdrant["Qdrant"]
        Milvus["Milvus"]
        Pinecone["Pinecone"]
        OpenSearch["OpenSearch"]
        Elastic["Elasticsearch"]

        Factory --> Chroma
        Factory --> Qdrant
        Factory --> Milvus
        Factory --> Pinecone
        Factory --> OpenSearch
        Factory --> Elastic
    end

来源：backend/open_webui/retrieval/vector/factory.py:47-47、backend/open_webui/retrieval/vector/async_client.py:48-48

用户记忆嵌入

除了文档 RAG 之外，嵌入系统还为"记忆"功能提供支持。当添加一条记忆时，它会使用全局的 EMBEDDING_FUNCTION 进行嵌入，并存储在特定于用户的向量集合中。

• 存储：记忆存储在名为 user-memory-{user.id} 的集合中 backend/open_webui/routers/memories.py:89-89。
• 查询：用户查询会被嵌入并与这些集合进行搜索，以提供长期上下文 backend/open_webui/routers/memories.py:141-145。

来源：backend/open_webui/routers/memories.py:84-98、backend/open_webui/routers/memories.py:135-145

重排序模型

重排序函数初始化

graph TB
    subgraph "get_rf() - open_webui/routers/retrieval.py"
        Input["engine: str<br/>reranking_model: str<br/>external_url: str<br/>external_api_key: str<br/>auto_update: bool"]

        CheckModel{{"reranking_model<br/>是否提供？"}}

        CheckColBERT{{"包含<br/>'jinaai/jina-colbert-v2'？"}}

        CheckExternal{{"engine == 'external'？"}}

        CreateColBERT["ColBERT()"]
        CreateExternal["ExternalReranker()"]
        CreateCrossEncoder["CrossEncoder()"]

        RF["rf: ColBERT | ExternalReranker |<br/>CrossEncoder | None"]
    end

    Input --> CheckModel
    CheckModel -->|否| RF
    CheckModel -->|是| CheckColBERT
    CheckColBERT -->|是| CreateColBERT
    CheckColBERT -->|否| CheckExternal
    CheckExternal -->|是| CreateExternal
    CheckExternal -->|否| CreateCrossEncoder

    CreateColBERT --> RF
    CreateExternal --> RF
    CreateCrossEncoder --> RF

重排序函数 get_rf 支持三种主要后端：

1. ColBERT：专门的多向量重排序，用于高精度 backend/open_webui/routers/retrieval.py:174-181。
2. 外部重排序器：与外部 API（例如 Jina、Cohere）集成 backend/open_webui/routers/retrieval.py:187-199。
3. CrossEncoder：使用 sentence_transformers.CrossEncoder 进行本地重排序 backend/open_webui/routers/retrieval.py:205-208。

来源：backend/open_webui/routers/retrieval.py:162-208

配置与管理

管理设置界面

嵌入配置通过管理面板暴露。Documents.svelte 组件管理嵌入引擎和模型更新的状态。

• 验证：确保为云提供商（OpenAI、Azure）提供了必需的密钥和 URL src/lib/components/admin/Settings/Documents.svelte:87-102。
• 更新逻辑：调用 updateEmbeddingConfig 将前端状态与后端 PersistentConfig 同步 src/lib/components/admin/Settings/Documents.svelte:113-132。

来源：src/lib/components/admin/Settings/Documents.svelte:41-58、src/lib/components/admin/Settings/Documents.svelte:69-142

标准化与使用跟踪

来自不同提供商（Ollama、OpenAI）的嵌入响应会被标准化为统一格式，以确保一致的使用跟踪和日志记录。

• Ollama 转 OpenAI：convert_embedding_response_ollama_to_openai 函数将 Ollama 的响应格式转换为 OpenAI 兼容的列表格式 backend/open_webui/utils/response.py:177-200。
• 使用量标准化：令牌计数（输入、输出、总计）在各提供商之间实现标准化 backend/open_webui/utils/response.py:11-49。

来源：backend/open_webui/utils/response.py:11-49、backend/open_webui/utils/response.py:177-200