6.4 · 嵌入配置（Embeddings Configuration）

嵌入配置

嵌入向量配置

相关源文件

本章引用的主要源码文件：

• docs/components/embedders/config.mdx
• docs/components/embedders/overview.mdx
• docs/components/llms/config.mdx
• docs/components/llms/overview.mdx
• mem0-ts/src/oss/src/embeddings/ollama.ts
• mem0-ts/src/oss/src/llms/ollama.ts
• mem0-ts/src/oss/tests/ollama-embedder.test.ts
• mem0/configs/embeddings/base.py
• mem0/configs/llms/base.py
• mem0/embeddings/base.py
• mem0/embeddings/configs.py
• mem0/embeddings/gemini.py
• mem0/embeddings/huggingface.py
• mem0/embeddings/ollama.py
• mem0/embeddings/openai.py
• mem0/llms/configs.py
• mem0/llms/gemini.py
• mem0/llms/xai.py
• tests/embeddings/test_huggingface_embeddings.py
• tests/embeddings/test_ollama_embeddings.py
• tests/embeddings/test_openai_embeddings.py

本文档介绍 Mem0 中嵌入向量模型的配置选项，重点讲解 BaseEmbedderConfig 类和特定于提供商的参数。有关可用嵌入向量提供商和 EmbeddingBase 接口的信息，请参阅嵌入向量提供商。有关大语言模型（LLM）的配置，请参阅大语言模型（LLM）配置。

概述

Mem0 中的嵌入向量配置通过 BaseEmbedderConfig 类进行管理，该类为所有嵌入向量提供商提供了统一的配置接口。配置系统支持 11 个以上的嵌入向量提供商，并提供了特定于提供商的参数，同时保持了 API 表面的一致性。

配置通过 EmbeddingBase 构造函数传递给嵌入向量实现，并决定了模型选择、API 认证、嵌入向量维度和特定于提供商的行为。

来源： mem0/configs/embeddings/base.py:10-111, mem0/embeddings/base.py:1-32

BaseEmbedderConfig 类

配置类图

来源： mem0/configs/embeddings/base.py:10-111, mem0/embeddings/base.py:7-32, mem0/embeddings/openai.py:11-35, mem0/embeddings/huggingface.py:15-28, mem0/embeddings/ollama.py:24-32, mem0/embeddings/gemini.py:11-20

构造函数参数

BaseEmbedderConfig 构造函数使用以下参数初始化配置实例：

来源： mem0/configs/embeddings/base.py:15-110

通用配置参数

模型选择

如果初始化时 model 参数为 None，各提供商将分配默认模型：

# OpenAI 默认值 [mem0/embeddings/openai.py:15]
self.config.model = self.config.model or "text-embedding-3-small"

# HuggingFace 默认值（本地） [mem0/embeddings/huggingface.py:23]
self.config.model = self.config.model or "multi-qa-MiniLM-L6-cos-v1"

# Ollama 默认值 [mem0/embeddings/ollama.py:28]
self.config.model = self.config.model or "nomic-embed-text"

# Gemini 默认值 [mem0/embeddings/gemini.py:15]
self.config.model = self.config.model or "models/gemini-embedding-001"

来源： mem0/embeddings/openai.py:15-15, mem0/embeddings/huggingface.py:23-23, mem0/embeddings/ollama.py:28-28, mem0/embeddings/gemini.py:15-15

API 密钥管理

API 密钥按以下优先级解析：

1. BaseEmbedderConfig 中显式设置的 api_key
2. 环境变量（例如 OPENAI_API_KEY、GOOGLE_API_KEY、AWS_REGION）

来源： mem0/embeddings/openai.py:21-21, mem0/embeddings/gemini.py:18-18, mem0/configs/embeddings/base.py:109-109

嵌入向量维度

embedding_dims 参数控制向量大小。不同提供商的实现方式各异：

