From 0831e445cf7c2a91d498292ea63a76dae7060e55 Mon Sep 17 00:00:00 2001 From: "open-swe[bot]" <215916821+open-swe[bot]@users.noreply.github.com> Date: Thu, 14 May 2026 15:35:30 -0700 Subject: [PATCH] docs(openai): document `base_url` env var fallback chain (#37436) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents the env vars that influence `base_url` resolution on `ChatOpenAI`, `OpenAIEmbeddings`, and `BaseOpenAI`. The previous docstrings only said "leave blank if not using a proxy or service emulator" and did not explain that two different env vars are consulted by two different layers. Concretely: - `OPENAI_API_BASE` is read explicitly by LangChain at init and passed as `base_url` to the underlying client. - `OPENAI_BASE_URL` is read by the underlying `openai` SDK client itself. LangChain only inspects its presence to decide whether to default-enable `stream_usage` (left off when set, because many non-OpenAI endpoints do not support streaming token usage). Precedence: explicit `base_url=` kwarg → `OPENAI_API_BASE` → `OPENAI_BASE_URL` (via SDK fallback). Docs-only change — no behavior change. > AI-agent involvement: drafted by an AI agent and reviewed before submission. _Opened collaboratively by Mason Daugherty and open-swe._ Co-authored-by: open-swe[bot] Co-authored-by: Mason Daugherty <61371264+mdrxy@users.noreply.github.com> --- .../openai/langchain_openai/chat_models/base.py | 15 +++++++++++++-- .../openai/langchain_openai/embeddings/base.py | 6 +++++- .../partners/openai/langchain_openai/llms/base.py | 12 ++++++++++-- 3 files changed, 28 insertions(+), 5 deletions(-) diff --git a/libs/partners/openai/langchain_openai/chat_models/base.py b/libs/partners/openai/langchain_openai/chat_models/base.py index 722721560e3..6686ffa2e3c 100644 --- a/libs/partners/openai/langchain_openai/chat_models/base.py +++ b/libs/partners/openai/langchain_openai/chat_models/base.py @@ -659,7 +659,18 @@ class BaseChatOpenAI(BaseChatModel): """ openai_api_base: str | None = Field(default=None, alias="base_url") - """Base URL path for API requests, leave blank if not using a proxy or service emulator.""" # noqa: E501 + """Base URL path for API requests, leave blank if not using a proxy or service emulator. + + Resolution order (first match wins): + + 1. Explicit `base_url` (or `openai_api_base`) kwarg. + 2. Env var `OPENAI_API_BASE` (read by LangChain at init). + 3. Env var `OPENAI_BASE_URL` (read by the underlying `openai` SDK client). + + `OPENAI_BASE_URL` is also inspected by LangChain only to decide whether to + default-enable `stream_usage` — when set, the default is left off because many + non-OpenAI endpoints do not support streaming token usage. + """ # noqa: E501 openai_organization: str | None = Field(default=None, alias="organization") """Automatically inferred from env var `OPENAI_ORG_ID` if not provided.""" @@ -2567,7 +2578,7 @@ class ChatOpenAI(BaseChatOpenAI): # type: ignore[override] | `timeout` | `float | Tuple[float, float] | Any | None` | Timeout for requests. | | `max_retries` | `int | None` | Max number of retries. | | `api_key` | `str | None` | OpenAI API key. If not passed in will be read from env var `OPENAI_API_KEY`. | - | `base_url` | `str | None` | Base URL for API requests. Only specify if using a proxy or service emulator. | + | `base_url` | `str | None` | Base URL for API requests. Only specify if using a proxy or service emulator. Falls back to env var `OPENAI_API_BASE`, then to `OPENAI_BASE_URL` (read by the underlying SDK client). | | `organization` | `str | None` | OpenAI organization ID. If not passed in will be read from env var `OPENAI_ORG_ID`. | See full list of supported init args and their descriptions below. diff --git a/libs/partners/openai/langchain_openai/embeddings/base.py b/libs/partners/openai/langchain_openai/embeddings/base.py index 93c687ba4b4..8595c7a8f4d 100644 --- a/libs/partners/openai/langchain_openai/embeddings/base.py +++ b/libs/partners/openai/langchain_openai/embeddings/base.py @@ -212,7 +212,11 @@ class OpenAIEmbeddings(BaseModel, Embeddings): """Base URL path for API requests, leave blank if not using a proxy or service emulator. - Automatically inferred from env var `OPENAI_API_BASE` if not provided. + Resolution order (first match wins): + + 1. Explicit `base_url` (or `openai_api_base`) kwarg. + 2. Env var `OPENAI_API_BASE` (read by LangChain at init). + 3. Env var `OPENAI_BASE_URL` (read by the underlying `openai` SDK client). """ # to support Azure OpenAI Service custom endpoints diff --git a/libs/partners/openai/langchain_openai/llms/base.py b/libs/partners/openai/langchain_openai/llms/base.py index a3c2dfb128f..48d311a090d 100644 --- a/libs/partners/openai/langchain_openai/llms/base.py +++ b/libs/partners/openai/langchain_openai/llms/base.py @@ -93,7 +93,8 @@ class BaseOpenAI(BaseLLM): `OPENAI_API_KEY`. openai_api_base: Base URL path for API requests, leave blank if not using a proxy or - service emulator. + service emulator. Falls back to env var `OPENAI_API_BASE`, then to + `OPENAI_BASE_URL` (read by the underlying SDK client). openai_organization: OpenAI organization ID. If not passed in will be read from env var `OPENAI_ORG_ID`. @@ -206,7 +207,14 @@ class BaseOpenAI(BaseLLM): alias="base_url", default_factory=from_env("OPENAI_API_BASE", default=None) ) """Base URL path for API requests, leave blank if not using a proxy or service - emulator.""" + emulator. + + Resolution order (first match wins): + + 1. Explicit `base_url` (or `openai_api_base`) kwarg. + 2. Env var `OPENAI_API_BASE` (read by LangChain at init). + 3. Env var `OPENAI_BASE_URL` (read by the underlying `openai` SDK client). + """ openai_organization: str | None = Field( alias="organization",