Eunhaa Tech Developer Blog

검색 증강 생성(RAG) - PDF RAG 학습 앱 (2)

EunHaa — Sun, 21 Jun 2026 00:26:04 +0900

이전 시간에 배운 RAG 기본 개념을 이용해 PDF RAG 분석 애플리케이션을 만들어보자.

이번엔 gradio 프레임워크를 이용해서 Python에서만 구성해볼 것이다.

먼저 gradio로 화면단만 구성한다. 사용된 코드는 아래와 같다.

import gradio as gr

# 화면 구성

with gr.Blocks() as app:
    gr.Markdown("# PDF RAG 학습 앱")

    with gr.Tabs():
        with gr.Tab("1단계 - PDF & Chunk 확인"):
            # 파일 업로드 컴포넌트
            pdf_input = gr.File(label="PDF 업로드", file_types=[".pdf"])
            btn1 = gr.Button("분석 시작")

            textConfig1 = [
                {"label": "총 페이지수", "lines": 1},
                {"label": "첫 페이지 내용", "lines": 20},
                {"label": "총 chunk 수", "lines": 1},
                {"label": "첫번째 chunk", "lines": 10},
                {"label": "첫번째 chunk_metadata", "lines": 5},
            ]

            # Textbox 5개
            text_list1 = [gr.Textbox(**chunk1) for chunk1 in textConfig1]

            btn1.click(fn=process_pdf, inputs=[pdf_input], outputs=text_list1)
        with gr.Tab("2단계 - RAG QA"):
            pdf_input2 = gr.File(label="PDF 업로드")
            q_input = gr.Textbox(label="질문 입력", lines=1)
            btn2 = gr.Button("질문하기")

            textConfig2 = [
                {"label": "검색된 Chunk", "lines": 20},
                {"label": "최종 답변", "lines": 10},
            ]

            text_list2 = [gr.Textbox(**chunk2) for chunk2 in textConfig2]

            btn2.click(fn=rag_chat, inputs=[pdf_input2, q_input], outputs=text_list2)
app.launch()

1단계 : PDF & Chunk 확인하는 탭

# 1단계
def process_pdf(pdf_file):
    if pdf_file is None:
        return ("PDF 파일을 업로드 해주세요", "", "", "", "")

    # PDF 로드
    loader = PyPDFLoader(pdf_file)
    docs = loader.load()

    # 총 페이지 수
    total_pages = len(docs)

    # 첫 페이지 내용
    first_page_content = docs[0].page_content[:1000]

    # 총 chunk 수
    splitter = RecursiveCharacterTextSplitter(chunk_size=300, chunk_overlap=30)
    chunks = splitter.split_documents(docs)
    total_chunks = len(chunks)

    # 첫번째 chunk
    first_chunk = chunks[0].page_content

    # 첫번쨰 chunk metadata
    first_chunk_metadata = chunks[0].metadata

    return (
        total_pages,
        first_page_content,
        total_chunks,
        first_chunk,
        first_chunk_metadata,
    )

2단계 : RAG QA

# 모델 LLM, Embedding
ollama_embedding = OllamaEmbeddings(model="nomic-embed-text-v2-moe")
llm = ChatOllama(model="qwen2.5")

# 2단계
def rag_chat(pdf_file, question):
    if pdf_file is None:
        return ("PDF 파일을 업로드 해주세요", "", "", "", "")

    # PDF 로드
    loader = PyPDFLoader(pdf_file)
    docs = loader.load()

    # TextSplitter
    splitter = RecursiveCharacterTextSplitter(chunk_size=300, chunk_overlap=30)
    split_docs = splitter.split_documents(docs)

    # embedding
    faiss_store = FAISS.from_documents(documents=split_docs, embedding=ollama_embedding)

    # retriever
    retriever = faiss_store.as_retriever(search_kwargs={"k": 3})

    retriever_docs = retriever.invoke(question)

    # 컨텍스트 생성
    context = "\n\n".join([doc.page_content for doc in result])

    # prompt
    system_message = """\
    당신은 pdf 기반 RAG AI입니다.
    다음 문서를 참고하여 질문에 답변하세요.

    문서:
    {context}

    질문:
    {question}
    """

    prompt = ChatPromptTemplate.from_template(system_message)

    # RAG Chain
    chain = prompt | llm | StrOutputParser()

    answer = chain.invoke({"context": context, "question": question})

    # 답변, rag 결과 반환
    retrieved_text = ""

    for i, doc in enumerate(retriever_docs):
        retrieved_text += f"""
        [검색 문서 {i}]

        내용 :
        {doc.page_content}

        메타데이터:
        {doc.metadata}
        {"=" * 50}
        """

    return retrieved_text, answer

검색 증강 생성(RAG) - 개념 (1)

EunHaa — Sat, 20 Jun 2026 21:58:33 +0900

1. RAG

올라마(Ollama)에서 임베딩 개념을 이야기하면서 RAG 개념이 시작되었다.

임베딩 모델을 통해 어떤 input을 고차원의 숫자 리스트로 바꾸어줬고,

이 임베딩된 숫자를 통해 RAG라는 것을 할 수 있다고 공부했었다.

여기서 RAG는 Retrieval Augmented Generation의 약자로써, 검색 증강 생성을 의미한다.

생성형 AI가 임베딩한 외부 문서를 검색한 뒤 그 내용을 기반으로 답변한다.

1) 문서 처리 : DocumentLoader

대표적으로, PyPDFLoader, JSONLoader, TextLoader, WebBaseLoader 등이 있다.

1. PyPDFLoader

from langchain_community.document_loaders import PyPDFLoader

loader = PyPDFLoader("../data/서울대 미대.pdf")
docs = loader.load()

print(f"총 페이지 수 : {len(docs)}")
print(f"첫 페이지 텍스트 : {docs[0].page_content[:100]}")
print(f"메타 데이타 : {docs[0].metadata}")

2. CSVLoader

from langchain_community.document_loaders import CSVLoader

csv_loader = CSVLoader("../data/restaurant_reviews.csv", encoding="utf-8", csv_args={'delimiter': ","})
csv_docs = csv_loader.load()

print(f"총 페이지 수 : {len(csv_docs)}")
print(f"첫 페이지 텍스트 : {csv_docs[0].page_content[:100]}")
print(f"메타 데이타 : {csv_docs[0].metadata}")

3. WebBaseLoader

# BeautifulSoup4 라이브러리 필요
from langchain_community.document_loaders import WebBaseLoader

web_loader = WebBaseLoader(web_paths=['https://python.org','https://langchain.com'])
web_docs = web_loader.load()

print(f"총 페이지 수 : {len(web_docs)}")
print(f"첫 페이지 텍스트 : {web_docs[0].page_content[:100]}")
print(f"메타 데이타 : {web_docs[0].metadata}")

4. DirectoryLoader

from langchain_community.document_loaders import DirectoryLoader

dir_loader = DirectoryLoader(path="../data", glob="**/*.pdf", loader_cls=PyPDFLoader, show_progress=True)
dir_docs = dir_loader.load()

print(f"총 페이지 수 : {len(dir_docs)}")
print(f"첫 페이지 텍스트 : {dir_docs[0].page_content[:100]}")
print(f"메타 데이타 : {dir_docs[0].metadata}")

5. 유튜브 스크립트 가져오기 예제

from youtube_transcript_api import YouTubeTranscriptApi

video_id = 'VRQzJMPf1ug'

yt_api = YouTubeTranscriptApi()

transcript = yt_api.fetch(video_id, languages=['ko'])

for idx, t in enumerate(transcript, 1):
    print(f"{idx} : {t.text}")
    print(f"{idx} : {t.start}")
    print(f"{idx} : {t.duration}")

text = " ".join(t.text for t in transcript)

print(text)

doc = Document(page_content=text, metadata={
    "source": f"https://www.youtube.com/watch?v={video_id}",
    "video_id": video_id
})

print(docs.page_content[:100])
print(docs.metadata)

2) 문서 쪼개기 : RecursiveCharacterTextSplitter

일반적인 RAG에서 주로 사용하며, LLM의 Context Window이 제한이 있어

문서를 한 번에 넣을 수 없으므로 TextSplitter 이용해 적절한 크기의 청크로 분할한다.

chunk_size (청크 최대 크기), chunk_overlap (청크 겹치는 부분 - 문맥 유지) 개념이 있다.

from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter

# 1. 문서 로드
loader = PyPDFLoader("../data/서울대 미대.pdf")
docs = loader.load()

# 2. 문서 분할
splitter = RecursiveCharacterTextSplitter(
    chunk_size=500, chunk_overlap=50, length_function=len, separators=['\n\n','\n',' ','']
)

chunks = splitter.split_documents(docs)

print(f"원본 페이지 수 : {len(docs)}")
print(f"분할한 청크 수 : {len(chunks)}")
print(f"첫 청크 길이 : {len(chunks[0].page_content)}")
print(f"첫 청크 내용 : {chunks[0].page_content}")
print(f"메타 데이타 : {chunks[0].metadata}")

3) 청크 파라미터

overlap이 0일 경우, 앞의 문맥에 대해 알지 못해

LLM에게 앞선 컨텍스트를 전달하지 못하는 문제를 확인하기 위함이다.

overlap이 많을수록 앞선 내용에 대해 기억하는 경우가 많을 것이다.

# chunk 파라미터 비교

text = "파이썬은 1991년에 발표된 언어이다" * 20

configs = [
    { "chunk_size": 100, "chunk_overlap": 0},
    { "chunk_size": 100, "chunk_overlap": 20},
    { "chunk_size": 200, "chunk_overlap": 50}
]

for cfg in configs:
    sp = RecursiveCharacterTextSplitter(**cfg)
    chunks = sp.split_text(text)
    print(f"size={cfg['chunk_size']}, overlap={cfg['chunk_overlap']}")
    print(f"{len(chunks)}개 청크, 첫 청크 : {chunks[0][:30]}....")
    if len(chunks) > 1:
        print(f"첫 청크 끝 : '{chunks[0][-20:]}'")
        print(f"둘째 청크 시작 : '{chunks[1][:20]}'")

4) 임베딩(Embedding)

텍스트를 고차원 벡터로 변환하는 과정이며, 의미가 비슷할수록 벡터가 가깝다.

RAG에서 임베딩은 다음과 같을 때 사용한다.

문서 청크를 저장할 때 사용
질문 검색할 때 사용

from langchain_ollama import OllamaEmbeddings

ollama_embedding = OllamaEmbeddings(model='nomic-embed-text-v2-moe')

# 단일 텍스트 쿼리
vector = ollama_embedding.embed_query("파이썬이란?")

print(f"벡터 차원 : {len(vector)}")
print(f"첫 5개 값 : {vector[:5]}")

texts = ["파이썬이란?", "자바란 무엇인가?", "오늘 날씨는?"]

# 여러 개 쿼리
vectors = ollama_embedding.embed_documents(texts)

print(f"임베딩 문서 수 : {len(vectors)}")

이제 이 벡터값을 가지고 벡터 유사도를 추출해 볼수 있다. (여기선 코사인 유사도 사용)

# 벡터 유사도
import numpy as np

def cosine_similarity(a, b):
    a, b = np.array(a), np.array(b)
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

vec1 = ollama_embedding.embed_query("파이썬이란?")
vec2 = ollama_embedding.embed_query("python이란?")
vec3 = ollama_embedding.embed_query("오늘 저녁 뭐 먹지?")

print(f"파이썬 vs Python : {cosine_similarity(vec1, vec2):.3f}")
print(f"파이썬 vs 저녁 : {cosine_similarity(vec1, vec3):.3f}")

5) 벡터 DB

메모리가 아닌 DB에 벡터 값을 벡터 저장소에 저장한다. 여기서는 chromaDB와 faiss를 사용할 것이다.

chromaDB

from langchain_chroma import Chroma

# 1. 문서 로드
loader = PyPDFLoader("../data/서울대 미대.pdf")
docs = loader.load()

# 2. 문서 분할
splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50, length_function=len, separators=['\n\n','\n',' ',''])

chunks = splitter.split_documents(docs)

# 3. 임베딩 처리
ollama_embedding = OllamaEmbeddings(model='nomic-embed-text-v2-moe')

# 4. 벡터 스토어에 저장(chromaDB)
vector_store = Chroma.from_documents(
    documents=chunks,
    embedding=ollama_embedding,
    persist_directory="./db/chroma_db",
    collection_name="my_docs"
)

# 5. 검색(Retrieval)
# 질문도 벡터로 변경해야 함, 유사도 높은 걸로 몇개 추출할 것인지 설정

results = vector_store.similarity_search("근로장학생 신청 절차는?",k=3)

for idx, doc in enumerate(results, 1):
    print(f"\n[결과] {idx} 출처 : {doc.metadata}")
    print(doc.page_content[:300])

# DB 확인

data = vector_store.get()

print(data['documents'][0][:300])
print(data['metadatas'][0])
print(f"청크 개수 : {vector_store._collection.count()}")

# 저장 후 불러오기
chromadb = Chroma(persist_directory="./db/chroma_db", embedding_function=ollama_embedding, collection_name="my_docs")

faiss

# faiss
from langchain_community.vectorstores import FAISS

# 1. 문서 로드
loader = PyPDFLoader("../data/서울대 미대.pdf")
docs = loader.load()

# 2. 문서 분할
splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50, length_function=len, separators=['\n\n','\n',' ',''])

chunks = splitter.split_documents(docs)

# 3. 임베딩 처리
ollama_embedding = OllamaEmbeddings(model='nomic-embed-text-v2-moe')

# 벡터 스토어에 저장(faiss)
faiss_vector_store = FAISS.from_documents(documents=chunks, embedding=ollama_embedding)

results_score = faiss_vector_store.similarity_search_with_score("수강신청 내역 확인 방법은?",k=3)

for doc, score in results_score:
    print(f"유사도 : {score:.4f}, {doc.page_content[:20]}")

# 로컬 저장
faiss_vector_store.save_local("./db/faiss_index")

# 저장 후 불러오기
faissdb = FAISS.load_local("./db/faiss_index",embeddings=ollama_embedding, allow_dangerous_deserialization=True)

6) LLM에게 전송

추가적으로 위에서 나온 결과를 LLM에게 전송해야 한다. (다듬는 과정)

# 1. 문서 로드
pdf_doc = PyPDFLoader("../data/Summary of ChatGPTGPT-4 Research.pdf")
loader = pdf_doc.load()

# 2. 문서 분할
splitter = RecursiveCharacterTextSplitter(chunk_size=500,chunk_overlap=50)
chunks = splitter.split_documents(loader)

# 3. 인덱싱 (임베딩)
embeddings = OllamaEmbeddings(model='nomic-embed-text-v2-moe')

# 4. 벡터 스토어(chromaDB)
chroma_store = Chroma.from_documents(documents=chunks,embedding=embeddings,persist_directory="./db/chroma_db", collection_name="research")

# 5. as_retriever() : 벡터 스토어를 검색 가능한 Retriever 형태로 변환 (랭체인과 연동)
retriever = chroma_store.as_retriever(search_type="similarity", search_kwargs={"k": 3})

system_message = """\
다음 컨텍스트를 참고하여 질문에 답하세요.
컨텍스트에 없는 내용은 모른다고 답하세요.

컨텍스트:
{context}

"""

# 6. RAG 프롬프트 생성
prompt = ChatPromptTemplate.from_messages([
    ("system",system_message),
    ("human","{question}")
])

qwen_llm = ChatOllama(model='qwen2.5')

def format_docs(docs):
    return "\n\n".join(doc.page_content for doc in docs)

rag_chain = {
    "context": retriever | format_docs,
    "question": RunnablePassthrough()
} | prompt | qwen_llm | StrOutputParser()

ans = rag_chain.invoke("Where can I use ChatGPT?")

print(ans)

출처 페이지를 함께 병렬 계산하고 싶은 경우 아래와 같이 처리한다.

# 출처 페이지 정보와 답변 함께 반환
def format_docs_with_source(docs):
    result = []
    for doc in docs:
        src = doc.metadata.get("source","알 수 없음")
        page = doc.metadata.get("page","")
        result.append(f"[출처 : {src} p.{page}\n{doc.page_content}]")
    return "\n\n".join(result)
    
rag_chain = {
    "context": retriever | format_docs_with_source,
    "question": RunnablePassthrough()
} | prompt | qwen_llm | StrOutputParser()

rag_with_source = RunnableParallel(answer=rag_chain, sources=retriever)
result = rag_with_source.invoke("where can I use ChatGPT?")

print("======답변======")
print(result['answer'])
print("======출처======")
for doc in result['sources']:
    print(f" - {doc.metadata.get('source')} p.{doc.metadata.get('page','')}")

랭체인(LangChain) - 심화 내용 (3)

EunHaa — Sat, 20 Jun 2026 15:42:03 +0900

1. RunnableSequence

파이프라인 문법에서 자세히 보면, RunnableSequence라고 하는 것을 내부적으로 생성한다.

그 중에는 다음과 같은 종류가 있다.

RunnablePassthrough : 입력을 통과시켜 다른 키와 병합
RunnableLambda : 체인을 파이썬 함수와 연동
RunnableParallel : 여러 체인을 동시에 실행하고 결과를 dict 구조로 병합
.assign() : 체인 중간에 새 키를 추가하는 메소드

1) RunnableLambda

chain은 RunnableSequence를 생성하기 때문에 일반 파이썬 함수는 바로 연결 불가하다.

이럴 때 일반 함수를 감싸는 용도로 사용한다.

from langchain_core.runnables import RunnableLambda

def upper(text):
    return text.upper()

prompt = ChatPromptTemplate.from_messages([
    ("system","당신은 언어 전문가입니다."),
    ("human","{topic}에 대해 설명해줘.")
])

chain = prompt | qwen_llm | StrOutputParser() | RunnableLambda(upper)

result = chain.invoke({ "topic" : "python" })

print(result)

# 후처리 함수
def remove_newline(text):
    return text.replace("\n"," ")

prompt = ChatPromptTemplate.from_template("{question}에 대해 답변해줘.")

chain = prompt | qwen_llm | StrOutputParser() | RunnableLambda(remove_newline)

print(chain.invoke({ "question": "Python의 리스트"}))

2) RunnablePassThrough

변수에 들어온 값이 RunnablePassthrough()에 전달되어 통과되는 개념이다.

from langchain_core.runnables import RunnablePassthrough

prompt = ChatPromptTemplate.from_template("{question}에 대해 답변해줘.")

chain = (
    { "question": RunnablePassthrough(), "answer": prompt | qwen_llm | StrOutputParser()} | RunnableLambda(lambda x: f"Q: {x['question']}\nA:{x['answer']}")
)

result = chain.invoke("파이썬이란?")
print(result)

3) RunnableParallel

여러 체인을 호출할 때 사용하며, 병렬처리 성능은 실제 컴퓨터 자원에 영향을 받는다.

from langchain_core.runnables import RunnableParallel

parser = StrOutputParser()

# 요약
summary_chain = ChatPromptTemplate.from_template("다음 텍스트를 한 문장으로 요약하세요. 한국어로. : {text}") | qwen_llm | parser

# 키워드 추출
keyword_chain = ChatPromptTemplate.from_template("다음 텍스트의 핵심 키워드 3개를 ,로 나열해줘 : {text}") | qwen_llm | parser

parallel_chain = RunnableParallel(summary=summary_chain,keyword=keyword_chain)

result = parallel_chain.invoke({ "text" : "인공지능은 인간의 지능을 모방하는 기술로..." })

print(result)

4) assign()

analysis_chain = ChatPromptTemplate.from_template("다음 리뷰를 분석해줘 : {review}") | qwen_llm | parser | {"text": RunnablePassthrough() }

full_chain = (RunnablePassthrough.assign(summary=ChatPromptTemplate.from_template("{review} 한 줄 요약") | qwen_llm | parser)
                                 .assign(sentiment=ChatPromptTemplate.from_template("{review} 감정 분석 : 긍정, 부정, 중립 중 하나만") | qwen_llm | parser))
                                 .assign(analysis=analysis_chain)

result = full_chain.invoke({"review": "정말 맛있는 음식이었어요."})

print(result)

2. 멀티 턴 대화

LLM은 기본적으로 Stateless 특성을 가진다. 이전 내용을 유지하는 방법을 배워보자.

이력 관리를 위해 messages 리스트에 누적이 필요하다. 그리고 그 내용을 보내줘야 한다.

from langchain_core.messages import HumanMessage, SystemMessage, AIMessage

messages = [
    SystemMessage(content="당신은 친절한 파이썬 튜터입니다. 한국어로 답변하세요.")
]

def chat(user_input):
    messages.append(HumanMessage(user_input))
    response = qwen_llm.invoke(messages)
    messages.append(AIMessage(response.content))
    return response.content

print(chat("파이썬이란?"))
print(chat("방금 말한 내용의 장점 3가지는?"))
print(chat("그 중 첫번째 장점에 대한 예시 코드 작성해줘."))
print(chat("두 번째 장점에 대한 예시 코드 작성해줘."))

for m in messages:
    print(f"[{m.type}] {m.content[:40]}...")

하지만, 이렇게 하지 않고, 자동으로 이력 관리를 해주는 개념이 나온다.

이것이 RunnableWithMessageHistory이다. 세션별로 대화 이력 관리를 하는 방식이다.

일단, InMemoryChatMessageHistory 객체를 이용한다. (메모리에 대화를 저장)

from langchain_core.chat_history import InMemoryChatMessageHistory

history = InMemoryChatMessageHistory()

def chat(user_input):
    history.add_user_message(user_input)
    response = qwen_llm.invoke(history.messages) # 전체 대화 맥락 보내주기
    history.add_ai_message(response.content)
    return response.content

chat("파이썬이란?")
chat("방금 말한 내용의 장점 3가지는?")
chat("그 중 첫번째 장점에 대한 예시 코드 작성해줘.")
chat("두 번째 장점에 대한 예시 코드 작성해줘.")

for m in history.message:
    print(f"[{m.type}] {m.content[:40]}...")

그러나 이 방식에는 한계가 있다. 만약 메모리에다가 계속 쌓는다면, 메모리 부하가 생길지도 모른다.

그리고 모델의 한계 컨텍스트 크기도 넘어갈 수 있다. (컨텍스트 오버플로우)

그전에 먼저 세션에 저장해서 기록하는 방법부터 알아보자. (여러 사람과 대화하는 것을 고민)

그것이 RunnableWithMessageHistory 객체이다.

# 여러 사람과 대화하는 부분 저장 => 세션별로 저장

store = {}

def get_session_history(session_id) -> BaseChatMessageHistory:
    if session_id not in store:
        store[session_id] = InMemoryChatMessageHistory()
    return store[session_id]

# 프롬프트 생성
prompt = ChatPromptTemplate.from_messages([
    ("system", "당신은 {role}입니다. 한국어로 답변하세요."),
    MessagesPlaceholder(variable_name="history"), # 대화 이력이 삽입될 위치임을 알려줌
    ("human", "{input}")
])

# LLM 생성 문구
qwen_llm = ChatOllama(model='qwen2.5')

# 체인 생성
chain = prompt | qwen_llm | StrOutputParser()

