LangChain и LangGraph без API-ключа

Что на практике может означать «без API-ключа»

Поиск по запросу langchain и langraph без api key обычно означает одно из трёх. Вы можете захотеть избежать оплаты до тех пор, пока не убедитесь, что стек работает. Вы можете не хотеть передавать кредитную карту ещё одному поставщику. Или вы можете надеяться запустить граф агента вообще без учётных данных.

Третье желание невозможно реализовать для любого хостингового сервиса: сервер, выполняющий работу, должен знать, кто его вызывает. Что вы можете получить, так это ключ, который ничего не стоит и не требует привязки карты. Новые пользователи на этом сайте могут получить $0,50 пробного баланса в один клик на странице API-ключа после регистрации через Google или по электронной почте и паролю. Он выдаётся один раз на человека и действителен в течение 7 дней.

Другой путь к «отсутствию ключа» — локальная модель, обслуживаемая чем-то на вашей собственной машине. Это работает, но вы несёте расходы на оборудование, и ноутбук не сравнится с хостинговым эндпоинтом при длительных запусках агентов. Хостинговый пробный запуск — более быстрый способ убедиться, что логика вашего графа корректна, а код, который вы напишете, будет идентичен тому, что вы запустите позже с оплаченным ключом.

Поскольку эндпоинт совместим с OpenAI, LangChain не требует специальной интеграции. Вы указываете его классу ChatOpenAI другой base URL, передаёте ключ и указываете модель uncensored. Всё, что описано ниже, предполагает эту настройку.

Шаг 1: получите пробный ключ и настройте окружение

Зарегистрируйтесь, откройте страницу ключей и нажмите кнопку пробного ключа. Скопируйте ключ и храните его вне репозитория. Поместите его в переменную окружения, чтобы тот же скрипт работал с пробным ключом сегодня и с полным ключом позже.

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

Прежде чем подключать любой фреймворк, проверьте ключ простым запросом. Две минуты здесь сэкономят час чтения трассировок стека, которые на самом деле являются ошибками аутентификации.

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 на эндпоинт

Используемый класс — ChatOpenAI из langchain-openai. Два аргумента делают работу: 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(...), и фрагменты поступают через события, отправляемые сервером, а использование сообщается в конце потока.

Одна распространённая ошибка — оставление переменной OPENAI_API_KEY установленной из старого проекта. LangChain с радостью отправит это значение на ваш базовый URL, если вы забудете передать api_key. Передайте ключ явно, и вы устраните неопределённость.

Шаг 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. Любой узел может использовать другой объект модели, поэтому вы можете позже задать дешёвому шагу планирования и более длинному шагу написания свои собственные настройки, такие как более низкая температура для планирования.

Шаг 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 инструмента, снизьте температуру и сделайте схему аргументов компактной. Короткие типизированные схемы реже дают сбои, чем длинные с множеством необязательных полей.

Лимиты запросов, повторные попытки и параллельные ветвления

Место, где графы агентов чаще всего спотыкаются, — это параллельность. Полный ключ позволяет 8 параллельных запросов и 300 запросов в минуту; пробный ключ позволяет 2 и 60. Если ваш граф разветвляется на пять параллельных узлов с пробным ключом, три из них будут отклонены с HTTP 429 и кодом ошибки concurrency. Превышение лимита в минуту возвращает rate_limited. Временная перегрузка также даёт 429 с заголовком Retry-After: 5.

Три привычки делают это управляемым:

• Держите max_retries на уровне 2 или 3 на ChatOpenAI, чтобы короткие ответы 429 повторялись с экспоненциальной задержкой.
• Ограничьте ветвление вашим лимитом параллельности. В 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. Выведите первые четыре символа значения, которое фактически использует ваш скрипт.
2. 404 или модель не найдена. Имя модели должно быть uncensored. Вызовите GET /v1/models, если вы не уверены, что перечисляет конечная точка.
3. Ошибки соединения. Базовый URL должен заканчиваться на /v1 и не должен включать /chat/completions; клиент добавляет эту часть сам.
4. Бесконечные циклы. Если агент продолжает вызывать инструмент, возвращаемое значение инструмента может не отвечать на вопрос. Возвращайте простые, короткие строки и установите лимит рекурсии через конфигурацию графа, чтобы плохой цикл останавливался рано.
5. Пустые или странные ответы. Выведите полный список сообщений после запуска. Часто более ранний узел написал системное сообщение, которое противоречит более позднему.

Когда запрос завершается неудачей на стороне сервера, укажите заголовок X-Request-Id в вашем сообщении в поддержку. Это позволяет им найти этот конкретный вызов без догадок. Также имейте в виду, что неудачные или отклонённые запросы не оплачиваются, поэтому сеанс отладки, полный ошибок, не съест ваши пробный баланс.

Ещё один принцип дизайна. Дайте каждому узлу узкую задачу и короткий промпт. Граф с планировщиком, генератором текста и проверяющим, каждый со своим небольшим системным сообщением, легче тестировать, чем один узел со страницей инструкций, и каждый компонент можно попробовать отдельно с прямым вызовом llm.invoke перед его подключением.

Сколько на самом деле стоит пробный запуск

Тарификация составляет $0,15 за 1M входных токенов и $0,50 за 1M выходных токенов из предоплаченного баланса. Неудачные или отклонённые запросы не оплачиваются. Графы агентов вызывают модель несколько раз за задачу, и каждый вызов повторно отправляет растущий список сообщений, поэтому входные токены доминируют.

Рассмотрите запуск с шестью вызовами модели. Предположим, что каждый вызов отправляет 3 000 токенов на вход и возвращает 400 токенов на выход. Это 18 000 входных токенов и 2 400 выходных токенов.

• Вход: 18 000 / 1 000 000 × $0,15 = $0,0027
• Выход: 2 400 / 1 000 000 × $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 для генерации текста без цензуры для видеопромптов