> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 环境变量

Agent Server 支持特定的环境变量来配置部署。

## `BG_JOB_ISOLATED_LOOPS`

将 `BG_JOB_ISOLATED_LOOPS` 设置为 `True`，以在与服务 API 事件循环隔离的独立事件循环中执行后台运行。

<Warning>
  启用此标志并不能解决根本问题。它只是将同步阻塞工作从服务 API 的事件循环中移开，从而使健康检查不再失败，但阻塞代码仍将在后台循环上运行，并**会**继续在生产环境中导致问题，例如吞吐量下降、尾部延迟尖峰、工作线程饥饿或连接池耗尽（参见下面的连接池大小注意事项），以及在负载下扩展性差。

  要正确解决这些问题，请在整个代理中使用原生异步驱动程序和异步代码。这意味着使用异步 HTTP 客户端（如 `httpx` 或 `aiohttp`，尽管我们建议缓存客户端以避免加载 SSL 上下文的 CPU 开销）、异步数据库驱动程序（如 `asyncpg` 或 `psycopg[async]`）以及异步模型 SDK。对于不可避免的同步库，请将特定调用包装在 `asyncio.to_thread(...)` 或 `loop.run_in_executor(...)` 中，而不是为整个部署启用此标志。
</Warning>

如果图/节点的实现包含同步代码，则应将此环境变量设置为 `True`。在这种情况下，同步代码将阻塞服务 API 事件循环，这可能导致 API 不可用。API 不可用的一个症状是由于健康检查失败而导致应用程序持续重启。

<Warning>
  当启用 `BG_JOB_ISOLATED_LOOPS` 时，每个后台工作线程在自己的线程中运行，并拥有**独立的 Postgres 连接池**。每个工作线程的连接池大小为 `LANGGRAPH_POSTGRES_POOL_MAX_SIZE // N_JOBS_PER_WORKER`。例如，如果 `LANGGRAPH_POSTGRES_POOL_MAX_SIZE=20` 且 `N_JOBS_PER_WORKER=15`，则每个工作线程只能获得 1 个连接的连接池。较小的每个工作线程连接池更容易受到连接故障的影响，因为单个陈旧连接占连接池的比例很大。如果启用隔离循环，请确保 `LANGGRAPH_POSTGRES_POOL_MAX_SIZE` 足够大，以便为每个工作线程提供至少几个连接。
</Warning>

默认值为 `False`。

## `BG_JOB_MAX_RETRIES`

后台运行在可重试故障（例如瞬态数据库错误、服务器关闭取消）后将被重试的最大次数。当运行因可重试错误失败时，它会被放回队列，并从最后一个检查点步骤恢复。如果运行超过最大重试次数，则被标记为失败。

默认值为 `3`。

## `BG_JOB_SHUTDOWN_GRACE_PERIOD_SECS`

以秒为单位指定服务器在队列收到关闭信号后等待后台作业完成的时间。在此时间段后，服务器将强制终止。默认值为 `180` 秒。最大值为 `3600` 秒。设置此值以确保作业在关闭期间有足够的时间干净地完成。在 `langgraph-api==0.2.16` 中添加。

## `BG_JOB_TIMEOUT_SECS`

可以增加后台运行的超时时间。但是，云部署的基础设施对 API 请求强制执行 1 小时的超时限制。这意味着客户端和服务器之间的连接将在 1 小时后超时。这是不可配置的。

后台运行可以执行超过 1 小时，但如果运行时间超过 1 小时，客户端必须重新连接到服务器（例如，通过 `POST /threads/{thread_id}/runs/{run_id}/stream` 加入流）以检索运行的输出。

默认值为 `86400`。

## `CORS_ALLOW_ORIGINS`

设置 `CORS_ALLOW_ORIGINS` 以指定允许的来源。

* 允许单个来源的示例：`CORS_ALLOW_ORIGINS=https://example.com`
* 允许多个来源的示例：`CORS_ALLOW_ORIGINS=https://example.com,https://app.example.com`