# 1. session_id 이력 조회

# 2. 없다면 history 키에 이력 삽입 -> prompt -> llm 실행 -> 대화 나눈 이력을 history에 추가

with_history = RunnableWithMessageHistory(chain, get_session_history=get_session_history, input_messages_key="input", history_messages_key="history")

# 세션 생성
config_a = { "configurable": {"session_id": "user_alice"}}
config_b = { "configurable": {"session_id": "user_bob"}}

res1 = with_history.invoke({ "role": "파이썬 튜터", "input": "안녕"}, config=config_a)
res2 = with_history.invoke({ "role": "파이썬 튜터", "input": "내 이름은 Alice야."}, config=config_a)
res4 = with_history.invoke({ "role": "파이썬 튜터", "input": "내 이름 기억해?"}, config=config_a)

res3 = with_history.invoke({ "role": "파이썬 튜터", "input": "파이썬 변수 타입은?"}, config=config_b)


print("Alice ", res2)
print("Alice ", res4)

컨텍스트 관리를 위해 개선하는 방향을 알아보자.

1) 최근 K 턴만 유지하기 (K=8)

def get_session_history(session_id) -> BaseChatMessageHistory:
    if session_id not in store:
        store[session_id] = InMemoryChatMessageHistory()

    # 최근 몇개만 유지
    history = store[session_id]

    if len(history.messages) > 8:
        history.messages[:] = history.messages[-8:]

    return history

with_history = RunnableWithMessageHistory(chain, get_session_history=get_session_history, input_messages_key="input", history_messages_key="history")

for i in range(10):
    with_history.invoke({ "role": "파이썬 튜터", "input": f'{i}번째 질문'}, config=config_a)

history = get_session_history("user_alice")

for msg in history.messages:
    print(msg)

print(len(history.messages))

2) 오래된 내용은 압축해서 보여주기

# 2. 오래된 대화 요약

store = {}

# 요약 프롬프트
summary_prompt = ChatPromptTemplate.from_messages([
    ("system", "다음 대화 내용을 핵심만 3문장 이내로 한국어로 요약하세요."),
    ("human", "{conversation}")
])

# 요약 체인
summaries_chain = summary_prompt | qwen_llm | StrOutputParser()

# 요약 기능이 포함된 클래스
class SummarizedChatHistory(InMemoryChatMessageHistory):
    """대화가 max_turns 초과 시 오래된 메시지 요약하기"""
    max_turns: int = Field(default=6)
    summary: str = Field(default="")

    def _maybe_summarize(self):
        if len(self.messages) > self.max_turns * 2:
            # 오래된 내용 찾기
            cutoff = len(self.messages) // 2
            old_msgs = self.messages[:cutoff]
            new_msgs = self.messages[cutoff:]

            # 요약할 텍스트 구성
            conv_text = "\n".join(f"{'사용자' if isinstance(m, HumanMessage) else "AI"}: {m.content}" for m in old_msgs)

            # 기존 요약이 있으며 함께 포함
            if self.summary:
                conv_text = f"[이전 요약]\n{self.summary}\n\n[새 대화]\n{conv_text}"

            # 요약 실행
            self.summary = summary_chain.invoke({ "conversation": conv_text })

            # 오래된 메시지 제거 후 요약본 SystemMessage로 앞에 삽입
            self.messages.clear()
            self.messages.append(SystemMessage(content=f"[이전 대화 요약]\n{self.summary}"))
            self.messages.extend(new_msgs)

    def add_message(self, message):
        super().add_message(message)
        self._maybe_summarize()
        

def get_session_history(session_id) -> SummarizedChatHistory:
    if session_id not in store:
        store[session_id] = SummarizedChatHistory(max_turns=6)
    
    return store[session_id]

prompt = ChatPromptTemplate.from_messages([
    ("system", "당신은 친절한 AI 어시스턴트입니다. 한국어로 답변하세요"),
    MessagesPlaceholder(variable_name="history"),
    ("human", "{input}")
])

chain = prompt | qwen_llm | StrOutputParser()

with_history = RunnableWithMessageHistory(chain, get_session_history=get_session_history, input_messages_key="input", history_messages_key="history")

# 세션 임의 생성
cfg_a = {"configurable": { "session_id": "user_alice"}}

# 임의 대화 생성
questions = [
    "파이썬이란?",
    "방금 설명한 파이썬의 장점은?",
    "단점은 뭐야?",
    "어떤 분야에 많이 쓰여?",
    "입문자에게 추천하는 학습 순서는?",
    "좋은 파이썬 책 추천해줘",
    "무료로 배울 수 있는 사이트는?",
    "이전에 내가 뭘 물어봤는지 기억해?"
]

for i, q in enumerate(questions, i):
    response = with_history.invoke({"input": q}, config=cfg_a)
    print(f"\n{i}턴 Q:{q}")
    print(f"\n      A: {response[:60]}....")

    # 요약 여부 확인
    history = get_session_history("user_alice")
    if history.summary:
        print(f"\n 요약 처리! 현재 메시지 수 {len(history.messages)}")
        print(f"\n 요약 내용 {history.summary[:80]}....")

3) 요리 전문가 챗봇 백엔드 수정하기 (수작업X, 메시지 히스토리 객체 이용)

from fastapi import APIRouter
from app.schemas.chat import ChatRequest, ChatResponse, ChatPairResponse, LLMChatOutput
from langchain_ollama import ChatOllama
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.chat_history import (
    InMemoryChatMessageHistory,
    BaseChatMessageHistory,
)
from langchain_core.messages import HumanMessage, AIMessage
from langchain_core.runnables.history import RunnableWithMessageHistory

router = APIRouter()

store = {}


def chain_return():
    structured_llm = ChatOllama(model="qwen2.5")

    system_prompt = """
    당신은 20년 경력의 전문 세프이자, 요리 연구가입니다.
    사용자의 요리 질문에 대해 재료, 조리방법, 실패 방지 팁, 대체 재료를 포함하여 답변하세요.
    항상 한국어로 답변하세요.
    """

    template = ChatPromptTemplate.from_messages(
        [
            ("system", system_prompt),
            MessagesPlaceholder(variable_name="history"),
            ("human", "{question}"),
        ]
    )

    chain = template | structured_llm

    return RunnableWithMessageHistory(
        chain,
        get_session_history,
        input_messages_key="question",
        history_messages_key="history",
    )


def get_session_history(session_id: int) -> BaseChatMessageHistory:
    if session_id not in store:
        store[session_id] = InMemoryChatMessageHistory()
    return store[session_id]


@router.post("/chat-input", response_model=ChatPairResponse)
async def chat(body: ChatRequest) -> str:
    session_id = body.session_id
    message = body.message

    chain = chain_return()

    cfg_user = {"configurable": {"session_id": session_id}}

    # llm_chat_output
    response = chain.invoke({"question": message}, config=cfg_user)

    chat_user_response = ChatResponse(
        session_id=session_id, sender="me", content=message
    )

    chat_bot_response = ChatResponse(
        session_id=session_id + 1, sender="bot", content=response.content
    )

    return ChatPairResponse(chats=[chat_user_response, chat_bot_response])

3. 번외 : 허깅 페이스 모델 사용하기

허깅 페이스에서 Models 항목에서 이 옵션을 체크한다. (외부에서 불러다 쓸 수 있는 모델)

우리는 Qwen2.5-Coder-7B-Instruct 모델을 사용해보자.

모델 상세페이지에 들어가 View Code Snippets 클릭한다.

우리는 openai를 이용하여 접근할 것인데, 코드 보면 알다시피 HF_TOKEN이 필요하다.

이것은 Access Token 탭에 들어가 발급받는다.

load_dotenv()

hf_token = os.getenv("HF_TOKEN")

client = OpenAI(
    base_url="https://router.huggingface.co/v1",
    api_key=hf_token,
)

completion = client.chat.completions.create(
    model="Qwen/Qwen2.5-Coder-7B-Instruct:nscale",
    messages=[
        {
            "role": "user",
            "content": "What is the capital of France?"
        }
    ],
)

그리고, langchain에서도 openai 항목을 지원한다.

from langchain_openai import ChatOpenAI

hugging_llm = ChatOpenAI(model="Qwen/Qwen2.5-Coder-7B-Instruct",api_key=hf_token,base_url="https://router.huggingface.co/v1")

response = hugging_llm.invoke("생성형 AI 설명해줘.")

print(response.content)

랭체인(LangChain) - 요리 전문가 챗봇 실습 (2)

EunHaa — Sat, 20 Jun 2026 01:19:19 +0900

다음 조건으로 요리 전문가 챗봇 앱을 제작해보자.

일단 UI 먼저 구성해보자. 다음과 같이 구성한다.

src/app/food/page.tsx

import ChatBotDiv from "@/components/food/ChatBotDiv";

export default function FoodPage() {
    return (
        <main className="w-full h-screen bg-[#ece0cb]">
            <div id="wrap" className="max-w-lg mx-auto h-full bg-[#f6eddf]">
                <ChatBotDiv />
            </div>
        </main>
    )
}

src/app/components/food/ChatBotDiv.tsx

"use client";

import { useEffect, useState } from "react";
import { useRouter } from "next/navigation";
import { IoArrowForwardSharp } from "react-icons/io5";
import BotChatting from "./BotChatting";
import ChatBotProfile from "./ChatBotProfile";
import HumanChatting from "./HumanChatting";



export interface ChatContent {
    session_id: number;
    sender: "bot" | "me";
    content: string;
    added_button_list: string[] | null
}

export default function ChatBotDiv() {

    const [inputText, setInputText] = useState<string>("");

    const [chatContents, setChatContents] = useState<ChatContent[]>([{ session_id: 0, sender: "bot", content: "안녕~ 어서와요 ^^ 오늘은 뭐가 드시고 싶어요?|냉장고에 뭐가 있는지 말하면 딱 맞는 메뉴 말해줄게요.", added_button_list: ["10분 안에 되는 메뉴", "자취 첫 요리 추천", "계란으로 뭐 해먹지?"] }]);

    const [showedManyButton, setShowedManyButton] = useState<boolean>(true);

    const changeShowed = (bool: boolean) => {
        setShowedManyButton(bool)
    }

    const router = useRouter();

    const changeInput = (e: React.ChangeEvent<HTMLInputElement>) => {
        setInputText(e.target.value)
    }


    return (
        <div id="chatBotDiv" className="w-full h-full relative">
            <div id="chatBotHeader" className="w-full h-[70px] relative box-border bg-[#faf3e9] flex items-center gap-[10px] px-[16px] border-b-[1px] border-[#e6e0d2] ">
                <ChatBotProfile />
                <div id="chatBotInfo" className="flex flex-col justify-between">
                    <span className="font-[800]">정이 이모</span>
                    <div className="status flex items-center gap-[5px] text-[#9a7b52] text-[14px]">
                        <span className="block w-[8px] h-[8px] rounded-full bg-[#7fa968]"></span>
                        <span>온라인</span>
                        <span>오늘 뭐 해먹지?</span>
                    </div>
                </div>
                <button className="text-[14px] absolute right-[20px] cursor-pointer" onClick={() => router.push("/")}>돌아가기</button>
            </div>
            <div id="chatBotBody" className="w-full h-[calc(100%-150px)] overflow-y-auto p-[16px] flex flex-col gap-[20px]">
                {
                    chatContents.map((chat: ChatContent) => (
                        chat.sender === 'bot' ? <BotChatting key={chat.session_id} chatting={chat} showed={showedManyButton} changeShowed={changeShowed} /> : <HumanChatting key={chat.session_id} chatting={chat} />
                    ))
                }
            </div>
            <div id="chatBotFooter" className="w-full h-[80px] bg-[#f9f2e8] absolute bottom-0 left-0 p-[20px] box-border">
                <div id="inputWrap" className="w-full h-[50px] box-border px-[10px] rounded-[20px] bg-[#fffdf8] border-[#7a5636] border-[1px] border-[#7a5636] flex items-center gap-[10px]">
                    <input type="text" className="flex-1 h-full outline-none px-[20px] placeholder:text-[#c9baa7]" placeholder="냉장고에 뭐가 있어요?" value={inputText} onChange={changeInput} />
                    <button className="w-[36px] h-[36px] rounded-full bg-[#c98a52] flex justify-center items-center disabled:opacity-45 cursor-pointer" disabled={!inputText.trim()}>
                        <IoArrowForwardSharp className="text-white text-[20px]" />
                    </button>
                </div>
            </div>
        </div>
    )
}

src/app/components/food/BotChatting.tsx

import { type ChatContent } from "./ChatBotDiv";
import ChatBotProfile from "./ChatBotProfile";

export default function BotChatting({ chatting, showed, changeShowed }: { chatting: ChatContent, showed: boolean, changeShowed: (bool: boolean) => void }) {
    return (
        <div className="bot__chat flex flex-wrap gap-[10px]">
            <ChatBotProfile className="self-end" />
            <div className="bot__chat__content text-[15px] p-[18px] bg-[#fffdf8] rounded-[20px_20px_20px_6px] font-[400]">
                {chatting.content.includes("|") ? chatting.content.split("|").map((content: string, idx: number) => (<span key={idx}>{content}<br /></span>)) : <span>{chatting.content}</span>}
            </div>
        </div>
    )
}

src/app/components/food/HumanChatting.tsx

import { type ChatContent } from "./ChatBotDiv";

export default function HumanChatting({ chatting }: { chatting: ChatContent }) {
    return (
        <div className="human__chat__content rounded-[20px_20px_6px_20px] inline-block p-[18px] bg-[#c98a52] text-white text-[15px] font-[400] self-end">{chatting.content}</div>
    )
}

그리고 나서 조건대로 FastAPI 백엔드를 구성한다.

라우터는 다음과 같이 구성한다.

조건에서는 StrOutputParser를 이용하라고 했으나, 내용 특성상 Pydantic를 이용하자.

from fastapi import APIRouter
from app.schemas.chat import ChatRequest, ChatResponse, ChatPairResponse, LLMChatOutput
from langchain_ollama import ChatOllama
from langchain_core.output_parsers import PydanticOutputParser
from langchain_core.prompts import ChatPromptTemplate

router = APIRouter()

qwen_llm = ChatOllama(model="qwen2.5")


@router.post("/chat-input", response_model=ChatPairResponse)
async def chat(body: ChatRequest) -> ChatPairResponse:
    session_id = body.session_id
    message = body.message

    parser = PydanticOutputParser(pydantic_object=LLMChatOutput)

    prompt = ChatPromptTemplate.from_messages(
        [
            (
                "system",
                "당신은 사용자의 냉장고 재료를 바탕으로 요리를 추천해주는 AI 어시스턴트입니다. 반드시 아래 형식에 맞게 JSON으로만 답변하세요. 단, content 항목은 적절히 | 으로 구분해주세요. : {format_instructions}",
            ),
            (
                "human",
                "냉장고에 있는 재료 또는 원하는 음식 : {message}",
            ),
        ]
    ).partial(format_instructions=parser.get_format_instructions())

    chain = prompt | qwen_llm | parser

    llm_output: LLMChatOutput = chain.invoke({"message": message})

    human_chat = ChatResponse(
        session_id=session_id,
        sender="me",
        content=message,
        added_button_list=None,
    )
    bot_chat = ChatResponse(
        session_id=session_id + 1,
        sender="bot",
        content=llm_output.content,
        added_button_list=llm_output.added_button_list,
    )
    return ChatPairResponse(chats=[human_chat, bot_chat])

추가로, human 채팅 내용과 bot 채팅 내용을 합쳐서 계속 채팅 내역이 쌓이게끔 하였다.

const [chatContents, setChatContents] = useState<ChatContent[]>([{ session_id: 0, sender: "bot", content: "안녕~ 어서와요 ^^ 오늘은 뭐가 드시고 싶어요?|냉장고에 뭐가 있는지 말하면 딱 맞는 메뉴 말해줄게요." }]);

const [showedManyButton, setShowedManyButton] = useState<boolean>(true);

const [loading, setLoading] = useState<boolean>(false);

const postInput = async () => {
        try {
            setLoading(true);
            setShowedManyButton(false)
            const response = await fetch("http://localhost:8000/api/chat-input", {
                method: 'POST',
                body: JSON.stringify({
                    message: inputText,
                    session_id: chatContents[chatContents.length - 1].session_id + 1
                }),
                headers: {
                    'Content-Type': 'application/json'
                }
            })
            const json = await response.json();
            setChatContents(prev => [...prev, ...json.chats])
            setInputText("");
        } catch (error) {
            console.error('Error post input:', error);
        } finally {
            setLoading(false);
        }
    }

랭체인(LangChain) - 개념 (1)

EunHaa — Sat, 6 Jun 2026 15:37:09 +0900

1. 랭체인 (LangChain)

LLM 기반 애플리케이션 개발을 위해서 사용하는 JS/Python 기반 프레임워크
Prompt - LLM - OutputParser 흐름을 체인으로 연결하는 파이프라인 도구
RAG, Agent, Memory, Tools 등 복잡한 패턴을 표준화된 인터페이스로 제공
Ollama, OpenAI, HuggingFace, Watsonx 등 LLM 백엔드를 동일한 코드로 교체

1) 구성요소

langchain-core : 프롬프트, 템플릿, 아웃풋 파서 등 랭체인의 기본적인 추상화와 인터페이스 제공
LCEL : 여러 단계를 거쳐 처리되는 작업 흐름(체인)을 코드 몇줄로 간단하고 직관적으로 만드는 문법
LangGraph : 복잡한 워크플로우와 에이전트 시스템을 구축하는 그래프 기반 프레임워크
LangServe : LangChain 애플리케이션을 API로 제공하는 서빙 프레임워크
LangSmith : 개발, 테스트, 모니터링을 위한 디버깅 관찰 도구

2) 설치 및 환경 구성

pip install langchain langchain-community langchain-ollama langchain-core

from langchain_ollama import ChatOllama
from langchain_ibm import ChatWatsonx
from langchain_core.prompts import PromptTemplate, ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser, JsonOutputParser, PydanticOutputParser

3) LangChain + Watsonx

# Watsonx 설정
load_dotenv()

api_key = os.getenv("WATSONX_API_KEY")
project_id = os.getenv("WATSONX_PROJECT_ID")
watsonx_ai_url = os.getenv("WATSONX_AI_URL")

# Langchain Frameworks 안에 Watsonx 사용하기

watson_llm = ChatWatsonx(
    model_id="ibm/granite-4-h-small",
    url=watsonx_ai_url,
    api_key=api_key,
    project_id=project_id,
    max_tokens = 2000
)

response = watson_llm.invoke("생성형 AI를 설명해줘.")
print(response.content)

4) LangChain + Ollama

# Langchain Frameworks 안에 Ollama 사용하기
qwen_llm = ChatOllama(model="qwen3.5:4b")

response = qwen_llm.invoke("생성형 AI를 설명해줘")
print(response.content)

5) PromptTemplate

변수가 있는 프롬프트 틀로써, f-string과 유사하지만, 타입 검증과 재사용성을 제공한다.

하나의 문자열 프롬프트를 생성한다.

### 기본 생성
template = PromptTemplate(input_variables=['topic','level'],template="{level} 수준으로 {topic}를 설명해줘. 예시 포함")
print(template.input_variables)
prompt_txt = template.format(topic="재귀 함수", level="초급자")
print(prompt_txt)

아래는 input_variables 설정을 없애고 간소화한 코드이다.

template = PromptTemplate.from_template("{level} 수준으로 {topic}을 설명해줘. 예시 포함")
print(template.input_variables)
prompt_txt = template.format(topic="재귀함수",level="초급자")
print(prompt_txt)

template = PromptTemplate.from_template("""
다음 질문에 답변하세요.

질문:
{question}
""")

formatted_prompt = template.format(question="SQL Injection 이란?")
response = watson_llm.invoke(formatted_prompt)
print(response.content)

6) ChatPromptTemplate

채팅 메시지 형식을 제공하고, from_template()과 from_messages() 메소드를 제공한다.

from_template()의 경우 human 메시지만 생성하지만

from_messages()의 경우 여러 메시지를 구성할 수 있다.

from_template

template = ChatPromptTemplate.from_template("""\
다음 질문에 답변하시오.

질문:
{question}

""")

formatted_prompt = template.format(question="SQL Injection에 대해 설명해줘")
response = watson_llm.invoke(formatted_prompt)
print(response.content)

from_messages

template = ChatPromptTemplate.from_messages(
    [
        ("system", "당신은 {role} 전문가입니다. {language}로 답변하세요"),
        ("human","{question}")
    ]
)

formatted_prompt = template.format(role="파이썬",language="한국어",question="리스트 컴프리헨션 이란?")
response = watson_llm.invoke(formatted_prompt)
print(response.content)

7) LCEL 파이프라인

| 연산자로 컴포넌트를 연결하는 파이프라인 문법으로써, 왼쪽에서 오른쪽으로 데이터가 흐르는 흐름을 제어할 수 있다.

invoke(), stream(), batch() 3가지 메소드를 제공한다.

invoke : 단일 동기 호출

prompt = ChatPromptTemplate.from_messages(
    [
        ("system", "당신은 {role} 전문가입니다."),
        ("human", "{question}")
    ]
)

parser = StrOutputParser()

chain = prompt | watson_llm | parser

response = chain.invoke({
    "role": "보안",
    "question": "XSS란?"
})

print(response)

stream : 스트리밍 형태

for chunk in chain.stream({"role": "보안","question": "XSS란?"}):
    print(chunk, end="",flush=True)

batch : 여러 요청을 병렬 처리

# batch() : 여러 입력을 병렬로 처리

results = chain.batch([
    {
        "role": "보안",
        "question": "XSS란?"
    },
    {
        "role": "Python",
        "question": "List란?"
    },
    {
        "role": "Python",
        "question": "Dictionary란?"
    },
    {
        "role": "Java",
        "question": "Class란?"
    }
])

for result in results:
    print(result)

8) 출력 파서(OutputParser)

1. StrOutputParser

parser = StrOutputParser()

str_chain = ChatPromptTemplate.from_template("{topic}을 한 문장으로 설명해줘.") | qwen_llm | parser

result = str_chain.invoke({"topic": "머신러닝"})

print(result)

2. JsonOutputParser

parser = JsonOutputParser()

json_chain = ChatPromptTemplate.from_messages([
    ("system","JSON 형식으로만 응답하세요."),
    ("human","{text}의 감정을 분석해서 {{'sentiment': '...', 'score': 0.0}} 형태로 출력하세요.")
]) | qwen_llm | parser

result = json_chain.invoke({ "text": "오늘 정말 행복한 하루였어요." })
print(result['sentiment'])
print(result['score'])

3. PydanticOutputParser

반환 타입은 객체이다.
입력 데이터 타입을 검증, 타입 자동 변환
에러 메시지가 정확함.
코드가 간결해짐
FastAPI와 호환 잘됨
json 변환이 쉽다.

다음은 Pydantic 입력 데이터 타입 검증 예제이다.

class User(BaseModel):
    name:str
    age:int

# 객체 생성
user = User(name="홍길동",age="20")
print(user)
print(type(user.age))

user = User(name="홍길동",age="스무살")

