ALO-LLM 프레임워크 사용한 표준 개발

Updated 2025.08.26

이 문서는 ALO-LLM 프레임워크를 사용하여 로컬 환경에서 서비스 API를 개발하는 방법을 안내합니다.

로컬 환경에서 API 개발하기

ALO-LLM은 사용자가 작성한 로직 코드를 FastAPI 형태로 변환하여 LLMOps에 등록하고, 인프라 환경까지 자동으로 구축하여 운영할 수 있도록 도와주는 개발 프레임워크입니다. LLM 로직 개발자는 복잡한 설정 없이 Service API 개발, 등록, 운영까지의 과정을 간편하고 효율적으로 처리할 수 있습니다.

제약사항

• python 3.12.x 버전 사용을 권장합니다.
• VS Code의 사용을 권장하며, Mobaxterm을 사용하시는 경우, 코드 및 주석에 한글 사용시 에러가 발생할 수 있습니다.

LLM 로직 개발자들은 아래와 같은 2단계를 진행하면서 Service API 를 Local 환경에서 개발할 수 있습니다.

1단계 : LLM Logic Code 작성

환경 변수를 .env 파일에 작성하고, load_dotenv를 사용하여 읽어들입니다. .env는 LLMOps에 등록 시 해당 파일의 내용을 AI Pack이 구동하는 Pod에 환경 변수로 등록이 되기 때문에 꼭 필요합니다 함수 정의 시 타입을 명시하고, Langchain 문법을 사용해 코드를 작성하며, 반환값은 Dict 형태로 구성합니다.

• o11y 패키지를 다운받아서 사용하는 경우 python-dotenv를 사용하지 않고 o11y에서 제공해주는 load_env를 사용해야 하 기 때문에 확인하고 사용해야 합니다.

2단계 : LLM Logic Code의 Service API화

ALO-LLM을 설치합니다. config.yaml 파일을 작성하여 필요한 라이브러리와 API 맵핑을 정의합니다. 그런 다음 alm api 명령어를 사용해 Logic 코드를 FastAPI로 전환합니다.

---

1단계: LLM logic code 작성

제약사항

• 로직 코드의 이름이 (main.py, alm.py) 혹은 함수 이름이 (main, alm)일 경우 에러와 가이드 문서가 출력되니 두 이름은 지양 부탁드립니다.
• 로직 코드에서 load하는 data의 이름은 영문으로 작성해주셔야 합니다.

LLM logic code 작성 시 아래의 3 가지 규칙만 따라주시면 됩니다. 또한, 작성하신 LLM logic code의 정상 동작 여부를 반드시 확 인하시고 다음 단계를 진행해주셔야합니다.

규칙 1: 현재 경로의 .env 파일에 사용할 모든 key(LLM model ky, DB endpoint 등) 값들을 작성하고, logic code에서 load_dotenv와 getenv 함수를 사용하여 환경 변수를 적용합니다.

규칙 2: Logic code 내 함수 정의 시 함수의 arguments는 type 정의를 반드시 해주셔야 합니다.

규칙 3: .env에 작성한 환경 변수들은 각 로직 코드에서 환경 변수로 load해서 사용합니다(gpt key, o11y의 주소, db uri)

####### .env #######
### .env logic code , . ###
# observability
LANGFUSE_SECRET_KEY="xxxxxxxxxxxxxxxx"
LANGFUSE_PUBLIC_KEY="xxxxxxxxxxxxxxxx"
LANGFUSE_HOST="http://langfuse.lge.com"
# LLM model
OPENAI_API_TYPE='azure'
AZURE_OPENAI_API_KEY='xxxxxxxxxxxxxxxxxxxx'
AZURE_OPENAI_ENDPOINT='https://dev.dxengws.apim.lgedx.biz/shared-1000'
AZURE_OPENAI_EMBEDDING='https://dev.dxengws.apim.lgedx.biz/shared-embedding'
OPENAI_API_VERSION='2023-05-15'
OPENAI_MODEL_ID='gpt-4o-2024-08-06'
# DB
DATABASE_LOADER_URI= DB_URI
DATABASE_LOADER_TYPE= DB_name
# VECTOR DB
VECTOR_LOADER_URI= DB_URI
VECTOR_LOADER_TYPE= DB_name

• 이 외에도 사용자가 편리한 이름으로 추가해서 사용 가능합니다
• 해당 내용을 제작 후 logic code에서 os.getenv로 사용하시면 됩니다

