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

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] <open-swe@users.noreply.github.com>
Co-authored-by: Mason Daugherty <61371264+mdrxy@users.noreply.github.com>

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.

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

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",