agentic_huge_data_base / wiki
页面 LightRAG · 3.2 关系型数据库实现·DeepWiki 中文全文译文
DeepWiki 中文译文 / LightRAG / 3.2

3.2 · 关系型数据库实现（Relational Database Implementations）

轻量图谱增强检索 · 聚焦本章的模块关系、源码依据与实现要点。

项目LightRAG 章节3.2 状态全文译文 模块存储与持久化、图谱与关系、测试、发布与运维、检索、召回与索引
项目要点页2.5 参考项目 项目章节目录LightRAG DeepWiki 原始章节Relational Database Implementations 上一章3.1 下一章3.3
源码线索
  • lightrag/kg/json_doc_status_impl.py
  • lightrag/kg/json_kv_impl.py
  • lightrag/kg/mongo_impl.py
  • lightrag/kg/postgres_impl.py
  • lightrag/kg/redis_impl.py
  • tests/test_dimension_mismatch.py
  • tests/test_no_model_suffix_safety.py
  • tests/test_postgres_age_quote_fix.py
  • tests/test_postgres_client_manager.py
  • tests/test_postgres_cypher_injection.py
模块标签
  • 存储与持久化
  • 图谱与关系
  • 测试、发布与运维
  • 检索、召回与索引
  • 界面与交互

章节正文

嵌入绑定与非对称嵌入

原始 DeepWiki 页面https://deepwiki.com/HKUDS/LightRAG/3.2-embedding-bindings-and-asymmetric-embedding

嵌入绑定与非对称嵌入

相关源文件

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

  • docs/AsymmetricEmbedding.md
  • lightrag/llm/anthropic.py
  • lightrag/llm/azure_openai.py
  • lightrag/llm/bedrock.py
  • lightrag/llm/binding_options.py
  • lightrag/llm/gemini.py
  • lightrag/llm/hf.py
  • lightrag/llm/jina.py
  • lightrag/llm/llama_index_impl.py
  • lightrag/llm/lmdeploy.py
  • lightrag/llm/lollms.py
  • lightrag/llm/nvidia_openai.py
  • lightrag/llm/ollama.py
  • lightrag/llm/openai.py
  • lightrag/llm/voyageai.py
  • tests/test_asymmetric_embedding.py
  • tests/test_token_auto_renewal.py
  • tests/test_voyageai_embed.py

LightRAG 提供了一套灵活的嵌入层，支持包括 OpenAI、Jina AI、VoyageAI、Gemini 和 HuggingFace 在内的多个提供商。该层专为满足检索增强生成（RAG）系统的特定需求而设计，例如非对称嵌入（对查询和文档采用不同的处理方式）以及维度缩减。

嵌入提供商架构

嵌入系统基于函数式接口构建，通过对特定提供商的实现进行封装，确保元数据和行为的一致性。

wrap_embedding_func_with_attrs 装饰器

lightrag/utils.py 中的 wrap_embedding_func_with_attrs 装饰器是绑定嵌入函数的核心机制。它会将关键元数据附加到函数上，RAG 引擎利用这些元数据来验证与向量存储的兼容性。

该装饰器管理的关键属性包括：

  • embedding_dim：输出向量的大小（例如 OpenAI text-embedding-3-small 的 1536）。
  • max_token_size：模型的最大上下文窗口。
  • model_name：底层模型的标识符。
  • supports_asymmetric：布尔标志，指示模型是否支持对查询和文档使用不同的任务。
提供商实现
提供商实现文件关键特性
OpenAIlightrag/llm/openai.py:1-664支持 Base64 编码以提高效率，text-embedding-3 维度缩减。
Jina AIlightrag/llm/jina.py:1-182原生支持 task 类型（retrieval.query/retrieval.passage）。
VoyageAIlightrag/llm/voyageai.py:1-100专为检索场景设计，支持 query 和 document 输入类型。
Geminilightrag/llm/gemini.py:1-400通过 google-genai 客户端集成。
HuggingFacelightrag/llm/hf.py:1-213本地执行，支持设备检测（CUDA/MPS/CPU）。

来源： lightrag/llm/openai.py、lightrag/llm/jina.py、lightrag/llm/hf.py、lightrag/llm/gemini.py、lightrag/utils.py。

非对称嵌入

非对称嵌入是指对"查询"（用户的问题）和"文档"（被索引的知识）使用不同的转换或前缀的做法。通过为搜索任务对齐向量空间，这可以提高检索的准确性。

实现逻辑

当装饰器中设置 supports_asymmetric=True 时，嵌入函数会接收一个 context 参数（值为 "query" 或 "document"）。

  1. Jina AI 逻辑：将 context="query" 映射为 task="retrieval.query"，将 context="document" 映射为 task="retrieval.passage" lightrag/llm/jina.py:132-138。
  2. HuggingFace 逻辑：根据 context 值，在输入字符串前添加 query_prefix 或 document_prefix lightrag/llm/hf.py:210-213。
  3. VoyageAI 逻辑：将 input_type 参数直接传递给 API，值为 query 或 document lightrag/llm/voyageai.py:75-80。
数据流图：非对称嵌入

下图展示了 context 属性如何从 RAG 检索/索引逻辑流入特定的提供商绑定。

LightRAG · 数据流图：非对称嵌入 · 图 1
LightRAG · 数据流图：非对称嵌入 · 图 1

来源： lightrag/llm/jina.py:132-146、lightrag/llm/hf.py:209-213、lightrag/llm/voyageai.py:75-80。

维度处理与 send_dimensions

现代嵌入模型（如 OpenAI 的 text-embedding-3 系列或 Jina 的 v3/v4）支持"套娃嵌入"，允许用户请求比模型原生最大维度更小的向量维度，而不会显著损失准确性。

关键参数
  • embedding_dim：在装饰器中定义 lightrag/llm/jina.py:62。该值用于初始化向量数据库（例如 Milvus、Qdrant）。
  • send_dimensions：一个标志（主要用于 OpenAI），决定是否向 API 发送 dimensions 参数。某些使用 OpenAI 兼容 API 的第三方提供商不支持此参数，如果发送会抛出错误 lightrag/llm/openai.py:590-600。
OpenAI 绑定中的实现

在 lightrag/llm/openai.py 中，代码会检查 EMBEDDING_SEND_DIMENSIONS 环境变量。如果为 true，则会将 dimensions 参数传递给 client.embeddings.create 调用 lightrag/llm/openai.py:630-640。

来源： lightrag/llm/openai.py:95-99、lightrag/llm/openai.py:625-645、lightrag/llm/jina.py:143。

系统集成图

下图将高级嵌入请求与实现中使用的特定代码实体和装饰器连接起来。

LightRAG · 系统集成图 · 图 2
LightRAG · 系统集成图 · 图 2

来源： lightrag/utils.py:27-30、lightrag/llm/openai.py:615-650、lightrag/llm/jina.py:75-110。

配置总结

环境变量作用
EMBEDDING_USE_BASE64启用 OpenAI 嵌入的 Base64 传输，以减少载荷大小 lightrag/llm/openai.py:95。
EMBEDDING_SEND_DIMENSIONS控制是否向 OpenAI 兼容 API 发送 dimensions 参数 lightrag/llm/openai.py:625。
JINA_API_KEYJina AI 嵌入所需的 API 密钥 lightrag/llm/jina.py:122。
VOYAGE_API_KEYVoyageAI 嵌入所需的 API 密钥 lightrag/llm/voyageai.py:60。

来源： lightrag/llm/openai.py、lightrag/llm/jina.py、lightrag/llm/voyageai.py。