import os
import functools
from langchain_openai import ChatOpenAI
from langchain_openai import AzureChatOpenAI
from langchain.prompts import ChatPromptTemplate
from dotenv import load_dotenv
load_dotenv()
#
OPENAI_API_TYPE = os.getenv("OPENAI_API_TYPE", "openai").lower()
AZURE_OPENAI_API_VERSION = os.getenv("OPENAI_API_VERSION")
OPENAI_MODEL_ID = os.getenv("OPENAI_MODEL_ID")
def get_openai_model() -> ChatOpenAI:
    if OPENAI_API_TYPE == "azure":
        return AzureChatOpenAI(model=OPENAI_MODEL_ID, api_version=AZURE_OPENAI_API_VERSION)
    else:
        return ChatOpenAI(model=OPENAI_MODEL_ID)
def ask_chat(topic: str) -> dict:
    model = get_openai_model()
    full_prompt = f"Tell me a joke about {topic}."
    prompt_template = ChatPromptTemplate.from_template(full_prompt)
    chain = prompt_template | model
    response = chain.invoke({"topic": topic})
    return {
        'response': response.content
    }

Tip

함수의 입력 type에 list 혹은 dict를 사용하고 싶으신 경우 아래와 동일하게 해주시면 됩니다.

def basic_analysis(question: list[str], answer: dict[str, int]):

그리고 config.yaml 파일은 아래와 같이 dict, list로 작성합니다.

...
service_api:
    path:
        /api/basic_analysis: # api path
            POST: # method
            handler: rest_index_api.basic_analysis # (python 파일).(함수)
            parameter: # args.
                question: list
                answer: dict

Tip

request 시 body로 전송하고 싶으신 경우 아래와 같이 사용하시면 됩니다.

from pydantic import BaseModel
class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None
def create_item(item: Item):
    print(item)
    return item

parameter의 value 값으로 object를 사용합니다.

...
service_api:
    path:
        /api/basic_analysis: # api path
            POST: # method
            handler: test.create_item# (python 파일).(함수)
            parameter: # args.
                item: object

---

2단계: LLM Logic code의 Service API화 진행

ALO-LLM 실행을 위한 사용자 작성 파일

ALO-LLM 패키지 설치 후, logic 개발 시에 아래와 같은 파일이 작업 경로에 존재해야 합니다.

1. config.yaml : Service API 를 어떻게 구성할지에 대한 configuration 입니다.
2. model.py (파일명 자유) : LLM logic 을 함수단위로 구현한 파일 입니다.
3. .env : Azure OpenAI 를 사용하기 위한 환경변수 설정 파일 입니다.

Service API는 FastAPI 프레임워크를 기반으로 구축됩니다. 각 API의 입력 형식을 규정해야 하며, URI를 명확하게 정의해야 합니 다. ALO-LLM는 이러한 규정을 바탕으로 자동으로 API를 생성합니다.

2-1. ALO-LLM를 pip 명령어로 설치

• pip install 명령어로 설치합니다 pip install mellerikat-alm

주의사항

ALO-LLM CLI를 통해 등록 시 현 위치에 존재하는 모든 폴더와 파일을 압축하여 등록합니다.

2-2. config.yaml 작성

---

• 작성하신 logic code를 기반으로 yaml을 작성합니다.

name: simple_chatbot # Service api name
version: 1.0.0 # Service api version
entry_point: alm api #
overview: A framework that easily converts Python code to FastAPI and deploys it to a production environment.
description:
    Agent: ALO-LLM #
    Developer: 홍길동 #
    Documents: http://collab.lge.com/main/pages/viewpage.action?pageId=3035388304 #
    codes: http://mod.lge.com/hub/llmops-aibigdata/llo/llo-dev/-/tree/v1.0.2?ref_type=heads #
    version: v1.2.0 # key
    etc: etc..
setting: # library
    pip:
        # requirements: True # True인 경우 requirements.txt
        requirements:
            - python-dotenv
            - pandas
            ..
    ai_logic_deployer_url: "https://ald.llm-dev.try-mellerikat.com" # AI Logic Deployer
components:
    local_host:
        port: 1333
service_api: # logic code
    path:
        /api/ask_chat: # api path
            POST: # method
            handler: chat.ask_chat# (python 파일).(함수)
            parameter: # args.
                topic: str

