Source code for langchain_openai.chat_models.base

"""OpenAI chat wrapper."""

from __future__ import annotations

import base64
import json
import logging
import os
import sys
import warnings
from io import BytesIO
from math import ceil
from operator import itemgetter
from typing import (
    Any,
    AsyncIterator,
    Callable,
    Dict,
    Iterator,
    List,
    Literal,
    Mapping,
    Optional,
    Sequence,
    Tuple,
    Type,
    TypedDict,
    TypeVar,
    Union,
    cast,
)
from urllib.parse import urlparse

import openai
import tiktoken
from langchain_core.callbacks import (
    AsyncCallbackManagerForLLMRun,
    CallbackManagerForLLMRun,
)
from langchain_core.language_models import LanguageModelInput
from langchain_core.language_models.chat_models import (
    BaseChatModel,
    LangSmithParams,
    agenerate_from_stream,
    generate_from_stream,
)
from langchain_core.messages import (
    AIMessage,
    AIMessageChunk,
    BaseMessage,
    BaseMessageChunk,
    ChatMessage,
    ChatMessageChunk,
    FunctionMessage,
    FunctionMessageChunk,
    HumanMessage,
    HumanMessageChunk,
    InvalidToolCall,
    SystemMessage,
    SystemMessageChunk,
    ToolCall,
    ToolMessage,
    ToolMessageChunk,
)
from langchain_core.messages.ai import UsageMetadata
from langchain_core.messages.tool import tool_call_chunk
from langchain_core.output_parsers import JsonOutputParser, PydanticOutputParser
from langchain_core.output_parsers.base import OutputParserLike
from langchain_core.output_parsers.openai_tools import (
    JsonOutputKeyToolsParser,
    PydanticToolsParser,
    make_invalid_tool_call,
    parse_tool_call,
)
from langchain_core.outputs import ChatGeneration, ChatGenerationChunk, ChatResult
from langchain_core.pydantic_v1 import BaseModel, Field, SecretStr, root_validator
from langchain_core.runnables import Runnable, RunnableMap, RunnablePassthrough, chain
from langchain_core.runnables.config import run_in_executor
from langchain_core.tools import BaseTool
from langchain_core.utils import (
    convert_to_secret_str,
    get_from_dict_or_env,
    get_pydantic_field_names,
)
from langchain_core.utils.function_calling import (
    convert_to_openai_function,
    convert_to_openai_tool,
)
from langchain_core.utils.pydantic import (
    PydanticBaseModel,
    TypeBaseModel,
    is_basemodel_subclass,
)
from langchain_core.utils.utils import build_extra_kwargs

logger = logging.getLogger(__name__)


def _convert_dict_to_message(_dict: Mapping[str, Any]) -> BaseMessage:
    """Convert a dictionary to a LangChain message.

    Args:
        _dict: The dictionary.

    Returns:
        The LangChain message.
    """
    role = _dict.get("role")
    name = _dict.get("name")
    id_ = _dict.get("id")
    if role == "user":
        return HumanMessage(content=_dict.get("content", ""), id=id_, name=name)
    elif role == "assistant":
        # Fix for azure
        # Also OpenAI returns None for tool invocations
        content = _dict.get("content", "") or ""
        additional_kwargs: Dict = {}
        if function_call := _dict.get("function_call"):
            additional_kwargs["function_call"] = dict(function_call)
        tool_calls = []
        invalid_tool_calls = []
        if raw_tool_calls := _dict.get("tool_calls"):
            additional_kwargs["tool_calls"] = raw_tool_calls
            for raw_tool_call in raw_tool_calls:
                try:
                    tool_calls.append(parse_tool_call(raw_tool_call, return_id=True))
                except Exception as e:
                    invalid_tool_calls.append(
                        make_invalid_tool_call(raw_tool_call, str(e))
                    )
        return AIMessage(
            content=content,
            additional_kwargs=additional_kwargs,
            name=name,
            id=id_,
            tool_calls=tool_calls,
            invalid_tool_calls=invalid_tool_calls,
        )
    elif role == "system":
        return SystemMessage(content=_dict.get("content", ""), name=name, id=id_)
    elif role == "function":
        return FunctionMessage(
            content=_dict.get("content", ""), name=cast(str, _dict.get("name")), id=id_
        )
    elif role == "tool":
        additional_kwargs = {}
        if "name" in _dict:
            additional_kwargs["name"] = _dict["name"]
        return ToolMessage(
            content=_dict.get("content", ""),
            tool_call_id=cast(str, _dict.get("tool_call_id")),
            additional_kwargs=additional_kwargs,
            name=name,
            id=id_,
        )
    else:
        return ChatMessage(content=_dict.get("content", ""), role=role, id=id_)  # type: ignore[arg-type]


def _format_message_content(content: Any) -> Any:
    """Format message content."""
    if content and isinstance(content, list):
        # Remove unexpected block types
        formatted_content = []
        for block in content:
            if (
                isinstance(block, dict)
                and "type" in block
                and block["type"] == "tool_use"
            ):
                continue
            else:
                formatted_content.append(block)
    else:
        formatted_content = content

    return formatted_content


def _convert_message_to_dict(message: BaseMessage) -> dict:
    """Convert a LangChain message to a dictionary.

    Args:
        message: The LangChain message.

    Returns:
        The dictionary.
    """
    message_dict: Dict[str, Any] = {"content": _format_message_content(message.content)}
    if (name := message.name or message.additional_kwargs.get("name")) is not None:
        message_dict["name"] = name

    # populate role and additional message data
    if isinstance(message, ChatMessage):
        message_dict["role"] = message.role
    elif isinstance(message, HumanMessage):
        message_dict["role"] = "user"
    elif isinstance(message, AIMessage):
        message_dict["role"] = "assistant"
        if "function_call" in message.additional_kwargs:
            message_dict["function_call"] = message.additional_kwargs["function_call"]
        if message.tool_calls or message.invalid_tool_calls:
            message_dict["tool_calls"] = [
                _lc_tool_call_to_openai_tool_call(tc) for tc in message.tool_calls
            ] + [
                _lc_invalid_tool_call_to_openai_tool_call(tc)
                for tc in message.invalid_tool_calls
            ]
        elif "tool_calls" in message.additional_kwargs:
            message_dict["tool_calls"] = message.additional_kwargs["tool_calls"]
            tool_call_supported_props = {"id", "type", "function"}
            message_dict["tool_calls"] = [
                {k: v for k, v in tool_call.items() if k in tool_call_supported_props}
                for tool_call in message_dict["tool_calls"]
            ]
        else:
            pass
        # If tool calls present, content null value should be None not empty string.
        if "function_call" in message_dict or "tool_calls" in message_dict:
            message_dict["content"] = message_dict["content"] or None
    elif isinstance(message, SystemMessage):
        message_dict["role"] = "system"
    elif isinstance(message, FunctionMessage):
        message_dict["role"] = "function"
    elif isinstance(message, ToolMessage):
        message_dict["role"] = "tool"
        message_dict["tool_call_id"] = message.tool_call_id

        supported_props = {"content", "role", "tool_call_id"}
        message_dict = {k: v for k, v in message_dict.items() if k in supported_props}
    else:
        raise TypeError(f"Got unknown type {message}")
    return message_dict


