Streamlit 기초 정리: 설치부터 챗봇 UI 구현까지

목차

1. Streamlit이란?
2. Streamlit 설치와 실행 방법
3. 프론트엔드와 Streamlit의 역할
4. Streamlit 기본 구조
5. 텍스트와 콘텐츠 출력 함수
6. 입력 위젯 정리
7. 미디어 요소 정리
8. Streamlit으로 OpenAI 챗봇 구현하기
9. Streamlit을 사용하는 이유
10. 마무리 정리

 

1. Streamlit이란?

Streamlit은 파이썬만으로 웹 애플리케이션을 빠르게 만들 수 있도록 도와주는 오픈소스 프레임워크이다.
특히 데이터 분석 결과를 시각화하거나, 머신러닝 모델의 예측 결과를 보여주거나, 챗봇처럼 사용자와 상호작용하는 앱을 구현할 때 많이 사용된다.

 

복잡한 프론트엔드 기술인 HTML, CSS, JavaScript를 직접 다루지 않아도, 파이썬 코드만으로 웹 화면을 구성할 수 있다는 점이 Streamlit의 가장 큰 장점이다. 

또한, 사용자 입력에 따라 화면이 즉시 갱신되므로, 실시간 상호작용이 필요한 앱을 비교적 쉽게 구현할 수 있다.

 

2. Streamlit 설치와 실행 방법

먼저 터미널에서 Streamlit을 설치한다.

pip install streamlit

 

설치가 끝났다면 예제 앱을 실행해볼 수 있다.

streamlit hello

 

직접 작성한 앱 파일을 실행할 때는 다음 명령어를 사용한다.

streamlit run app.py

 

여기서 app.py는 Streamlit 코드가 들어 있는 파이썬 파일 이름이다.

 

3. 프론트엔드와 Streamlit의 역할

웹 애플리케이션은 일반적으로 사용자에게 화면을 보여주는 프론트엔드와, 요청을 처리하는 백엔드가 있다.

 

프론트엔드는 사용자가 브라우저를 통해 직접 보게 되는 화면과 UI를 담당한다.
사용자의 입력을 받고, 서버로 요청을 전달하며, 응답받은 결과를 다시 화면에 보여주는 역할을 한다.

 

Streamlit은 파이썬 기반 프레임워크이지만, 이런 프론트엔드 역할을 매우 간단하게 구현할 수 있게 해준다.
즉, 버튼, 입력창, 텍스트, 이미지 같은 UI를 파이썬 코드만으로 만들고, 사용자의 입력에 따라 결과를 바로 화면에 반영할 수 있다. 

이 때문에 Streamlit은 “파이썬으로 빠르게 만드는 프론트엔드형 웹앱 도구”라고 이해하면 쉽다.

 

 

4. Streamlit 기본 구조

가장 간단한 Streamlit 앱은 다음과 같이 작성할 수 있다.

이 코드는 페이지 제목과 아이콘을 설정하고, 메인 화면과 사이드바에 텍스트를 출력하는 가장 기본적인 예제이다

import streamlit as st

st.set_page_config(
    page_title="Hello",
    page_icon="👋"
)

st.write("# Welcome to Streamlit!")
st.sidebar.success("데모 선택")

st.markdown(
    """
    Streamlit은 머신러닝 및 데이터 과학 프로젝트를 위해 만들어진 오픈소스 앱 프레임워크입니다.
    """
)

 

 

5. 텍스트와 콘텐츠 출력 함수

Streamlit은 다양한 형태의 콘텐츠를 쉽게 화면에 표시할 수 있도록 여러 함수를 제공한다.

 

st.write()

가장 범용적으로 사용할 수 있는 출력 함수이다.
텍스트뿐 아니라 데이터프레임, 그래프 등도 출력할 수 있다.

st.write("Hello **world**!")

 

st.markdown()

마크다운 형식의 텍스트를 출력할 때 사용한다.

