.js

gpt-oss tutorial(cpu에서 실행하기)

Wed, 20 Aug 2025 00:00:00 +0000

1. gpt-oss 개요

OpenAI는 2019년 이후 처음으로 가중치가 공개된 대형 언어 모델을 발표했다. 이름은 gpt-oss로, 두 가지 모델(20b, 120b)이 제공된다. 단순히 연구용 데모 수준이 아니라, 실제 환경에서 활용 가능한 고성능 모델을 누구나 내려받아 쓸 수 있다는 점에서 의미가 있다. (그리고 ClosedAI가 아닌 드디어 OpenAI가 됐다는 점에서도)

gpt-oss는 Transformer 기반 구조 위에 Mixture-of-Experts(MoE) 방식을 적용했다. 모든 토큰을 처리할 때 전체 파라미터가 동원되는 것이 아니라, 일부 전문가 집합만 활성화되어 연산 효율을 크게 높인다. 훈련시 4비트 양자화(MXFP4) 기법이 사용되었다. 또한 작업에 따라 reasoning effort 를 3단계로 설정할 수 있고 low로 설정시 매우 빠른 속도로 추론이 가능하다. 따라서 파라미터 규모가 크더라도 상대적으로 가벼운 리소스로 실행할 수 있다.

gpt-oss 20b 모델

gpt oss 20b는 약 210억 개의 파라미터를 가지고 있으며, 이 중 실제로 활성화되는 파라미터 수는 약 3.6억 개다. 이 모델의 가장 큰 특징은 16GB 메모리 환경에서도 실행 가능하다는 점이다.

즉, 최신 고성능 GPU 없이도 개인 PC나 엣지 디바이스에서 돌릴 수 있어 접근성이 매우 높다. 성능은 OpenAI의 o3-mini 모델과 유사한 수준으로 알려져 있으며, 일상적인 질의응답, 코드 작성, 간단한 추론 작업에 무리 없이 활용 가능하다.

gpt-oss 120b 모델

규모가 더 큰 120b 모델은 총 1,168억 파라미터를 갖고 있으며, 활성 파라미터는 약 51억 개다. 단일 80GB GPU(H100, MI300X 등)에서 구동할 수 있고, 성능은 o4-mini 모델에 근접한다.
주로 고사양 서버 환경에서의 대규모 추론이나 정밀한 작업을 위해 설계되었지만, 20b 모델과 동일하게 오픈 가중치로 제공되므로 연구·개발·커스터마이징에도 적합하다. 물론 PC나 서버에 많은 투자를 한게 아니라면 개인이 실행하는데에는 무리가 있다.

2. OpenAI Harmony 포맷

2-1. Harmony 포맷이란?

gpt-oss 모델은 Harmony 응답 포맷으로 학습되었으며, 포맷 없이 사용 시 올바르게 동작하지 않는다.
이 포맷은 OpenAI의 Responses API 구조를 모방해 설계되었으며, 대화 구조, 추론 흐름 (Chain-of-Thought), function 호출 구조화를 모두 포함한다.

쉽게 말해, 모델이 정형화된 포맷으로 답변을 생성하기 때문에 유저 입장에서 모델 출력결과가 최종 답변인지 함수 호출인지 등을 손쉽게 구분할 수 있고, 함수 호출이라면 함수명이 무엇이고 인자는 어떤 형태로 제공되는지 등을 바로 알 수 있다. 따라서 답변 형식을 따로 프롬프트 엔지니어링으로 사전에 정의하는 수고를 덜 수 있다.

2-2. 주요 구성 요소

역할 (Roles)

system: 정체성, 추론 수준, 메타 정보, 내장 도구 등을 지정
developer: 시스템 프롬프트나 function tool 지침을 작성할 때 사용
user: 사용자 입력
assistant: 모델 출력 또는 도구(함수) 호출, 3개의 채널을 사용함.
tool: function 도구 호출의 결과 메시지를 나타냄
역할 계층: system > developer > user > assistant > tool

채널 (Channels)

analysis: 모델의 추론 과정(CoT)을 담당하는 채널. 최종 사용자에게 노출되지 않도록 주의해야함.
commentary: 도구(함수) 사용 요청을 보내고, 사용자로부터 받은 함수 실행 결과값을 처리하는 채널.
final: 최종 출력을 담당하는 채널. 사용자에게 보여지는 메시지.

2-3. Harmony 렌더러 라이브러리

OpenAI는 Python 및 Rust용 공식 openai-harmony라이브러리를 제공하며, 이를 통해 올바른 포맷을 생성하고 토큰화할 수 있다. 다음은 harmony cookbook에서 볼 수 있는 대화 렌더링 예시이다. 총 6개의 메세지로 구성되어 있다. Identity(1번)와 시스템 프롬프트(2번)는 항상 앞에 위치하는 형식으로 시작된다. 유저의 질문(3번)을 어시스턴트가 질문의 의도를 분석해(4번) 함수 실행을 유저에게 요청하며 함수명과 인자를 제공(5번)한다. 마지막으로 실행된 함수의 결과값을 받아(6번) 처리한다.

# system_message, develper_message 정의하는 법은 cookbook 참조

convo = Conversation.from_messages(
    [
        # System Messege: Identity(모델 정체성)과 reasoning effort 등이 포함된다. 특히, 모델 정체성은 아래 문장을 바꾸지 말고 그대로 사용하라고 강조한다.
        # You are ChatGPT, a large language model trained by OpenAI.
        Message.from_role_and_content(Role.SYSTEM, system_message),
        # Developer Messege: 시스템 프롬프트, 모델의 성격이나 역할, 룰 등을 정의하고 싶다면 이 부분에 정의하면 된다.
        Message.from_role_and_content(Role.DEVELOPER, developer_message),
        # 이 아래로는 user와 assistant간의 대화, 또는 assistant의 CoT, function call 등이 순차적으로 이어진다.
        Message.from_role_and_content(Role.USER, "What is the weather in Tokyo?"),
        Message.from_role_and_content(
            Role.ASSISTANT,
            'User asks: "What is the weather in Tokyo?" We need to use get_weather tool.',
        ).with_channel("analysis"),
        Message.from_role_and_content(Role.ASSISTANT, '{"location": "Tokyo"}')
        .with_channel("commentary")
        .with_recipient("functions.get_weather")
        .with_content_type("%3C|constrain|%3E json"),
        Message.from_author_and_content(
            Author.new(Role.TOOL, "functions.lookup_weather"),
            '{ "temperature": 20, "sunny": true }',
        ).with_channel("commentary"),
    ]
)

tokens = encoding.render_conversation(convo)
convo_harmony = encoding.decode(tokens)
print(convo_harmony)

출력결과

<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.
Knowledge cutoff: 2024-06
Current date: 2025-08-21

Reasoning: high

# Valid channels: analysis, commentary, final. Channel must be included for every message.
Calls to these tools must go to the commentary channel: 'functions'.<|end|><|start|>developer<|message|># Instructions

Always respond in riddles

# Tools

## functions

namespace functions {

// Gets the current weather in the provided location.
type get_current_weather = (_: {
// The city and state, e.g. San Francisco, CA
location: string,
format?: "celsius" | "fahrenheit", // default: celsius
}) => any;

} // namespace functions<|end|><|start|>user<|message|>What is the weather in Tokyo?<|end|><|start|>assistant<|channel|>analysis<|message|>User asks: "What is the weather in Tokyo?" We need to use get_weather tool.<|end|><|start|>assistant to=functions.get_weather<|channel|>commentary <|constrain|> json<|message|>{"location": "Tokyo"}<|call|><|start|>functions.lookup_weather<|channel|>commentary<|message|>{ "temperature": 20, "sunny": true }<|end|>'

render_conversation(Conversation)함수 대신 render_conversation_for_completion(Conversation, Role.ASSISTANT))함수 사용시 마지막에 추가로 <|start|>assistant|>토큰이 붙은 결과로 나온다. 모델 입력으로 사용시엔 꼭 후자로 사용해야만 답변이 정상적으로 생성된다. (assistant가 답변할 차례라는것을 명시적으로 가이드하는 역할)

2-4. Harmony 흐름 요약

3. Unsloth 개요

3-1. Unsloth란?

Unsloth는 OpenAI의 gpt-oss를 포함한 다양한 LLM을 더 빠르고 효율적으로 실행, 튜닝 가능하게 해 주는 오픈소스 프레임워크이다.

3-2. Unsloth의 장점

경량화된 실행 환경: gpt-oss-20b는 약 14 GB VRAM으로 튜닝 가능하며, 120b는 65 GB로 충분하다.
파인튜닝 효율 개선: 일반 방식 대비 1.5× 빠른 학습, 70% VRAM 감소, 10× 긴 컨텍스트를 제공한다.
포맷 호환성 강화: GGUF, llama.cpp, Hugging Face, vLLM 등 다양한 플랫폼과 호환 가능
Harmony 포맷 안정화: Unsloth의 chat template 수정으로 파싱 오류를 줄이고 안정성 확보
튜토리얼 제공: Colab 및 로컬 사용자를 위한 단계별 가이드와 안정적인 실행 흐름 제공

3-3. Unsloth에서 제공하는 gpt-oss 변형 모델

원본 gpt-oss는 mxfp4(4비트 양자화) 포맷만 지원하는데 반해, unsloth에서 제공하는 변형모델은 다양한 포맷과 양자화를 지원한다. 특히, mxfp4 포맷은 gpu에서만 실행할 수 있기 때문에 20b 모델 기준 최소 16gb vram gpu가 없는 pc에서는 로드조차 불가능한데, 변형모델 중 gguf 포맷으로 제공되는 버전은 llama.cpp를 활용해 cpu와 ram에서도 실행 가능하기 때문에 개인이 다루기에 아주 적합하다.

이 때문인지 허깅페이스에 올라온 다양한 gpt-oss 변형 모델 중 상위권을 차지하고 있다.

4. 튜토리얼

gpt oss를 로컬에서 실행하고, function call을 중심으로 간단한 채팅 워크플로우를 구성한 뒤, 앞에서 설명했던 예시인 유저의 현재 위치를 구하고 위치를 기반으로 기온을 구하는 워크플로우를 실행해본다. 마지막으론 실제로 내가 gpt-oss와 harmony를 다루면서 삽질한 경험을 바탕으로 모델 사용시 주의해야 하는 점을 정리했다.

4-1. gpt oss 20b CPU에서 실행하기

실행 환경

가상환경 생성이나 개발환경 세팅같은 내용은 생략하고, 현재 내가 사용중인 환경의 필수 패키지 버전만 작성했다.

python version: 3.12

requirements:

unsloth==2025.8.7
unsloth-zoo==2025.8.6
llama-cpp-python==0.3.16
openai-harmony==0.0.4

ram이 14gb정도 필요하므로 16gb, 여유있게 32gb ram 정도는 구매하는게 좋다.

gpt-oss-20b-F16.gguf 실행

import json

import unsloth

from llama_cpp import Llama
from unsloth_zoo import encode_conversations_with_harmony
from openai_harmony import (
    Author,
    Conversation,
    DeveloperContent,
    HarmonyEncodingName,
    Message,
    Role,
    SystemContent,
    ToolDescription,
    load_harmony_encoding,
    ReasoningEffort
)

# Model Loading
llm = Llama.from_pretrained(
    repo_id="unsloth/gpt-oss-20b-GGUF",
    filename="gpt-oss-20b-F16.gguf",
    jinja=True,
    n_ctx=16384, # unsloth recomendation
    n_threads=20,
    temp=1.0,  # openai recomendation
    top_p=1.0, # openai recomendation
    top_k=0,   # openai recomendation
    verbose=False
)

딱히 설명이 더 필요 없을 정도로 너무 쉽게 실행됐다. unsloth_zoo를 import 하기 전에 unsloth를 미리 import 하는게 좋다. 이유는 잘 모르겠지만 나의 경우는 unsloth_zoo만 단독으로 import하면 unsloth를 내부적으로 import하지 못하는 문제가 있었다.

4-2. 대화 워크플로우 구성

필요 함수 사전 정의

모델이 사용할 함수를 우선 정의한다. 유저의 현재 위치를 기반으로 해당 위치의 온도를 구하는 대화를 할 계획이기 때문에 location을 구하는 함수, temperature를 구하는 함수 두개가 필요하다. 출력값은 각각 “Korea, Republic of”과 25로 고정해놨고 json 포맷으로 변환할 수 있게 dict로 반환한다.

def get_current_temperature(location, format_t='celcius'):
    temperature = 25
    
    return {"temperature": temperature}
    
def get_current_location(userid, max_len=10):
    location = 'Korea, Republic of'
    
    if len(location) > max_len:
        location = location[:max_len]
        
    return {"location": location}

func_map = {
    "get_current_temperature": get_current_temperature,
    "get_current_location": get_current_location
}

System Message, Developer Message 작성

원래라면 openai-harmony 패키지에서 제공하는 Conversation, Author, Message 같은 클래스를 사용해 작성해야 하지만, unsloth에서 제공하는 encode_conversations_with_harmony 함수를 사용한다면 이를 훨씬 쉽게 작성할 수 있다. 첫 유저 메세지는 시험삼아 “안녕”이라고 작성해보았다.

# 추론 수준: low, medium, high
reasoning_effort = "low"
# 인코딩 결과를 모델 입력으로 사용할지 여부
add_generation_prompt = True
# 함수 명세
tool_calls = [
    {"function": {
        "name": "get_current_temperature", 
        "description": "get current temperature based on current location", 
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The Country, state or city, e.g. USA, CA, LA",
                },
                "format_t": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "default": "celsius",
                },
            },
            "required": ["location"],
        },
    }},
    {"function": {
        "name": "get_current_location", 
        "description": "get current location based on user metadata", 
        "parameters": {
            "type": "object",
            "properties": {
                "userid": {
                    "type": "string",
                    "description": "User's ID of current client session.",
                },
                "max_len": {
                    "type": "number",
                    "default": 10,
                    "description": "Max result length",
                },
            },
            "required": ["userid"],
        },
    }},
]
# 개발자 지침 또는 시스템 프롬프트
developer_instructions = "If you don't know the answer just say that you don't know."
# 모델 정체성 (!!!변경하지 말고 그대로 쓰기!!!)
model_identity = "You are ChatGPT, a large language model trained by OpenAI."

