LangChain 커스텀 LLM API: 임의의 Base URL로 연결
langchain 커스텀 LLM API를 사용하려면 커스텀 클래스를 작성할 필요가 없습니다. OpenAI 호환 채팅 래퍼는 base URL, 키 및 모델 이름을 받습니다. 정확한 구성은 다음과 같으며, 스트리밍, 도구, JSON 출력 및 제한 처리도 포함됩니다.
주요 포인트
- ChatOpenAI는 base_url, api_key 및 model을 받으므로 상속이 필요하지 않습니다.
- 모델 uncensored와 base URL https://api.llmapistatus.com/v1을 사용하세요.
- 도구 호출, 스트리밍 및 JSON 모드는 모두 엔드포인트를 통해 전달됩니다.
- 동시성 제한을 유지하기 위해 병렬 체인을 8로 제한하세요. 임베딩은 제공되지 않습니다.

짧은 답변: 다른 base URL을 사용한 ChatOpenAI
LangChain은 langchain-openai 패키지를 통해 OpenAI 스타일 서버와 통신합니다. 이 ChatOpenAI 클래스를 사용하면 요청이 전송되는 위치를 재정의할 수 있으며, 이는 커스텀 엔드포인트에 정확히 필요합니다. 패키지를 설치한 후 base URL https://api.llmapistatus.com/v1, 키 및 모델 ID uncensored의 세 값을 전달하세요.
pip install -U langchain-openai langchain-core로 설치하세요.
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.llmapistatus.com/v1",
api_key=os.environ["LLM_API_KEY"],
temperature=0.7,
)
print(llm.invoke("Reply with the single word: ready").content)
응답이 출력되면 연결이 올바르게 설정된 것입니다. API 키 페이지에서 키를 받으세요. 빠른 시작은 일반 SDK 사용자를 위해 동일한 전환 방법을 보여줍니다. 엔드포인트는 POST /v1/chat/completions 및 GET /v1/models을 제공하며, 이 두 메서드가 채팅용 OpenAI 래퍼에 모두 필요합니다.
"커스텀 LLM"이라는 용어에 대한 설명. LangChain은 베이스 클래스를 상속하여 사용자 정의 채팅 모델을 작성하는 방법을 문서화하고 있으며, 이는 OpenAI 형식을 사용하지 않는 API에 적합합니다. 이 엔드포인트는 해당 형식을 지원하므로 상속하면 유지해야 할 코드가 늘어납니다. 래퍼로 표현할 수 없는 동작이 필요한 경우에만 사용하세요.
프롬프트 및 출력 파싱으로 체인 구축
모델 객체가 준비되면 LangChain의 나머지 기능은 다른 채팅 모델과 동일한 방식으로 작동합니다. 다음은 표현식 언어 스타일로 작성된 작은 체인입니다: 프롬프트 템플릿, 모델 및 문자열 파서.
# reuses llm from the first example: base_url https://api.llmapistatus.com/v1, model uncensored
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
prompt = ChatPromptTemplate.from_messages([
("system", "You are a blunt technical editor. Answer in at most {limit} words."),
("human", "Rewrite this for clarity:\n\n{text}"),
])
chain = prompt | llm | StrOutputParser()
print(chain.invoke({
"limit": 60,
"text": "The thing that we did was basically to make the cache be invalidated on write.",
}))
이 체인에서 모델이 다른 도메인 뒤에 위치한다는 것을 알거나 신경 쓰는 요소는 없습니다. 호환 API의 이점입니다: 표준 채팅 인터페이스를 대상으로 작성된 프롬프트, 메모리 클래스, 검색기 및 에이전트는 계속 작동합니다. 사용자가 확인할 것은 프롬프트 자체입니다. 콘텐츠 거부 없이 답변하도록 조정된 모델은 지시를 문자 그대로 따르므로 모호한 시스템 프롬프트는 모호한 동작을 생성합니다. 역할, 형식 및 길이를 명시하세요.
검색 파이프라인을 설계하기 전에 알아야 할 한 가지 제한 사항이 있습니다. 이 서비스는 텍스트 전용입니다. 임베딩이 없으므로 이 base URL을 가리키는 OpenAIEmbeddings는 실패합니다. 벡터 저장소에는 로컬 임베딩 모델이나 다른 제공자를 사용하고, 생성에만 이 엔드포인트를 사용하세요.
도착하는 토큰 스트리밍
stream: true를 보내면 엔드포인트는 서버 전송 이벤트를 지원하며 LangChain은 이를 이터레이터로 변환합니다. 플래그를 직접 설정할 필요가 없습니다. .stream() 호출 시 자동으로 설정됩니다.
# reuses llm from the first example: base_url https://api.llmapistatus.com/v1, model uncensored
for chunk in llm.stream("Write a four-line poem about a failing cron job."):
print(chunk.content, end="", flush=True)
print()
비동기 서버의 경우 astream을 사용하세요. JavaScript 라이브러리에도 동일한 호출이 존재합니다:
import { ChatOpenAI } from "@langchain/openai";
const llm = new ChatOpenAI({
model: "uncensored",
apiKey: process.env.LLM_API_KEY,
configuration: { baseURL: "https://api.llmapistatus.com/v1" },
});
const stream = await llm.stream("Write a four-line poem about a failing cron job.");
for await (const chunk of stream) {
process.stdout.write(chunk.content);
}
스트리밍 요청은 마지막 이벤트가 도착할 때까지 동시성 슬롯을 유지합니다. 사용자가 브라우저 탭을 닫고 서버가 스트림을 계속 읽는 경우 해당 슬롯이 점유된 상태로 유지됩니다. 클라이언트가 연결을 해제하면 업스트림 요청을 취소하세요. 사용량 데이터는 스트림 끝에 도착하므로, 여기서 최종 토큰 수를 읽어 청구 로그에 기록합니다.
함수 호출 및 에이전트
도구 호출이 제공됩니다: 엔드포인트는 tools 및 tool_choice을 받고, tool_calls을 스트리밍하며, role: "tool" 메시지로 결과를 받습니다. LangChain에서는 bind_tools로 도구를 연결하고 프레임워크가 메시지를 생성하도록 합니다.
# reuses llm from the first example: base_url https://api.llmapistatus.com/v1, model uncensored
from langchain_core.tools import tool
@tool
def get_order_status(order_id: str) -> str:
'Look up the status of an order by its id.'
return f"Order {order_id} shipped yesterday."
llm_tools = llm.bind_tools([get_order_status])
ai = llm_tools.invoke("Where is order A-1042?")
print(ai.tool_calls)
호출 실행 및 결과 반환은 루프의 두 번째 부분입니다:
# reuses llm from the first example: base_url https://api.llmapistatus.com/v1, model uncensored
# llm_tools comes from the previous snippet
from langchain_core.messages import HumanMessage, ToolMessage
messages = [HumanMessage("Where is order A-1042?")]
ai = llm_tools.invoke(messages)
messages.append(ai)
for call in ai.tool_calls:
result = get_order_status.invoke(call["args"])
messages.append(ToolMessage(content=result, tool_call_id=call["id"]))
print(llm_tools.invoke(messages).content)
오픈 웨이트 모델은 도구 선택 및 인수 채우기 성능이 다를 수 있습니다. 도구 설명은 짧고 구체적으로 유지하고, 호출당 도구 수를 적게 사용하며, 함수에서 인수를 검증하여 신뢰하지 마세요. 에이전트가 무한 루프에 빠지면 온도를 낮추고 에이전트 실행기에 최대 단계 수를 설정하세요.
구조화 및 JSON 출력
JSON 모드는 response_format: {"type": "json_object"}을 통해 지원됩니다. LangChain에서는 JSON 모드 메서드를 사용하는 with_structured_output이 가장 쉬운 방법이며, 이는 스키마에 대해 결과를 검증합니다.
# reuses llm from the first example: base_url https://api.llmapistatus.com/v1, model uncensored
from pydantic import BaseModel
class Ticket(BaseModel):
title: str
priority: str
tags: list[str]
structured = llm.with_structured_output(Ticket, method="json_mode")
result = structured.invoke(
"Return JSON with keys title, priority and tags for this report: "
"login page times out on mobile, affects many users."
)
print(result)
JSON 모드는 출력이 JSON 객체임을 보장하지만, 원하는 필드가 있음을 보장하지는 않습니다. 두 가지 습관이 도움이 됩니다. 첫째, 프롬프트에서 키 이름을 지정하세요. JSON 생성 지시는 명시적이어야 합니다. 둘째, 실패 시 다시 파싱하는 재시도로 호출을 감싸세요. pydantic 확인은 누락된 필드와 잘못된 유형을 포착하며, 오류 메시지를 추가한 단일 재시도로 대부분 해결됩니다.
model_kwargs={"response_format": {"type": "json_object"}}로 모델을 빌드할 때 response_format을 직접 설정할 수도 있으며, 이는 JSON 파서로 끝나는 일반 체인에 유용합니다.
속도 제한, 재시도 및 병렬 체인
배치 작업과 에이전트는 한 번에 많은 호출을 수행하며, 이때 커스텀 엔드포인트는 로컬 모델과 다릅니다. 전체 키는 동시 요청 8개와 분당 300개의 요청을 허용합니다. 체험 키는 동시 2개, 분당 60개를 허용합니다. 한도를 초과하면 API는 HTTP 429와 함께 rate_limited 또는 concurrency 오류 코드를 반환하며, 일시적 과부하 시 Retry-After: 5와 함께 429를 반환합니다.
두 가지 LangChain 설정으로 대부분 처리할 수 있습니다. 모델은 max_retries를 받아 백오프로 일시적 실패를 재시도하며, runnable은 배치 작업을 위한 구성에 max_concurrency 값을 허용합니다:
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.llmapistatus.com/v1",
api_key=os.environ["LLM_API_KEY"],
max_retries=4,
timeout=120,
)
questions = [f"Summarise item {i} in one sentence." for i in range(40)]
answers = llm.batch(questions, config={"max_concurrency": 6})
전체 키에서 한도를 6으로 설정하면 앱의 사용자 대상 호출 등 다른 두 요청을 위한 여유가 생깁니다. 체험 키의 경우 1 또는 2를 사용하세요. 동시성 문제에는 재시도에만 의존하지 마세요. 설정한 한도가 키의 허용 한도를 초과하면 재시도는 동일한 충돌을 다시 생성합니다. 응답 헤더에서 X-RateLimit-Limit-Requests 및 X-RateLimit-Limit-Concurrency을 읽으면 키가 허용되는 내용을 알 수 있습니다.
긴 입력은 프롬프트와 응답을 합쳐 100,000토큰 창까지 가능하며, 요청 본문은 8 MB로 제한됩니다. LangChain 텍스트 분할기를 청크당 수천 토큰으로 설정하면 두 제한 모두 훨씬 아래에 머뭅니다.
커스텀 엔드포인트 문제 해결
커스텀 base URL과 관련된 대부분의 문제는 짧은 목록에 분류되며, 각 문제마다 빠른 테스트가 있습니다.
- 인증 오류. LangChain은 또한
OPENAI_API_KEY환경 변수를 읽습니다.api_key를 명시적으로 전달하면 해당 값이 우선하지만, 만료된 변수가 구성을 깜빡한 두 번째 모델 객체를 혼동시킬 수 있습니다. 매번 키를 전달하고,LLM_API_KEY와 같이 변수에 다른 이름을 부여하세요. - 찾을 수 없음 오류. base URL은
/v1로 끝나야 합니다. LangChain은/chat/completions을 자체적으로 추가하므로 base URL에 추가하면 경로가 중복됩니다. - 알 수 없는 모델. 동일한 키로
GET /v1/models을 요청하고 출력된 ID를 복사하세요. 이는uncensored여야 합니다. - 긴 체인에서의 무응답 상태. 모델에
timeout을 설정하고X-Request-Id응답 헤더를 로깅하세요. 지원팀에 문의할 때 이 ID를 통해 정확한 요청을 찾을 수 있습니다. - 예상치 못한 출력. 전송 전 최종 프롬프트를 출력하세요. LangChain의 예상치 못한 응답 대부분은 변수에 예상치 못한 무언가를 채운 템플릿에서 비롯되며, 모델에서 비롯된 것이 아닙니다.
의심스러울 때는 동일한 URL로 단순 curl을 사용해 실패하는 호출을 재현하세요. curl이 작동하고 LangChain이 작동하지 않으면 문제가 체인에 있습니다. 둘 다 실패하면 키와 잔액을 확인하세요.
빌드 중 비용 확인
체인은 토큰 수를 숨기므로 초기에 측정해야 합니다. 각 응답에는 사용량이 포함되며, 응답 헤더에는 X-Balance-USD가 포함됩니다. 가격은 입력 토큰 100만 개당 $0.15, 출력 토큰 100만 개당 $0.50이며 선불 크레딧에서 청구됩니다.
계산 예시: 컨텍스트와 질문으로 6,000토큰을 보내고 400토큰을 받는 검색 체인의 경우, 입력 비용은 6,000 x $0.15 / 1M = $0.0009, 출력 비용은 400 x $0.50 / 1M = $0.0002이므로 호출당 $0.0011입니다. 테스트 일괄 실행에서 이러한 호출 5,000개를 실행하면 $5.50이 듭니다. 에이전트 루프가 밤새 실행되기 전에 이를 아는 것이 유용합니다.
실패하거나 거부된 요청에는 요금이 부과되지 않습니다. 가격 책정 페이지에는 $20부터 $500까지 보너스가 포함된 충전 금액이 나열되어 있으며, 신규 계정은 클릭 한 번으로 $0.50 무료 체험 크레딧을 청구할 수 있습니다. 이는 설정을 완료하는 동안 몇백 건의 작은 테스트 호출에 충분합니다.
더 많은 가이드
질문과 답변
LangChain의 채팅 모델 기본 클래스를 상속받아야 하나요?
아니요. 엔드포인트는 OpenAI 호환이므로 커스텀 base_url, api_key 및 모델로 ChatOpenAI를 사용하면 됩니다. 다른 형식을 사용하는 API의 경우에만 상속이 필요합니다.
이 엔드포인트에서 OpenAIEmbeddings를 사용할 수 있나요?
아니요. 이 서비스는 텍스트 전용이며 임베딩 기능이 없습니다. 벡터용 로컬 임베딩 모델이나 다른 제공자를 사용하고, 생성에는 이 엔드포인트를 사용하세요.
어떤 모델 이름을 전달해야 하나요?
model에 uncensored를 전달하세요. GET /v1/models는 동일한 ID를 반환합니다.
배치 작업에서 429 오류가 발생하는 이유는 무엇인가요?
분당 요청 수 또는 동시 요청 한도를 초과했습니다. 전체 키의 경우 max_concurrency를 8 미만으로, 체험 키의 경우 2로 낮추고 재시도를 활성화하세요.
LangChain의 스트리밍이 여기서 작동하나요?
네. stream 또는 astream 호출은 서버 전송 이벤트(SSE)를 사용하며, 사용량은 스트림 끝에 전송됩니다.
키는 양식 하나만 작성하면 받을 수 있습니다
계정을 생성하고 키를 복사한 후 base URL을 변경하세요. 설정은 이것으로 끝입니다.