st.markdown("**굵은 글씨**를 표시할 수 있습니다.")

 

st.title(), st.header(), st.subheader()

제목, 헤더, 서브헤더를 출력할 때 사용한다.

st.title("앱 제목")
st.header("헤더입니다")
st.subheader("서브헤더입니다")

 

st.caption()

작은 설명 문구를 출력할 때 사용한다.

st.caption("간단한 보조 설명")

 

st.code()

코드 블록을 출력한다.

st.code("a = 1234")

 

st.echo()

코드를 화면에 보여주면서 실행할 때 사용한다. 튜토리얼용으로 유용하다.

with st.echo():
    st.write("이 코드는 출력됩니다.")

 

st.latex()

수학 수식을 출력한다.

st.latex(r"\int a x^2 \, dx")

 

st.text()

고정 폭 글꼴로 단순 텍스트를 표시한다.

st.text("Hello world")

 

st.divider()

구분선을 그린다.

st.divider()

 

st.write_stream()

스트리밍 출력에 사용되며, 타자기처럼 한 글자씩 출력되는 효과를 낼 수 있다.
LLM 응답을 실시간으로 보여줄 때 유용하다.

st.write_stream(my_generator)

 

 

이외의 다양한 함수들은 공식 사이트 document를 참고하면 좋다.

 

streamlit 도큐먼트
https://docs.streamlit.io/

Streamlit Docs

 

 

6. 입력 위젯 정리

사용자의 입력을 받기 위한 주요 위젯은 다음과 같다.

 

st.button()

버튼을 만들고, 클릭 여부를 반환한다.

clicked = st.button("Click me")

 

st.download_button()

파일 다운로드 버튼을 만든다.

st.download_button("파일 다운로드", file)

 

st.checkbox()

체크박스를 표시하고 선택 여부를 반환한다.

selected = st.checkbox("동의합니다")

 

st.radio()

라디오 버튼을 통해 여러 선택지 중 하나를 고르게 한다.

choice = st.radio("선택하세요", ["고양이", "강아지"])

 

st.slider()

숫자 범위를 슬라이더로 선택하게 한다.

number = st.slider("숫자를 선택하세요", 0, 100)

 

st.text_input()

한 줄짜리 텍스트 입력창을 만든다.

name = st.text_input("이름")

 

 

7. 미디어 요소 정리

이미지, 오디오, 비디오도 쉽게 넣을 수 있다.

 

st.image()

st.image("https://example.com/myimage.jpg")

 

st.audio()

st.audio("https://example.com/myaudio.mp3", format="audio/mp3")

 

st.video()

st.video("https://example.com/myvideo.mp4", format="video/mp4")

 

 

8. Streamlit으로 OpenAI 챗봇 구현하기

앞에서 Streamlit의 기본 구조와 주요 함수를 정리했다면, 이제 이를 바탕으로 실제 챗봇 형태의 앱을 어떻게 구현하는지 살펴볼 수 있다.

아래 코드는 Streamlit과 OpenAI API를 이용해 간단한 GPT 챗봇을 만드는 예제이다.

import streamlit as st
import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()
OPENAI_API_KEY = os.getenv('OPENAI_API_KEY')

# API 연결
client = OpenAI(api_key=OPENAI_API_KEY)

# 화면 구성
st.title("GPT Chatbot")

# 모델명 저장
if 'openai_model' not in st.session_state:
    st.session_state.openai_model = 'gpt-5.2'

# 대화 기록 저장소 초기화
if 'messages' not in st.session_state:
    st.session_state.messages = []

# 기존 대화 출력
for msg in st.session_state.messages:
    with st.chat_message(msg['role']):
        st.markdown(msg['content'])