class User(BaseModel):
    name:str
    age:int = Field(gt=0)
    
user = User(name="홍길동", age="0")

이번엔 직접 체이닝 예제로 적용시켜보자.

# 감정, 점수, 이유, 키워드 3개
# Pydantic 모델 정의

class SentimentResult(BaseModel):
    sentiment: Literal["postive","negative","neutral"]
    score: float = Field(ge=0.0,le=1.0,description="감정 강도")
    reason:str = Field(description="판단 근거 한 문장")
    keywords:list[str] = Field(description="핵심 키워드 3개 이내")

# 파서 정의
pydantic_parser = PydanticOutputParser(pydantic_object=SentimentResult)

# 프롬프트
# {format_instructions} : pydantic_parser에서 필드를 참고해서 작성
pydantic_prompt = ChatPromptTemplate.from_messages([
    ("system","감정 분석 전문가입니다.\n\n {format_instructions}"),
    ("human","다음 텍스트의 감정을 분석하세요 :\n {text}")
]).partial(format_instructions=pydantic_parser.get_format_instructions())

pydantic_chain = pydantic_prompt | qwen_llm | pydantic_parser

result = pydantic_chain.invoke({
    "text": "오늘 최악의 하루였습니다. 모든게 잘못됐어요."
})

print(result)
print(result.sentiment)
print(result.score)
print(result.keywords)
print(result.reason)

올라마(Ollama) - 개념 및 실습

EunHaa — Sat, 6 Jun 2026 14:57:17 +0900

1. 로컬 LLM (Local LLM)

현재 상용화된 LLM인 ChatGPT, Claude, Gemini 등은 우리가 돈을 지불하고 사용을 해야 하는데

우리는 허깅 페이스 플랫폼에서 오픈 소스로 제공해주는 무료 모델을 사용했었다.

이제 이 무료 모델들을 로컬에서 쓰고 싶다는 생각에서 유래했다.

앞에서 이야기 했던 LLM 아키텍처를 살펴보자.

1) 트랜스포머 핵심 아키텍쳐

2) LLM 추론 파이프라인

대부분의 현업의 상용화된 LLM은 이런 과정을 거친다.

입력 텍스트는 컴퓨터가 이해할 수 있게 토큰 단위로 나누는 토크나이저(토큰화) 단계를 거친다.
토큰화된 리스트를 차원을 늘려 임베딩 과정을 거친다 (벡터화)
임베딩 과정까지는 글자를 나누는 것이 의미있게 가져오는 과정은 아니다.
앞 뒤 문맥(Context) 참고하여 의미 파악한다. -> 셀프 어텐션(Self Attention)
위 문맥 인코딩을 여러번 반복한다.
이제 의미를 알아냈으니까 어떤 의미를 가지고 있는지 서로 확률 분포 확인
최종적으로 우리가 원하는 텍스트를 출력

3) 올라마(Ollama) 아키텍쳐

올라마(Ollama)는 llama.cpp를 기반으로 하는 로컬 LLM 서버
GPU와 CPU 기반 엔진 제공
RestAPI 서버 제공, OpenAI 호환 API 제공

4) 올라마(Ollama) 설치 방법

https://ollama.com/

Ollama

Ollama is the easiest way to automate your work using open models, while keeping your data safe.

ollama.com

여기서 Downloads 버튼을 통해 설치하면 된다.

설치되었으면 아래와 같은 화면이 뜰 것이다.

CLI 명령어로 다음과 같이 모델을 다운로드 받을 수 있다.

5) 양자화(Quantization)

모델 정보를 32비트로 표현하면 공간도 많이 사용하고,

정밀하기 때문에 느리기도 하는데, 로컬 컴퓨터의 환경 조차도 좋지 않을 수 있다.

그래서 정밀도 부분에서 손실을 보더라도 가중치를 조금 낮추어 추론 속도를 높이는 핵심 기술

6) 정밀도별 특성 비교

7) GGUF(GPT-Generated Unified Format)

모델을 어떤 포맷으로 저장할 지에 관한 것 (허깅 페이스에서도 다운로드 가능)
Apple Slicon , CUDA 가속 가능
CPU Only 실행 파일 지원 (GPU 없어도 동작)

8) 오픈 소스 모델 비교

2. 올라마(Ollama) 샘플 코드

chat 이라는 공통 인터페이스를 사용하여 질의한다.

1) 간단한 자기소개

from ollama import chat

response = chat(
    model='qwen2.5',
    messages = [
        {
            'role': 'user',
            'content': '안녕하세요! 자기소개 해줘!'
        }
    ]
)

print(response.message.content)

2) 어디까지 학습되었는지 샘플 코드

from ollama import chat

response = chat(
    model='qwen2.5',
    messages = [
        {
            'role': 'user',
            'content': '대한민국 대통령은 누구야?'
        }
    ]
)

print(response.message.content)

현재 답변하는 시점까지 학습이 되었으므로,

이재명 대통령이 아닌 윤석열 대통령으로 답변해줌을 확인할 수 있다.

모델이 어느 시점까지 학습이 되었는지도 중요하다고 보인다.

3) DeepSeek R1 모델 : 추론에 강하다

CoT(Chain Of Thought)으로써 단계별 사고적 흐름으로 추론하는 것에 특화되어 있는 모델이다.

from ollama import chat

response = chat(
    model='deepseek-r1:1.5b',
    messages = [
        {
            'role': 'user',
            'content': '파이썬으로 피보나치 수열 구현해줘.'
        }
    ]
)

print(response.message.content)

4) 산수문제 테스트 : 어떤 모델이 더 특화되어 있는지

버젼에 따라 답변이 다르긴 하지만, R1 모델이 수학적으로 추론해서 접근하는 것에 더 특화되어 있다.

models = [
    'qwen2.5',
    'deepseek-r1:1.5b'
]

for model in models:
    response = chat(
        model = model,
        messages = [
            {
                'role': 'user',
                'content': '사과 3개가 있다. 2개를 친구에게 주고 1개를 다시 받았다. 현재 몇 개인가?'
            }
        ]
    )
    print(model)
    print(response.message.content)
    print("\n")

5) 퓨샷 메시지 예제

messages = [
    # 시스템 프롬프트
    {
        "role": "system",
        "content": "너는 문장의 감정을 긍정, 부정, 중립 중 하나로 분리하는 AI야"
    },
    # 퓨샷
    {
        "role": "user",
        "content": "정말 만족스러운 서비스였어요"
    },
    {
        "role": "assistant",
        "content": "긍정"
    },
    {
        "role": "user",
        "content": "다시는 이용 안할 것 같아요."
    },
    {
        "role": "assistant",
        "content": "부정"
    },
    # 사용자 프롬프트
    {
        "role": "user",
        "content": "배송이 너무 늦었어요"
    }
]

response = chat(
    model='qwen2.5',
    messages=messages
)

print(response.message.content)

6) 스트림 효과 예제

from ollama import chat

response = chat(
    model='qwen2.5',
    messages = [
        {
            'role': 'user',
            'content': '안녕하세요! 자기소개 해줘!'
        }
    ],
    stream=True
)

for chunk in response:
    content = chunk['message']['content']
    print(content, end="", flush=True)

3. 구조화된 출력

주로 파이썬에서는 딕셔너리 구조로, 자바스크립트에서는 오브젝트 구조로 받기 위해

JSON으로 받아주는 것이 편한데, 그 방법으로는 여러가지가 있다.

1) 사용자 프롬프트에 지정

prompt = """
    다음 문장의 감정을 분석하라.
    JSON으로만 반환하시오.

    {
        "sentiment" : "",
        "score" : 0
    }

    문장: 오늘 정말 행복한 하루였다.
"""

response = chat(
    model='qwen2.5',
    messages=[
        {
            "role": "user",
            "content": prompt
        }
    ]
)

print(response.message.content)

prompt = """
    다음 뉴스 기사를 분석하시오.
    JSON으로만 반환하시오.

    {
        'summary': '',
        'sentiment': '',
        'keywords': []
    }

    기사 내용 ----------
    스위스 "19일 뷔르겐슈토크서 종전 MOU 서명식"(종합)

    (베를린=연합뉴스) 김계연 특파원 = 미국과 이란의 종전 양해각서(MOU) 서명식이 오는 19일(현지시간) 스위스 휴양지 뷔르겐슈토크에서 열린다고 스위스 정부가 16일 밝혔다.

    서명식은 당초 유엔 사무국 등 국제기구가 모여 있는 스위스 제네바에서 열린다고 알려졌었다. 스위스 외무부는 미국과 이란, 중재국 파키스탄과 카타르가 뷔르겐슈토크를 서명식 장소로 제안했다면서 이들 4개국과 소통하며 외교적 여건을 조성하고 있다고 말했다.

    스위스 중부 니드발덴주에 있는 뷔르겐슈토크는 루체른 호수가 내려다보이는 알프스 산악지대 휴양지다. 100여개국 대표단이 참석한 2024년 우크라이나 평화회의 등 국제행사가 종종 열린다.

    스위스 외무부는 현재로서는 서명식 절차와 세부 사항을 알릴 수 없다고 덧붙였다. 미국과 이란은 이미 지난 14일 종전 MOU에 전자 서명했다. 양측은 협상 대표인 JD 밴스 미국 부통령과 모하마드 바게르 갈리바프 이란의회 의장 등이 참석하는 MOU 공식 서명식에 이어 후속 실무협상을 할 예정이다.

    서명식 장소를 바꾼 데는 제네바와 달리 일반인 접근이 어려워 보안·경호에 유리한 점도 작용한 것으로 보인다. 제네바는 인근 프랑스 에비앙레뱅에서 17일 끝나는 주요 7개국(G7) 정상회의 반대 시위대가 세계 곳곳에서 몰려들어 몸살을 앓고 있다.

    서명식이 열리는 뷔르겐슈토크 리조트는 중재국 카타르 국부펀드인 카타르투자청(QIA) 자회사 카타라호스피탤러티가 소유하고 있다. 스위스 일간 노이에취르허차이퉁(NZZ)은 카타르가 서명식 주최 역할을 할 것으로 내다봤다.


"""

response = chat(
    model='qwen2.5',
    messages=[
        {
            "role": "user",
            "content": prompt
        }
    ]
)

print(response.message.content)

2) JSON Schema를 넘기는 방식

schema = {
    "type": "object",
    "properties" : {
        "sentiment": {
            "type": "string",
            "description": "sentiment"
        },
        "score": {
            "type": "integer",
            "description": "score"
        }
    }
}

prompt = """
    다음 문장의 감정을 분석하라.
    
    단, format으로 주어진 구조로 출력하시오.

    문장: 오늘 정말 행복한 하루였다.
"""

response = chat(
    model='qwen2.5',
    messages=[
        {
            "role": "user",
            "content": prompt
        }
    ],
    format=schema
)

print(response.message.content)

schema = {
    "type": "object",
    "properties": {
        "summary": {
            "type": "string",
            "description": "news writer summary"
        },
        "sentiment": {
            "type": "string",
            "enum": ["positive","negative","neutral"]
        },
        "keywords": {
            "type": "array"
        }
    },
    "required": [
        "summary",
        "sentiment",
        "keywords"
    ]
}

prompt = """
    다음 뉴스 기사를 분석하시오.
    단, format으로 주어진 구조로 반환하시오.

    기사 내용 ----------
    스위스 "19일 뷔르겐슈토크서 종전 MOU 서명식"(종합)

    (베를린=연합뉴스) 김계연 특파원 = 미국과 이란의 종전 양해각서(MOU) 서명식이 오는 19일(현지시간) 스위스 휴양지 뷔르겐슈토크에서 열린다고 스위스 정부가 16일 밝혔다.

    서명식은 당초 유엔 사무국 등 국제기구가 모여 있는 스위스 제네바에서 열린다고 알려졌었다. 스위스 외무부는 미국과 이란, 중재국 파키스탄과 카타르가 뷔르겐슈토크를 서명식 장소로 제안했다면서 이들 4개국과 소통하며 외교적 여건을 조성하고 있다고 말했다.

    스위스 중부 니드발덴주에 있는 뷔르겐슈토크는 루체른 호수가 내려다보이는 알프스 산악지대 휴양지다. 100여개국 대표단이 참석한 2024년 우크라이나 평화회의 등 국제행사가 종종 열린다.

    스위스 외무부는 현재로서는 서명식 절차와 세부 사항을 알릴 수 없다고 덧붙였다. 미국과 이란은 이미 지난 14일 종전 MOU에 전자 서명했다. 양측은 협상 대표인 JD 밴스 미국 부통령과 모하마드 바게르 갈리바프 이란의회 의장 등이 참석하는 MOU 공식 서명식에 이어 후속 실무협상을 할 예정이다.

    서명식 장소를 바꾼 데는 제네바와 달리 일반인 접근이 어려워 보안·경호에 유리한 점도 작용한 것으로 보인다. 제네바는 인근 프랑스 에비앙레뱅에서 17일 끝나는 주요 7개국(G7) 정상회의 반대 시위대가 세계 곳곳에서 몰려들어 몸살을 앓고 있다.

    서명식이 열리는 뷔르겐슈토크 리조트는 중재국 카타르 국부펀드인 카타르투자청(QIA) 자회사 카타라호스피탤러티가 소유하고 있다. 스위스 일간 노이에취르허차이퉁(NZZ)은 카타르가 서명식 주최 역할을 할 것으로 내다봤다.


"""

response = chat(
    model='qwen2.5',
    messages=[
        {
            "role": "user",
            "content": prompt
        }
    ],
    format=schema
)

print(response.message.content)

3) pydantic

from pydantic import BaseModel, Field

class SentimentResult(BaseModel):
    sentiment: str
    score: float = Field(ge=0.0, le=1.0) #범위지정
    keywords: list[str]

prompt = '''
다음 문장의 감정을 분석하라.

문장 : 오늘 정말 행복한 하루였다.
'''

response = chat(
    model='qwen2.5',
    messages=[
        {
            "role": "user",
            "content": prompt
        }
    ],
    format=SentimentResult.model_json_schema()
)

result = SentimentResult.model_validate_json(response.message.content)

print(result.sentiment)
print(result.score)
print(result.keywords)

from typing import Literal

class NewsWriteResult(BaseModel):
    summary: str
    sentiment: Literal['positive','neutral','negative']
    keywords: list[str]

prompt = """
    다음 뉴스 기사를 분석하시오.

    기사 내용 ----------
    스위스 "19일 뷔르겐슈토크서 종전 MOU 서명식"(종합)

    (베를린=연합뉴스) 김계연 특파원 = 미국과 이란의 종전 양해각서(MOU) 서명식이 오는 19일(현지시간) 스위스 휴양지 뷔르겐슈토크에서 열린다고 스위스 정부가 16일 밝혔다.

    서명식은 당초 유엔 사무국 등 국제기구가 모여 있는 스위스 제네바에서 열린다고 알려졌었다. 스위스 외무부는 미국과 이란, 중재국 파키스탄과 카타르가 뷔르겐슈토크를 서명식 장소로 제안했다면서 이들 4개국과 소통하며 외교적 여건을 조성하고 있다고 말했다.

    스위스 중부 니드발덴주에 있는 뷔르겐슈토크는 루체른 호수가 내려다보이는 알프스 산악지대 휴양지다. 100여개국 대표단이 참석한 2024년 우크라이나 평화회의 등 국제행사가 종종 열린다.

    스위스 외무부는 현재로서는 서명식 절차와 세부 사항을 알릴 수 없다고 덧붙였다. 미국과 이란은 이미 지난 14일 종전 MOU에 전자 서명했다. 양측은 협상 대표인 JD 밴스 미국 부통령과 모하마드 바게르 갈리바프 이란의회 의장 등이 참석하는 MOU 공식 서명식에 이어 후속 실무협상을 할 예정이다.

    서명식 장소를 바꾼 데는 제네바와 달리 일반인 접근이 어려워 보안·경호에 유리한 점도 작용한 것으로 보인다. 제네바는 인근 프랑스 에비앙레뱅에서 17일 끝나는 주요 7개국(G7) 정상회의 반대 시위대가 세계 곳곳에서 몰려들어 몸살을 앓고 있다.

    서명식이 열리는 뷔르겐슈토크 리조트는 중재국 카타르 국부펀드인 카타르투자청(QIA) 자회사 카타라호스피탤러티가 소유하고 있다. 스위스 일간 노이에취르허차이퉁(NZZ)은 카타르가 서명식 주최 역할을 할 것으로 내다봤다.


"""

response = chat(
    model='qwen2.5',
    messages=[
        {
            "role": "user",
            "content": prompt
        }
    ],
    format=NewsWriteResult.model_json_schema()
)

result = NewsWriteResult.model_validate_json(response.message.content)

print(result.summary)
print(result.sentiment)
print(result.keywords)

4. 툴 콜링 (Tool Calling)

오픈 소스 모델을 가지고 날씨에 대해 물어보면 모델은 대답을 해주지 못한다.

그래서 날씨를 알려주는 API에게 가서 받은 날씨를 가져오라고 해야 한다.

1) 1단계 : 함수 정의

def calculator(a, b):
    return a + b

2) 2단계 : 함수를 적용할 Tools 지정

tools = [
    {
        "type": "function",
        "function": {
            "name": "calculator",
            "description": "두 숫자를 더한다.",
            "parameters": {
                "type": "object",
                "properties": {
                    "a" : {
                        "type": "integer",
                        "description": "첫번째 숫자"
                    },
                    "b" : {
                        "type": "integer",
                        "description": "두번째 숫자"
                    }
                },
                "required": ["a","b"]
            }
        }
    }
]

3) 3단계 : 사용자의 메시지와 메세지 파악한 LLM이 필요하다면 호출할 Tools를 넘겨줌.

아직 계산은 안들어가고 요청을 받아주는 상태

response = chat(
    model='qwen2.5',
    messages=[{"role": "user", "content": "25와 36을 더해줘."}],
    tools=tools
)

print(response.message)

4) 4단계: Tool을 실행해달라고 요청

tool_call = response.message.tool_calls[0]
args = tool_call.function.arguments

result = calculator(args["a"], args["b"])
print(result)

messages = [
    {
        "role": "user",
        "content": "25와 6을 더해줘."
    },
    response.message,
    {
        "role": "tool",
        "content": str(result)
    }
]

final_response = chat(
    model='qwen2.5',
    messages=messages
)

print(final_response.message.content)

5) 날씨 함수 예시

import json

# 함수 정의
def get_weather(city:str) -> dict:
    data = {
        "서울" : { "temp": 22, "condition": "맑음" },
        "부산" : { "temp": 25, "condition": "흐림" }
    }
    return data.get(city, { "temp": 0, "condition": "알 수 없음"})

# 툴 스키마
tools = [
    {
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "특정 도시의 날씨를 조회한다.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "날씨를 조회할 도시 이름 (예 : 서울, 부산)"
                }
            },
            "required": ["city"]
        }
    }
}
]

messages = [{ "role": "user", "content": "서울 날씨 알려줘"}]

# LLM 호출 - Tool 목록 전달
response = chat(
    model='qwen2.5',
    messages=messages,
    tools=tools
)

print(response.message)

if response.message.tool_calls:
    for tool_call in response.message.tool_calls:
        name = tool_call.function.name
        args = tool_call.function.arguments

        tool_map = {"get_weather": get_weather}
        result = tool_map[name](**args)
        print(f"Tool 실행 : {name}({args}) -> {result}")

        messages.append(response.message)
        messages.append(
            {
                "role": "tool",
                "content": json.dumps(result, ensure_ascii=False)
            }
        )

final = chat(model='qwen2.5', messages=messages)
print(final.message.content)

6) 여러 툴 등록 및 자동 루프 처리

def get_weather(city):
    return {"temp": 12, "condition": "비" }

def need_umbrella(condition):
    return { "result" : condition in ["비","눈"] }

def calculate(expression):
    return { "result": eval(expression) }

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "도시 날씨 조회",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": { "type" : "string" }
                },
                "required": ["city"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "need_umbrella",
            "description" : "날씨 상태로 우산 필요 여부 판단",
            "parameters": {
                "type": "object",
                "properties": {
                    "condition": {
                        "type": "string"
                    }
                },
                "required": ["condition"]
            }
        }
    }
]

tool_map = {
    "get_weather": get_weather,
    "need_umbrella": need_umbrella
}

messages = [ { "role": "user", "content": "서울 날씨 보고서 우산이 필요한지 알려줘."}]

while True:
    response = chat(model='qwen2.5',messages=messages,tools=tools)

    if not response.message.tool_calls:
        print(response.message.content)
        break

    messages.append(response.message)

    for tc in response.message.tool_calls:
        name = tc.function.name
        args = tc.function.arguments
        result = tool_map[name](**args)
        print(f"[Tool] {name}({args}) -> {result}")

        messages.append(
            {
                "role": "tool",
                "content": json.dumps(result, ensure_ascii=False)
            }
        )

f = chat(model='qwen2.5', messages=messages)
print(f.message.content)

7) LLM 요청 시 REST 방식으로 요청

# post

import requests

response = requests.post("http://localhost:11434/api/chat", json= {
    "model":'qwen2.5',
    "messages": [
        {"role": "system", "content": "당신은 친절한 AI 어시스턴트입니다."},
        {"role": "user", "content": "파이썬의 장점을 3가지 알려주세요"}
    ],
    "stream": False
})

data = response.json()
print(data['message']['content'])

사용되는 API 엔드포인트들은 아래와 같다.

5. 임베딩(Embedding)

토큰 리스트를 고차원 벡터 변환 해주는 과정이다.

먼저 Ollama 사이트에서 임베딩 모델을 설치한다.

다음 코드를 샘플 코드로 입력한다. (몇 차원인지도 확인한다)

import ollama

response = ollama.embed(
    model='nomic-embed-text-v2-moe',
    input='The sky is blue because of Rayleigh scattering',
)
print(response.embeddings)
print(len(response.embeddings[0]))

임베딩 값들은 다음과 같은 경우에 이용할 수 있다.

RAG : 주어진 문서 안에서 질의 응답 가능한 형태
분류, 군집 : 비슷한 의미의 문서끼리 그룹화한다.
벡터 DB : 임베딩 값을 저장할 수 있는 데이터베이스

예를 들어, 문자들의 비슷한 의미를 따지는 코사인 유사도 코드로 알아볼 수 있다.

# 코사인 유사도

from numpy import dot
from numpy.linalg import norm

def cosine_similarity(a, b):
    return dot(a, b) / (norm(a) * norm(b))

# 두 개의 문장이 유사한가?

s1 = '파이썬은 프로그래밍 언어이다.'
s2 = 'Python은 개발에 사용되는 언어이다'

s1 = ollama.embed(model='nomic-embed-text-v2-moe', input=s1).embeddings[0]
s2 = ollama.embed(model='nomic-embed-text-v2-moe', input=s2).embeddings[0]

print(cosine_similarity(s1,s2))

나중에, pdf 문서를 다 쪼개고, 모두 벡터화(임베딩) 처리를 해서 질문을 했을 때,

질문도 벡터화 시켜, 기존의 벡터화 시킨 숫자와 유사도를 비교해서 답변을 해주는 방식으로 응용한다.

