천천히 올바르게

멱등한 HTTP 를 Idempotency-Key 를 통해 구현해보자

huisam — Sun, 12 Apr 2026 21:07:04 +0900

들어가며

대규모의 시스템을 설계하면, 서로 다른 백엔드 시스템과의 통신이 많아지고 복잡해지는데요.

통신이 많아질 수록 네트워크에 오류가 발생할 확률이 조금씩 늘어나게 됩니다.

네트워크 오류는 일시적인 순단이거나 connection timeout 이 발생하는 클라이언트 일시적인 오류거나 패킷 손실 등 다양한 원인일 수 있습니다.

이러한 원인을 매번 파헤치는 것은 시간적 소요가 많이 들 뿐더러, 원인을 찾아낸더라 해도 재발 방지책을 세우기도 쉽지 않습니다.

왜냐하면 단순 retry 하는 것으로 끝나는 경우들이 많기 때문입니다.

그래서 Idempotent HTTP 를 설계하려는 노력들을 많이 시작하게 되었는데요. 한번 시작해보겠습니다

용어정리

우선 앞으로 설명하게 될 용어에 대해 간단하게 소개해보겠습니다.

크게 멱등성과 회복탄력성에 대해 설명하고자 하는데요

멱등성(Idempotency): 수학이나 전산학의 한 성질로, 연산을 여러번 적용하더라도 결과가 달라지지 않는 성질. ( ( ))= ( )
회복탄력성(Resilience): 시스템이 외부 충격이나 장애 상황에서도 정상적인 기능을 유지하거나 빠르게 복구할 수 있는 능력

Idempotency

멱등성이 없는 HTTP API 는클라이언트가 요청을 보냈지만 요청시간이 초과되거나 불안정한 커넥션을 맞이한 경우, 클라이언트는 리소스의 상태에 불확실한 상태에 놓입니다.

리소스가 생성되었는지, 업데이트 되었는지, 또는 서버가 요청을 처리를 완료했는지 알 수가 없습니다.

더 나아가, 클라이언트는 요청을 안전하게 재시도할 수 있는지 조차 판단할 수 없습니다.

이것을 그림으로 설명하면 위와 같습니다.

따라서 리소스를 생성, 수정, 삭제하는 행위를 하는 API 에는 멱등성(Idempotency)을 제공하여 언제든 재시도(retry) 할 수 있는 기반을 제공하고 시스템의 회복탄력성을 높이는 것이 매우매우 중요합니다.

그러면 어떻게 설계해야 할까요?

Architecture

다양한 설계방안들이 있지만, IETF 의 draft 로 올려놓은 설계안을 위주로 설계해보았습니다

https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-01.html

The Idempotency-Key HTTP Header Field

The following core rules are included by reference, as defined in Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed),

www.ietf.org

위 설계안에서는 Idempotency-Key HTTP header 를 optional 하게 제공하여,

가장 핵심이 되는 것은 아래와 같은 case 를 구분하는 것입니다

(첫 요청) HTTP 요청을 정상 처리했으면, HTTP 200 을 내려주고, 요청과 응답을 repository 를 통해 저장한다(가급적 TTL 을 거는 것이 운영상 편리합니다)
(두번째 요청) 동일한 Idempotency-Key 와 동일한 request body 로 요청이 오고 처리가 된게 server 쪽에 저장되어 있는 경우, 저장된 응답을 내려줍니다.
(중복 요청) 동일한 Idempotency-Key 헤더 짧은 시간내로 중복 요청이 온 경우(=처리 진행중인 경우), HTTP 409 를 내려주어 이미 처리중임을 client 에게 알립니다
(오류 요청) 같은 Idempotency-Key 인데, 다른 request body 로 요청이 온 경우, HTTP 422 를 내려주어 처리할 수 없음을 client 에게 알립니다
(오류 요청) Idempotency-Key 헤더의 길이 제약에 실패한 경우, HTTP 400 을 내려주어 요청이 잘못됨을 알립니다

1번은 흔한 성공 case 라 설명을 생략하겠습니다. 중요한 것은 2번 case 에 대한 기능을 client 에게 제공하여 쉽게 재시도할 수 있도록 가능성을 열어두는 것이죠

3번 case 는 client 가 재시도하였으나, 너무 짧은 주기로 재시도한 경우 backoff 시간을 좀 더 길게 가져가라는 의미를 내려주는 것입니다.

4번 case 는 client 측 구현 실수 혹은 위변조 방지를 위한 기능입니다

API 스펙상 예시

이것을 코드로 구현하면 아래와 같습니다.

package com.huisam.springidempotency.idempotency.filter

import com.huisam.springidempotency.idempotency.domain.IdempotencyHeader
import com.huisam.springidempotency.idempotency.domain.IdempotentHttp
import com.huisam.springidempotency.idempotency.domain.IdempotentHttpRequest
import com.huisam.springidempotency.idempotency.domain.IdempotentHttpResponse
import com.huisam.springidempotency.idempotency.repository.IdempotentHttpRepository
import jakarta.servlet.FilterChain
import jakarta.servlet.http.HttpServletRequest
import jakarta.servlet.http.HttpServletResponse
import org.slf4j.LoggerFactory
import org.springframework.boot.servlet.filter.OrderedFilter
import org.springframework.core.Ordered
import org.springframework.http.HttpStatus
import org.springframework.http.MediaType
import org.springframework.stereotype.Component
import org.springframework.web.filter.OncePerRequestFilter
import org.springframework.web.util.ContentCachingResponseWrapper

/**
 * Filter for managing idempotent HTTP requests/responses based on [IdempotencyHeader.IDEMPOTENCY_KEY] value
 *
 * Since IdempotentHttpId is generated based on HTTP method and path, clients need to request a unique [IdempotencyHeader.IDEMPOTENCY_KEY] for each API.
 *
 * @property order The filter execution order defaults to the order before entering [org.springframework.web.servlet.DispatcherServlet]
 */
