여행 중 오디오 가이드는 목적지의 역사와 문화를 이해하는 데 큰 도움이 됩니다. 하지만 기존 오디오 가이드는 사전에 녹음된 콘텐츠만 제공하기 때문에 사용자 질문에 대응하거나 맞춤형 정보를 제공하는 데 한계가 있었습니다. OpenAI의 최신 Agents SDK와 음성 파이프라인을 활용하면 이런 문제를 해결하고 동적이고 개인화된 AI 오디오 투어 가이드를 만들 수 있습니다. 이 튜토리얼에서는 사용자의 위치, 관심사, 원하는 투어 시간을 기반으로 맞춤형 오디오 투어를 생성하는 애플리케이션을 구축해 보겠습니다.
왜 AI 오디오 투어 가이드가 필요한가?
OpenAI가 Agents SDK와 새로운 음성 파이프라인 통합을 발표했을 때, 이는 음성 기반 애플리케이션 개발에 큰 돌파구가 되었습니다. 특히 동적 오디오 콘텐츠 생성이라는 실용적 문제를 해결할 수 있게 되었습니다. 기존에는 새로운 콘텐츠가 필요할 때마다 음성 인재를 다시 녹음해야 했지만, 이제는 AI로 실시간 콘텐츠 생성이 가능해졌습니다.
OpenAI Agents SDK는 음성 기반 애플리케이션을 쉽게 구축할 수 있는 기능을 제공합니다. (출처: OpenAI)
GPT-4o-mini TTS와 같은 OpenAI의 새로운 음성 모델은 자연스러운 감정 표현이 가능한 음성으로 사용자 경험을 크게 향상시킵니다. 단순한 매개변수 조정 없이도 자연어 지시만으로 음성 특성(톤, 속도, 감정, 개성 등)을 쉽게 조절할 수 있는 점이 가장 강력한 기능 중 하나입니다.
우리가 만들 앱의 특징
이번에 구축할 Streamlit 애플리케이션은 OpenAI Agents SDK와 GPT-4o-mini TTS를 활용하여 개인화된 오디오 투어 가이드 시스템을 만듭니다. 이 앱은 사용자 위치에 맞는 콘텐츠를 생성하고, 자연스러운 음성으로 변환해 줍니다.
주요 기능
- 다중 에이전트 아키텍처: 특화된 콘텐츠 생성기들로 구성
- 오케스트레이터 에이전트: 전체 투어 흐름 조정, 전환 관리, 모든 전문가 에이전트의 콘텐츠 조합
- 역사 에이전트: 권위 있는 목소리로 유익한 역사적 이야기 전달
- 건축 에이전트: 설명적이고 기술적인 톤으로 건축적 세부사항, 스타일, 디자인 요소 강조
- 문화 에이전트: 열정적인 목소리로 지역 관습, 전통, 예술적 유산 탐색
- 요리 에이전트: 열정적이고 매력적인 톤으로 상징적인 요리와 음식 문화 설명
- 위치 인식 콘텐츠 생성: 웹 검색 통합으로 최신 정보 제공
- 맞춤형 투어 시간: 5분에서 60분까지 선택 가능
- 고품질 오디오 출력: GPT-4o-mini TTS 활용
- 사용자 친화적 인터페이스: Streamlit으로 구현
- 사용자 입력 위치 기반 동적 콘텐츠 생성
- 실시간 웹 검색 통합으로 관련성 있고 최신 정보 제공
- 사용자 관심 카테고리 기반 개인화된 콘텐츠 전달
앱 작동 방식
사용자 흐름과 다중 에이전트 워크플로우는 다음과 같이 진행됩니다:
- 사용자 입력: 사용자는 세 가지 핵심 정보를 입력합니다:
- 탐색하고 싶은 위치(도시, 랜드마크, 동네)
- 관심 분야(역사, 건축, 문화, 요리)
- 원하는 투어 길이(5-60분)
- 계획 단계: 플래너 에이전트가 사용자 관심사와 투어 시간에 따라 각 콘텐츠 섹션에 시간을 할당합니다.
- 콘텐츠 생성: 전문화된 에이전트(건축, 역사, 문화, 요리)가 각 분야에 맞는 콘텐츠를 생성합니다. 각 에이전트는:
- 해당 위치에 대한 최신 정보를 얻기 위해 웹 검색 사용
- 회화적이고 오디오에 적합한 형식으로 콘텐츠 구성
- 투어 시간에 맞춰 계산된 단어 제한 내에서 작업
- 투어 조립: 오케스트레이터 에이전트가 모든 섹션을 자연스러운 전환으로 결합합니다.
- 텍스트-음성 변환: 최종 투어 텍스트가 GPT-4o-mini TTS의 “nova” 음성을 사용하여 자연스러운 오디오로 변환됩니다.
사전 준비 사항
시작하기 전에 다음 항목이 준비되어 있는지 확인하세요:
- Python 설치(버전 3.10 이상 권장)
- OpenAI API 키
- 코드 에디터(VS Code 또는 PyCharm 권장)
- Python 프로그래밍 기본 지식
단계별 구현 가이드
전문 에이전트 설정하기
먼저 agent.py 파일을 생성하여 오디오 투어를 위한 모든 전문 에이전트를 정의합니다.
첫 번째로, 건축 에이전트를 살펴보겠습니다:
ARCHITECTURE_AGENT_INSTRUCTIONS = """
당신은 자가 안내 오디오 투어 시스템의 건축 에이전트입니다.
위치와 사용자의 관심 영역이 주어지면, 다음과 같은 역할을 수행합니다:
1. 건축 스타일, 주목할만한 건물, 도시 계획, 디자인 요소 설명
2. 기술적 통찰력과 접근하기 쉬운 설명의 균형 유지
3. 시각적으로 가장 눈에 띄거나 역사적으로 중요한 구조물 강조
4. 건축 콘텐츠를 전달할 때 자세하고 서술적인 음성 스타일 채택
...
"""
class Architecture(BaseModel):
output: str
architecture_agent = Agent(
name="ArchitectureAgent",
instructions=ARCHITECTURE_AGENT_INSTRUCTIONS,
model="gpt-4o-mini",
tools=[WebSearchTool()],
model_settings=ModelSettings(tool_choice="required"),
output_type=Architecture
)
역사, 문화, 요리 콘텐츠를 위한 유사한 에이전트들도 각각 구체적인 지침과 출력 유형으로 정의됩니다.
시간 할당을 관리하는 플래너 에이전트:
planner_agent = Agent(
name="PlannerAgent",
instructions=PLANNER_INSTRUCTIONS,
model="gpt-4o",
output_type=Planner,
)
그리고 모든 것을 조립하는 오케스트레이터 에이전트:
orchestrator_agent = Agent(
name="OrchestratorAgent",
instructions=ORCHESTRATOR_INSTRUCTIONS,
model="gpt-4o-mini",
output_type=FinalTour,
)
투어 관리자 클래스 구현하기
manager.py 파일을 생성하여 TourManager를 정의합니다.
class TourManager:
"""전체 흐름을 조율합니다"""
def __init__(self) -> None:
self.console = Console()
self.printer = Printer(self.console)
async def run(self, query: str, interests: list, duration: str) -> None:
# 시간에 따른 단어 제한 계산
words_per_minute = 150
total_words = int(duration) * words_per_minute
words_per_section = total_words // len(interests)
# 선택된 관심사만 조사
if "Architecture" in interests:
research_results["architecture"] = await self._get_architecture(query, interests, words_per_section)
if "History" in interests:
research_results["history"] = await self._get_history(query, interests, words_per_section)
# ...다른 관심사에 대해서도 동일한 방식으로 진행
# 선택된 관심사만으로 최종 투어 가져오기
final_tour = await self._get_final_tour(query, interests, duration, research_results)
# 최종 투어 콘텐츠 구성
sections = []
for interest in interests:
if interest.lower() in research_results:
sections.append(research_results[interest.lower()].output)
# 자연스러운 전환으로 최종 투어 포맷팅
final = ""
for i, content in enumerate(sections):
if i > 0:
final += "\n\n" # 섹션 간 간격 추가
final += content
return final
관리자는 각 콘텐츠 유형에 대한 특수 메서드를 호출하고 요청된 투어 시간에 따라 단어 수를 계산합니다.
음성 변환 기능 구현하기
주요 애플리케이션 파일 ai_audio_tour_agent.py에서 생성된 투어 텍스트를 음성으로 변환하는 함수:
def tts(text):
from pathlib import Path
from openai import OpenAI
client = OpenAI()
speech_file_path = Path(__file__).parent / f"speech_tour.mp3"
response = client.audio.speech.create(
model="gpt-4o-mini-tts",
voice="nova",
input=text,
instructions="""당신은 친근하고 매력적인 투어 가이드입니다. 마치 방문자와 함께 걷고 있는 것처럼
자연스럽고 대화하듯 말하세요. 전체적으로 따뜻하고 초대하는 톤을 사용하세요.
로봇 같거나 형식적인 언어를 피하세요. 투어가 지식이 풍부한 친구와의 캐주얼한
대화처럼 느껴지게 만드세요. 주제 간 자연스러운 전환을 사용하고 열정적이지만
편안한 속도를 유지하세요."""
)
response.stream_to_file(speech_file_path)
return speech_file_path
Streamlit UI 구현하기
사용자가 선호도를 입력할 수 있는 깔끔한 인터페이스를 제공하는 Streamlit UI:
# 카드로 깔끔한 레이아웃 만들기
col1, col2 = st.columns([2, 1])
with col1:
st.markdown("### 📍 어디를 둘러보고 싶으신가요?")
location = st.text_input("", placeholder="도시, 랜드마크 또는 위치 입력...")
st.markdown("### 🎯 무엇에 관심이 있으신가요?")
interests = st.multiselect(
"",
options=["History", "Architecture", "Culinary", "Culture"],
default=["History", "Architecture"],
help="알고 싶은 주제를 선택하세요"
)
with col2:
st.markdown("### ⏱️ 투어 설정")
duration = st.slider(
"투어 시간 (분)",
min_value=5,
max_value=60,
value=10,
step=5,
help="투어 시간을 선택하세요"
)
투어 생성 프로세스 구현하기
사용자가 “투어 생성” 버튼을 클릭하면 투어 생성 프로세스가 시작됩니다:
if st.button("🎧 투어 생성", type="primary"):
# ... 유효성 검사
with st.spinner(f"{location}의 맞춤형 투어를 생성 중..."):
mgr = TourManager()
final_tour = run_async(mgr.run, location, interests, duration)
# 투어 콘텐츠 표시
with st.expander("📝 투어 콘텐츠", expanded=True):
st.markdown(final_tour)
# 오디오 생성 및 표시
with st.spinner("🎙️ 오디오 투어 생성 중..."):
progress_bar = st.progress(0)
tour_audio = tts(final_tour)
progress_bar.progress(100)
st.markdown("### 🎧 투어 듣기")
st.audio(tour_audio, format="audio/mp3")
# 다운로드 버튼 추가
with open(tour_audio, "rb") as file:
st.download_button(
label="📥 오디오 투어 다운로드",
data=file,
file_name=f"{location.lower().replace(' ', '_')}_tour.mp3",
mime="audio/mp3"
)
앱 실행하기
코드가 준비되면 앱을 실행할 차례입니다.
- 터미널에서 프로젝트 폴더로 이동한 후 다음 명령어를 실행합니다:
streamlit run ai_audio_tour_agent.py
- Streamlit은 로컬 URL(일반적으로 http://localhost:8501)을 제공합니다. 웹 브라우저에서 이 URL을 열고 API 키를 입력하면 첫 번째 투어를 생성할 준비가 완료됩니다.
기술적 깊이: GPT-4o-mini TTS의 강점
이 프로젝트의 핵심은 OpenAI의 최신 텍스트-음성 변환 모델인 GPT-4o-mini TTS의 활용에 있습니다. 이 모델의 몇 가지 주목할 만한 특징은 다음과 같습니다:
- 자연스러운 감정 표현: 이 모델은 단순한 기계적 읽기를 넘어 감정과 뉘앙스를 담은 음성을 생성할 수 있습니다.
- 쉬운 음성 조절: 단순한 텍스트 프롬프트로 음성의 톤, 속도, 감정, 개성 특성을 조절할 수 있어 복잡한 매개변수 조정이 필요 없습니다.
- 다양한 음성 옵션: 현재 10개의 사전 설정 음성으로 시작하여 특정 시나리오에 맞게 음성을 커스터마이징할 수 있습니다.
- 합리적인 가격: GPT-4o-mini TTS는 입력 텍스트 토큰 100만 개당 $0.60, 출력 오디오 토큰 100만 개당 $12.00(약 분당 $0.015)의 비용으로 제공됩니다.
결론 및 활용 방안
OpenAI Agents SDK와 OpenAI의 최신 TTS 기능을 활용한 강력한 오디오 투어 생성 시스템을 구축했습니다. 이 애플리케이션은 다음과 같은 중요한 개념을 보여줍니다:
- 복잡한 작업을 해결하기 위한 여러 전문 에이전트의 조율 방법
- 최신 정보를 제공하기 위한 웹 검색 도구 활용법
- 오디오 전달에 최적화된 콘텐츠 생성 방법
- GPT-4o-mini TTS를 사용한 텍스트의 자연스러운 음성 변환 방법
이 프로젝트를 더욱 발전시키기 위한 몇 가지 아이디어:
- 위치 감지 추가: 매핑 API와 통합하여 근처 관심 지점 제안
- 음성 입력 구현: 타이핑 대신 말로 선호도 입력 가능하게 하기
- 단계별 투어 생성: 걷기 투어를 위한 랜드마크 간 방향 생성
- 다국어 지원: 국제 여행자를 위한 투어 번역
이 투어 가이드는 이러한 기술로 가능한 것의 한 예일 뿐입니다. 다양한 에이전트 구성과 기능으로 실험하여 더 정교한 AI 애플리케이션을 구축해 보세요.
답글 남기기