refactor code

README.md

@@ -1,22 +1,67 @@
 ---
 title: First Chatbot
-emoji: 🐠
+emoji: 🤖
 colorFrom: indigo
 colorTo: pink
 sdk: streamlit
 sdk_version: 1.44.0
 app_file: app.py
 pinned: false
-short_description: tutorial
+short_description: A simple chatbot using Streamlit and Hugging Face.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🤖 나만의 개인 챗봇
 
-# How to do it
+Hugging Face 모델과 Streamlit을 사용하여 만든 간단한 대화형 챗봇입니다. 사이드바에서 AI의 성격, 시작 메시지, 아바타 등을 직접 설정하고 AI와 대화를 나눌 수 있습니다.
 
+## ✨ 주요 기능
 
+- **💬 실시간 채팅 인터페이스**: 사용자와 AI가 메시지를 주고받는 깔끔한 UI.
+- **🔧 손쉬운 설정**: 사이드바에서 시스템 메시지, 시작 메시지, 최대 응답 길이를 쉽게 변경할 수 있습니다.
+- **🎨 커스텀 아바타**: 사용자와 AI의 아바타를 원하는 이모티콘으로 선택할 수 있습니다.
+- **🧠 유연한 모델 사용**: Hugging Face에 있는 다양한 언어 모델(`MODEL_ID` 변경)을 활용할 수 있습니다.
+- **🔄 대화 초기화**: 버튼 클릭 한 번으로 대화 기록을 초기화하고 새 대화를 시작할 수 있습니다.
 
+## 🛠️ 시작하기
 
-# Reference
+### 1. 환경 설정
 