• OpenAI：如果用户设置了该参数，则将 dimensions 传递给 API。默认值为 1536 mem0/embeddings/openai.py:18-19。
• HuggingFace：如果未指定，则从 model.get_sentence_embedding_dimension() 自动检测 mem0/embeddings/huggingface.py:27。
• Gemini：如果提供了 output_dimensionality 则使用该值，否则默认值为 768 mem0/embeddings/gemini.py:16。
• Ollama：默认值为 512 mem0/embeddings/ollama.py:29。

来源： mem0/embeddings/openai.py:18-19, mem0/embeddings/huggingface.py:27-27, mem0/embeddings/gemini.py:16-16, mem0/embeddings/ollama.py:29-29

配置流程

从配置到提供商实例化

来源： mem0/embeddings/configs.py:6-32, mem0/embeddings/base.py:14-18, mem0/embeddings/openai.py:12-35, mem0/embeddings/huggingface.py:16-28

特定于提供商的配置

OpenAI 配置

OpenAI 嵌入向量支持自定义基础 URL 和批量处理。

• openai_base_url：从配置中解析，然后检查 OPENAI_API_BASE（已废弃），再检查 OPENAI_BASE_URL，默认值为 "https://api.openai.com/v1" mem0/embeddings/openai.py:22-27。
• 批处理：embed_batch 自动将输入分块为每批 100 个，以保持在 API 限制范围内 mem0/embeddings/openai.py:62。
• Matryoshka 支持：仅当在配置中显式设置了 embedding_dims 时，dimensions 参数才会传递给 API mem0/embeddings/openai.py:18。

来源： mem0/embeddings/openai.py:11-77

HuggingFace 配置

支持两种操作模式：

1. 远程模式：使用 huggingface_base_url 通过 OpenAI 客户端连接到文本嵌入向量推理（TEI）端点 mem0/embeddings/huggingface.py:19-21。
2. 本地模式：使用 SentenceTransformer 在本地加载模型 mem0/embeddings/huggingface.py:25。

来源： mem0/embeddings/huggingface.py:15-44

Ollama 配置

Ollama 实现确保模型在使用前已存在于本地：

• ollama_base_url：作为 host 传递给 ollama.Client mem0/embeddings/ollama.py:31。
• 自动拉取：_ensure_model_exists() 检查本地模型列表，如果模型缺失则拉取该模型 mem0/embeddings/ollama.py:38-49。

来源： mem0/embeddings/ollama.py:24-66

Gemini 配置

Gemini 嵌入向量使用 google-genai SDK：

• output_dimensionality：映射到 types.EmbedContentConfig mem0/embeddings/gemini.py:34。
• 默认模型：models/gemini-embedding-001 mem0/embeddings/gemini.py:15。

来源： mem0/embeddings/gemini.py:11-39

任务特定嵌入向量

Mem0 支持针对不同记忆操作的任务特定嵌入向量类型。这对于 Vertex AI 等区分检索和存储任务的提供商特别有用。

• memory_add_embedding_type：添加记忆时使用。
• memory_update_embedding_type：更新记忆时使用。
• memory_search_embedding_type：搜索记忆时使用。

embed 函数签名包含一个 memory_action 参数以支持此逻辑： def embed(self, text, memory_action: Optional[Literal["add", "search", "update"]] = None) mem0/embeddings/base.py:21。

来源： mem0/configs/embeddings/base.py:32-34, 96-98, mem0/embeddings/base.py:21-31

校验与 Pydantic 模式

EmbedderConfig 类使用 Pydantic 的 field_validator 为嵌入向量提供商提供高级别校验：

class EmbedderConfig(BaseModel):
    provider: str = Field(
        description="嵌入向量模型的提供商（例如 'ollama'、'openai'）",
        default="openai",
    )
    config: Optional[dict] = Field(description="特定嵌入向量模型的配置", default={})

    @field_validator("config")
    def validate_config(cls, v, values):
        provider = values.data.get("provider")
        if provider in [
            "openai", "ollama", "huggingface", "azure_openai", "gemini",
            "vertexai", "together", "lmstudio", "langchain", "aws_bedrock", "fastembed",
        ]:
            return v
        else:
            raise ValueError(f"不支持的嵌入向量提供商：{provider}")

来源： mem0/embeddings/configs.py:6-32