예시로 다음과 같이 구성해보자.

documents = [
    "파이썬은 프로그래밍 언어이다.",
    "축구는 세계적으로 인기있는 스포츠이다.",
    "인공지능은 머신러닝을 활용한다.",
    "서울은 대한민국의 수도이다."
]

doc_vectors = []

for doc in documents:
    vector = ollama.embed(model='nomic-embed-text-v2-moe', input=doc).embeddings[0]
    doc_vectors.append(vector)

query = "AI 기술이란?"
query_vector = ollama.embed(model='nomic-embed-text-v2-moe', input=query).embeddings[0]

scores = []
for doc, vec in zip(documents, doc_vectors):
    score = cosine_similarity(query_vector, vec)
    scores.append((doc, score))

scores.sort(key=lambda x:x[1], reverse=True)

for doc, score in scores:
    print(doc, score)

context = scores[0][0]

prompt = f'''
문서: {context}

질문: {query}
'''

response = chat(model='qwen2.5', messages=[{
    "role": "user",
    "content": prompt
}])

print(response.message.content)

6. 정해진 인터페이스

모델 플랫폼에 따라, 지금 인터페이스가 조금씩 다르고 있다.

이것을 정형화된 템플릿이 필요한데, 이것은 다음 시간에 배우게 될 LangChain 프레임워크로 이어진다.

허깅 페이스(Hugging Face) - 음성 비서 앱 (7)

EunHaa — Fri, 5 Jun 2026 22:58:55 +0900

멀티 모달을 활용하는 개발 경험에서 음성 비서 앱도 추가할 수 있다.

특히 다음과 같은 기능을 제공할 수 있다.

음성을 텍스트로 변환하고, 그것을 기준으로 질문 처리하여, 그것을 또 음성으로 변환하는 기능을 수행한다.

구체적인 단계는 다음과 같다.

먼저 화면 구성 먼저 진행해보자.

1단계 : 화면 구성

사용된 Next.js는 다음과 같다.

app/sound_assistant/page.tsx

import AudioComponent from "@/components/AudioComponent";
import AudioResponse from "@/components/AudioResponse";
import CommonPut from "@/components/CommonPut";

export default function SoundAssistantPage() {
    return (
        <main>
            <div id="wrap" className="w-[1080px] mx-auto">
                <h2 className="mt-[30px] mb-[20px]">AI 음성 비서</h2>
                <div id="gra__block" className="grid grid-cols-2 gap-[10px]">
                    <AudioComponent />
                    <CommonPut put={"output"} label={"텍스트 변환"} height={110} highHeight={150} />
                    <CommonPut put={"input"} label={"question"} height={40} hasButton={"질문하기"} />
                    <CommonPut put={"input"} label={"answer"} height={40} hasButton={"답변하기"} />
                </div>
                <div className="mt-[10px]">
                    <AudioResponse />
                </div>
            </div>
        </main>
    )
}

src/components/AudioComponent.tsx

'use client';

import { useState, useRef } from "react";
import { MdSpatialAudioOff, MdUpload } from "react-icons/md";
import { HiOutlineMicrophone } from "react-icons/hi2";
import { IoCloseCircle } from "react-icons/io5";
import { MdPlayArrow, MdPause } from "react-icons/md";
import { MdSkipPrevious, MdSkipNext } from "react-icons/md";

export default function AudioComponent() {
    const [activeTab, setActiveTab] = useState<'upload' | 'record'>('upload');
    const [uploadedAudio, setUploadedAudio] = useState<string>("");
    const [isUploading, setIsUploading] = useState(false);
    const [isPlaying, setIsPlaying] = useState(false);
    const [duration, setDuration] = useState(0);
    const [currentTime, setCurrentTime] = useState(0);
    const inputRef = useRef<HTMLInputElement | null>(null);
    const audioRef = useRef<HTMLAudioElement | null>(null);

    const handleAudioUpload = () => {
        inputRef.current?.click();
    };

    const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
        const file = e.target.files?.[0];
        if (!file) return;

        try {
            setIsUploading(true);
            const formData = new FormData();
            formData.append("file", file);
            const response = await fetch("http://localhost:8000/api/v1/file-upload", {
                method: "POST",
                body: formData,
            });
            const data = await response.json();
            setUploadedAudio(data.url);
        } catch (error) {
            console.error("Upload failed:", error);
        } finally {
            setIsUploading(false);
        }
    };

    const clearAudio = () => {
        setUploadedAudio("");
        setIsPlaying(false);
        setCurrentTime(0);
        if (inputRef.current) inputRef.current.value = "";
    };

    const handlePlayPause = () => {
        if (audioRef.current) {
            if (isPlaying) {
                audioRef.current.pause();
            } else {
                audioRef.current.play();
            }
            setIsPlaying(!isPlaying);
        }
    };

    const handleTimeUpdate = () => {
        if (audioRef.current) {
            setCurrentTime(audioRef.current.currentTime);
        }
    };

    const handleLoadedMetadata = () => {
        if (audioRef.current) {
            setDuration(audioRef.current.duration);
        }
    };

    const handleProgressChange = (e: React.ChangeEvent<HTMLInputElement>) => {
        const newTime = parseFloat(e.target.value);
        setCurrentTime(newTime);
        if (audioRef.current) {
            audioRef.current.currentTime = newTime;
        }
    };

    const formatTime = (time: number) => {
        if (isNaN(time)) return "0:00";
        const minutes = Math.floor(time / 60);
        const seconds = Math.floor(time % 60);
        return `${minutes}:${seconds.toString().padStart(2, "0")}`;
    };

    return (
        <div id="audioWrap">
            <div id="audioWrapBox" className="w-full h-[250px] border border-[#e6e6e8] rounded-[5px] flex flex-col">
                <div id="audioWrapBoxTitle" className="w-[80px] h-[30px] border-r border-b border-[#e6e6e8] flex items-center justify-center gap-[5px]">
                    <MdSpatialAudioOff />
                    <span className="text-[12px]">오디오</span>
                </div>
                <div id="audioWrapBoxContent" className="flex-1 flex flex-col justify-center items-center gap-[12px]">
                    {activeTab === 'upload' ? (
                        <>
                            {uploadedAudio ? (
                                <div className="w-[280px] flex flex-col items-center gap-[12px]">
                                    {/* 음파 시각화 */}
                                    <div className="w-full h-[40px] flex items-center justify-center gap-[2px] mb-[4px]">
                                        {[...Array(40)].map((_, i) => (
                                            <div
                                                key={i}
                                                className="w-[1.5px] bg-[#999] rounded-full"
                                                style={{
                                                    height: `${20 + Math.sin(i * 0.5 + currentTime) * 10}px`,
                                                    opacity: i / 40 <= (currentTime / duration) ? 1 : 0.3,
                                                }}
                                            />
                                        ))}
                                    </div>

                                    {/* 플레이어 컨트롤 */}
                                    <div className="w-full flex items-center justify-center gap-[8px] px-[8px]">
                                        <button className="text-[#999] hover:text-[#333] transition-colors">
                                            <MdSkipPrevious size={16} />
                                        </button>
                                        <button
                                            onClick={handlePlayPause}
                                            className="text-[#999] hover:text-[#333] transition-colors"
                                        >
                                            {isPlaying ? <MdPause size={16} /> : <MdPlayArrow size={16} />}
                                        </button>
                                        <button className="text-[#999] hover:text-[#333] transition-colors">
                                            <MdSkipNext size={16} />
                                        </button>
                                        <span className="text-[10px] text-[#999] min-w-[24px]">{formatTime(currentTime)}</span>
                                    </div>

                                    {/* 진행률 바 */}
                                    <input
                                        type="range"
                                        min="0"
                                        max={duration || 0}
                                        value={currentTime}
                                        onChange={handleProgressChange}
                                        className="w-full h-[2px] bg-[#ddd] rounded-full appearance-none cursor-pointer"
                                        style={{
                                            background: `linear-gradient(to right, #999 0%, #999 ${(currentTime / duration) * 100}%, #ddd ${(currentTime / duration) * 100}%, #ddd 100%)`
                                        }}
                                    />

                                    <button
                                        onClick={clearAudio}
                                        className="flex items-center gap-[6px] text-[#919096] hover:text-[#333] transition-colors text-[12px]"
                                    >
                                        <IoCloseCircle size={16} />
                                        <span>제거</span>
                                    </button>

                                    <audio
                                        ref={audioRef}
                                        onTimeUpdate={handleTimeUpdate}
                                        onLoadedMetadata={handleLoadedMetadata}
                                        onEnded={() => setIsPlaying(false)}
                                    >
                                        <source src={uploadedAudio} type="audio/mpeg" />
                                    </audio>
                                </div>
                            ) : (
                                <button
                                    onClick={handleAudioUpload}
                                    disabled={isUploading}
                                    className="flex flex-col justify-center items-center gap-[5px]"
                                >
                                    <MdUpload size={22} color={"#919096"} />
                                    <span className="text-[#d6d9d6]">오디오를 여기에 드롭</span>
                                    <span className="text-[#919096]">-또는-</span>
                                    <span className="text-[#919096]">{isUploading ? "업로드 중..." : "클릭하여 업로드"}</span>
                                </button>
                            )}
                            <input
                                type="file"
                                ref={inputRef}
                                onChange={handleFileChange}
                                accept="audio/mp3,audio/wav,audio/m4a,audio/ogg,audio/flac,.mp3,.wav,.m4a,.ogg,.flac"
                                className="hidden"
                            />
                        </>
                    ) : (
                        <button className="flex flex-col justify-center items-center gap-[5px]">
                            <HiOutlineMicrophone size={22} color={"#919096"} />
                            <span className="text-[#d6d9d6]">녹음 시작</span>
                            <span className="text-[#919096]">클릭하여 녹음</span>
                        </button>
                    )}
                </div>
                <div id="audioWrapBoxTab" className="h-[40px] border-t border-[#e6e6e8] flex justify-center items-center gap-[20px] px-[20px]">
                    <button
                        onClick={() => setActiveTab('upload')}
                        className={`flex items-center gap-[6px] transition-colors ${activeTab === 'upload'
                            ? 'text-[#333]'
                            : 'text-[#919096]'
                            }`}
                    >
                        <MdUpload size={16} />
                    </button>
                    <button
                        onClick={() => setActiveTab('record')}
                        className={`flex items-center gap-[6px] transition-colors ${activeTab === 'record'
                            ? 'text-[#333]'
                            : 'text-[#919096]'
                            }`}
                    >
                        <HiOutlineMicrophone size={16} />
                    </button>
                </div>
            </div>
            <button className="w-full py-[10px] bg-[#e4e4e6] rounded-[5px] mt-[20px] disabled:opacity-45" disabled={!uploadedAudio}>텍스트 변환</button>
        </div>
    )
}

src/components/CommonPut.tsx

export default function CommonPut({ put, label, height, highHeight, hasButton }: { put: string, label: string, height: number, highHeight?: number, hasButton?: string }) {
    return (
        <div id="commonPut">
            <div id="commonPutBox" className="border border-[#e6e6e8] rounded-[5px] px-[16px] py-[10px]" style={{ height: highHeight ? `${highHeight}px` : "auto" }}>
                <h2 className="text-[13px] font-[500] mb-[10px]">{label}</h2>
                {put === "output" ? (
                    <div className="text__content w-full border border-[#e6e6e8] box-border rounded-[5px]" style={{ height: `${height}px` }}>

                    </div>
                ) : (
                    <input type="text" className="text__content px-[10px] outline-none w-full h-[112px] border border-[#d2d2d3] box-border rounded-[5px]" style={{ height: `${height}px` }}>

                    </input>
                )}
            </div>
            {hasButton && <button className="w-full py-[10px] px-[14px] bg-[#e6e6e8] text-white rounded-[5px] mt-[10px]">{hasButton}</button>}
        </div>
    )
}

src/components/AudioResponse.tsx

'use client';

import { useState, useRef } from "react";
import { MdSpatialAudioOff } from "react-icons/md";
import { IoCloseCircle } from "react-icons/io5";
import { MdPlayArrow, MdPause } from "react-icons/md";
import { MdSkipPrevious, MdSkipNext } from "react-icons/md";
import { IoIosMusicalNotes } from "react-icons/io";

interface AudioResponseProps {
    audioUrl?: string;
    onClear?: () => void;
}

export default function AudioResponse({ audioUrl, onClear }: AudioResponseProps) {
    const [isPlaying, setIsPlaying] = useState(false);
    const [duration, setDuration] = useState(0);
    const [currentTime, setCurrentTime] = useState(0);
    const audioRef = useRef<HTMLAudioElement | null>(null);

    const handlePlayPause = () => {
        if (audioRef.current) {
            if (isPlaying) {
                audioRef.current.pause();
            } else {
                audioRef.current.play();
            }
            setIsPlaying(!isPlaying);
        }
    };

    const handleTimeUpdate = () => {
        if (audioRef.current) {
            setCurrentTime(audioRef.current.currentTime);
        }
    };

    const handleLoadedMetadata = () => {
        if (audioRef.current) {
            setDuration(audioRef.current.duration);
        }
    };

    const handleProgressChange = (e: React.ChangeEvent<HTMLInputElement>) => {
        const newTime = parseFloat(e.target.value);
        setCurrentTime(newTime);
        if (audioRef.current) {
            audioRef.current.currentTime = newTime;
        }
    };

    const formatTime = (time: number) => {
        if (isNaN(time)) return "0:00";
        const minutes = Math.floor(time / 60);
        const seconds = Math.floor(time % 60);
        return `${minutes}:${seconds.toString().padStart(2, "0")}`;
    };

    const clearAudio = () => {
        setIsPlaying(false);
        setCurrentTime(0);
        onClear?.();
    };

    return (
        <div id="audioResponse">
            <div id="audioResponseBox" className="w-full border border-[#e6e6e8] rounded-[5px] flex flex-col">
                <div id="audioResponseTitle" className="w-[80px] h-[30px] border-r border-b border-[#e6e6e8] flex items-center justify-center gap-[5px]">
                    <MdSpatialAudioOff />
                    <span className="text-[12px]">답변</span>
                </div>
                <div id="audioResponseContent" className="flex-1 flex justify-center items-center p-[20px]">
                    {audioUrl ? (
                        <div className="w-[280px] flex flex-col items-center gap-[12px]">
                            {/* 음파 시각화 */}
                            <div className="w-full h-[40px] flex items-center justify-center gap-[2px] mb-[4px]">
                                {[...Array(40)].map((_, i) => (
                                    <div
                                        key={i}
                                        className="w-[1.5px] bg-[#999] rounded-full"
                                        style={{
                                            height: `${20 + Math.sin(i * 0.5 + currentTime) * 10}px`,
                                            opacity: i / 40 <= (currentTime / duration) ? 1 : 0.3,
                                        }}
                                    />
                                ))}
                            </div>

                            {/* 플레이어 컨트롤 */}
                            <div className="w-full flex items-center justify-center gap-[8px] px-[8px]">
                                <button className="text-[#999] hover:text-[#333] transition-colors">
                                    <MdSkipPrevious size={16} />
                                </button>
                                <button
                                    onClick={handlePlayPause}
                                    className="text-[#999] hover:text-[#333] transition-colors"
                                >
                                    {isPlaying ? <MdPause size={16} /> : <MdPlayArrow size={16} />}
                                </button>
                                <button className="text-[#999] hover:text-[#333] transition-colors">
                                    <MdSkipNext size={16} />
                                </button>
                                <span className="text-[10px] text-[#999] min-w-[24px]">{formatTime(currentTime)}</span>
                            </div>

                            {/* 진행률 바 */}
                            <input
                                type="range"
                                min="0"
                                max={duration || 0}
                                value={currentTime}
                                onChange={handleProgressChange}
                                className="w-full h-[2px] bg-[#ddd] rounded-full appearance-none cursor-pointer"
                                style={{
                                    background: `linear-gradient(to right, #999 0%, #999 ${(currentTime / duration) * 100}%, #ddd ${(currentTime / duration) * 100}%, #ddd 100%)`
                                }}
                            />

                            <button
                                onClick={clearAudio}
                                className="flex items-center gap-[6px] text-[#919096] hover:text-[#333] transition-colors text-[12px]"
                            >
                                <IoCloseCircle size={16} />
                                <span>제거</span>
                            </button>

                            <audio
                                ref={audioRef}
                                onTimeUpdate={handleTimeUpdate}
                                onLoadedMetadata={handleLoadedMetadata}
                                onEnded={() => setIsPlaying(false)}
                            >
                                <source src={audioUrl} type="audio/mpeg" />
                            </audio>
                        </div>
                    ) : (
                        <div className="not__answer">
                            <IoIosMusicalNotes color={"#c3c0c0ff"} />
                        </div>
                    )}
                </div>
            </div>
        </div>
    );
}

2단계 : 음성을 입력으로 받아 텍스트로 변환 후 출력

현재 음성을 업로드 후 오디오 컴포넌트에 표시되어 있는 것은 아래와 같이 구현되어 있다.

이제 위 파일을 인풋으로 보내어 FastAPI에서 처리하고

텍스트 변환 응답값을 내려받아 처리하는 함수를 만들고자 한다.

먼저 Transformer의 pipeline 함수에서 다음과 같은 태스크를 선언하자.

whisper = pipeline("automatic-speech-recognition", model="openai/whisper-base")

그리고 다음과 같은 라우터를 선언할 예정이다.

@router.post("/audio_to_text", summary="transfer audio to text")
async def audioToText(input_audio_path: str):
    pass

가장 먼저 로컬 서버에 업로드 된 파일을 실제 로컬 폴더의 path로 변환하는 과정을 거쳐야 한다.

file_path = input_audio_path.replace("http://localhost:8000", "").lstrip("/")
project_root = Path(__file__).parent.parent.parent.parent.parent
full_path = project_root / file_path

그리고 이 path를 whisper에 연결하여 결과를 확인한다.

result = whisper(str(full_path))

결과를 확인하기 위해 프론트엔드단에서 처리하자.

const handleTransferText = async () => {
        try {
            const response = await fetch(`http://localhost:8000/api/v1/audio_to_text?input_audio_path=${uploadedAudio}`, {
                method: "POST"
            });
            const data = await response.json();
            console.log(data)
        } catch (error) {
            console.error("Transfer failed:", error);
        }
    }

결과 값은 아래와 같이 디버깅 된다.

올바로 처리 된 것 같다. 이제 이것을 응답값으로 넘기고 프론트엔드에서

따로 상태 값으로 저장해 UI에 뿌려주면 될 것으로 보인다.

@router.post("/audio_to_text", summary="transfer audio to text")
async def audioToText(input_audio_path: str):

    file_path = input_audio_path.replace("http://localhost:8000", "").lstrip("/")

    project_root = Path(__file__).parent.parent.parent.parent.parent
    full_path = project_root / file_path

    # 음성 인식 처리
    result = whisper(str(full_path))

    return {"text": result["text"]}

이 값을 저장하기 위해 먼저 app/sound_assistant/page.tsx에서 useState 통해 상태 값을 선언한다.

const [audioToTextValue, setAudioToTextValue] = useState<string>("")

이것을 값을 받아 값을 바꿔주는 함수를 선언해서 넘겨주자.

const changeAudioToText = (data: string) => {
    setAudioToTextValue(data);
}

<AudioComponent changeAudioToText={changeAudioToText} />

이제 src/components/AudioComponent.tsx 에서 change 함수 처리를 한다.

const handleTransferText = async () => {
        try {
            const response = await fetch(`http://localhost:8000/api/v1/audio_to_text?input_audio_path=${uploadedAudio}`, {
                method: "POST"
            });
            const data = await response.json();
            changeAudioToText(data.text)
        } catch (error) {
            console.error("Transfer failed:", error);
        }
 }

이제 그 값을 첫번째 CommonPut.tsx 컴포넌트에 넣어주어 UI에 업데이트한다.

<CommonPut put={"output"} label={"텍스트 변환"} height={110} highHeight={150} value={audioToTextValue} />

그럼 다음과 같이 결과 UI가 나온다.

3단계 : 변환된 텍스트를 이용해 질문하기

이제 질문에 대한 답변을 얻기 위해 두 번째 pipeline 태스크가 필요한 상황으로 보인다.

text_generation = pipeline("text-generation")

이제 직접 프롬프팅을 통해 답변을 도출해내야 한다.

기존 텍스트 변환 내용 기반으로 답변을 해주어야 하므로, 기존 텍스트 변환 내용도 넘겨주어야 한다.

그래서 이전 라우팅에서 내용과 현재에서도 이 변수를 공유하려면, 전역 변수를 이용하자.

voice_txt, current_answer = ""

여기서 current_answer는 다음 단계에서 똑같은 과정을 거칠 것이므로 일단 참고만 해두자.

기존 텍스트 변환 라우터를 다음과 같이 수정하자.

@router.post("/audio_to_text", summary="transfer audio to text")
async def audioToText(input_audio_path: str):
    global voice_txt

    file_path = input_audio_path.replace("http://localhost:8000", "").lstrip("/")

    project_root = Path(__file__).parent.parent.parent.parent.parent
    full_path = project_root / file_path

    # 음성 인식 처리
    result = whisper(str(full_path))
    voice_text = result["text"]

    return {"text": result["text"]}

현재 질문 라우팅은 다음과 같이 설정하자.

@router.post("/text_generation", summary="text generation")
async def generate_text(question: str):
    global voice_txt

    if not voice_txt:
        return {"status": "fail", "message": "음성을 텍스트로 변환 후 질문하세요"}

    # 간단한 응답 생성 (영어 프롬프트 사용)
    prompt = f"Based on: {voice_txt[:100]}\nQuestion: {question}\nAnswer: "

    try:
        result = text_generation_pipeline(prompt, max_new_tokens=100, do_sample=True, top_p=0.95)
        generated_text = result[0]["generated_text"].strip()

        # 프롬프트 부분 제거하고 답변만 추출
        answer_start = generated_text.find("Answer:")
        if answer_start != -1:
            final_answer = generated_text[answer_start + 7:].strip()
        else:
            final_answer = generated_text

        return {
            "status": "success",
            "message": final_answer,
        }
    except Exception as e:
        return {
            "status": "fail",
            "message": f"텍스트 생성 중 오류가 발생했습니다: {str(e)}"
        }

이것을 토대로 프론트엔드 설정해보자.

먼저 questionValue를 통해 질문 데이터를 관리한다.

const [questionValue, setQuestionValue] = useState<string>("");

또 onChange 함수를 연결한다.

const changeQuestionValue = (e: React.ChangeEvent<HTMLInputElement>) => {
   setQuestionValue(e.target.value)
}

다음은 answerValue를 관리하자.

const [answerValue, setAnswerValue] = useState<string>("");

또, change 함수를 통해 순수함수를 구현하여, answerValue를 받아오자.

 const changeAnswerValue = (data: string) => {
    setAnswerValue(data)
 }

이제 PutCommon.tsx 컴포넌트에서 status가 성공할 경우에만 응답값을 받아오자.