encoded = encode_conversations_with_harmony(
    [{"role": "user", "content": "안녕"}], # 대화내역
    reasoning_effort = reasoning_effort,
    add_generation_prompt = add_generation_prompt,
    tool_calls = tool_calls,
    developer_instructions = developer_instructions,
    model_identity = model_identity
)
print(encoded[0])

출력결과

<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.
Knowledge cutoff: 2024-06
Current date: 2025-08-21

Reasoning: low

# Valid channels: analysis, commentary, final. Channel must be included for every message.
Calls to these tools must go to the commentary channel: 'functions'.<|end|><|start|>developer<|message|># Instructions

If you don't know the answer just say that you don't know.

# Tools

## functions

namespace functions {

// get current weather based on current location
type get_current_temperature = (_: {
// The city and state, e.g. San Francisco, CA
location: string,
format_t?: "celsius" | "fahrenheit", // default: celsius
}) => any;

// get current location based on user metadata
type get_current_location = (_: {
// User's ID of current client session.
userid: string,
// Max result length
max_len?: number, // default: 10
}) => any;

} // namespace functions<|end|><|start|>user<|message|>안녕<|end|><|start|>assistant

출력결과 마지막이 <|start|>assistant로 끝나는데, 이는 add_generation_prompt=True로 설정했기 때문이다. false로 설정하면 저 부분이 추가되지 않는다. 모델 입력시 assistant가 대답할 차례라고 명시해주는 역할인데, 만약 이를 빼먹고 모델에 입력하면 출력결과에 문제가 생길 수 있다.

harmony encoding 정의

텍스트로 된 harmony 포맷을 객체 형태로 인코딩하거나 메세지 단위로 나누기 위해 필요하다.

allowed_special = {
    '<|start|>',     # 200006
    '<|end|>',       # 200007
    '<|message|>',   # 200008
    '<|channel|>',   # 200005
    '<|constrain|>', # 200003
    '<|return|>',    # 200002
    '<|call|>'       # 200012
}

# Harmony Encoding
harmony_encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)

# From harmony format string To list of tokens
# 모델 입력이 아닌 메세지 파싱이 목적이므로 EOS 토큰이 마지막에 와야함. <|start|>assisant 빼기 위해 [:-18] 슬라이싱
tokens = harmony_encoding.encode(encoded[0][:-18], allowed_special=allowed_special)
# From list of tokens to list of Message
parsed_messages = harmony_encoding.parse_messages_from_completion_tokens(tokens, Role.ASSISTANT)
print(parsed_messages)

출력결과

[Message(author=Author(role=%3CRole.ASSISTANT: 'assistant'%3E, name=None), content=[TextContent(text="You are ChatGPT, a large language model trained by OpenAI.\nKnowledge cutoff: 2024-06\nCurrent date: 2025-08-21\n\nReasoning: low\n\n# Valid channels: analysis, commentary, final. Channel must be included for every message.\nCalls to these tools must go to the commentary channel: 'functions'.")], channel=None, recipient='<|start|>system', content_type=None), Message(author=Author(role=<Role.DEVELOPER: 'developer'>, name=None), content=[TextContent(text='# Instructions\n\nIf you don\'t know the answer just say that you don\'t know.\n\n# Tools\n\n## functions\n\nnamespace functions {\n\n// get current weather based on current location\ntype get_current_temperature = (_: {\n// The city and state, e.g. San Francisco, CA\nlocation: string,\nformat_t?: "celsius" | "fahrenheit", // default: celsius\n}) => any;\n\n// get current location based on user metadata\ntype get_current_location = (_: {\n// User\'s ID of current client session.\nuserid: string,\n// Max result length\nmax_len?: number, // default: 10\n}) => any;\n\n} // namespace functions')], channel=None, recipient=None, content_type=None), Message(author=Author(role=<Role.USER: 'user'>, name=None), content=[TextContent(text='안녕')], channel=None, recipient=None, content_type=None)]

대화 워크플로우 자동화 함수 작성

유저 입력과 대화 기록(user_message, conversation_history)를 입력받아 모델 최종 답변과 추가된 대화 기록(assistant_response, conversation_history)를 반환하는 함수를 작성한다.

실행 흐름은 다음과 같다.

대화 내역이 없으면 새 리스트 생성
마지막 대화 내역에 유저 입력 추가
대화내역 harmony 포맷으로 인코딩(conversation_harmony)
모델에 harmony 텍스트 입력 후 결과 반환
결과(response_harmony)를 list of Message 형태로 파싱해 for문 순회하며 차례로 대화내역에 저장. (중간 Message가 analysis channel인 경우 해당)
마지막 Message가 commentary channel인 경우 함수 이름과 인자를 받아 직접 함수 실행후 출력값 도출
- 시스템 프롬프트에 정의된 함수 명세와 유저 입력을 근거로 모델은 스스로 어떤 함수와 인자값이 필요한지 정할 수 있음
- 그러나, 모델이 함수를 스스로 실행하지는 못하므로 모델로부터 함수와 인자값을 받아 함수를 실행하는 코드가 반드시 필요함
함수 출력값을 포함한 메세지를 harmony 포맷으로 작성
대화내역 harmony + 결과 harmony + 함수 출력값 포함 메세지 harmony 를 다시 모델에 입력 및 함수 호출과 출력값까지 대화내역에 저장
10번에 도달할때까지 5~8번 반복
마지막 Message가 final channel인 경우 대화내역에 저장하고 유저에게 최종 입력값 제공

def get_response(user_message, conversation_history=None):
    if conversation_history is None:
        conversation_history = []
    
    # Add user message to history
    conversation_history.append({"role": "user", "content": user_message})
    
    # From system prompt and sonversations to Harmony format
    encoded = encode_conversations_with_harmony(
        conversation_history,
        reasoning_effort = reasoning_effort,
        add_generation_prompt = add_generation_prompt,
        tool_calls = tool_calls,
        developer_instructions = developer_instructions,
        model_identity = model_identity
    )
    conversation_harmony = encoded[0]
    # conversation_tokens = encoded[1]
    
    assistant_response = None
    
    #  Repeat until assistant final response is received
    while assistant_response is None:
        response = llm.create_completion(conversation_harmony, max_tokens=-1)
        
        response_harmony = response["choices"][0]["text"].strip()
        print("====== response harmony =======")
        print(response_harmony)
        
        try:
            # response_harmony = '%3C|start|%3Eassistant' + response_harmony
            tokens = harmony_encoding.encode(response_harmony, allowed_special=allowed_special)
            parsed_messages = harmony_encoding.parse_messages_from_completion_tokens(tokens, Role.ASSISTANT)
            print("======= parsed messages ======")
            print(parsed_messages)
        except:
            raise RuntimeError(f"Failed to handle conversation: {response_harmony}")
        
        for pm in parsed_messages:
            # Add assistant function call and result to history
            if pm.channel == "commentary":
                func = pm.recipient[10:].strip() # functions. -> 10chars
                args = json.loads(pm.content[0].text.strip())

                if func is not None and args is not None:
                    result = func_map[func](**args)  # run function
                    result_json = json.dumps(result)
                    
                    conversation_harmony = ''.join([
                        conversation_harmony,
                        response_harmony,
                        '<|call|>',
                        f'<|start|>functions.{func} to=assistant<|channel|>commentary<|message|>{result_json}<|end|><start>assistant'
                    ])
                    
                    conversation_history.append({"role": "assistant", "tool_calls": [{"name": func, "arguments": json.dumps(args)}]})
                    conversation_history.append({"role": "tool", "name": func, "content": result_json})

            # Add assistant thought to history
            elif pm.channel == "analysis":
                conversation_history.append({"role": "assistant", "content": pm.content[0].text, "thinking": ""})
                
            # Add assistant answer to history
            else: # pm.channel == "final"
                assistant_response = pm.content[0].text
                conversation_history.append({"role": "assistant", "content": assistant_response})
                
    return assistant_response, conversation_history

대화 시작

response, conversation_history = get_response(
    "유저 id가 john123인 사람의 현재 위치에 해당하는 곳의 현재 온도를 화씨로 알려줘. 그리고 그 온도라면 야외 활동하기에 어떤 상황인지도 대략적으로 설명해주고."
)
print(response)

중간출력

====== response harmony =======
<|channel|>analysis<|message|>Need to call get_current_location then get_current_temperature.<|end|><|start|>assistant<|channel|>commentary to=functions.get_current_location <|constrain|>json<|message|>{"userid":"john123","max_len":10}
======= parsed messages ======
[Message(author=Author(role=<Role.ASSISTANT: 'assistant'>, name=None), content=[TextContent(text='Need to call get_current_location then get_current_temperature.')], channel='analysis', recipient=None, content_type=None), Message(author=Author(role=<Role.ASSISTANT: 'assistant'>, name=None), content=[TextContent(text='{"userid":"john123","max_len":10}')], channel='commentary', recipient='functions.get_current_location', content_type='<|constrain|>json')]
====== response harmony =======
<|channel|>analysis<|message|>Now get temperature.<|end|><|start|>assistant<|channel|>commentary to=functions.get_current_temperature <|constrain|>json<|message|>{"location":"Korea, Rep","format_t":"fahrenheit"}
======= parsed messages ======
[Message(author=Author(role=<Role.ASSISTANT: 'assistant'>, name=None), content=[TextContent(text='Now get temperature.')], channel='analysis', recipient=None, content_type=None), Message(author=Author(role=<Role.ASSISTANT: 'assistant'>, name=None), content=[TextContent(text='{"location":"Korea, Rep","format_t":"fahrenheit"}')], channel='commentary', recipient='functions.get_current_temperature', content_type='<|constrain|>json')]
====== response harmony =======
<|channel|>final<|message|>현재 `john123`님의 위치는 **대한민국**이며, 해당 지역의 현재 기온은 **25 °F**(섭씨 약 -3.9 °C)입니다.  

**25 °F**는 상당히 추운 온도로, 실내에서 보온이 필요한 상황입니다.  

- **야외 활동**: 25 °F에서는 장갑, 두꺼운 코트, 모자, 목도리 등 방한 장비가 필수입니다.  
- **운동**: 조깅이나 자전거 타기 같은 유산소 운동은 몸이 차가워지기 쉽고, 근육이 경직될 수 있어 부상 위험이 높습니다.  
- **일상 생활**: 외출 시 충분히 따뜻하게 입고, 기온 차가 큰 지역이라면 실내에서 휴식을 취하는 것이 좋습니다.  

따라서, **야외 활동은 권장되지 않으며** 방한 준비가 충분히 된 뒤에야 짧은 시간 동안 밖에 나가야 할 필요가 있을 때 고려해 보시는 것이 좋습니다.
======= parsed messages ======
[Message(author=Author(role=<Role.ASSISTANT: 'assistant'>, name=None), content=[TextContent(text='현재 `john123`님의 위치는 **대한민국**이며, 해당 지역의 현재 기온은 **25\u202f°F**(섭씨 약\u202f-3.9\u202f°C)입니다.  \n\n**25\u202f°F**는 상당히 추운 온도로, 실내에서 보온이 필요한 상황입니다.  \n\n- **야외 활동**: 25\u202f°F에서는 장갑, 두꺼운 코트, 모자, 목도리 등 방한 장비가 필수입니다.  \n- **운동**: 조깅이나 자전거 타기 같은 유산소 운동은 몸이 차가워지기 쉽고, 근육이 경직될 수 있어 부상 위험이 높습니다.  \n- **일상 생활**: 외출 시 충분히 따뜻하게 입고, 기온 차가 큰 지역이라면 실내에서 휴식을 취하는 것이 좋습니다.  \n\n따라서, **야외 활동은 권장되지 않으며** 방한 준비가 충분히 된 뒤에야 짧은 시간 동안 밖에 나가야 할 필요가 있을 때 고려해 보시는 것이 좋습니다.')], channel='final', recipient=None, content_type=None)]

대화 워크플로우는 다음과 같이 흘러간다.

user 입력에 대해 assistant가 analysis 채널에서 무엇을 해야하는지 스스로 생각 후 위치 구하는 함수가 필요하다는 것을 알아낸다.
assistant가 전체 입력값을 근거로 함수명과 인자(get_current_location({“userid”: “john123”, “max_len”: 10}))를 정해 모델 외부에 제공한다. 1, 2번은 모델 내에서 연속적으로 이루어진다.
모델 외부의 함수 실행기에서 함수명과 인자를 받아 실행 후 출력값({“location”: “Korea, Rep”})을 다시 모델에 제공한다.
함수 실행기로부터 받은 출력값을 근거로 모델은 다시 analysis 채널에서 다음 행동을 생각한다. 이번엔 온도 구하는 함수가 필요하다는 것을 알아낸다.
assistant가 전체 입력값을 근거로 함수명과 인자(get_current_temperature({“location”: “Korea, Rep”, “format_t”: “fahrenheit”}))를 정해 모델 외부에 제공한다. 4, 5번은 모델 내에서 연속적으로 이루어진다.
모델 외부의 함수 실행기에서 함수명과 인자를 받아 실행 후 출력값({“temperature”: 25})을 다시 모델에 제공한다.
함수 실행기로부터 받은 출력값을 근거로 모델은 final 채널에서 user에게 제공할 최종 답변을 생성한다.

최종출력

현재 `john123`님의 위치는 **대한민국**이며, 해당 지역의 현재 기온은 **25 °F**(섭씨 약 -3.9 °C)입니다.  

**25 °F**는 상당히 추운 온도로, 실내에서 보온이 필요한 상황입니다.  