# 사용자 입력 처리
if prompt := st.chat_input('메시지를 입력하세요'):
    st.session_state.messages.append(
        {
            "role": "user",
            "content": prompt
        }
    )

    with st.chat_message('user'):
        st.markdown(prompt)

    with st.chat_message('assistant'):
        stream = client.chat.completions.create(
            model=st.session_state.openai_model,
            messages=[
                {
                    "role": m['role'],
                    "content": m['content']
                }
                for m in st.session_state.messages
            ],
            stream=True
        )

        response = st.write_stream(stream)

        st.session_state.messages.append(
            {
                'role': 'assistant',
                'content': response
            }
        )

 

8-1. 전체 흐름 먼저 이해하기

이 코드는 다음 순서로 동작한다.

1. 필요한 라이브러리를 불러온다.
2. .env 파일에서 API 키를 읽어 OpenAI 클라이언트를 만든다.
3. Streamlit 화면에 제목을 출력한다.
4. 세션 상태(st.session_state)에 모델명과 대화 기록을 저장할 공간을 만든다.
5. 이전 대화 내용을 화면에 다시 출력한다.
6. 사용자가 입력창에 메시지를 입력하면, 그 내용을 대화 기록에 추가한다.
7. OpenAI API로 응답을 생성한다.
8. 생성된 응답을 화면에 스트리밍 방식으로 보여준다.
9. 응답 내용도 대화 기록에 저장한다.

즉, 이 코드는 단순히 입력창 하나를 만드는 것이 아니라, 대화 기록을 유지하는 챗봇 구조 전체를 구현한 것이다.

 

8-2. 라이브러리 불러오기

import streamlit as st
import os
from openai import OpenAI
from dotenv import load_dotenv

 

이 부분은 필요한 라이브러리를 가져오는 단계이다.

• streamlit : 웹 화면과 입력 UI를 만들기 위한 라이브러리
• os : 환경변수를 읽기 위한 파이썬 내장 모듈
• OpenAI : OpenAI API를 사용하기 위한 클라이언트
• load_dotenv : .env 파일에 저장된 API 키를 불러오기 위한 함수

즉, 이 단계는 앱 화면 구성 + API 연결 준비를 위한 기본 설정이라고 볼 수 있다.

 

8-3. API 키 불러오기와 클라이언트 생성

load_dotenv()
OPENAI_API_KEY = os.getenv('OPENAI_API_KEY')

client = OpenAI(api_key=OPENAI_API_KEY)

 

이 부분은 OpenAI API를 사용하기 위한 인증 설정이다.

먼저 load_dotenv()를 호출하면 .env 파일에 저장된 환경변수가 현재 파이썬 프로그램에서 사용 가능해진다.

이후 os.getenv('OPENAI_API_KEY')를 통해 환경변수 값을 읽어와 OPENAI_API_KEY 변수에 저장한다.

마지막으로 OpenAI(api_key=OPENAI_API_KEY)를 사용해 실제 API 요청에 사용할 클라이언트를 생성한다.

 

즉, 이 단계는 OpenAI와 연결하기 위한 준비 과정이다

 

참고로 파이썬에서는 대문자로 작성된 변수명을 상수처럼 사용하는 것이 일반적인 관례이다.
하지만 이는 언어 차원에서 강제되는 규칙은 아니며, 개발자들이 가독성과 의미 전달을 위해 사용하는 암묵적인 규칙(convention)이다.

 

 

8-4. 화면 제목 출력

st.title("GPT Chatbot")

 

이 코드는 앱 상단에 제목을 출력한다.
Streamlit에서는 st.title()을 사용하면 가장 큰 제목 형식으로 텍스트가 표시된다.

 

이 한 줄만으로도 사용자는 현재 앱이 무엇을 하는지 바로 알 수 있다.

 

8-5. 모델명 저장하기

if 'openai_model' not in st.session_state:
    st.session_state.openai_model = 'gpt-5.2'

 

여기서 중요한 것은 st.session_state이다.
Streamlit은 사용자의 입력이 발생할 때마다 스크립트를 위에서부터 다시 실행하는 구조이기 때문에, 값을 따로 저장하지 않으면 이전 상태가 유지되지 않는다.

 