@Component
class IdempotentHttpWebMvcFilter(
    private val idempotentHttpWebMvcRegistry: IdempotentHttpWebMvcRegistry,
    private val idempotentHttpRepository: IdempotentHttpRepository,
    private val order: Int = Ordered.LOWEST_PRECEDENCE - 1,
) : OncePerRequestFilter(), OrderedFilter {
    private val log = LoggerFactory.getLogger(this::class.java)

    override fun doFilterInternal(
        request: HttpServletRequest,
        response: HttpServletResponse,
        filterChain: FilterChain
    ) {
        val httpMethod = request.method
        val httpPath = request.requestURI
        val idempotencyKey = request.getHeader(IdempotencyHeader.IDEMPOTENCY_KEY)

        when {
            idempotencyKey == null -> filterChain.doFilter(request, response)

            idempotencyKey.isBlank() || idempotencyKey.length > 100 -> {
                response.status = HttpStatus.BAD_REQUEST.value()
                response.contentType = MediaType.TEXT_PLAIN_VALUE
                response.writer.write("Idempotency-Key must be 1 to 100 characters and not blank.")
            }

            idempotentHttpWebMvcRegistry.notRegistered(httpMethod, httpPath) -> {
                response.status = HttpStatus.BAD_REQUEST.value()
                response.contentType = MediaType.TEXT_PLAIN_VALUE
                response.writer.write("Idempotency-Key is not allowed on $httpMethod $httpPath")
            }

            else -> processIdempotentHttp(
                idempotentHttpId = createIdempotentHttpId(httpMethod, httpPath, idempotencyKey),
                request = request,
                response = response,
                filterChain = filterChain,
            )
        }
    }

    private fun createIdempotentHttpId(httpMethod: String, httpPath: String, idempotencyKey: String): String {
        return "$httpMethod::$httpPath::$idempotencyKey"
    }

    private fun processIdempotentHttp(
        idempotentHttpId: String,
        request: HttpServletRequest,
        response: HttpServletResponse,
        filterChain: FilterChain,
    ) {
        val cachingRequest = ContentCachingRequestWrapper(request)
        val idempotentHttp = IdempotentHttp(
            idempotentHttpId = idempotentHttpId,
            request = IdempotentHttpRequest(
                method = cachingRequest.method,
                path = cachingRequest.requestURI,
                contentType = cachingRequest.contentType,
                body = cachingRequest.requestBody,
            ),
            response = null,
        )
        val existedIdempotentHttp = idempotentHttpRepository.findByIdOrNull(idempotentHttp.idempotentHttpId)

        when {
            existedIdempotentHttp == null -> {
                doIdempotentHttpFilter(idempotentHttp, cachingRequest, response, filterChain)
            }

            existedIdempotentHttp.isDifferentRequest(idempotentHttp.request) -> {
                response.status = HttpStatus.UNPROCESSABLE_ENTITY.value()
                response.contentType = MediaType.TEXT_PLAIN_VALUE
                response.writer.write("Request does not equal with original request.")
            }

            existedIdempotentHttp.response == null -> {
                response.status = HttpStatus.CONFLICT.value()
                response.contentType = MediaType.TEXT_PLAIN_VALUE
                response.writer.write("Request is still processing. Please try again later.")
                log.warn("Idempotent request is still processing. Please check the server latency or client retry interval --> $idempotentHttpId")
            }

            else -> {
                response.status = existedIdempotentHttp.response.status
                response.contentType = existedIdempotentHttp.response.contentType
                response.writer.write(existedIdempotentHttp.response.body)
            }
        }
    }

    private fun doIdempotentHttpFilter(
        idempotentHttp: IdempotentHttp,
        cachingRequest: ContentCachingRequestWrapper,
        response: HttpServletResponse,
        filterChain: FilterChain
    ) {
        recordRequest(idempotentHttp)

        val cachingResponse = ContentCachingResponseWrapper(response)
        try {
            filterChain.doFilter(cachingRequest, cachingResponse)

            recordResponse(idempotentHttp, cachingResponse)
            log.info("Success idempotent request --> ${idempotentHttp.idempotentHttpId}")
        } finally {
            // Respond cached response to client buffer
            cachingResponse.copyBodyToResponse()
        }
    }

    private fun recordRequest(idempotentHttp: IdempotentHttp) {
        idempotentHttpRepository.save(idempotentHttp)
    }

    /**
     * If saving the response fails, the request was processed but the response was not saved.
     * In this case, since reliable idempotent HTTP cannot be guaranteed, delete the HTTP record itself to avoid responding with a conflict(409) status.
     */
    private fun recordResponse(
        idempotentHttp: IdempotentHttp,
        cachingResponse: ContentCachingResponseWrapper
    ) {
        runCatching {
            val idempotentHttpResponse = IdempotentHttpResponse(
                status = cachingResponse.status,
                contentType = cachingResponse.contentType,
                body = String(cachingResponse.contentAsByteArray),
            )
            idempotentHttpRepository.save(idempotentHttp.recordResponse(idempotentHttpResponse))
        }.onFailure {
            log.error("Error while recording response for idempotencyHttp: ${idempotentHttp.idempotentHttpId}", it)
            deleteIdempotentHttp(idempotentHttp.idempotentHttpId)
        }
    }

    private fun deleteIdempotentHttp(idempotentHttpId: String) {
        runCatching {
            idempotentHttpRepository.deleteById(idempotentHttpId)
        }.onFailure {
            log.error("Error while deleting idempotentHttp: $idempotentHttpId", it)
        }
    }

    override fun getOrder(): Int = order
}

여기서 repository 를 선택하는 주요 요소는 TTL 이 지원되는 repository 를 고르는 것이 좋은데요.

Redis 를 이용하면 key value 형태의 command 요청으로 동시성 제어도 가능하고, 빠른 속도로 구현할 수 있게 되어 저는 redis 저장소를 추천드리는 편입니다.

관련된 소스코드는 아래 저장소에 업로드 해두었습니다 ㅎㅎ

https://github.com/huisam/spring-idempotency

GitHub - huisam/spring-idempotency: HTTP Idempotency based on Spring

HTTP Idempotency based on Spring. Contribute to huisam/spring-idempotency development by creating an account on GitHub.

github.com

Client configuration

그러면 client 측에서는 어떻게 Idempotency-Key header 와 retry 전략을 설정하는 것이 좋을까요?

먼저 Idempotency-Key 헤더 입니다.

Idempotency-Key 는 API 요청마다 유니크한 key 로 정의하면 됩니다. UUID v4 를 사용할 것을 적극 권장합니다.
Http Status 409 를 응답받은 경우, 아직 서버에서 요청을 처리하고 있어 일정시간 후에 같은 Idempotency-Key 로 재시도가 가능합니다.
서버에서는 요청의 결과를 성공/실패 상관없이 모두 기록합니다. 이는 "클라이언트가 어떤 요청을 시도했고, 그 결과가 무엇이었는지" 에 대한 불확실성을 제거하는데 초점을 둡니다.
- 새로운 요청을 시도하고 싶다면, 새로운 Idempotency-Key 로 요청해야 합니다.

여기서 성공/실패 를 상관없이 기록한다는 것의 의미는.. 비즈니스적인 실패 상황도 기록하는 것을 의미합니다.

예를 들면, 결제 API 를 호출했는데, 카드 만료로 인해 실패한 경우, 해당 요청은 카드 만료로 실패했다고 응답한 것을 기록하는 것입니다.

Idempotency-Key 의 핵심은 요청에 대한 성공을 하나만 보장하기 위함이 아닌, 요청 자체의 성공/실패의 연산을 기록하는 것입니다.

재시도에 관한 정책은 아래와 같습니다.

재시도는 너무 많은 횟수를 지정하거나, 짧은 주기로 재시도한다면 서버에게 더 큰 악영향을 끼칠 수가 있습니다. 재시도 횟수를 제한하고, 지수적 backoff 전략을 고려할 것을 권장합니다.
권장사항
- maxAttempts: 3
- exponential backoff
  - initial delay: 2s
  - multiplier: 2

지수적 backoff 를 사용하는 이유는 서버의 부하를 막고, 처리중인 상황을 매번 안내받지 않도록 하는 것에 의의를 두고 있습니다.