- **야외 활동**: 25 °F에서는 장갑, 두꺼운 코트, 모자, 목도리 등 방한 장비가 필수입니다.  
- **운동**: 조깅이나 자전거 타기 같은 유산소 운동은 몸이 차가워지기 쉽고, 근육이 경직될 수 있어 부상 위험이 높습니다.  
- **일상 생활**: 외출 시 충분히 따뜻하게 입고, 기온 차가 큰 지역이라면 실내에서 휴식을 취하는 것이 좋습니다.  

따라서, **야외 활동은 권장되지 않으며** 방한 준비가 충분히 된 뒤에야 짧은 시간 동안 밖에 나가야 할 필요가 있을 때 고려해 보시는 것이 좋습니다.

이전 대화를 기억한 상태로 두번째 대화를 시작하려면 conversation_history를 같이 제공하면 된다.

response, conversation_history = get_response(
    "그렇다면 유저 id가 jay_lee인 사람은?",
    conversation_history=conversation_history
)
print(response)

최종결과

현재 `jay_lee`님의 위치는 **대한민국**이며, 해당 지역의 현재 기온은 **25 °F**(섭씨 약 -3.9 °C)입니다.  

**25 °F**는 매우 추운 온도이므로 야외 활동은 권장되지 않습니다. 방한 장비(두꺼운 코트, 모자, 장갑, 목도리 등)를 충분히 착용하고, 필요하다면 짧은 시간 동안 밖에 나가더라도 몸을 따뜻하게 유지하는 것이 중요합니다.

두 번의 연속된 대화에서 conversation_history는 다음과 같이 저장되었다. 이는 unsloth 인코더에 입력되는 포맷으로 harmony 렌더러를 사용할때보다 훨씬 간편한 형태인 것을 볼 수 있다.

# conversation_history
[{'role': 'user',
  'content': '유저 id가 john123인 사람의 현재 위치에 해당하는 곳의 현재 온도를 화씨로 알려줘. 그리고 그 온도라면 야외 활동하기에 어떤 상황인지도 대략적으로 설명해주고.'}, # user
 {'role': 'assistant',
  'content': 'Need to call get_current_location then get_current_temperature.',
  'thinking': ''}, # assistant analysis
 {'role': 'assistant',
  'tool_calls': [{'name': 'get_current_location',
    'arguments': '{"userid": "john123", "max_len": 10}'}]}, # assistant commentary (function call)
 {'role': 'tool',
  'name': 'get_current_location',
  'content': '{"location": "Korea, Rep"}'}, # function result to assistant commentary
 {'role': 'assistant', 'content': 'Now get temperature.', 'thinking': ''}, # assistant analysis
 {'role': 'assistant',
  'tool_calls': [{'name': 'get_current_temperature',
    'arguments': '{"location": "Korea, Rep", "format_t": "fahrenheit"}'}]}, # assistant commentary (function call)
 {'role': 'tool',
  'name': 'get_current_temperature',
  'content': '{"temperature": 25}'}, # function result to assistant commentary
 {'role': 'assistant',
  'content': '현재 `john123`님의 위치는 **대한민국**이며, 해당 지역의 현재 기온은 **25\u202f°F**(섭씨 약\u202f-3.9\u202f°C)입니다.  \n\n**25\u202f°F**는 상당히 추운 온도로, 실내에서 보온이 필요한 상황입니다.  \n\n- **야외 활동**: 25\u202f°F에서는 장갑, 두꺼운 코트, 모자, 목도리 등 방한 장비가 필수입니다.  \n- **운동**: 조깅이나 자전거 타기 같은 유산소 운동은 몸이 차가워지기 쉽고, 근육이 경직될 수 있어 부상 위험이 높습니다.  \n- **일상 생활**: 외출 시 충분히 따뜻하게 입고, 기온 차가 큰 지역이라면 실내에서 휴식을 취하는 것이 좋습니다.  \n\n따라서, **야외 활동은 권장되지 않으며** 방한 준비가 충분히 된 뒤에야 짧은 시간 동안 밖에 나가야 할 필요가 있을 때 고려해 보시는 것이 좋습니다.'}, # assistant final
 {'role': 'user', 'content': '그렇다면 유저 id가 jay_lee인 사람은?'}, # user
 {'role': 'assistant', 'content': 'Need location then temp.', 'thinking': ''}, # assistant analysis
 {'role': 'assistant',
  'tool_calls': [{'name': 'get_current_location',
    'arguments': '{"userid": "jay_lee", "max_len": 10}'}]}, # assistant commentary 
 {'role': 'tool',
  'name': 'get_current_location',
  'content': '{"location": "Korea, Rep"}'}, # function result to assistant commentary
 {'role': 'assistant',
  'tool_calls': [{'name': 'get_current_temperature',
    'arguments': '{"location": "Korea, Rep", "format_t": "fahrenheit"}'}]}, # assistant commentary, 첫번째 대화와 다르게 analysis를 거치지 않고 바로 function call을 한다.
 {'role': 'tool',
  'name': 'get_current_temperature',
  'content': '{"temperature": 25}'}, # function result to assistant commentary
 {'role': 'assistant',
  'content': '현재 `jay_lee`님의 위치는 **대한민국**이며, 해당 지역의 현재 기온은 **25\u202f°F**(섭씨 약\u202f-3.9\u202f°C)입니다.  \n\n**25\u202f°F**는 매우 추운 온도이므로 야외 활동은 권장되지 않습니다. 방한 장비(두꺼운 코트, 모자, 장갑, 목도리 등)를 충분히 착용하고, 필요하다면 짧은 시간 동안 밖에 나가더라도 몸을 따뜻하게 유지하는 것이 중요합니다.'}] # assistant final

4-3. troubleshooting

harmony encoding 파싱 오류

harmony 문서에서 parse_messages_from_completion_tokens함수가 제대로 동작하지 않을 때를 대비해 예외처리를 권장하고 있다.

The bindings raise plain Python exceptions. The most common ones are:

RuntimeError – returned for rendering or parsing failures (for example if a token sequence is malformed or decoding fails).
ValueError – raised when an argument is invalid, e.g. an unknown Role is provided to load_harmony_encoding or StreamableParser.
ModuleNotFoundError – accessing the package without building the compiled extension results in this error.

In typical code you would wrap encoding operations in a try/except block:

try:
    tokens = enc.render_conversation_for_completion(convo, Role.ASSISTANT)
    parsed = enc.parse_messages_from_completion_tokens(tokens, Role.ASSISTANT)
except RuntimeError as err:
    print(f"Failed to handle conversation: {err}")

가장 중요한 RuntimeError의 경우 시작 토큰이 없거나 종료 토큰이 없는 경우, 시작 토큰 뒤에 role이 아닌 channel이 오는 경우 등등 harmony 형식에서 어긋난 토큰 순서를 만나면 발생한다.

만약 모델에서 생성된 결과가 harmony 포맷에서 어긋난다면, 앞부분에서도 강조했듯이 가장 먼저 모델 입력값에 <|start|>assistant를 붙이고 모델에 입력했는지를 꼭 확인해봐야 한다. 만약 붙이지 않고 입력한다면 다음과 같이 시작 토큰 뒤에 채널명이 생성되어버리는 대참사가 종종 발생한다.

# malformed harmony example
<|start|>analysis<|message|>Need to call get_current_location then get_current_temperature.<|end|>

llama.cpp에서 stop token을 제공하지 않는 문제

스페셜 토큰 중 두 개의 stop token이 있는데, <|call|>과 <|return|>이다. 문제는 llama 모델의 create_completion 함수 실행후 나오는 결과 값에 제공되는 생성 종료 사유에 둘 중 어떤 토큰으로 종료되었는지를 알려주지 않고 해당 stop token을 제거한채로 결과를 줘버린다.

따라서 위에 작성된 get_response 함수 내부에서 function call의 결과를 다시 모델에 제공할 때 강제로 <|call|> 토큰을 올바른 위치에 붙여주는 것만 신경쓰면 된다.

conversation_harmony = ''.join([
                        conversation_harmony,
                        response_harmony,
                        '<|call|>', # 삭제된 stop token 강제로 추가
                        f'<|start|>functions.{func} to=assistant<|channel|>commentary<|message|>{result_json}<|end|><start>assistant'])

harmony 문서에는 다음과 같이 언급되어있다.

Implementation note: <|return|> is a decode-time stop token only. When you add the assistant’s generated reply to conversation history for the next turn, replace the trailing <|return|> with <|end|> so that stored messages are fully formed as <|start|>{header}<|message|>{content}<|end|>. Prior messages in prompts should therefore end with <|end|>. For supervised targets/training examples, ending with <|return|> is appropriate; for persisted history, normalize to <|end|>.

5. 총평

gguf포맷으로 cpu에서 충분히 실행할 수는 있으나 실시간성으로 쓰기엔 많이 느리다. (한번 생성에 분 단위 소요)
unsloth에서 harmony 렌더러 wrapping해서 제공해준 함수가 기대이상으로 쓰기 간편하다
harmony 포맷이 구조화가 잘 되어있어 모델이 토큰을 생성하는 순서를 체계적으로 이해할 수 있고 모델 외부와 높은 확률로 오류 없이 결과를 주고받을 수 있는 점이 맘에 든다
moe 레이어만 cpu에서 실행하고 나머지는 gpu에서 실행할 수 있다는데 (llama –cpu-moe 옵션) 한번 쓸만한지 테스트해보면 좋을듯

출처

AWS Bedrock Tutorial - 음성파일로부터 자막과 이미지 생성하기(2)

Sun, 22 Sep 2024 00:00:00 +0000

이어서

음성파일을 S3 버킷에 업로드한 지난 게시글에 이어 음성 파일이 업로드 되는 순간 자막을 생성하고, 자막과 연관된 이미지를 생성하는 과정이 자동화 될 수 있도록 필요한 과정을 마저 진행한다.

0. 주의점

모든 서비스의 리전은 전부 같은 리전이어야 한다. 이 글에선 미국 동부(us-east-1)으로 진행한다.
S3 버킷에 파일 생성을 트리거로 입력 파일을 받아 출력 파일을 생성하고, 그 출력 파일을 같은 버킷에 넣으면 안된다!!! 입력파일생성 - 트리거 - 출력파일생성(=입력파일생성) - 트리거 - 출력파일생성(=입력파일생성) - … 의 무한루프에 빠져 무한히 파일이 생성되며 요금 폭탄이 나올 수 있다. 따라서 반드시 입력파일이 생성되는 버킷과 출력파일이 생성되는 버킷은 구분해주어야 한다.

1. S3 버킷 생성

지난 게시글을 참고해 자막 파일을 업로드할 버킷 1개와 이미지 파일을 업로드할 버킷 1개를 각각 생성한다.

버킷 이름은 전 세계에서 중복되지 않는 이름이어야 하며, 본인이 구분하기 좋은 이름으로 설정하면 된다.

여기선 my-toy-bucket-upload-transcription-jay, my-toy-bucket-upload-image-jay로 각각 생성하고 진행한다.

2. Transcribe를 실행하는 Lambda 함수 생성

Lambda 서비스로 이동해 ‘함수 생성’을 누른다.

함수 이름을 입력하고, 런타임 언어로 파이썬을 선택한다. ‘함수 생성’을 누르면 기본 생성 역할과 함께 Lambda 함수가 생성된다.

구성 - 일반 구성 - ‘편집’을 선택한다.

제한시간을 30초로 변경한다. Transcribe 모델 실행시간이 수십초 걸릴 수 있기 때문에 넉넉히 변경한다. ‘저장’을 누른다.

from botocore.exceptions import ClientError
from datetime import date, datetime

import json
import boto3
import logging


logger = logging.getLogger()
logger.setLevel("INFO")

def json_serial(obj):
    """JSON serializer for objects not serializable by default json code"""

    if isinstance(obj, (datetime, date)):
        return obj.isoformat()
    raise TypeError ("Type %s not serializable" % type(obj))
    
def lambda_handler(event, context):
    # TODO implement
    bucket_name = event['Records'][0]['s3']['bucket']['name']
    key = event['Records'][0]['s3']['object']['key']
    
    transcribe_client = boto3.client("transcribe")
    job_name = 'my_transciption_job_{}_{}'.format(datetime.now().strftime('%Y%m%d_%H%M%S'), key)
    
    try:
        job_args = {
            "TranscriptionJobName": job_name,
            "Media": {"MediaFileUri": 's3://{}/{}'.format(bucket_name, key)},
            "MediaFormat": 'mp3',
            "LanguageCode": 'en-US',
            ##########################################
            "OutputBucketName": Bucket-name-to-upload,
            ##########################################
            "OutputKey": 'my_transcription_{}.json'.format(key.split('.')[0].split('_')[-1]),
            "Settings":{
                'ShowSpeakerLabels': True,
                'MaxSpeakerLabels': 2
            }
        }
        response = transcribe_client.start_transcription_job(**job_args)
        response = json.dumps(response, default=json_serial)
        logger.info("Started transcription job %s.", job_name)
    except ClientError:
        logger.exception("Couldn't start transcription job %s.", job_name)
        raise
    else:
        return response
        
    logger.info("job done")
    logger.info(json.loads(response))

코드 창에 위의 함수를 붙여넣는다. Bucket-name-to-upload에는 앞에서 생성한 자막 파일 업로드용 버킷의 이름을 넣는다.

위로 가 ‘트리거 추가’를 누른다.

소스 선택에서 ‘S3’를 선택한다.

이후 버킷 선택에서 음성 파일이 업로드된 버킷을 선택하고, 이벤트 유형에는 다른 유형은 다 삭제하고 PUT만 추가한다. 트리거가 발생할 파일명의 조건으로는 접두사로 my_audio, 접미사로 .mp3를 입력해 다른 유형의 파일이 생성되었을 때 필요 없는 함수 호출이 없도록 방지한다. 마지막으로 재귀 호출에 체크하고 ‘추가’를 누른다.

구성 - 권한 - 역할 이름 링크를 클릭해 IAM 서비스로 이동한다.

