API 키 없이 LangChain과 LangGraph과 LangGraph과 LangGraph

"API 키 없이"가 실제로 의미할 수 있는 것

API 키 없는 langchain 및 langraph를 검색하는 것은 보통 세 가지 의미 중 하나를 나타냅니다. 스택이 작동하는지 확인하기 전에 비용을 지불하고 싶지 않을 수 있습니다. 또 다른 벤더에 신용 카드를 넘기고 싶지 않을 수도 있습니다. 또는 자격 증명이 전혀 없이 에이전트 그래프를 실행하기를 희망할 수도 있습니다.

세 번째 소원은 호스팅 서비스로 충족할 수 없습니다: 작업을 수행하는 서버는 호출자가 누구인지 알아야 합니다. 얻을 수 있는 것은 카드가 필요 없으며 비용이 들지 않는 키입니다. Google 또는 이메일과 비밀번호로 가입한 후 API 키 페이지에서 한 번의 클릭으로 $0.50의 무료 체험 크레딧을 받을 수 있습니다. 이는 사람당 하나이며 7일 동안 유효합니다.

"키 없음"에 도달하는 다른 경로는 자체 머신에서 실행되는 로컬 모델입니다. 이는 작동하지만 하드웨어를 직접 관리해야 하며, 긴 에이전트 실행의 경우 로컬 모델이 호스팅 엔드포인트를 따라잡기 어렵습니다. 호스팅 서비스의 체험판은 그래프 로직이 올바른지 확인하는 더 빠른 방법이며, 작성한 코드는 나중에 잔액이 있는 키로 실행할 코드와 동일합니다.

엔드포인트가 OpenAI 호환이므로 LangChain은 특수 통합이 필요하지 않습니다. OpenAI 채팅 클래스의 base URL을 다른 곳으로 지정하고 키를 제공한 후 모델 이름을 uncensored로 지정합니다. 아래 내용은 이 설정을 가정합니다.

1단계: 체험 키 획득 및 환경 설정

가입하고 키 페이지를 연 후 체험 버튼을 누릅니다. 키를 복사하여 저장소 밖에 보관하세요. 환경 변수에 넣으면 동일한 스크립트가 오늘 체험 키로, 나중에 전체 키로도 작동합니다.

Copyexport UNCENSORED_API_KEY="paste-your-key-here"
pip install -U langchain-openai langgraph langchain-core

어떤 프레임워크를 사용하기 전에 일반 요청으로 키를 확인하세요. 여기서 2분을 투자하면 실제 인증 오류인 스택 트레이스 확인에 1시간을 절약할 수 있습니다.

Copycurl https://api.stableaudio.top/v1/chat/completions \
  -H "Authorization: Bearer $UNCENSORED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"uncensored","messages":[{"role":"user","content":"Reply with one word: ready"}]}'

GET /v1/models 호출은 다른 빠른 확인 방법입니다. uncensored가 나열되어야 합니다. 체험 키는 동시 요청 2개와 분당 60개의 요청을 허용하며, 그래프 개발에는 충분하지만 병렬 노드를 추가할 때 기억해 두는 것이 좋습니다.

2단계: LangChain을 엔드포인트에 연결

사용할 클래스는 langchain-openai의 ChatOpenAI입니다. 두 인자로 설정합니다: base_url 및 api_key. 모델 이름은 uncensored이며, 일반적인 샘플링 설정이 전달됩니다.

Copyimport os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.stableaudio.top/v1",
    api_key=os.environ["UNCENSORED_API_KEY"],
    temperature=0.7,
    max_retries=3,
)

print(llm.invoke("Give me three titles for an ambient track about rain.").content)

이것이 텍스트를 출력하면 연결이 양호합니다. 스트리밍도 동일한 방식으로 작동합니다: llm.stream(...)를 반복하면 청크가 서버 전송 이벤트(SSE)를 통해 도착하며 스트림 끝에 사용량이 보고됩니다.

흔한 실수 중 하나는 오래된 프로젝트에서 설정된 OPENAI_API_KEY 변수를 그대로 두는 것입니다. api_key을 전달하는 것을 잊으면 LangChain은 해당 값을 커스텀 base URL로 보낼 수 있습니다. 키를 명시적으로 전달하면 추측을 없앨 수 있습니다.

3단계: 최소한의 LangGraph 그래프

