로컬 또는 호스팅: 제약 조건에 따라 선택
로컬 모델용 LangChain을 찾는 사람들은 보통 세 가지 중 하나를 원합니다: 프라이버시, 토큰별 청구 없음 또는 벤더 독립성. Ollama나 llama.cpp와 같은 도구로 제공되는 로컬 머신의 모델은 사용 가능한 속도로 실행할 하드웨어가 있는 경우 이 세 가지를 모두 제공합니다. 대가는 설정 시간, 메모리 제한 및 소유한 GPU 또는 CPU의 속도에 대한 것입니다.
호스팅 엔드포인트는 이를 작은 사용 비용과 교환합니다. 프롬프트를 네트워크로 보내고 모델은 타인의 하드웨어에서 실행됩니다. 여기서는 오픈 웨이트 모델로, 합법적인 성인 사용에 콘텐츠 거부 없이 답변하도록 조정되었으며 OpenAI 호환 API를 통해 제공됩니다. 프롬프트는 학습에 사용되지 않지만 머신을 떠나므로 데이터가 절대 떠나서는 안 된다는 규칙이 있는 경우 호스팅 서비스는 맞지 않는 선택입니다.
LangChain 개발자에게 유용한 부분은 코드가 거의 다르지 않다는 것입니다. Ollama와 llama.cpp 같은 로컬 서버는 OpenAI 스타일의 엔드포인트를 노출하며 호스팅 엔드포인트는 동일한 프로토콜을 사용합니다. 구성 가능한 base URL이 있는 ChatOpenAI에 대해 앱을 작성하면 로컬에서 개발하고 환경 변수로 호스팅 모델로 전환할 수 있습니다. 이는 작은 로컬 모델로 반복하고 GPU를 소유하지 않고도 더 큰 모델의 동작을 원할 때 호스팅 모델을 사용하는 실용적인 하이브리드를 제공합니다.
ChatOpenAI를 엔드포인트에 연결
통합 패키지를 설치한 후 세 가지 설정으로 모델 객체를 생성하세요.
pip install langchain-openai langchain-core
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.llmproxyapi.com/v1",
api_key=os.environ["LLMPROXY_API_KEY"],
temperature=0.7,
)
print(llm.invoke("Give me three names for a fantasy tavern.").content)
이것이 실행되면 나머지도 같은 방식으로 작동합니다. API 키 페이지에서 키를 얻으세요; 새 사용자는 가입 후 한 번의 클릭으로 카드 없이 $0.50의 무료 체험 크레딧을 청구할 수 있습니다. 환경 변수에 의존하기보다 코드에서 base URL을 명시적으로 전달하세요. 다른 라이브러리 버전은 다른 변수 이름을 읽으며 기본 OpenAI 호스트로 조용히 폴백되면 키가 잘못된 곳으로 전송될 수 있습니다.
모델 이름은 사람들이 실수하는 유일한 곳입니다. 여기서 유일한 ID는 uncensored입니다. llama3 또는 gpt-4o와 같은 이름은 인식되지 않습니다.
프롬프트 템플릿이 있는 체인
프롬프트, 모델 및 출력 파서의 표준 파이프라인은 변경되지 않고 실행됩니다. 이 예제는 선택된 어조로 텍스트를 요약합니다.
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
prompt = ChatPromptTemplate.from_messages([
("system", "You are a writing assistant. Answer in a {tone} tone."),
("human", "Summarize in two sentences:\n\n{text}"),
])
chain = prompt | llm | StrOutputParser()
print(chain.invoke({"tone": "dry", "text": "Long article text goes here..."}))
많은 입력의 경우 batch를 사용하고 동시 요청 수를 제한하세요. 전체 키는 동시 요청 8개와 분당 요청 300개를 허용하므로, 설정을 8 이하로 유지하세요:
results = chain.batch(
[{"tone": "dry", "text": t} for t in documents],
config={"max_concurrency": 6},
)
체험 키는 동시 요청 2개와 분당 60개만 허용하므로 테스트 중에는 max_concurrency를 2로 사용하세요.
스트리밍
API는 Server-Sent Events를 통해 스트리밍되며 LangChain은 이를 stream로 노출합니다. 사람이 답변이 형성되는 것을 보는 채팅 인터페이스에 사용하세요.
for chunk in llm.stream("Write a short scene set in a lighthouse."):
print(chunk.content, end="", flush=True)
실용적인 세부 사항: 스트리밍 요청은 스트림이 끝날 때까지 병렬성 슬롯을 유지합니다. UI가 스트림을 중간에 중단하는 경우 생성기가 닫히도록 하여 병렬성 여유가 줄어들지 않도록 하세요. 비동기 코드는 동일한 방식으로 astream를 사용합니다.
도구 및 에이전트
도구 호출이 지원됩니다: API는 tools 및 tool_choice을 받고 tool_calls를 스트리밍하며 role: "tool" 메시지로 결과를 받습니다. LangChain은 이를 bind_tools로 감쌉니다.
from langchain_core.tools import tool
@tool
def dice(sides: int) -> int:
"Roll a die with the given number of sides."
import random
return random.randint(1, sides)
llm_tools = llm.bind_tools([dice])
msg = llm_tools.invoke("Roll a twenty-sided die for the goblin attack.")
print(msg.tool_calls)
결과는 모델이 원하는 호출 목록을 표시하며 이름과 인수가 포함됩니다. 이를 실행하고 결과를 도구 메시지로 추가한 후 모델을 다시 호출하거나 LangGraph와 같은 에이전트 프레임워크가 해당 루프를 실행하도록 하세요. 에이전트는 사용자 요청당 많은 호출을 수행하므로 단순 체인보다 분당 제한에 더 빨리 도달합니다. 병렬성 수준을 선택하기 전에 실행당 호출 수를 세어 보세요.
컨텍스트 창은 프롬프트와 출력(completion)을 합쳐 100,000 토큰이며, 대화 기억에는 넉넉한 수치입니다. 그럼에도 불구하고 이전 턴을 정리하세요: 모든 호출에서 전체 기록에 대해 요금이 부과되며, 입력 토큰 1M당 $0.15입니다.
JSON 출력
JSON 모드는 response_format을 통해 제공됩니다. LangChain에서는 model_kwargs로 전달하거나 JSON 모드에서 구조화된 출력 도우미를 사용하고 프롬프트에서 필드를 설명할 수 있습니다.
from pydantic import BaseModel
class Character(BaseModel):
name: str
role: str
secret: str
structured = llm.with_structured_output(Character, method="json_mode")
out = structured.invoke(
"Invent a character for a mystery story. Reply in JSON with keys name, role, secret."
)
print(out)
method="json_mode"를 사용할 때 프롬프트는 모델이 생성할 키를 알려 줘야 합니다. Pydantic 클래스는 파싱된 결과를 검증합니다. 가끔 발생하는 잘못된 응답에 대비해 재시도 로직을 두세요.
지원되지 않는 부분
LangChain의 주요 구성 요소 두 가지는 다른 소스가 필요합니다. API에는 임베딩 엔드포인트가 없으므로, 여기를 가리키는 OpenAIEmbeddings은 실패합니다. 문서에 대한 검색에는 로컬 임베딩 모델이나 다른 임베딩 제공업체를 사용하고, 이 엔드포인트는 채팅 단계에만 사용하세요. 이미지 입력 또는 생성, 오디오, 파인튜닝도 지원하지 않으므로 비전 체인 및 멀티모달 로더는 사용할 수 없습니다.
오류 처리는 주로 429 응답에 관한 것입니다. 코드 rate_limited은 분당 한도를 초과했음을 의미하며, concurrency은 병렬 호출이 너무 많음을 의미하며, Retry-After: 5가 있는 429는 일시적 과부하를 표시합니다. ChatOpenAI에 max_retries을 설정하여 클라이언트가 대기하고 재시도하게 하세요. 실패 및 거부된 요청은 청구되지 않습니다.
응답 헤더는 모니터링에 도움이 됩니다: X-Balance-USD은 남은 크레딧을 표시하고 X-Request-Id는 지원용 호출을 식별합니다.
하나의 변수로 로컬과 호스팅 간 전환
하이브리드 설정을 원한다면 세 가지 설정을 환경 변수에 넣고 하나의 함수에서 모델을 빌드하세요. 체인은 해당 함수를 가져오고 벤더를 언급하지 않습니다.
import os
from langchain_openai import ChatOpenAI
def make_llm():
if os.environ.get("LLM_MODE") == "local":
return ChatOpenAI(
model=os.environ["LOCAL_MODEL"],
base_url="http://localhost:11434/v1",
api_key="not-needed",
)
return ChatOpenAI(
model="uncensored",
base_url="https://api.llmproxyapi.com/v1",
api_key=os.environ["LLMPROXY_API_KEY"],
)
로컬 분기는 기본 포트에서 Ollama 서버를 가정하며, 이는 /v1 아래에 OpenAI 스타일 라우트를 노출합니다. 올바른 주소와 모델 이름을 위해 자체 서버 설명서를 확인하세요. 모델 간 동작이 다르므로 전환 후 프롬프트를 다시 실행하세요. 하나의 모델 습관에 맞게 조정된 프롬프트는 다른 모델에서 다르게 동작할 수 있으며 도구 호출 품질은 모델에 따라 다르므로 해당 경로를 먼저 테스트하세요.
현실적인 워크플로는 GPU가 없을 때 호스팅 모델에 대해 프롬프트를 개발한 다음 앱의 어떤 부분이 자체 머신에 남아야 하는지 결정하는 것입니다. 민감한 문서는 로컬 분기를 사용하고 공개적인 창의적 기능은 호스팅된 모델을 사용할 수 있습니다.
비용 및 다음 단계
가격은 선불 크레딧으로 구독 없이 입력 토큰 1M당 $0.15, 출력 토큰 1M당 $0.50입니다. 2,000개의 입력 토큰과 500개의 출력 토큰이 있는 체인 호출은 2,000 x $0.15 / 1M + 500 x $0.50 / 1M = $0.0003 + $0.00025 = $0.00055가 듭니다. 천 번의 호출은 $0.55가 듭니다. 충전은 암호화폐(TRC20의 USDT, Base의 USDC)로 $20부터 $500까지 가능하며, $50부터 5%, $100부터 10%, $200부터 15%의 보너스가 있습니다. 세부 정보는 가격 페이지에 있습니다.
동일한 API의 일반 HTTP 보기를 위해 빠른 시작을 읽으세요. 사이트에는 사용량 기반 서비스에 대한 짧은 개요도 있습니다.