권한 추가의 ‘인라인 정책 생성’을 클릭한다.

검색창에 getObject를 입력 후 체크박스 선택. 리소스 항목에선 특정을 선택 후 ‘ARN 추가’를 누른다.

음성 파일이 업로드 된 버킷명을 bucket name에 입력하고, 음성 파일명의 접두사를 object name에 입력 후 ‘ARN 추가’를 누른다.

하단의 ‘권한 더 추가’를 눌러 PutObject 권한도 추가해줄 것이다.

위에서 GetObject와 동일하게 PutObject도 추가해주고, ARN은 이번엔 자막파일을 업로드 할 버킷의 이름과 접두사를 입력한다. 또한 자막파일 생성시 temp파일도 생성되므로 ARN을 하나 더 추가한다. 다 됐으면 다음을 누른다.

적당한 정책 이름 입력 후 ‘정책 생성’을 클릭한다.

정책 하나를 더 연결해야 한다. 이번엔 기본적으로 있는 정책을 가져온다. 권한 추가의 ‘정책 연결’을 누른다.

transcribe를 검색해 AmazonTranscribeFullAccess 정책의 체크박스를 클릭한다. 사실 이 정책도 세부적으로 선택할 수 있겠지만 잘 모르는 부분이기도 하고 토이프로젝트니 FullAccess 정책으로 선택한다.

다시 Lambda 함수로 돌아와 Deploy로 함수를 배포한다.

Test 버튼을 눌러 새 테스트를 생성 후 한번 실행시켜 CloudWatch에 로그가 기록되도록 한다. 테스트는 실패해도 상관없으니 아무렇게나 생성하고 실행하면 된다.

Postman에서 테스트로 음성 파일 업로드 시, 자막파일까지 순차적으로 생성된다면 성공이다.

자막 파일은 위와 같이 JSON 파일 형식으로 생성된다. “I’m starving. Let’s grab a bite to eat.” 이 두 문장을 후에 이미지 생성 모델의 프롬프트로 입력할 것이다.

3. Bedrock을 실행하는 Lambda 함수 생성

베드락 서비스에 접속해 좌측 하단의 ‘모델 엑세스’를 클릭한다.

‘Modify model access’를 클릭한다.

사용하고자 하는 모델에 체크박스를 선택하면 되는데, 여기선 Amazon - Titan Image Generator G1을 사용할 것이다.

사실 해당 모델은 기본 사용이 가능하므로 아마 체크가 안될 것이다. 만약 다른 모델을 써보고 싶다면 추가로 체크한다. (다만 이 글에서 다른 모델들의 파라미터 작성법까지 소개되진 않는다.)

Next - Summit 순으로 클릭해 완료한다.

다시 Lambda 서비스로 돌아와, Bedrock과 관련된 이름으로 새 함수를 생성한다.

이후 과정은 앞서 Transcribe Lambda 함수 작성 과정과 거의 동일하기 때문에, 차이점 위주로만 설명한다.

- lambda_handler 코드

import json
import logging
import boto3
from botocore.exceptions import ClientError
import base64


# This creates a logger instance
logger = logging.getLogger()
logger.setLevel(logging.INFO)

# This initializes the clients Bedrock Runtime and S3
bedrock_runtime_client = boto3.client('bedrock-runtime', region_name='us-east-1')
s3 = boto3.client('s3')

def lambda_handler(event, context):
    # We need to extract 'text' and 'seed' from the event, provide defaults if not present
    bucket_name = event['Records'][0]['s3']['bucket']['name']
    key = event['Records'][0]['s3']['object']['key']

    s3_resource = boto3.resource('s3')
    
    content_object = s3_resource.Object(bucket_name, key)
    file_content = content_object.get()['Body'].read().decode('utf-8')
    json_content = json.loads(file_content)
    
    prompt = json_content["results"]["transcripts"][0]["transcript"]
    prompt = '. '.join(prompt.split('. ')[1:3]) + '.'
    logger.info(prompt)
    
    ##########################################
    upload_bucket_name = Bucket-name-to-upload
    ##########################################
    
    try:
        base64_image_data = invoke_titan_image(prompt)
        
        # The image data is a base64-encoded string, so we need to decode it to get the actual image data
        image_data = base64.b64decode(base64_image_data)
        object_key = "my_image_{}.jpg".format(key.split('.')[0].split('_')[-1])

        # Now we upload the image data to S3
        s3.put_object(
            Bucket=upload_bucket_name,
            Key=object_key,
            Body=image_data,
            ContentType='image/jpeg'  # This is adjustable!
        )
        logger.info("Uploaded image to s3://{}/{}".format(upload_bucket_name, object_key))

        return {
            'statusCode': 200,
            'body': json.dumps({'message': "Image uploaded successfully to {}/{}.".format(upload_bucket_name, object_key)})
        }

    except Exception as e:
        logger.error("Error: %s", str(e))
        return {
            'statusCode': 500,
            'body': json.dumps({'error': 'Failed to invoke model or upload image', 'detail': str(e)})
        }

def invoke_titan_image(prompt):
    try:
        request = json.dumps({
            "taskType": "TEXT_IMAGE",
            "textToImageParams": {"text": prompt},
            "imageGenerationConfig": {
                "numberOfImages": 1,
                "quality": "standard",
                "cfgScale": 8.0,
                "height": 640, # Permissible sizes: https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-titan-image.html#:~:text=The%20following%20sizes%20are%20permissible.
                "width": 1408
            },
        })

        response = bedrock_runtime_client.invoke_model(
            modelId="amazon.titan-image-generator-v1", body=request
        )

        response_body = json.loads(response["body"].read())
        base64_image_data = response_body["images"][0]

        return base64_image_data

    except ClientError as e:
        logger.error("Couldn't invoke Titan Image generator: {}".format(e))
        raise    

- 트리거

자막 파일이 업로드되는 버킷과 자막파일에 맞는 접두사, 접미사로 변경

- 실행 시간

동일하게 30초 이상으로 넉넉하게 설정

- 정책 설정

ARN 설정 없이 ListBucket 추가

ARN은 자막 파일이 업로드되는 버킷에 맞게 설정하고, GetObject 추가

ARN은 이미지 파일이 업로드되는 버킷에 맞게 설정하고, PutObject 추가

AmazonBedrockFullAccess 권한 추가

마찬가지로 Deploy 후 테스트 한번 실행해 CloudWatch 로그 그룹을 생성해준다. (테스트 실패해도 상관없음)

4. 테스트

Postman으로 테스트 해보자.

생성한 이미지 파일이 정상적으로 버킷에 존재하면 성공!

입력파일로 음식과 관련된 영어 대화 음성 파일을 사용했더니 결과물은 건초를 먹는 염소(?)가 나왔다.

구현에 집중한 토이 프로젝트라 결과물이 조금 재미 없는데, 여기에 프롬프트 엔지니어링을 잘 하고 좋은 입력 소스를 구한다면 재미있는 결과가 나올것 같다.

끝!

출처

AWS Bedrock Tutorial - 음성파일로부터 자막과 이미지 생성하기(1)

Sun, 22 Sep 2024 00:00:00 +0000

AWS Bedrock 활용한 토이 프로젝트 제작

음성 파일을 업로드해 자막을 생성하고, 그 자막과 연관된 이미지를 생성하는 프로세스를 자동화하는 AWS Bedrock 토이 프로젝트의 튜토리얼이다.

사용된 AWS 서비스는 다음과 같다.

IAM : 역할과 정책 관리
API Gateway : 각종 API 생성 및 관리
S3 : 파일 저장소
Lambda : 서버리스 컴퓨팅
Transcribe : 음성 파일 텍스트 변환 모델
Bedrock : 생성형 AI 모델 사용

1편에선 음성파일을 S3버킷에 업로드하는 부분까지 설명한다.

0. 주의점

모든 서비스의 리전은 전부 같은 리전이어야 한다. 이 글에선 미국 동부(us-east-1)으로 진행한다.
S3 버킷에 파일 생성을 트리거로 입력 파일을 받아 출력 파일을 생성하고, 그 출력 파일을 같은 버킷에 넣으면 안된다!!! 입력파일생성 - 트리거 - 출력파일생성(=입력파일생성) - 트리거 - 출력파일생성(=입력파일생성) - … 의 무한루프에 빠져 무한히 파일이 생성되며 요금 폭탄이 나올 수 있다. 따라서 반드시 입력파일이 생성되는 버킷과 출력파일이 생성되는 버킷은 구분해주어야 한다.

1. IAM 역할 생성

모든 프로세스에 대해 IAM에서 총 3개의 역할이 필요하다.

S3에 음성 파일을 업로드 하는 역할
업로드된 음성 파일로부터 자막을 생성하는 역할
생성된 자막 파일로부터 이미지파일을 생성하는 역할

그리고 각 역할에는 다음과 같은 권한들이 필요하다.

음성파일 업로드
1. API Gateway 기본 권한 (CloudWatch에 로그 생성)
2. 음성파일이 업로드될 S3 버킷의 쓰기 권한
자막 생성
1. Lambda 기본 권한 (CloudWatch에 로그 생성)
2. 음성파일이 업로드된 S3 버킷의 읽기 권한
3. 자막파일이 업로드될 S3 버킷의 쓰기 권한
4. Transcribe 사용 권한
이미지 생성
1. Lambda 기본 권한 (CloudWatch에 로그 생성)
2. 자막파일이 업로드된 S3 버킷의 읽기 권한
3. 이미지파일이 업로드될 S3 버킷의 쓰기 권한
4. Bedrock 사용 권한

각 서비스들을 하나씩 생성할때마다 기본적으로 역할을 생성할 수 있기 때문에, 기본 생성된 역할에 나열된 권한을 추가해주면 된다. 단, API Gateway의 메서드는 미리 역할을 만들어놔야 하기 때문에, 역할 하나를 미리 만들고 진행한다.

역할 탭에서 ‘역할 생성’ 버튼을 클릭한다.

신뢰할 수 있는 엔티티 유형에서 AWS 서비스를 선택 후, 아래 서비스 또는 사용 사례 목록에서 API Gateway를 선택하고 ‘다음’을 누른다.

권한 추가 탭에선 따로 선택하지 말고 ‘다음’으로 넘어간다.

적당히 구분하기 좋은 이름을 입력 후, 밑으로 쭉 내려 ‘역할 생성’을 누른다.

방금 생성한 오디오 업로드 역할에 대해, 추가 정책(권한)을 부여해야 한다. 정책 탭으로 가 ‘정책 생성’을 누른다.

서비스에서 ‘S3’를 선택한다.

권한 지정에서 작업 검색창에 PutObject를 검색 후, 밑에 나오는 리스트 중 ‘PutObject’에 체크한다.

밑으로 가 리소스 항목에서 ‘특정’을 선택하고, ‘ARN 추가’를 클릭한다.

Resource bucket name에는 앞으로 만들 오디오 파일 업로드용 버킷 이름을 입력한다.

Resource object name에는 앞으로 업로드할 오디오 파일 이름을 입력한다.

ARN은 Amazon Resource Name의 약자로, 사진과 같이 입력하게 된다면 지금 설정하는 PutObjet 정책은 위의 ARN에 대해서만 유효하다.

즉, 아무 버킷에 아무 파일명으로 PutObject 할 수 있는게 아닌, my-toy-bucket-upload-audio-jay 버킷에만 my_audio로 시작하는 파일명으로 제한적인 업로드가 가능한 것이다.

다 입력했으면 ‘ARN 추가’를 누른다.

ARN이 정상적으로 추가되었다면 ‘다음’을 누른다.

적당히 구분하기 쉬운 정책 이름을 입력하고, 밑으로 가 ‘정책 생성’을 누른다.

정책 생성이 완료되었다면, 다시 역할 탭으로 가 앞에서 생성했던 S3 업로드용 역할을 클릭한다.

‘권한 추가’ - ‘정책 연결’을 클릭한다.

검색창에 방금 생성한 S3 putObject 정책을 검색 후, 체크박스를 선택하고 ‘권한 추가’를 누른다.

최종적으로 S3 업로드 역할엔, 다음과 같이 CloudWatch 로그 권한과 putObject 권한이 생기게 된다.

2. API Gateway 생성

API 서비스에 접속 후, API 탭으로 이동해 ‘API 생성’버튼을 누른다.

REST API에서 ‘구축’을 누른다.

적당한 API이름을 입력하고 ‘생성’을 누른다.

방금 생성한 API 하위 항목의 리소스 탭에서 ‘/’가 선택된 상태로 리소스 생성 버튼을 누른다.

리소스 경로에 ‘/’가 선택되어있는지 확인하고, 리소스 이름에 {folder}를 입력 후 리소스 생성 버튼을 누른다.

이번엔 ‘/{folder}’가 선택된 상태로 리소스 생성 버튼을 누른다.

리소스 경로에 ‘/{fodler}/’가 선택되어있는지 확인하고, 리소스 이름에 {object}를 입력 후 리소스 생성 버튼을 누른다.

리소스 경로에 ‘/{object}/’가 선택되어있는지 확인하고, 메서드 생성을 클릭한다.

메서드 유형: PUT, 통합 유형: AWS 서비스, AWS 리전: us-east-1, AWS 서비스: S3, HTTP 메서드: PUT을 각각 선택한다.

경로 재정의에 {bucket}/{key}를 입력하고, 실행 역할에 아까 생성한 역할의 ARN을 복사해 붙여넣는다. 콘텐츠 처리는 패스스루를 선택하고 ‘다음’을 누른다. 여기서 아까 생성한 역할의 ARN은 IAM 서비스로 돌아가 위와 같은 위치에서 확인 및 복사를 할 수 있다.

다시 API Gateway 리소스로 돌아와, PUT 메서드가 선택된 상태에서 통합 요청 탭의 ‘편집’을 누른다.

하단에서 ‘경로 파라미터 추가’를 누른다. 총 두번 눌러 두개를 추가한다.

