Skip to content

The agent engineering platform.

docs(openai): document `base_url` env var fallback chain (#37436)

open-swe[bot]0831e445cf7c
diff --git a/libs/partners/openai/langchain_openai/chat_models/base.py b/libs/partners/openai/langchain_openai/chat_models/base.py
index 722721560e..6686ffa2e3 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 93c687ba4b..8595c7a8f4 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 a3c2dfb128..48d311a090 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",