From df4a29b5d0e5cbacd178e08f08c4eddb3176a44f Mon Sep 17 00:00:00 2001 From: Mason Daugherty Date: Mon, 16 Feb 2026 23:10:31 -0500 Subject: [PATCH] docs(openai): more nits (#35277) --- .../langchain_openai/chat_models/base.py | 13 ++-- .../langchain_openai/embeddings/base.py | 74 ++++++++++++------- 2 files changed, 54 insertions(+), 33 deletions(-) diff --git a/libs/partners/openai/langchain_openai/chat_models/base.py b/libs/partners/openai/langchain_openai/chat_models/base.py index 7c514dc0102..ad755a14ffe 100644 --- a/libs/partners/openai/langchain_openai/chat_models/base.py +++ b/libs/partners/openai/langchain_openai/chat_models/base.py @@ -1538,7 +1538,7 @@ class BaseChatOpenAI(BaseChatModel): try: choices = response_dict["choices"] except KeyError as e: - msg = f"Response missing `choices` key: {response_dict.keys()}" + msg = f"Response missing 'choices' key: {response_dict.keys()}" raise KeyError(msg) from e if choices is None: @@ -1546,7 +1546,7 @@ class BaseChatOpenAI(BaseChatModel): # when the response format differs or an error occurs without # populating the error field. Provide a more helpful error message. msg = ( - "Received response with null value for `choices`. " + "Received response with null value for 'choices'. " "This can happen when using OpenAI-compatible APIs (e.g., vLLM) " "that return a response in an unexpected format. " f"Full response keys: {list(response_dict.keys())}" @@ -2692,6 +2692,7 @@ class ChatOpenAI(BaseChatOpenAI): # type: ignore[override] !!! version-added "Added in `langchain-openai` 0.3.9" !!! version-added "Added in `langchain-openai` 0.3.26" + You can also initialize `ChatOpenAI` with `use_previous_response_id`. Input messages up to the most recent response will then be dropped from request payloads, and `previous_response_id` will be set using the ID of the most @@ -2702,10 +2703,12 @@ class ChatOpenAI(BaseChatOpenAI): # type: ignore[override] ``` !!! note "OpenAI-compatible endpoints" + Some OpenAI-compatible providers/proxies may not support forwarding - reasoning blocks in request history. If you see request-format errors - while using reasoning + Responses API, prefer - `use_previous_response_id=True` (so the server keeps conversation state). + reasoning blocks in request history. If you see request-format + errors while using reasoning + Responses API, prefer + `use_previous_response_id=True` (so the server keeps + conversation state). ??? info "Reasoning output" diff --git a/libs/partners/openai/langchain_openai/embeddings/base.py b/libs/partners/openai/langchain_openai/embeddings/base.py index 81e5f653f44..93c687ba4b4 100644 --- a/libs/partners/openai/langchain_openai/embeddings/base.py +++ b/libs/partners/openai/langchain_openai/embeddings/base.py @@ -161,11 +161,12 @@ class OpenAIEmbeddings(BaseModel, Embeddings): [-0.009100092574954033, 0.005071679595857859, -0.0029193938244134188] ``` - OpenAI-compatible APIs (e.g. OpenRouter, Ollama, vLLM): - When using a non-OpenAI provider, set ``check_embedding_ctx_length=False`` - to send raw text instead of tokens (which many providers don't support), - and optionally set ``encoding_format`` to ``"float"`` to avoid base64 - encoding issues: + !!! note "OpenAI-compatible APIs (e.g. OpenRouter, Ollama, vLLM)" + + When using a non-OpenAI provider, set + `check_embedding_ctx_length=False` to send raw text instead of tokens + (which many providers don't support), and optionally set + `encoding_format` to `'float'` to avoid base64 encoding issues: ```python from langchain_openai import OpenAIEmbeddings @@ -188,7 +189,7 @@ class OpenAIEmbeddings(BaseModel, Embeddings): dimensions: int | None = None """The number of dimensions the resulting output embeddings should have. - Only supported in `text-embedding-3` and later models. + Only supported in `'text-embedding-3'` and later models. """ # to support Azure OpenAI Service custom deployment names @@ -199,14 +200,20 @@ class OpenAIEmbeddings(BaseModel, Embeddings): default_factory=from_env("OPENAI_API_VERSION", default=None), alias="api_version", ) - """Automatically inferred from env var `OPENAI_API_VERSION` if not provided.""" + """Version of the OpenAI API to use. + + Automatically inferred from env var `OPENAI_API_VERSION` if not provided. + """ # to support Azure OpenAI Service custom endpoints openai_api_base: str | None = Field( 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.""" + """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. + """ # to support Azure OpenAI Service custom endpoints openai_api_type: str | None = Field( @@ -226,7 +233,10 @@ class OpenAIEmbeddings(BaseModel, Embeddings): ) = Field( alias="api_key", default_factory=secret_from_env("OPENAI_API_KEY", default=None) ) - """Automatically inferred from env var `OPENAI_API_KEY` if not provided.""" + """API key to use for API calls. + + Automatically inferred from env var `OPENAI_API_KEY` if not provided. + """ openai_organization: str | None = Field( alias="organization", @@ -234,7 +244,10 @@ class OpenAIEmbeddings(BaseModel, Embeddings): ["OPENAI_ORG_ID", "OPENAI_ORGANIZATION"], default=None ), ) - """Automatically inferred from env var `OPENAI_ORG_ID` if not provided.""" + """OpenAI organization ID to use for API calls. + + Automatically inferred from env var `OPENAI_ORG_ID` if not provided. + """ allowed_special: Literal["all"] | set[str] | None = None @@ -249,8 +262,10 @@ class OpenAIEmbeddings(BaseModel, Embeddings): request_timeout: float | tuple[float, float] | Any | None = Field( default=None, alias="timeout" ) - """Timeout for requests to OpenAI completion API. Can be float, `httpx.Timeout` or - None.""" + """Timeout for requests to OpenAI completion API. + + Can be float, `httpx.Timeout` or `None`. + """ headers: Any = None @@ -258,8 +273,9 @@ class OpenAIEmbeddings(BaseModel, Embeddings): """Set this to False to use HuggingFace `transformers` tokenization. For non-OpenAI providers (OpenRouter, Ollama, vLLM, etc.), consider setting - ``check_embedding_ctx_length=False`` instead, as it bypasses tokenization - entirely.""" + `check_embedding_ctx_length=False` instead, as it bypasses tokenization + entirely. + """ tiktoken_model_name: str | None = None """The model name to pass to tiktoken when using this class. @@ -267,12 +283,13 @@ class OpenAIEmbeddings(BaseModel, Embeddings): Tiktoken is used to count the number of tokens in documents to constrain them to be under a certain limit. - By default, when set to `None`, this will be the same as the embedding model name. - However, there are some cases where you may want to use this `Embedding` class with - a model name not supported by tiktoken. This can include when using Azure embeddings - or when using one of the many model providers that expose an OpenAI-like - API but with different models. In those cases, in order to avoid erroring - when tiktoken is called, you can specify a model name to use here. + By default, when set to `None`, this will be the same as the embedding model + name. However, there are some cases where you may want to use this + `Embedding` class with a model name not supported by tiktoken. This can + include when using Azure embeddings or when using one of the many model + providers that expose an OpenAI-like API but with different models. In those + cases, in order to avoid erroring when tiktoken is called, you can specify a + model name to use here. """ show_progress_bar: bool = False @@ -300,24 +317,25 @@ class OpenAIEmbeddings(BaseModel, Embeddings): http_client: Any | None = None """Optional `httpx.Client`. - Only used for sync invocations. Must specify `http_async_client` as well if you'd - like a custom client for async invocations. + Only used for sync invocations. Must specify `http_async_client` as well if + you'd like a custom client for async invocations. """ http_async_client: Any | None = None """Optional `httpx.AsyncClient`. - Only used for async invocations. Must specify `http_client` as well if you'd like a - custom client for sync invocations. + Only used for async invocations. Must specify `http_client` as well if you'd + like a custom client for sync invocations. """ check_embedding_ctx_length: bool = True """Whether to check the token length of inputs and automatically split inputs - longer than embedding_ctx_length. + longer than `embedding_ctx_length`. - Set to ``False`` to send raw text strings directly to the API instead of + Set to `False` to send raw text strings directly to the API instead of tokenizing. Useful for many non-OpenAI providers (e.g. OpenRouter, Ollama, - vLLM).""" + vLLM). + """ model_config = ConfigDict( extra="forbid", populate_by_name=True, protected_namespaces=()