이는 API 마다 처리시간이 다르므로, API 별로 안내할 것을 적극 권장합니다.

대부분의 경우에는 위 권장사항으로 처리가능하나, 간혹가다 latency 가 늘어지는 API 도 있기에, latency 가 긴 API 들만 initial delay 를 살짝 조정해주면 됩니다.

마치며

오늘은 이렇게 멱등성(Idempotency)과 Idempotency-Key HTTP header 를 통해 멱등한 API 를 제공하는 방법에 대해 알아보았네요

MSA 환경에서 회복탄력성 있는 시스템을 운영하기 위해서는 알아야될 필수 요소이니

이번 게시글을 통해 적용해보면 좋겠네요

AI agent 란 무엇이고 agent 에게 tool 을 주어보자(feat. OpenAi)

huisam — Sat, 21 Mar 2026 18:12:37 +0900

들어가며

저번 시간에 우리는 아주 기초적인 LLM API 를 호출하고 간단하게 tool 을 활용하는 방법에 대해 배워보았습니다.

혹시나 어떤 내용인지 궁금하시다면 아래 링크를 클릭해주세요~!

https://huisam.tistory.com/entry/llm-api

LLM API 를 이용하여 Text 와 Tool 을 제공해보자(feat. OpenAi)

들어가며안녕하세요~! 저번 시간에는 우리가 LLM 의 기본 동작과 돌아가는 원리에 대해 살펴보았는데요오늘은 조금 더 실무 관점에서 어떤식으로 Frontier Model 을 사용할 수 있는지 설명해보려고

huisam.tistory.com

그런데 매번 tool 관련된 복잡한 python code 를 작성하는 것은 보일러플레이트 코드를 양산하고,

tool 이 많아질수록 코드는 더 복잡해지게 되겠죠

이번 게시글에서는 위와 같은 불편함을 해결하기 위해, 등장한 AI agent 라이브러리를 간단하게 알아볼게요.

수많은 AI agent 라이브러리들이 있지만, OpenAI model 을 사용할 것이라 Open AI agents 를 기반으로 한번 설명드려보겠습니다~!

AI Agent

본격적으로 들어가기 전에, AI agent 는 뭘까요? 도대체 우리는 무엇을 AI agent 라고 부르고 있을까요?

AI agent 에 정의는 시대에 따라 바뀌어왔지만, 개인적으로는 아래와 같이 AI agent 라고 정의하고 있습니다.

To archieve a goal using tools in a loop
도구를 반복적으로 사용하여 목표를 달성한다

즉, 어떤 tool(도구) 들을 통해 주어진 goal(목표)를 달성하기 위해 수행하는 것을 AI agent 라고 부릅니다.

AI agent

단순 LLM(Large Language Model) 의 token 예측기에서 어떻게 능동적으로 자율적으로 판단하여 목표를 이루는 것일까요?

이는 LLM 의 next token 을 예측하는 방식은 그대로 사용하되, tool 을 주고받는 interface 를 통해 모든 것이 가능해졌습니다.

tool 의 description 을 적어줌으로써, 어떤 상황에서 어떤 tool 을 사용하여 어떤 결과를 얻을 것인지 예측하여 실행하게 되는 것이죠.

또한, 한번의 tool 을 사용하는 것이 아닌 여러개의 tool 이 있다면, 상황에 따라 반복적으로 tool 을 호출하여 목표를 달성하게 되는 것입니다.

OpenAI agents

OpenAI agents 는 OpenAI 에서 제공하는 agent 라이브러리입니다.

다양한 기능(Handoff, Guardrail, Agent as tool, Trace ..)들이 제공되지만, 앞으로 하나씩 상황에 맞게 소개해드릴 예정입니다 ㅎㅎ

오늘은 아주 기초적인 Agent 를 예시 코드와 함께 설명드릴게요

uv add openai-agents

openai-agents 라이브러리 의존성을 위 명령어를 통해 가져옵니다!

먼저, 이전에 Agent 라이브러리 없이 작성된 코드를 기억하시나요?

import os

from dotenv import load_dotenv
from openai import OpenAI
from openai.types import Reasoning

load_dotenv()
open_ai = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

tools = [
    {
        "type": "function",
        "name": "get_weather",
        "description": "Get current temperature for a given location.",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and country e.g. Bogotá, Colombia",
                }
            },
            "required": ["location"],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

response = open_ai.responses.create(
    model="gpt-5-nano",
    input="What is the weather like in Paris today?",
    tools=tools,
    reasoning=Reasoning(effort="minimal")
)
print(response.output[1].to_json())

def get_weather(location):
    # 실제 날씨 API 호출 (예시에서는 하드코딩)
    return f"The current temperature in {location} is 15°C with clear skies."

# Tool 호출 구현 (response API)
for item in response.output:
    if item.type == "function_call":
        if item.name == "get_weather":
            location = item.arguments
            # 실제 날씨 API 호출 (예시에서는 하드코딩)
            weather_info = get_weather(location)
            # 모델에 도구 호출 결과 제공
            follow_up_response = open_ai.responses.create(
                model="gpt-5-nano",
                input=f"The weather information for {location} is: {weather_info}",
                reasoning=Reasoning(effort="minimal")
            )
            print(follow_up_response.output_text)

위와 같이 tool 의 json schema 를 정의하고, tool 호출시에 python function 을 호출해주고, LLM 에게 전달하는 과정을 거쳤는데요.

OpenAI agents 를 사용하면 아래와 같이 간소화 됩니다

from agents import Agent, ModelSettings, Runner, function_tool
from dotenv import load_dotenv
from openai.types import Reasoning

load_dotenv()


@function_tool(docstring_style="google")
def get_weather(location: str) -> str:
    """Get current temperature for a given location.

    Args:
        location: City and country e.g. Bogotá, Colombia

    Returns:
        A concise weather sentence that includes Celsius temperature and a condition summary.
    """
    return f"The current temperature in {location} is 15°C with clear skies."


weather_search_agent = Agent(
    name="weather_search_agent",
    instructions="""
    You are a weather assistant. For weather-related requests, 
    call the `get_weather` tool to get weather information and respond with a concise summary.
    """,
    model="gpt-5.4-nano",
    model_settings=ModelSettings(reasoning=Reasoning(effort="none")),
    tools=[get_weather],
)

어때요? 정말 간소화 되었죠?

OpenAI Agents 에 탑재되어 있는 function_tool decorator 를 사용해주기만 하면, Agent 에게 정의할 tool 을 지정할 수 있게 됩니다.

해당 decorator 를 통해 json schema 를 만들게 되고, LLM 은 이를 인지하여 tool 을 언제 사용해야 겠다 를 판단할 수 있게 되죠

그럼 정말 잘 작동하는지 검증해보러 가볼까요?

def main() -> None:
    query = "What is the weather in Seoul today?"
    result = Runner.run_sync(weather_search_agent, input=query)
    print(json.dumps(get_weather.params_json_schema, indent=2, ensure_ascii=False))
    print(result.final_output)


if __name__ == "__main__":
    main()

