跳转至

配置 (Configuration)

类型化配置系统，基于 Pydantic BaseSettings 和 .env 文件。提供五个子模型分别管理 PostgreSQL、LLM、Embedding、Reranker 和查询参数的配置，以及一个模块级延迟单例 settings。所有配置验证在首次访问时以快速失败方式执行，错误信息按分组归类展示。

顶层配置

lightrag_langchain.config.Settings

Bases: BaseSettings

组合所有五个配置组的顶层配置。

所有实例化失败（直接或通过单例）都会抛出 SettingsError 并附带分类摘要，绝不会抛出原始的 ValidationError。

Example 
from lightrag_langchain.config import settings

# 通过单例访问子配置
pg = settings.pg
llm = settings.llm
embedding = settings.embedding
reranker = settings.reranker
query_params = settings.query_params
源代码位于： src/lightrag_langchain/config.py 
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
class Settings(BaseSettings):
    """组合所有五个配置组的顶层配置。

    所有实例化失败（直接或通过单例）都会抛出 ``SettingsError``
    并附带分类摘要，绝不会抛出原始的 ``ValidationError``。

    Example:
        ```python
        from lightrag_langchain.config import settings

        # 通过单例访问子配置
        pg = settings.pg
        llm = settings.llm
        embedding = settings.embedding
        reranker = settings.reranker
        query_params = settings.query_params
        ```
    """

    model_config = SettingsConfigDict(
        env_file=".env",
        env_nested_delimiter="__",
        nested_model_default_partial_update=True,
        extra="forbid",
        case_sensitive=False,
        frozen=True,
    )

    pg: PgConfig
    llm: LlmConfig
    embedding: EmbeddingConfig
    reranker: RerankerConfig = RerankerConfig()
    query_params: QueryParamsConfig = QueryParamsConfig()

    def __init__(__pydantic_self__, **data: Any) -> None:  # noqa: N805
        try:
            super().__init__(**data)
        except ValidationError as exc:
            raise SettingsError(_format_validation_error(exc)) from exc

settings 为模块级延迟单例，通过 from lightrag_langchain.config import settings 访问。

配置子模型

lightrag_langchain.config.PgConfig

Bases: BaseModel

PostgreSQL 连接和连接池设置。

环境变量通过顶层 Settings 的字段名 pg 进行路由。 PG_HOST → pg.host、PG_PORT → pg.port 等。

连接池字段： - workspace：多租户 LightRAG 数据库的隔离命名空间 （D-05 单工作空间策略，默认 "default"）。 - pool_min_size / pool_max_size：asyncpg 连接池大小 （D-03，默认 2 / 10）。 - pool_timeout：命令超时时间，单位为秒（默认 30.0）。

Example 
from lightrag_langchain.config import settings

pg_config = settings.pg
print(pg_config.host, pg_config.database)
源代码位于： src/lightrag_langchain/config.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
class PgConfig(BaseModel):
    """PostgreSQL 连接和连接池设置。

    环境变量通过顶层 ``Settings`` 的字段名 ``pg`` 进行路由。
    ``PG_HOST`` → ``pg.host``、``PG_PORT`` → ``pg.port`` 等。

    连接池字段：
    - ``workspace``：多租户 LightRAG 数据库的隔离命名空间
      （D-05 单工作空间策略，默认 ``"default"``）。
    - ``pool_min_size`` / ``pool_max_size``：asyncpg 连接池大小
      （D-03，默认 2 / 10）。
    - ``pool_timeout``：命令超时时间，单位为秒（默认 30.0）。

    Example:
        ```python
        from lightrag_langchain.config import settings

        pg_config = settings.pg
        print(pg_config.host, pg_config.database)
        ```
    """

    model_config = ConfigDict(frozen=True)

    host: str
    port: int = 5432
    user: str
    password: SecretStr
    database: str
    workspace: str = "default"
    age_schema: str = "ag_catalog"
    pool_min_size: int = 2
    pool_max_size: int = 10
    pool_timeout: float = 30.0

lightrag_langchain.config.LlmConfig

Bases: BaseModel

LLM provider 设置。

必填：binding、binding_host、binding_api_key、model。 可选：temperature（默认 0.0）、max_tokens（默认 9000）。

Example 
from lightrag_langchain.config import settings

llm_config = settings.llm
print(llm_config.model, llm_config.temperature)
源代码位于： src/lightrag_langchain/config.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
class LlmConfig(BaseModel):
    """LLM provider 设置。

    必填：binding、binding_host、binding_api_key、model。
    可选：temperature（默认 0.0）、max_tokens（默认 9000）。

    Example:
        ```python
        from lightrag_langchain.config import settings

        llm_config = settings.llm
        print(llm_config.model, llm_config.temperature)
        ```
    """

    model_config = ConfigDict(frozen=True)

    binding: str
    binding_host: str
    binding_api_key: SecretStr
    model: str
    temperature: float = 0.0
    max_tokens: int = 9000

