시작하기 전에 필요한 항목
LangChain은 OpenAI 채팅 완성 프로토콜을 구현하는 모든 서버와 통신하므로 특별한 통합을 설치할 필요가 없습니다. 시작점은 OpenAI 자체를 위해 사용할 패키지와 동일합니다: Python의 경우 langchain-openai, Node의 경우 @langchain/openai입니다. 세 가지 값만 변경됩니다.
- 베이스 URL:
https://api.deepseekapipricing.com/v1 - 모델:
uncensored - 키:
Authorization: Bearer <key>로 전송되며 클라이언트가 이를 처리합니다.
이름에 대한 설명입니다. 이 엔드포인트는 콘텐츠 거부 없이 답변하는 데 특화된 단일 오픈 웨이트 모델을 실행하는 독립형 서비스입니다. 공식 DeepSeek API가 아니며 벤더 간 라우터도 아니므로 모델 이름은 항상 uncensored이며 벤더 모델 ID가 아닙니다. 키가 필요하면 API 키 페이지에서 가입 단계와 원클릭 $0.50 체험판을 확인할 수 있습니다.
Python에서 패키지 설치 및 첫 번째 호출
패키지를 설치하세요:
pip install -U langchain-openai langchain-core
# then use base_url https://api.deepseekapipricing.com/v1 and model "uncensored"
그런 다음 모델 객체를 생성합니다. 원치 않는 OpenAI 키가 다른 호스트로 전송될 수 있으므로 OPENAI_API_KEY 환경 변수에 의존하지 않고 키를 명시적으로 전달합니다.
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.deepseekapipricing.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
temperature=0.7,
max_retries=2,
)
print(llm.invoke("Say hello in five words.").content)
인사말이 출력되면 연결, 키 및 모델 이름이 모두 정확합니다. 이 단계에서 가장 흔한 실수는 베이스 URL에서 /v1을 누락하는 것으로, 이는 일반적으로 not-found 오류를 발생시킵니다.
프롬프트, 체인 및 스트리밍
이후에는 LangChain이 평소와 같이 작동합니다. 프롬프트 템플릿, 모델 및 출력 파서를 파이프 연산자로 조합하여 체인을 구성합니다:
# llm = ChatOpenAI(model="uncensored", base_url="https://api.deepseekapipricing.com/v1", ...)
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
prompt = ChatPromptTemplate.from_messages([
("system", "You write tight, vivid scene descriptions for adult fiction."),
("human", "Describe this setting in under 80 words: {setting}"),
])
chain = prompt | llm | StrOutputParser()
print(chain.invoke({"setting": "a flooded subway station at night"}))
스트리밍은 서버 전송 이벤트를 통해 이루어집니다. LangChain에서는 stream을 호출하고 각 청크에는 텍스트 조각이 포함됩니다. 스트림 끝에 토큰 개수를 보려면 모델에 stream_usage=True를 설정하세요. API는 마지막 이벤트에서 사용량 정보를 전송합니다.
llm_stream = ChatOpenAI(
model="uncensored",
base_url="https://api.deepseekapipricing.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
stream_usage=True,
)
for chunk in llm_stream.stream("Write a four-line poem about a night train."):
print(chunk.content, end="", flush=True)
스트리밍 요청은 스트림이 완료될 때까지 동시성 슬롯을 유지하므로, 스트림을 닫지 않고 중단하면 해당 슬롯이 예상보다 오래 점유된 상태로 유지됩니다.
Node 및 TypeScript
JavaScript 패키지는 베이스 URL을 configuration 객체 내부에 받습니다:
import { ChatOpenAI } from "@langchain/openai";
const llm = new ChatOpenAI({
model: "uncensored",
apiKey: process.env.UNCENSORED_API_KEY,
configuration: { baseURL: "https://api.deepseekapipricing.com/v1" },
maxRetries: 2,
});
const res = await llm.invoke("Say hello in five words.");
console.log(res.content);
const stream = await llm.stream("Write a four-line poem about a night train.");
for await (const chunk of stream) {
process.stdout.write(chunk.content);
}
ES 모듈로 실행합니다("type": "module"을 package.json에 설정하거나, 또는 .mjs 파일). Node API의 나머지 모든 부분, 프롬프트 템플릿과 runnable을 포함한 모든 것은 다른 채팅 모델과 동일하게 동작합니다.
함수 호출 및 에이전트
API는 OpenAI 도구 형식을 지원합니다: tools 및 tool_choice 파라미터, 스트리밍 tool_calls 및 role: "tool" 메시지로 반환되는 도구 결과입니다. LangChain에서는 데코레이터로 도구를 선언하고 bind_tools로 연결합니다:
# llm = ChatOpenAI(model="uncensored", base_url="https://api.deepseekapipricing.com/v1", ...)
from langchain_core.tools import tool
from langchain_core.messages import HumanMessage, ToolMessage
@tool
def order_status(order_id: str) -> str:
"""Return the shipping status of an order."""
return f"Order {order_id} left the warehouse yesterday."
llm_tools = llm.bind_tools([order_status])
messages = [HumanMessage("Where is order 1042?")]
ai = llm_tools.invoke(messages)
messages.append(ai)
for call in ai.tool_calls:
result = order_status.invoke(call["args"])
messages.append(ToolMessage(content=result, tool_call_id=call["id"]))
print(llm_tools.invoke(messages).content)
한 번 직접 루프를 작성하는 것은 10분의 가치가 있습니다. 이는 모델이 반환한 내용, 각 호출에 대해 선택한 인수 및 잘못된 도구 설명이 잘못된 추측으로 이어지는 지점을 정확히 보여줍니다. 이것이 명확해지면 사전 구축된 에이전트로 전환하고 디버깅 참조용으로 직접 작성한 버전을 유지하세요.
직접 작성한 전체 루프는 다음과 같습니다: 모델이 도구를 요청하면, 실행하고, 결과를 반환하며, 모델이 최종 답변을 작성합니다. 미리 만들어진 에이전트 루프를 선호한다면 langgraph 패키지는 create_react_agent(llm, [order_status])를 제공하며, {"messages": [("user", "Where is order 1042?")]}로 호출합니다.
모델이 도구를 선택하는 방식은 모델에 따라 다르므로 실제 도구 스키마로 테스트해야 합니다. 짧고 구체적인 도구 설명과 낮은 temperature가 도움이 됩니다. 약 27,000개의 입력 토큰과 1,800개의 출력 토큰을 가진 6번의 호출을 수행하는 에이전트는 약 $0.00405 + $0.0009, 즉 약 0.5센트의 비용이 듭니다.
JSON 모드를 사용한 구조화된 출력
JSON 모드는 response_format을 통해 지원됩니다. 모델에 바인딩하고 프롬프트에서 특정 키가 있는 JSON을 원한다고 명시하세요. 형식 플래그는 스키마가 아닌 구문을 제어하기 때문입니다:
# llm = ChatOpenAI(model="uncensored", base_url="https://api.deepseekapipricing.com/v1", ...)
import json
json_llm = llm.bind(response_format={"type": "json_object"})
msg = json_llm.invoke(
"Return a JSON object with keys title (string) and tags (list of 3 strings) "
"for a short story about a lighthouse keeper."
)
data = json.loads(msg.content)
print(data["title"], data["tags"])
Pydantic 또는 자체 검증으로 파싱된 결과를 신뢰하기 전에 검증하고, json.JSONDecodeError을 한 번의 재시도로 처리하세요. 대규모 추출 작업의 경우 첫 번째 응답이 깨끗하다고 가정하지 말고 모든 응답을 방어적으로 파싱하세요.
검색, 메모리 및 콜백
이 API에는 임베딩 엔드포인트가 없으므로 검색 파이프라인은 별도의 임베딩 소스가 필요합니다. 검색 이후의 모든 과정은 일반 채팅과 동일합니다. 일반적인 검색 체인은 벡터 저장소에서 상위 문서 조각들을 가져와 프롬프트에 삽입한 후, 해당 텍스트를 바탕으로 모델이 답변하도록 요청합니다. 컨텍스트 창이 100,000 토큰이므로 충분한 길이의 문서 조각을 사용할 수 있지만, 요금을 기억하세요: 검색된 컨텍스트의 모든 토큰은 입력으로 처리되며 백만 토큰당 $0.15의 요금이 발생하므로, 20,000 토큰의 컨텍스트는 질문당 $0.003의 비용이 듭니다.
채팅 메모리의 경우 가장 간단한 접근 방식은 각 호출 전에 토큰 개수로 메시지 목록을 자르는 것입니다. LangChain에는 이를 위한 trim_messages과 같은 도우미가 제공됩니다. 시스템 메시지와 최신 턴을 유지하고, 기록이 선택한 한도에 도달하면 중간 부분을 삭제하거나 요약하세요. 더 짧은 기록은 답변을 집중시키고, 전체 기록이 매번 입력으로 다시 전송되므로 각 턴의 비용을 낮춥니다.
콜백은 호출 비용을 기록하는 곳입니다. 각 응답에는 프롬프트 및 완성 토큰을 포함하는 사용량 블록이 있으며, LangChain에서 반환된 메시지에는 usage_metadata에 포함되어 있습니다:
# llm = ChatOpenAI(model="uncensored", base_url="https://api.deepseekapipricing.com/v1", ...)
msg = llm.invoke("Name three rivers.")
u = msg.usage_metadata
cost = u["input_tokens"] * 0.15 / 1_000_000 + u["output_tokens"] * 0.50 / 1_000_000
print(u, f"${cost:.6f}")
요청 ID와 함께 비용을 로깅하여 놀라운 청구 내역을 하나의 체인으로 추적할 수 있습니다.
시스템 프롬프트 및 어조
모델에는 내장된 콘텐츠 거부가 없으므로 시스템 메시지에서 제품 동작을 설정합니다: 페르소나, 어조, 피해야 할 주제 및 응답 형식입니다. 새로운 동료에게 주는 간략한 설명처럼 작성하세요. 짧고 구체적이어야 하며 길고 모호한 것보다 낫습니다. 미성년자가 관련된 콘텐츠는 이 서비스에서 엄격한 제한 사항이므로 이에 근접하는 프롬프트를 만들지 마세요.
출시 전 짧은 체크리스트
- 키는 환경 변수나 비밀 저장소에 보관하며 저장소에는 절대 포함하지 마세요.
max_concurrency는 키의 제한에 맞게 설정하거나 다른 서비스가 키를 공유하는 경우 그 이하로 설정하세요.- 재시도는 짧은 백오프를 사용하며,
Retry-After: 5가 포함된 429 응답을 따릅니다. - 클라이언트 연결 해제 시 스트림을 닫아 슬롯을 해제합니다.
- JSON 출력은 방어적으로 파싱되고 검증됩니다.
- 사용량 블록에서 체인별로 비용이 로깅됩니다.
- 엔드포인트에 도달할 수 없는 경우를 위한 대체 방법이 존재하며, 대체 방법이 오류 메시지일 수도 있습니다.
해당 목록을 따르면 통합이 다른 모든 LangChain 채팅 모델처럼 동작합니다. 차이점은 콘텐츠 측면에 있는데, 다른 모델이 합법적인 성인 사용에 대해서도 거부하는 요청에 답변합니다.
속도 제한, 동시성 및 일반 오류
전체 키는 분당 300개의 요청과 8개의 동시 요청을 허용합니다. 체험 키는 분당 60개의 요청과 2개의 동시 요청을 허용합니다. 요청 본문은 최대 8 MB이며, 컨텍스트 창은 프롬프트와 완성을 합쳐 100,000 토큰입니다.
LangChain의 배치 도우미는 요청을 분산하므로 키에 맞는 상한을 설정하세요:
# llm = ChatOpenAI(model="uncensored", base_url="https://api.deepseekapipricing.com/v1", ...)
inputs = [{"setting": s} for s in ["a rooftop garden", "a desert diner", "a quiet harbor"]]
results = chain.batch(inputs, config={"max_concurrency": 8})
체험 키에는 2를 8 대신 사용하세요. 한도를 초과하면 API는 HTTP 429를 반환하며 오류 코드 rate_limited(분당 요청 수 초과) 또는 concurrency(동시 요청 초과)을 반환합니다. 일시적 과부하 시에도 429를 반환하며 Retry-After: 5 헤더를 포함합니다. 클라이언트의 max_retries 설정은 일시적 문제를 처리하지만, concurrency 오류 코드가 반복되면 재시도를 추가하는 대신 max_concurrency을 낮추세요.
- 모든 호출에서 존재하지 않음 오류 발생: 베이스 URL이
/v1로 끝나는지 확인하세요. - 인증 오류: 키가 누락되었거나 오타가 있습니다;
api_key를 통해 전달되었는지 확인하세요. - 모델 오류: 모델 이름은 정확히
uncensored여야 합니다. - 느린 배치 실행: 중단된 스트림은 동시성 슬롯을 점유하므로, 스트림을 종료하거나 시간 제한을 설정하세요.
가격은 입력 토큰 백만 토큰당 $0.15, 출력 토큰 백만 토큰당 $0.50이며, 실패하거나 거부된 요청에는 요금이 부과되지 않습니다. 가격 페이지에는 충전 방법이 나열되어 있고, 문서에는 모든 파라미터와 응답 헤더가 포함되어 있으며, 여기에는 LangChain 콜백에 로깅하기 편리한 X-Request-Id 및 X-Balance-USD이 포함됩니다.