위와 같이 실행할 수 있는 코드와, 우리가 만든 tool 의 schema 를 확인할 수 있는 간단한 실행 코드를 작성해봅니다

그렇게 되면 json schema 는 아래와 같이 나옵니다

{
  "properties": {
    "location": {
      "description": "City and country e.g. Bogotá, Colombia",
      "title": "Location",
      "type": "string"
    }
  },
  "required": [
    "location"
  ],
  "title": "get_weather_args",
  "type": "object",
  "additionalProperties": false
}

Agents 라이브러리를 사용할 때와 거의 유사한 json 이 나오게 되죠?

이러한 보일러플레이트 코드를 쉽게 생성하기 위해 Agent 라이브러리들을 사용하는 것에 많은 이점에 있습니다.(부가적인 기능들도 포함해서)

Agent 호출은 어떻게 되었는지 OpenAI Platform 에서 쉽게 확인해볼 수 있습니다.

OpenAI platform 은 AI Engineer 들을 위한 페이지이고, Observability, Evaluation, Fine tuning, Billing 등 다양한 기능들이 있어요

https://platform.openai.com/

OpenAI Platform

Explore developer resources, tutorials, API docs, and dynamic examples to get the most out of OpenAI's platform.

platform.openai.com

다만, 과금 요금제를 사용하고 있는 저만 확인할 수 있으니 어떤 내용인지 캡처로 공유해드릴게요 ㅎㅎ

trace

agent 에 하나의 trace 로 묶인 것을 볼 수 있죠. 총 2번의 LLM API call 이 있었고, 1번의 tool 사용이 있었네요

순서대로 하나씩 설명드리겠습니다.

1st LLM call

첫번째 llm call 은 사용자의 input 과 instructions 를 통해, output 을 도출해냈는데요.

output 이 get_weather 호출과 parameter(location) 을 어떻게 지정해서 전달할 것인지를 나타냈습니다.

1st tool call

다음은 tool 호출인데요. local 에서 python code 를 실행하였고, 인자에 대한 결과값을 보여주고 있습니다.

2nd LLM call

마지막으로 2번째 LLM API 호출인데요. tool 의 결과값을 LLM 에게 전달하여, 최종 output 을 이끌어내는 모습입니다

즉, 이렇게 해서 우리의 weather_search_agent 는 날씨를 가져오는 tool 을 통해 최종적인 목표(오늘 서울 날씨 뭐야?) 를 달성하게 되었네요

위에서는 간단한 예시로 설명드렸지만, 다양한 tool 을 제공하면 더 복잡하고 어려운 상황에서 많은 tool 호출이 이루어지고, 최종적인 목표를 달성하기 위한 과정(journey)를 거치게 되는 것입니다

정리하며

여러분들도 수작업으로 하고 있는 과정들을 개인화된 Agent 를 만들어 어떤 목표를 이루게 할 것인지 정의해보는 것도 좋겠네요.

Agent 에게 어떤 작업을 위임할 것이고, 어떤 Agent 라이브러리를 활용하여 목표를 달성하게 할 것인지 직접 구현해보고 실험해보면 좋겠습니다~!

다음 시간에는 조금 더 심화된 Agent pattern 을 통해서 어떤 상황에 어떤 pattern 를 사용하는게 적합할지에 대해 알아볼게요^^

참고

OpenAI Agents SDK

LLM API 를 이용하여 Text 와 Tool 을 제공해보자(feat. OpenAi)

huisam — Sun, 15 Feb 2026 16:58:42 +0900

들어가며

안녕하세요~! 저번 시간에는 우리가 LLM 의 기본 동작과 돌아가는 원리에 대해 살펴보았는데요

오늘은 조금 더 실무 관점에서 어떤식으로 Frontier Model 을 사용할 수 있는지 설명해보려고 합니다.

먼저 Frontier Model 이라는 용어에 대해 이해가 어려우실텐데요. 우리가 흔히 사용하는 LLM 은 크게 2가지 분류로 분류됩니다

Frontier Model: 많은 양의 데이터로 학습되었고, 파라미터 양이 엄청나게 많아 대규모 Model 을 일컫음(ex. GPT, Claude, Gemini ...)
Open source Model: 적은 양의 데이터로 학습되었고, 파라미터 양이 적어 무료로 오픈소스로 사용할 수 있는 Model 을 일컫음(ex. llama, gemma, gpt-oss... )

우리가 Chat Interface 에서 경험했던, 예를 들면 chatgpt.com 에서 경험했던 LLM model 들은 모두 Frontier Model 을 지칭한다고 보시면 됩니다.

특정 LLM 을 학습시키고, 완성된 Model 을 제공한다는 것은 규모가 작은 기업 혹은 기술자가 부족한 기업에서는 자체적으로 LLM 을 운영할 수 없기에, LLM 을 전문적으로 다루는 기업에서 제공한 LLM 들을 사용하여 AI application 을 누구나 쉽게 만들 수 있게 되는 것이죠.

대신에 서버 비용이라는 것이 공짜는 없기에, Token 단위의 사용량을 토대로 요금을 납부하는 대가로 사용할 수 있게 됩니다.

이번 게시글에서는 OpenAI 라는 AI platform 을 사용하여 실습을 진행하게 되므로, 이점 감안하여 실습을 진행해보세요.

OpenAI 에서는 5달러 라는 기본 요금만 납부하기만 하면 간단한 실습예제에서는 큰 Token 을 소비하지 않으니 크게 걱정 않으셔도 됩니다.

Tech stack 은 아래와 같이 진행합니다.

language: python 3.14 sdk 기반
project manager: uv 로 python project management

참고로 python application 의 최근 추세는 모두 uv 로 사용하는 추세로 넘어가고 있습니다.

uv 는 rust 로 작성되어 있어서 속도가 빠르고, virtual env 에 대한 관리 와 dependency 로드를 병렬로 하고 있어 매우 편리하고 빠르다고 볼 수 있습니다.

https://docs.astral.sh/uv/

An extremely fast Python package and project manager, written in Rust. Installing Trio's dependencies with a warm cache. A single tool to replace pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more. 10-100x faster than pip. Provides comprehens

docs.astral.sh

Text generation

가장 쉬운 것부터 시작해보려고 합니다. 특정 input 을 주었을 때 output 을 어떻게 만들 수 있을까요?

uv add opneai
uv add python-dotenv

먼저 프로젝트에 openai 라이브러리 종속성을 가져옵니다.

import os

from dotenv import load_dotenv
from openai import OpenAI
from openai.types import Reasoning

load_dotenv()
open_ai = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

# chat completion api
chat_response = open_ai.chat.completions.create(
    model="gpt-5-nano",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"},
    ],
    reasoning_effort="minimal"
)
print(chat_response.choices[0].message.content)

# response api
response = open_ai.responses.create(
    model="gpt-5-nano",
    instructions="You are a helpful assistant.",
    input="What is the capital of France?",
    reasoning=Reasoning(effort="minimal")
)
print(response.output_text)

그 후에 위와 같은 코드를 간단하게 작성해보았는데요. model 은 가성비 model 인 gpt-5-nano 를 기반으로 하였습니다.