lightrag_langchain.config.EmbeddingConfig

Bases: BaseModel

Embedding provider 设置。

dim 默认为 1024（根据 D-06，匹配上游阿里云 text-embedding-v4）。

Example 
from lightrag_langchain.config import settings

emb_config = settings.embedding
print(emb_config.model, emb_config.dim)
源代码位于： src/lightrag_langchain/config.py 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
class EmbeddingConfig(BaseModel):
    """Embedding provider 设置。

    ``dim`` 默认为 1024（根据 D-06，匹配上游阿里云 text-embedding-v4）。

    Example:
        ```python
        from lightrag_langchain.config import settings

        emb_config = settings.embedding
        print(emb_config.model, emb_config.dim)
        ```
    """

    model_config = ConfigDict(frozen=True)

    binding: str
    binding_host: str
    binding_api_key: SecretStr
    model: str
    dim: int = 1024

lightrag_langchain.config.RerankerConfig

Bases: BaseModel

Reranker 设置。

所有字段均有默认值——binding 为空字符串表示禁用 rerank。

Example 
from lightrag_langchain.config import settings

rerank_config = settings.reranker
if rerank_config.binding:
    print(f"Reranker enabled: {rerank_config.model}")
源代码位于： src/lightrag_langchain/config.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
class RerankerConfig(BaseModel):
    """Reranker 设置。

    所有字段均有默认值——binding 为空字符串表示禁用 rerank。

    Example:
        ```python
        from lightrag_langchain.config import settings

        rerank_config = settings.reranker
        if rerank_config.binding:
            print(f"Reranker enabled: {rerank_config.model}")
        ```
    """

    model_config = ConfigDict(frozen=True)

    binding: str = ""
    binding_host: str = ""
    binding_api_key: SecretStr = SecretStr("")
    model: str = ""
    min_rerank_score: float = 0.0

lightrag_langchain.config.QueryParamsConfig

Bases: BaseModel

匹配上游 LightRAG 常量的查询行为默认值。

Token budget 不变量（D-08）： max_entity_tokens + max_relation_tokens < max_total_tokens。

Example 
from lightrag_langchain.config import settings

qp = settings.query_params
print(qp.top_k, qp.chunk_top_k, qp.max_total_tokens)
源代码位于： src/lightrag_langchain/config.py 
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
class QueryParamsConfig(BaseModel):
    """匹配上游 LightRAG 常量的查询行为默认值。

    Token budget 不变量（D-08）：
    ``max_entity_tokens + max_relation_tokens < max_total_tokens``。

    Example:
        ```python
        from lightrag_langchain.config import settings

        qp = settings.query_params
        print(qp.top_k, qp.chunk_top_k, qp.max_total_tokens)
        ```
    """

    model_config = ConfigDict(frozen=True)

    top_k: int = 40
    chunk_top_k: int = 20
    max_entity_tokens: int = 6000
    max_relation_tokens: int = 8000
    max_total_tokens: int = 30000
    cosine_threshold: float = 0.2
    kg_chunk_pick_method: str = "VECTOR"
    keyword_language: str = "Chinese"

    @model_validator(mode="after")
    def check_token_budget(self) -> QueryParamsConfig:
        """强制执行 token budget 不变量——只读（不进行修改）。"""
        if self.max_entity_tokens + self.max_relation_tokens >= self.max_total_tokens:
            raise ValueError(
                f"Token budget violated: max_entity_tokens ({self.max_entity_tokens}) "
                f"+ max_relation_tokens ({self.max_relation_tokens}) "
                f"must be < max_total_tokens ({self.max_total_tokens})"
            )
        return self

check_token_budget 

check_token_budget() -> QueryParamsConfig

强制执行 token budget 不变量——只读（不进行修改）。

源代码位于： src/lightrag_langchain/config.py 
200
201
202
203
204
205
206
207
208
209
@model_validator(mode="after")
def check_token_budget(self) -> QueryParamsConfig:
    """强制执行 token budget 不变量——只读（不进行修改）。"""
    if self.max_entity_tokens + self.max_relation_tokens >= self.max_total_tokens:
        raise ValueError(
            f"Token budget violated: max_entity_tokens ({self.max_entity_tokens}) "
            f"+ max_relation_tokens ({self.max_relation_tokens}) "
            f"must be < max_total_tokens ({self.max_total_tokens})"
        )
    return self

异常

lightrag_langchain.config.SettingsError

Bases: Exception

配置验证失败时抛出，附带分类摘要。

Example 
from lightrag_langchain.config import SettingsError

try:
    from lightrag_langchain.config import settings
except SettingsError as e:
    print(f"Configuration error: {e}")
源代码位于： src/lightrag_langchain/config.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
class SettingsError(Exception):
    """配置验证失败时抛出，附带分类摘要。

    Example:
        ```python
        from lightrag_langchain.config import SettingsError

        try:
            from lightrag_langchain.config import settings
        except SettingsError as e:
            print(f"Configuration error: {e}")
        ```
    """