const quest = async () => {
        try {
            const response = await fetch(`http://localhost:8000/api/v1/text_generation?question=${questionValue}`, {
                method: "POST"
            })
            const data = await response.json()
            if (data.status === "success") {
                changeAnswerValue(data.message)
                console.log(data.message)
            } else {
                console.error(data.message)
            }
        } catch (error) {
            console.log(error)
        }
 }

4단계 : 답변을 음성으로 듣기

현재 받은 답변을 기반으로 다시 음성으로 변환하는 TTS 기능을 구현해보자.

아까 전역 변수로 선언한 current_answer를 이용해보자.

먼저 TTS 함수 만들자.

async def text_to_voice(text):
    voice = "ko-KR-InJoonNeural"

    # 타임스탬프를 포함한 파일명 생성
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    filename = f"answer_{timestamp}.mp3"
    filepath = ANSWER_DIR / filename

    communicate = edge_tts.Communicate(text, voice)
    await communicate.save(str(filepath))

    # 파일 URL 반환
    file_url = f"http://localhost:8000/answer/{filename}"
    return file_url

이걸 이용해 API 함수 만들자.

@router.post("/tts", summary="text-to-speech")
async def tts():
    global current_answer
    if not current_answer:
        return {"status": "fail", "message": "변환할 텍스트가 없습니다"}

    try:
        file_url = await text_to_voice(current_answer)
        return {
            "status": "success",
            "audio_url": file_url
        }
    except Exception as e:
        return {
            "status": "fail",
            "message": f"음성 변환 중 오류가 발생했습니다: {str(e)}"

허깅 페이스(Hugging Face) - 감정 분석 앱 (6)

EunHaa — Fri, 5 Jun 2026 17:48:27 +0900

이번에 실습으로 만들어 볼 웹 애플리케이션은 감정 분석 애플리케이션이다.

앞서 허깅 페이스 Transformer로 할 수 있는 기능 중에 감정 분석이 있었는데

그것을 애플리케이션화 한다고 보면 된다.

총 6단계에 걸쳐 UI를 구현할 예정인데

먼저 1단계는 텍스트 인풋을 통해 감정과 확률을 아웃풋으로 받는 형태이다.

1단계 : 영어 문장

다음과 같은 Next.js 코드로 화면단(프론트엔드) 먼저 구현한다.

app/emotion/page.tsx

"use client";

import { useState } from "react";
import PutColumn from "@/components/PutColumn";


export default function EmotionPage() {
    const putArray = [
        {
            ele: 'input',
            label: 'text'
        },
        {
            ele: 'output',
            label: 'greeting'
        }
    ]

    const [inputValue, setInputValue] = useState<string>("");
    const [outputValue, setOutputValue] = useState<string>("");

    const inputChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
        setInputValue(e.target.value)
    }

    const outputChange = (data: string) => {
        setOutputValue(data)
    }


    const handleClear = () => {
        setInputValue("");
        setOutputValue("");
    }

    return (
        <main>
            <div id="wrap" className="w-[1080px] mx-auto">
                <h2 className="text-center mb-[30px]">AI 감정 분석 웹앱</h2>
                <p className="text-[14px] mb-[16px]">
                    Hugging Face Transformer 모델 기반 감정 분석
                </p>
                <div className="put__rc grid grid-cols-2 gap-[10px]">
                    {putArray.map((e, i) => (
                        <PutColumn
                            key={i}
                            ele={e.ele}
                            label={e.label}
                            value={e.ele === 'input' ? inputValue : outputValue}
                            onChange={e.ele === 'input' ? inputChange : outputChange}
                            onClear={e.ele === 'input' ? handleClear : undefined}
                        />
                    ))}
                </div>
            </div>
        </main>
    )
}

src/components/PutColumn.tsx

import { cn } from "@/lib/cn";
import PutBox from "./PutBox";

interface PutColumnProps {
    ele: string;
    label: string;
    value: string;
    onChange?: ((e: React.ChangeEvent<HTMLTextAreaElement>) => void) | ((data: string) => void);
    onClear?: () => void;
}

export default function PutColumn({
    ele,
    label,
    value,
    onChange,
    onClear,
}: PutColumnProps) {
    return (
        <div className={cn("put__column__" + ele)}>
            <PutBox textColor={"#8c8e99"} label={label} ele={ele} value={value} onChange={onChange} />
            {ele === "output" ? (
                <button className="w-full font-[600] py-[10px] bg-[#e4e4e6] rounded-[5px] cursor-pointer">
                    Flag
                </button>
            ) : (
                <div className="buttons flex gap-[10px]">
                    <button
                        className="flex-1 font-[600] py-[10px] bg-[#f87315] text-[#fff] rounded-[5px] cursor-pointer disabled:opacity-45"
                        disabled={!value.trim()}
                    >
                        Submit
                    </button>
                    <button
                        className="flex-1 font-[600] py-[10px] bg-[#e4e4e6] rounded-[5px] cursor-pointer"
                        onClick={onClear}
                    >
                        Clear
                    </button>
                </div>
            )}
        </div>
    );
}

src/components/PutBox.tsx

export default function PutBox({
    label,
    ele,
    value,
    onChange,
    textColor
}: {
    label: string;
    ele: string;
    value: string | number[];
    onChange?: ((e: React.ChangeEvent<HTMLTextAreaElement>) => void) | ((data: string) => void);
    textColor?: string;
}) {

    return (
        <div className="put__box p-[14px] border border-[#e7e7e9] rounded-[5px] mb-[30px]">
            <h2 className="text-[14px] font-[700] mb-[8px]" style={{ color: `${textColor}` }}>{label}</h2>
            {
                ele === 'input' ?
                    <textarea
                        className="resize-none w-full block box-border h-[200px] p-[14px] border border-[#e7e7e9] outline-none rounded-[5px]"
                        value={value as string}
                        onChange={(e) => {
                            if (onChange) {
                                (onChange as (e: React.ChangeEvent<HTMLTextAreaElement>) => void)(e);
                            }
                        }}
                    />
                    :
                    <div className="p-[14px] h-[200px] border border-[#e7e7e9] rounded-[5px] box-border">
                    </div>
            }
        </div>
    )
}

다음 코드 실행 시 아래와 같은 UI가 도출될 것이다.

중요한건 AI 기능이므로 프론트엔드 코드에 대한 자세한 설명은 넘어가도록 하겠다.

여기서 FastAPI 엔드포인트를 구축하여, 입력한 텍스트를 받아 LLM을 통해

감정의 긍/부정 여부 및 긍/부정 확률을 도출하는 간단한 앱을 구성할 것이다.

먼저, Transformer의 pipeline을 가져와 sentiment-analysis 태스크를 가져오자.

analyzer = pipeline("sentiment-analysis")

이 함수 변수를 input_text (단, 반드시 한 문장이어야 한다)에 적용시켜 결과값을 리턴하면 된다.

@router.post("/sentiment-analysis", summary="Analyze text sentiment")
async def get_sentiment(input_text: str):
    result = analyzer(input_text)
    return {"result": result}

이제 간단한 API 구축에 성공했으니, 프론트엔드와 연결시켜보자.

app/emotion/page.tsx 에서 handleSubmit 함수를 추가할 것이다.

const handleSubmit = async () => {
        try {
            const response = await fetch(`http://localhost:8000/api/v1/sentiment-analysis?input_text=${inputValue}`, {
                method: "POST",
            })
            const json = await response.json()
            console.log(json)
        } catch (error) {
            console.error(error)
        }
 }

이 코드를 통해 콘솔에 출력된 결과값은 아래와 같다.

올바로 응답값이 내려왔으므로, 이 응답값을 상태값으로 저장 후

greeting UI에 형식대로 출력하도록 하면 되겠다.

setOutputValue(`감정:${json.result[0].label}|확률:${json.result[0].score}`)

그리고 src/components/PutBox.tsx 에서 아래와 같이 처리한다.

<div className="p-[14px] h-[200px] border border-[#e7e7e9] rounded-[5px] box-border overflow-auto">
      {(value as string).split("|").map((e, i) => (
           <p key={i} className="leading-[1.6]">{e}</p>
      ))}
</div>

여기서 보여주는 감정과 확률 수치는 가장 높은 확률이 나온 것을 분석해서 보여주는 것이다.

즉 이 상황에서는 Negative일 확률이 99%, 나머지일 확률이 1%이므로

Negative, 99%를 보여주는 것이다.

2단계 : 영어 + 한국어 지원

한국어로 입력했을 때 분석해주는 한국어 인공지능 모델들을 살펴보자.

한국어로 처리하도록 개선하는 데에는 여러가지 방법이 있을 것이다.

물론 한국어 모델을 찾는 방법도 있겠지만,

번역 모델을 중간에 미들웨어처럼 끼워 넣을 수도 있다.

그 번역 모델을 통해 한국어를 영어로 번역 후

그것을 분석해달라고 요청할 수도 있다.

일단 실습에서는 간단한 한국어 모델을 사용하는 쪽으로 구성을 잡도록 하자.

한국어 모델을 3가지 정도 테스트해보도록 할 예정이다.

(감정 분석이 가능한 한국어 모델 3가지를 가져와봤다)

1) WhitePeak/bert-base-cased-Korean-sentiment

다음과 같이 모델명을 지정해보자. 그리고 바로 화면단에서 테스트해보면 된다.

analyzer = pipeline(
    "sentiment-analysis", model="WhitePeak/bert-base-cased-Korean-sentiment"
)

감정 부분 데이터가 우리가 아는 형식과 다르게 나오므로,

Negative / Postive / Neutral 형식으로 맵핑할 필요성이 있겠다.

model_map = {
    "LABEL_0": "NEGATIVE",
    "LABEL_1": "POSITIVE",
    "LABEL_2": "NEUTRAL",
}

def normalize_label(label: str) -> str:
    """Normalize sentiment label to standard format"""
    return model_map.get(label, label)

@router.post("/sentiment-analysis", summary="Analyze text sentiment")
async def get_sentiment(input_text: str):
    result = analyzer(input_text)

    result[0]["label"] = normalize_label(result[0]["label"])

    return {"result": result}

2) snunlp/KR-FinBert-SC

analyzer = pipeline(
    "sentiment-analysis", model="snunlp/KR-FinBert-SC"
)

기존 형식도 맵핑 딕셔너리에 키-속성으로 추가 후 테스트 해봤다.

이번에는 결과가 우리가 원하던 형식으로 잘 나오는 것 같으나, 분석 정확도는 첫번째 모델보다는 아닌 것 같다.

일단 우선순위를 뒤로 미뤄놓고 생각해보자.

3) nlptown/bert-base-multilingual-uncased-sentiment

확인해보면 알겠지만, 이 모델도 label 결과값이 우리가 원하는 형식과 다르므로,

label_map 딕셔너리에 형식을 추가해줄 것이다.

analyzer = pipeline(
    "sentiment-analysis", model="nlptown/bert-base-multilingual-uncased-sentiment"
)

model_map = {
    "LABEL_0": "NEGATIVE",
    "LABEL_1": "POSITIVE",
    "LABEL_2": "NEUTRAL",
    "NEGATIVE": "NEGATIVE",
    "POSITIVE": "POSITIVE",
    "NEUTRAL": "NEUTRAL",
    "1 star": "NEGATIVE",
    "2 stars": "NEGATIVE",
    "3 stars": "NEUTRAL",
    "4 stars": "POSITIVE",
    "5 stars": "POSITIVE",
}


def normalize_label(label: str) -> str:
    """Normalize sentiment label to standard format"""
    return model_map.get(label, label)


@router.post("/sentiment-analysis", summary="Analyze text sentiment")
async def get_sentiment(input_text: str):
    result = analyzer(input_text)

    result[0]["label"] = normalize_label(result[0]["label"])

    return {"result": result}

최종적으로 이런 테스트를 통해 어떤 모델이 감정 분석에 효율적인지 찾는 과정을 거쳐야 한다.

필자는 WhitePeak/bert-base-cased-Korean-sentiment 모델을 사용하도록 하겠다.

3단계: 감정 시각화

위와 같이, 감정 분석한 것을 시각화하는 과정을 거치겠다.

Output 부분 화면단을 만들어야 하므로, Next.js를 사용하여 만들었다.

app/emotion_visual/page.tsx

"use client";

import OutputColumn from "@/components/OutputColumn";
import PutColumn from "@/components/PutColumn";
import { useState } from "react";

export interface Output {
    model_lang: string;
    result: Result[];
}

interface Result {
    label: string;
    score: number;
}

export default function EmotionVisualPage() {
    const [inputValue, setInputValue] = useState<string>("");
    const [isSubmitting, setIsSubmitting] = useState<boolean>(false)
    const [outputValue, setOutputValue] = useState<Output | null>(null)

    const inputChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
        setInputValue(e.target.value)
    }

    const inputClear = () => {
        setInputValue("");
    }

    const inputSubmit = async () => {
        try {
            setIsSubmitting(true);
            const response = await fetch(`http://localhost:8000/api/v1/sentiment-analysis?input_text=${inputValue}`, {
                method: "POST"
            })
            const json = await response.json()
            setOutputValue(json)
        } catch (error) {
            console.log(error)
        } finally {
            setIsSubmitting(false);
        }
    }

    return (
        <main>
            <div id="wrap" className="w-[1080px] mx-auto">
                <h2 className="text-center mb-[30px]">AI 감정 분석 웹앱</h2>
                <p className="text-[14px] mb-[16px]">
                    Hugging Face Transformer 모델 기반 감정 분석
                </p>
                <div className="put__rc grid grid-cols-2 gap-[10px]">
                    <PutColumn ele="input" label="text" value={inputValue} onSubmit={inputSubmit} onChange={inputChange} onClear={inputClear} isSubmitting={isSubmitting} />
                    <OutputColumn output={outputValue} />
                </div>
            </div>
        </main>
    )
}

src/components/OutputColumn.tsx

import { Output } from "@/app/emotion_visual/page";
import { VscOutput } from "react-icons/vsc";
import OutputBar from "./OutputBar";

export default function OutputColumn({ output }: { output: Output | null }) {
    return (
        <div className="new__output w-full">
            <div id="outputArea" className="w-full border border-[#e7e7e9] rounded-[5px] overflow-auto flex flex-col">
                <div id="outputAreaTitle" className="w-[80px] h-[30px] border-r border-b border-[#e7e7e9] flex justify-center items-center gap-[6px]">
                    <VscOutput size={14} />
                    <span className="text-[12px]">Output</span>
                </div>
                {output ? (
                    <div id="output" className="flex flex-col pb-[50px]">
                        <h2 className="text-[19px] text-center mb-[20px]">{output.result[0].label}</h2>
                        <OutputBar current={[output.result[0].label, output.result[0].score]} />
                        <OutputBar current={["others", 1 - output.result[0].score]} />
                    </div>
                ) : (
                    <div id="output" className="flex flex-col pb-[50px]">
                        <h2 className="text-[19px] text-center mb-[20px]">No output</h2>
                    </div>
                )}
            </div>
            <button className="w-full font-[600] py-[10px] bg-[#e4e4e6] rounded-[5px] cursor-pointer mt-[30px]">
                Flag
            </button>
        </div>
    )
}

src/components/OutputBar.tsx

export default function OutputBar({ current }: { current: any[] }) {
    return (
        <div className="bar__container mb-[10px] self-center w-[90%]">
            <div className="bar h-[6px] rounded-[6px]" style={{ width: `${Math.floor(current[1] * 100)}%`, backgroundImage: `linear-gradient(to right,#f39b4b,#fadcb1)` }}></div>
            <div className="info w-full flex justify-between items-center">
                <span className="text-[14px]">{current[0]}</span>
                <span className="text-[14px]">{Math.floor(current[1] * 100)}%</span>
            </div>
        </div>
    )
}

여기서 json 데이터 기반으로 현재 감정과 반대 감정을 동시에 보내서 표현해주면 끝이다.

4단계: 다중 문장 감정 분석

그 동안 하나의 문장으로 분석한 결과를 알려주는 앱을 만들었다.

이번에는 여러 문장을 넣어서, 한 문장씩 결과를 알려주는 앱을 만들어 보고 싶다.

먼저 여러 문장을 받아서 리스트로 처리해야 하는데, 여기서 splitlines() 메소드를 사용해보자.

@router.post("/multi-sentiment", summary="multi-sentiment")
async def post_multi_sentiment(data: TextInput):
    # 리스트로 분리
    input_lists = input_text.splitlines()

위와 같은 상태로 분리되므로 우리가 원한 결과가 나왔다고 할 수 있겠다.

추가로 여백이 존재할 수도 있으므로 strip() 처리를 추가적으로 해 줄 필요는 있다.

# 여백 처리
sentences = [s.strip() for s in input_lists if s.strip()]

이제 각각 for를 돌면서 각 문장마다 결과값을 보내주어야 할 것 같다.

@router.post("/multi-sentiment", summary="multi-sentiment")
async def post_multi_sentiment(data: TextInput):

    results_text = []
    input_text = data.input_text

    # 리스트로 분리
    input_lists = input_text.splitlines()

    # 여백 처리
    sentences = [s.strip() for s in input_lists if s.strip()]

    # 각 문장별로 개별 분석
    analyzer = korean_analyzer if is_korean(input_text) else english_analyzer

    for sentence in sentences:
        result = analyzer(sentence)
        # result: [{"label": "LABEL_0", "score": 0.999}]
        best = result[0]
        label = best["label"]
        label = normalize_label(label)
        score = best["score"]

        results_text.append({"text": sentence, "label": label, "score": score})

    return results_text

프론트엔드에서 이 결과값을 map 메소드로 돌려주면 끝일 것 같다.

{outputs!.length > 0 ? (
                    <div id="output" className="flex flex-col pb-[50px]">
                        {
                            outputs!.map((out, idx) => (
                                <div key={idx} className="flex flex-col pt-[6px] px-[10px]">
                                    <p className="text-[14px]">문장: {out.text}</p>
                                    <p className="text-[14px]">감정: {out.label}</p>
                                    <p className="text-[14px]">확률: {out.score}</p>
                                </div>
                            ))
                        }
                    </div>
                ) : (
                    <div id="output" className="flex flex-col pb-[50px]">
                        <h2 className="text-[19px] text-center mb-[20px]">No output</h2>
                    </div>
                )}

추가로, Output UI를 데이터프레임(테이블) 형태로 구현해보자.

{outputs!.length > 0 ? (
                    <div id="output" className="flex flex-col pb-[50px] pt-[20px] px-[20px]">
                        <table className="border-collapse border border-[#e7e7e7]">
                            <thead>
                                <tr>
                                    <th className="border border-[#e7e7e7] pl-[10px] py-[8px] text-left">문장</th>
                                    <th className="border border-[#e7e7e7] pl-[10px] py-[8px] text-left">감정</th>
                                    <th className="border border-[#e7e7e7] pl-[10px] py-[8px] text-left">확률</th>
                                </tr>
                            </thead>
                            <tbody>
                                {
                                    outputs?.map((output: Outputs, index: number) => (
                                        <tr key={index}>
                                            <td className="border border-[#e7e7e7] pl-[10px] py-[8px]">{output.text}</td>
                                            <td className="border border-[#e7e7e7] pl-[10px] py-[8px]">{output.label}</td>
                                            <td className="border border-[#e7e7e7] pl-[10px] py-[8px]">{output.score}</td>
                                        </tr>
                                    ))
                                }
                            </tbody>
                        </table>
                    </div>
                ) : (
                    <div id="output" className="flex flex-col pb-[50px]">
                        <h2 className="text-[19px] text-center mb-[20px]">No output</h2>
                    </div>
                )}

5단계 : csv 파일 업로드 + 통계

이제는 파일로 데이터 분석을 실행해보자.

새로운 UI로 사용자에게 보여줄 예정이므로, 프론트엔드 코드를 다시 만들어보자.

Next.js 코드는 다음과 같다.

app/emotion_csv/page.tsx

"use client";

import { useState } from 'react';
import CsvResults from "@/components/CsvResults";
import FileAnalysis from "@/components/FileAnalysis";
import CsvOutputs from '@/components/CsvOutputs';

export interface AnalyzedData {
    all_reviews: number;
    positive_reviews: number;
    neutral_reviews: number;
    negative_reviews: number;
    positive_rate: number;
    neutral_rate: number;
    negative_rate: number;
}

export default function EmotionCsvPage() {
    const [results, setResults] = useState<string[]>([]);
    const [analyzedData, setAnalyzedData] = useState<AnalyzedData | null>(null);

    const changeResults = (data: string[]) => {
        setResults(data);
    }

    const changeAnalyzedData = (data: AnalyzedData) => {
        setAnalyzedData(data);
    }

    return (
        <main>
            <div id="wrap" className="w-[1080px] mx-auto">
                <h2 className="text-center mb-[30px]">AI 감정 분석 웹앱</h2>
                <p className="text-[14px] mb-[16px]">
                    Hugging Face Transformer 모델 기반 감정 분석
                </p>
                <FileAnalysis changeResults={changeResults} changeAnalyzedData={changeAnalyzedData} />
                <CsvResults results={results} />
                <CsvOutputs analyzedData={analyzedData} />
            </div>
        </main>
    )
}

src/components/CsvResults.tsx

import { cn } from "@/lib/cn";

export default function CsvResults({ results }: { results: string[] }) {
    return (
        <div id="csvResults" className="mt-[60px] w-full h-[400px] border border-[#e6e6e8] rounded-[8px] overflow-hidden flex flex-col">
            <h2 className="pl-[6px] pt-[8px] pb-[10px] h-[15px] bg-[#fff] border-b-[10px] border-[#e6e6e8] text-[14px] font-[500]">문장</h2>
            <div className={cn("flex-1 overflow-y-scroll flex flex-col", results.length == 0 && "justify-center items-center")}>
                {results.length > 0 ? results.map((result: string, index: number) => <p key={index} className={cn("px-[6px] text-[14px] py-[10px]", index % 2 === 1 ? "bg-[#fafafa]" : "bg-[#fff]")}>{result}</p>) : <p className="text-[14px]">파일이 비어있습니다.</p>}
            </div>
        </div>
    )
}

src/components/CsvOutputs.tsx

import { AnalyzedData } from "@/app/emotion_csv/page";

export default function CsvOutputs({ analyzedData }: { analyzedData: AnalyzedData | null }) {
    return (
        <div id="csvOutputs" className="w-full h-[200px] border border-[#e6e6e8] rounded-[6px] mt-[40px] p-[10px] flex flex-col">
            <h2 className="text-[14px] font-[500] mb-[20px] h-[20px] flex items-center">통계 결과</h2>
            {analyzedData ? (
                <div id="csvOutputsBox" className="w-full h-[140px] overflow-y-auto border border-[#e6e6e8] rounded-[6px] p-[10px] box-border flex-1 py-[30px] px-[20px]">
                    <p className="text-[14px]">
                        총 리뷰 수 : {analyzedData.all_reviews} <br />
                        <br />
                        긍정 리뷰 : {analyzedData.positive_reviews} 개 <br />
                        부정 리뷰 : {analyzedData.negative_reviews} 개 <br />
                        중립 리뷰 : {analyzedData.neutral_reviews}
                        <br />
                        <br />
                        긍정 비율 : {analyzedData.positive_rate} % <br />
                        부정 비율 : {analyzedData.negative_rate} % <br />
                        중립 비율 : {analyzedData.neutral_rate} %
                    </p>
                </div>
            ) : (
                <div id="csvOutputsBox" className="w-full h-[140px] border border-[#e6e6e8] rounded-[6px] p-[10px] box-border flex-1 flex flex-col justify-center items-center">
                    <p className="text-[14px]">감정분석을 실행해주세요.</p>
                </div>
            )}
        </div>
    )
}