그럼 위 코드를 가동하게 되면?

Paris 라는 결과물을 주는군요!

우리는 LLM 을 이용하여 프랑스의 수도를 알려주는 기능을 구현했습니다 ^-^

그런데 조금 더 세밀하게 들여다봐야겠죠? 먼저 크게 2가지 유형으로 작성하였는데요.

대부분의 경우 chat completion API 를 사용하는 것으로 생각하시면 됩니다.

Chat Completion API 는 OpenAI 가 처음으로 제공했던 API 양식이며, 다른 Frontier model provider 들도 OpenAI 에서 제공한 양식으로 맞추려는 움직임들도 있어 누구나 쉽게 Model 을 교체하여 application 을 운영하게 되었습니다.
그러자 OpenAI 는 오로지 자기 모델에 종속적인 API 를 제공하는 것으로 스탠스를 바꾸었죠. 이는 다른 Model 사용하지 말고, OpenAI model 사용에 종속적인 application 이 되라는 것을 의미합니다.

중요한 것은 데이터를 보낼 때, role 과 content 를 지정한 것을 볼 수 있습니다.

role 은 크게 3가지 유형이 있는데요.

system: 시스템에서 설정한 text
user: 사용자가 질의한 text
assistant: LLM 이 생성한 응답 text

이 3가지 데이터를 모두 고려하여, LLM 의 최종 응답이 생성된다고 보면 됩니다.

LLM 은 그 자체만으로 어떤 상태를 갖고 있지 않기 때문에, 대화형 interface 에서는 대화의 모든 이력을 데이터화 해서 전송하고, 최종적인 결과물을 얻게 되는 것이죠.

여기서 AHA 모먼트를 느끼면 좋겠네요 ^-^

사실 우리가 사용하는 모든 chat interface 를 통한 질의는 모든 대화 이력을 데이터화 하는 것이라는 것을요.

대화가 길어지면 길어질수록 LLM 이 생성하는 응답의 퀄리티가 이상해지는 현상을 볼 수도 있는데, 이는 너무 많은 Context 가 담겨있어 어떤 Text 를 생성해야될지 갈팡질팡 하는 단계라고 볼 수 있습니다.

많은 Context 가 담긴다는 것은 이전의 원리에서도 볼 수 있듯이, 수없이 많은 Vector 들이 나열되기에 서로 상충되는 Vector 데이터들이 생기거나 일관성이 없는 데이터가 생긴다면 LLM 의 output 퀄리티도 자연스럽게 떨어지게 되는것이죠

그래서 Frontier model 에서는 model 마다 허용가능한 Context window 를 안내하고 있습니다.

gpt-5 nano

저희가 사용한 gpt-5-nano 모델은 최대 40만개의 Context window 라고 하는군요.

내가 질의한 내용에 대해 결과물이 만족스럽지 못한다면, 지금 나의 대화는 얼만큼의 Context window 로 넘어갈지, 대화 이력동안의 일관성은 있는지 체크해보면 좋겠군요.

이러한 Context window 의 중요성은 추후에 AI agent application 을 제작할 때, Context Engineering 이라는 주제로도 이어지게 된답니다.

Tool

LLM 이 Agentic AI 로 갈 수 있었던 배경에는 이 Tool 이 있습니다. 먼저 예시와 함께 설명해볼게요

import os

from dotenv import load_dotenv
from openai import OpenAI
from openai.types import Reasoning

load_dotenv()
open_ai = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

tools = [
    {
        "type": "function",
        "name": "get_weather",
        "description": "Get current temperature for a given location.",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and country e.g. Bogotá, Colombia",
                }
            },
            "required": ["location"],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

response = open_ai.responses.create(
    model="gpt-5-nano",
    input="What is the weather like in Paris today?",
    tools=tools,
    reasoning=Reasoning(effort="minimal")
)
print(response.output[1].to_json())

def get_weather(location):
    # 실제 날씨 API 호출 (예시에서는 하드코딩)
    return f"The current temperature in {location} is 15°C with clear skies."

# Tool 호출 구현 (response API)
for item in response.output:
    if item.type == "function_call":
        if item.name == "get_weather":
            location = item.arguments
            # 실제 날씨 API 호출 (예시에서는 하드코딩)
            weather_info = get_weather(location)
            # 모델에 도구 호출 결과 제공
            follow_up_response = open_ai.responses.create(
                model="gpt-5-nano",
                input=f"The weather information for {location} is: {weather_info}",
                reasoning=Reasoning(effort="minimal")
            )
            print(follow_up_response.output_text)

지금은 직접적으로 Tool 을 호출하고 있기에 코드가 많이 어려운데요 ㅎㅎ..

나중에는 AI agent 라이브러리를 통해 이러한 보일러플레이트 같은 코드를 직접적으로 신경쓰지는 않을 것입니다.
다음 포스팅을 기대해주세요~!

어쨌든 위 코드를 조금 쉽게 큰 그림으로 설명드리면, 이 코드는 LLM API call 을 총 2번하게 되는 코드입니다.

첫번째 호출에 대한 결과 print 는 아래와 같이 출력되고

두번째 호출에 대한 결과 print 는 아래와 같이 출력됩니다.

LLM 에게 get_weather(날씨 조회) 라는 tool 을 제공하였더니, LLM 이 tool 을 이용한 결과값을 요청하는 것이 첫번째 print 문이라고 보면 됩니다. 어떤 함수와 어떤 인자로 전달할 것인지도 결정해서 json 형태로 알려주었죠.

두번째 print 는 사용자가 요청한 질의와 함수 결과값을 최종적으로 종합하여 최종 응답을 생성한 것이라고 이해하면 됩니다.

이를 그림으로 표현하면 아래와 같습니다.

Tool 은 쉽게 이야기해서, LLM 사용할 수 있는 도구를 의미합니다. 이는 개발자가 정의한 함수를 의미하며, 로컬에서 돌린 함수 결과를 LLM 에게 전달하는 것이죠

도구는 여러가지 형태로 사용될 수 있어요.

RAG retrieval: RAG 를 통한 질의
API call: API 호출
DB query: DB 질의

이 Tool 이 있기에 LLM 은 정말 무엇이든지 할 수 있게 되었습니다. 단순한 Text 예측기에서 LLM 이 직접 행동할 수 있는 기반을 갖게 되었죠.

그렇기에 모든 Model 의 Tool 표준을 정해주는 MCP(Model Context Protocol) 이 각광받게 되었습니다.

여기서도 AHA 모먼트를 느낄 수 있죠 ^-^

LLM 에게 어떤 tool 을 제공할 것인지에 따라 설계하고자하는 AI application 이 다양하게 개발될 수 있고, 어떤 일을 하게 될지 경계를 명확히 할 수 있다는 것을요.

그래서 Tool 을 정의하고, Tool 에 대한 설명을 어떻게 작성하느냐에 따라 결과물은 정말 완전히 달라질 수 있습니다.

정리하며

오늘은 크게 2가지 API 를 실전 예제와 함께 해보면서 정리해보았는데요.

