Langchain

작성되는 모든 내용은, AI 입문인 사람이, 여러 레퍼런스와 자료, 공식 문서 등을 보고 나름대로 확인하여 작성됩니다.
따라서, 모든 내용은 비 공식적이며, 완벽한 예제가 아닐 수 있습니다.

LangChain 이란?

Langchain 은, 대규모 언어 모델을 활용한 애플리케이션 개발에 특화된 오픈소스 프레임워크 입니다.
Langchain을 통해서, 기존 언어 모델의 한계를 극복하고, AI 기술을 활용한 새로운 애플리케이션을 구축할 수 있는 중요한 도구 입니다.

LangChain(랭체인)을 사용하는 이유
LLM을 직접 사용하면 단순한 질문답변만 가능하지만, LangChain(랭체인)을 사용하면 복잡한 워크플로우를 구성할 수 있습니다. 이를테면 “문서 읽기 → 요약 → 질문에 답변 →결과 저장”과 같은 과정을 자동화하거나, 여러 데이터 소스를 연결해 종합적인 분석을 수행할 수 있죠. 또한 대화 기록 관리, 외부 API연동, 에러 처리 등 실제 서비스에 필요한 기능들을 쉽게 구현할 수 있어 개발 시간을 크게 단축시켜 줍니다.

안타깝게도, LangChain 프레임워크는 기본적으로 파이썬 기반으로 작성되어 있습니다.
하지만, 이를 위해 Java 를 위한 LangChain4J 라는 라이브러리가 존재합니다.
이를 활용하여 Ollama 와 같이 사용하는 방법을 학습해보도록 하겠습니다.

Ollama 설치

Ollama 는, 로컬 환경에서 GPT, Deepseek, gemma 등 대규모 언어 모델을 실행시킬 수 있는 도구 입니다.
클라우드 API를 사용하지 않고도 PC에서 직접 모델을 구동할 수 있어, 비용 없이, 인터넷 연결 없이, 개인 데이터가 외부로 나가지 않는 환경에서 AI를 활용할 수 있습니다.

설치하기

올라마 홈페이지 에 접속하여 운영체제에 맞는 Ollama 를 설치해줍니다.
설치가 완료되면, 터미널에서 ollama를 입력하여 재대로 설치 되었는지 확인합니다.

$ ollama
Usage:
  ollama [flags]
  ollama [command]

Available Commands:
  serve       Start ollama
  create      Create a model
  show        Show information for a model
  run         Run a model
  stop        Stop a running model
  pull        Pull a model from a registry
  push        Push a model to a registry
  signin      Sign in to ollama.com
  signout     Sign out from ollama.com
  list        List models
  ps          List running models
  cp          Copy a model
  rm          Remove a model
  help        Help about any command

Flags:
  -h, --help      help for ollama
  -v, --version   Show version information

Use "ollama [command] --help" for more information about a command.

필요한 언어 모델 다운로드 받기

올라마는 언어 모델을 로컬환경에서 실행시켜주는 도구 입니다.
따라서 실행 하고 싶은 모델을 다운로드 받아줍니다.
올라마_검색페이지 에 접속하면 다양한 model 을 확인할 수 있습니다.

20b? 120b? 1.5b? b가 뭐지?
b는 billion 으로, 모델이 가진 파라미터의 수를 나타냅니다.
이 파라미터는 LLM 의 뉴런 연결 가중치를 의미합니다.
모델은 수많은 파라미터를 학습하면서 언어 패턴, 문맥, 사실 등을 내재화 하여 사용합니다.
즉, B숫자가 클 수록, 모델의 기억력과 추론 능력은 높아지고, 그만큼 필요한 VRAM/메모리/연산량 도 많아지게 됩니다.

참고로, GPT-5 는 635B 정도로 추론하고 있습니다.

gpt-oss:20b의 모델을 사용하도록 하겠습니다.

해당 20b 짜리의 run 명령어는 ollama run gpt-oss:20b 입니다.
모델을 다운로드 받기 위해서는, run 대신 pull 로 진행하시면 됩니다.

$ ollama pull gpt-oss:20b
pulling manifest
pulling e7b273f96360: 100% ▕██████████████████▏  13 GB
pulling fa6710a93d78: 100% ▕██████████████████▏ 7.2 KB
pulling f60356777647: 100% ▕██████████████████▏  11 KB
pulling d8ba2f9a17b3: 100% ▕██████████████████▏   18 B
pulling 776beb3adb23: 100% ▕██████████████████▏  489 B
verifying sha256 digest
writing manifest
success

다운로드 후 에는, ollama list 를 통해 현재 보유중인 모델을 모두 확인해 볼 수 있습니다.

$ ollama list
NAME           ID              SIZE      MODIFIED
gpt-oss:20b    17052f91a42e    13 GB     32 seconds ago
llama3.1:8b    46e0c10c039e    4.9 GB    6 hours ago