이 코드는 세션 상태에 openai_model이라는 이름으로 모델명을 저장하는 역할을 한다.

• 처음 실행될 때만 'gpt-5.2'를 저장
• 이미 값이 있으면 다시 덮어쓰지 않음

즉, 현재 사용할 모델명을 세션 상태에 보관하는 코드이다.

 

 

8-6. 대화 기록 저장소 초기화

이 부분은 챗봇의 대화 기록을 저장하기 위한 준비 단계이다.

if 'messages' not in st.session_state:
    st.session_state.messages = []

 

messages는 리스트 형태로 저장되며, 각 메시지는 다음과 같은 딕셔너리 구조를 가진다.

{
    "role": "user",
    "content": "안녕하세요"
}

{
    "role": "assistant",
    "content": "안녕하세요. 무엇을 도와드릴까요?"
}

 

즉, 이 코드는 사용자와 챗봇의 대화 내역을 저장할 빈 리스트를 만드는 역할을 한다.

 

8-7. 기존 대화 출력하기

 

for msg in st.session_state.messages:
    with st.chat_message(msg['role']):
        st.markdown(msg['content'])

 

이 부분은 지금까지 저장된 대화 내용을 화면에 다시 그려주는 역할을 한다.

Streamlit은 입력이 발생할 때마다 전체 코드가 다시 실행되기 때문에, 이전 대화를 화면에 유지하려면 저장된 기록을 다시 출력해야 한다.

• for msg in st.session_state.messages : 저장된 모든 메시지를 하나씩 꺼냄
• st.chat_message(msg['role']) : 메시지의 역할에 따라 사용자 또는 챗봇 말풍선 생성
• st.markdown(msg['content']) : 실제 대화 내용 표시

즉, 이 코드는 대화 기록을 채팅창 형태로 복원하는 코드이다.

 

8-8. 사용자 입력 받기

if prompt := st.chat_input('메시지를 입력하세요'):

 

이 부분은 사용자가 채팅 입력창에 메시지를 입력했는지 확인하는 코드이다.

 

st.chat_input()은 채팅 전용 입력창을 화면 하단에 만들어준다.
사용자가 입력 후 전송하면 그 값이 반환되고, 입력이 없으면 None에 가까운 값으로 처리된다.

 

여기서 :=는 왈러스 연산자로, 값을 변수에 저장하면서 동시에 조건문에서 검사하는 역할을 한다.

즉, 이 코드는 다음과 같은 의미이다.

• 사용자가 메시지를 입력하면 그 값을 prompt에 저장
• 입력된 경우에만 아래 코드 실행

 

8-9. 사용자 메시지 저장하기

st.session_state.messages.append(
    {
        "role": "user",
        "content": prompt
    }
)

 

이 부분은 사용자가 입력한 메시지를 대화 기록에 추가하는 코드이다.

• "role": "user" : 이 메시지가 사용자 메시지임을 의미
• "content": prompt : 사용자가 입력한 실제 텍스트 저장

즉, 이 단계에서 사용자의 질문이 기록에 저장된다.

 

8-10. 사용자 메시지를 화면에 바로 출력하기

with st.chat_message('user'):
    st.markdown(prompt)

 

이 코드는 사용자가 방금 입력한 메시지를 즉시 화면에 보여주는 역할을 한다.

이미 messages에 저장했더라도, 현재 실행 중인 흐름 안에서 바로 보이게 하려면 이처럼 직접 출력해주는 것이 자연스럽다.

 

8-11. OpenAI API로 응답 생성하기

with st.chat_message('assistant'):
    stream = client.chat.completions.create(
        model=st.session_state.openai_model,
        messages=[
            {
                "role": m['role'],
                "content": m['content']
            }
            for m in st.session_state.messages
        ],
        stream=True
    )