LangGraph는 에이전트를 노드 간에 이동하는 상태로 모델링합니다. 유용한 최소 그래프에는 모델을 호출하고 응답을 메시지 목록에 추가하는 하나의 노드가 있습니다. MessagesState은 이 목록을 무료로 제공합니다.

Copyfrom langgraph.graph import StateGraph, MessagesState, START, END

def call_model(state: MessagesState):
    reply = llm.invoke(state["messages"])
    return {"messages": [reply]}

builder = StateGraph(MessagesState)
builder.add_node("model", call_model)
builder.add_edge(START, "model")
builder.add_edge("model", END)
graph = builder.compile()

out = graph.invoke({"messages": [("user", "Outline a three-act short story about a lighthouse keeper.")]})
print(out["messages"][-1].content)

의도적으로 단순하게 작성했습니다. LangGraph의 핵심은 llm 뒤에 어떤 공급자가 있는지 알거나 신경 쓰지 않는다는 점입니다. 모든 노드는 다른 모델 객체를 사용할 수 있으므로 나중에 저렴한 계획 단계와 긴 쓰기 단계에 각각 다른 설정(예: 계획용 낮은 temperature)을 제공할 수 있습니다.

4단계: 도구 및 루프 추가

모델이 함수를 호출할 수 있을 때 에이전트는 흥미로워집니다. 엔드포인트는 tools 및 tool_choice로 함수 호출을 지원하며, 도구 결과는 role: "tool" 메시지로 반환됩니다. LangChain 및 LangGraph는 이러한 하부 구조를 처리합니다.

Copyfrom langchain_core.tools import tool
from langgraph.prebuilt import ToolNode, tools_condition

@tool
def word_count(text: str) -> int:
    'Count the words in a piece of text.'
    return len(text.split())

tools = [word_count]
llm_with_tools = llm.bind_tools(tools)

def agent(state: MessagesState):
    return {"messages": [llm_with_tools.invoke(state["messages"])]}

builder = StateGraph(MessagesState)
builder.add_node("agent", agent)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", tools_condition)
builder.add_edge("tools", "agent")
graph = builder.compile()

result = graph.invoke({"messages": [("user", "Write a 40-word product blurb, then check its word count with the tool.")]})
print(result["messages"][-1].content)

루프가 핵심 아이디어입니다: 에이전트 노드가 응답하고, tools_condition이 응답이 도구를 요청했는지 확인하며, 도구 노드가 이를 실행하고 제어가 에이전트로 돌아갑니다. 응답에 도구 호출이 없으면 그래프가 종료됩니다.

오픈 웨이트 모델은 도구 인자의 정리 방식이 다양합니다. 호출이 잘못된 형식으로 반환되면 도구의 docstring을 보완하고, temperature를 낮추며, 인자 스키마를 작게 유지하세요. 선택적 필드가 많은 긴 스키마보다 짧고 타입이 지정된 스키마가 실패할 가능성이 적습니다.

속도 제한, 재시도 및 병렬 분기

에이전트 그래프가 가장 자주 막히는 곳은 동시성입니다. 전체 키는 동시 요청 8개와 분당 300개의 요청을 허용하며, 체험 키는 각각 2개와 60개를 허용합니다. 체험 키에서 그래프가 5개의 병렬 노드로 확장되면 3개가 HTTP 429 오류와 concurrency 오류 코드로 거부됩니다. 분당 예산을 초과하면 rate_limited이 반환됩니다. 일시적 과부하도 429를 반환하며, Retry-After: 5 헤더가 포함됩니다.

이를 관리하기 위한 세 가지 습관:

• 짧은 429 오류를 백오프로 재시도하도록 ChatOpenAI에서 max_retries를 2 또는 3으로 유지하세요.
• 동시성 한도 내에서 분기를 제한하세요. LangGraph에서는 그래프를 호출할 때 config={"max_concurrency": 2}를 전달할 수 있습니다.
• 스트리밍 요청은 스트림이 끝날 때까지 슬롯을 유지하므로, 느린 소비자는 슬롯을 점유한 상태로 유지합니다.

Copyout = graph.invoke(
    {"messages": [("user", "Draft five taglines in parallel.")]},
    config={"max_concurrency": 2},
)

응답 헤더는 디버깅에 도움이 됩니다. X-Request-Id은 지원팀에 문의할 때 호출을 식별하며, X-Balance-USD은 각 요청 후 남은 크레딧을 보여줍니다.

그래프가 비정상적으로 작동할 때의 디버깅 체크리스트