ollama 에 모델 실행해보기

ollama 를 다운로드 받으셨다면 다음과 같이 채팅을 칠 수 있는 프로그램이 실행되었을 것 입니다.

가볍게 1+1이 무엇인지 물어보겟습니다.

다음과 같이 GPT 처럼 답변을 해주는 모습을 보여줍니다.
- ~~사실 GPT 가 맞기는 합니다. 성능이 조금 많이 떨어지기는 하지만.~~
이제 스프링 프로젝트를 하나 띄워서 실행시켜 보겠습니다.

스프링 + Langchain4J

기본 프로젝트 셋팅은 제외하겠습니다.
Langchain4J 에서 제공하는 Ollama 를 사용한 예제는 다음 공식문서, Github 를 참고하시기 바랍니다.

의존성 추가

Maven Repository 에서 Langchain4J 를 검색하고 두가지 의존성을 build.gradle에 추가하겠습니다.

...
dependencies {
    ....
    implementation("dev.langchain4j:langchain4j:1.7.1")
    implementation("dev.langchain4j:langchain4j-ollama:1.7.1")
}

langchain4j는 코어 프레임 워크이고, langchain4j-ollama는 Ollama 모델에 접속하는 어뎁터 입니다.
- 저희는 Ollama 를 사용해서 모델을 기동시키고 있기 때문에 의존성이 2개 필요합니다.

Service 작성해보기

컨트롤러 코드는 제외하겠습니다.
추후, Stream 으로 Response 를 다룰때 같이 작성하겠습니다.

다음과 같이 OllamaChatModel 을 만들어서 여러가지 옵션을 통해 추가할 수 있습니다.

@Slf4j
@Service
@RequiredArgsConstructor
public class AiService {

	public String answerToAi(String question) {
		ChatModel model = OllamaChatModel.builder()
			.baseUrl("http://localhost:11434")
			.modelName("gpt-oss:20b")
			.temperature(0.0)
			.build();

		return model.chat(question);
	}
}

다음 answerToAi 메서드는, 입력받은 question 을 gpt-oss:20b 모델을 통해서 실행합니다.
다양한 파라미터는 공식문서_파라미터 부분 을 통해 확인이 가능합니다.

중요한 몇가지 공유!
temperature : LLM 의 성격을 경정하는 부분
낮은 값 (0.2 등) : 모델이 가장 확률 높은 예측 가능한 단어만 선택. (요약, 정보추출 등에 적합)
높은 값 (1.0 등) : 모델이 덜 예상되는 단어도 과감하게 선택하며, 훨씬 창의적인 결과를 냄. (브레인스토밍, 소설 작성 등)

topK : 다음 단어를 예측할 때, 가장 확률이 높은 K개의 후보 중에서만 고르도록 제한합니다.

topP : topK보다 더 동적인 방식입니다. 확률 순으로 단어를 더해가며, 누적 확률이 P가 될 때까지만 후보로 삼습니다.

이제 해당 Serivce 를 Controller 에 연결해서 요청해서 확인해보면 다음과 같은 결과를 얻을 수 있습니다.

문제점(?)

현재 "서울의 수도" 와 같은 직관적인 정답이 있는 문제는 정확하게 잘 해결해 주었습니다.
만약, 조금 더 복잡한 내용들은 잘 처리할 수 있을까요?
- 자바의 객체 지향적 설계에 대해서 한번 물어보도록 하겠습니다.

꽤 잘 찾아 줍니다.
그런데, 이상한 부분에서 재대로 된 답변이 오지 않습니다.

1+1은 3이라고 하네요...(?)

@Slf4j
@Service
@RequiredArgsConstructor
public class AiService {

	public String answerToAi(String question) {
		ChatModel model = OllamaChatModel.builder()
			.baseUrl("http://localhost:11434")
			.modelName("gpt-oss:20b")
			.temperature(0.0)
			.build();

		List<ChatMessage> chatMessageList = List.of(
			SystemMessage.from(
				"""
					You are a professional mathematician and calculator.
					When you receive an input, treat it as a mathematical expression and compute its value.
					Respond **only** with the numeric result, without explanations or text.
					Show decimal numbers up to two decimal places, rounding from the third digit.
					Examples:
					Input: 1+1 → Output: 2
					Input: 2.345+1.111 → Output: 3.46
					"""
			),
			UserMessage.from(question)
		);

		ChatResponse response = model.chat(chatMessageList);
		return response.aiMessage().text();
	}
}

명확하게 프롬프트로 계산역할을 하도록 구성하고, 다음과 같이 진행하니 정확하게 맞아 떨어졌습니다.
즉, 다음과 같이 명확한 프롬프트를 설정해두는 것이 좋습니다.

GPT 같은 경우, 저러한 페르소나를 지정하지 않아도 1+1 등의 가벼운 문제는 잘 해결됩니다.
그만큼, 사용하기 편할정도로 잘 튜닝된 LLM 모델임을 확인할 수 있습니다.