위 입력칸의 이름에 bucket, 다음에서 매핑됨에 method.request.path.folder를 입력한다.

아래 입력칸의 이름에 key, 다음에서 매핑됨에 method.request.path.object를 입력하고 ‘저장’을 누른다.

API 설정 탭으로 가 이진 미디어 유형 항목의 ‘미디어 유형 관리’를 클릭한다.

이진 미디어 유형 추가 클릭 후, */*를 입력 후 ‘변경 사항 저장’을 누른다. (모든 이진 미디어 유형을 허용하겠다는 의미)

다시 API의 리소스 창으로 가 ‘API 배포’를 누른다.

*새 스테이지*를 선택하고, 스테이지 이름에 ‘v1’을 입력한다. ‘배포’를 누른다.

API 배포가 완료되었다.

3. S3 버킷 생성

S3 서비스로 이동해 버킷 만들기를 클릭한다.

앞에서 S3 업로드 정책에서 사용했던 ARN과 동일하게 S3 버킷을 만들어야 한다. 버킷 이름은 전 세계 모든 버킷에 대해 이름이 중복되면 안되므로, 만약 입력한 버킷명이 중복되었다면 변경 후 IAM 정책도 수정하도록 하자. 다른 설정들은 기본으로 두고 밑으로 쭉 내려 ‘버킷 만들기’를 완료한다.

4. 테스트

Postman 앱과 같은 API 테스트 툴을 다운로드 받는다. 다른 툴이 익숙하다면 그대로 사용해도 된다.

또한 링크에서 테스트용 샘플 mp3파일 모음을 다운받아 압축을 해제한다.

API Gateway 스테이지 탭으로 가 앞서 생성한 API의 URL을 복사한다.

Postman 앱에 URL을 복사한다.

메서드 종류는 PUT, URL은 복사한 텍스트 뒤에 ‘/업로드할 버킷명/업로드할 파일명’을 추가한다. 파일명은 앞서 정책에서 ARN 지정했던대로 my_audio로 시작해야 한다. 여기선 my_audio_1.mp3로 입력하자.

Body 탭에선 입력 음성파일을 업로드할 수 있는데, 파일 타입은 ‘binary’(이진 타입)를 선택하고, 앞서 다운로드 받았던 음성 파일 샘플 중 하나를 선택한다.

마지막으로 Send를 눌러 아래에 정상 응답(특별한 에러메세지가 없으며, 200 OK)이 도착했는지 확인한다.

생성한 파일이 정상적으로 버킷에 존재하는지 확인해보자. 정상적으로 음성 파일이 버킷에 업로드 된 것을 확인할 수 있다.

남은 부분들은 다음 게시글로 이어진다.

출처

Obsidian github 동기화 세팅하기(iOS 자동화, 단축어 활용)

Sun, 15 Oct 2023 00:00:00 +0000

이 글은 Joshua Kim 님의 옵시디언 사용해 보실래요? - 동기화, 백업 환경 구축의 내용을 참고해 작성되었습니다.

옵시디언 입문

메모 습관과 시스템을 바꿔보고자 obsidian에 입문했다. 여러 기기에 설치하고 동기화 세팅을 하려 했지만, 공식 동기화 플러그인 obsidian sync는 구독형 요금제이며 너무 비싸다는 단점이 있었다. 메모앱 하나에 일년에 10만원을 태워?

현재 내가 사용하는 기기는 windows pc, mac, iphone, ipad 총 네대로, 서로 다른 플랫폼에서의 동기화 방법을 고민하다가 Joshua Kim 님의 글을 참고해 github를 사용한 동기화 세팅을 진행했다. 여기에 약간의 추가 세팅과 아이폰 자동화, 단축어 등을 사용해 조금 더 편하게 사용할 수 있게 만든 방법을 공유하고자 한다.

1. 깃헙에 원격 repository 만들기

깃헙의 Repositories 탭에서 New 버튼으로 새 원격 저장소를 생성한다.

저장소 이름 입력, 공개/비공개 설정, Create repository 클릭

2. PC에 git client 활용해 원격 저장소 내려받기

원격 저장소에서 로컬 기기로 원격 저장소를 내려받고 연결해야한다. 이 글에선 Mac을 기준으로 설명하지만, 리눅스와 윈도우즈에서도 크게 차이나는 점은 없다.

혹시라도 git client를 어떻게 사용하는지 모른다면 이 글을 참고하자.

먼저, 아래 명령어를 사용해 로컬 기기로 원격 저장소를 내려받는다.

git clone https://github.com/{본인 계정 이름}/{저장소 이름}

# 예시
git clone https://github.com/Clarit7/obsidian-sync.git

만약 private로 설정한 저장소의 경우엔 아래 명령어를 사용한다.

git clone https://{본인 계정 이름}@github.com/{본인 계정 이름}/{저장소 이름}

# 예시
git clone https://[email protected]/Clarit7/obsidian-sync.git

해당 폴더 내에 .gitignore 파일을 생성한다.

vim .gitignore 명령어로 생성해도 좋고, 다른 텍스트 편집기가 있다면 써도 좋다.

.gitignore파일의 내용은 다음과 같이 작성한다.

.DS_Store
.obsidian/

.DS_Store는 맥에서 파인더를 사용할 때 생성되는 metadata이며, .obsidian폴더는 obsidiana의 설정값 등이 저장되는 폴더이다. 만약 .obsidian폴더를 ignore처리하지 않을 경우 여러 기기에서 pull, push를 진행하며 설정값 때문에 conflict가 날 확률이 크기 때문에 꼭 위와 같이 작성하는 것을 추천한다.

.gitignore 작성이 완료되었으면, 최초 1회는 upstream branch 설정을 위해 수동으로 push하는 것을 추천한다.

git commit -m "커밋메세지"
git push --set-upstream origin main

만약 옛날에 만들어 놓은 저장소를 사용한다면 branch명이 master일 수도 있는데, 깃헙은 노예제를 연상시킨다는 이유로 더이상 master라는 브랜치명을 사용하지 않는다.

혹시라도 이후 과정에서 옵시디언에서 원격 저장소에 연결되지 못하는 에러가 계속 발생한다면, 원격 저장소 연결을 삭제 후 다시 연결해보자.

git remote remove origin
git remote add origin https://github.com/{본인 계정 이름}/{저장소 이름} # public
git remote add origin https://{본인 계정 이름}@github.com/{본인 계정 이름}/{저장소 이름} # private

3. 맥, 윈도우, 리눅스에서 Obsidian Git 플러그인을 활용한 동기화 세팅

Obsidian을 실행한다. 만약 이미 다른 vault가 열려있다면 왼쪽 아래의 open another vault 버튼으로 vault 탐색기를 연다.

Open folder as vault 로 아까 로컬 저장소에 클론한 폴더를 연다.

설정 - Community plugins - Turn on community plugins

Community plugins가 활성화되면 Browse 버튼을 클릭한다.

Obsidian Git을 검색하고, 해당 플러그인을 선택해 설치한다.

Obsidian Git을 활성화시킨다.

메인화면으로 돌아와 command 창을 연다. 이후 git을 검색해 Switch branch를 클릭한다.

main 브랜치를 클릭한다.

이후 command 창을 열어 수동으로 commit과 push를 진행해도 좋고, 주기적으로 commit & push와 pull을 진행하도록 설정해도 좋다.

아래는 push, pull을 주기적으로 진행하도록 설정하는 방법이다. 원하는 push와 pull 간격을 분 단위로 입력한다.

Pull updates on startup 옵션도 키는 것을 추천한다.

테스트 파일을 만들어 실제 자동 동기화가 잘 이루어지는지 확인해보았다.

4. iOS, iPadOS 에서 Working Copy 활용한 동기화 세팅

모바일에선 Obsidian Git이 설치만 되고 작동하지 않으니, 다른 git client 앱을 활용해야 한다. 앱스토어에서 Working Copy 앱을 내려받고, 앱 내부에서 모든 기능 언락을 결제한다. (구독형이 아닌 일회성 결제 30,000원이라 충분히 살만하다.)

아래에선 아이폰을 기준으로 설명한다. 아이패드에선 앱의 인터페이스가 조금 다를 수 있는 점은 참고.

앱 실행 후 Clone repository를 선택한다.

GitHub 탭에서 저장소를 선택해준다.

선택하면 URL 탭으로 넘어가는데, 이때 프로토콜은 https를 선택해주고, User에 본인 깃헙 닉네임을 입력해준다. (ssh프로토콜에선 문제가 생길 수 있다는 reddit 글을 본 것 같은데 확실하진 않음) 이후 Clone을 눌러 원격 저장소를 내려받는다.

옵시디언을 실행해 왼쪽 위 탭을 누른다.

Vault 이름 옆 화살표를 누르고 Manage vaults… 를 선택.

Create new vault를 선택한다.

원격 저장소와 같은 이름으로 Vault name을 입력하고, Store in iCloud는 체크 해제상태로 Create를 실행한다.

Working Copy 앱으로 돌아가, 내려받은 저장소를 선택 후 Repository를 설정 창으로 넘어간다.

저장소명 오른쪽의 화살표를 선택 후, Link Repository to를 선택한다.

Directory를 누른다.

파일탐색기가 열리면 나의 iPhone 최상단 폴더 - Obsidian 폴더로 들어가면 아까 옵시디언에서 생성한 Vault가 있다.

해당 Vault를 선택 후 열기를 누른다.

이러면 Obsidian mobile에서 생성한 Vault와 Working Copy를 통해서 Clone한 저장소가 연결된다. 아까 만들었던 Test.md 파일도 정상적으로 표시되고 있다.

이후 Working Copy를 통해 commit, pull, push를 진행해도 되지만, 옵시디언에서 메모 후 Working Copy를 통해 수동으로 백업을 해야 한다는 점이 귀찮으니 자동화와 단축어를 이용해 앱이 실행되고 종료될때마다 자동으로 백업과 메모 최신화가 될 수 있도록 세팅해보자.

5. pull, push 단축어 생성 및 자동화 설정

아래 단축어를 다운로드 받는다.

Pull 단축어 다운로드

Push 단축어 다운로드

Pull, Push 둘 다 모든 빈칸에 전부 obsidian 저장소를 선택해 채워넣는다.

자동화 탭으로 가서 추가를 선택한다.

앱이 열리거나 닫힐때 조건을 선택한다.

앱 - Obsidian, 조건 - 열릴 때, 즉시실행 으로 세팅 후 다음을 누른다.

나의 단축어로 들어간다.

Pull shortcut을 선택한다.

Push shorcut도 동일하게 세팅하면 된다. 단, 조건은 앱이 닫힐 때로 바꿔준다.

이제 제대로 업데이트가 이루어지는지 확인해보자. 옵시디언에서 새로운 문서를 작성한 후 앱을 종료하면 이렇게 귀찮은 commit과 push가 앱을 닫을때 자동으로 스무스하게 실행된다!

마찬가지로 앱을 실행할때 자동으로 pull이 된다.

혹시라도 이 세팅으로 잘 사용하다가 pull, push가 어느 순간부터 에러가 난다면 Working Copy에서 발생하는 에러일 수 있다. 그럴땐 4번 과정에서 Link Repository to를 다시 해주면 해결된다.

세팅을 마치며

이렇게 안드로이드를 제외한 모든 플랫폼에서 자동으로 백업과 동기화가 이루어지도록 옵시디언 세팅을 완료할 수 있었다.

알아본 바로는 Remotely Save라는 커뮤니티 플러그인과 드롭박스, 구글 드라이브의 조합, 또는 icloud 등을 이용해도 충분히 동기화 세팅을 진행할 수 있다. 그러나 이렇게 github을 이용하는 방법이 메모의 히스토리까지 저장 가능하다는 점, conflict가 생기는 상황에서 익숙한 방법으로 해결이 가능하다는 점이 좋아 이 방법을 선택했다.

사실 어떻게 세팅하든, 정작 메모를 적극적으로 활용하지 못한다면 의미가 없을 것이다. 앞으로 PARA 노트 정리법에 따라 메모를 작성하며 생산성을 높여봐야겠다.

(MLOps) MLFlow 기초 - 모델 배포 및 쿼리

Mon, 09 May 2022 00:00:00 +0000

이 글은 에이콘 출판사의 ‘MLFlow를 활용한 MLOps’ 도서의 내용을 참고해 작성되었습니다.

붓꽃 분류 모델 배포하기

지난 포스트 MLFlow로 붓꽃 분류 모델 로깅하기에서 이어진다.

이번 포스트에선 저장된 모델을 배포하고 쿼리문으로 POST request를 작성해 inference를 수행하는 방법에 대해 알아본다.

데이터 로드 및 스케일링

필요한 패키지를 불러온다.

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sns
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler
from sklearn.datasets import load_iris
from sklearn.metrics import accuracy_score, confusion_matrix

import subprocess
import json

붓꽃 데이터를 불러온다.

iris = load_iris()
iris_data = pd.DataFrame(data=np.c_[iris['data'], iris['target']], columns=iris['feature_names']+['target'])

x_data = iris_data.iloc[:, :-1]
y_data = iris_data.iloc[:,[-1]]

데이터 불러오기

타겟별로 데이터를 구분하고, 스케일러를 Fitting한다.

현재 예제에서는 스케일러를 새로 정의했지만, 이런 Fitting이 필요한 오브젝트들은 훈련 후 같이 파이프라인에 저장해서 Inference 과정을 자동화 할 수 있다.

setosa = iris_data[iris_data.target == 0.0]
versicolor = iris_data[iris_data.target == 1.0]
virginica = iris_data[iris_data.target == 2.0]

scaler = StandardScaler()
scaler.fit(pd.concat((setosa.sample(frac=0.5), versicolor.sample(frac=0.5), virginica.sample(frac=0.5))).drop('target', axis=1))

입력데이터에서 타겟을 분리시키고, 스케일러에 입력시켜 표준화한다.

데이터프레임을 json으로 변환할 때 현재 코드에선 “split” 형식으로 변환했다.

x_input = pd.concat((setosa_train, versicolor_train, virginica_train)).sample(n=20)
y = np.array(x_input['target'])
x_input.drop('target', axis=1, inplace=True)

x_input = pd.DataFrame(scaler.transform(x_input)).to_json(orient="split")

모델 배포

이제 ui 서버를 열고 저장된 모델을 클릭한다.

mlflow ui -p 1234

실험 클릭 -> 실행 클릭

표시된 부분에서 실행명과 모델명을 확인할 수 있다.

터미널에서 새 탭이나 새 창을 열고 Inference 서버를 실행하며 모델을 배포한다. 주소나 포트 번호는 ui 서버와 다르게 사용해야 한다.

(iterm 기준 command + t 로 새 탭 열기가 가능하다.)

mlflow models serve --model-uri runs:/e45b49292ea64807844ccd436d379672/log_reg_model -p 1235

서버 실행 결과

POST request 쿼리를 사용한 inference

다음과 같이 쿼리문을 작성하고, subprocess에 쿼리문을 입력해 실행하면 다음과 같은 결과를 얻을 수 있다.

query = ["curl", "-X", "POST", "-H", "Content-Type:application/json; format=pandas-split", "--data", x_input, "http://127.0.0.1:1235/invocations"]
proc = subprocess.run(query, stdout=subprocess.PIPE, encoding='utf-8')
output = proc.stdout
preds = pd.DataFrame([json.loads(output)])
preds

POST request inference 수행 결과

이때 이 쿼리문의 각각의 명령어와 파라미터들은 다음과 같은 의미를 가진다.

curl : cli에서 데이터 전송을 위해 사용하는 라이브러리인 cURL의 명령어
-X POST : REST API 메소드를 POST로 설정한다.
-H Content-Type:application/json : 헤더의 컨텐츠 타입을 application/json으로 설정한다. {key:value}의 형태로 전송된다.
format=pandas-split : json의 형식은 pandas-split으로 지정한다.
--data {x_input} : 데이터엔 json 오브젝트가 입력된다.
http://127.0.0.1:1235/invocations : POST request를 전달할 서버 주소

마지막으로 Inference 결과물이 제대로 예측됐는지 확인해본다.

val_acc = accuracy_score(y, preds.T)
eval_acc

>>>
0.9

conf_matrix = confusion_matrix(y, preds.T)
ax = sns.heatmap(conf_matrix, annot=True, fmt='g')
ax.invert_xaxis()
ax.invert_yaxis()
plt.ylabel('Actual')
plt.xlabel('Predicted')
plt.title("Confusion Matrix")

Confusion Matrix

20개 중 총 18개의 데이터에 대해 예측에 성공했다.

출처

(MLOps) MLFlow 기초 - 실행 및 로깅

Tue, 12 Apr 2022 00:00:00 +0000

이 글은 에이콘 출판사의 ‘MLFlow를 활용한 MLOps’ 도서의 내용을 참고해 작성되었습니다.

MLOps란?

‘Machine Learning Operations’의 약자로, 데이터 적재, 전처리, 모델 훈련, 모델 저장, 테스트와 검증, 모델 배포, 모니터링 등 머신러닝의 생명주기에 포함된 모든 과정과 이를 효율적으로 관리하는 방법론을 통칭한다.

MLOps 엔지니어가 이 모든 과정을 담당한다면 리서처들은 데이터의 활용, 모델의 설계, 연구와 같은 과정에만 전념할 수 있게 된다. 특히 데이터 중심의 AI가 각광받음에 따라서 데이터의 품질 관리가 점점 중요해지고 있기에 연구자들이 고품질의 데이터를 활용할 수 있도록 돕는 MLOps 엔지니어의 역할이 더욱 커지는 상황이라고 생각한다. 물론 다양한 MLOps관련 도구에서 실험과 연관된 막강한 기능들을 지원하니, 연구자라도 스스로 MLOps에 대한 이해가 높다면 더욱 효율적인 실험 진행도 가능할 것이다!

개념 자체는 소프트웨어의 생명 주기를 책임지는 과정인 DevOps와 비슷하지만, 코드 중심이 아닌 데이터와 모델 중심의 관리라는 점에서 약간의 차이가 있다.

MLFlow란?

MLFlow는 대중적인 MLOps 오픈소스 라이브러리 중 하나이다. 강력한 로깅과 트래킹 기능, 도커와 콘다를 포함한 가상환경 파이프라인의 재사용성 확보, 모델 저장과 서버 배포 관리, 다양한 API와 UI기능 지원을 통한 확장성까지 이름처럼 머신러닝의 ‘흐름’에 필요한 다양한 기능을 활용할 수 있다. 깃헙 레포지터리 링크

MLFlow 홈페이지

MLFlow 설치

MLFlow 설치는 번거로운 과정 없이 pip를 통해 가능하다.

python3 -m pip install mlflow

붓꽃 데이터 로지스틱 회귀 예제

먼저, 필요한 데이터와 붓꽃 데이터를 불러온다.

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sns
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler
from sklearn.metrics import confusion_matrix
from sklearn.datasets import load_iris

import mlflow
import mlflow.sklearn

데이터를 판다스 데이터프레임으로 변환한다.

iris = load_iris()
iris_data = pd.DataFrame(data=np.c_[iris['data'], iris['target']], columns=iris['feature_names']+['target'])

iris_data

DataFrame

컬럼을 feature와 target으로 분할한다.

x_data = iris_data.iloc[:, :-1]
y_data = iris_data.iloc[:,[-1]]             

클래스별로 변수를 따로 할당한다.

setosa = iris_data[iris_data.target == 0.0]
versicolor = iris_data[iris_data.target == 1.0]
virginica = iris_data[iris_data.target == 2.0]

print("Setosa : {}".format(setosa.shape))
print("Versicolor : {}".format(versicolor.shape))
print("Virginica : {}".format(virginica.shape))

>>>
Setosa : (50, 5)
Versicolor : (50, 5)
Virginica : (50, 5)

훈련셋과 테스트셋으로 분할한다.

setosa_train, setosa_test = train_test_split(setosa, test_size=0.2)
versicolor_train, versicolor_test = train_test_split(versicolor, test_size=0.2)
virginica_train, virginica_test = train_test_split(virginica, test_size=0.2)

나눴던 변수를 다시 concat한다.

x_train = pd.concat((setosa_train, versicolor_train, virginica_train))
x_test = pd.concat((setosa_test, versicolor_test, virginica_test))

y_train = np.array(x_train['target'])
y_test = np.array(x_test['target'])

x_train.drop('target', axis=1, inplace=True)
x_test.drop('target', axis=1, inplace=True)

>>>
Training sets:
	x_train: (120, 4) 
	y_train: (120,)

Testing sets:
	x_test: (30, 4) 
	y_test: (30,)

피처 스케일링

scaler = StandardScaler()
scaler.fit(pd.concat((setosa, versicolor, virginica)).drop('target', axis=1))
x_train = scaler.transform(x_train)
x_test = scaler.transform(x_test)

훈련 함수 작성

def train(sklearn_model, x_train, y_train):
    sklearn_model = sklearn_model.fit(x_train, y_train)
    train_acc = sklearn_model.score(x_train, y_train)
    mlflow.log_metric("train_acc", train_acc)
    print("Train Accuracy: {:.3%}".format(train_acc))

평가 함수 작성

def evaluate(sklearn_model, x_test, y_test):
    eval_acc = sklearn_model.score(x_test, y_test)
    preds = sklearn_model.predict(x_test)

    mlflow.log_metric("eval_acc", eval_acc)
    print("Eval Accuracy: {:.3%}".format(eval_acc))
    
    conf_matrix = confusion_matrix(y_test, preds)
    ax = sns.heatmap(conf_matrix, annot=True, fmt='g')
    ax.invert_xaxis()
    ax.invert_yaxis()
    plt.ylabel('Actual')
    plt.xlabel('Predicted')
    plt.title("Confusion Matrix")
    plt.savefig("sklearn_conf_matrix.png")
    mlflow.log_artifact("sklearn_conf_matrix.png")

모델과 실험(파이프라인)을 설정한다.

처음에 mlflow.set_experiment("실험이름")을 통해 로깅될 실험의 이름을 설정한다.

with 블록 안에 파이프라인 train, evaluate, logging 등의 과정이 적재되어있고, start_run() 메소드를 통해 실행된다. with 구문 덕분에 각 실행의 독립성이 보장된다. 쉽게 말해 여러번 실험을 할 경우 하나의 실험이 예상치 못하게 종료되든, 올바르게 종료되든 다음 실험에는 전혀 영향을 주지 않는다.

sklearn_model = LogisticRegression(max_iter=50, solver='newton-cg')
mlflow.set_experiment("iris_experiment")
with mlflow.start_run():
    train(sklearn_model, x_train, y_train)
    evaluate(sklearn_model, x_test, y_test)
    mlflow.sklearn.log_model(sklearn_model, "log_reg_model")
    print("Model run: ", mlflow.active_run().info.run_uuid)
mlflow.end_run()

MLFlow는 이처럼 pythonic한 파이프라인을 작성하기 좋다.

실행결과는 다음과 같다

>>>
Train Accuracy: 95.000%
Eval Accuracy: 96.667%
Model run:  e45b49292ea64807844ccd436d379672

Testset 분류 결과

loaded_model = mlflow.sklearn.load_model("runs:/a67105e9dd424de390b33509cc1a7e10/log_reg_model")
print(loaded_model.score(x_test, y_test))

>>>
0.9666666666666667

MLFlow ui 실행

터미널 접속 후 코드가 저장된 디렉토리에서

mlflow ui -p 9999  # 포트 번호 지정

만약 command not found 에러를 마주한다면 conda(miniforge) 가상환경이 활성화가 된 상태인지 먼저 확인해보자.

정상적으로 진행된다면 다음과 같이 localhost의 9999번 포트에서 실행된다.

[2022-04-12 22:07:09 +0900] [9424] [INFO] Starting gunicorn 20.1.0
[2022-04-12 22:07:09 +0900] [9424] [INFO] Listening at: http://127.0.0.1:9999 (9424)
[2022-04-12 22:07:09 +0900] [9424] [INFO] Using worker: sync
[2022-04-12 22:07:09 +0900] [9425] [INFO] Booting worker with pid: 9425

웹 브라우저 접속시 메인화면

왼쪽에 실험명인 iris_experiment를 클릭하면 그동안의 실험이 전부 기록되어 있다.

가장 최근의 실행을 클릭해 들어가보면 기록된 설명, 파라미터, 평가항목, 태그, 저장된 모델 정보와 이미지 등을 볼 수 있다.

실행 정보

다음과 같이 필터링 조건을 걸어 원하는 실행만 모아 볼 수 있고

조건부 필터링

여러개의 실행을 동시 선택 후 Compare를 눌러 실행간의 시각화된 비교 결과를 볼 수 도 있다.

여러개를 선택 후 Compare 클릭

Scatter Plot

좌측 실험 탭에서 각 실험들은 휴지통 버튼으로 삭제할 수 있지만, 삭제된 실험들은 모두 .trash에 남아있다. 따라서 완전히 삭제하기 위해선 터미널에서 따로 휴지통을 비워줘야 한다.

rm -rf mlruns/.trash/*

터미널에서 포그라운드 상태로 ‘ctrl + c’를 눌러 MLFlow를 종료할 수 있다. 맥에서도 ‘command’가 아닌 ‘ctrl’을 그대로 사용하면 된다.

또는 pkill -f gunicorn 으로도 종료할 수 있다.

출처

(MacOS) Vim을 기본 텍스트 에디터로 사용하기

Tue, 22 Mar 2022 00:00:00 +0000

맥에서 Automator를 활용해 기본 텍스트 에디터를 Vim으로 설정하는 법을 정리해본다.

Automator & AppleScript 설정

아래 사진에 따라 설정을 진행한다

런치패드 또는 Spotlight 검색으로 Automator 실행 -> '새로운 문서' 선택

'응용 프로그램' 선택

검색창에 'AppleScript' 검색 후 'AppleScript 실행' 더블클릭, 스크립트 입력창에 아래 코드 작성

on run {input, parameters}
	if (count of input) > 0 then
		tell application "System Events"
			set runs to false
			try
				set p to application process "iTerm"
				set runs to true
			end try
		end tell
		tell application "iTerm"
			activate
			set numItems to the count of items of input
			set launchPaths to ""
			repeat with x from 1 to numItems
				set filePath to quoted form of POSIX path of item x of input
				set launchPaths to launchPaths & " " & filePath
			end repeat
			tell current window
				delay 0.01
				create tab with default profile command "vim " & launchPaths
			end tell
		end tell
	end if
end run

코드의 출처는 글 아래에 명시해 놨는데, 해당 글에서 소개한 코드에서 create tab ... 바로 위 라인에 delay 0.01 코드가 추가된 것을 알 수 있다.

맥 버전이나 기종마다 다른지는 확실히 알 수 없지만, 내 경우 이렇게 딜레이 코드를 넣지 않으면 iterm이 실행중이지 않을 때 텍스트 파일을 열면 iterm만 실행되고 Vim은 실행되지 않는 문제가 생겼다.

앱 이름 및 위치 지정

'응용 프로그램'과 같은 적당한 위치에 작성한 앱 저장

열고싶은 텍스트 파일 우클릭 -> 다음으로 열기 -> 기타

저장한 앱 선택 -> '항상 선택한 응용 프로그램으로 열기' 체크

실행 결과

이제 같은 확장자를 가진 텍스트 파일들은 바로 Vim으로 다이렉트로 열 수 있다

출처

https://gist.github.com/Huluk/5117702

M1 맥 GPU 가속 지원하는 텐서플로우 개발환경 세팅

Thu, 17 Mar 2022 00:00:00 +0000

M1pro 맥북프로 14인치를 질렀다.

Mac OS는 처음이라 익숙치 않아 2~3일 정도는 설정을 만지작거렸고, 이후에 딥러닝 개발 환경 세팅을 시작했다.

아직까지 애플 실리콘에선 완벽한 딥러닝 환경을 구현하기엔 무리가 있지만, 적어도 텐서플로우는 공식적으로 GPU가속을 지원한다.

개발환경 세팅을 위해 인터넷에 올라온 여러 글을 참고했는데, 여러번 설치에 실패했다.

결국 돌고 돌아 애플 공식 개발자 가이드에 소개된 내용이 정답이었다

주의사항

파이썬 버전 3.8 또는 3.9 필요
Conda 설치 금지
Homebrew 사용 금지

우선 이 글을 보는 누군가의 삽질을 막기 위해 주의사항으로 시작한다. 자세한 이유는 아래에서 설명한다.

만약 이미 Anaconda나 Conda를 설치했다면 가능하면 삭제 후에 진행하자.

Conda 삭제방법 가장 추천수 많이 받은 답변 참고

추가로 내 경우는 아나콘다가 /opt/anaconda3 에도 설치되었다. 각자 아나콘다가 삭제된 폴더를 잘 찾아서 싹 다 삭제해주자

환경설정

Miniforge 설치용 쉘 스크립트 파일을 다운로드 받는다. 링크

Miniforge는 Conda와 비슷한 파이썬 패키지 및 가상환경 관리 플랫폼이다. Conda를 사용하지 않는 이유는 애플 실리콘을 지원하지 않기 때문이고, 텐서플로우의 GPU가속 플러그인 tensorflow-metal이 이 miniforge채널을 통해서만 배포되기 때문이다.

아래 명령어로 설치를 진행한다.

$ chmod +x ~/Downloads/Miniforge3-MacOSX-arm64.sh
$ sh ~/Downloads/Miniforge3-MacOSX-arm64.sh
$ source ~/miniforge3/bin/activate

여기부턴 가상환경(base)이 실행된 상태가 된다.

Miniforge 설치 중 환경변수 이름을 conda로 사용할 거냐고 묻는 메세지가 중간에 나오는데, 십중팔구는 Yes를 선택할 것이다.

이러면 기존에 설치된 conda랑 환경변수가 겹칠 수 있으니, 애플 실리콘 지원 안해주는 conda를 처음부터 삭제하고 설치하는 것이 낫다.

설치확인

(base)$ conda info

>>> 
     active environment : None
            shell level : 0
                
                        ...
                
               platform : osx-arm64
             user-agent : conda/4.11.0 requests/2.27.1 CPython/3.9.10 Darwin/21.4.0 OSX/12.3
                UID:GID : 000:00
             netrc file : None
           offline mode : False                

중간에 platform에 ‘osx-arm64’로 표기되어 있어야 성공이다. ‘osx-64’ 이렇게 표기되면 실패한거니 삭제 후 다시 설치하자.

Homebrew를 사용하지 말라는 이유가 여기 있다. Miniforge는 쉘 스크립트 파일 다운받고 명령어 여러줄 칠 필요 없이 Homebrew만으로도 간편하게 설치가 가능한데, 이렇게 설치하면 애플 실리콘 버전이 아닌 인텔 버전이 설치된다. 일단 적어도 내 경우에는 그랬다.

텐서플로우 dependencies 설치

(base)$ conda install -c apple tensorflow-deps

텐서플로우 설치

(base)$ python -m pip install tensorflow-macos

텐서플로우 metal 플러그인 설치

(base)$ python -m pip install tensorflow-metal

디바이스 선택

텐서플로우 2.8에선 MLIR 이라는 채-신 기술을 사용해 디바이스를 자동으로 선택해준다. 따로 설정할 필요 없음

Multi-Level Intermediate Representation, 다중 계층에서 파편화된 딥러닝의 표현방식, 컴파일러, 프레임워크, 실행 환경 등을 일반화하고 통합하는 프로젝트라고 하는데, 다음에 자세히 알아봐야겠다.

테스트

MNIST 예제 코드

import tensorflow as tf

mnist = tf.keras.datasets.mnist

(x_train, y_train), (x_test, y_test) = mnist.load_data()
x_train, x_test = x_train / 255.0, x_test / 255.0

model = tf.keras.models.Sequential([
  tf.keras.layers.Flatten(input_shape=(28, 28)),
  tf.keras.layers.Dense(128, activation='relu'),
  tf.keras.layers.Dropout(0.2),
  tf.keras.layers.Dense(10, activation='softmax')
])

model.compile(optimizer='adam',
              loss='sparse_categorical_crossentropy',
              metrics=['accuracy'])

model.fit(x_train, y_train, epochs=5)

model.evaluate(x_test,  y_test, verbose=2)

실행 결과

Metal device set to: Apple M1 Pro

systemMemory: 32.00 GB
maxCacheSize: 10.67 GB

2022-03-18 00:46:54.141153: I tensorflow/core/common_runtime/pluggable_device/pluggable_device_factory.cc:305] Could not identify NUMA node of platform GPU ID 0, defaulting to 0. Your kernel may not have been built with NUMA support.
2022-03-18 00:46:54.141252: I tensorflow/core/common_runtime/pluggable_device/pluggable_device_factory.cc:271] Created TensorFlow device (/job:localhost/replica:0/task:0/device:GPU:0 with 0 MB memory) -> physical PluggableDevice (device: 0, name: METAL, pci bus id: <undefined>)
2022-03-18 00:46:54.273304: W tensorflow/core/platform/profile_utils/cpu_utils.cc:128] Failed to get CPU frequency: 0 Hz
Epoch 1/5
2022-03-18 00:46:54.409370: I tensorflow/core/grappler/optimizers/custom_graph_optimizer_registry.cc:113] Plugin optimizer for device_type GPU is enabled.
1875/1875 [==============================] - 9s 5ms/step - loss: 0.2959 - accuracy: 0.9148
Epoch 2/5
1875/1875 [==============================] - 9s 5ms/step - loss: 0.1403 - accuracy: 0.9587
Epoch 3/5
1875/1875 [==============================] - 9s 5ms/step - loss: 0.1023 - accuracy: 0.9689
Epoch 4/5
1875/1875 [==============================] - 9s 5ms/step - loss: 0.0803 - accuracy: 0.9753
Epoch 5/5
1875/1875 [==============================] - 9s 5ms/step - loss: 0.0680 - accuracy: 0.9789
2022-03-18 00:47:38.664373: I tensorflow/core/grappler/optimizers/custom_graph_optimizer_registry.cc:113] Plugin optimizer for device_type GPU is enabled.
313/313 - 1s - loss: 0.0706 - accuracy: 0.9771 - 1s/epoch - 4ms/step

디바이스가 Apple M1 Pro로 제대로 인식되었다

GPU 활성 상태

또한 GPU 활성 상태도 90% 이상으로 성능을 잘 활용하는 것을 확인했다.

기타

파이토치는 애플 실리콘 네이티브를 지원하지만 아직까지 GPU가속 지원은 개발중이라고 한다.

개인적으로 따로 쓸 수 있는 GPU 서버가 없다면 구글 코랩이나 Paperspace Gradient같은 클라우드 딥러닝 플랫폼을 사용하는걸 권한다.

출처

파이토치 모델이 CPU에서 너무 느릴때. torch.set_flush_denormal()

Mon, 13 Dec 2021 00:00:00 +0000

결론부터 말하자면, 파이토치 관련 코드의 시작 부분에 이렇게 쓰면 된다.

torch.set_flush_denormal(True)

딥러닝 모델 훈련 및 실사용시엔 고차원 텐서 연산을 병렬적으로 처리할 수 있는 GPU가 거의 필수적이지만, 가벼우면서 real-time estimation이 필수적이지 않은 모델은 CPU에서 실행하더라도 충분히 실사용이 가능한 경우도 있다.

그러나 훈련된 모델을 CPU에서 실행시켜보면 간혹 예상한 속도보다 비교가 안 될 정도로 느려진다. GPU에서 하나의 입력에 대해 예측값을 내기까지 걸리는 시간이 0.1초도 걸리지 않는 모델이 CPU에서 실행했더니 20초가 넘게 걸린다고 가정해보자. 아무리 실시간 예측을 포기한다고 하더라도 결과 하나를 얻기 위해 수 초 이상을 기다리는 경험은 상당히 불쾌할 것이다.

위에 적은 내용은 실제로 내가 경험한 일이다. 해당 모델은 몇개의 모듈 단위로 구성되어 있었고, 각 모듈마다 선형 레이어가 사용되었다. 모듈별로 입/출력값은 달랐지만 선형 레이어와 입/출력값의 사이즈는 모두 같았다. 나는 당연히 입력 텐서와 선형 레이어의 크기가 같은 모듈끼린 실행 시간이 비슷할 것이라고 예상했지만, 두 모듈 내에서 선형 레이어의 연산 속도를 비교 출력해본 결과 처리 속도가 무려 40배 이상 차이가 났다. 처음엔 둘다 동일한 CPU에서 실행됐기 때문에 CPU와 관련된 문제라곤 생각하지 못했다. 각각의 입력값과 가중치가 문제인가도 고민했지만, 수십만개의 가중치와 입력값을 일일히 비교해보는 것도 무리였다.

특정 개발자 커뮤니티에 질문한 후 가장 유력한 답변을 하나 받게 되었는데, 0에 가까운 수는 연산이 느리고, 파이토치에 이를 0으로 처리하는 옵션이 있다는 것이다. 덕분에 torch.set_flush_denormal의 존재에 대해 알게 됐고, 해당 모델의 실행속도는 20초에서 0.3초 남짓으로 대폭 줄어들게 되었다. (성능 변화도 거의 없었다.)

비정규값 (Denormalized numbers)

일반적으로 부동소수점 값을 표현할 때는 아래 예시와 같이 유효숫자의 첫자리를 1의자리에서 시작한다. 가수부의 표현 범위를 1이상 9이하, 즉 유효숫자를 일의 자리로 정규화했기 때문에 이를 정규값이라고 한다.

\[1.05 \times 10^{-2}\]

같은 수라도 정규화해서 표현하지 않고 지수부를 다르게 해서 자유롭게 표현할 수 있다.

$0.105 \times 10^{-1}$ 또는 $10.5 \times 10^{-3}$ 도 모두 같은 수이다.

만약 0.000000000105라는 숫자를 부동 소수점으로 표현하고 싶은데, 지수부가 표현 가능한 자릿수를 8로 제한한다면 정규화 되지 않은 수로만 표현 할 수 있을 것이다. 이렇게 지수부 제한으로 인해 정규화되지 못한 작은 값들을 비정규값(denormalized number)으로 부른다.

\[0.0105 \times 10^{-8}\]

컴퓨터는 부동 소수점을 부호, 지수부, 가수부를 통해 2진법으로 나타내게 되는데, 메모리 비트 수에 따라 지수부가 표현할 수 있는 수의 범위가 제한된다. 정규값에서 가수부의 맨 앞 비트가 1의자리를 표현하지만, 비정규값은 지수부가 모두 0으로 채워져 있고 가수부의 맨 앞 비트가 0.1의 자리를 나타낸다. 만약 부호가 양수이고 지수부 8비트가 모두 0, 가수부 비트가 0101000….인 비정규값이 있다면, 실제 값을 이렇게 표현할 수 있다.

\[0.0101_{(2)} \times 2^{-255}\]

이렇듯 0에 가까운 작은 수가 비정규값으로 처리되고, 파이토치에서 이러한 비정규값 입력과 가중치들을 모두 0으로 일괄 처리하는 옵션을 통해 연산속도를 향상시킬 수 있다는 점을 알게 되었다. 그러나 비정규값이 정규값에 비해 더 많은 비트를 차지하는 것도 아닌데 어째서 연산속도는 미치도록 느린 것인지 이해가 되지 않아 이유를 좀 더 찾아보았다.

x86 CPU의 비정규값 처리

해당 스택 오버플로우 답변을 통해 알 수 있었다. 답변자는 x86 CPU의 설계 경험이 있다고 한다… 고인물이다.

비정규값 연산 중 가수부와 지수부는 각각 다음과 같은 과정을 거친다.

가수부 비트는 left-shift 연산으로 정규화되고 연산 후엔 다시 right-shift로 변환된다.
지수부는 레지스터나 메모리에 적재될때는 32비트 중 8비트로만 제한적으로 표현되지만 연산과정 자체는 비트수의 제약을 받지 않는다.

간단한 shift연산과 정수연산… 이것만 본다면 딱히 느릴 이유가 없어보인다.

원인은 아키텍쳐 설계 원칙에 있다. CPU가 주로 처리하는 값의 대부분은 정규값이다. 자주 사용하는 연산을 더 빠른 회로에서 처리하고 덜 사용되는 연산은 상대적으로 더 오래 걸리는 회로에 배치하는 설계원칙에 의해 비정규값 연산의 우선순위가 뒤로 밀린 것이다.

해당 수가 정규값인지 비정규값인지부터 판단하고 연산을 하는 회로에선 정규값 계산시 50%의 추가 지연 시간이 생기기 때문에, x86 CPU는 모든 연산을 정규값 연산으로 처리해버리고 이후 비정규값으로 인해 예외가 발생하면 예외처리 후 뒤늦게 비정규값 연산을 수행하는 구조로 설계되었다고 한다. 때문에 정규값 연산은 클럭 주파수 3~6 사이클 수준이지만 비정규값 연산은 100 사이클 가까이 걸린다고.

결국 비정규값의 연산 그 자체가 오래 걸리는 건 아니지만 microcode exception handler까지 도달했다가 나오는 시간이 문제였다.

반대로 GPU는 비정규값을 처리하기 위한 파이프라인을 추가로 구축함으로써 정규값 연산속도에 약간의 trade-off가 존재하지만 덕분에 비정규값을 거의 속도 저하 없이 처리할 수 있다고 한다.

파이토치에서 해당 옵션 사용시 주의사항

SSE3 명령어셋을 지원하는 x86 CPU 또는 x64 CPU 에서만 사용 가능하다. (x64(64bit)는 x86(32bit)의 하위 호환성을 보장한다.)

CPU 아키텍쳐 확인

$ arch
>>> x86-64

SSE3 지원 확인

$ grep 'sse3\|pni' /proc/cpuinfo > /dev/null
if [ $? -eq 0 ];  then
        echo "Supported!"
else
        echo "Not supported!"
fi
>>> "Supported!"

arm등 다른 아키텍쳐의 CPU에서도 비정규값 처리 기능이 있고, 더 자세히 관련 내용에 대해 알아보려면 ‘Flush To Zero’라는 키워드로 검색해보면 된다.

출처

Tablesense 논문 리뷰 (TableSense - Spreadsheet Table Detection with Convolutional Neural Networks)

Fri, 10 Dec 2021 00:00:00 +0000

TableSense: Spreadsheet Table Detection with Convolutional Neural Networks 논문 데이터셋

Abstract & Problem Statement

Table Detection

Spreadsheet table detection은 엑셀 파일 등에서 테이블이 존재하는 영역, 정확히는 top, left, bottom, right 네 방향의 boundary를 감지하는 종류의 과제를 말한다. 스프레드 시트라는 2차원 좌표계 내에서 bounding box를 추출하는 과제이므로 얼핏 보면 이미지 object detection과 비슷한 느낌이 있다. 실제로도 저자는 이 문제를 해결하기 위한 base algorithm으로 딥러닝 이미지 처리 분야에서 real-time object detection의 포문을 열었던 모델인 Faster R-CNN을 사용했다. 그러나 이 과제는 이미지의 object detection과 결정적인 차이점이 존재한다.

먼저, 이미지 object detection은 평가지표가 Intersection-over-Union(IoU)라는 것이다. Bounding box라는 것이 완전히 절대적인 기준에 의해 라벨링 된 것이 아닌(비록 일관성 있는 라벨링을 가능한 유지하려는 노력은 있었겠지만) 인간의 시각을 기준으로 임의로 부여된 것이다 보니, 아래 그림과 같이 예측 bounding box가 ground truth와 약간의 차이가 있더라도 IoU는 충분히 높게 측정되고, 인간의 눈으로 보기에도 정답이라고 인정할 수준이 된다.

Ground Truth vs Predicted Bbox

하지만 엑셀 파일에서 테이블을 추출하는 작업은 가능한 한 셀의 오차도 없이 정확해야 한다. 이미지 처리에 비교하자면 1픽셀의 오차도 허용하면 안되는 상황인 것이다. 만약 테이블의 가장 우측 또는 최하단에 중요한 정보가 포함되어 있고, bounding box에서 이런 row나 column만 제외된다면 추출된 테이블 활용에 문제가 생길 것이다.

그리고 입력 데이터의 성격도 다르다. 이미지는 각 픽셀당 3채널에 R, G, B 색상 정보를 가지고 있는데, 엑셀에서 하나의 셀이 품고 있는 정보는 배경색, 선 스타일, 입력값, 수식 등등… 훨씬 많다. 게다가 가로 또는 세로가 편향적으로 길쭉한 이미지나 객체는 거의 없지만, 엑셀 파일에선 가로보다 세로 길이가 100배 이상 길쭉한 비율을 가진 테이블을 흔히 찾을 수 있다.

저자는 위 문제를 해결하기 위해 새로운 모델 구조와 평가방법, 학습 방법을 제시했고, 관련 데이터셋을 구축하는 성과를 올렸다. 비록 이 분야 자체가 사람들의 관심도가 높은 편은 아니지만, 논문은 엑셀의 본고장 마이크로소프트의 연구진들에 의해 작성됐고 연구진들의 후속 논문에서도 이 Tablesense 논문이 꾸준하게 사용되고 있기 때문에 한번쯤 볼만한 논문이다.

IoU vs EoB

이후부턴 bounding box를 편의상 bbox로 줄여 부르겠다. Object detection의 가장 보편적인 평가지표는 Intersection-over-Union이다. 이는 예측 bbox $(B)$와 실제 bbox $(B’)$의 일치도를 나타내는데, 두 bbox간의 교집합 넓이를 합집합 넓이로 나눈 것이다.

\[\mathrm{IoU} = \frac{\mathrm{area}(B \cap B')}{\mathrm{area}(B \cup B')}\]

이는 bbox의 절대적인 크기와 상관 없이 각 bbox간 오차의 상대적 비율만 고려한다. 따라서 큰 bbox간 IoU를 구할 수록 작은 절대 오차는 무시된다. 같은 크기지만 해상도가 다른 20pixel x 20pixel 이미지와 1000pixel x 1000pixel 이미지가 있을 때, 20 x 20 해상도 이미지에선 한쪽 boundary가 5픽셀 차이가 나면 인간의 시각 기준으로 매우 큰 차이로 느껴지고 실제로 IoU도 작게 측정겠지만, 1000 x 1000 해상도 이미지에선 한쪽 boundary가 5픽셀 차이나도 인간의 시각은 문제 없이 bbox를 정답으로 인식하고 IoU역시 높게 측정된다. 따라서 전체 영역이 커질수록 작은 차이가 무시되는 IoU는 엑셀 테이블 추출의 평가지표로 사용하기에 매우 부적합하기에 저자들은 새로운 평가지표인 Error-of-Boundary를 제시한다.

\[\begin{align*} \mathrm{EoB} = \mathrm{max}( &\vert\mathrm{row_{top}^\mathit{B}} - \mathrm{row_{top}^\mathit{B'}}\vert, \vert\mathrm{row_{bottom}^\mathit{B}} - \mathrm{row_{bottom}^\mathit{B'}}\vert, \\ &\vert\mathrm{row_{left}^\mathit{B}} - \mathrm{row_{left}^\mathit{B'}}\vert, \vert\mathrm{row_{right}^\mathit{B}} - \mathrm{row_{right}^\mathit{B'}}\vert) \end{align*}\]

EoB는 예측과 정답 boundary의 최대 절대 오차가 기준이다. 예를 들어, 상/하/좌/우 boundary의 예측값과 정답이 각각 2/0/1/1 셀 만큼씩 차이가 난다면, top-boundary의 오차가 2로 가장 크고, 따라서 EoB는 이 경우 2가 된다. 덕분에 테이블이 크기와 상관 없이 영역이 아닌 boundary를 기준으로 평가할 수 있다.

Datasets & Framework

스프레드 시트 파일을 웹에서 크롤링해 그 중 10220개의 시트에 라벨링을 해 훈련 셋으로 사용하고 이와 겹치지 않는 400개의 시트를 테스트 셋으로 사용했다.

TableSense Framework

Tablesense는 다음 다섯 단계에 걸쳐 테이블을 추출한다.

Cell Featurization
CNN Backbone
Region Proposal Network
Bounding Box Regresssion
Precise Bounding Box Regression

Cell Featurization은 시트를 텐서로 변환하는 단계이다. 이미지 파일은 한 픽셀에 색상 3채널의 정보를 담고 있지만, 엑셀 파일은 한 셀당 20채널로 나타낸다. 각 채널마다 영문자 비율, 숫자 비율, 입력값 길이, 선 스타일 적용 유무, 배경색, 글자색, 수식 적용 여부 등등의 정보를 담게 된다.

이후 CNN backbone, Region Proposal Network, Bounding Box Regression은 Faster R-CNN의 알고리즘을 그대로 사용한다. 약간의 차이점이 있다면 resnet backbone에서 pooling layer를 제거한것과, RPN의 anchor세트가 base size 8 ~ 4096, ratio 1/256 ~ 256 까지 존재하는 등 다양한 크기와 극단적으로 편향된 비율을 가진 케이스까지 포함한다는 점이다.

주목해야 할 부분은 이 모델의 핵심 구조인 PBR(Precise Bounding Box Regression) 모듈이다. BBR모듈의 Regrion of Interest를 기반으로 세부적인 boundary를 보정하는데, 어떤 원리인지 자세히 알아보자.

Precise Bounding Box Regression module

BBR 모듈로 출력된 RoI는 부정확한 boundary를 가지고 있기 때문에, 이 boundary를 기준으로 receptive field를 새로 설정해 예측값과 정답값의 차이를 구하게 된다. 좌, 우 boundary에 대해서는 수평방향으로 $2k$, 상/하 boundary에 대해서는 수직방향으로 $2k$의 사이즈를 가지는 좁은 receptive 필드는 예측 boundary와 실제 boundary의 오차를 최소화하는데 적합하다. 논문에선 적절한 $k$를 7로 설정했다. $k$가 너무 크면 여러개의 작은 표가 가까이 붙어있는 경우 정답을 예측하는데 방해가 되고, 너무 작으면 receptive field가 ground truth boundary를 포함하지 못할 확률이 높아지기 때문이다. 네 방향의 receptive field로부터 추출된 feature map은 RoIAlign을 통해 $2k \times 2k$ 크기의 텐서로 고정되고, regression 이후 세부적인 보정값을 출력하게 된다. Receptive field의 폭 또는 높이와 RoIAlign 후의 폭 또는 높이가 같기 때문에 정보의 손실이 거의 없게 된다. PBR모듈의 출력값을 통해 BBR모듈이 출력한 RoI를 보정하게 되면 경계 오차가 매우 적은 bbox를 얻을 수 있다.

Target & Loss Function

기존 Faster R-CNN의 손실함수는 다음과 같이 smooth L1을 사용한다.

\[L_\mathrm{reg}(t, t^{*}) = \sum_{i \in \{ x, y, w, h\}} \mathrm{smooth_\mathit{L_1}} (t_i - t_i^{*})\]

타겟은 다음과 같이 설정된다.

\[\begin{align*} &t_x = (x - x_a) / w_a,\quad t_w = \log(w/w_a) \\ &t_x^* = (x^* - x_a) / w_a,\quad t_w^a = \log(w^*/w_a) \end{align*}\]