FastAPI 코드는 아래와 같다.

@router.post("/csv_result", summary="result of csv")
async def post_csv_result(data: CsvInput):
    csv_array = []

    file_path = data.input_path.replace("http://localhost:8000", "").lstrip("/")

    # 프로젝트 루트 기준 전체 경로로 변환
    project_root = Path(__file__).parent.parent.parent.parent.parent
    full_path = project_root / file_path

    # csv 파일 다루기
    with open(full_path, "r", encoding="utf-8") as f:
        reader = pd.read_csv(f)
        for r in reader["review"]:
            csv_array.append(r)
        return {"data": csv_array}


@router.post("/csv_chart", summary="chart of csv")
async def post_csv_chart(data: CsvInput):
    file_path = data.input_path.replace("http://localhost:8000", "").lstrip("/")

    project_root = Path(__file__).parent.parent.parent.parent.parent
    full_path = project_root / file_path

    pd_result = pd.read_csv(full_path)
    pd_list = pd_result["review"].to_list()

    # 총 리뷰 수
    all_reviews = len(pd_list)

    # 긍정 리뷰 수
    positive_reviews = 0
    # 중립 리뷰 수
    neutral_reviews = 0
    # 부정 리뷰 수
    negative_reviews = 0

    # 긍정 비율
    positive_rate = 0
    # 중립 비율
    neutral_rate = 0
    # 부정 비율
    negative_rate = 0

    for sentence in pd_list:
        if is_korean(sentence):
            new_result = korean_analyzer(sentence)
        else:
            new_result = english_analyzer(sentence)

        if normalize_label(new_result[0]["label"]) == "긍정  ":
            positive_reviews += 1
        elif normalize_label(new_result[0]["label"]) == "중립  ":
            neutral_reviews += 1
        elif normalize_label(new_result[0]["label"]) == "부정  ":
            negative_reviews += 1

    positive_rate = round(positive_reviews / all_reviews * 100, 4)
    neutral_rate = round(neutral_reviews / all_reviews * 100, 4)
    negative_rate = round(negative_reviews / all_reviews * 100, 4)

    return {
        "all_reviews": all_reviews,
        "positive_reviews": positive_reviews,
        "neutral_reviews": neutral_reviews,
        "negative_reviews": negative_reviews,
        "positive_rate": positive_rate,
        "neutral_rate": neutral_rate,
        "negative_rate": negative_rate,
    }

밑에 있는 통계 결과를 추가로 차트 형식으로 변경해보자.

recharts 라이브러리를 이용하여 아래와 같이 변경하면 될 것 같다.

'use client';

import { AnalyzedData } from "@/app/emotion_csv/page";
import { PieChart, Pie, Cell, Legend, Tooltip, ResponsiveContainer } from "recharts";

export default function CsvOutputs({ analyzedData }: { analyzedData: AnalyzedData | null }) {
    const chartData = analyzedData ? [
        { name: "긍정", value: analyzedData.positive_reviews },
        { name: "부정", value: analyzedData.negative_reviews },
    ] : [];

    const COLORS = ["#4CAF50", "#F44336"];

    const renderCustomLabel = (entry: any) => {
        const { cx, cy, midAngle, innerRadius, outerRadius, name, value, percent } = entry;
        const radius = innerRadius + (outerRadius - innerRadius) * 0.2;
        const x = cx + radius * Math.cos(-midAngle * Math.PI / 180);
        const y = cy + radius * Math.sin(-midAngle * Math.PI / 180);
        const percentage = (percent * 100).toFixed(1);

        return (
            <text
                x={x}
                y={y}
                fill="white"
                textAnchor={x > cx ? 'start' : 'end'}
                dominantBaseline="central"
                className="text-[14px] font-[600]"
            >
                {`${name}\n(${percentage}%)`}
            </text>
        );
    };

    return (
        <div id="csvOutputs" className="w-full h-[400px] border border-[#e6e6e8] rounded-[6px] mt-[40px] p-[10px] flex flex-col">
            <h2 className="text-[14px] font-[500] mb-[20px] h-[20px] flex items-center">통계 결과</h2>
            {analyzedData ? (
                <div id="csvOutputsBox" className="w-full h-[340px] border border-[#e6e6e8] rounded-[6px] p-[10px] box-border flex-1">
                    <ResponsiveContainer width="100%" height="100%">
                        <PieChart>
                            <Pie
                                data={chartData}
                                cx="50%"
                                cy="50%"
                                labelLine={false}
                                label={renderCustomLabel}
                                outerRadius={100}
                                fill="#8884d8"
                                dataKey="value"
                            >
                                {chartData.map((entry, index) => (
                                    <Cell key={`cell-${index}`} fill={COLORS[index % COLORS.length]} />
                                ))}
                            </Pie>
                            <Tooltip />
                        </PieChart>
                    </ResponsiveContainer>
                </div>
            ) : (
                <div id="csvOutputsBox" className="w-full h-[340px] border border-[#e6e6e8] rounded-[6px] p-[10px] box-bower flex-1 flex flex-col justify-center items-center">
                    <p className="text-[14px]">감정분석을 실행해주세요.</p>
                </div>
            )}
        </div>
    )
}

6단계 : 가장 긍정적인 가장 부정적인 리뷰 찾기

긍정 및 부정 점수를 통해 가장 긍정적이고, 가장 부정적인 리뷰 찾아보자.

 # 가장 긍정/부정적인 리뷰 저장
    most_positive_review = None
    most_positive_score = -1
    most_negative_review = None
    most_negative_score = -1

    for sentence in pd_list:
        if is_korean(sentence):
            new_result = korean_analyzer(sentence)
        else:
            new_result = english_analyzer(sentence)

        label = normalize_label(new_result[0]["label"])
        score = new_result[0]["score"]

        if label == "긍정  ":
            positive_reviews += 1
            if score > most_positive_score:
                most_positive_score = score
                most_positive_review = sentence
        elif label == "중립  ":
            neutral_reviews += 1
        elif label == "부정  ":
            negative_reviews += 1
            if most_negative_review is None or score > most_negative_score:
                most_negative_score = score
                most_negative_review = sentence

{analyzedData && (
                <div className="mt-[20px] grid grid-cols-2 gap-[10px]">
                    <div className="border border-[#4CAF50] rounded-[6px] p-[12px] bg-[#f1f8f4]">
                        <h3 className="text-[12px] font-[600] text-[#4CAF50] mb-[8px]">가장 긍정적인 리뷰</h3>
                        <p className="text-[12px] text-[#333] leading-[1.5] line-clamp-2">{analyzedData.most_positive_review}</p>
                        <p className="text-[10px] text-[#666] mt-[6px]">신뢰도: {analyzedData.most_positive_score}</p>
                    </div>
                    <div className="border border-[#F44336] rounded-[6px] p-[12px] bg-[#fef4f3]">
                        <h3 className="text-[12px] font-[600] text-[#F44336] mb-[8px]">가장 부정적인 리뷰</h3>
                        <p className="text-[12px] text-[#333] leading-[1.5] line-clamp-2">{analyzedData.most_negative_review}</p>
                        <p className="text-[10px] text-[#666] mt-[6px]">신뢰도: {analyzedData.most_negative_score}</p>
                    </div>
                </div>
            )}

허깅 페이스(Hugging Face) - 멀티 모달 (5)

EunHaa — Tue, 2 Jun 2026 14:35:13 +0900

앞서서 Transformer의 pipeline 함수를 이용해 텍스트를 이용한 여러 태스크를 알아봤었다.

이번엔 이미지 관련된 태스크를 알아볼 예정인데, 이러면서 나오는 개념이 멀티 모달이다.

멀티 모달이란, 여러 종류의 데이터를 처리하는 AI 개념이다.

멀티 모달 종류에는 다음과 같은 종류가 있다.

텍스트 + 이미지
음성 + 텍스트
영상 + 텍스트
이미지 + 텍스트

이런 것을 하기 위해서 이미지 처리를 어떻게 할 것인지 필요한데 이미지 관련 태스크를 가져오면 될 것이다.

허깅 페이스(Hugging Face)에 접속해서 태스크 및 모델을 찾을 필요가 있다.

https://huggingface.co/

Hugging Face – The AI community building the future.

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

huggingface.co

먼저 Models 탭에 들어간다.

검색 항목에서 Tasks 항목에 들어간다.

여기서 이미지 분류(Image Classification)을 선택해보자.

선택 후, 옆 레이아웃에 있는 여러가지 모델들을 확인하면 될 것 같다.

여기서 뭐가 잘 되는지는 테스트를 해 봐야 안다.

코드 창으로 돌아가서 pipeline 코드를 작성해보자.

from transformers import pipeline
from PIL import Image

image = Image.open("./sample_concert.gif")
classifier = pipeline("image-classification") # 모델 선택하지 않을 경우 기본 모델 가져옴
result = classifier(image)
print(result)

코드에 대한 설명을 하자면, 가져온 이미지를 Image-Classification 태스크에 맞춰 파이프라인을 거쳐

나온 결과를 출력해주는 코드이다. 결과 예시는 다음과 같다.

위에 나오는 경고 콘솔은 model이 선택되지 않아 기본 모델을 선택한다는 뜻으로 무시해도 된다.

결론적으로 위와 같이 분석해서 JSON 형태로 출력해주는 걸 확인할 수 있었다.

그 다음으로, 많이 하는 Tasks가 이미지에 캡션 넣어주는 것(Image-to-text)이다.

다음과 같은 코드를 작성해보자.

역시 샘플 테스트이므로, 모델은 기본 모델로 사용할 것이다.

from transformers import pipeline
from PIL import Image
import json

capper = pipeline("image-to-text")

image = Image.open("./sample_concert.gif")

result = capper(image)

print(json.dumps(result,indent=4,ensure_ascii=False))

이제 그 다음으로 많이 하는 것은 텍스트를 통해 이미지로 생성하는 태스크이다.

이 개념을 주로 스테이블 디퓨전(Stable Diffusion)이라고 부른다.

이미지를 생성할 때 이미지를 처음부터 만들어주는 것이 아니라, 점점 이미지를 좋아지게 만드는 개념이다.

즉, 처음에는 노이즈 같은 이미지부터 시작해서 텍스트를 입력해서 텍스트 의미를 이해해서

점차적으로 노이즈를 제거하고 이미지를 완성하는 개념인 것이다.

여기서 GPU 기반으로 움직이면 빨리 결과가 도출되는 듯 하다.

Google Colab 같은 외부 환경에서는 런타임 유형 변경 설정이 필요하나,

필자는 GPU 기반 맥북에서 진행하고 있으므로, 이 부분은 넘어가도록 하겠다.

일단, Diffusers 개념이 필요하므로, 새로운 패키지를 설치할 필요가 있다.

pip install diffusers==0.29.2 peft==0.11.1

그리고 다음과 같은 코드를 작성해보자.

from diffusers import StableDiffusionPipeline
import torch

pipe = StableDiffusionPipeline.from_pretrained("runwayml/stable-diffusion-v1-5", torch_dtype = torch.float16)

# Use Apple Silicon GPU acceleration
pipe = pipe.to("mps")

image = pipe("서울의 밤 풍경").images[0]

image.save("./saved/seoul.png")

결과 이미지는 개인보다 다르므로, 직접 확인해보길 바란다.

이제 다음은 오디오 처리 중 음성을 텍스트로 바꾸는 것에 대해 알아보자.

허깅 페이스(Hugging Face)에서는 다음과 같은 태스크에 속한다.

여기서 많이 쓰는 태스크 개념이 whisper이다.

모델을 보면 whisper 기반으로 만들어진 모델들이 많다.

다음과 같은 코드로 테스트해보자.

from transformers import pipeline
import json

whisper = pipeline("automatic-speech-recognition", model="openai/whisper-base")
result = whisper("../data/obama.mp3", return_timestamps=True)
print(json.dumps(result,indent=4,ensure_ascii=False))

음성이 너무 길어, timestamp로 분리하여, chunks 설정을 통해 문장 별로 분리한 상태이다.

반대인 Text to Speech는 경량 TTS 모델들을 이용할 수가 있는데 간단히 테스트해보자.

import edge_tts

text = "안녕하세요 반갑습니다"
voice = "ko-KR-SunHiNeural"

output_file = "./saved/voice.mp3"

async def main():
    communicate = edge_tts.Communicate(text, voice)
    await communicate.save(output_file)

await main()

결과물들은 직접 확인해서 테스트해보길 바란다.

그럼 위에서 공부했던 개념들을 통해 간단한 웹앱을 만들어보자.

필자는 Next.js로 프론트엔드 화면단을 만들고, FastAPI로 백엔드 API 서버단을 구성했지만,

화면단 구현이 부담스러운 사람들은 Gradio나 Streamlit 같은 웹 프레임워크를 사용해도 좋을 것 같다.

목표 화면은 다음과 같다.

위 화면을 위해 구현한 Next.js 코드는 다음과 같다.

app/page.tsx

import ChatBox from "@/components/ChatBox";

export default function Home() {

  return (
    <main>
      <div id="wrap" className="w-[1080px] mx-auto">
        <h2 className="text-center">멀티모달 AI 챗봇</h2>
        <p className="text-[14px] mb-[20px]">이미지를 업로드하면 이미지에 대한 설명을 생성하는 챗봇입니다. 텍스트로 질문도 가능합니다.</p>
        <ChatBox />
      </div>
    </main>
  )
}

app/components/ChatBox.tsx

"use client";

import React, { useRef, useState, useEffect } from "react";
import { IoChatboxEllipsesSharp } from "react-icons/io5";
import { MdFileUpload, MdOutlineFileDownloadDone } from "react-icons/md";
import ChatMessage from "./ChatMessage";
import ImageUrlBox from "./ImageUrlBox";

export interface ChatBoxMessages {
    chat_id: string;
    message: string;
    fileUrl: string;
    isMe: boolean;
    timestamp: string;
}

export default function ChatBox() {
    const [chatMessage, setChatMessage] = useState<string>("");
    const [imageUrl, setImageUrl] = useState<string>("");
    const [inputHeight, setInputHeight] = useState<number>(0);
    const [chattingArray, setChattingArray] = useState([]);
    const [isLoading, setIsLoading] = useState<boolean>(false);
    const [isInitialLoading, setIsInitialLoading] = useState<boolean>(true);
    const chatBoxRef = useRef<HTMLDivElement>(null);

    const handleChatMessageChange = (e: React.ChangeEvent<HTMLInputElement>) => {
        setChatMessage(e.target.value);
    }

    const fileRef = useRef<HTMLInputElement | null>(null);

    const fileClick = () => {
        fileRef.current?.click();
    }

    const localFileUpload = async (file: File) => {
        try {
            const formData = new FormData();
            formData.append('file', file);

            const response = await fetch(`http://localhost:8000/api/v1/file-upload`, {
                method: "POST",
                body: formData
            });
            const json = await response.json();
            setImageUrl(json.url)
        } catch (e) {
            console.log(e);
        }
    }

    const handleFile = async (e: React.ChangeEvent<HTMLInputElement>) => {
        const file = e.target.files?.[0];
        if (file) {
            await localFileUpload(file);
        }
    }

    const closeImageUrl = () => {
        setImageUrl("")
    }

    const getChatMessage = async () => {
        try {
            const response = await fetch("http://localhost:8000/api/v1/get-chat");
            const json = await response.json();
            setChattingArray(json);
        } catch (e) {
            console.log(e)
        } finally {
            setIsInitialLoading(false);
        }
    }

    const submitChat = async () => {
        try {
            const currentMessage = chatMessage;
            const currentImageUrl = imageUrl;

            const params = new URLSearchParams({
                message: currentMessage,
                fileUrl: currentImageUrl
            });
            await fetch(`http://localhost:8000/api/v1/add-chat?${params}`, {
                method: "POST",
                headers: {
                    "Content-Type": "application/json"
                }
            })

            setChatMessage("");
            setImageUrl("");
            await getChatMessage();

            setIsLoading(true);
            const llmParams = new URLSearchParams({
                message: currentMessage,
                fileUrl: currentImageUrl,
            });
            const response2 = await fetch(`http://localhost:8000/api/v1/llm-chat?${llmParams}`, {
                method: "POST"
            });
            const llmResult = await response2.json();
            console.log("LLM Response:", llmResult);

            // 백엔드에서 자동으로 저장되므로 리스트 새로고침
            await getChatMessage();
            setIsLoading(false);
        } catch (e) {
            console.log(e);
            setIsLoading(false);
        }
    }

    useEffect(() => {
        const updateInputHeight = () => {
            if (chatBoxRef.current) {
                setInputHeight(chatBoxRef.current.clientHeight);

            }
        };

        updateInputHeight();

        const observer = new ResizeObserver(updateInputHeight);
        if (chatBoxRef.current) {
            observer.observe(chatBoxRef.current);
        }

        return () => observer.disconnect();
    }, []);

    useEffect(() => {
        getChatMessage()
    }, [])


    return (
        <div id="chatBox" className="w-full h-[400px] border border-solid border-[#e7e7e9] relative">
            <div id="chatBoxLabel" className="w-[80px] h-[25px] border-r border-b border-[#e7e7e9] flex justify-center items-center gap-[5px] text-[#8d8b8f]">
                <IoChatboxEllipsesSharp color={"#e7e7e9"} size={14} />
                <span className="text-[12px]">Chatbot</span>
            </div>
            <div className="chatbox_contents w-[95%] mx-auto flex flex-col gap-[10px] overflow-y-auto" style={{ height: `calc(400px - 37px - ${inputHeight}px)` }}>
                {isInitialLoading ? (
                    <div className="flex items-center justify-center h-full text-[14px] text-[#8d8b8f]">
                        데이터 로드 중...
                    </div>
                ) : (
                    <>
                        {
                            chattingArray.map((chat: ChatBoxMessages) => (<ChatMessage chatContent={chat} key={chat.chat_id} onDelete={getChatMessage} />))
                        }
                        {isLoading && <div className="text-[14px] text-[#8d8b8f]">LLM 처리 중...</div>}
                    </>
                )}
            </div>
            <div id="chatBoxInput" className="p-[10px] w-[95%] border-[#e7e7e9] border absolute bottom-[10px] left-[0] right-[0] mx-auto" ref={chatBoxRef}>
                <h2 className="text-[13px] font-[300]">Chatbot Input</h2>
                {
                    imageUrl && <ImageUrlBox url={imageUrl} closeImageUrl={closeImageUrl} />
                }
                <div className="real__input flex mt-[20px] items-center f">
                    <input type="file" className="hidden" ref={fileRef} onChange={handleFile} />
                    <button className="w-[30px] h-[30px] flex justify-center items-center hover:bg-[#fafafa] cursor-pointer" onClick={fileClick}>
                        <MdFileUpload size={20} />
                    </button>

                    <input type="text" className="block h-[30px] outline-none flex-1 border-none box-border placeholder:text-[#bbbbc2]" placeholder={"Enter message or upload file"} onChange={handleChatMessageChange} value={chatMessage} />
                    <button className="w-[30px] h-[30px] flex justify-center items-center" disabled={!chatMessage.trim()} onClick={submitChat}>
                        <MdOutlineFileDownloadDone size={20} color={!chatMessage.trim() ? "#f5f5f5" : "#232323"} />
                    </button>
                </div>
            </div>
        </div>
    )
}

app/components/ChatMessage.tsx

import { IoClose } from "react-icons/io5";
import { ChatBoxMessages } from "./ChatBox";


export default function ChatMessage({ chatContent, onDelete }: { chatContent: ChatBoxMessages; onDelete: () => void }) {
    const deleteChat = async () => {
        try {
            const response = await fetch(`http://localhost:8000/api/v1/delete-chat?chat_id=${chatContent.chat_id}`, {
                method: "DELETE"
            })
            const json = await response.json();
            console.log(json);
            onDelete();
        } catch (e) {
            console.log(e);
        }
    }

    return (
        <div className={`relative flex flex-col text-[14px] border max-h-[150px] p-[15px] ${chatContent.isMe ? "bg-[#fef7ec] border-[#fef7e3] self-end w-[25%]" : "bg-[#fafafa] border-[#e7e7e9] self-start max-w-[50%]"} `}>
            {chatContent.fileUrl && (
                <img src={chatContent.fileUrl} alt="fileImage" className="w-[50px] h-[50px] object-cover mb-[10px]" />
            )}
            <span>{chatContent.message}</span>
            {chatContent.isMe && <button className="absolute right-[10px] top-[10px]" onClick={deleteChat}><IoClose /></button>}
        </div>
    )
}

app/components/ImageUrlBox.tsx

import { IoClose } from "react-icons/io5";

export default function ImageUrlBox({ url, closeImageUrl }: { url: string, closeImageUrl: () => void }) {
    return (
        <div id="imageUrlBox" className="w-[55px] h-[50px] border border-[#e5e5e5] border-solid flex justify-center items-center relative">
            <img src={url} alt="fileImage" className="w-[40px] h-[40px] object-cover" />
            <button className="absolute top-[0] right-[0] p-[0] cursor-pointer" onClick={closeImageUrl}>
                <IoClose />
            </button>
        </div>
    )
}

위의 코드 적용 시 구현되는 UI는 아래와 같다.

화면단은 사람에 따라 다를 수 있으니 참고만 하고 넘어가도록 하고,

주요 기능에 필요한 FastAPI 코드를 알아보자.

먼저, 다음과 같이 파일을 첨부했을 때 등장하는 이미지 컴포넌트가 필요하므로 /file-upload 엔드포인트를 만들자.

이를 위해 엔드포인트 라우터 부분과 main.py 부분을 나누어서 작업했다.

./main.py

import uvicorn

if __name__ == "__main__":
    # Start the FastAPI application via uvicorn
    # reload=True makes the server reload on code changes
    uvicorn.run("app.main:app", host="localhost", port=8000, reload=True)

./app/main.py

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import HTMLResponse
from fastapi.staticfiles import StaticFiles
from app.core.config import settings
from app.api.v1.router import api_router
from pathlib import Path

# Initialize FastAPI app with metadata
app = FastAPI(
    title=settings.PROJECT_NAME,
    description="FastAPI Base Template with modern structure and weather API proxy.",
    version="1.0.0",
    openapi_url=f"{settings.API_V1_STR}/openapi.json" if settings.DEBUG else None,
)

# Configure CORS Middleware
# Allows all origins for local development, customize as needed
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# Include Central API Router
app.include_router(api_router, prefix=settings.API_V1_STR)

# Mount static files for uploads
upload_path = Path("uploads")
upload_path.mkdir(exist_ok=True)
app.mount("/uploads", StaticFiles(directory="uploads"), name="uploads")

./app/core/config.py

