LangChain

채팅 모델 메서드

BaseChatModel의 invoke/stream/batch, bind_tools, with_structured_output, with_retry, with_fallbacks

#chat-model#invoke#stream#batch#tools#structured-output#retry공식 문서

모든 채팅 모델(BaseChatModel 하위 클래스)은 Runnable 인터페이스를 따릅니다. 입력은 문자열, 메시지 리스트, PromptValue 중 하나(LanguageModelInput)이고 출력은 AIMessage입니다. 각 메서드에는 비동기 버전(ainvoke, astream, abatch, abatch_as_completed)이 있습니다.

Import

python
from langchain.chat_models import init_chat_model
from langchain_core.language_models import BaseChatModel  # 타입 힌트용

시그니처

python
# langchain-core 1.7.0, BaseChatModel
def invoke(self, input: LanguageModelInput, config: RunnableConfig | None = None,
           *, stop: list[str] | None = None, **kwargs) -> AIMessage
def stream(self, input: LanguageModelInput, config: RunnableConfig | None = None,
           *, stop: list[str] | None = None, **kwargs) -> Iterator[AIMessageChunk]
def batch(self, inputs: list[Input], config: RunnableConfig | list[RunnableConfig] | None = None,
          *, return_exceptions: bool = False, **kwargs) -> list[Output]
def batch_as_completed(self, inputs: Sequence[Input], config=None,
                       *, return_exceptions: bool = False, **kwargs) -> Iterator[tuple[int, Output | Exception]]
def bind_tools(self, tools: Sequence[dict | type | Callable | BaseTool],
               *, tool_choice: str | None = None, **kwargs) -> Runnable[LanguageModelInput, AIMessage]
def with_structured_output(self, schema: dict | type,
                           *, include_raw: bool = False, **kwargs) -> Runnable[LanguageModelInput, dict | BaseModel]
def with_retry(self, *, retry_if_exception_type: tuple[type[BaseException], ...] | Callable[[BaseException], bool] = (Exception,),
               wait_exponential_jitter: bool = True,
               exponential_jitter_params: ExponentialJitterParams | None = None,
               stop_after_attempt: int = 3) -> Runnable
def with_fallbacks(self, fallbacks: Sequence[Runnable], *,
                   exceptions_to_handle: tuple[type[BaseException], ...] = (Exception,),
                   exception_key: str | None = None) -> RunnableWithFallbacks

파라미터

invoke / stream / batch

파라미터타입기본값설명
inputstr | list[메시지 또는 dict] | PromptValue문자열은 HumanMessage 하나로 변환됩니다. {"role": "user", "content": "..."} dict도 됩니다.
configRunnableConfig | NoneNonetags, metadata, callbacks, run_name, max_concurrency(batch), configurable 등.
stoplist[str] | NoneNone정지 시퀀스(stop sequence).
return_exceptionsboolFalsebatch에서 실패한 항목을 예외 객체로 돌려주고 나머지는 계속 실행합니다.
**kwargs이번 호출에만 적용할 제공자 인자.

bind_tools

파라미터타입기본값설명
toolsSequence[dict | type | Callable | BaseTool]@tool 함수, Pydantic 클래스, 일반 함수, OpenAI 형식 dict.
tool_choicestr | NoneNone"auto", "any"/"required"(반드시 도구 호출), 특정 도구 이름. ChatOpenAI는 dict | str | bool도 받습니다.
strict (ChatOpenAI)bool | NoneNoneOpenAI strict 스키마 모드.
parallel_tool_calls (ChatOpenAI)bool | NoneNone병렬 도구 호출 허용 여부.

with_structured_output

파라미터타입기본값설명
schematype[BaseModel] | TypedDict | dict출력 스키마. Pydantic이면 인스턴스, TypedDict/JSON Schema면 dict를 돌려줍니다.
include_rawboolFalseTrue면 {"raw": AIMessage, "parsed": ..., "parsing_error": ...} 반환.
method (ChatOpenAI)"json_schema" | "function_calling" | "json_mode""json_schema"제공자 네이티브 구조화 출력 방식.
strict (ChatOpenAI)bool | NoneNone스키마 엄격 검증.

with_retry / with_fallbacks

