LightRAG 非对称嵌入Asymmetric Embedding配置完全指南模型选择、前缀与 Provider 任务参数【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG导读本文以 LightRAG 官方文档 docs/AsymmetricEmbedding.md 为核心系统讲解如何在 LightRAG 中按模型特性配置查询query与文档document分离的非对称嵌入模式。你将掌握EMBEDDING_ASYMMETRIC、EMBEDDING_QUERY_PREFIX、EMBEDDING_DOCUMENT_PREFIX、NO_PREFIX哨兵值的完整语义与校验规则理解Provider 任务参数与文本前缀两种非对称实现路径的适用模型并学会在切换配置后安全地重建向量库索引。文末结合lightrag/api/config.py、lightrag/api/lightrag_server.py与单元测试给出源码级佐证帮助你判断自己的嵌入模型到底该用哪种模式。默认行为LightRAG 默认保持对称嵌入LightRAG 在默认情况下使用对称嵌入——即查询与文档走完全相同的嵌入输入形式。非对称嵌入只有在显式设置EMBEDDING_ASYMMETRICtrue时才会被启用。这一点之所以被设计为显式 opt-in是为了避免一类隐蔽的事故当环境中残留了EMBEDDING_QUERY_PREFIX、EMBEDDING_DOCUMENT_PREFIX等前缀变量但用户实际上并未有意开启非对称嵌入时检索行为不应被这些遗留变量静默改变。从源码可以看到这一开关的读取发生在 lightrag/api/config.pyargs.embedding_asymmetric_configured EMBEDDING_ASYMMETRIC in os.environ args.embedding_asymmetric get_env_value(EMBEDDING_ASYMMETRIC, False, bool)系统会单独记录该变量是否出现在环境中从而在日志和校验中区分未设置与显式设为 false两种状态。一个重要的前置判断不要从 API Binding 推断模型行为在决定是否开启非对称嵌入之前务必先查阅所选模型的 model card 或服务商文档。不要仅凭 API 形状API binding做推断一个openai兼容端点背后可能托管的是无指令模型instruction-free、前缀型模型如 BGE/E5/GTE也可能是供应商特有的任务参数型模型。同样是 OpenAI 兼容接口真实行为可能完全不同。两类非对称实现风格Binding TypesLightRAG 将支持非对称嵌入的绑定明确区分为两种风格二者互斥风格绑定点Bindings非对称行为如何生效Provider 任务参数Provider task parametersjina、gemini、voyageaiLightRAG 根据 query/document 上下文向供应商特有的task、task_type或input_type参数传递检索意图。文本任务前缀Text task prefixesopenai、azure_openai、ollamaLightRAG 在调用嵌入 API 之前把配置好的文本前缀拼接到输入前面。仅当模型卡明确要求区分 query/document 前缀时才应使用。其他服务端嵌入绑定点如bedrock、lollms等目前不支持EMBEDDING_ASYMMETRICtrue一旦设置会直接触发启动校验错误。这两个绑定集合在源码中定义得非常直观见 lightrag/api/config.pyNO_PREFIX_SENTINEL NO_PREFIX PROVIDER_ASYMMETRIC_EMBEDDING_BINDINGS {gemini, jina, voyageai} PREFIX_ASYMMETRIC_EMBEDDING_BINDINGS {azure_openai, ollama, openai}默认的对称模式前缀被忽略并告警当EMBEDDING_ASYMMETRIC未设置时LightRAG 不启用任何非对称行为即使前缀变量存在也一样# EMBEDDING_ASYMMETRIC is unset # EMBEDDING_QUERY_PREFIXsearch_query: # EMBEDDING_DOCUMENT_PREFIXsearch_document: 此时前缀会被忽略并在日志中输出一条警告。显式设为false效果相同EMBEDDING_ASYMMETRICfalse对应校验函数resolve_asymmetric_embedding_opt_in()中lightrag/api/config.pyif not embedding_asymmetric: if has_prefix_config: state false if embedding_asymmetric_configured else unset logger.warning( fEMBEDDING_ASYMMETRIC is {state}; EMBEDDING_QUERY_PREFIX and EMBEDDING_DOCUMENT_PREFIX will be ignored. ) return False无指令模型请保持对称模式部分嵌入模型是无指令型instruction-free业界也称其使用隐式意图implicit intent——它们直接从原始文本本身学习如何匹配查询与文档既不需要 query/document 前缀也不需要 Provider 的任务参数。对这类模型不要设置EMBEDDING_ASYMMETRICtrue保持不设置或显式false同时也不要配置EMBEDDING_QUERY_PREFIX与EMBEDDING_DOCUMENT_PREFIX。文档给出的常见应保持对称的模型族模型族示例模型 ID说明BGE-M3BAAI/bge-m3使用纯文本输入。除非所使用部署封装serving wrapper的模型卡另有说明不要自行添加search_query:/search_document:。OpenAI Text Embedding 3text-embedding-3-small、text-embedding-3-largeOpenAI embeddings API 只接受文本输入加模型名不暴露 query/document 任务参数。Mistral Embedmistral-embed使用服务商提供的普通嵌入输入不要臆造任务前缀。阿里 GTE base 模型gte-large、gte-large-zh基础 GTE 模型常规检索用纯文本。不适用于新的instruct变体如gte-Qwen2-1.5B-instruct请核对对应模型卡。Jina Embeddings v2jina-embeddings-v2-base-en、jina-embeddings-v2-base-zhJina v2 为纯文本输入Jina v3/v4 则不同检索任务需使用task参数。给无指令模型强行开启 LightRAG 的非对称模式会让输入形态偏离模型训练/文档声明所预期的样子。即使服务能正常启动检索质量也可能下降——这类问题尤其隐蔽因为启动成功并不等于行为正确。Provider 任务参数型绑定Jina / Gemini / VoyageAI这种模式适用于服务商在 API 层暴露了独立的 query/document 嵌入任务的情况。对这类绑定不要配置前缀变量。Jina 示例EMBEDDING_BINDINGjina EMBEDDING_ASYMMETRICtrue EMBEDDING_MODELjina-embeddings-v4Gemini 示例EMBEDDING_BINDINGgemini EMBEDDING_ASYMMETRICtrue EMBEDDING_MODELgemini-embedding-001VoyageAI 示例EMBEDDING_BINDINGvoyageai EMBEDDING_ASYMMETRICtrue EMBEDDING_MODELvoyage-3如果在这种绑定下还额外配置了EMBEDDING_QUERY_PREFIX或EMBEDDING_DOCUMENT_PREFIXLightRAG 会记录警告并忽略前缀见 lightrag/api/config.py 中对 Provider 绑定 前缀同时出现时的分支处理。源码中的实现证据在 lightrag/api/lightrag_server.py 中服务端按 binding 分发并决定传入哪些参数Jinalightrag/llm/jina.py 对应封装非对称开启时传入context并显式把task置为None由嵌入函数根据context自动选出retrieval.query/retrieval.passageGemini从绑定选项中读取task_type未显式指定时结合context映射为RETRIEVAL_QUERY/RETRIEVAL_DOCUMENTVoyageAI同样传入context由封装映射为 provider 的input_type。这些映射行为有专门的单元测试覆盖见 tests/llm/test_asymmetric_embedding.pytest_jina_default_task_is_query_when_context_query/test_jina_default_task_is_passage_when_context_document验证 Jina 在taskNone时按context自动生成retrieval.query/retrieval.passagetest_gemini_task_type_query_for_query_context/test_gemini_task_type_document_for_document_context验证 Gemini 映射出RETRIEVAL_QUERY/RETRIEVAL_DOCUMENT显式传入task/task_type时则覆盖上下文推断test_jina_explicit_task_overrides_context等。注意一个常见误区Jina v2 是纯文本模型前面已列入对称模型表而 Jina v3/v4 才使用task参数。因此 Provider 任务参数模式适用于jina-embeddings-v3/v4这类新模型切勿对 v2 使用。文本任务前缀型绑定OpenAI / Azure OpenAI / Ollama这种模式适用于模型本身期望在输入文本中携带任务指令的场景例如模型卡明确写明需要search_query:、search_document:、query:、passage:等前缀典型的如 BGE 系列、E5 系列。不要因为模型恰好是通过openai、azure_openai或ollama服务而盲目开启此模式。开启后两个前缀变量必须都显式配置EMBEDDING_ASYMMETRICtrue EMBEDDING_QUERY_PREFIXsearch_query: EMBEDDING_DOCUMENT_PREFIXsearch_document: 如果某一侧确实希望不加前缀使用哨兵值NO_PREFIXEMBEDDING_ASYMMETRICtrue EMBEDDING_QUERY_PREFIXsearch_query: EMBEDDING_DOCUMENT_PREFIXNO_PREFIXNO_PREFIX内部会被转换成空字符串。它与变量未设置不同它表示这一侧经过人工确认故意不加前缀。这也是get_embedding_prefix_config()的解析逻辑lightrag/api/config.py存在的意义——用显式哨兵把有意留空和误漏配置区分开。至少有一侧必须是非空前缀下面这种配置是无效的、启动即报错EMBEDDING_ASYMMETRICtrue EMBEDDING_QUERY_PREFIXNO_PREFIX EMBEDDING_DOCUMENT_PREFIXNO_PREFIX前缀如何被拼接到输入上前缀拼接发生在各 binding 的嵌入实现内。以 lightrag/llm/ollama.py 为例ollama_embed接收query_prefix与document_prefix并按context决定在整批文本前统一拼接if context query and query_prefix: texts [query_prefix text for text in texts] elif context document and document_prefix: texts [document_prefix text for text in texts]在服务端 lightrag/api/lightrag_server.py只有Provider 支持非对称 opt-in 通过双重条件满足时才把这些参数下发给底层函数否则维持纯对称的旧调用路径。前缀模式下前缀被忽略的情况还需注意一种易混淆场景前缀模式仅对openai/azure_openai/ollama生效若你在 Provider 任务参数型绑定jina/gemini/voyageai上配置了前缀变量两者同时出现时前缀同样会被忽略并告警因为 Provider 任务参数优先级更高、二者实现路径互斥。无效的空前缀不要用空的环境变量值来表达故意不加前缀EMBEDDING_DOCUMENT_PREFIX请改用NO_PREFIX。空值会被拒绝原因是 shell、.env与 Docker Compose 对空字符串的处理方式往往让空值与意外的配置缺失难以区分。如果允许空值一个被误清空的变量可能悄悄退化为另一种语义。从代码可见get_embedding_prefix_config()对空串直接抛错if value : raise ValueError( f{env_key} is empty. Use {NO_PREFIX_SENTINEL} to explicitly request no prefix, or remove the variable to leave it unconfigured. )校验规则速查表Validation Summary下表是 LightRAG 对非对称嵌入全部配置组合的最终判定结果可直接作为排障参考配置结果EMBEDDING_ASYMMETRIC未设置对称模式前缀被忽略并告警。EMBEDDING_ASYMMETRICfalse对称模式前缀被忽略并告警。无指令模型如BAAI/bge-m3、text-embedding-3-small、mistral-embed、基础 GTE、Jina v2保持对称模式除非模型卡要求否则不要配置前缀或 Provider 任务。EMBEDDING_ASYMMETRICtruejina/gemini/voyageaiProvider 任务参数模式前缀被忽略并告警。EMBEDDING_ASYMMETRICtrueopenai/azure_openai/ollama且两个前缀变量均已配置文本前缀模式。前缀模式下缺少某个前缀变量启动报错请填写真实前缀或NO_PREFIX。前缀模式下两侧都是NO_PREFIX启动报错不存在任何非对称行为。前缀变量被设为空值启动报错请改用NO_PREFIX。校验由谁执行所有上述判定集中在resolve_asymmetric_embedding_opt_in()这一个入口lightrag/api/config.py它对三种情况分别处理非对称开关关闭时告警并返回FalseProvider 任务型绑定直接放行前缀型绑定则要求双侧均显式配置且至少一侧非空否则抛出ValueError其余绑定一律拒绝。对应地服务端启动流程在 lightrag/api/lightrag_server.py 调用该函数并把结果写入最终EmbeddingFunc实例的supports_asymmetric标志见同文件 L1011供后续所有查询/入库路径使用。单测对每条规则都有断言例如test_asymmetric_opt_in_explicit_true_requires_both_prefix_settings缺前缀抛 requires both、test_asymmetric_opt_in_explicit_true_rejects_both_sides_no_prefix双侧NO_PREFIX抛 At least one、test_get_embedding_prefix_config_rejects_empty_env_value空值抛错可参考 tests/llm/test_asymmetric_embedding.py。配置变更后的重建索引要求Reindexing改变非对称嵌入配置会改变已存文档与未来查询所产生的向量本身。因此在启用、禁用或修改以下任一设置后都必须清空该工作区已有的 LightRAG 数据并重新对源文件建索引EMBEDDING_ASYMMETRICEMBEDDING_QUERY_PREFIXEMBEDDING_DOCUMENT_PREFIXProvider 任务行为类设置例如 Jina 的task、Gemini 的task_type、VoyageAI 的input_type不要把已建好的向量库直接复用在配置变更前后。混合使用不同 query/document 行为生成的向量会让检索质量变得不可预测。这一点与 examples/lightrag_gemini_workspace_demo.py 等示例所演示的工作区 重新插入文档流程一致——工作区级数据清理是最稳妥的重建粒度。即便是从一个合法非对称配置切到另一个合法非对称配置同样必须清理数据并重新索引。实战决策清单最后给出一个可直接照做的配置决策流程覆盖从模型确认到上线运行的全过程查模型卡确认目标嵌入模型是无指令型前缀型还是Provider 任务型openai兼容端点背后可能是任意一种不要想当然。无指令型BGE-M3、text-embedding-3-*、mistral-embed、GTE base、Jina v2 等保持EMBEDDING_ASYMMETRIC不设置或为false不设任何前缀变量。Provider 任务型Jina v3/v4、Gemini embedding、VoyageAI设置EMBEDDING_ASYMMETRICtrue与对应EMBEDDING_MODEL不加前缀变量如需固定task/task_type再在绑定选项中显式配置。前缀型BGE、E5 等EMBEDDING_ASYMMETRICtrue加两个前缀变量单侧有意留空用NO_PREFIX严禁空字符串严禁两侧全空。验证启动观察启动日志确认告警或错误与速查表预期一致。生效切换任何配置增删改之后清空工作区向量数据并重新插入源文档不要复用旧向量库。LightRAG 默认对称、显式开启非对称的设计本质上把检索行为是否改变的决策权交还给用户并用启动期校验把误配置挡在服务运行之前。理解文档 docs/AsymmetricEmbedding.md 中这两类风格与NO_PREFIX语义配合 env.example 中内嵌的注释模板其同样强调Jina/Gemini/VoyageAI 等 Provider 任务型绑定不应配置前缀变量而 BGE/E5/GTE 等前缀型模型需要两个前缀变量带尾随空格的取值需加引号包裹就能为任意嵌入后端选出唯一正确的配置组合。【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LightRAG 非对称嵌入（Asymmetric Embedding）配置完全指南：模型选择、前缀与 Provider 任务参数
LightRAG 非对称嵌入Asymmetric Embedding配置完全指南模型选择、前缀与 Provider 任务参数【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG导读本文以 LightRAG 官方文档 docs/AsymmetricEmbedding.md 为核心系统讲解如何在 LightRAG 中按模型特性配置查询query与文档document分离的非对称嵌入模式。你将掌握EMBEDDING_ASYMMETRIC、EMBEDDING_QUERY_PREFIX、EMBEDDING_DOCUMENT_PREFIX、NO_PREFIX哨兵值的完整语义与校验规则理解Provider 任务参数与文本前缀两种非对称实现路径的适用模型并学会在切换配置后安全地重建向量库索引。文末结合lightrag/api/config.py、lightrag/api/lightrag_server.py与单元测试给出源码级佐证帮助你判断自己的嵌入模型到底该用哪种模式。默认行为LightRAG 默认保持对称嵌入LightRAG 在默认情况下使用对称嵌入——即查询与文档走完全相同的嵌入输入形式。非对称嵌入只有在显式设置EMBEDDING_ASYMMETRICtrue时才会被启用。这一点之所以被设计为显式 opt-in是为了避免一类隐蔽的事故当环境中残留了EMBEDDING_QUERY_PREFIX、EMBEDDING_DOCUMENT_PREFIX等前缀变量但用户实际上并未有意开启非对称嵌入时检索行为不应被这些遗留变量静默改变。从源码可以看到这一开关的读取发生在 lightrag/api/config.pyargs.embedding_asymmetric_configured EMBEDDING_ASYMMETRIC in os.environ args.embedding_asymmetric get_env_value(EMBEDDING_ASYMMETRIC, False, bool)系统会单独记录该变量是否出现在环境中从而在日志和校验中区分未设置与显式设为 false两种状态。一个重要的前置判断不要从 API Binding 推断模型行为在决定是否开启非对称嵌入之前务必先查阅所选模型的 model card 或服务商文档。不要仅凭 API 形状API binding做推断一个openai兼容端点背后可能托管的是无指令模型instruction-free、前缀型模型如 BGE/E5/GTE也可能是供应商特有的任务参数型模型。同样是 OpenAI 兼容接口真实行为可能完全不同。两类非对称实现风格Binding TypesLightRAG 将支持非对称嵌入的绑定明确区分为两种风格二者互斥风格绑定点Bindings非对称行为如何生效Provider 任务参数Provider task parametersjina、gemini、voyageaiLightRAG 根据 query/document 上下文向供应商特有的task、task_type或input_type参数传递检索意图。文本任务前缀Text task prefixesopenai、azure_openai、ollamaLightRAG 在调用嵌入 API 之前把配置好的文本前缀拼接到输入前面。仅当模型卡明确要求区分 query/document 前缀时才应使用。其他服务端嵌入绑定点如bedrock、lollms等目前不支持EMBEDDING_ASYMMETRICtrue一旦设置会直接触发启动校验错误。这两个绑定集合在源码中定义得非常直观见 lightrag/api/config.pyNO_PREFIX_SENTINEL NO_PREFIX PROVIDER_ASYMMETRIC_EMBEDDING_BINDINGS {gemini, jina, voyageai} PREFIX_ASYMMETRIC_EMBEDDING_BINDINGS {azure_openai, ollama, openai}默认的对称模式前缀被忽略并告警当EMBEDDING_ASYMMETRIC未设置时LightRAG 不启用任何非对称行为即使前缀变量存在也一样# EMBEDDING_ASYMMETRIC is unset # EMBEDDING_QUERY_PREFIXsearch_query: # EMBEDDING_DOCUMENT_PREFIXsearch_document: 此时前缀会被忽略并在日志中输出一条警告。显式设为false效果相同EMBEDDING_ASYMMETRICfalse对应校验函数resolve_asymmetric_embedding_opt_in()中lightrag/api/config.pyif not embedding_asymmetric: if has_prefix_config: state false if embedding_asymmetric_configured else unset logger.warning( fEMBEDDING_ASYMMETRIC is {state}; EMBEDDING_QUERY_PREFIX and EMBEDDING_DOCUMENT_PREFIX will be ignored. ) return False无指令模型请保持对称模式部分嵌入模型是无指令型instruction-free业界也称其使用隐式意图implicit intent——它们直接从原始文本本身学习如何匹配查询与文档既不需要 query/document 前缀也不需要 Provider 的任务参数。对这类模型不要设置EMBEDDING_ASYMMETRICtrue保持不设置或显式false同时也不要配置EMBEDDING_QUERY_PREFIX与EMBEDDING_DOCUMENT_PREFIX。文档给出的常见应保持对称的模型族模型族示例模型 ID说明BGE-M3BAAI/bge-m3使用纯文本输入。除非所使用部署封装serving wrapper的模型卡另有说明不要自行添加search_query:/search_document:。OpenAI Text Embedding 3text-embedding-3-small、text-embedding-3-largeOpenAI embeddings API 只接受文本输入加模型名不暴露 query/document 任务参数。Mistral Embedmistral-embed使用服务商提供的普通嵌入输入不要臆造任务前缀。阿里 GTE base 模型gte-large、gte-large-zh基础 GTE 模型常规检索用纯文本。不适用于新的instruct变体如gte-Qwen2-1.5B-instruct请核对对应模型卡。Jina Embeddings v2jina-embeddings-v2-base-en、jina-embeddings-v2-base-zhJina v2 为纯文本输入Jina v3/v4 则不同检索任务需使用task参数。给无指令模型强行开启 LightRAG 的非对称模式会让输入形态偏离模型训练/文档声明所预期的样子。即使服务能正常启动检索质量也可能下降——这类问题尤其隐蔽因为启动成功并不等于行为正确。Provider 任务参数型绑定Jina / Gemini / VoyageAI这种模式适用于服务商在 API 层暴露了独立的 query/document 嵌入任务的情况。对这类绑定不要配置前缀变量。Jina 示例EMBEDDING_BINDINGjina EMBEDDING_ASYMMETRICtrue EMBEDDING_MODELjina-embeddings-v4Gemini 示例EMBEDDING_BINDINGgemini EMBEDDING_ASYMMETRICtrue EMBEDDING_MODELgemini-embedding-001VoyageAI 示例EMBEDDING_BINDINGvoyageai EMBEDDING_ASYMMETRICtrue EMBEDDING_MODELvoyage-3如果在这种绑定下还额外配置了EMBEDDING_QUERY_PREFIX或EMBEDDING_DOCUMENT_PREFIXLightRAG 会记录警告并忽略前缀见 lightrag/api/config.py 中对 Provider 绑定 前缀同时出现时的分支处理。源码中的实现证据在 lightrag/api/lightrag_server.py 中服务端按 binding 分发并决定传入哪些参数Jinalightrag/llm/jina.py 对应封装非对称开启时传入context并显式把task置为None由嵌入函数根据context自动选出retrieval.query/retrieval.passageGemini从绑定选项中读取task_type未显式指定时结合context映射为RETRIEVAL_QUERY/RETRIEVAL_DOCUMENTVoyageAI同样传入context由封装映射为 provider 的input_type。这些映射行为有专门的单元测试覆盖见 tests/llm/test_asymmetric_embedding.pytest_jina_default_task_is_query_when_context_query/test_jina_default_task_is_passage_when_context_document验证 Jina 在taskNone时按context自动生成retrieval.query/retrieval.passagetest_gemini_task_type_query_for_query_context/test_gemini_task_type_document_for_document_context验证 Gemini 映射出RETRIEVAL_QUERY/RETRIEVAL_DOCUMENT显式传入task/task_type时则覆盖上下文推断test_jina_explicit_task_overrides_context等。注意一个常见误区Jina v2 是纯文本模型前面已列入对称模型表而 Jina v3/v4 才使用task参数。因此 Provider 任务参数模式适用于jina-embeddings-v3/v4这类新模型切勿对 v2 使用。文本任务前缀型绑定OpenAI / Azure OpenAI / Ollama这种模式适用于模型本身期望在输入文本中携带任务指令的场景例如模型卡明确写明需要search_query:、search_document:、query:、passage:等前缀典型的如 BGE 系列、E5 系列。不要因为模型恰好是通过openai、azure_openai或ollama服务而盲目开启此模式。开启后两个前缀变量必须都显式配置EMBEDDING_ASYMMETRICtrue EMBEDDING_QUERY_PREFIXsearch_query: EMBEDDING_DOCUMENT_PREFIXsearch_document: 如果某一侧确实希望不加前缀使用哨兵值NO_PREFIXEMBEDDING_ASYMMETRICtrue EMBEDDING_QUERY_PREFIXsearch_query: EMBEDDING_DOCUMENT_PREFIXNO_PREFIXNO_PREFIX内部会被转换成空字符串。它与变量未设置不同它表示这一侧经过人工确认故意不加前缀。这也是get_embedding_prefix_config()的解析逻辑lightrag/api/config.py存在的意义——用显式哨兵把有意留空和误漏配置区分开。至少有一侧必须是非空前缀下面这种配置是无效的、启动即报错EMBEDDING_ASYMMETRICtrue EMBEDDING_QUERY_PREFIXNO_PREFIX EMBEDDING_DOCUMENT_PREFIXNO_PREFIX前缀如何被拼接到输入上前缀拼接发生在各 binding 的嵌入实现内。以 lightrag/llm/ollama.py 为例ollama_embed接收query_prefix与document_prefix并按context决定在整批文本前统一拼接if context query and query_prefix: texts [query_prefix text for text in texts] elif context document and document_prefix: texts [document_prefix text for text in texts]在服务端 lightrag/api/lightrag_server.py只有Provider 支持非对称 opt-in 通过双重条件满足时才把这些参数下发给底层函数否则维持纯对称的旧调用路径。前缀模式下前缀被忽略的情况还需注意一种易混淆场景前缀模式仅对openai/azure_openai/ollama生效若你在 Provider 任务参数型绑定jina/gemini/voyageai上配置了前缀变量两者同时出现时前缀同样会被忽略并告警因为 Provider 任务参数优先级更高、二者实现路径互斥。无效的空前缀不要用空的环境变量值来表达故意不加前缀EMBEDDING_DOCUMENT_PREFIX请改用NO_PREFIX。空值会被拒绝原因是 shell、.env与 Docker Compose 对空字符串的处理方式往往让空值与意外的配置缺失难以区分。如果允许空值一个被误清空的变量可能悄悄退化为另一种语义。从代码可见get_embedding_prefix_config()对空串直接抛错if value : raise ValueError( f{env_key} is empty. Use {NO_PREFIX_SENTINEL} to explicitly request no prefix, or remove the variable to leave it unconfigured. )校验规则速查表Validation Summary下表是 LightRAG 对非对称嵌入全部配置组合的最终判定结果可直接作为排障参考配置结果EMBEDDING_ASYMMETRIC未设置对称模式前缀被忽略并告警。EMBEDDING_ASYMMETRICfalse对称模式前缀被忽略并告警。无指令模型如BAAI/bge-m3、text-embedding-3-small、mistral-embed、基础 GTE、Jina v2保持对称模式除非模型卡要求否则不要配置前缀或 Provider 任务。EMBEDDING_ASYMMETRICtruejina/gemini/voyageaiProvider 任务参数模式前缀被忽略并告警。EMBEDDING_ASYMMETRICtrueopenai/azure_openai/ollama且两个前缀变量均已配置文本前缀模式。前缀模式下缺少某个前缀变量启动报错请填写真实前缀或NO_PREFIX。前缀模式下两侧都是NO_PREFIX启动报错不存在任何非对称行为。前缀变量被设为空值启动报错请改用NO_PREFIX。校验由谁执行所有上述判定集中在resolve_asymmetric_embedding_opt_in()这一个入口lightrag/api/config.py它对三种情况分别处理非对称开关关闭时告警并返回FalseProvider 任务型绑定直接放行前缀型绑定则要求双侧均显式配置且至少一侧非空否则抛出ValueError其余绑定一律拒绝。对应地服务端启动流程在 lightrag/api/lightrag_server.py 调用该函数并把结果写入最终EmbeddingFunc实例的supports_asymmetric标志见同文件 L1011供后续所有查询/入库路径使用。单测对每条规则都有断言例如test_asymmetric_opt_in_explicit_true_requires_both_prefix_settings缺前缀抛 requires both、test_asymmetric_opt_in_explicit_true_rejects_both_sides_no_prefix双侧NO_PREFIX抛 At least one、test_get_embedding_prefix_config_rejects_empty_env_value空值抛错可参考 tests/llm/test_asymmetric_embedding.py。配置变更后的重建索引要求Reindexing改变非对称嵌入配置会改变已存文档与未来查询所产生的向量本身。因此在启用、禁用或修改以下任一设置后都必须清空该工作区已有的 LightRAG 数据并重新对源文件建索引EMBEDDING_ASYMMETRICEMBEDDING_QUERY_PREFIXEMBEDDING_DOCUMENT_PREFIXProvider 任务行为类设置例如 Jina 的task、Gemini 的task_type、VoyageAI 的input_type不要把已建好的向量库直接复用在配置变更前后。混合使用不同 query/document 行为生成的向量会让检索质量变得不可预测。这一点与 examples/lightrag_gemini_workspace_demo.py 等示例所演示的工作区 重新插入文档流程一致——工作区级数据清理是最稳妥的重建粒度。即便是从一个合法非对称配置切到另一个合法非对称配置同样必须清理数据并重新索引。实战决策清单最后给出一个可直接照做的配置决策流程覆盖从模型确认到上线运行的全过程查模型卡确认目标嵌入模型是无指令型前缀型还是Provider 任务型openai兼容端点背后可能是任意一种不要想当然。无指令型BGE-M3、text-embedding-3-*、mistral-embed、GTE base、Jina v2 等保持EMBEDDING_ASYMMETRIC不设置或为false不设任何前缀变量。Provider 任务型Jina v3/v4、Gemini embedding、VoyageAI设置EMBEDDING_ASYMMETRICtrue与对应EMBEDDING_MODEL不加前缀变量如需固定task/task_type再在绑定选项中显式配置。前缀型BGE、E5 等EMBEDDING_ASYMMETRICtrue加两个前缀变量单侧有意留空用NO_PREFIX严禁空字符串严禁两侧全空。验证启动观察启动日志确认告警或错误与速查表预期一致。生效切换任何配置增删改之后清空工作区向量数据并重新插入源文档不要复用旧向量库。LightRAG 默认对称、显式开启非对称的设计本质上把检索行为是否改变的决策权交还给用户并用启动期校验把误配置挡在服务运行之前。理解文档 docs/AsymmetricEmbedding.md 中这两类风格与NO_PREFIX语义配合 env.example 中内嵌的注释模板其同样强调Jina/Gemini/VoyageAI 等 Provider 任务型绑定不应配置前缀变量而 BGE/E5/GTE 等前缀型模型需要两个前缀变量带尾随空格的取值需加引号包裹就能为任意嵌入后端选出唯一正确的配置组合。【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考