$x, w$는 각각 bbox의 중심 $x$좌표와 폭을 나타내고, $y, h$에 대해서도 동일한 식을 사용한다. 첨자가 없는 문자는 예측 bbox의 값, 아래첨자 $a$가 붙은 문자는 anchor box의 값, 윗첨자 $*$가 붙은 문자는 ground-truth box의 값을 나타낸다. 이 식에서 $x$에 대한 손실함수의 기울기는 $w_a$에 대해 반비례하고, $w$에 대한 손실함수의 기울기는 $w$에 대해 반비례한다. 즉 anchor box가 클 수록 중심 좌표에 대한 가중치 업데이트 값이 작아지고, 마찬가지로 예측 bbox가 클 수록 폭과 높이에 대한 가중치 업데이트 값이 작아진다. 이는 bbox의 크기와 상관 없이 안정적인 훈련을 보장하지만 boundary를 정확하게 예측하는 데에는 적합하지 않다.

따라서 PBR 모듈은 새로운 손실함수와 타겟을 사용한다.

\[L_\mathrm{reg}(t, t^*) = \sum_{i \in \mathrm{\{ top, bottom, left, right\}}} R (t_i - t_i^*)\] \[R(x) = \begin{cases} 0.5x^2, & \mathrm{if} \: \vert x \vert < k\\ 0.5k^2, & \mathrm{otherwise} \end{cases}\]

