LangChain4j: подключаем Java-приложение к Claude и GPT через шлюз

Когда говорят «LangChain Java», обычно имеют в виду библиотеку LangChain4j: это отдельный проект для JVM со своим API, а не порт на Java кода из Python. У неё есть модуль для OpenAI-совместимых серверов, и именно он позволяет направить приложение на шлюз и вызывать оттуда Claude, GPT, DeepSeek и другие модели без смены кода. Разберём настройку на Maven и Spring Boot, потоковый ответ и сервис с инструментами.

LangChain Java: что подключаем и зачем

В документации LangChain4j модуль langchain4j-open-ai описан как собственная реализация REST-клиента OpenAI, которая лучше всего работает со Spring и Quarkus. У билдера есть параметры baseUrl, apiKey и modelName. Нам нужны ровно они: Zukko принимает запросы формата Chat Completions по адресу https://api.zukko.pro/v1, поэтому остаётся подставить свой адрес, ключ fetch_... и имя модели из каталога.

Плюс такого подхода в том, что модель выбирается строкой. Переключиться с claude-sonnet-5-5 на gpt-6.1-sol или glm-5.3-flash можно без перекомпиляции, если вынести имя в настройки.

Зависимость

Для обычного Java-проекта:

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai</artifactId>
    <version>1.22.0</version>
</dependency>

Версия 1.22.0 указана в документации на момент подготовки статьи. Актуальную версию сверьте на docs.langchain4j.dev↗, потому что библиотека обновляется часто. Ключ положите в переменную окружения:

export ZUKKO_API_KEY="fetch_ваш_ключ"

Баланс пополняется от $1: СБП (платёжная страница добавляет 8,5% сверху), криптовалюта, карты MasterCard.

Простой чат

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;

public class Main {
    public static void main(String[] args) {
        ChatModel model = OpenAiChatModel.builder()
                .baseUrl("https://api.zukko.pro/v1")
                .apiKey(System.getenv("ZUKKO_API_KEY"))
                .modelName("claude-sonnet-5-5")
                .temperature(0.0)
                .build();

        String answer = model.chat("Чем record отличается от обычного класса в Java?");
        System.out.println(answer);
    }
}

Если ответ пришёл, подключение работает. Дальше всё стандартно для LangChain4j: сообщения, память, шаблоны. Параметры самого запроса описаны в справочнике Chat Completions↗.

Spring Boot

В Spring Boot вместо билдера настраивают application.properties. Имена свойств взяты из документации модуля:

langchain4j.open-ai.chat-model.base-url=https://api.zukko.pro/v1
langchain4j.open-ai.chat-model.api-key=${ZUKKO_API_KEY}
langchain4j.open-ai.chat-model.model-name=claude-sonnet-5-5

Для этого подключается стартер langchain4j-open-ai-spring-boot-starter. Это вариант для Spring Boot 3; для Spring Boot 4 документация указывает отдельный стартер langchain4j-open-ai-spring-boot4-starter, поэтому выбирайте по версии вашего Spring. После этого создаётся бин ChatModel, который можно внедрять в контроллеры и сервисы. Если вы работаете со Spring AI, а не LangChain4j, смотрите заметку о Spring AI↗.

Стриминг

Для потокового вывода есть отдельный класс OpenAiStreamingChatModel. Через AI Services его удобно использовать с возвращаемым типом TokenStream:

import dev.langchain4j.model.openai.OpenAiStreamingChatModel;
import dev.langchain4j.service.AiServices;
import dev.langchain4j.service.TokenStream;

interface Assistant {
    TokenStream chat(String message);
}

var streamingModel = OpenAiStreamingChatModel.builder()
        .baseUrl("https://api.zukko.pro/v1")
        .apiKey(System.getenv("ZUKKO_API_KEY"))
        .modelName("gpt-6.1-sol")
        .build();

Assistant assistant = AiServices.create(Assistant.class, streamingModel);

assistant.chat("Объясни, как работает сборщик мусора G1")
        .onPartialResponse(System.out::print)
        .onCompleteResponse(r -> System.out.println("\n[готово]"))
        .onError(Throwable::printStackTrace)
        .start();

Метод start() запускает поток, а не блокирует вызывающий поток, поэтому в консольной программе нужно дождаться завершения, например через CompletableFuture (пример ожидания есть в документации LangChain4j по AI Services).

Сервис с инструментами

Главная возможность AI Services: обычные методы Java превращаются в инструменты, которые модель может вызвать. Для этого достаточно аннотации @Tool.

import dev.langchain4j.agent.tool.P;
import dev.langchain4j.agent.tool.Tool;
import dev.langchain4j.memory.chat.MessageWindowChatMemory;
import dev.langchain4j.service.AiServices;

class OrderTools {
    @Tool("Возвращает статус заказа по его номеру")
    String orderStatus(@P("Номер заказа") String orderId) {
        return "Заказ " + orderId + ": передан в доставку";
    }
}

interface SupportBot {
    String chat(String message);

Библиотека сама строит описание функции из аннотации и типов параметров, вызывает метод, когда модель запросила инструмент, и возвращает результат модели. Это тот же цикл, что при ручной работе с API, только без ручной упаковки сообщений. Поддержка вызова инструментов зависит от конкретной модели, поэтому проверьте выбранную на своих сценариях.

Какую модель взять для Java

Универсального ответа нет, поэтому сравнивайте по цене, контексту и индексу силы (Intelligence Index, Artificial Analysis), а потом проверяйте на своём коде. Цены на 18 октября 2026, $ за 1M токенов:

Пример расчёта для gpt-6.1-sol: 1 000 запросов, в каждом 1 500 токенов входа и 400 токенов выхода.

• вход: 1 500 000 × 0.27 / 1 000 000 = $0.405;
• выход: 400 000 × 1.32 / 1 000 000 = $0.528;
• итого $0.933.

Для glm-5.3-flash: 1 500 000 × 0.04 / 1 000 000 = $0.06 плюс 400 000 × 0.04 / 1 000 000 = $0.016, всего $0.076. Актуальный список и цены отдаёт GET https://api.zukko.pro/v1/models.

Оговорка по кэшу: для Claude скидка за кэш видна шлюзу только в Anthropic-формате, а LangChain4j с этим модулем отправляет запросы в OpenAI-формате, так что весь вход идёт по цене входа. У GPT-моделей чтение кэша учитывается и в этом формате.

Частые вопросы

Нужен ли суффикс /v1 в baseUrl?

Да. LangChain4j-модуль OpenAI относится к OpenAI-совместимым клиентам, поэтому используйте https://api.zukko.pro/v1. Без /v1 путь будет собран неверно и вы получите 404.

Можно ли вызвать Claude, а не только GPT?

Да, имя claude-sonnet-5-5 передаётся в modelName так же, как любое другое. Шлюз принимает любую модель из каталога в любом формате.

Как узнать, что ключ ограничен по моделям?

Ответ 403 с кодом model_not_allowed_for_key означает, что в настройках ключа список разрешённых моделей не содержит вашу. Измените список в кабинете или используйте другую модель. Неизвестное имя даст 404 model_not_found.

Работает ли это из России?

Пополнить баланс из России можно по СБП, картой MasterCard или криптой. Код приложения не меняется.

Чтобы начать, создайте ключ в кабинете↗, укажите его в ZUKKO_API_KEY и запустите пример с простым чатом.