이 부분이 실제 챗봇 응답을 생성하는 핵심 코드이다.

• model=st.session_state.openai_model
  현재 세션에 저장된 모델명을 사용
• messages=[ ... for m in st.session_state.messages ]
  지금까지의 전체 대화 기록을 OpenAI API에 전달
• stream=True
  응답을 한 번에 받지 않고, 조금씩 나누어 받도록 설정

즉, 이 코드는 이전 대화 맥락을 포함한 상태로 챗봇 응답을 생성하는 역할을 한다.

 

 

8-12. 스트리밍 방식으로 응답 출력하기

response = st.write_stream(stream)

 

st.write_stream()은 스트리밍 응답을 화면에 실시간으로 출력하는 함수이다.
챗봇이 한 글자씩 답변을 써 내려가는 것처럼 보이는 효과를 만들 수 있다.

 

이 함수는 단순히 출력만 하는 것이 아니라, 최종적으로 생성된 전체 응답 문자열도 반환한다.
따라서 화면 출력과 응답 저장을 동시에 처리할 수 있다.

 

8-13. 챗봇 응답을 대화 기록에 저장하기

st.session_state.messages.append(
    {
        'role': 'assistant',
        'content': response
    }
)

 

이 부분은 방금 생성된 챗봇 응답을 대화 기록에 추가하는 코드이다.

이렇게 해야 다음번 실행 때도 이전 대화가 유지되고, 이후 API 요청에도 맥락이 계속 전달된다.

즉, 이 단계는 챗봇의 답변을 기억하게 만드는 과정이다.

 

8-14. 이 코드의 핵심 의미

이 예제는 단순히 Streamlit 화면을 만드는 수준이 아니라, 다음 요소를 모두 포함하고 있다.

• Streamlit UI 구성
• 채팅 입력 처리
• 세션 상태를 이용한 대화 기록 유지
• OpenAI API 연동
• 스트리밍 응답 출력

즉, Streamlit을 이용해 실제 대화형 챗봇 애플리케이션의 기본 구조를 구현한 코드라고 볼 수 있다.

 

8-15. 현재 코드의 한계와 확장 가능성

이 코드는 학습용 예제로는 매우 적절하지만, 실제 서비스 수준으로 확장하려면 몇 가지를 더 고려할 수 있다.

 

첫째, 대화 기록이 계속 누적되므로 길이가 너무 길어질 수 있다. 이 경우 토큰 사용량이 증가하고 응답 속도가 느려질 수 있으므로, 오래된 메시지를 일부 삭제하거나 요약하는 방식이 필요할 수 있다.

둘째, 현재는 메모리 기반으로만 대화가 저장된다. 따라서 DB와 연동하면 사용자별 대화 기록을 장기 저장할 수 있다.

셋째, 예외 처리나 API 오류 처리, 로딩 표시, 사용자별 설정 기능 등을 추가하면 더 완성도 높은 앱으로 발전시킬 수 있다.

 

9. Streamlit을 사용하는 이유

Streamlit의 장점은 명확하다.

1. 파이썬만으로 웹 UI를 빠르게 만들 수 있다.
2. 둘째, 데이터 분석 결과나 모델 출력값을 바로 화면에 연결하기 쉽다.
3. 셋째, 사용자 입력에 따라 결과를 즉시 다시 그려주기 때문에 상호작용형 앱 구현이 편하다.
4. 넷째, 챗봇, 대시보드, 예측 시스템처럼 “결과를 보여주는 AI 앱”을 만들 때 진입장벽이 낮다.

즉, Streamlit은 머신러닝이나 딥러닝 모델 자체를 만드는 도구라기보다, 그 결과를 사용자에게 보여주는 앱을 빠르게 구현하는 도구라고 볼 수 있다.

 

 

---

👉 FastAPI와 REST API 쉽게 이해하기 (Streamlit과의 관계까지)