\[\begin{align*} &t_{left} = x - x_a - w/2,\quad t_{right} = x - x_a + w/2 \\ &t_{left}^* = x^* - x_a - w^*/2,\quad t^*_{right} = x^* - x_a + w^*/2 \end{align*}\]

$t_i - t_i^*$를 계산해 보면 anchor box에 관련된 변수들은 사라지고 예측값과 ground-truth의 절댓값 차이만이 남는다. 따라서 PBR 모듈의 가중치 업데이트는 절대 오차에 따라 이뤄진다. 또한 함수 $R$에서 오차가 $k$ 이상일 때는 기울기가 $0.5k^2$으로 고정되기에 예측값과 ground-truth간의 차이가 너무 크더라도 업데이트가 급격하게 이루어지는 상황을 방지했다.

모든 손실함수는 역전파 전에 더해진다. 기본적으로 PBR 모듈만으론 Region Proposal Network의 안정적인 훈련을 기대할 수 없기 때문에 BBR모듈의 smooth L1 함수도 버려지지 않고 여전히 사용된다.

Evaluation Results

다음과 같은 baseline 모델들과의 비교를 진행했다.

Region-growth : 특정 셀부터 8방향으로 접한 모든 셀로 영역을 가능한 확장시키고 확장이 끝났을 때의 영역을 테이블로 추출한다.
Region-growth + SVM : Regtion-growth 방식으로 추출한 테이블이 실제 테이블인지 아닌지 예측하는 classifier를 학습시킨다.
Mask R-CNN : 당시에 sota를 달성한 object detection 모델이다.
YOLO-v3 : 당시에 sota를 달성한 real time object detection 모델이다.
Faster R-CNN : 당시에 sota를 달성한 real time object detection 모델이고 TableSense의 base 알고리즘이다. YOLO보단 느린 대신 정확도는 조금 더 높다.

측정은 EoB-0와 EoB-2를 기준으로 했다. EoB-0는 EoB가 0인 경우만 예측 성공으로 인정하는 것이고, EoB-2는 2이하 까지 예측 성공으로 인정하는 것이다. 결과는 논문에 나와 있듯이 TableSense가 다른 baseline에 비해 압도적으로 높은 recall/precision을 기록했다.

Baseline Comparison

또한 cell featurization 과정에서 특정 feature를 제외시켰을 때보다 모든 feature를 전부 사용했을때 성능이 가장 좋았다고 한다.

모델이 훈련 중 스스로 불확실한 데이터에 대해서만 사람에게 라벨링을 요구하고 특정 조건을 만족하는 데이터는 스스로 라벨링 하도록 하는 Active Learning은 훈련 횟수가 증가함에 따라 오류가 점차 줄어드는 경향을 보임으로 제시한 학습법의 효율성을 입증했다고 한다.