-- https://medium.com/@james.irving.phd/creating-your-personal-chatbot-using-hugging-face-spaces-and-streamlit-596a54b9e3ed
+이 프로젝트는 `uv`와 같은 가상 환경 도구를 사용하는 것을 권장합니다.
+
+먼저, 필요한 라이브러리를 설치하세요.
+
+```bash
+uv pip install -r requirements.txt
+```
+
+### 2. Hugging Face 토큰 설정
+
+프로젝트 루트 디렉터리에 `.env` 파일을 생성하고, 여러분의 Hugging Face API 토큰을 추가하세요. 토큰은 [Hugging Face 설정](https://huggingface.co/settings/tokens)에서 발급받을 수 있습니다.
+
+```
+HF_TOKEN="ここにHugging Faceのトークンを貼り付けてください"
+```
+
+### 3. 애플리케이션 실행
+
+터미널에서 아래 명령어를 실행하여 Streamlit 앱을 시작하세요.
+
+```bash
+uv run streamlit run app.py
+```
+
+앱이 실행되면 웹 브라우저에서 로컬 주소(예: `http://localhost:8501`)가 열립니다.
+
+## 📂 코드 구조
+
+`app.py` 파일은 가독성과 유지보수성을 높이기 위해 기능별로 모듈화되었습니다.
+
+- **상수 정의**: `MODEL_ID`, `PROMPT_TEMPLATE` 등 주요 설정값을 파일 상단에서 관리합니다.
+- **LLM 및 체인 설정 (`get_llm`, `get_chain`)**: Hugging Face 모델을 로드하고, LangChain으로 프롬프트와 모델을 연결하는 체인을 생성합니다.
+- **UI 렌더링 (`initialize_session_state`, `setup_sidebar`, `display_chat_history`)**: Streamlit의 세션 상태를 초기화하고, 사이드바와 채팅 기록 UI를 구성합니다.
+- **메인 로직 (`generate_response`, `main`)**: 사용자 입력을 받아 AI의 응답을 생성하고, 전체 애플리케이션의 흐름을 제어합니다.
+
+## 📚 참고 자료
+
+- [Creating Your Personal Chatbot Using Hugging Face Spaces and Streamlit](https://medium.com/@james.irving.phd/creating-your-personal-chatbot-using-hugging-face-spaces-and-streamlit-596a54b9e3ed)
+- [Hugging Face Spaces Configuration Reference](https.huggingface.co/docs/hub/spaces-config-reference)

app.py

@@ -1,194 +1,198 @@
 import os
-from dotenv import load_dotenv
-from langchain_huggingface import HuggingFaceEndpoint
+
 import streamlit as st
-from langchain_core.prompts import PromptTemplate
+from dotenv import load_dotenv
 from langchain_core.output_parsers import StrOutputParser
+from langchain_core.prompts import PromptTemplate
+from langchain_huggingface import HuggingFaceEndpoint
+
+# --- 상수 정의 ---
+# 사용할 Hugging Face 모델 ID
+MODEL_ID = "google/gemma-3n-e4b"
+# 프롬프트 템플릿
+PROMPT_TEMPLATE = """
+[INST] {system_message}
+현재 대화:
+{chat_history}
 
-# 사용할 Hugging Face 모델 ID를 정의합니다.
-model_id = "mistralai/Mistral-7B-Instruct-v0.3"
+사용자: {user_text}
+[/INST]
+AI:
+"""
 
-# .env 파일 로드
-load_dotenv()
 
+# --- LLM 및 체인 설정 함수 ---
 
-def get_llm_hf_inference(model_id=model_id, max_new_tokens=128, temperature=0.1):
+def get_llm(max_new_tokens=128, temperature=0.1):
     """
-    Hugging Face 추론을 위한 언어 모델을 반환합니다.
+    Hugging Face 추론을 위한 언어 모델(LLM)을 생성하고 반환합니다.
 
-    매개변수:
-    - model_id (str): Hugging Face 모델 저장소의 ID입니다.
-    - max_new_tokens (int): 생성할 수 있는 최대 새 토큰 수입니다.
-    - temperature (float): 모델에서 샘플링할 때의 온도 값입니다.
+    Args:
+        max_new_tokens (int): 생성할 최대 토큰 수입니다.
+        temperature (float): 샘플링 온도로, 낮을수록 결정적인 답변을 생성합니다.
 
-    반환값:
-    - llm (HuggingFaceEndpoint): Hugging Face 추론을 위한 언어 모델입니다.
+    Returns:
+        HuggingFaceEndpoint: 설정된 언어 모델 객체입니다.
     """
-    # HuggingFaceEndpoint를 사용하여 언어 모델을 초기화합니다.
-    llm = HuggingFaceEndpoint(
-        repo_id=model_id,  # 사용할 모델 ID
-        max_new_tokens=max_new_tokens,  # 생성할 최대 토큰 수
-        temperature=temperature,  # 샘플링 시 온도 설정
-        token=os.getenv("HF_TOKEN"),  # Hugging Face API 토큰 (환경 변수에서 가져옴)
+    return HuggingFaceEndpoint(
+        repo_id=MODEL_ID,
+        max_new_tokens=max_new_tokens,
+        temperature=temperature,
+        token=os.getenv("HF_TOKEN"),
     )
-    return llm  # 초기화된 언어 모델을 반환합니다.
 
 
-# Streamlit 앱 설정을 구성합니다.
-st.set_page_config(page_title="HuggingFace ChatBot", page_icon="🤗")
-st.title("개인 HuggingFace 챗봇")
-st.markdown(
-    f"*이것은 HuggingFace transformers 라이브러리를 사용하여 텍스트 입력에 대한 응답을 생성하는 간단한 챗봇입니다. {model_id} 모델을 사용합니다.*"
-)
+def get_chain(llm):
+    """
+    주어진 언어 모델(LLM)을 사용하여 대화 체인을 생성합니다.
 
-# 아바타에 대한 세션 상태를 초기화합니다.
-if "avatars" not in st.session_state:
-    st.session_state.avatars = {"user": None, "assistant": None}
+    Args:
+        llm (HuggingFaceEndpoint): 사용할 언어 모델입니다.
 
-# 사용자 텍스트 입력에 대한 세션 상태를 초기화합니다.
-if "user_text" not in st.session_state:
-    st.session_state.user_text = None
+    Returns:
+        RunnableSequence: LangChain 표현 언어(LCEL)로 구성된 실행 가능한 체인입니다.
+    """
+    prompt = PromptTemplate.from_template(PROMPT_TEMPLATE)
+    return prompt | llm | StrOutputParser()
 
-# 모델 매개변수에 대한 세션 상태를 초기화합니다.
-if "max_response_length" not in st.session_state:
-    st.session_state.max_response_length = 256
 
-# 시스템 메시지에 대한 세션 상태를 초기화합니다.
-if "system_message" not in st.session_state:
-    st.session_state.system_message = "인간 사용자와 대화하는 친절한 AI"
+def generate_response(chain, system_message, chat_history, user_text):
+    """
+    LLM 체인을 호출하여 사용자의 입력에 대한 응답을 생성합니다.
 
-# 시작 메시지에 대한 세션 상태를 초기화합니다.
-if "starter_message" not in st.session_state:
-    st.session_state.starter_message = "안녕하세요! 오늘 무엇을 도와드릴까요?"
+    Args:
+        chain (RunnableSequence): 응답 생성을 위한 LLM 체인입니다.
+        system_message (str): AI의 역할을 정의하는 시스템 메시지입니다.
+        chat_history (list[dict]): 이전 대화 기록입니다.
+        user_text (str): 사용자의 현재 입력 메시지입니다.
 
+    Returns:
+        str: 생성된 AI의 응답 메시지입니다.
+    """
+    history_str = "\n".join(
+        [f"{msg['role']}: {msg['content']}" for msg in chat_history]
+    )
+    response = chain.invoke({
+        "system_message": system_message,
+        "chat_history": history_str,
+        "user_text": user_text,
+    })
+    return response.split("AI:")[-1].strip()
 
-# 설정을 위한 사이드바를 구성합니다.
-with st.sidebar:
-    st.header("시스템 설정")
 
-    # AI 설정
-    st.session_state.system_message = st.text_area(
-        "시스템 메시지", value="당신은 인간 사용자와 대화하는 친절한 AI입니다."
-    )
-    st.session_state.starter_message = st.text_area(
-        "첫 번째 AI 메시지", value="안녕하세요! 오늘 무엇을 도와드릴까요?"
-    )
+# --- UI 렌더링 함수 ---
 
-    # 모델 설정
-    st.session_state.max_response_length = st.number_input("최대 응답 길이", value=128)
+def initialize_session_state():
+    """
+    Streamlit 세션 상태를 초기화합니다.
+    세션이 처음 시작될 때 기본값을 설정합니다.
+    """
+    defaults = {
+        "avatars": {"user": "👤", "assistant": "🤗"},
+        "chat_history": [],
+        "max_response_length": 256,
+        "system_message": "당신은 인간 사용자와 대화하는 친절한 AI입니다.",
+        "starter_message": "안녕하세요! 오늘 무엇을 도와드릴까요?",
+    }
+    for key, value in defaults.items():
+        if key not in st.session_state:
+            st.session_state[key] = value
+
+    if not st.session_state.chat_history:
+        st.session_state.chat_history = [
+            {"role": "assistant", "content": st.session_state.starter_message}
+        ]
+
+
+def setup_sidebar():
+    """
+    사이드바 UI 구성 요소를 설정하고 렌더링합니다.
+    사용자는 이 사이드바에서 시스템 설정, AI 메시지, 모델 응답 길이 등을 조정할 수 있습니다.
+    """
+    with st.sidebar:
+        st.header("시스템 설정")
 
-    # 아바타 선택
-    st.markdown("*아바타 선택:*")
-    col1, col2 = st.columns(2)
-    with col1:
-        st.session_state.avatars["assistant"] = st.selectbox(
-            "AI 아바타", options=["🤗", "💬", "🤖"], index=0
+        st.session_state.system_message = st.text_area(
+            "시스템 메시지", value=st.session_state.system_message
         )
-    with col2:
-        st.session_state.avatars["user"] = st.selectbox(
-            "사용자 아바타", options=["👤", "👱‍♂️", "👨🏾", "👩", "👧🏾"], index=0
+        st.session_state.starter_message = st.text_area(
+            "첫 번째 AI 메시지", value=st.session_state.starter_message
         )
-    # 채팅 기록 초기화 버튼
-    reset_history = st.button("채팅 기록 초기화")
-
-# 채팅 기록을 초기화하거나, 초기화 버튼이 눌렸을 경우 초기화합니다.
-if "chat_history" not in st.session_state or reset_history:
-    st.session_state.chat_history = [
-        {"role": "assistant", "content": st.session_state.starter_message}
-    ]
-
-
-def get_response(
-    system_message,
-    chat_history,
-    user_text,
-    eos_token_id=["User"],
-    max_new_tokens=256,
-    get_llm_hf_kws={},
-):
+        st.session_state.max_response_length = st.number_input(
+            "최대 응답 길이", value=st.session_state.max_response_length
+        )
+
+        st.markdown("*아바타 선택:*")
+        col1, col2 = st.columns(2)
+        with col1:
+            st.session_state.avatars["assistant"] = st.selectbox(
+                "AI 아바타", options=["🤗", "💬", "🤖"], index=0
+            )
+        with col2:
+            st.session_state.avatars["user"] = st.selectbox(
+                "사용자 아바타", options=["👤", "👱‍♂️", "👨🏾", "👩", "👧🏾"], index=0
+            )
+
+        if st.button("채팅 기록 초기화"):
+            st.session_state.chat_history = [
+                {"role": "assistant", "content": st.session_state.starter_message}
+            ]
+            st.rerun()
+
+
+def display_chat_history():
     """
-    챗봇 모델로부터 응답을 생성합니다.
-
-    매개변수:
-        system_message (str): 대화의 시스템 메시지입니다.
-        chat_history (list): 이전 채팅 메시지 목록입니다.
-        user_text (str): 사용자의 입력 텍스트입니다.
-        model_id (str, optional): 사용할 Hugging Face 모델의 ID입니다.
-        eos_token_id (list, optional): 문장 종료 토큰 ID 목록입니다.
-        max_new_tokens (int, optional): 생성할 수 있는 최대 새 토큰 수입니다.
-        get_llm_hf_kws (dict, optional): get_llm_hf 함수에 전달할 추가 키워드 인자입니다.
-
-    반환값:
-        tuple: 생성된 응답과 업데이트된 채팅 기록을 포함하는 튜플입니다.
+    세션에 저장된 채팅 기록을 순회하며 화면에 메시지를 표시합니다.
     """
-    # 모델을 설정합니다.
-    hf = get_llm_hf_inference(max_new_tokens=max_new_tokens, temperature=0.1)
-
-    # 프롬프트 템플릿을 생성합니다.
-    prompt = PromptTemplate.from_template(
-        (
-            "[INST] {system_message}"
-            "\n현재 대화:\n{chat_history}\n\n"
-            "\n사용자: {user_text}.\n [/INST]"
-            "\nAI:"
-        )
-    )
-    # 프롬프트를 연결하여 채팅 체인을 만듭니다.
-    chat = prompt | hf.bind(skip_prompt=True) | StrOutputParser(output_key="content")
-
-    # 응답을 생성합니다.
-    response = chat.invoke(
-        input=dict(
-            system_message=system_message,
-            user_text=user_text,
-            chat_history=chat_history,
-        )
-    )
-    # "AI:" 접두사를 제거합니다.
-    response = response.split("AI:")[-1]
+    for message in st.session_state.chat_history:
+        if message["role"] == "system":
+            continue
+        avatar = st.session_state.avatars.get(message["role"])
+        with st.chat_message(message["role"], avatar=avatar):
+            st.markdown(message["content"])
 
-    # 채팅 기록을 업데이트합니다.
-    chat_history.append({"role": "user", "content": user_text})
-    chat_history.append({"role": "assistant", "content": response})
-    return response, chat_history
 
+# --- 메인 애플리케이션 실행 ---
 
-# 채팅 인터페이스를 설정합니다.
-chat_interface = st.container(border=True)
-with chat_interface:
-    output_container = st.container()
-    st.session_state.user_text = st.chat_input(
-        placeholder="여기에 텍스트를 입력하세요."
+def main():
+    """
+    메인 Streamlit 애플리케이션을 실행합니다.
+    """
+    load_dotenv()
+
+    st.set_page_config(page_title="HuggingFace ChatBot", page_icon="🤗")
+    st.title("개인 HuggingFace 챗봇")
+    st.markdown(
+        f"*이것은 HuggingFace transformers 라이브러리를 사용하여 텍스트 입력에 대한 응답을 생성하는 간단한 챗봇입니다. {MODEL_ID} 모델을 사용합니다.*"
     )
 
-# 채팅 메시지를 표시합니다.
-with output_container:
-    # 채팅 기록에 있는 각 메시지에 대해 반복합니다.
-    for message in st.session_state.chat_history:
-        # 시스템 메시지는 건너뜁니다.
-        if message["role"] == "system":
-            continue
+    initialize_session_state()
+    setup_sidebar()
 
-        # 올바른 아바타를 사용하여 채팅 메시지를 표시합니다.
-        with st.chat_message(
-            message["role"], avatar=st.session_state["avatars"][message["role"]]
-        ):
-            st.markdown(message["content"])
+    # 채팅 기록 표시
+    display_chat_history()
 
-    # 사용자가 새 텍스트를 입력했을 때:
-    if st.session_state.user_text:
-        # 사용자의 새 메시지를 즉시 표시합니다.
+    # 사용자 입력 처리
+    if user_input := st.chat_input("여기에 텍스트를 입력하세요."):
+        # 사용자 메시지를 기록에 추가하고 화면에 표시
+        st.session_state.chat_history.append({"role": "user", "content": user_input})
         with st.chat_message("user", avatar=st.session_state.avatars["user"]):
-            st.markdown(st.session_state.user_text)
+            st.markdown(user_input)
 
-        # 응답을 기다리는 동안 스피너 상태 표시줄을 표시합니다.
+        # AI 응답 생성 및 표시
         with st.chat_message("assistant", avatar=st.session_state.avatars["assistant"]):
             with st.spinner("생각 중..."):
-                # 시스템 프롬프트, 사용자 텍스트 및 기록을 사용하여 추론 API를 호출합니다.
-                response, st.session_state.chat_history = get_response(
-                    system_message=st.session_state.system_message,
-                    user_text=st.session_state.user_text,
-                    chat_history=st.session_state.chat_history,
-                    max_new_tokens=st.session_state.max_response_length,
+                llm = get_llm(max_new_tokens=st.session_state.max_response_length)
+                chain = get_chain(llm)
+                response = generate_response(
+                    chain,
+                    st.session_state.system_message,
+                    st.session_state.chat_history,
+                    user_input,
                 )
+                st.session_state.chat_history.append({"role": "assistant", "content": response})
                 st.markdown(response)
+
+
+if __name__ == "__main__":
+    main()