from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env", env_file_encoding="utf-8", extra="ignore"
    )

    PROJECT_NAME: str = "FastAPI Project"
    API_V1_STR: str = "/api/v1"
    DEBUG: bool = True

    WEATHER_API_URL: str = (
        "https://dev-agri.todayjeju.net/api/datahub/v0/weather/nearest-grid"
    )


settings = Settings()

./app/api/v1/file_upload.py

from fastapi import APIRouter, File, UploadFile, HTTPException
from fastapi.staticfiles import StaticFiles
import shutil
from pathlib import Path
from datetime import datetime
import os

router = APIRouter()

UPLOAD_FOLDER = Path(os.getcwd()) / "uploads"
UPLOAD_FOLDER.mkdir(exist_ok=True)

ALLOWED_EXTENSIONS = {"png", "jpg", "jpeg", "gif", "webp"}


@router.post("/file-upload", summary="file upload")
async def fileUpload(file: UploadFile = File(...)):

    file_ext = file.filename.split(".")[-1].lower()
    if file_ext not in ALLOWED_EXTENSIONS:
        raise HTTPException(status_code=400, detail="Invalid File Type")

    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_")
    filename = timestamp + file.filename
    filepath = UPLOAD_FOLDER / filename

    with open(filepath, "wb") as f:
        shutil.copyfileobj(file.file, f)

    file_url = f"http://localhost:8000/uploads/{filename}"

    return {"url": file_url, "filename": filename}

파일 업로드 엔드포인트 파일을 중점적으로 보자면,

업로드 폴더를 만들어, File 형태의 데이터를 받아 로컬 서버에 올려주는 방식이다.

이는 배포 시 따로 Superbase나 AWS_S3 같은 서버를 이용할 수도 있지만,

필자같은 경우 아직 배포 단계까진 가지 않을 예정이므로, 로컬에서만 처리해주자.

이제, 파일 업로딩하는 작업을 해주었으니, 채팅 보내기, 채팅 가져오기, 채팅 지우기, LLM 채팅 같은 채팅 작업을 해주어야 한다.

우리는 로컬에서 1:1 대화를 가정하고 할 것이므로 WebSocket은 사용하지 않겠다.

따라서, 메시지 히스토리에 계속 저장하는 방식으로 해 줄 예정이다. (물론 서버 재시작 시에는 초기화될 것이다)

./app/api/v1/chat.py

from fastapi import APIRouter
from datetime import datetime
import uuid
from transformers import pipeline
from PIL import Image
from typing import Optional
import asyncio
from concurrent.futures import ThreadPoolExecutor

router = APIRouter()

messageHistory = []

# 가벼운 모델 전역 로드
captioner = None
executor = ThreadPoolExecutor(max_workers=1)


def load_model():
    global captioner
    try:
        captioner = pipeline("image-to-text")
        print("LLM 모델 로드 완료")
    except Exception as e:
        print(f"LLM 모델 로드 실패: {e}")


@router.on_event("startup")
async def startup_event():
    load_model()


@router.post("/add-chat", summary="add-chat")
async def addChat(message: str, fileUrl: str):
    chat_id = str(uuid.uuid4())
    timestamp = datetime.now().isoformat()

    chat_item = {
        "chat_id": chat_id,
        "message": message,
        "fileUrl": fileUrl,
        "timestamp": timestamp,
        "isMe": True,
    }

    messageHistory.append(chat_item)

    return chat_item


@router.get("/get-chat", summary="get-chat")
async def getChat():
    return messageHistory


@router.delete("/delete-chat", summary="delete-chat")
async def deleteChat(chat_id: str):
    global messageHistory

    # 삭제할 메시지 찾기
    deleted_index = None
    for i, chat in enumerate(messageHistory):
        if chat["chat_id"] == chat_id:
            deleted_index = i
            break

    if deleted_index is None:
        return {"status": "not found", "chat_id": chat_id}

    # 내 메시지(isMe=True)인 경우, 그 다음 LLM 응답도 함께 삭제
    deleted_chat = messageHistory[deleted_index]
    if deleted_chat.get("isMe") and deleted_index + 1 < len(messageHistory):
        next_chat = messageHistory[deleted_index + 1]
        if not next_chat.get("isMe"):  # 다음이 LLM 응답이면
            messageHistory = [chat for chat in messageHistory if chat["chat_id"] not in [chat_id, next_chat["chat_id"]]]
        else:
            messageHistory = [chat for chat in messageHistory if chat["chat_id"] != chat_id]
    else:
        messageHistory = [chat for chat in messageHistory if chat["chat_id"] != chat_id]

    return {"status": "deleted", "chat_id": chat_id}


def analyze_image(fileUrl):
    """이미지 분석 (동기 함수)"""
    try:
        result = captioner(fileUrl)
        return result[0].get("generated_text", "") if result else "이미지 분석 실패"
    except Exception as e:
        return f"이미지 분석 중 오류: {str(e)}"


@router.post("/llm-chat", summary="llm-chat")
async def llmChat(message: Optional[str] = None, fileUrl: Optional[str] = None):
    global messageHistory, captioner

    llm_response = ""

    # 이미지가 있으면 분석 (비동기)
    if fileUrl and fileUrl.strip() and captioner:
        loop = asyncio.get_event_loop()
        llm_response = await loop.run_in_executor(executor, analyze_image, fileUrl)
    # 이미지가 없으면 메시지 사용
    elif message and message.strip():
        llm_response = message
    else:
        return {"error": "message 또는 fileUrl이 필요합니다"}

    # LLM 응답을 messageHistory에 저장
    llm_chat_id = str(uuid.uuid4())
    llm_timestamp = datetime.now().isoformat()

    llm_chat_item = {
        "chat_id": llm_chat_id,
        "message": llm_response,
        "fileUrl": "",
        "timestamp": llm_timestamp,
        "isMe": False,
    }

    messageHistory.append(llm_chat_item)

    return llm_chat_item

먼저 addChat() 함수를 살펴보면, message와 fileUrl을 가져와서, 전체 messageHistory에 추가하는 과정이다.

그 messageHistory()를 getChat()에서 받아오는 형태이고,

deleteChat()에서 자신의 메시지와, LLM 메시지를 모두 삭제하는 형태이다.

LLM 메시지 로직이 조금 복잡한데, 간단하게 설명하자면,

transformer의 pipeline을 이용하여 image-to-text 태스크를 통해 result를 받아 넘겨주는 형태이다.

다만 이미지 파일이 넘어오는지 안 넘어오는지를 비동기 처리했다.

실제 받는 데이터는 LLM이 실제 이미지를 받아 캡셔닝한 형태가 된다.

최종적으로 다음 엔드포인트를 router.py에서 연결해줌으로, API 구성이 완료되었다.

from fastapi import APIRouter
from app.api.v1.endpoints import hello, fileUpload, chat

api_router = APIRouter()

# Include endpoints routers
api_router.include_router(hello.router, tags=["default"])
api_router.include_router(fileUpload.router, tags=["fileUpload"])
api_router.include_router(chat.router, tags=["chat"])

이제 좀 더 발전해서, 다음 같이 답변 형식을 정해주는 형태로 변경해보자.

FastAPI에서 LLM 챗 코드만 수정해주면 될 것 같다.

import textwrap

prompt = textwrap.dedent(
        f"""이미지 설명:
            {llm_response}

            사용자 질문:
            {message if message else 'N/A'}
        """
    )

llm_chat_item = {
    "chat_id": llm_chat_id,
    "message": prompt,
    "fileUrl": "",
    "timestamp": llm_timestamp,
    "isMe": False,
}

messageHistory.append(llm_chat_item)

여기서 prompt 형식 (띄어쓰기 등)을 맞춰야 하므로, 프론트엔드에서 조금 처리가 필요할 것 같다.

<span className="whitespace-pre-line">{chatContent.message}</span>

그럼 다음과 같이 구현할 수 있다.

이제 마지막으로, 분석한 이미지에 대한 추가 질문에 대한 답변을 구현해보자.

그러기 위해서는 태스크를 하나 더 추가해야 한다. 추가 질문에 대한 답변 태스크는 text-generation 인데

앞서 위의 코드와 같이 전역 변수를 선언한 후 지역 변수처럼 사용할 것이다.

global generator = None

def load_model():
    global captioner, generator
    try:
        captioner = pipeline("image-to-text")
        generator = pipeline("text-generation", model="Qwen/Qwen2.5-1.5B-Instruct")
        print("LLM 모델 로드 완료")
    except Exception as e:
        print(f"LLM 모델 로드 실패: {e}")

지역 변수처럼 사용을 위해서는 함수 내에서 global 예약어를 사용해야 하며, 파이프라인으로 연결해서 변수에 저장시킨다.

이 함수는 위에서 처럼 앱이 시작하는 동시에 로드될 것이므로, 정상적으로 처리된다면 LLM 로드 완료가 콘솔에 뜰 것이다.

이를 통해 메인 로직은 llm-chat에서 수정해줄 것인데, 이미지 설명을 가져오는 것이 공통되므로

current_caption 전역변수로 로직을 조금 수정해줄 것이다.

current_caption = ""

if fileUrl and fileUrl.strip() and captioner:
        loop = asyncio.get_event_loop()
        llm_response = await loop.run_in_executor(executor, analyze_image, fileUrl)
        current_caption = llm_response

        prompt = textwrap.dedent(
            f"""이미지 설명:
                {current_caption}

                사용자 질문:
                {message if message else 'N/A'}
            """
        ).strip()

처음에 했던 이미지를 보냈을 때 이미지를 분석하는 로직이다. 코드가 복잡하긴 하지만 간단하게 설명하자면,

LLM을 통해 캡션명 받은 것을 current_caption으로 받아주어, 그 뒤에 사용자가 이미지에 대해 추가로 질문했을 때

LLM에 current_caption를 한번 더 넘겨주겠다는 의미로 변수를 관리했다.

else:
            new_prompt = textwrap.dedent(
                f"""\
                당신은 이미지 분석 AI입니다.
                다음 이미지 설명을 참고해서 사용자의 질문에 한 문장으로 답변하세요.

                이미지 설명:
                {current_caption}

                질문:
                {message}

                답변:\
            """
            )
            print(new_prompt)

            # 비동기로 generator 실행 (FastAPI 이벤트 루프가 차단되는 것 방지)
            if generator:
                loop = asyncio.get_event_loop()
                result = await loop.run_in_executor(
                    executor,
                    lambda: generator(
                        new_prompt,
                        max_new_tokens=50,
                        return_full_text=False,
                        pad_token_id=generator.tokenizer.eos_token_id,
                    ),
                )
                prompt = (
                    result[0].get("generated_text", "").strip()
                    if result
                    else "답변을 생성하지 못했습니다."
                )
            else:
                prompt = "텍스트 생성 모델이 로드되지 않았습니다."
    else:
        return {"error": "message 또는 fileUrl이 필요합니다"}

다음은 이미지가 아니라 텍스트를 보냈을 때 처리 방법이다. LLM 프롬프트를 통해 앞서 받았던 이미지 설명과 질문을 같이 보내고

그에 대한 대답을 같이 받아오는 형식이다. 최종적으로 JSON에는 prompt 변수가 들어가므로, 비동기 설정을 해주어서

generator 함수를 통해 답변을 받거나, 답변이 생성하지 못했다는 경고메시지를 받게 된다.

데이터 분석 - 판다스 (2)

EunHaa — Sun, 31 May 2026 00:16:05 +0900

판다스(Pandas)는 Python에서 데이터를 쉽고 효율적으로 분석하고 처리하기 위해

사용하는 대표적인 데이터 분석 라이브러리이다. 엑셀과 비슷한 형태의 표(Tabular Data)를

다룰 수 있으며, Series와 DataFrame 이라는 강력한 자료구조를 제공한다.

CSV, Excel, SQL 등의 다양한 데이터 파일을 불러와 정렬, 필터링, 결측치 처리, 통계 분석 등을

간편하게 수행할 수 있으며, 대량의 데이터를 빠르게 가공할 수 있다.

설치방법

pip install pandas

python -m pip install pandas

첫번째 방법은 글로벌 설치이고, 두번째는 가상 환경 내의 설치이다.

또한 외부 라이브러리이므로, 사용하려면 import 문으로 라이브러리를 불러와야 한다.

import pandas as pd

시리즈 (Series)

판다스(Pandas)에서 제공하는 가장 기본적인 1차원 데이터 구조이며

값(Value)과 인덱스(Index)가 함께 구성된 자료형이다.

넘파이(Numpy)의 1차원 배열과 비슷하나, 각 데이터에 이름표 역할을 하는 인덱스가 추가되어

데이터를 더 체계적으로 관리할 수 있다.

데이터의 값(Value)이 들어가면 그 값에 이름표 역할을 하는 인덱스(Index)가 부여되는 형식이다.

예시를 살펴보면서 이해해보자.

idx = ['김사과','반하나','오렌지','이메론','배애리']
data = [67, 75, 90, 62, 98]

여기서 시리즈를 만들려면, 판다스(Pandas) 안의 함수(메소드)를 통해 만드는데 Series 메소드를 통해 만든다.

pd.Series(data,idx)

첫 매개변수에 데이터 값(Value)를 넣고, 두번째 매개변수에 인덱스(Index) 항목을 넣는 것이다.

그런데 만약 다음처럼 인덱스(Index)를 안 넣을 경우에는

pd.Series(data)

다음과 같은 결과가 나오며, 자동으로 번호(인덱스)가 추가되는 방식이다.

반대로 인덱스를 넣을 경우에는 번호(인덱스)에 idx가 차례대로 배치되는 모습이다.

이제 이 시리즈를 변수에 저장해보자.

ser1 = pd.Series(data, idx)

그리고 시리즈의 속성들을 출력해보자. 먼저 index를 출력해보자.

print(ser1.index)

출력해보니까 Index 객체라고 정의되어 있다.

이번에는 Series의 values를 출력해보자.

print(ser1.values)

시리즈는 이렇게 인덱스 객체와 다차원 배열(ndarray)인 values로 구성되어 있다는 점을 알았다.

그런데 인덱스 객체는 처음 보는 객체여서 설명이 필요할 것 같다.

여기서 인덱스(Index) 객체는 시리즈(Series)와 데이터 프레임(DataFrame)에서

각 위치를 식별하고 관리하기 위한 이름표(Label) 역할을 하는 자료구조이다.

일반 리스트처럼 보이지만, 단순한 데이터 저장용이 아니라 데이터를 빠르게 검색하고 정렬하며

서로 다른 데이터끼리 매칭할 수 있도록 최적화된 판다스(Pandas) 전용 객체이다.

리스트와 달리, 데이터를 인덱싱으로 접근해서 수정하지 못한다.

데이터 프레임(DataFrame)

판다스(Pandas) 라이브러리에서 제공하는 중요하고 강력한 데이터 구조로,

2차원 테이블 형태의 데이터를 다루는데 사용된다. 각 요소는 인덱스(Index), 열(Column), 값(Value)으로 구성되어 있다.

데이터 프레임은 행과 열로 이루어져 있고, 각 열은 다양한 데이터 타입을 가질 수 있다. 값은 ndarray 기반으로 저장된다.

그림에서 보면 알수 있듯이 시리즈(Series)가 모이면, 데이터 프레임(DataFrame)이 되는 구조이다.

다만 합칠 때는 시리즈(Series)의 인덱스가 같아야 합쳐진다. 합쳐진 각 시리즈의 제목이 한 열(컬럼)이 되는 것이다.

직접 예제를 살펴보자.

data = [[67, 93, 91],
        [75, 68, 96],
        [87, 81, 82],
        [62, 70, 75],
        [98, 56, 87]]
        
idx = ['김사과', '반하나', '오렌지', '이메론', '배애리']
col = ['국어', '영어', '수학']

다음은 데이터, 인덱스, 컬럼 변수들이다. 이걸 가지고 데이터프레임을 한번 만들어보자.

일단 데이터 값만 먼저 넣을 것이다.

pd.DataFrame(data)

그 결과는 들어가지 않은 인덱스와 컬럼은 0,1,2,.... 같은 형태로 채워지고

2차원 데이터(값)이 그에 맞게 구성되는 것을 확인할 수 있다.

이번에는 인덱스까지 넣어보자.

pd.DataFrame(data, idx)

그러면 왼쪽 행에 각각 인덱스가 표시되고, 넣지 않은 컬럼만 0,1,2... 같이 자동 배치될 것이다.

그러면 컬럼까지 전부 다 넣어보자.

(참고로 매개변수의 순서를 맞추지 않으면 당연히 오류가 난다.)

pd.DataFrame(data, idx, col)

이제 완벽한 데이터 프레임이 구성이 되었다.

그런데 앞선 내용에서 설명을 하긴 했지만, 매개변수가 몇십개가 넘어가는 메소드나 함수에서 다 순서를 맞출 수 있을까?

아니다. 매개변수를 미리 셋팅해놓는 기본 매개변수로 해결할 수 있을 것이다.

그런데 만약 진짜 넘겨야 되는 매개변수라면 어떻게 해야 할까? 전부 순서를 맞춰 주는 것이 아니라,

매개변수 = 값 형태로 매개변수로 넣어주면 되는 것이다.

그래서 위와 같은 경우도, 전부 순서를 맞출 필요 없이 매개변수 = 값 형태로 구성할 수 있다. 다음처럼 말이다.

df = pd.DataFrame(index=idx,columns=col,data=data)

즉 매개변수의 이름을 쓰면 순서가 달라도 관계없기 때문에 매개변수의 순서를 일일이 확인할 필요가 없는 것이다.

앞서 Python의 기본에서 학습했던 내용이므로, 꼭 기억해두자.

그러면 저장한 데이터프레임 변수에서 각 속성들을 출력해보자.

print(df.index)
print(df.columns)
print(df.values)

그런데 여기서 columns 속성이 인덱스 객체로 인식되는 점에 주목해보자.

만약 데이터가 기하급수적으로 많을 경우, 값은 다차원 데이터이므로 컬럼을 통해서 데이터 값을 찾아야 할 수도 있다

즉 인덱스와 컬럼 항목은 어떤 데이터를 찾는데 속도가 빨라야 하므로 인덱스 객체를 이용하는 것이다.

이번에는 딕셔너리를 사용해서 데이터프레임을 만들어보자.

dic = {
   '국어':[67, 75, 76, 62, 98],
   '영어':[93, 68, 81, 70, 56],
   '수학':[91, 96, 82, 75, 87]
}

df = pd.DataFrame(data=dic, index=idx)

키와 값의 구조가 데이터에 들어가게 되면, 자동으로 컬럼까지 만들어주는 특징이 있다.

인덱스는 그대로 구조대로 가고, 딕셔너리의 키가 컬럼이 되고, 딕셔너리의 값은 값이 되는 특징이다.

데이터 프레임 만들기가 편한 구조로, 딕셔너리를 이용하기도 한다.

CSV 파일 읽기

CSV 파일이란 Comma-Separated Values 파일의 약자로,

데이터를 단순한 텍스트 형식으로 저장하는데 사용하는 파일 형식이다.

직접 CSV 파일 하나를 읽어오겠다. 동시에 이 파일을 메모리에 올리겠다.

메모리에 올리면서 동시에 csv 파일을 데이터프레임으로 만들 것이다.

df = pd.read_csv("./광고모델_브랜드평판.csv")

실제로 타입을 찍어보면 다음과 같다.

print(type(df))

이제 판다스(Pandas)의 데이터프레임을 만들고 나서 데이터 분석 위해 해야 할 것들 몇가지를 알아보자.

먼저, 데이터프레임(DataFrame)의 info라는 메소드이다.

df.info()

이 메소드를 실행하면 다음과 같은 분석 결과가 나온다.

가장 중요한 이 분석 결과를 볼 줄 알아야 하는데,

가장 위에 있는 것은 csv 파일을 불러와 저장한 변수의 데이터 타입인데, 여기서는 데이터프레임 이다.

두번째에 있는 RangeIndex는 전체 데이터 갯수 및 인덱스 범위를 지칭한다. 여기서는 총 20개로 지칭된다. (0 ~ 19)

세번째에 있는 Data Columns는 말 그대로 데이터 컬럼의 개수이다. 여기서는 밑에 나오듯이 총 7개이다.

그 컬럼 중에 중요한 것이 Non-Null Count 항목이다. 말 그대로, Null이 아닌 데이터 개수를 지칭한다.

아까 NaN이 있었던 혈액형을 제외하고 다 채워져 모두 20개로 지칭되고 있다. 혈액형만 2개의 결측값이 있어 18개이다.

마지막으로, DType은 데이터 타입을 의미한다. 여기선 컬럼의 각 요소의 데이터 타입을 말하는데 object로 표시된다.

(자세히 들어가면 str으로 이해해도 된다.)

전체적으로 이 메소드의 목적은 Null 값이 몇개 있는지 한 눈에 보기 위함이다.

Null 값이 중요한 이유는 나중에 머신러닝/딥러닝에서 데이터 학습을 시킬 때

Null 값이 있으면 위험하기 때문이다. (잘못된 연산 발생)

이번에는 df (데이터프레임 변수)의 컬럼 부분을 출력해보겠다.

df.columns

아까 살펴봤듯이 데이터프레임이므로, 컬럼 부분은 인덱스 객체로 출력될 것이다.

여기서 컬럼 이름을 바꿔주는 방법을 알아보자.

new_columns = ['name','company','gender','birthday','height','blood','brand']
df.columns = new_columns
df

컬럼의 개수와 동일한 문자열이 들어간 새로운 리스트를 만든 후에 column 속성에 한꺼번에 할당하는 방법이다.

실제로 컬럼이 바뀐 문자열로 변경됨을 확인할 수 있다!

이번에는 통계 정보를 보는 방법을 알아보자.

df.describe()

그 결과는 다음과 같다.

저 메소드에서는 수치 값으로 볼 수 있는 통계 정보가 나오는데, 그러는데 사실 데이터 값 중에

수치값으로 볼 수 있는게 없다는 것을 알 것이다. (데이터 타입이 모두 str 이기 때문에)

그래서 위는 문자열에 관련된 통계 정보만 나온 것이다.

그래서 먼저 키(height)에 해당하는 height 값을 숫자형으로 바꿔줘야 할 것 같다.

그래야 다음과 같은 describe 정보를 얻을 수 있기 때문이다.

하지만, 지금은 다음과 같이 문자에 관련 정보만 나오고 있는 것이다.

df.describe(include=object)

이제, 숫자에 관한 정보를 보기 전에 먼저 원하는 갯수의 데이터 보는 방법부터 알아보자.

1. 상위 5개의 row(행) 출력

총 데이터에서 위에서부터 5개의 행만 출력하는 메소드이다.

아무것도 설정하지 않을 경우 기본 값이 5이기 때문에 상위 5개만 출력된다.

df.head()

만약, 상위 3개만 보고 싶다면, 다음과 같이 설정해주면 된다.

df.head(3)

2. 하위 5개의 row(행) 출력

만약에 내가 끝에서부터 데이터를 가져오고 싶다면, 다음과 같이 설정하자.

이것 역시 기본 값은 5이므로, 하위 5개의 행이 출력된다.

df.tail()

데이터 정렬