Text generation 을 통해 Context window 의 중요성과 실제 데이터구조를 알아보았고,

Tool 을 통해 Tool 의 동작원리와 중요성에 대해 알아보았네요.

이제 AI Engineer 가 되기 위한 기초가 되었으니, 다음 게시글에서는 조금 심화된 과정의 Agent 로 찾아오도록 할게요!

참고문서

Developer QuickStart

LLM 의 구조와 원리에 대해 쉽게 알아보자 (feat. llama)

huisam — Sun, 11 Jan 2026 19:45:56 +0900

들어가며

안녕하세요~!

오늘은 요즘 핫한 LLM(Large Language Model)의 구조와 동작 방식에 대해 이해하기 쉽게 한번 정리해보려 합니다.

깊게 들어가면 들어갈수록 수학적인 공식과, 논문 레벨 단위로 설명을 해야 되는데, 그렇게 deep 한 level 은 다루진 않고

이해하기 쉽게 풀어가며 정리해보려고 합니다

Architecture

LLM 은 기본적으로 언어(Language)를 기반으로 다음에 나올 Token 을 예측하여 확률을 할당하는 모델입니다.

수십억개의 파라미터를 가진 신경망(Neural Network) 구조를 기반으로 하고 있습니다. 예전에는 통계(ex. Linear Regression)를 기반으로 한 모델들도 있었지만, 요즘은 신경망(Neural Network) 을 기반으로 하는 것이 보편적으로 자리를 잡게 되었습니다.

Neural Network 구조

신경망(Neural Network)은 각각의 layer들이 있고, 이 Layer는 주어진 입력(input)과 가중치(weight)를 기반으로 출력(output)을 이끌어내게 되는데요.

신경망(Neural Network)에서 주고받는 데이터는 숫자에 불과하며, 우리가 LLM에게 입력한 언어(Language)는 사실 내부 구조적으로 숫자로 변경되어 전달하게 됩니다.

물론, 이 과정속에서 이루어지는 다양한 수식과 원리를 통해 지나가게 되지만, 신경망(Neural Network)의 구조는 너무나 복잡하므로 이번 게시글에서는 이렇게 간략하게만 짚고 넘어가려고 합니다.

이제 본격적으로 LLM 의 상세 구조와 동작원리에 대해서 알고자 한다면, 기본적으로 어떤 아키텍처를 가지고 있는지 알아보아야 하는데요.

역시나 가장 쉬운 방법은 실제 LLM 모델을 예시로 설명하면서 차근차근 보는 것이 중요하겠네요!

Overview

우선은 우리는 Llama-3.2-1B 모델을 기반으로 한 아키텍쳐를 살펴보려고 합니다.

해당 모델은 opensource model 이며, hugging face에서 모델을 다운로드할 수 있습니다.

https://huggingface.co/meta-llama/Llama-3.2-1B

meta-llama/Llama-3.2-1B · Hugging Face

We’re on a journey to advance and democratize artificial intelligence through open source and open science.

huggingface.co