有关高级 CORS 配置，请参阅[如何添加自定义 CORS 配置](/langsmith/cli#customizing-http-middleware-and-headers)。

默认值为 `*`（所有来源）。

## `DD_API_KEY`

指定 `DD_API_KEY`（您的 [Datadog API 密钥](https://docs.datadoghq.com/account_management/api-app-keys/)）以自动为部署启用 Datadog 追踪。指定其他 [`DD_*` 环境变量](https://ddtrace.readthedocs.io/en/stable/configuration.html)以配置追踪插桩。

如果指定了 `DD_API_KEY`，应用程序进程将被包装在 [`ddtrace-run` 命令](https://ddtrace.readthedocs.io/en/stable/installation_quickstart.html)中。通常需要其他 `DD_*` 环境变量（例如 `DD_SITE`、`DD_ENV`、`DD_SERVICE`、`DD_TRACE_ENABLED`）来正确配置追踪插桩。有关更多详细信息，请参阅 [`DD_*` 环境变量](https://ddtrace.readthedocs.io/en/stable/configuration.html)。您可以启用 `DD_TRACE_DEBUG=true` 并设置 `DD_LOG_LEVEL=debug` 进行故障排除。

<Note>
  启用 `DD_API_KEY`（因此启用 `ddtrace-run`）可能会覆盖或干扰您可能已插桩到应用程序代码中的其他自动插桩解决方案（例如 OpenTelemetry）。
</Note>

## `LANGGRAPH_POSTGRES_POOL_MAX_SIZE`

从 langgraph-api 版本 `0.2.12` 开始，可以使用 `LANGGRAPH_POSTGRES_POOL_MAX_SIZE` 环境变量控制 Postgres 连接池（每个副本）的最大大小。通过设置此变量，您可以确定服务器将与 Postgres 数据库建立的并发连接数的上限。

例如，如果部署扩展到 10 个副本，并且 `LANGGRAPH_POSTGRES_POOL_MAX_SIZE` 配置为 `150`，则最多可以建立 `1500` 个到 Postgres 的连接。这对于数据库资源有限（或更可用）的部署，或者需要为性能或扩展原因调整连接行为的部署特别有用。

当启用 [`BG_JOB_ISOLATED_LOOPS`](#bg_job_isolated_loops) 时，连接池不是共享的。相反，每个后台工作线程创建自己的连接池，最大大小为 `LANGGRAPH_POSTGRES_POOL_MAX_SIZE / N_JOBS_PER_WORKER`。在降低连接池大小时请记住这一点。对于共享连接池效果良好的值，在隔离循环下可能导致每个工作线程的连接池非常小。

默认值为 `150` 个连接。

## `LS_CHECKPOINT_DELETE`

用于延迟检查点删除的 JSON 值配置。启用后，线程删除和修剪操作会将检查点排入后台删除队列，而不是同步删除，从而将 I/O 从请求热路径中移出。在 `langgraph-api>=0.8.1` 中可用。

<Note>
  仅支持默认的 PostgreSQL 检查点后端。延迟删除将在未来版本中成为默认设置。
</Note>

接受的字段：

* `enabled`（布尔值，默认 `false`）：当为 `true` 时，线程删除和修剪操作会将检查点排入 `checkpoint_delete_queue` 并立即返回，后台工作线程会清空队列。
* `enabledWorkerOnly`（布尔值，默认 `false`）：仅运行后台清空工作线程，而不排入新条目。在将 `enabled` 回滚到 `false` 后，使用此选项完成队列的清空。
* `pollIntervalMs`（整数，默认 `5000`）：工作线程轮询队列的频率，以毫秒为单位。
* `batchSize`（整数，默认 `25`）：工作线程每个事务出队的检查点条目数。较小的值会将 I/O 分散到更长的时间，代价是更长的清空延迟。
* `batchSleepMs`（整数，默认 `500`）：当队列非空时，工作线程在批次之间休眠的时间，以毫秒为单位。

示例：`LS_CHECKPOINT_DELETE='{"enabled":true,"batchSize":10,"pollIntervalMs":1000}'`。

默认为禁用（同步检查点删除）。

## `LS_DEFAULT_CHECKPOINTER_BACKEND`

为未在 `langgraph.json` 中指定检查点后端的代理服务器设置默认的[检查点后端](/langsmith/configure-checkpointer)。接受的值：`"default"`（PostgreSQL）、`"mongo"`、`"custom"`。

如果应用程序的 `langgraph.json` 包含 `checkpointer.backend` 值，则它优先于此变量。

设置为 `"mongo"` 时，还必须通过 [`LS_MONGODB_URI`](#ls_mongodb_uri) 提供 MongoDB 连接 URI。

## `LANGSMITH_API_KEY`

仅适用于使用[自托管 LangSmith](/langsmith/self-hosted) 的部署。

要将追踪发送到自托管 LangSmith 实例，请将 `LANGSMITH_API_KEY` 设置为从自托管实例创建的 API 密钥。

## `LANGSMITH_ENDPOINT`

仅适用于使用[自托管 LangSmith](/langsmith/self-hosted) 的部署。

要将追踪发送到自托管 LangSmith 实例，请将 `LANGSMITH_ENDPOINT` 设置为自托管实例的主机名。

## `LANGSMITH_TRACING`

将 `LANGSMITH_TRACING` 设置为 `false` 以禁用向 LangSmith 发送追踪。

<Note>
  有关基于运行时条件（例如每个客户端要求或数据敏感性）的选择性追踪控制，请参阅[条件追踪](/langsmith/conditional-tracing)。
</Note>

默认值为 `true`。

## `LOG_COLOR`

这主要与通过 `langgraph dev` 命令使用开发服务器相关。将 `LOG_COLOR` 设置为 `true` 以在使用默认控制台渲染器时启用 ANSI 彩色控制台输出。通过将此变量设置为 `false` 禁用颜色输出会产生单色日志。默认值为 `true`。

## `LOG_LEVEL`

配置[日志级别](https://docs.python.org/3/library/logging.html#logging-levels)。默认值为 `INFO`。

## `LOG_JSON`

将 `LOG_JSON` 设置为 `true` 以使用配置的 `JSONRenderer` 将所有日志消息渲染为 JSON 对象。这会产生结构化日志，可以轻松地被日志管理系统解析或摄取。默认值为 `false`。

## `MOUNT_PREFIX`

<Info>
  **仅允许在自托管部署中**
  `MOUNT_PREFIX` 环境变量仅允许在自托管部署模型中使用，LangSmith SaaS 不允许使用此环境变量。
</Info>

设置 `MOUNT_PREFIX` 以在特定路径前缀下提供 Agent Server。这对于服务器位于需要特定路径前缀的反向代理或负载均衡器后面的部署很有用。

例如，如果服务器要在 `https://example.com/langgraph` 下提供服务，请将 `MOUNT_PREFIX` 设置为 `/langgraph`。

## `N_JOBS_PER_WORKER`

Agent Server 任务队列中每个工作线程的作业数。默认值为 `10`。

## `LS_APM_OTEL_ENABLED`

要为部署配置 OpenTelemetry APM 追踪，请将 `LS_APM_OTEL_ENABLED` 设置为 `true`，并将 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 或 `OTEL_EXPORTER_OTLP_ENDPOINT` 设置为目标追踪摄取端点。请注意，在 `0.7.17` 之后的服务器版本中，需要同时设置 `LS_APM_OTEL_ENABLED` 和另外两个导出端点之一才能激活 OpenTelemetry APM 追踪。

指定其他 [`OTEL_*` 环境变量](https://opentelemetry.io/docs/collector/configuration/)以配置追踪、日志记录和其他插桩。

```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 如果您设置了 LS_APM_OTEL_ENABLED 和 (OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 或 OTEL_EXPORTER_OTLP_ENDPOINT)，
# 服务器将启动并启用 OpenTelemetry 插桩。
LS_APM_OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=<目标追踪摄取端点>
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.nr-data.net
OTEL_SERVICE_NAME=MY_LANGSMITH_DEPLOYMENT
OTEL_EXPORTER_OTLP_HEADERS=api-key=<YOUR_INGEST_LICENSE_KEY>
LANGSMITH_OTEL_ENABLED=true
# 常用 OTEL 设置
OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT=4095
OTEL_EXPORTER_OTLP_COMPRESSION=gzip
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta
OTEL_PYTHON_EXCLUDED_URLS=/metrics,/ok,/info
# 可选：OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
```

例如，要将 OpenTelemetry 追踪提交到 [New Relic 的美国区域](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/)，请设置以下内容：

```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
LS_APM_OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otlp.nr-data.net/v1/traces
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.nr-data.net
OTEL_EXPORTER_OTLP_HEADERS=api-key=<YOUR_INGEST_LICENSE_KEY>
```

<Note>
  OTel APM 追踪在 Agent Server 版本 `0.5.32` 中添加，目前处于 Alpha 阶段。
</Note>

## `LS_MONGODB_URI`

MongoDB 检查点后端的 MongoDB 连接 URI。

URI 必须指向副本集成员或 `mongos` 路由器，并且必须在路径中包含数据库名称。

有关详细信息，请参阅[配置检查点后端](/langsmith/configure-checkpointer)。

有关详细信息，请参阅[配置检查点后端](/langsmith/configure-checkpointer)。

## `POSTGRES_URI_CUSTOM`

<Info>
  **仅适用于混合和自托管**
  自定义 Postgres 实例仅适用于[混合](/langsmith/hybrid)和[自托管](/langsmith/self-hosted)部署。
</Info>

指定 `POSTGRES_URI_CUSTOM` 以使用自定义 Postgres 实例。`POSTGRES_URI_CUSTOM` 的值必须是有效的 [Postgres 连接 URI](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS)。

Postgres：

* 版本 15.8 或更高。
* 必须存在初始数据库，并且连接 URI 必须引用该数据库。

控制平面功能：

* 如果指定了 `POSTGRES_URI_CUSTOM`，控制平面将不会为服务器配置数据库。
* 如果移除了 `POSTGRES_URI_CUSTOM`，控制平面将不会为服务器配置数据库，也不会删除外部管理的 Postgres 实例。
* 如果移除了 `POSTGRES_URI_CUSTOM`，修订版的部署将不会成功。一旦指定了 `POSTGRES_URI_CUSTOM`，在部署的整个生命周期内必须始终设置它。
* 如果删除了部署，控制平面不会删除外部管理的 Postgres 实例。
* `POSTGRES_URI_CUSTOM` 的值可以更新。例如，可以更新 URI 中的密码。

数据库连接性：

* 自定义 Postgres 实例必须可被 Agent Server 访问。用户负责确保连接性。

## `REDIS_CLUSTER`

<Warning>
  此功能处于 Alpha 阶段。
</Warning>

<Info>
  **仅允许在自托管部署中**
  Redis 集群模式仅在自托管部署模型中可用，LangSmith SaaS 默认会为您配置一个 redis 实例。
</Info>

将 `REDIS_CLUSTER` 设置为 `True` 以启用 Redis 集群模式。启用后，系统将使用集群模式连接到 Redis。这在连接到 Redis 集群部署时很有用。

默认值为 `False`。

## `REDIS_KEY_PREFIX`

<Info>
  **在 API Server 版本 0.1.9+ 中可用**
  此环境变量在 API Server 版本 0.1.9 及更高版本中受支持。
</Info>

指定 Redis 键的前缀。这允许多个 Agent Server 实例通过使用不同的键前缀共享同一个 Redis 实例。

默认值为 `''`。

## `REDIS_URI_CUSTOM`

<Info>
  **仅适用于混合和自托管**
  自定义 Redis 实例仅适用于[混合](/langsmith/hybrid)和[自托管](/langsmith/self-hosted)部署。
</Info>

指定 `REDIS_URI_CUSTOM` 以使用自定义 Redis 实例。`REDIS_URI_CUSTOM` 的值必须是有效的 [Redis 连接 URI](https://redis-py.readthedocs.io/en/stable/connections.html#redis.Redis.from_url)。

## `REDIS_MAX_CONNECTIONS`

可以使用 `REDIS_MAX_CONNECTIONS` 环境变量控制 Redis 连接池（每个副本）的最大大小。通过设置此变量，您可以确定服务器将与 Redis 实例建立的并发连接数的上限。

例如，如果部署扩展到 10 个副本，并且 `REDIS_MAX_CONNECTIONS` 配置为 `150`，则最多可以建立 `1500` 个到 Redis 的连接。

默认值为 `2000`。

## `RESUMABLE_STREAM_TTL_SECONDS`

Redis 中可恢复流数据的生存时间（以秒为单位）。

当创建运行并流式传输输出时，可以将流配置为可恢复（例如 `stream_resumable=True`）。如果流是可恢复的，则流的输出会临时存储在 Redis 中。可以通过设置 `RESUMABLE_STREAM_TTL_SECONDS` 来配置此数据的 TTL。

有关如何实现可恢复流的更多详细信息，请参阅 [Python](https://reference.langchain.com/python/langsmith/deployment/sdk/#langgraph_sdk.client.RunsClient.stream) 和 [JS/TS](https://langchain-ai.github.io/langgraphjs/reference/classes/sdk_client.RunsClient.html#stream) SDK。

默认值为 `120` 秒。

<Note>
  将 `RESUMABLE_STREAM_TTL_SECONDS` 设置为非常高的值可能会在存在许多具有大型或频繁流式输出的并发运行时导致大量的 Redis 内存使用。将此值设置为允许在网络中断期间恢复的最小值，并优先考虑检查点以实现长期持久性和执行快照。
</Note>

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/env-var.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>