• name: 이 필드는 서비스 API의 이름을 지정합니다. 여기서는 simple Chatbot으로 명명되었습니다.
• version: 서비스 API의 버전을 설정합니다. 현재 버전은 1.0.0입니다
• entry_point: 사용자가 실행할 명령어입니다. ALO-LLM을 사용하시는 경우는 'alm api'로 그 외 사용자 custom 명령어로 쓰시면됩니다.
• overview: 전반적인 서비스 API의 설명을 적습니다.
• description: 등록한 서비스 API의 자세한 설명을 적습니다. key: value 형태로 작성하며, 상위 4개(Agent 명, 개발자, Documents, Codes)는 필수로 그 외는 사용자가 추가/삭제하여 작성할 수 있습니다.
• setting: 서비스 구성을 위한 설정을 나타냅니다.
• pip: 설치할 라이브러리 목록을 지정합니다.
• requirements: 필요한 라이브러리들을 나열합니다.
• ai_logic_deployer_uri: 등록 및 배포를 진행할 AI Logic Deployer의 주소를 적습니다.
• components: 이 필드는 실험에 사용되는 port를 정의하는 부분입니다.
• local_host: 로컬 실험 영역에 대한 설정 부분입니다.
• port: 로컬 환경에서 테스트를 위한 포트 설정 부분입니다. 설정한 포트가 사용 불가능한 경우 랜덤으로 할당됩니다. (1024 이상으로 지정해주세요)
• service_api: 작성한 로직 코드를 API로 맵핑하는 설정을 포함합니다.
• path: 특정 API 경로와 메서드를 정의합니다.
• /api/generate_questions: 정의된 API 경로입니다.
• GET: HTTP 메서드입니다. GET 혹은 POST 메서드를 사용합니다.
• handler: 해당 핸들러는 (python 파일).(함수) 형식을 따릅니다. 여기서는 rest_index_api.generate_questions로 지정되어 있습니다.
• parameter: 함수의 인자(arguments)와 입력 타입을 설정합니다.
• target: 문자열 타입(str)의 인자입니다.
• ...

2-3. 작성한 Logic 코드를 Fast API 형태로 변경

---

• 작성된 로직 코드를 Fast API화 하기 위해 CLI 명령어를 실행합니다.

alm api

• 정상적으로 실행된 경우 Local URL이 출력됩니다.

2-4. Local 환경에서 Service 정상 동작 여부 확인

주의 사항

1. 0.0.0.0 주소 대신, 실제 서버 주소로 접근해주시면 됩니다.
2. ex) http://{host}:{port}/docs/api/v1 → http://10.158.2.106:8758/docs/api/v1

• swagger를 통한 정상 동작을 확인합니다. (위 작성된 서버 주소에/docs/api/v1을 추가합니다. → ex: http://10.158.2.106:8758/docs/api/v1)
• (Optional) 사용한 LLM의 observability 확인을 위해 langfuse에 접속합니다.

---

참고 자료

python 3.12 가상 환경 생성

pyenv 설치 용 스크립트를 다운로드 합니다.

curl -L -o install_pyenv.sh http://mod.lge.com/hub/dxadvtech/aicontents-framework/alo-guide/-/raw/main/install_pyenv.sh

사외 사용자의 경우:

curl -L -o install_pyenv.sh https://raw.githubusercontent.com/meerkat-alo/alo-guide/main/install_pyenv.sh

pyenv 와 pipenv 설치 및 실행 합니다.

## pyenv
exec bash ## bash
bash install_pyenv.sh (or ./install_pyenv.sh)
pyenv install 3.12
## pyenv
pyenv global 3.12
## pipenv
python3 -m pip install --user pipenv
## pipenv
## virtual_env_dir . mkdir .
## .
mkdir (virtual_env_dir)
cd (virtual_env_dir)
pipenv --python 3.12
pipenv shell

• pyenv install 3.12 에서 WARNING 이나 ERROR 시 다음과 같이 의존 패키지 설치 후 재시도 sudo apt install zlib1g zlib1g-dev libssl-dev libbz2-dev libsqlite3-dev libncurses-dev libffi-dev tk-dev liblzma-dev libreadline-dev -y
• 기존에 가상 환경을 생성하신 경우에는 아래 명령어만 터미널에 입력하시면 됩니다.

cd (virtual_env_dir)
pipenv --python 3.12
pipenv shell