OpenRouter 튜토리얼 – LangChain ChatOpenRouter로 멀티 프로바이더 체인 만들기

설치
기본 호출
도구 호출과 구조화 출력
Provider routing과 fallback
운영 팁
관련 문서
참고 자료

ChatOpenRouter는 LangChain 체인에서 OpenRouter의 provider/model 슬러그를 직접 쓰게 해주는 통합이다. 기존 체인 구조를 유지하면서 모델 교체, provider routing, fallback, reasoning budget, 멀티모달 입력, 구조화 출력을 OpenRouter 계층에 위임할 수 있다.

설치

Python에서는 langchain-openrouter, TypeScript에서는 @langchain/openrouter 패키지를 사용한다. 패키지가 비교적 최근 통합이므로 LangChain 버전을 함께 최신으로 맞추는 편이 안전하다.

pip install langchain-openrouter
npm install @langchain/openrouter

기본 호출

from langchain_openrouter import ChatOpenRouter

model = ChatOpenRouter(
    model="anthropic/claude-sonnet-4.5",
    temperature=0.8,
)

response = model.invoke("이 지원 티켓을 한 문장으로 요약해줘.")
print(response.content)

모델명은 OpenRouter의 provider/model 문자열이다. 비용, 컨텍스트, 모달리티, 지원 파라미터는 OpenRouter 모델 카탈로그를 기준으로 확인해야 한다.

도구 호출과 구조화 출력

bind_tools와 with_structured_output을 그대로 사용할 수 있다. strict=True를 주면 모델이 도구 인자나 JSON schema를 더 엄격하게 따르도록 요청한다.

from pydantic import BaseModel, Field

class TicketSummary(BaseModel):
    sentiment: str
    priority: int = Field(ge=1, le=5)
    summary: str

structured = model.with_structured_output(
    TicketSummary,
    method="json_schema",
)

result = structured.invoke("고객이 내보내기 버튼 오류에 화가 나 있다.")

모든 모델과 provider가 모든 파라미터를 지원하는 것은 아니다. OpenRouter의 provider 설정에서 require_parameters: True를 켜면 요청한 파라미터를 지원하는 endpoint로만 라우팅하게 할 수 있다.

Provider routing과 fallback

OpenRouter의 장점은 같은 모델을 여러 provider가 제공할 때 가격, 지연 시간, 처리량, 장애 상태를 기준으로 라우팅할 수 있다는 점이다.

model = ChatOpenRouter(
    model="anthropic/claude-sonnet-4.5",
    openrouter_provider={
        "order": ["Anthropic", "Google"],
        "allow_fallbacks": True,
        "data_collection": "deny",
        "sort": "throughput",
        "require_parameters": True,
    },
)

allow_fallbacks는 선호 provider가 실패할 때 다른 provider로 넘어가게 한다. 모델 자체 fallback이 필요하면 model_kwargs에 models 배열을 넣어 1순위 모델 실패 시 다음 모델을 시도할 수 있다.

운영 팁

모델 문자열은 문서 예시가 아니라 OpenRouter catalog에서 확인한다.
오래된 LangChain 환경에서는 ChatOpenAI의 base_url을 OpenRouter API로 바꾸는 방식도 가능하지만, 새 프로젝트는 전용 패키지가 낫다.
reasoning, prompt caching, trace metadata는 체인 구조 변경 없이 request parameter로 붙인다.
provider fallback은 애플리케이션 재시도 코드를 줄이지만, 품질 차이와 파라미터 호환성은 별도 평가해야 한다.

참고 자료

Using OpenRouter With LangChain (ChatOpenRouter) — OpenRouter Blog (2026-07-29)

Like?

AI Sparkup