def _convert_delta_to_message_chunk(
    _dict: Mapping[str, Any], default_class: Type[BaseMessageChunk]
) -> BaseMessageChunk:
    id_ = _dict.get("id")
    role = cast(str, _dict.get("role"))
    content = cast(str, _dict.get("content") or "")
    additional_kwargs: Dict = {}
    if _dict.get("function_call"):
        function_call = dict(_dict["function_call"])
        if "name" in function_call and function_call["name"] is None:
            function_call["name"] = ""
        additional_kwargs["function_call"] = function_call
    tool_call_chunks = []
    if raw_tool_calls := _dict.get("tool_calls"):
        additional_kwargs["tool_calls"] = raw_tool_calls
        try:
            tool_call_chunks = [
                tool_call_chunk(
                    name=rtc["function"].get("name"),
                    args=rtc["function"].get("arguments"),
                    id=rtc.get("id"),
                    index=rtc["index"],
                )
                for rtc in raw_tool_calls
            ]
        except KeyError:
            pass

    if role == "user" or default_class == HumanMessageChunk:
        return HumanMessageChunk(content=content, id=id_)
    elif role == "assistant" or default_class == AIMessageChunk:
        return AIMessageChunk(
            content=content,
            additional_kwargs=additional_kwargs,
            id=id_,
            tool_call_chunks=tool_call_chunks,  # type: ignore[arg-type]
        )
    elif role == "system" or default_class == SystemMessageChunk:
        return SystemMessageChunk(content=content, id=id_)
    elif role == "function" or default_class == FunctionMessageChunk:
        return FunctionMessageChunk(content=content, name=_dict["name"], id=id_)
    elif role == "tool" or default_class == ToolMessageChunk:
        return ToolMessageChunk(
            content=content, tool_call_id=_dict["tool_call_id"], id=id_
        )
    elif role or default_class == ChatMessageChunk:
        return ChatMessageChunk(content=content, role=role, id=id_)
    else:
        return default_class(content=content, id=id_)  # type: ignore


def _convert_chunk_to_generation_chunk(
    chunk: dict, default_chunk_class: Type, base_generation_info: Optional[Dict]
) -> Optional[ChatGenerationChunk]:
    token_usage = chunk.get("usage")
    choices = chunk.get("choices", [])
    usage_metadata: Optional[UsageMetadata] = (
        UsageMetadata(
            input_tokens=token_usage.get("prompt_tokens", 0),
            output_tokens=token_usage.get("completion_tokens", 0),
            total_tokens=token_usage.get("total_tokens", 0),
        )
        if token_usage
        else None
    )

    if len(choices) == 0:
        # logprobs is implicitly None
        generation_chunk = ChatGenerationChunk(
            message=default_chunk_class(content="", usage_metadata=usage_metadata)
        )
        return generation_chunk

    choice = choices[0]
    if choice["delta"] is None:
        return None

    message_chunk = _convert_delta_to_message_chunk(
        choice["delta"], default_chunk_class
    )
    generation_info = {**base_generation_info} if base_generation_info else {}

    if finish_reason := choice.get("finish_reason"):
        generation_info["finish_reason"] = finish_reason
        if model_name := chunk.get("model"):
            generation_info["model_name"] = model_name
        if system_fingerprint := chunk.get("system_fingerprint"):
            generation_info["system_fingerprint"] = system_fingerprint

    logprobs = choice.get("logprobs")
    if logprobs:
        generation_info["logprobs"] = logprobs

    if usage_metadata and isinstance(message_chunk, AIMessageChunk):
        message_chunk.usage_metadata = usage_metadata

    generation_chunk = ChatGenerationChunk(
        message=message_chunk, generation_info=generation_info or None
    )
    return generation_chunk


def _update_token_usage(
    overall_token_usage: Union[int, dict], new_usage: Union[int, dict]
) -> Union[int, dict]:
    # Token usage is either ints or dictionaries
    # `reasoning_tokens` is nested inside `completion_tokens_details`
    if isinstance(new_usage, int):
        if not isinstance(overall_token_usage, int):
            raise ValueError(
                f"Got different types for token usage: "
                f"{type(new_usage)} and {type(overall_token_usage)}"
            )
        return new_usage + overall_token_usage
    elif isinstance(new_usage, dict):
        if not isinstance(overall_token_usage, dict):
            raise ValueError(
                f"Got different types for token usage: "
                f"{type(new_usage)} and {type(overall_token_usage)}"
            )
        return {
            k: _update_token_usage(overall_token_usage.get(k, 0), v)
            for k, v in new_usage.items()
        }
    else:
        warnings.warn(f"Unexpected type for token usage: {type(new_usage)}")
        return new_usage


class _FunctionCall(TypedDict):
    name: str


_BM = TypeVar("_BM", bound=BaseModel)
_DictOrPydanticClass = Union[Dict[str, Any], Type[_BM], Type]
_DictOrPydantic = Union[Dict, _BM]


class _AllReturnType(TypedDict):
    raw: BaseMessage
    parsed: Optional[_DictOrPydantic]
    parsing_error: Optional[BaseException]


