어떤 일을 했고, 결과는 어땠어?
웹(Next.js)과 AI 서버(Python)를 모두 만들었습니다. 결과 중심으로 정리하면 이렇습니다. (경로 로직과 에이전트 분기는 “설계 고민과 회고” 대화에 따로 정리했습니다.)
웹 · 풀스택 (Next.js)
| 한 일 | 결과 |
|---|---|
| BFF 설계 | 외부 API 키와 AI 서버 주소를 브라우저에 노출하지 않음 · 서버 라우트 10여 개 |
| SEO 콘텐츠 레이어 | 검색엔진이 읽을 수 있는 페이지 1개 → 77개 · 검색 노출 3,500회 |
| AI 코스 화면 연동 | 기존 코스 UI를 그대로 재사용하면서 AI 코스를 실시간 스트리밍으로 표시 |
| 코스 동선 최적화 | 무작위 순서 대비 동선 평균 1.99배 단축 (시뮬레이션) |
| 한/영 다국어 · 모바일 | 화면·AI 프롬프트·코스 콘텐츠까지 한/영 전환 · 모바일 바텀시트 화면 |
AI 엔지니어링 (LangGraph · RAG)
| 한 일 | 결과 |
|---|---|
| 코스 생성 파이프라인 | 9노드 중 LLM 판단은 3곳뿐 · 모델 4종 180회 실행에서 없는 장소 생성 0건 |
| 식당 정보 캐싱 | 요청마다 20~30초 걸리던 식당 조회 → 요청 중 외부 호출 0회 |
| 임베딩 배포 구조 | GPU 상시 가동 → 트래픽 없으면 0대 · 인덱스 62M → 20M |
| 장소 데이터 확장 | 최종 1,651곳 (마지막 확장 807곳 → 1,651곳) · 권역을 주소 자치구 기준으로 재배정 |
| 혼잡도 예보 전환 | 생성 시점의 현재값 → 방문 시각의 예보값 |
자세한 내용은 아래 질문에서 하나씩 설명합니다.
웹은 Next.js로 어떻게 설계했어?
한 앱 안에서 렌더링 방식을 나눴습니다. 지도 화면은 Naver Maps SDK가 브라우저에서만 동작하므로 클라이언트 전용(dynamic(..., { ssr: false }))으로 불러옵니다. 반대로 명소·코스 소개 페이지는 검색엔진이 읽어야 하므로 서버에서 렌더링합니다. 같은 루트 레이아웃을 쓰되, 라우트 그룹 (content)로 두 영역을 나눴습니다.
서버 라우트(Route Handler)를 BFF로 썼습니다. 브라우저는 외부 API나 AI 서버를 직접 부르지 않고 Next.js 서버 라우트만 호출합니다. API 키는 서버 환경변수에만 있습니다.
| 라우트 | 하는 일 |
|---|---|
/api/places/congestion | 서울시 실시간 인구 API → 지도 혼잡도 |
/api/ai-info | 장소 정보 + 혼잡 예보·날씨를 넣어 AI 방문 팁 생성 (서버 메모리 30분 캐시) |
/api/ai-recommend | 조건에 맞는 장소 추천 (후보를 반경 3km 군집으로 먼저 좁힘) |
/api/course | AI 서버의 SSE 스트림을 그대로 중계 (X-Internal-Token 부착) |
/api/poi · /api/geocode | 장소 검색 · 좌표 변환 |
/api/feedback | 사용자 피드백 수집 |
배포는 Vercel 서울 리전(icn1) 입니다. 서울시 API와 AI 서버(Cloud Run 서울 리전)가 모두 가까이 있어서 왕복 지연을 줄였습니다.
다국어는 데이터까지 나눴습니다. 화면 문구뿐 아니라 AI 프롬프트도 한/영으로 분리했고, 영문 코스 콘텐츠는 별도 파일로 두되 장소 이름을 기준점으로 삼아 한/영 데이터가 서로 어긋나면 감지되게 했습니다.
근거: 773ec68 (혼잡도 연동) · 83bc2c3 (다국어) · 0851d82 (UI 전면 리팩토링) · bb8caff (모바일)
SEO는 어떻게 했어?
문제 — 지도 앱은 클라이언트에서만 그려지기 때문에, 서버가 보내는 HTML에는 텍스트가 거의 없었습니다. 검색엔진이 읽을 수 있는 페이지가 사실상 홈 한 장뿐이었습니다.
조치 — 지도 앱은 그대로 두고, 그 옆에 서버 렌더링 콘텐츠 레이어를 따로 얹었습니다.
/spots·/spots/[slug]— 서울명소 55곳. 주소는 로마자 표기(gyeongbokgung-palace)/courses·/courses/[id]— 테마 코스 19개- 구조화 데이터(JSON-LD) — 명소는
TouristAttraction, 코스는TouristTrip sitemap.ts·robots.ts— URL 77개, 프리뷰 배포는 색인 차단- 코스 ↔ 명소, 주변 명소끼리 서로 링크해서 내부 링크망 구성
지도 화면은 스크롤을 잠가야 하고 콘텐츠 페이지는 스크롤이 필요한데, 둘이 같은 루트 레이아웃을 씁니다. 그래서 스크롤 잠금을 body에 직접 걸지 않고 CSS body:has(> .app-shell)로 지도 화면일 때만 걸리게 바꿨습니다.
결과 — 색인 대상 URL이 1개 → 77개가 됐고, 광고 없이 구글 검색 노출 3,500회 · 클릭 130회를 기록했습니다(2026-09-29 기준).
근거: 60a2ec0
AI 코스는 웹에 어떻게 붙였어?
스트리밍 중계 — /api/course는 AI 서버의 SSE 스트림을 브라우저로 그대로 흘려보냅니다. 버퍼링되면 진행 상황이 한꺼번에 몰려오기 때문에 Node 런타임과 동적 렌더링을 강제하고 X-Accel-Buffering: no를 붙였습니다. 오류도 SSE 이벤트로 보내서, 화면은 스트림 하나만 읽으면 성공과 실패를 모두 처리할 수 있습니다. AI 서버 주소가 설정되지 않은 환경에서는 오류 이벤트로 격리됩니다.
타입을 넓혀서 기존 UI를 재사용 — AI 코스를 위한 화면을 새로 만들지 않고, 정적 테마 코스 타입(ThemeCourse)을 확장했습니다. 시간표, 식사 슬롯, 예상 혼잡도, 여러 날 일정 같은 새 필드는 전부 선택 항목으로 추가해서, 기존 테마 코스 19개는 전혀 영향을 받지 않고 지도·상세 패널·장소 카드를 그대로 씁니다.
- 식사 슬롯에 주변 식당이 없으면 타임라인에는 자리만 남기고 지도와 경로에서는 뺍니다.
- 여러 날 코스는 일차별로 경로 색을 다르게 그립니다.
- AI 코스엔 대표 사진이 없어서, 코스 id 해시로 그라데이션을 만들어 이미지 요청 자체를 없앴습니다(404 방지).
사용 흐름 — 조건 선택 위저드 → 생성 단계 실시간 표시 → 완성 코스 렌더링 순서입니다. 만든 코스는 조건과 함께 브라우저에 저장해 나중에 “어떻게 만들었는지” 다시 볼 수 있고, “다시 만들기”는 시드를 바꿔 다른 코스를 받습니다.
AI 서버의 파이프라인은 어떻게 설계했어?
LangGraph StateGraph의 선형 9노드 파이프라인입니다.
| 노드 | 하는 일 | 바깥 의존 |
|---|---|---|
parse_intent | 자연어 → 칩 구조화 (칩으로 들어오면 0콜) | 챗 LLM |
plan | 시간 골격 · 식사 앵커 | 없음 (순수 계산) |
retrieve | 의미검색 + 권역 필터 · 개인화 재랭킹 · 종류 쿼터 | 임베딩 API → Chroma |
select_places | 장소 선정 · reason · activities | 챗 LLM (여러 날이면 일차별 병렬) |
fit_schedule | 방문 순서 · 시각 · 이동수단 | 없음 (순수 계산) |
meals | 끼니별 실제 식당 3곳 | 로컬 캐시 |
enrich | 방문 시각의 혼잡도 예보 | 서울시 citydata |
nearby | 주변 식당 · 진행 중 행사 카드 | 캐시 재사용 · 서울시 citydata |
compose | 제목 · 선정 근거 · 장소 카드 문구 | 챗 LLM |
LLM은 검색이 추려 준 후보 목록 안에서만 장소를 고를 수 있고, 목록에 없는 이름은 버립니다. 순서와 시각은 코드가 계산합니다.
결과 — 모델 4종 × 페르소나 15개 × 시드 3회, 총 180회 실행에서 만들어진 장소 1,098곳을 전수 검사했고 후보 밖 장소는 한 건도 없었습니다. 어떤 모델을 써도 같았기 때문에, 환각을 막은 건 모델이 아니라 구조라고 판단했습니다.
클라이언트 연결 — 브라우저는 Vercel의 Next.js BFF에만 붙고, BFF가 X-Internal-Token을 붙여 AI 서버로 프록시합니다. AI 서버 주소와 토큰은 브라우저에 노출되지 않습니다. 어디를, 왜, 어떤 순서로 갈지는 AI 서버가 정하고, 프론트는 그 순서대로 지도에 실제 도로 경로만 그립니다.
근거: 모델 비교 평가 10-2절 · 97a123e
식당 조회가 왜 20~30초나 걸렸어?
코스에 넣을 식당을 요청마다 Visit Seoul 상세 API로 실시간 조회했기 때문입니다. 식당 여러 곳을 한꺼번에 부르다 보니 API 호출 한도에 걸려, 코스 하나에 식당 조회만 20~30초가 걸렸습니다.
그런데 식당 목록은 자주 바뀌지 않는 정보입니다. 그래서 서울을 9개 권역으로 나눠 미리 캐시 파일로 저장해 두고, 요청이 오면 파일을 읽어 반경으로 거르기만 하도록 바꿨습니다.
처음에는 권역 중심 좌표로 키워드 검색을 해서 캐시를 만들었는데, 제목·요약 문자열만 매칭하는 방식이라 서울 전체에서 96곳밖에 잡히지 않았습니다. “음식” 카테고리 전체를 페이지 단위로 훑고 좌표로 권역을 배정하는 방식으로 바꾸자 1,249곳이 모두 들어왔습니다.
확인 — 종로·맛집 조건으로 실제 요청을 보냈을 때, 점심 슬롯 식당 3곳이 인사동 기준 0.02~0.04km 안에서 API 호출 없이 배정됐습니다. 다만 관악·사당처럼 원본 데이터 자체가 적은 권역은 후보가 부족해서, 직접 찾아보라는 안내 문구로 대신합니다.
배포는 어떻게 했어?
AI 서버는 Cloud Run(서울 리전) CPU 컨테이너에 올렸습니다. 트래픽이 없으면 인스턴스가 0대로 내려가서, 쓰지 않는 시간에는 비용이 들지 않습니다.
이 구조가 가능했던 건 임베딩을 API로 바꿨기 때문입니다. 개발 때 쓰던 로컬 모델(qwen3-embedding:8b)을 그대로 배포하려면 GPU 인스턴스를 계속 띄워 둬야 했습니다. Upstage embedding-2로 바꾸면서 차원이 4096 → 1024로 줄어, 이미지에 함께 넣는 Chroma 인덱스도 62M → 20M으로 줄었습니다. 한국어 검색 품질과 코스 품질은 기존 모델과 차이가 없었습니다.
| 측정 (배포 직후) | 값 |
|---|---|
| 첫 요청 (콜드 스타트 포함) | 14.8초 |
| 이후 요청 | 7.7초 |
/health | 1.6초 |
코스 생성에 몇 초가 걸리기 때문에 SSE로 진행 상황을 계속 보내서, 사용자가 빈 화면을 기다리지 않게 했습니다.
데이터 쪽은 어떻게 개선했어?
장소 데이터를 여러 번에 걸쳐 늘려 최종 1,651곳을 모았습니다. 서울시 열린데이터, Visit Seoul, 문화공간 정보를 직접 정제해 합쳤고, 마지막 확장에서 807곳 → 1,651곳이 됐습니다. 처음에는 장소가 적은 데다 강남·강북·강동·강서 4개 권역으로만 나뉘어 있어서, 권역이 너무 넓다 보니 장소 사이 거리가 10km를 넘는 코스가 나왔습니다. 장소를 늘린 뒤로는 이태원·한남, 성수·건대처럼 좁게 나눈 권역에서도 코스를 짤 만큼 후보가 모입니다.
권역은 좌표가 아니라 주소의 자치구로 배정합니다. 좌표로 가장 가까운 권역을 붙였더니 한강 경계에서 강 건너 권역으로 잘못 붙는 경우가 나왔습니다(압구정이 성수 권역에 붙는 식). 전수 검사해 보니 861건 중 110건이 이렇게 잘못 배정돼 있었습니다.
혼잡도는 방문 시각의 예보로 바꿨습니다. 오후 2시에 저녁 7시 코스를 만들면 2시의 혼잡도가 붙는 모순이 있었습니다. 서울시 citydata 응답에 이미 12시간 예보가 함께 오기 때문에 추가 호출 없이 바꿀 수 있었습니다. 1.5시간 전 예보 인구수가 실제 값과 맞는지 확인했고, 등록된 지점은 모두 예보를 제공했습니다. 혼잡도는 장소 선정에서는 빼고 정보 표시에만 씁니다.
챗 모델은 어떻게 골랐어?
같은 파이프라인에 모델만 바꿔 180회 돌려 비교했습니다. solar-open2, solar-pro4, claude-haiku-4-5, gemini-3.1-flash-lite 4종에 페르소나 15개 × 시드 3회씩입니다. .env의 LLM_PROVIDER 값만 바꾸면 모델이 바뀌도록 만들어 둔 덕분에 조건을 똑같이 맞출 수 있었습니다.
| 확인한 것 | 결과 |
|---|---|
| 없는 장소 생성 | 4종 모두 0건 |
| 코스당 입력 토큰 | 모델에 따라 최대 1.88배 차이 (한국어 토크나이저 차이) |
| 생성 실패 | 0~4.4% (표본이 작아 순위는 판단 불가) |
| 글 품질 (LLM 심사) | 구분 불가 — 순서만 바꿔도 판정이 40~60% 뒤집힘 |
결론은 이 구조에서는 모델이 품질을 크게 바꾸지 못한다는 것이었습니다. 그래서 비용(토큰)과 안정성을 기준으로 골랐습니다. solar-open2 비공개 베타가 끝난 뒤에는 생성 실패 0건이었던 gemini-3.1-flash-lite로 바꿨고, 임베딩은 Upstage를 그대로 씁니다.
근거: 모델 비교 평가 문서 · 실행 기록 eval/runs/