LlamaForCausalLM(
  (model): LlamaModel(
    (embed_tokens): Embedding(128256, 2048)
    (layers): ModuleList(
      (0-15): 16 x LlamaDecoderLayer(
        (self_attn): LlamaAttention(
          (q_proj): Linear(in_features=2048, out_features=2048, bias=False)
          (k_proj): Linear(in_features=2048, out_features=512, bias=False)
          (v_proj): Linear(in_features=2048, out_features=512, bias=False)
          (o_proj): Linear(in_features=2048, out_features=2048, bias=False)
        )
        (mlp): LlamaMLP(
          (gate_proj): Linear(in_features=2048, out_features=8192, bias=False)
          (up_proj): Linear(in_features=2048, out_features=8192, bias=False)
          (down_proj): Linear(in_features=8192, out_features=2048, bias=False)
          (act_fn): SiLUActivation()
        )
        (input_layernorm): LlamaRMSNorm((2048,), eps=1e-05)
        (post_attention_layernorm): LlamaRMSNorm((2048,), eps=1e-05)
      )
    )
    (norm): LlamaRMSNorm((2048,), eps=1e-05)
    (rotary_emb): LlamaRotaryEmbedding()
  )
  (lm_head): Linear(in_features=2048, out_features=128256, bias=False)

뭔가 출력을 해서 보여주긴 했지만, 아직까지는 어떤게 무엇인지 감이 안오시죠? ㅎㅎ 이제 한단계씩 알아보도록 해보겠습니다

Embedding

가장 첫줄에는 embed_tokens 이라는 것이 있군요. 처음에 소개할 때 Token 을 예측하는 모델이라고 하였는데요.

Token 은 무엇이고, embed 는 뭘까요?

먼저, Token 은 주어진 Text 를 Model 이 처리할 수 있는 데이터로 변환한 단위를 의미합니다.

즉 Model 은 Token 단위로 unqiue 한 숫자ID 를 가지게 되며, 내부적으로는 숫자ID 를 기반으로 데이터만 전달하게 되는 것이죠

Token 은 너무나 작은 단위(1 character) 로 하게 되면, 모델이 처리해야 되는 데이터가 기하급수적으로 증가하고 의미적인 관계를 파악하기가 어렵습니다.

너무나 큰 단위(1 word) 로 하게 되면, 엄청나게 많은 단어집을 모델이 들고 있어야하고, 의미적인 관계가 같은데도 서로 다른 id 를 가져야 합니다.

예를 들면, word 와 words 는 단어를 의미하고, 둘간의 단어의 차이는 1개의 word 이냐 복수개의 word 를 지칭하고 있습니다.
'w' , 'o' , 'r', 'd' 는 의미적인 관계를 파악하기에 어렵고, 'word' 'words' 는 서로 같은 의미를 가지고 있습니다

따라서 보편적으로는 이에 대한 절충안으로 유사도를 고려한 하위 단어(sub word) 로 token 의 단위를 결정하게 됩니다

예시를 통해 쉽게 알아볼게요.

tokenizer.tokenize("Hello. I am studying about LLMs.")
# ['Hello', '.', 'ĠI', 'Ġam', 'Ġstudying', 'Ġabout', 'ĠL', 'LM', 's', '.']

하나의 문장을 Model 이 정의한 token 단위로 변환되는 것을 볼 수 있죠. 신기한 것은 LLMs 과 같은 축약어를 'L' 'LM' 's' 로 변환했다는 것에 주목해주세요

그 다음, Embed 는 뭘까요?

Embedding 은 Token 에서 ID 로 변환된 데이터를 벡터(Nx1 행렬) 표현한 것을 의미합니다.

Embedding

저는 앞서서 의미적인 관계를 파악하는 것에 대해 말씀드렸는데요.

우리가 어떤 Token 을 예측하기 위해서는, 의미적인 관계를 파악하는 것이 매우 중요하기 때문입니다.

'나는 XXX 다' 와 '똑똑한 나는 XXX 다' 에서 XXX 를 예측하는데에는 의미적인 관계를 알면 올바르게 XXX 를 예측할 확률이 높아진다고 보면 되요

그래서 Embedding 은 어떤 하나의 문장을 고차원 행렬로 변환시키는 과정을 갖게 되는 것이죠.

각 Token 은 vector(Nx1 행렬) 하나의 문장은 여러개의 Vector 를 가진 NxN 행렬을 탄생시키게 됩니다.

고차원의 행렬을 만들게 되면, cosine 함수와 같은 것을 이용하여, 유사도를 계산할 수 있게 됩니다. (같은 방향이면 같은 유사도)

Cosine 유사도

길고긴 embed_token 을 지나 이제 본격적으로 다음 Layer 로 넘어가도록 하겠습니다 ㅎㅎ

Self Attention Layer

이제 가장 중요한 Attention Layer 입니다. 여기서부터는 사실상 Transformer 아키텍쳐라고 볼 수 있습니다.

위에서도 보시다 싶이 크게 2가지 단계를 볼 수 있는데요.

Multi-Head Attention : Token 들의 문맥을 파악하고, Token 의미를 업데이트하는 과정(Apple 은 사과일 수도 혹은 기업일 수도)
Feed forward : Token 그 자체의 정보를 해석하고 지식을 꺼내는 곳(Apple 기업은 아이폰을 만든다)

llama 에서 Multi head attention 은

        (self_attn): LlamaAttention(
          (q_proj): Linear(in_features=2048, out_features=2048, bias=False)
          (k_proj): Linear(in_features=2048, out_features=512, bias=False)
          (v_proj): Linear(in_features=2048, out_features=512, bias=False)
          (o_proj): Linear(in_features=2048, out_features=2048, bias=False)
        )

로 구성되어 있군요! q,k,v,o 는 아래와 같은 역할을 가지고 있습니다

q_proj: Query(질문) 에 대한 Token 들의 행렬(2048 x 2048)
k_proj: Key(색인) 에 대한 Tokene 들의 행렬(2048 x 512)
v_proj: Value(값) 에 대한 Token 들의 행렬(2048 x 512)
o_proj: Output(결과) 에 대한 Token 들의 행렬(2048 x 2048)

핵심은 Q, K, V 라는 것을 알 수 있습니다. 각 Q,K,V 를 아래와 같은 수식으로 변환하게 되는데요

Attention

Query 와 Key 를 곱해서 연관성을 확인하고, 그 후 숫자를 안정화(분모) 한뒤에 softmax 함수를 통해 확률분포를 갖게 되며 각 확률별로 문장내에 있는 다른 Token의 Value 를 곱해서 모두 더하게 됩니다.

결과적으로 이러한 복잡한 수식 연산 과정이 Token 이 개별로 갖는 의미를 파악하기 위함이라고 볼 수 있죠

MLP layer

MLP(Multi Level Perceptron) 은 Perceptron 을 여러개의 Level 로 구성해둔 것을 의미하는데요

Perceptron 은 인공신경망(Neural Network)를 구축하는 가장 기본적인 단위라고 이해하시면 됩니다.

Perceptron

쉽게 이야기하면 여러개의 입력과 가중치를 받아서 하나의 출력을 형성하는 것이라고 보면 됩니다.

그러면 실제로 llama 에서는 어떤식으로 설계하게 된 걸까요?

          (gate_proj): Linear(in_features=2048, out_features=8192, bias=False)
          (up_proj): Linear(in_features=2048, out_features=8192, bias=False)
          (down_proj): Linear(in_features=8192, out_features=2048, bias=False)
          (act_fn): SiLUActivation()

구성	설명
gate_proj	정보의 중요도를 판단하기 위해 입력된 vector 의 차원을 확장합니다. up_proj 와 동일한 차원으로 확장합니다.
up_proj	입력된 vector 의 차원을 확장합니다. llama 는 2048 차원에서 8192 인 4배로 확장합니다
down_proj	넓어진 vector 를 다시 축소합니다. 이때 중요정보만 남기고 불필요한 것은 버립니다. (gate_proj, up_proj 값을 기반)
act_fn	활성화 함수. 복잡하고 추상적인 개념을 이해하기 위함. llama 에서는 SiLU 함수를 따름

llama 3.2 기준으로는 projection layer 에 gateway projection 을 추가로 둠으로써 더 정교하게 데이터를 제공하기 위한 기반을 제공하고 있습니다. Projection layer 라는 것은 단순 행렬 곱연산을 위한 하나의 단계라고 이해하시면 됩니다. Token 들이 가지고 있는 벡터들을 N 차원의 공간으로 투영시켜, 벡터가 가지는 의미적인 관계를 추론하다고 보시면 되겠습니다.

activation functions

활성화 함수(Activation functions)라는 것에 대해 조금 더 어렵게 느껴지긴 합니다만. 쉽게 설명하면 선형적인 그래프를 곡선의 그래프로 바꾸기 위함입니다.

더~ 쉽게 이야기하면 터무니 없는 결과값은 취급하지 않게 하기 위해 계산이 아닌 drop 하는 것을 의미합니다.

위 그림으로 보이듯이 선형(Linear) 그래프는 y 값의 제한이 없기 때문에, 무한으로 값이 확장될 수 있는 구조인데,
y 값 자체를 한계를 지어버리면 다른 그래프들처럼 완만한곡선 혹은 기울기가 매우 작은 형태를 띄게 되는 것을 볼 수 있습니다.

결과적으로, Selft attention layer 와 MLP layer 를 통과하게 되면, 다음 Token 을 예측하이 모두 끝난 것이죠

Token 자체의 문맥을 이미 파악했고, Token 의 개념까지 확장해내었으니, 어떤 Token 이 다음에 와야할지 vector 정보로 갖고 있게 된답니다.

Normalization

그런데 위에 원리들을 보다보면, 수없이 확장되면 경우의 수가 너무 많아지지 않을까? 하는 생각도 드는데요.

이렇게 과한 확장을 방지하기 위해 Normalization 이 존재한답니다.

    (norm): LlamaRMSNorm((2048,), eps=1e-05)

조금 쉽게 설명하면, 숫자를 곱하는 과정에서 너무 크거나, 작은 값들을 없앰으로써 일정한 숫자 범위를 갖도록 하는 것입니다.

한번 숫자가 너무 커져버리면, 최종적인 확률 분포를 계산하는데에 있어 고르게 분포할수는 없고 편향적으로 분포하게 되거든요

Normalization 은 일종의 안정화 작업이라고 보면 됩니다. llama 구조에서는 아래와 같은 normalizatioin 이 존재하는데요

        (input_layernorm): LlamaRMSNorm((2048,), eps=1e-05)
        (post_attention_layernorm): LlamaRMSNorm((2048,), eps=1e-05)

attention 에 들어가기 전과 후에 normalization 을 넣어주면 학습시에 더 안정적인 결과를 얻어낼 수 있겠죠!

Lm head

자, 이제 최종적인 최종적인 vector 정보를 알게 되었으니, 이 vector 를 다시 Token ID 숫자를 기반으로 Token 언어로 바꾸게 되는 것입니다.

  (lm_head): Linear(in_features=2048, out_features=128256, bias=False)

어떻게 보면 embed_token 의 반대의 행렬이라고 볼 수 있죠. embed_tokens 는 128,256 x 2,048 행렬이었지만, lm_head 는 2,048 x 128,256 행렬이겠군요

그래서 Lm head 는 주어진 vector 를 기반으로 행렬곱 연산을 진행하여 model 이 갖고 있는 모든 Token 에 대한 점수(logits) 를 반환하게 되는 것입니다.

요런식으로 말이죠

우리가 Open AI 혹은 Anthropic 에서 Temperature 나 Top_k 이런 파라미터를 받는 것들은 LM head 를 통해 나온 점수(logits)를 기반으로 확률을 구할 때 어떤 곱셈 파라미터를 적용하여, 확률 분포를 고르게 하거나(Temperature), 가장 가능성 있는 몇 개만 선정(Top_k)하기 위한 과정이라고 이해하시면 됩니다

정리하며

이렇게 우리는 llama 구조를 기반으로 LLM 이 동작하는 방식에 대해 쉽게 설명해보았습니다.

각 layer 마다 되게 심도있는 학술 자료들이 많지만, 깊이 들어가지 않는 선에서 쉽게 정리해보았는데요.

기본적인 원리를 이해함으로써, LLM application 을 제작하기 위한 Insight 를 얻기 위함으로 이해해 주시면 좋겠네요 ㅎㅎ

Reference

How transformers solve problem

Embedding 이란 무엇이고 언제 사용하는가

LLM's simplified

Automated dependency update - Renovate 란 무엇인가?

huisam — Sun, 30 Mar 2025 23:15:25 +0900

들어가며

안녕하세요~ 오늘은 자동적으로 버젼을 관리해주는 renovate 에 대해 알아보도록 해보겠습니다.

소프트웨어를 운영하다보면 여러가지 라이브러리들을 사용하게 되고, 관리하는 라이브러리들이 점점 많아지게 되는데요.

아무래도 소프트웨어를 지속적으로 운영하기 위해서는 버젼관리가 항상 필수적으로 요구되는 사항입니다.

우리는 버젼관리 에 대한 자동화를 통해 조금 더 원활하게 버젼관리를 진행하고, 매번 업데이트되는 사항들을 받아보는 것을 기반으로 Pull request 까지 자동 생성하게끔 하는 것이 renovate 를 사용하는 목적이라고 볼 수 있겠습니다.

Renovate란?

Renovate는 오픈 소스 도구로, GitHub, GitLab, Bitbucket과 같은 다양한 플랫폼에서 의존성의 자동 업데이트를 지원합니다.

이 도구는 프로젝트의 package.json, Gemfile, pom.xml 등 다양한 설정 파일을 분석하여 필요한 업데이트를 자동으로 제안하고, 이를 Pull Request 형태로 생성합니다.

주요 기능

그래서 주요한 기능에 대해 먼저 알아볼 것인데요. Renovate 에서 제공하는 주요 기능들은 아래와 같습니다.

크게 4가지 주요한 기능들이 아주 중요한 포인트라고 볼 수 있어요.

자동 업데이트
- Renovate는 다양한 패키지 매니저(예: npm, Yarn, Maven 등)를 지원하여 프로젝트의 의존성을 자동으로 확인하고, 최신 버전을 제안합니다.
- 각 Pull Request는 업데이트된 버전의 세부 정보와 변경 로그를 포함하여 개발자가 쉽게 이해할 수 있도록 합니다.
스케줄링
- 사용자 맞춤형 스케줄을 설정하여 업데이트 빈도를 조정할 수 있습니다. 예를 들어, 매주 월요일마다 업데이트를 확인하도록 설정할 수 있습니다.
보안 취약점 탐지
- Renovate는 보안 취약점이 발견된 패키지를 자동으로 감지하여 최신 안정 버전으로 업데이트합니다. 이는 프로젝트의 보안을 크게 강화하는 데 기여합니다.
세부 설정 옵션
- Renovate는 다양한 설정을 통해 업데이트 방식과 조건을 조정할 수 있습니다. 예를 들어, 특정 라이브러리는 항상 최신 버전으로 업데이트하도록 설정하거나, 메이저 버전 업그레이드는 수동으로 처리하도록 설정할 수 있습니다.

적용 예시

먼저 k8s 기반으로 self hosting 하는 예시를 들어볼까 합니다.

아무래도 회사내 시스템에 적용하는 것을 목표로 한다면, public github 보다는 enterprise github 혹은 gitlab 을 사용할 가능성이 높으니까요

apiVersion: batch/v1
kind: CronJob
metadata:
  name: renovate
spec:
  schedule: '@hourly' # 실행 주기 설정
  concurrencyPolicy: Forbid
  jobTemplate:
    spec:
      template:
        spec:
          containers:
            - name: renovate
              image: renovate/renovate:latest
              args:
                - user/repo
              env:
                - name: LOG_LEVEL
                  value: debug
              envFrom:
                - secretRef:
                    name: renovate-env
          restartPolicy: Never

위와 같이 기본적인 cronjob 을 생성해주고, 얼마정도의 주기로 실행해줄 지를 적용합니다.

그 다음 인증정보를 채워주는 secret 만 등록해주면 되는데요~!

apiVersion: v1
kind: Secret
metadata:
  name: renovate-env
type: Opaque
stringData:
  RENOVATE_GITHUB_COM_TOKEN: 'any-personal-user-token-for-github-com-for-fetching-changelogs'
  # You can set RENOVATE_AUTODISCOVER to true to run Renovate on all repos you have push access to
  RENOVATE_AUTODISCOVER: 'false'
  RENOVATE_ENDPOINT: 'https://github.company.com/api/v3'
  RENOVATE_GIT_AUTHOR: 'Renovate Bot <bot@renovateapp.com>'
  RENOVATE_PLATFORM: 'github'
  RENOVATE_TOKEN: 'your-github-enterprise-renovate-user-token'

이런식으로 사외 github 에서 change log 를 가져올 github access token 과 사내에서 사용되는 github token 을 발급받아 지정해주면 됩니다.

그렇게 되면, 자동으로 renovate 는 돌게 되고,

sample repository

아무래도 사내 github 을 가져올 수는 없으니, 공개 github 에 적용되어 있는 제 예시 repository 와 함께 샘플로 남겨드립니다 ㅎㅎ

https://github.com/huisam/spring-observability/blob/main/renovate.json

spring-observability/renovate.json at main · huisam/spring-observability

Playground for spring observability based on opentelemetry - huisam/spring-observability

github.com

마무리하며

Renovate는 소프트웨어 개발에서 의존성 관리를 혁신적으로 변화시키는 도구입니다.

자동화된 업데이트, 보안 관리, 유연한 설정 옵션 등을 통해 개발자는 코드의 품질을 유지하고, 프로젝트의 안전성을 강화할 수 있습니다.

더 이상 수동으로 의존성을 관리할 필요 없이, Renovate를 통해 효율적인 개발 환경을 구축해보시면 좋겠네요 ㅎㅎ

참고

Renovate Docs