[docs]class BaseChatOpenAI(BaseChatModel): client: Any = Field(default=None, exclude=True) #: :meta private: async_client: Any = Field(default=None, exclude=True) #: :meta private: root_client: Any = Field(default=None, exclude=True) #: :meta private: root_async_client: Any = Field(default=None, exclude=True) #: :meta private: model_name: str = Field(default="gpt-3.5-turbo", alias="model") """Model name to use.""" temperature: float = 0.7 """What sampling temperature to use.""" model_kwargs: Dict[str, Any] = Field(default_factory=dict) """Holds any model parameters valid for `create` call not explicitly specified.""" openai_api_key: Optional[SecretStr] = Field(default=None, alias="api_key") """Automatically inferred from env var `OPENAI_API_KEY` if not provided.""" openai_api_base: Optional[str] = Field(default=None, alias="base_url") """Base URL path for API requests, leave blank if not using a proxy or service emulator.""" openai_organization: Optional[str] = Field(default=None, alias="organization") """Automatically inferred from env var `OPENAI_ORG_ID` if not provided.""" # to support explicit proxy for OpenAI openai_proxy: Optional[str] = None request_timeout: Union[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.""" max_retries: int = 2 """Maximum number of retries to make when generating.""" presence_penalty: Optional[float] = None """Penalizes repeated tokens.""" frequency_penalty: Optional[float] = None """Penalizes repeated tokens according to frequency.""" seed: Optional[int] = None """Seed for generation""" logprobs: Optional[bool] = None """Whether to return logprobs.""" top_logprobs: Optional[int] = None """Number of most likely tokens to return at each token position, each with an associated log probability. `logprobs` must be set to true if this parameter is used.""" logit_bias: Optional[Dict[int, int]] = None """Modify the likelihood of specified tokens appearing in the completion.""" streaming: bool = False """Whether to stream the results or not.""" n: int = 1 """Number of chat completions to generate for each prompt.""" top_p: Optional[float] = None """Total probability mass of tokens to consider at each step.""" max_tokens: Optional[int] = None """Maximum number of tokens to generate.""" tiktoken_model_name: Optional[str] = None """The model name to pass to tiktoken when using this class. 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.""" default_headers: Union[Mapping[str, str], None] = None default_query: Union[Mapping[str, object], None] = None # Configure a custom httpx client. See the # [httpx documentation](https://www.python-httpx.org/api/#client) for more details. http_client: Union[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. """ http_async_client: Union[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.""" stop: Optional[Union[List[str], str]] = Field(default=None, alias="stop_sequences") """Default stop sequences.""" extra_body: Optional[Mapping[str, Any]] = None """Optional additional JSON properties to include in the request parameters when making requests to OpenAI compatible APIs, such as vLLM.""" include_response_headers: bool = False """Whether to include response headers in the output message response_metadata.""" class Config: """Configuration for this pydantic object.""" allow_population_by_field_name = True @root_validator(pre=True) def build_extra(cls, values: Dict[str, Any]) -> Dict[str, Any]: """Build extra kwargs from additional params that were passed in.""" all_required_field_names = get_pydantic_field_names(cls) extra = values.get("model_kwargs", {}) values["model_kwargs"] = build_extra_kwargs( extra, values, all_required_field_names ) return values @root_validator(pre=False, skip_on_failure=True, allow_reuse=True) def validate_environment(cls, values: Dict) -> Dict: """Validate that api key and python package exists in environment.""" if values["n"] < 1: raise ValueError("n must be at least 1.") if values["n"] > 1 and values["streaming"]: raise ValueError("n must be 1 when streaming.") values["openai_api_key"] = convert_to_secret_str( get_from_dict_or_env(values, "openai_api_key", "OPENAI_API_KEY") ) # Check OPENAI_ORGANIZATION for backwards compatibility. values["openai_organization"] = ( values["openai_organization"] or os.getenv("OPENAI_ORG_ID") or os.getenv("OPENAI_ORGANIZATION") ) values["openai_api_base"] = values["openai_api_base"] or os.getenv( "OPENAI_API_BASE" ) values["openai_proxy"] = get_from_dict_or_env( values, "openai_proxy", "OPENAI_PROXY", default="" ) client_params = { "api_key": ( values["openai_api_key"].get_secret_value() if values["openai_api_key"] else None ), "organization": values["openai_organization"], "base_url": values["openai_api_base"], "timeout": values["request_timeout"], "max_retries": values["max_retries"], "default_headers": values["default_headers"], "default_query": values["default_query"], } if values["openai_proxy"] and ( values["http_client"] or values["http_async_client"] ): openai_proxy = values["openai_proxy"] http_client = values["http_client"] http_async_client = values["http_async_client"] raise ValueError( "Cannot specify 'openai_proxy' if one of " "'http_client'/'http_async_client' is already specified. Received:\n" f"{openai_proxy=}\n{http_client=}\n{http_async_client=}" ) if not values.get("client"): if values["openai_proxy"] and not values["http_client"]: try: import httpx except ImportError as e: raise ImportError( "Could not import httpx python package. " "Please install it with `pip install httpx`." ) from e values["http_client"] = httpx.Client(proxy=values["openai_proxy"]) sync_specific = {"http_client": values["http_client"]} values["root_client"] = openai.OpenAI(**client_params, **sync_specific) values["client"] = values["root_client"].chat.completions if not values.get("async_client"): if values["openai_proxy"] and not values["http_async_client"]: try: import httpx except ImportError as e: raise ImportError( "Could not import httpx python package. " "Please install it with `pip install httpx`." ) from e values["http_async_client"] = httpx.AsyncClient( proxy=values["openai_proxy"] ) async_specific = {"http_client": values["http_async_client"]} values["root_async_client"] = openai.AsyncOpenAI( **client_params, **async_specific ) values["async_client"] = values["root_async_client"].chat.completions return values @property def _default_params(self) -> Dict[str, Any]: """Get the default parameters for calling OpenAI API.""" exclude_if_none = { "presence_penalty": self.presence_penalty, "frequency_penalty": self.frequency_penalty, "seed": self.seed, "top_p": self.top_p, "logprobs": self.logprobs, "top_logprobs": self.top_logprobs, "logit_bias": self.logit_bias, "stop": self.stop or None, # also exclude empty list for this "max_tokens": self.max_tokens, "extra_body": self.extra_body, } params = { "model": self.model_name, "stream": self.streaming, "n": self.n, "temperature": self.temperature, **{k: v for k, v in exclude_if_none.items() if v is not None}, **self.model_kwargs, } return params def _combine_llm_outputs(self, llm_outputs: List[Optional[dict]]) -> dict: overall_token_usage: dict = {} system_fingerprint = None for output in llm_outputs: if output is None: # Happens in streaming continue token_usage = output["token_usage"] if token_usage is not None: for k, v in token_usage.items(): if k in overall_token_usage: overall_token_usage[k] = _update_token_usage( overall_token_usage[k], v ) else: overall_token_usage[k] = v if system_fingerprint is None: system_fingerprint = output.get("system_fingerprint") combined = {"token_usage": overall_token_usage, "model_name": self.model_name} if system_fingerprint: combined["system_fingerprint"] = system_fingerprint return combined def _stream( self, messages: List[BaseMessage], stop: Optional[List[str]] = None, run_manager: Optional[CallbackManagerForLLMRun] = None, **kwargs: Any, ) -> Iterator[ChatGenerationChunk]: kwargs["stream"] = True payload = self._get_request_payload(messages, stop=stop, **kwargs) default_chunk_class: Type[BaseMessageChunk] = AIMessageChunk base_generation_info = {} if "response_format" in payload and is_basemodel_subclass( payload["response_format"] ): # TODO: Add support for streaming with Pydantic response_format. warnings.warn("Streaming with Pydantic response_format not yet supported.") chat_result = self._generate( messages, stop, run_manager=run_manager, **kwargs ) msg = chat_result.generations[0].message yield ChatGenerationChunk( message=AIMessageChunk( **msg.dict(exclude={"type", "additional_kwargs"}), # preserve the "parsed" Pydantic object without converting to dict additional_kwargs=msg.additional_kwargs, ), generation_info=chat_result.generations[0].generation_info, ) return if self.include_response_headers: raw_response = self.client.with_raw_response.create(**payload) response = raw_response.parse() base_generation_info = {"headers": dict(raw_response.headers)} else: response = self.client.create(**payload) with response: is_first_chunk = True for chunk in response: if not isinstance(chunk, dict): chunk = chunk.model_dump() generation_chunk = _convert_chunk_to_generation_chunk( chunk, default_chunk_class, base_generation_info if is_first_chunk else {}, ) if generation_chunk is None: continue default_chunk_class = generation_chunk.message.__class__ logprobs = (generation_chunk.generation_info or {}).get("logprobs") if run_manager: run_manager.on_llm_new_token( generation_chunk.text, chunk=generation_chunk, logprobs=logprobs ) is_first_chunk = False yield generation_chunk def _generate( self, messages: List[BaseMessage], stop: Optional[List[str]] = None, run_manager: Optional[CallbackManagerForLLMRun] = None, **kwargs: Any, ) -> ChatResult: if self.streaming: stream_iter = self._stream( messages, stop=stop, run_manager=run_manager, **kwargs ) return generate_from_stream(stream_iter) payload = self._get_request_payload(messages, stop=stop, **kwargs) generation_info = None if "response_format" in payload: if self.include_response_headers: warnings.warn( "Cannot currently include response headers when response_format is " "specified." ) payload.pop("stream") response = self.root_client.beta.chat.completions.parse(**payload) elif self.include_response_headers: raw_response = self.client.with_raw_response.create(**payload) response = raw_response.parse() generation_info = {"headers": dict(raw_response.headers)} else: response = self.client.create(**payload) return self._create_chat_result(response, generation_info) def _get_request_payload( self, input_: LanguageModelInput, *, stop: Optional[List[str]] = None, **kwargs: Any, ) -> dict: messages = self._convert_input(input_).to_messages() if stop is not None: kwargs["stop"] = stop return { "messages": [_convert_message_to_dict(m) for m in messages], **self._default_params, **kwargs, } def _create_chat_result( self, response: Union[dict, openai.BaseModel], generation_info: Optional[Dict] = None, ) -> ChatResult: generations = [] response_dict = ( response if isinstance(response, dict) else response.model_dump() ) # Sometimes the AI Model calling will get error, we should raise it. # Otherwise, the next code 'choices.extend(response["choices"])' # will throw a "TypeError: 'NoneType' object is not iterable" error # to mask the true error. Because 'response["choices"]' is None. if response_dict.get("error"): raise ValueError(response_dict.get("error")) token_usage = response_dict.get("usage", {}) for res in response_dict["choices"]: message = _convert_dict_to_message(res["message"]) if token_usage and isinstance(message, AIMessage): message.usage_metadata = { "input_tokens": token_usage.get("prompt_tokens", 0), "output_tokens": token_usage.get("completion_tokens", 0), "total_tokens": token_usage.get("total_tokens", 0), } generation_info = generation_info or {} generation_info["finish_reason"] = ( res.get("finish_reason") if res.get("finish_reason") is not None else generation_info.get("finish_reason") ) if "logprobs" in res: generation_info["logprobs"] = res["logprobs"] gen = ChatGeneration(message=message, generation_info=generation_info) generations.append(gen) llm_output = { "token_usage": token_usage, "model_name": response_dict.get("model", self.model_name), "system_fingerprint": response_dict.get("system_fingerprint", ""), } if isinstance(response, openai.BaseModel) and getattr( response, "choices", None ): message = response.choices[0].message # type: ignore[attr-defined] if hasattr(message, "parsed"): generations[0].message.additional_kwargs["parsed"] = message.parsed if hasattr(message, "refusal"): generations[0].message.additional_kwargs["refusal"] = message.refusal return ChatResult(generations=generations, llm_output=llm_output) async def _astream( self, messages: List[BaseMessage], stop: Optional[List[str]] = None, run_manager: Optional[AsyncCallbackManagerForLLMRun] = None, **kwargs: Any, ) -> AsyncIterator[ChatGenerationChunk]: kwargs["stream"] = True payload = self._get_request_payload(messages, stop=stop, **kwargs) default_chunk_class: Type[BaseMessageChunk] = AIMessageChunk base_generation_info = {} if "response_format" in payload and is_basemodel_subclass( payload["response_format"] ): # TODO: Add support for streaming with Pydantic response_format. warnings.warn("Streaming with Pydantic response_format not yet supported.") chat_result = await self._agenerate( messages, stop, run_manager=run_manager, **kwargs ) msg = chat_result.generations[0].message yield ChatGenerationChunk( message=AIMessageChunk( **msg.dict(exclude={"type", "additional_kwargs"}), # preserve the "parsed" Pydantic object without converting to dict additional_kwargs=msg.additional_kwargs, ), generation_info=chat_result.generations[0].generation_info, ) return if self.include_response_headers: raw_response = await self.async_client.with_raw_response.create(**payload) response = raw_response.parse() base_generation_info = {"headers": dict(raw_response.headers)} else: response = await self.async_client.create(**payload) async with response: is_first_chunk = True async for chunk in response: if not isinstance(chunk, dict): chunk = chunk.model_dump() generation_chunk = _convert_chunk_to_generation_chunk( chunk, default_chunk_class, base_generation_info if is_first_chunk else {}, ) if generation_chunk is None: continue default_chunk_class = generation_chunk.message.__class__ logprobs = (generation_chunk.generation_info or {}).get("logprobs") if run_manager: await run_manager.on_llm_new_token( generation_chunk.text, chunk=generation_chunk, logprobs=logprobs ) is_first_chunk = False yield generation_chunk async def _agenerate( self, messages: List[BaseMessage], stop: Optional[List[str]] = None, run_manager: Optional[AsyncCallbackManagerForLLMRun] = None, **kwargs: Any, ) -> ChatResult: if self.streaming: stream_iter = self._astream( messages, stop=stop, run_manager=run_manager, **kwargs ) return await agenerate_from_stream(stream_iter) payload = self._get_request_payload(messages, stop=stop, **kwargs) generation_info = None if "response_format" in payload: if self.include_response_headers: warnings.warn( "Cannot currently include response headers when response_format is " "specified." ) payload.pop("stream") response = await self.root_async_client.beta.chat.completions.parse( **payload ) elif self.include_response_headers: raw_response = await self.async_client.with_raw_response.create(**payload) response = raw_response.parse() generation_info = {"headers": dict(raw_response.headers)} else: response = await self.async_client.create(**payload) return await run_in_executor( None, self._create_chat_result, response, generation_info ) @property def _identifying_params(self) -> Dict[str, Any]: """Get the identifying parameters.""" return {"model_name": self.model_name, **self._default_params} def _get_invocation_params( self, stop: Optional[List[str]] = None, **kwargs: Any ) -> Dict[str, Any]: """Get the parameters used to invoke the model.""" return { "model": self.model_name, **super()._get_invocation_params(stop=stop), **self._default_params, **kwargs, } def _get_ls_params( self, stop: Optional[List[str]] = None, **kwargs: Any ) -> LangSmithParams: """Get standard params for tracing.""" params = self._get_invocation_params(stop=stop, **kwargs) ls_params = LangSmithParams( ls_provider="openai", ls_model_name=self.model_name, ls_model_type="chat", ls_temperature=params.get("temperature", self.temperature), ) if ls_max_tokens := params.get("max_tokens", self.max_tokens): ls_params["ls_max_tokens"] = ls_max_tokens if ls_stop := stop or params.get("stop", None): ls_params["ls_stop"] = ls_stop return ls_params @property def _llm_type(self) -> str: """Return type of chat model.""" return "openai-chat" def _get_encoding_model(self) -> Tuple[str, tiktoken.Encoding]: if self.tiktoken_model_name is not None: model = self.tiktoken_model_name else: model = self.model_name try: encoding = tiktoken.encoding_for_model(model) except KeyError: model = "cl100k_base" encoding = tiktoken.get_encoding(model) return model, encoding
[docs] def get_token_ids(self, text: str) -> List[int]: """Get the tokens present in the text with tiktoken package.""" if self.custom_get_token_ids is not None: return self.custom_get_token_ids(text) # tiktoken NOT supported for Python 3.7 or below if sys.version_info[1] <= 7: return super().get_token_ids(text) _, encoding_model = self._get_encoding_model() return encoding_model.encode(text)
# TODO: Count bound tools as part of input.
[docs] def get_num_tokens_from_messages(self, messages: List[BaseMessage]) -> int: """Calculate num tokens for gpt-3.5-turbo and gpt-4 with tiktoken package. **Requirements**: You must have the ``pillow`` installed if you want to count image tokens if you are specifying the image as a base64 string, and you must have both ``pillow`` and ``httpx`` installed if you are specifying the image as a URL. If these aren't installed image inputs will be ignored in token counting. OpenAI reference: https://github.com/openai/openai-cookbook/blob/ main/examples/How_to_format_inputs_to_ChatGPT_models.ipynb""" if sys.version_info[1] <= 7: return super().get_num_tokens_from_messages(messages) model, encoding = self._get_encoding_model() if model.startswith("gpt-3.5-turbo-0301"): # every message follows <im_start>{role/name}\n{content}<im_end>\n tokens_per_message = 4 # if there's a name, the role is omitted tokens_per_name = -1 elif model.startswith("gpt-3.5-turbo") or model.startswith("gpt-4"): tokens_per_message = 3 tokens_per_name = 1 else: raise NotImplementedError( f"get_num_tokens_from_messages() is not presently implemented " f"for model {model}. See " "https://platform.openai.com/docs/guides/text-generation/managing-tokens" # noqa: E501 " for information on how messages are converted to tokens." ) num_tokens = 0 messages_dict = [_convert_message_to_dict(m) for m in messages] for message in messages_dict: num_tokens += tokens_per_message for key, value in message.items(): # This is an inferred approximation. OpenAI does not document how to # count tool message tokens. if key == "tool_call_id": num_tokens += 3 continue if isinstance(value, list): # content or tool calls for val in value: if isinstance(val, str) or val["type"] == "text": text = val["text"] if isinstance(val, dict) else val num_tokens += len(encoding.encode(text)) elif val["type"] == "image_url": if val["image_url"].get("detail") == "low": num_tokens += 85 else: image_size = _url_to_size(val["image_url"]["url"]) if not image_size: continue num_tokens += _count_image_tokens(*image_size) # Tool/function call token counting is not documented by OpenAI. # This is an approximation. elif val["type"] == "function": num_tokens += len( encoding.encode(val["function"]["arguments"]) ) num_tokens += len(encoding.encode(val["function"]["name"])) else: raise ValueError( f"Unrecognized content block type\n\n{val}" ) elif not value: continue else: # Cast str(value) in case the message value is not a string # This occurs with function messages num_tokens += len(encoding.encode(str(value))) if key == "name": num_tokens += tokens_per_name # every reply is primed with <im_start>assistant num_tokens += 3 return num_tokens
[docs] def bind_functions( self, functions: Sequence[Union[Dict[str, Any], Type[BaseModel], Callable, BaseTool]], function_call: Optional[ Union[_FunctionCall, str, Literal["auto", "none"]] ] = None, **kwargs: Any, ) -> Runnable[LanguageModelInput, BaseMessage]: """Bind functions (and other objects) to this chat model. Assumes model is compatible with OpenAI function-calling API. NOTE: Using bind_tools is recommended instead, as the `functions` and `function_call` request parameters are officially marked as deprecated by OpenAI. Args: functions: A list of function definitions to bind to this chat model. Can be a dictionary, pydantic model, or callable. Pydantic models and callables will be automatically converted to their schema dictionary representation. function_call: Which function to require the model to call. Must be the name of the single provided function or "auto" to automatically determine which function to call (if any). **kwargs: Any additional parameters to pass to the :class:`~langchain.runnable.Runnable` constructor. """ formatted_functions = [convert_to_openai_function(fn) for fn in functions] if function_call is not None: function_call = ( {"name": function_call} if isinstance(function_call, str) and function_call not in ("auto", "none") else function_call ) if isinstance(function_call, dict) and len(formatted_functions) != 1: raise ValueError( "When specifying `function_call`, you must provide exactly one " "function." ) if ( isinstance(function_call, dict) and formatted_functions[0]["name"] != function_call["name"] ): raise ValueError( f"Function call {function_call} was specified, but the only " f"provided function was {formatted_functions[0]['name']}." ) kwargs = {**kwargs, "function_call": function_call} return super().bind(functions=formatted_functions, **kwargs)
[docs] def bind_tools( self, tools: Sequence[Union[Dict[str, Any], Type, Callable, BaseTool]], *, tool_choice: Optional[ Union[dict, str, Literal["auto", "none", "required", "any"], bool] ] = None, strict: Optional[bool] = None, **kwargs: Any, ) -> Runnable[LanguageModelInput, BaseMessage]: """Bind tool-like objects to this chat model. Assumes model is compatible with OpenAI tool-calling API. .. versionchanged:: 0.1.21 Support for ``strict`` argument added. Args: tools: A list of tool definitions to bind to this chat model. Supports any tool definition handled by :meth:`langchain_core.utils.function_calling.convert_to_openai_tool`. tool_choice: Which tool to require the model to call. Options are: - str of the form ``"<<tool_name>>"``: calls <<tool_name>> tool. - ``"auto"``: automatically selects a tool (including no tool). - ``"none"``: does not call a tool. - ``"any"`` or ``"required"`` or ``True``: force at least one tool to be called. - dict of the form ``{"type": "function", "function": {"name": <<tool_name>>}}``: calls <<tool_name>> tool. - ``False`` or ``None``: no effect, default OpenAI behavior. strict: If True, model output is guaranteed to exactly match the JSON Schema provided in the tool definition. If True, the input schema will be validated according to https://platform.openai.com/docs/guides/structured-outputs/supported-schemas. If False, input schema will not be validated and model output will not be validated. If None, ``strict`` argument will not be passed to the model. .. versionadded:: 0.1.21 kwargs: Any additional parameters are passed directly to ``self.bind(**kwargs)``. """ # noqa: E501 formatted_tools = [ convert_to_openai_tool(tool, strict=strict) for tool in tools ] if tool_choice: if isinstance(tool_choice, str): # tool_choice is a tool/function name if tool_choice not in ("auto", "none", "any", "required"): tool_choice = { "type": "function", "function": {"name": tool_choice}, } # 'any' is not natively supported by OpenAI API. # We support 'any' since other models use this instead of 'required'. if tool_choice == "any": tool_choice = "required" elif isinstance(tool_choice, bool): tool_choice = "required" elif isinstance(tool_choice, dict): tool_names = [ formatted_tool["function"]["name"] for formatted_tool in formatted_tools ] if not any( tool_name == tool_choice["function"]["name"] for tool_name in tool_names ): raise ValueError( f"Tool choice {tool_choice} was specified, but the only " f"provided tools were {tool_names}." ) else: raise ValueError( f"Unrecognized tool_choice type. Expected str, bool or dict. " f"Received: {tool_choice}" ) kwargs["tool_choice"] = tool_choice return super().bind(tools=formatted_tools, **kwargs)
[docs] def with_structured_output( self, schema: Optional[_DictOrPydanticClass] = None, *, method: Literal[ "function_calling", "json_mode", "json_schema" ] = "function_calling", include_raw: bool = False, strict: Optional[bool] = None, **kwargs: Any, ) -> Runnable[LanguageModelInput, _DictOrPydantic]: """Model wrapper that returns outputs formatted to match the given schema. Args: schema: The output schema. Can be passed in as: - an OpenAI function/tool schema, - a JSON Schema, - a TypedDict class (support added in 0.1.20), - or a Pydantic class. If ``schema`` is a Pydantic class then the model output will be a Pydantic instance of that class, and the model-generated fields will be validated by the Pydantic class. Otherwise the model output will be a dict and will not be validated. See :meth:`langchain_core.utils.function_calling.convert_to_openai_tool` for more on how to properly specify types and descriptions of schema fields when specifying a Pydantic or TypedDict class. method: The method for steering model generation, one of: - "function_calling": Uses OpenAI's tool-calling (formerly called function calling) API: https://platform.openai.com/docs/guides/function-calling - "json_schema": Uses OpenAI's Structured Output API: https://platform.openai.com/docs/guides/structured-outputs Supported for "gpt-4o-mini", "gpt-4o-2024-08-06", and later models. - "json_mode": Uses OpenAI's JSON mode. Note that if using JSON mode then you must include instructions for formatting the output into the desired schema into the model call: https://platform.openai.com/docs/guides/structured-outputs/json-mode Learn more about the differences between the methods and which models support which methods here: - https://platform.openai.com/docs/guides/structured-outputs/structured-outputs-vs-json-mode - https://platform.openai.com/docs/guides/structured-outputs/function-calling-vs-response-format include_raw: If False then only the parsed structured output is returned. If an error occurs during model output parsing it will be raised. If True then both the raw model response (a BaseMessage) and the parsed model response will be returned. If an error occurs during output parsing it will be caught and returned as well. The final output is always a dict with keys "raw", "parsed", and "parsing_error". strict: - True: Model output is guaranteed to exactly match the schema. The input schema will also be validated according to https://platform.openai.com/docs/guides/structured-outputs/supported-schemas - False: Input schema will not be validated and model output will not be validated. - None: ``strict`` argument will not be passed to the model. If ``method`` is "json_schema" defaults to True. If ``method`` is "function_calling" or "json_mode" defaults to None. Can only be non-null if ``method`` is "function_calling" or "json_schema". kwargs: Additional keyword args aren't supported. Returns: A Runnable that takes same inputs as a :class:`langchain_core.language_models.chat.BaseChatModel`. | If ``include_raw`` is False and ``schema`` is a Pydantic class, Runnable outputs an instance of ``schema`` (i.e., a Pydantic object). Otherwise, if ``include_raw`` is False then Runnable outputs a dict. | If ``include_raw`` is True, then Runnable outputs a dict with keys: - "raw": BaseMessage - "parsed": None if there was a parsing error, otherwise the type depends on the ``schema`` as described above. - "parsing_error": Optional[BaseException] .. versionchanged:: 0.1.20 Added support for TypedDict class ``schema``. .. versionchanged:: 0.1.21 Support for ``strict`` argument added. Support for ``method`` = "json_schema" added. .. note:: Planned breaking changes in version `0.2.0` - ``method`` default will be changed to "json_schema" from "function_calling". - ``strict`` will default to True when ``method`` is "function_calling" as of version `0.2.0`. .. dropdown:: Example: schema=Pydantic class, method="function_calling", include_raw=False, strict=True Note, OpenAI has a number of restrictions on what types of schemas can be provided if ``strict`` = True. When using Pydantic, our model cannot specify any Field metadata (like min/max constraints) and fields cannot have default values. See all constraints here: https://platform.openai.com/docs/guides/structured-outputs/supported-schemas .. code-block:: python from typing import Optional from langchain_openai import ChatOpenAI from langchain_core.pydantic_v1 import BaseModel, Field class AnswerWithJustification(BaseModel): '''An answer to the user question along with justification for the answer.''' answer: str justification: Optional[str] = Field( default=..., description="A justification for the answer." ) llm = ChatOpenAI(model="gpt-4o", temperature=0) structured_llm = llm.with_structured_output( AnswerWithJustification, strict=True ) structured_llm.invoke( "What weighs more a pound of bricks or a pound of feathers" ) # -> AnswerWithJustification( # answer='They weigh the same', # justification='Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ.' # ) .. dropdown:: Example: schema=Pydantic class, method="function_calling", include_raw=True .. code-block:: python from langchain_openai import ChatOpenAI from langchain_core.pydantic_v1 import BaseModel class AnswerWithJustification(BaseModel): '''An answer to the user question along with justification for the answer.''' answer: str justification: str llm = ChatOpenAI(model="gpt-4o", temperature=0) structured_llm = llm.with_structured_output( AnswerWithJustification, include_raw=True ) structured_llm.invoke( "What weighs more a pound of bricks or a pound of feathers" ) # -> { # 'raw': AIMessage(content='', additional_kwargs={'tool_calls': [{'id': 'call_Ao02pnFYXD6GN1yzc0uXPsvF', 'function': {'arguments': '{"answer":"They weigh the same.","justification":"Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ."}', 'name': 'AnswerWithJustification'}, 'type': 'function'}]}), # 'parsed': AnswerWithJustification(answer='They weigh the same.', justification='Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ.'), # 'parsing_error': None # } .. dropdown:: Example: schema=TypedDict class, method="function_calling", include_raw=False .. code-block:: python # IMPORTANT: If you are using Python <=3.8, you need to import Annotated # from typing_extensions, not from typing. from typing_extensions import Annotated, TypedDict from langchain_openai import ChatOpenAI class AnswerWithJustification(TypedDict): '''An answer to the user question along with justification for the answer.''' answer: str justification: Annotated[ Optional[str], None, "A justification for the answer." ] llm = ChatOpenAI(model="gpt-4o", temperature=0) structured_llm = llm.with_structured_output(AnswerWithJustification) structured_llm.invoke( "What weighs more a pound of bricks or a pound of feathers" ) # -> { # 'answer': 'They weigh the same', # 'justification': 'Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume and density of the two substances differ.' # } .. dropdown:: Example: schema=OpenAI function schema, method="function_calling", include_raw=False .. code-block:: python from langchain_openai import ChatOpenAI oai_schema = { 'name': 'AnswerWithJustification', 'description': 'An answer to the user question along with justification for the answer.', 'parameters': { 'type': 'object', 'properties': { 'answer': {'type': 'string'}, 'justification': {'description': 'A justification for the answer.', 'type': 'string'} }, 'required': ['answer'] } } llm = ChatOpenAI(model="gpt-4o", temperature=0) structured_llm = llm.with_structured_output(oai_schema) structured_llm.invoke( "What weighs more a pound of bricks or a pound of feathers" ) # -> { # 'answer': 'They weigh the same', # 'justification': 'Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume and density of the two substances differ.' # } .. dropdown:: Example: schema=Pydantic class, method="json_mode", include_raw=True .. code-block:: from langchain_openai import ChatOpenAI from langchain_core.pydantic_v1 import BaseModel class AnswerWithJustification(BaseModel): answer: str justification: str llm = ChatOpenAI(model="gpt-4o", temperature=0) structured_llm = llm.with_structured_output( AnswerWithJustification, method="json_mode", include_raw=True ) structured_llm.invoke( "Answer the following question. " "Make sure to return a JSON blob with keys 'answer' and 'justification'.\\n\\n" "What's heavier a pound of bricks or a pound of feathers?" ) # -> { # 'raw': AIMessage(content='{\\n "answer": "They are both the same weight.",\\n "justification": "Both a pound of bricks and a pound of feathers weigh one pound. The difference lies in the volume and density of the materials, not the weight." \\n}'), # 'parsed': AnswerWithJustification(answer='They are both the same weight.', justification='Both a pound of bricks and a pound of feathers weigh one pound. The difference lies in the volume and density of the materials, not the weight.'), # 'parsing_error': None # } .. dropdown:: Example: schema=None, method="json_mode", include_raw=True .. code-block:: structured_llm = llm.with_structured_output(method="json_mode", include_raw=True) structured_llm.invoke( "Answer the following question. " "Make sure to return a JSON blob with keys 'answer' and 'justification'.\\n\\n" "What's heavier a pound of bricks or a pound of feathers?" ) # -> { # 'raw': AIMessage(content='{\\n "answer": "They are both the same weight.",\\n "justification": "Both a pound of bricks and a pound of feathers weigh one pound. The difference lies in the volume and density of the materials, not the weight." \\n}'), # 'parsed': { # 'answer': 'They are both the same weight.', # 'justification': 'Both a pound of bricks and a pound of feathers weigh one pound. The difference lies in the volume and density of the materials, not the weight.' # }, # 'parsing_error': None # } """ # noqa: E501 if kwargs: raise ValueError(f"Received unsupported arguments {kwargs}") if strict is not None and method == "json_mode": raise ValueError( "Argument `strict` is not supported with `method`='json_mode'" ) is_pydantic_schema = _is_pydantic_class(schema) if method == "function_calling": if schema is None: raise ValueError( "schema must be specified when method is not 'json_mode'. " "Received None." ) tool_name = convert_to_openai_tool(schema)["function"]["name"] llm = self.bind_tools( [schema], tool_choice=tool_name, parallel_tool_calls=False, strict=strict, ) if is_pydantic_schema: output_parser: OutputParserLike = PydanticToolsParser( tools=[schema], # type: ignore[list-item] first_tool_only=True, # type: ignore[list-item] ) else: output_parser = JsonOutputKeyToolsParser( key_name=tool_name, first_tool_only=True ) elif method == "json_mode": llm = self.bind(response_format={"type": "json_object"}) output_parser = ( PydanticOutputParser(pydantic_object=schema) # type: ignore[arg-type] if is_pydantic_schema else JsonOutputParser() ) elif method == "json_schema": if schema is None: raise ValueError( "schema must be specified when method is not 'json_mode'. " "Received None." ) strict = strict if strict is not None else True response_format = _convert_to_openai_response_format(schema, strict=strict) llm = self.bind(response_format=response_format) output_parser = ( cast(Runnable, _oai_structured_outputs_parser) if is_pydantic_schema else JsonOutputParser() ) else: raise ValueError( f"Unrecognized method argument. Expected one of 'function_calling' or " f"'json_mode'. Received: '{method}'" ) if include_raw: parser_assign = RunnablePassthrough.assign( parsed=itemgetter("raw") | output_parser, parsing_error=lambda _: None ) parser_none = RunnablePassthrough.assign(parsed=lambda _: None) parser_with_fallback = parser_assign.with_fallbacks( [parser_none], exception_key="parsing_error" ) return RunnableMap(raw=llm) | parser_with_fallback else: return llm | output_parser
[docs]class ChatOpenAI(BaseChatOpenAI): """OpenAI chat model integration. .. dropdown:: Setup :open: Install ``langchain-openai`` and set environment variable ``OPENAI_API_KEY``. .. code-block:: bash pip install -U langchain-openai export OPENAI_API_KEY="your-api-key" .. dropdown:: Key init args — completion params model: str Name of OpenAI model to use. temperature: float Sampling temperature. max_tokens: Optional[int] Max number of tokens to generate. logprobs: Optional[bool] Whether to return logprobs. stream_options: Dict Configure streaming outputs, like whether to return token usage when streaming (``{"include_usage": True}``). See full list of supported init args and their descriptions in the params section. .. dropdown:: Key init args — client params timeout: Union[float, Tuple[float, float], Any, None] Timeout for requests. max_retries: int Max number of retries. api_key: Optional[str] OpenAI API key. If not passed in will be read from env var OPENAI_API_KEY. base_url: Optional[str] Base URL for API requests. Only specify if using a proxy or service emulator. organization: Optional[str] 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 in the params section. .. dropdown:: Instantiate .. code-block:: python from langchain_openai import ChatOpenAI llm = ChatOpenAI( model="gpt-4o", temperature=0, max_tokens=None, timeout=None, max_retries=2, # api_key="...", # base_url="...", # organization="...", # other params... ) **NOTE**: Any param which is not explicitly supported will be passed directly to the ``openai.OpenAI.chat.completions.create(...)`` API every time to the model is invoked. For example: .. code-block:: python from langchain_openai import ChatOpenAI import openai ChatOpenAI(..., frequency_penalty=0.2).invoke(...) # results in underlying API call of: openai.OpenAI(..).chat.completions.create(..., frequency_penalty=0.2) # which is also equivalent to: ChatOpenAI(...).invoke(..., frequency_penalty=0.2) .. dropdown:: Invoke .. code-block:: python messages = [ ( "system", "You are a helpful translator. Translate the user sentence to French.", ), ("human", "I love programming."), ] llm.invoke(messages) .. code-block:: pycon AIMessage( content="J'adore la programmation.", response_metadata={ "token_usage": { "completion_tokens": 5, "prompt_tokens": 31, "total_tokens": 36, }, "model_name": "gpt-4o", "system_fingerprint": "fp_43dfabdef1", "finish_reason": "stop", "logprobs": None, }, id="run-012cffe2-5d3d-424d-83b5-51c6d4a593d1-0", usage_metadata={"input_tokens": 31, "output_tokens": 5, "total_tokens": 36}, ) .. dropdown:: Stream .. code-block:: python for chunk in llm.stream(messages): print(chunk) .. code-block:: python AIMessageChunk(content="", id="run-9e1517e3-12bf-48f2-bb1b-2e824f7cd7b0") AIMessageChunk(content="J", id="run-9e1517e3-12bf-48f2-bb1b-2e824f7cd7b0") AIMessageChunk(content="'adore", id="run-9e1517e3-12bf-48f2-bb1b-2e824f7cd7b0") AIMessageChunk(content=" la", id="run-9e1517e3-12bf-48f2-bb1b-2e824f7cd7b0") AIMessageChunk( content=" programmation", id="run-9e1517e3-12bf-48f2-bb1b-2e824f7cd7b0" ) AIMessageChunk(content=".", id="run-9e1517e3-12bf-48f2-bb1b-2e824f7cd7b0") AIMessageChunk( content="", response_metadata={"finish_reason": "stop"}, id="run-9e1517e3-12bf-48f2-bb1b-2e824f7cd7b0", ) .. code-block:: python stream = llm.stream(messages) full = next(stream) for chunk in stream: full += chunk full .. code-block:: python AIMessageChunk( content="J'adore la programmation.", response_metadata={"finish_reason": "stop"}, id="run-bf917526-7f58-4683-84f7-36a6b671d140", ) .. dropdown:: Async .. code-block:: python await llm.ainvoke(messages) # stream: # async for chunk in (await llm.astream(messages)) # batch: # await llm.abatch([messages]) .. code-block:: python AIMessage( content="J'adore la programmation.", response_metadata={ "token_usage": { "completion_tokens": 5, "prompt_tokens": 31, "total_tokens": 36, }, "model_name": "gpt-4o", "system_fingerprint": "fp_43dfabdef1", "finish_reason": "stop", "logprobs": None, }, id="run-012cffe2-5d3d-424d-83b5-51c6d4a593d1-0", usage_metadata={"input_tokens": 31, "output_tokens": 5, "total_tokens": 36}, ) .. dropdown:: Tool calling .. code-block:: python from langchain_core.pydantic_v1 import BaseModel, Field class GetWeather(BaseModel): '''Get the current weather in a given location''' location: str = Field( ..., description="The city and state, e.g. San Francisco, CA" ) class GetPopulation(BaseModel): '''Get the current population in a given location''' location: str = Field( ..., description="The city and state, e.g. San Francisco, CA" ) llm_with_tools = llm.bind_tools( [GetWeather, GetPopulation] # strict = True # enforce tool args schema is respected ) ai_msg = llm_with_tools.invoke( "Which city is hotter today and which is bigger: LA or NY?" ) ai_msg.tool_calls .. code-block:: python [ { "name": "GetWeather", "args": {"location": "Los Angeles, CA"}, "id": "call_6XswGD5Pqk8Tt5atYr7tfenU", }, { "name": "GetWeather", "args": {"location": "New York, NY"}, "id": "call_ZVL15vA8Y7kXqOy3dtmQgeCi", }, { "name": "GetPopulation", "args": {"location": "Los Angeles, CA"}, "id": "call_49CFW8zqC9W7mh7hbMLSIrXw", }, { "name": "GetPopulation", "args": {"location": "New York, NY"}, "id": "call_6ghfKxV264jEfe1mRIkS3PE7", }, ] Note that ``openai >= 1.32`` supports a ``parallel_tool_calls`` parameter that defaults to ``True``. This parameter can be set to ``False`` to disable parallel tool calls: .. code-block:: python ai_msg = llm_with_tools.invoke( "What is the weather in LA and NY?", parallel_tool_calls=False ) ai_msg.tool_calls .. code-block:: python [ { "name": "GetWeather", "args": {"location": "Los Angeles, CA"}, "id": "call_4OoY0ZR99iEvC7fevsH8Uhtz", } ] Like other runtime parameters, ``parallel_tool_calls`` can be bound to a model using ``llm.bind(parallel_tool_calls=False)`` or during instantiation by setting ``model_kwargs``. See ``ChatOpenAI.bind_tools()`` method for more. .. dropdown:: Structured output .. code-block:: python from typing import Optional from langchain_core.pydantic_v1 import BaseModel, Field class Joke(BaseModel): '''Joke to tell user.''' setup: str = Field(description="The setup of the joke") punchline: str = Field(description="The punchline to the joke") rating: Optional[int] = Field(description="How funny the joke is, from 1 to 10") structured_llm = llm.with_structured_output(Joke) structured_llm.invoke("Tell me a joke about cats") .. code-block:: python Joke( setup="Why was the cat sitting on the computer?", punchline="To keep an eye on the mouse!", rating=None, ) See ``ChatOpenAI.with_structured_output()`` for more. .. dropdown:: JSON mode .. code-block:: python json_llm = llm.bind(response_format={"type": "json_object"}) ai_msg = json_llm.invoke( "Return a JSON object with key 'random_ints' and a value of 10 random ints in [0-99]" ) ai_msg.content .. code-block:: python '\\n{\\n "random_ints": [23, 87, 45, 12, 78, 34, 56, 90, 11, 67]\\n}' .. dropdown:: Image input .. code-block:: python import base64 import httpx from langchain_core.messages import HumanMessage image_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" image_data = base64.b64encode(httpx.get(image_url).content).decode("utf-8") message = HumanMessage( content=[ {"type": "text", "text": "describe the weather in this image"}, { "type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_data}"}, }, ] ) ai_msg = llm.invoke([message]) ai_msg.content .. code-block:: python "The weather in the image appears to be clear and pleasant. The sky is mostly blue with scattered, light clouds, suggesting a sunny day with minimal cloud cover. There is no indication of rain or strong winds, and the overall scene looks bright and calm. The lush green grass and clear visibility further indicate good weather conditions." .. dropdown:: Token usage .. code-block:: python ai_msg = llm.invoke(messages) ai_msg.usage_metadata .. code-block:: python {"input_tokens": 28, "output_tokens": 5, "total_tokens": 33} When streaming, set the ``stream_usage`` kwarg: .. code-block:: python stream = llm.stream(messages, stream_usage=True) full = next(stream) for chunk in stream: full += chunk full.usage_metadata .. code-block:: python {"input_tokens": 28, "output_tokens": 5, "total_tokens": 33} Alternatively, setting ``stream_usage`` when instantiating the model can be useful when incorporating ``ChatOpenAI`` into LCEL chains-- or when using methods like ``.with_structured_output``, which generate chains under the hood. .. code-block:: python llm = ChatOpenAI(model="gpt-4o", stream_usage=True) structured_llm = llm.with_structured_output(...) .. dropdown:: Logprobs .. code-block:: python logprobs_llm = llm.bind(logprobs=True) ai_msg = logprobs_llm.invoke(messages) ai_msg.response_metadata["logprobs"] .. code-block:: python { "content": [ { "token": "J", "bytes": [74], "logprob": -4.9617593e-06, "top_logprobs": [], }, { "token": "'adore", "bytes": [39, 97, 100, 111, 114, 101], "logprob": -0.25202933, "top_logprobs": [], }, { "token": " la", "bytes": [32, 108, 97], "logprob": -0.20141791, "top_logprobs": [], }, { "token": " programmation", "bytes": [ 32, 112, 114, 111, 103, 114, 97, 109, 109, 97, 116, 105, 111, 110, ], "logprob": -1.9361265e-07, "top_logprobs": [], }, { "token": ".", "bytes": [46], "logprob": -1.2233183e-05, "top_logprobs": [], }, ] } .. dropdown:: Response metadata .. code-block:: python ai_msg = llm.invoke(messages) ai_msg.response_metadata .. code-block:: python { "token_usage": { "completion_tokens": 5, "prompt_tokens": 28, "total_tokens": 33, }, "model_name": "gpt-4o", "system_fingerprint": "fp_319be4768e", "finish_reason": "stop", "logprobs": None, } """ # noqa: E501 stream_usage: bool = False """Whether to include usage metadata in streaming output. If True, additional message chunks will be generated during the stream including usage metadata. """ @property def lc_secrets(self) -> Dict[str, str]: return {"openai_api_key": "OPENAI_API_KEY"} @classmethod def get_lc_namespace(cls) -> List[str]: """Get the namespace of the langchain object.""" return ["langchain", "chat_models", "openai"] @property def lc_attributes(self) -> Dict[str, Any]: attributes: Dict[str, Any] = {} if self.openai_organization: attributes["openai_organization"] = self.openai_organization if self.openai_api_base: attributes["openai_api_base"] = self.openai_api_base if self.openai_proxy: attributes["openai_proxy"] = self.openai_proxy return attributes @classmethod def is_lc_serializable(cls) -> bool: """Return whether this model can be serialized by Langchain.""" return True def _should_stream_usage( self, stream_usage: Optional[bool] = None, **kwargs: Any ) -> bool: """Determine whether to include usage metadata in streaming output. For backwards compatibility, we check for `stream_options` passed explicitly to kwargs or in the model_kwargs and override self.stream_usage. """ stream_usage_sources = [ # order of preference stream_usage, kwargs.get("stream_options", {}).get("include_usage"), self.model_kwargs.get("stream_options", {}).get("include_usage"), self.stream_usage, ] for source in stream_usage_sources: if isinstance(source, bool): return source return self.stream_usage def _stream( self, *args: Any, stream_usage: Optional[bool] = None, **kwargs: Any ) -> Iterator[ChatGenerationChunk]: """Set default stream_options.""" stream_usage = self._should_stream_usage(stream_usage, **kwargs) # Note: stream_options is not a valid parameter for Azure OpenAI. # To support users proxying Azure through ChatOpenAI, here we only specify # stream_options if include_usage is set to True. # See https://learn.microsoft.com/en-us/azure/ai-services/openai/whats-new # for release notes. if stream_usage: kwargs["stream_options"] = {"include_usage": stream_usage} return super()._stream(*args, **kwargs) async def _astream( self, *args: Any, stream_usage: Optional[bool] = None, **kwargs: Any ) -> AsyncIterator[ChatGenerationChunk]: """Set default stream_options.""" stream_usage = self._should_stream_usage(stream_usage, **kwargs) if stream_usage: kwargs["stream_options"] = {"include_usage": stream_usage} async for chunk in super()._astream(*args, **kwargs): yield chunk
def _is_pydantic_class(obj: Any) -> bool: return isinstance(obj, type) and is_basemodel_subclass(obj) def _lc_tool_call_to_openai_tool_call(tool_call: ToolCall) -> dict: return { "type": "function", "id": tool_call["id"], "function": { "name": tool_call["name"], "arguments": json.dumps(tool_call["args"]), }, } def _lc_invalid_tool_call_to_openai_tool_call( invalid_tool_call: InvalidToolCall, ) -> dict: return { "type": "function", "id": invalid_tool_call["id"], "function": { "name": invalid_tool_call["name"], "arguments": invalid_tool_call["args"], }, } def _url_to_size(image_source: str) -> Optional[Tuple[int, int]]: try: from PIL import Image # type: ignore[import] except ImportError: logger.info( "Unable to count image tokens. To count image tokens please install " "`pip install -U pillow httpx`." ) return None if _is_url(image_source): try: import httpx except ImportError: logger.info( "Unable to count image tokens. To count image tokens please install " "`pip install -U httpx`." ) return None response = httpx.get(image_source) response.raise_for_status() width, height = Image.open(BytesIO(response.content)).size return width, height elif _is_b64(image_source): _, encoded = image_source.split(",", 1) data = base64.b64decode(encoded) width, height = Image.open(BytesIO(data)).size return width, height else: return None def _count_image_tokens(width: int, height: int) -> int: # Reference: https://platform.openai.com/docs/guides/vision/calculating-costs width, height = _resize(width, height) h = ceil(height / 512) w = ceil(width / 512) return (170 * h * w) + 85 def _is_url(s: str) -> bool: try: result = urlparse(s) return all([result.scheme, result.netloc]) except Exception as e: logger.debug(f"Unable to parse URL: {e}") return False def _is_b64(s: str) -> bool: return s.startswith("data:image") def _resize(width: int, height: int) -> Tuple[int, int]: # larger side must be <= 2048 if width > 2048 or height > 2048: if width > height: height = (height * 2048) // width width = 2048 else: width = (width * 2048) // height height = 2048 # smaller side must be <= 768 if width > 768 and height > 768: if width > height: width = (width * 768) // height height = 768 else: height = (width * 768) // height width = 768 return width, height def _convert_to_openai_response_format( schema: Union[Dict[str, Any], Type], strict: bool ) -> Union[Dict, TypeBaseModel]: if isinstance(schema, type) and is_basemodel_subclass(schema): return schema else: function = convert_to_openai_function(schema, strict=strict) function["schema"] = function.pop("parameters") return {"type": "json_schema", "json_schema": function} @chain def _oai_structured_outputs_parser(ai_msg: AIMessage) -> PydanticBaseModel: if ai_msg.additional_kwargs.get("parsed"): return ai_msg.additional_kwargs["parsed"] elif ai_msg.additional_kwargs.get("refusal"): raise OpenAIRefusalError(ai_msg.additional_kwargs["refusal"]) else: raise ValueError( "Structured Output response does not have a 'parsed' field nor a 'refusal' " "field." )
[docs]class OpenAIRefusalError(Exception): """Error raised when OpenAI Structured Outputs API returns a refusal. When using OpenAI's Structured Outputs API with user-generated input, the model may occasionally refuse to fulfill the request for safety reasons. See here for more on refusals: https://platform.openai.com/docs/guides/structured-outputs/refusals .. versionadded:: 0.1.21 """