오름차순 정렬

index 기준으로 오름차순 정렬하는 메소드이다.

그러나 이미 처음부터 index 기준으로 정렬이 되어 있는 형태이다.

그러므로 변화는 없을 것이다.

df.sort_index()

내림차순 정렬

index를 기준으로 내림차순 정렬하는 메소드이다.

df.sort_index(ascending=False)

정렬 기준 바꾸기

키(height)를 기준으로 오름차순 정렬을 하려고 한다. 다음과 같은 설정을 추가해주면 된다.

df.sort_values(by="height")

이렇게 정렬이 잘 된 것처럼 보이지만, 여기에서는 문제가 하나 발생한다.

문자열 비교는 사전(Dictionary) 순서로 비교하므로 182cm > 182.2cm 같은 이상한 결과가 발생하기 때문이다.

다음처럼 말이다.

그 원리는 182cm와 182.2cm를 비교하게 되면, 182 부분까지는 똑같고

c와 .이랑 비교를 하게 되므로, .의 유니코드가 우선이라 오름차순 순위가 올라가는 사태가 발생하는 것이다.

그래서 인덱스가 height인 시리즈를 선택해서 그 값들을 숫자로 바꾸는 과정이 지금 필요하다.

다음과 같이 말이다.

df['height'] = df['height'].str.replace('cm','').astype(float)

문자열 중 cm을 제거하고 숫자만 남은 문자열을 숫자형으로 캐스팅하는 코드이다.

그러면 height 시리즈는 다음과 같이 실수형으로 변화한다.

이렇게 바꾸었으면 height 컬럼은 숫자로써 사용할 수 있겠다.

그런 김에 숫자처럼 생긴 문자열은 brand 시리즈도 숫자형으로 캐스팅해보자.

df['brand'] = df['brand'].str.replace(",", '').astype(int)

그럼 다음과 같은 결과가 나온다.

그러면 데이터 타입이 제대로 바뀌었는지 info 메소드를 통해 정보를 확인해보자.

df.info()

결과를 보면 알겠지만, height은 float 타입으로, brand는 int 타입으로 변경되었다.

그러면 통계 정보도 바뀌지 않았을까? 확인해보자.

df.describe()

이제 숫자 위주의 통계 정보가 보임을 확인할 수 있다!

그러면 키(height)으로 다시 내림차순 정렬해보자.

df.sort_values(by='height', ascending=False)

아까 문제였던 182.2cm와 182cm의 비교가 해결됨을 확인할 수 있다.

이제 한 가지 해결할 문제가 생기는데

이렇게 키가 똑같은 중복 데이터가 생겼을 때는 추가로 정렬 기준이 있을까라는 의문이 생긴다.

그 때 키가 같을 때는 브랜드 평판지수(brand)가 높은 사람이 상단으로 올라가게 하고 싶다는 것이다.

그러기 위해서 2차 정렬 셋팅이 필요하다.

# 1차 정렬: 키 (내림차순) 2차 정렬: 브랜드 (내림차순)
df.sort_values(by=["height","brand"], ascending=[False, False], na_position='first')

이렇게 같은 키일때는 brand 크기 순서대로 내림차순됨을 확인할 수 있다.

여기서 na_position 옵션은 기준 값이 NaN이 되었을 때 어디에 위치시킬지 정하는 옵션이다.

지금 같은 경우, first이므로, 맨 위에 위치하는 경우이다.

인덱싱

일단 맨 앞 5개의 행 데이터만 먼저 뽑아보자.

df.head()

여기서 blood에 해당하는 시리즈만 보고 싶다.

다음과 같이 2가지 방법으로 blood 시리즈만 뽑을 수 있다.

df['blood']
df.blood

왜 2가지 경우를 제공하는 것일까?

만약에 "blood"를 다음과 같이 변수에 저장했다고 해보자.

a = "blood"

그러면 다음과 같이 사용할 수도 있지 않을까?

df[a]
df.a

결론적으로, [] 안에 변수 여러 개를 넣을 수도 있고, for 문을 돌리거나 변수를 이용해 내가 원하는

데이터프레임의 시리즈를 뽑을 수가 있다.

첫번째 경우는 프로그램의 확장성을 위한 것이고, 두번째는 가독성을 위해 제공한 것이다.

추가로, 아까 우리가 데이터 맨 위 3개의 행을 가져오는 방법을 공부했었다.

df.head(3)

이와 똑같은 의미의 코드를 다음과 같이 작성할 수 있다.

df[:3]

열은 다 가져오고, 행은 0부터 2까지 3개 가져오라는 의미이다.

이번엔 확장된 개념은 로케이션 인덱싱(loc)에 대해 알아보자.

로케이션 인덱싱은 컬럼 인덱싱인데 다음과 같이 사용한다.

# 컬럼 인덱싱
# df.loc(행관련인덱싱, 열관련인덱싱)

df.loc[:,'name']

행은 모두 가져오라는 뜻이고, 열은 'name' 컬럼만 가져오라는 뜻이다.

결국 다음과 같은 코드이다.

df['name']

그런데 굳이 df['name'] 이 있는데 왜 확장된 개념을 제공하는 것일까?

다음과 같은 예시를 한번 더 살펴보자.

 df.loc[2:5, 'name']

이것은 2부터 5까지의 행을 가져오고, 그 중 'name' 컬럼만 가져오라는 것이다.

이것은 앞서 배운 슬라이싱과 조금 달라서 뒷 값인 5를 포함한다는 점을 꼭 기억해두자.

그럼 컬럼을 여러 개 가져오려면 어떻게 해야 할까? 여러 개를 뭉칠려면 리스트로 뭉치면 된다.

다음과 같이 말이다.

df.loc[2:5, ['name','gender','height']]

그렇다면, 이번엔 행 중에 2번과 5번만 뽑아오고 싶다고 해보자.

그러면 다음과 같이 작성할 수 있다.

df.loc[[2,5], ['name','gender','height']]

범위를 지정해주는 것과 하나 하나 인덱스를 찍는 것을 구분해야 할 것 같다.

다음과 같은 예제는 무슨 의미일까?

df.loc[2:5, 'name':'gender']

행은 2부터 5까지이고, 컬럼은 name 컬럼부터 gender 컬럼까지 출력해달라는 의미이다.

이번엔 더 확장된 개념인 iloc(index-location)에 대해 알아보자.

다음과 같은 예시를 보자.

df.iloc[:,0]

한마디로 인덱스 숫자만으로 로케이팅을 하는 것이다.

위 의미는 행은 모두 가져오고, 컬럼은 0번째 컬럼만 가져오라는 것이다.

다음과 같은 예시를 살펴보면 어떨까.

df.iloc[:,0:3]

이것은 모든 행을 가져오고, 컬럼은 0부터 2까지 가져오라는 것이다. (이번에는 끝 값을 포함하지 않는다)

이번엔 인덱싱에 조건식을 넣는 방식을 알아보자.

 df['height'] >= 180

결과값이 각 인덱스 별로 bool 타입으로 결과가 나온다. 이것을 통해 bool Indexing을 할 수가 있다.

df[df['height'] >= 180]

이것은 데이터프레임에서 True인 것만 뽑아서 나올 것이다.

여기서 조금 더 확장(응용)해서 이 중 이름만 보고 싶다면 어떻게 해야할까?

다음과 같이 할 수 있다.

df[df['height'] >= 180]['name']

이것을 loc를 통해 만들면 다음과 같이 할 수도 있다.

df.loc[df['height'] >= 180,'name']

결측값

결측값(Missing Value)은 데이터가 존재하지 않거나 비어있는 값을 의미하고, 보통 NaN 형태로 표현된다.

예를 들어, 키 / 몸무게 / 나이 같은 정보가 입력되지 않았거나 수집 과정에서 누락된 경우 발생한다.

데이터 분석과 머신러닝에서는 결측값이 매우 중요하며, 그대로 두면

평균 계산, 통계 분석, 모델 학습과정에서 오류나 성능저하가 발생할 수 있다.

결측값 처리는 데이터 품질을 높이고 정확한 분석 결과를 얻기 위한 매우 중요한 데이터 전처리 과정이다.

결측값 처리의 방법에는 몇가지가 있는데,

첫번째, NaN이 들어있는 행을 과감히 지워버리는 것이다.

두번째, NaN 데이터 값에 평균값을 넣는 것이다.

세번째, NaN 데이터 값에 중위값을 넣는 것이다.

만약 비어있는 값이 blood 처럼 str 형식인 경우는 어떻게 해야할까?

많이 나온 데이터 값을 넣는 것을 생각해볼 수 있다 (최빈값 넣기)

또, 날씨 데이터 중에 컬럼이 강수량이 있는 경우를 생각해보자.

강수량의 데이터가 몇개가 빠져 있다면? 이 때는 0을 넣는 방법도 생각해볼 수 있다.

이런 식으로 결측값을 지우거나, 다른 것으로 채우는 방안을 데이터를 파악해서 결정해야 한다.

현재 결측치가 다음과 같이 있다고 해보자.

이제, 결측치 여부를 알아보는 메소드를 알아보자.

df.isna()

또, 비슷한 의미인 isnull() 메소드도 있다.

df.isnull()

이번엔 반대의 의미인 notnull()을 살펴보자.

df.notnull()

이제 이것들을 이용해 불린 인덱싱하면 우리가 원하는 결과를 얻을 수 있다.

df[df['blood'].isna()]

그리고 이번엔 테스트를 위해 height의 일부값들을 NaN으로 바꾸기 위해 다음과 같은 코드를 적용할 것이다.

import numpy as np

df.loc[8, 'height'] = np.nan
df.loc[19, 'height'] = np.nan

이것을 기준으로 height이 NaN인 행을 살펴보면 다음과 같다.

df[df['height'].isna()]

이 상황에서 원본 데이터프레임인 df의 오염을 방지하기 위해 데이터프레임을 복사해서 사용하자.

df_copy = df.copy()

이제 df_copy에서 결측값을 채우는 처리를 해보자. 먼저 결측값을 채워주는 함수는 다음과 같다.

df_copy['height'].fillna(0, inplace=True)

지금은 결측값을 0으로 채워주라는 의미이고, inplace=True 셋팅은 실제로 메모리까지 적용되는 설정이다.

여기서는 실제로 0으로 채우고 싶지는 않으므로 다음과 같이 확인만 할 것이다.

df_copy['height'].fillna(0)

이 상태에서, 평균값을 한번 구해보자. 평균값 구하는 메소드는 다음과 같다.

height = df_copy['height'].mean()

이 평균값을 실제로 결측치에 적용할 것이다.

df_copy['height'] = df_copy['height'].fillna(df_copy['height'].mean())

실제로 평균값인 178.527778 값이 결측치 대신 적용되었다!

이번에는 다시 다음과 같이 초기화 하고 중위값을 넣어볼 수 있다.

df_copy = df.copy()

height = df_copy['height'].median()

df['height'] = df['height'].fillna(height)

중위값인 180.5가 결측치 대신 잘 입력되었다!

이번에는 NaN에 해당하는 데이터를 지워버리는 방법을 알아보자.

df_copy = df_copy.dropna()

이것은 결측값이 있는 행 또는 열을 제거하는데, 결측값이 한개라도 있는 경우 삭제한다.

axis 값을 설정할 수 있는데, 기본값은 0으로써 행 삭제이고, 1인 경우 열을 삭제한다.

행, 열 추가 및 삭제

다음과 같은 딕셔너리 구조를 보자.

dic = {
    'name': '김사과',
    'company': '애플',
    'gender': '여자',
    'birthday': '2000-01-01',
    'height': 160.0,
    'blood': 'A',
    'brand': 1234567
}

이 딕셔너리 값을 통해 새로운 행을 추가해주고 싶다. 이럴 땐 어떻게 해야할까?

다음과 같이 해보자. 맨 끝 행에 자료를 추가하는 방법이다.

df_copy.loc[len(df_copy)] = dic

그리고, 데이터 프레임에서 새로운 열을 추가할 때 값을 하나로 통일시켜주고 싶다면,

다음과 같이 실행해주면 된다.

df_copy['nation'] = '대한민국'

만약 여기서 name이 김사과인 행의 nation 컬럼을 미국으로 바꾸고 싶다면 다음과 같이 또 해주면 된다.

df_copy.loc[df_copy['name'] === '김사과', 'nation'] = '미국'

이번엔 행을 제거하는 방법을 알아보자.

df_copy.drop(20, axis=0)

다음과 같이 매개변수로 제거할 행또는 열의 인덱스와, axis 값을 통해 제거할 것이 행인지 열인지 명시해주면 된다.

앞서와 똑같이 0은 행이고 1은 열이다.

통계 함수

통계 함수는 다음과 같다.

print(df_copy['height'].sum()) # 합계
print(df_copy['height'].count()) # 개수, NaN은 포함하지 않음
print(df_copy['height'].mean()) # 평균
print(df_copy['height'].median()) # 중앙값
print(df_copy['height'].max()) # 최대값
print(df_copy['height'].min()) # 최소값
print(df_copy['height'].var()) # 분산
print(df_copy['height'].std()) # 표준편차

여기서 평균과 중앙값은 무슨 차이일지 정리해보자. 동시에 분산과 표준편차도 알아보자.

평균과 중앙값

평균(Mean)은 데이터의 모든 값을 더한 뒤 데이터 개수로 나눈 값으로 전체 데이터의 중심적인

경향을 나타내는 대표적인 통계값이다. 반면, 중앙값은 데이터를 크기순으로 정렬했을 때

가장 가운데 위치한 값을 의미하며, 이상치의 영향을 적게 받는다.

평균은 전체 데이터를 모두 반영하는 대표 값이고

중앙값은 데이터의 정중앙 위치를 나타내는 대표값이라고 할 수 있다.

분산 & 표준편차

분산(Variance)은 데이터가 평균으로부터 얼마나 퍼져있는지 수치로 나타낸 값으로

각 데이터와 평균의 차이를 제곱한 뒤 평균을 내어 계산한다.

값이 클수록 데이터의 흩어짐이 크다는 의미이며, 값이 작을수록 평균에 모여있다는 의미이다.

하지만 분산은 차이를 제곱해서 계산하므로, 단위가 원래 데이터와 달라진다는 단점이 있다.

이를 해결하기 위해 사용하는 것이 표준편차(Standard Deviation)이며

표준편차는 분산에 제곱근을 취한 값이다. 따라서 원래 데이터와 같은 단위를 사용해

해석이 더 직관적이다.

그리고 이 통계 함수를 사용할 때는 다음과 같이 groupby() 함수를 맺어 사용할 수 있다.

df_copy.groupby('blood').count()

또, 데이터 분석할 때나 머신러닝/딥러닝 전처리에 많이 사용되는 다음 함수를 알아보자.

df_copy['blood'].value_counts()

다음 함수는 열의 각 값에 대한 데이터를 반환하고, 기본은 NaN을 생략한 채로 반환한다.

데이터 프레임 다루기

다음과 같은 2개의 데이터가 있다고 해보자.

df1 = pd.read_csv("./광고모델_브랜드평판.csv")
df2 = pd.read_csv("./광고모델_상세정보.csv")

광고모델_브랜드평판

광고모델_상세정보

데이터 오염을 방지하기 위해 2개의 데이터프레임 모두 복사해주자.

df1_copy = df1.copy()
df2_copy = df2.copy()

여기서 두 개의 데이터프레임을 연결하는 함수를 알아보자.

concat은 두 개의 데이터프레임을 연결해주는 역할을 한다. 행으로 다음과 같이 연결한다.

pd.concat([df1, df1_copy])

처음 0번부터 19번까지가 원래 데이터인데 밑에 0번부터 19번까지가 한번 더 합쳐졌다.

그러나 여기서 0부터 19번까지 인덱스가 2번 출력되어 보기가 좋지 않다.

여기서 인덱스를 리셋하는 방법이 있다.

df1_concat = pd.concat([df1, df1_copy])
df1_concat.reset_index(drop=True)

이렇게 되면 다음과 같이 인덱스가 리셋된다.

인덱스가 리셋되어 20부터 다시 시작하는 걸 볼 수 있다.

그리고 여기서 drop = True 셋팅은 새로운 인덱스 컬럼이 생기는 것을 방지할 수 있다.

다음처럼 기존 인덱스가 drop이 되는 형태인 것이다. 다음과 같이 생기는 걸 방지하는 것이다.

이제 옆으로 붙이는 (컬럼 단위로 붙이는) 것을 해보자.

pd.concat([df1_copy, df2_copy], axis=1)

axis 값을 1로 주어 붙이는 기준을 컬럼으로 설정해주면 된다.

이렇게 컬럼으로 합쳐지는 것이다. 그러나 결합할 때 합치는 기준이 인덱스 기준이다. (즉, 중복되는 컬럼이 나올 수 있다.)

즉, 2개의 데이터프레임이 합쳐질 수 있었던 건 두 데이터프레임의 인덱스가 완전히 일치했기 때문이다.

그럼 일부 행들을 drop 시켜서 인덱스가 완전히 일치하지 않는다면 어떻게 될까? 다음과 같이 살펴보자.

df2_copy = df2_copy.drop([1, 3, 5, 7, 9])

보시다시피 1, 3, 5, 7, 9번 행이 데이터프레임에서 지워졌다.

이 상태에서 다시 concat 함수를 통해 합쳐보자.

pd.concat([df1_copy, df2_copy], axis=1)

일단 인덱스 번호 일부가 지워지긴 했지만, 인덱스 번호가 흐트러진게 아니므로, 같은 번호끼리는 잘 합쳐질 것이다.

(비어있는 인덱스는 보기와 같이 NaN 처리된다)

이제 2번째 데이터프레임을 인덱스 재정렬하고 한번 확인해보자.

df2_copy = df2_copy.reset_index(drop=True)

0번부터 14번까지로 재정렬 되었으므로 인덱스가 흐트러졌다고 할 수 있다.

이제 첫번째 데이터프레임 인덱스와 두번째 데이터프레임 인덱스가 다른 상황이다.

여기에다가 또 데이터를 하나 더 추가해보자.

dic = {
	'이름': '김사과',
    '연봉': 99000000,
    '주소': '서울 강남구'
}

df2_copy.loc[len(df2_copy)] = dic

이제 이 상황에서 concat을 통해 합쳐보자.

pd.concat([df1_copy, df2_copy], axis=1)

인덱스를 기준으로 합쳐지므로, 같은 인덱스의 이름이 서로 다르게 합쳐지는 오류가 발생한다.

즉, 인덱스 번호가 다르면 열로 붙일 수 없는 문제가 발생한다.

이제 그 문제점을 해결하는 merge 함수에 대해 알아보자.

pd.merge(df1_copy, df2_copy, on="이름", how="left")

이것은 특정 고유한 키(key) 값을 기준으로 합치는데 내가 원하는 열을 보고 서로 열이 같은 것 끼리 합칠 수 있다는 것이다.

그래서 on에 유니크 값(키값)에 해당하는 컬럼을 설정해주면 된다. 여기서는 이름 컬럼으로 설정했다.

how에는 병합의 기준을 넣어야 하는데, left / right / inner / cross 4가지 값이 있다.

기준값을 보면 알겠지만 RDB의 JOIN 연산과 매우 유사하다.

how = "left"

먼저, LEFT의 의미는 왼쪽 데이터프레임을 기준으로 먼저 합쳐달라는 의미이다. 여기서 왼쪽 데이터프레임은 df1_copy인데

df1_copy의 데이터는 다 뿌리고, 그것에 맞춰서 df2_copy를 합쳐달라는 의미이다.

다음과 같이 가정해보자.

왼쪽 데이터의 행의 갯수가 20개이고, 오른쪽 데이터 행의 갯수가 14개라고 가정한다.

그러면 20개를 그대로 보여주고, 오른쪽 데이터 프레임을 왼쪽 프레임에 맞춰서 보여주는 형태이다.

오른쪽 프레임에 맞지 않는 컬럼의 값에 NaN이 나온 것도 Left 연산이기 때문이다.

how = "right"

이것을 오른쪽 기준으로 합쳐달라는 의미이다. 방금 가정한 것에서 예시를 적용하자면

여기서 오른쪽을 기준으로 합쳐져야 하므로, 왼쪽 데이터프레임 중 오른쪽 데이터프레임과 겹치는 부분만

출력될 것이고, 최종적으로 14개의 행만 보여질 것이다.

왼쪽 데이터프레임 중에 오른쪽 데이터프레임에 포함되어 있지 않는 데이터는 당연히 제외될 것이다.

(즉, 왼쪽 데이터프레임이 오른쪽 데이터프레임 기준으로 맵핑되는 것만 포함될 것이라는 얘기이다.)

다만 오른쪽 데이터프레임 기준으로 출력되는 것이므로 포함되지 않는 데이터는 NaN 포함된 채로 출력될 것이다.

단 여기서 세부적인 사항에 따라 inner 연산이냐 cross 연산이냐로 나뉘는데

inner 연산은 서로 교집합인 경우에만 출력되는 경우이다.

cross 연산은 왼쪽 데이터프레임의 한 사람당, 오른쪽 데이터프레임의 모든 데이터들을 다 연결해보는 것이다.

집합 연산의 카디널 프로덕트(곱 연산)과 비슷하다.

날짜 타입

이제 날짜 부분을 처리하기 위해 다시 데이터프레임의 info를 확인해보자.

df_copy.info()

현재 생년월일에 해당하는 birthday 컬럼의 데이터 값의 데이터 타입은 object(str)이다.

이것을 날짜 타입으로 한번 바꾸어보자. 다음과 같이 하자.

df_copy['birthday'] = pd.to_datetime(df_copy['birthday'])

그러면 날짜 타입으로 변경됨을 확인할 수 있다.

그러면 다음과 같은 속성 접근으로 날짜만 뽑을 수 있다.

df_copy['birthday'].dt.year # 년도
df_copy['birthday'].dt.month # 월
df_copy['birthday'].dt.day # 일
df_copy['birthday'].dt.hour # 시간
df_copy['birthday'].dt.minute # 분
df_copy['birthday'].dt.second # 초
df_copy['birthday'].dt.dayofweek # 요일
df_copy['birthday'].dt.isocalendar().week # 1년중에 몇번째 주인지

자주 사용하는 함수

apply

데이터프레임이나 시리즈의 데이터를 사용자 정의 함수 혹은 내장 함수에 적용하여

새로운 값을 계산하거나 변환할 때 사용한다. 데이터를 행 또는 열 단위로 처리하는 강력한 도구이다.

다음과 같은 데이터가 있을 때 성별을 남자는 1, 여자는 0으로 변환하고 싶다고 해보자.

(머신러닝/딥러닝 때 필요한 수치화)

그럼 다음과 같이 할 수 있을 것이다.

df_copy.loc[df_copy['성별'] == '남자', '성별'] = 1
df_copy.loc[df_copy['성별'] == '여자', '성별'] = 0

이것을 함수를 통해서 바꾸는 방법을 생각해보자.

def male_or_female(x):
  if x == '남':
    return 1
  elif x == '여':
    return 0
  else:
    return None

그러면 다음과 같이 적용시킬 수 있다.

df_copy['성별'].apply(male_or_female)