파라미터타입기본값설명
retry_if_exception_typetuple[type] | Callable(Exception,)재시도할 예외 종류 또는 판별 함수.
wait_exponential_jitterboolTrue지수 백오프 + 지터(jitter).
exponential_jitter_paramsExponentialJitterParams | NoneNoneinitial, max, exp_base, jitter 값.
stop_after_attemptint3최초 시도를 포함한 최대 시도 횟수.
fallbacksSequence[Runnable]순서대로 시도할 대체 Runnable.
exceptions_to_handletuple[type](Exception,)이 예외가 나면 다음 fallback으로 넘어갑니다.
exception_keystr | NoneNone지정하면 앞 단계 예외를 입력 dict의 이 키로 전달합니다(입력이 dict여야 함).

메서드와 반환값

메서드반환비고
invoke / ainvokeAIMessage.text, .content_blocks, .tool_calls, .usage_metadata
stream / astreamIterator[AIMessageChunk]청크끼리 +로 합칠 수 있습니다.
batch / abatchlist[AIMessage]입력 순서 유지. config={"max_concurrency": N}로 동시성 제한.
batch_as_completedIterator[(index, 결과)]끝난 순서대로.
bind_toolsRunnable도구 스키마를 묶은 새 Runnable. 원본은 그대로입니다.
with_structured_outputRunnable출력이 스키마 객체.
with_retry / with_fallbacksRunnable감싼 새 Runnable. bind_tools 등은 감싸기 전에 호출해야 합니다.
get_num_tokens_from_messages(messages, tools=None)int토큰 수 추정.
stream_events(input, version="v2")이벤트 이터레이터version="v3"(beta)은 .text, .reasoning, .tool_calls, .output 프로젝션을 가진 ChatModelStream을 반환합니다.

예제

python
import os
from langchain.chat_models import init_chat_model

MODEL = os.getenv("LAB_MODEL", "openai:gpt-5-mini")
llm = init_chat_model(MODEL)

# 1) invoke
msg = llm.invoke([{"role": "system", "content": "짧게 답하라"}, {"role": "user", "content": "RAG란?"}])
print(msg.text, msg.usage_metadata)

# 2) stream: 청크를 누적하면 최종 메시지가 된다
full = None
for chunk in llm.stream("LangGraph 장점 3가지"):
    print(chunk.text, end="", flush=True)
    full = chunk if full is None else full + chunk
print()

# 3) batch: 동시성 제한
results = llm.batch(["1+1?", "2+2?", "3+3?"], config={"max_concurrency": 2})
print([r.text for r in results])

도구 바인딩과 구조화 출력:

python
import os
from pydantic import BaseModel, Field
from langchain.chat_models import init_chat_model
from langchain.tools import tool

MODEL = os.getenv("LAB_MODEL", "openai:gpt-5-mini")
llm = init_chat_model(MODEL)


@tool
def get_weather(city: str) -> str:
    """도시의 현재 날씨를 조회한다."""
    return f"{city}: 맑음"


ai = llm.bind_tools([get_weather]).invoke("서울 날씨 알려줘")
for call in ai.tool_calls:
    print(call["name"], call["args"], call["id"])


class Movie(BaseModel):
    title: str = Field(description="영화 제목")
    year: int = Field(description="개봉 연도")


movie = llm.with_structured_output(Movie).invoke("인셉션 정보")
print(movie.title, movie.year)

재시도와 대체 모델:

python
import os
from langchain.chat_models import init_chat_model

MODEL = os.getenv("LAB_MODEL", "openai:gpt-5-mini")
primary = init_chat_model(MODEL, max_retries=0)
backup = init_chat_model("openai:gpt-5-nano")

robust = primary.with_retry(stop_after_attempt=2).with_fallbacks([backup])
print(robust.invoke("안녕").text)

주의사항

주의

with_retry()/with_fallbacks()가 반환한 객체는 채팅 모델이 아니라 일반 Runnable이므로 bind_tools가 없습니다. llm.bind_tools(tools).with_retry() 순서로 쓰고, fallback 모델에도 각각 bind_tools를 해야 합니다.

주의

ChatOpenAI는 자체 max_retries(SDK 재시도)를 가집니다. with_retry와 겹치면 재시도 횟수가 곱해지니 하나만 쓰세요.

팁

AIMessage.text는 v1부터 프로퍼티입니다(msg.text). msg.text()처럼 메서드로 부르는 방식은 langchain-core 1.0부터 deprecated이고 2.0에서 제거될 예정입니다.

팁

에이전트 안에서 재시도/대체가 필요하면 Runnable 래퍼보다 ModelRetryMiddleware / ModelFallbackMiddleware를 쓰는 편이 도구 바인딩과 충돌하지 않습니다.

관련 문서