Streaming 으로 변환하기

보통 이런 응답은 기본적인 데이터베이스를 활용한 조회 응답과 달리 매우 시간이 오래 걸립니다.
따라서 이런 경우 Streaming 으로 처리하여, 사용성을 최대한 보장해줘야 한다.
현재 위의 "자바의 객체 지향" 에 대한 응답을 생성하는데 약 30초가 걸렸습니다.
아무리 훌륭한 응답이라도, 30초가 걸린다면 사용성이 굉장히 나쁘게 느껴질 수 있습니다.
실제, Chat GPT 나 Claud 등은, Streaming 하게 응답을 보내주는 것을 볼 수 있습니다.

Streaming 으로 변환

공식문서 를 참고해서 작성하였습니다.

공식 문서에서는 ResponseEntity 에는 담아서 보내지 않아, 맞춰서 작성하였습니다.
대한민국의 수도에 대해서

Controller

    ....
    @GetMapping(value = "/stream")
	public ResponseEntity<StreamingResponseBody> streamCapacityAndFood(
		@RequestParam(value = "question") String question
	) {
		StreamingResponseBody body = aiService.streamAnswerTest(question);
		return ResponseEntity.ok()
			.header(HttpHeaders.CONTENT_TYPE, "text/plain; charset=UTF-8")
			.body(body);
	}
    ....

Service

    ....
    public StreamingResponseBody streamAnswerTest(String question) {
		OllamaStreamingChatModel model = OllamaStreamingChatModel.builder()
			.baseUrl("http://localhost:11434")
			.modelName("gpt-oss:20b")
			.temperature(0.8)
			.logRequests(true)
			.logResponses(true)
			.build();

		List<ChatMessage> messages = List.of(
			SystemMessage.from("""
				너는 나라의 이름을 전달 받을 꺼야..
				응답은 다음을 따라서 응답해:
				1) 나라의 수도를 응답해줘.
				2) 그 나라의 5가지 유명한 음식을 소개해줘
				"""),
			UserMessage.from(question)
		);

		log.info(">>> [1] StreamingResponseBody lambda has been entered. Waiting for model response...");

		return outputStream -> {
			try (outputStream) {
				final CompletableFuture<Void> future = new CompletableFuture<>();
				var request = ChatRequest.builder().messages(messages).build();

				CustomStreamingResponseHandler handler = new CustomStreamingResponseHandler(outputStream, future);
				model.chat(request, handler);

				future.join();
			}
		};
	}
    ....

CustomStreamingResponseHandler

package com.baekgwa.springlangchain4j;

import java.io.IOException;
import java.io.OutputStream;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.CompletableFuture;

import dev.langchain4j.model.chat.response.ChatResponse;
import dev.langchain4j.model.chat.response.StreamingChatResponseHandler;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;

/**
 * PackageName : com.baekgwa.springlangchain4j
 * FileName    : CustomStreamingResponseHandler
 * Author      : Baekgwa
 * Date        : 2025-10-20
 * Description : 
 * =====================================================================================================================
 * DATE          AUTHOR               NOTE
 * ---------------------------------------------------------------------------------------------------------------------
 * 2025-10-20     Baekgwa               Initial creation
 */
@Slf4j
@RequiredArgsConstructor
public class CustomStreamingResponseHandler implements StreamingChatResponseHandler {

	private final OutputStream outputStream;
	private final CompletableFuture<Void> future;

	@Override
	public void onPartialResponse(String partial) {
		try {
			log.debug("Received partial response: {}", partial.replaceAll("\n", "\\\\n"));
			outputStream.write(partial.getBytes(StandardCharsets.UTF_8));
			outputStream.flush();
		} catch (IOException e) {
			future.completeExceptionally(e);
			throw new RuntimeException("Error writing partial response to stream", e);
		}
	}

	@Override
	public void onCompleteResponse(ChatResponse fullResponse) {
		log.info("Stream completed.");
		try {
			outputStream.flush();
		} catch (IOException ignored) {
		}
		future.complete(null);
	}

	@Override
	public void onError(Throwable error) {
		log.error("Error during streaming response", error);
		try {
			String errorMessage = "\n\n[ERROR] " + error.getMessage();
			outputStream.write(errorMessage.getBytes(StandardCharsets.UTF_8));
			outputStream.flush();
		} catch (IOException ignored) {
		}
		future.completeExceptionally(error);
	}
}

후기

AI 관련된 작업은 API 로 활용해서 사용한 경험밖에 없는데, 이번에 Ollama 와 Langchain 을 찍먹하며, 조금씩 알아 가볼 수 있을 것 같다.
추후, 해당 블로그에 RAG 를 추가해볼 생각인데, 재밌을 것 같다.

[LangChain] Ollama와 Langchain4J 를 사용하여 자바로 AI 모델 기동하기

스택 시리즈LLM & RAG with Langchain4J