첫 LangGraph 프로젝트의 대부분의 실패는 모델과 관련이 없습니다. 구성에서 비롯되며 짧은 체크리스트로 거의 모든 문제를 잡을 수 있습니다.

1. 401 또는 인증 오류. 키가 누락되었거나 오타가 있거나, 오래된 OPENAI_API_KEY이 읽히고 있습니다. 스크립트가 실제로 사용하는 값의 처음 4자를 출력하세요.
2. 404 또는 모델을 찾을 수 없음. 모델 이름은 uncensored여야 합니다. 엔드포인트가 나열하는 모델이 확실하지 않다면 GET /v1/models를 호출하세요.
3. 연결 오류. base URL은 /v1로 끝나야 하며 /chat/completions을 포함해서는 안 됩니다. 클라이언트가 해당 부분을 추가합니다.
4. 무한 루프. 에이전트가 도구를 계속 호출한다면, 도구의 반환값이 질문에 답하지 못했을 수 있습니다. 일반적이고 짧은 문자열을 반환하고 그래프 구성을 통해 재귀 한도를 설정하여 잘못된 루프가 조기에 중단되도록 하세요.
5. 빈 응답 또는 이상한 응답. 실행 후 전체 메시지 목록을 출력하세요. 종종 이전 노드가 나중에 작성된 메시지와 모순되는 시스템 메시지를 작성했을 수 있습니다.

서버 측에서 요청이 실패하면 support에 보낼 메시지에 X-Request-Id 헤더를 인용하세요. 이렇게 하면 추측 없이 해당 정확한 호출을 찾을 수 있습니다. 실패하거나 거부된 요청에는 요금이 청구되지 않으므로 오류로 가득 찬 디버깅 세션이 체험 크레딧을 소모하지 않는다는 점도 기억하세요.

또 다른 설계 포인트입니다. 각 노드에 좁은 작업과 짧은 프롬프트를 부여하세요. 계획자, 작성자, 검사기로 구성된 그래프는 각각 작은 시스템 메시지로 구성되어 단일 노드가 여러 페이지의 지시를 가진 것보다 테스트하기 쉬우며, 각 부분은 연결하기 전에 직접 llm.invoke 호출로 단독으로 시도할 수 있습니다.

체험 실행의 실제 비용

가격은 선불 크레딧 기준 입력 토큰 100만 개당 $0.15, 출력 토큰 100만 개당 $0.50입니다. 실패하거나 거부된 요청에는 요금이 청구되지 않습니다. 에이전트 그래프는 작업당 여러 번 모델을 호출하며, 모든 호출은 증가하는 메시지 목록을 다시 전송하므로 입력 토큰이 대부분을 차지합니다.

모델 호출 6회를 실행해 보세요. 각 호출이 3,000개의 토큰을 입력하고 400개의 토큰을 반환한다고 가정해 봅시다. 이는 18,000개의 입력 토큰과 2,400개의 출력 토큰입니다.

• 입력: 18,000 / 1,000,000 x $0.15 = $0.0027
• 출력: 2,400 / 1,000,000 x $0.50 = $0.0012
• 총 비용: 실행당 $0.0039

$0.50 체험금을 $0.0039로 나누면 해당 크기의 실행이 약 128회 가능하며, 그래프를 제대로 구축하고 테스트하기에 충분합니다. 체험금이 소진되면 $20부터 $500까지 정액으로 충전할 수 있으며, $50 이상은 5%, $100 이상은 10%, $200 이상은 15% 보너스가 제공됩니다. 가격 페이지에서 세부 사항을 확인하세요. 카드로(Visa, Mastercard, Apple Pay, Google Pay) 또는 암호화폐(USDT(TRC20), USDC(Base))로 결제할 수 있습니다. 크레딧은 만료되지 않으며 프롬프트는 학습에 사용되지 않습니다.

프롬프트와 생성을 합친 컨텍스트 창은 100,000 토큰까지 지원하므로 긴 에이전트 기록도 처리할 수 있지만, 다시 전송하는 모든 토큰에 대해 요금이 부과됩니다. LangGraph의 메시지 유틸리티를 사용하여 오래된 메시지를 정리하면 비용과 지연 시간을 줄일 수 있습니다. 관련 모든 요청의 기본 형식에 대해서는 API 문서를 참조하세요.

더 많은 가이드

• 텍스트-오디오 LLM: 가능한 것과 불가능한 것
• 비디오 프롬프트용 무검열 텍스트 API