⚙️ [기능추가][장소명] 인스타 추출정보를 통한 정확한 장소명 추출 필요

[Cassiiopeia]

📝 현재 문제점

• Ollama API 를 사용해서 정확한 장소명을 추출해야합니다.
• Ollama에서 정해진 json 객체로 반환값을 내주는것에 대한 결과가 좀 미흡하긴합니다
• 그래서 fallback 한 5번으로 잡고 해야합니다
• 쉽게 사용할수있는 방법을 java 라이브러리로는 만들어놨는데 py에서는 직접 작성해야될것같습니다

🛠️ 해결 방안 / 제안 기능

• ai.suhsaechan.kr 을 사용하면됩니다 X-API-KEY 를 입력해야하는데 이것은 기본입니다
• 일단 테스트할 수 있어야 합니다
• 기본적인 테스트를 완료한 이슈는 다음과같습니다
• 사용해야할 모델은

gemma3:1b-it-qat

입니다 해당모델을 사용하여 구현해야합니다 (빠르고 나름 정확함)

어떤식의 json으로 여러 장소명들을 추출해야할지는 설계를 해야합니다

🙋‍♂️ 담당자

• 백엔드: @Cassiiopeia
• 프론트엔드: 이름
• 디자인: 이름

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260127_#19_인스타_추출정보를_통한_정확한_장소명_추출_필요

커밋 메시지

인스타 추출정보를 통한 정확한 장소명 추출 필요 : feat : {변경 사항에 대한 설명} https://github.com/MapSee-Lab/MapSy-AI/issues/19

[Cassiiopeia]

Ollama AI 서버에 대해서 고찰한 이슈 공유합니다

• 📄 [문서] Json Format Ollama API 지원에 대한 고찰 Cassiiopeia/suh-project-control#31

[Cassiiopeia]

구현 보고서: Ollama API 기반 장소명 추출 기능

GitHub Issue: #19 인스타 추출정보를 통한 정확한 장소명 추출
작성일: 2026-01-27
상태: ✅ 완료

---

1. 요약

인스타그램 콘텐츠(caption)에서 Ollama API(ai.suhsaechan.kr)를 사용하여 정확한 장소명을 추출하는 기능을 구현했습니다.

주요 구현 내용

• gemma3:1b-it-qat 모델을 사용한 장소명 추출
• JSON Schema 기반 구조화된 응답 처리
• 최대 3회 재시도 로직으로 Ollama의 불완전한 JSON 응답 대응
• 테스트 엔드포인트 /api/test/llm-place-extract 제공

---

2. 변경 파일 목록

파일	변경 유형	설명
src/core/config.py	수정	Ollama API 환경변수 추가
src/utils/common.py	수정	http_post_json() 함수 추가
src/services/modules/ollama_llm.py	신규	Ollama LLM 연동 모듈
src/apis/test_router.py	수정	테스트 엔드포인트 추가
.env	수정	환경변수 값 설정

---

3. 상세 구현 내용

3.1 환경변수 설정 (src/core/config.py)

# Ollama API (ai.suhsaechan.kr)
OLLAMA_API_URL: str = "https://ai.suhsaechan.kr/api/chat"
OLLAMA_API_KEY: str = ""
OLLAMA_MODEL: str = "gemma3:1b-it-qat"

3.2 HTTP POST 유틸리티 (src/utils/common.py)

OLLAMA_HTTP_TIMEOUT = 120.0  # Ollama API 타임아웃 (2분)

async def http_post_json(
    url: str,
    json_body: dict[str, Any],
    headers: dict[str, str] | None = None,
    timeout: float = OLLAMA_HTTP_TIMEOUT
) -> dict[str, Any]

• 기존 http_get_json() 패턴과 동일한 예외 처리
• 기본 타임아웃 120초 (긴 텍스트 처리 대응)

3.3 Ollama LLM 모듈 (src/services/modules/ollama_llm.py)

Pydantic 응답 모델

class OllamaPlaceResult(BaseModel):
    place_names: list[str] = Field(default_factory=list, description="추출된 장소명 리스트")
    has_places: bool = Field(default=False, description="장소 존재 여부")

JSON Schema (Ollama format 파라미터)

PLACE_EXTRACTION_SCHEMA = {
    "type": "object",
    "properties": {
        "place_names": {"type": "array", "items": {"type": "string"}},
        "has_places": {"type": "boolean"}
    },
    "required": ["place_names", "has_places"],
    "additionalProperties": False
}

프롬프트 설계

다음 텍스트에서 장소명(가게명, 상호명, 식당명, 카페명, 관광지명 등)을 추출하세요.

장소명 예시:
- 스타벅스 종합운동장사거리점
- 블루보틀 성수
- 스시호
- 사사노하

규칙:
1. 텍스트에 언급된 실제 장소명만 추출하세요.
2. 해시태그(#)가 붙어있어도 장소명이면 추출하세요. (#스시호 → 스시호)
3. 일반 명사(맛집, 초밥, 카페 등)는 장소명이 아닙니다.
4. 장소가 없으면 빈 배열 []을 반환하세요.

<Context>
{caption}
</Context>

핵심 함수

async def extract_place_names_with_ollama(
    caption: str,
    max_retries: int = 3
) -> OllamaPlaceResult

• X-API-KEY 헤더 인증
• 최대 3회 재시도 (JSON 파싱 실패 시)
• 실패 시 빈 결과 반환 (에러 발생하지 않음)

3.4 테스트 엔드포인트 (src/apis/test_router.py)

POST /api/test/llm-place-extract
Content-Type: application/json

{
  "caption": "1. #스시호 -위치_서울 송파구 가락로 98길..."
}

응답 예시

{
  "place_names": ["스시호", "시스스시", "김태완스시", "사사노하"],
  "has_places": true
}

---

4. API 사용법

cURL 예시

curl -X POST http://localhost:8001/api/test/llm-place-extract \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "저장해두면 도움 되는 송파 판초밥 맛집4\n\n1. #스시호\n-위치_서울 송파구 가락로 98길\n\n2. #시스스시\n-위치_서울 송파구 백제고분로43길 8"
  }'

기대 결과

{
  "place_names": ["스시호", "시스스시"],
  "has_places": true
}

---

5. 설계 결정사항

항목	결정	이유
재시도 횟수	3회	Ollama JSON 응답 불안정성 대응, 과도한 지연 방지
타임아웃	120초	긴 텍스트 처리 시 충분한 시간 확보
실패 처리	빈 결과 반환	파이프라인 중단 방지, 네이버 지도에서 추가 검증
프롬프트	느슨한 필터링	현대적 장소명의 다양성 수용
통합 방식	독립 모듈	기존 Gemini 워크플로우와 분리 운영

---

6. 환경변수 설정 (.env)

# Ollama API
OLLAMA_API_URL=https://ai.suhsaechan.kr/api/chat
OLLAMA_API_KEY=your_api_key_here
OLLAMA_MODEL=gemma3:1b-it-qat

---

7. 참고사항

• Ollama의 JSON Schema 지원은 제한적 (pattern, enum, minimum/maximum 미지원)
• 환각 현상 방지를 위해 명확한 프롬프트와 예시 제공
• 장소명이 없는 텍스트 입력 시 {"place_names": [], "has_places": false} 반환

[Cassiiopeia]

현재 정상 추출 확인되나 좀 성능이 안좋습니다

프롬프트로 잘 해결해야될것같습니다

curl -X 'POST' \
  'https://ai.mapsy.suhsaechan.kr/api/test/llm-place-extract' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "caption": "1. #스시호 -위치_서울 송파구 가락로 98길 2. #시스스시 -위치_서울 송파구"
}'

요청값

{
  "caption": "1. #스시호 -위치_서울 송파구 가락로 98길 2. #시스스시 -위치_서울 송파구"
}

반환값

{
  "place_names": [
    "스시호",
    "송파구"
  ],
  "has_places": false
}

[Cassiiopeia]

1

{
"caption": "#블루보틀성수 -위치_서울시 성동구"
}

{
"place_names": [
"블루보틀성수"
],
"has_places": true
}

2

{
"caption": "송파구 맛집 추천"
}

{
"place_names": [
"송파구",
"맛집"
],
"has_places": false
}

3

{
"caption": "1. 스타벅스 2. 투썸플레이스"
}

{
"place_names": [
"스타벅스",
"투썸플레이스"
],
"has_places": true
}

4

{
"caption": "#사사노하 #멘야하나비"
}

{
"place_names": [
"사사노하",
"멘야하나비"
],
"has_places": false
}

[Cassiiopeia]

구현 보고서: 통합 테스트 API (Instagram → LLM → 네이버 지도)

---

📌 작업 개요

Instagram URL만 입력하면 자동으로 장소 정보를 추출하는 통합 파이프라인 테스트 API 구현

• Instagram 파싱 → caption 추출
• Ollama LLM으로 장소명 추출
• 각 장소명을 네이버 지도에서 검색
• 모든 정보를 통합하여 반환

엔드포인트: POST /api/test/integrated-place-search

---

🎯 구현 목표

1. Instagram 게시물에서 caption 추출
2. Ollama LLM(gemma3:1b-it-qat)으로 장소명 추출
3. 추출된 각 장소명을 네이버 지도에서 검색하여 상세 정보 획득
4. SNS 정보 + LLM 추출 결과 + 네이버 지도 정보를 통합 응답

---

✅ 구현 내용

응답 모델 추가

• 파일: src/models/integrated_search.py
• 변경 내용: SnsInfo, IntegratedPlaceSearchResponse Pydantic 모델 생성
• 이유: 통합 파이프라인의 구조화된 응답을 위한 타입 정의

통합 검색 엔드포인트 추가

• 파일: src/apis/test_router.py
• 변경 내용: /integrated-place-search POST 엔드포인트 추가
• 이유: 전체 파이프라인을 단일 API 호출로 테스트 가능하도록 구현

---

🔧 주요 변경사항 상세

SnsInfo 모델

Instagram 메타데이터를 담는 Pydantic 모델

class SnsInfo(BaseModel):
    platform: str           # "instagram"
    content_type: str       # "post", "reel", "igtv"
    url: str                # 원본 URL
    author: str | None      # 작성자
    caption: str | None     # 게시물 본문
    likes_count: int | None # 좋아요 수
    comments_count: int | None
    posted_at: str | None
    hashtags: list[str]
    og_image: str | None
    image_urls: list[str]
    author_profile_image_url: str | None

IntegratedPlaceSearchResponse 모델

통합 검색 결과를 담는 응답 모델

class IntegratedPlaceSearchResponse(BaseModel):
    sns_info: SnsInfo                    # SNS 메타데이터
    extracted_place_names: list[str]     # LLM 추출 장소명
    has_places: bool                     # 장소 존재 여부
    place_details: list[NaverPlaceInfo]  # 네이버 지도 검색 결과
    total_extracted: int                 # 추출된 장소 수
    total_found: int                     # 네이버에서 찾은 장소 수
    failed_searches: list[str]           # 검색 실패한 장소명

통합 검색 파이프라인 (5단계)

Step	작업	로깅
1/5	요청 수신	URL 로깅
2/5	Instagram 파싱	author, caption 길이 로깅
3/5	LLM 장소 추출	추출된 장소 수 로깅
4/5	네이버 지도 검색	각 검색 진행률 및 성공/실패 로깅
5/5	결과 통합	총 추출/발견 수 로깅

특이사항:

• 모든 로깅은 INFO 레벨 사용
• 각 로그에 [통합 검색] Step N/5: 접두사로 진행 상황 추적 가능
• 네이버 지도 검색은 개별 실패 허용 (failed_searches에 기록하고 계속 진행)

---

📦 파일 변경 목록

파일	작업
src/models/integrated_search.py	신규 생성
src/apis/test_router.py	엔드포인트 추가

---

🧪 테스트 및 검증

API 호출 예시

curl -X POST http://localhost:8001/api/test/integrated-place-search \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.instagram.com/p/ABC123/"}'

기대 응답

{
  "sns_info": {
    "platform": "instagram",
    "content_type": "post",
    "author": "jamsilism",
    "caption": "저장해두면 도움 되는 송파 판초밥 맛집4...",
    "likes_count": 7434,
    "hashtags": ["스시호", "사사노하", "맛집"]
  },
  "extracted_place_names": ["스시호", "사사노하", "김태완스시"],
  "has_places": true,
  "place_details": [
    {
      "place_id": "1234567",
      "name": "스시호",
      "category": "초밥,롤",
      "latitude": 37.5012,
      "longitude": 127.1234,
      "address": "서울 송파구 가락로 98길"
    }
  ],
  "total_extracted": 3,
  "total_found": 2,
  "failed_searches": ["김태완스시"]
}

로그 출력 예시

[통합 검색] Step 1/5: 요청 수신 - url=https://instagram.com/p/...
[통합 검색] Step 2/5: Instagram 파싱 시작
[통합 검색] Step 2/5: Instagram 파싱 완료 - author=jamsilism, caption 길이=234
[통합 검색] Step 3/5: LLM 장소 추출 시작 - caption 길이=234
[통합 검색] Step 3/5: LLM 장소 추출 완료 - 추출된 장소 수=3
[통합 검색] Step 4/5: 네이버 지도 검색 시작 - 검색할 장소 수=3
[통합 검색] Step 4/5: 네이버 지도 검색 (1/3) - query=스시호
[통합 검색] Step 4/5: 검색 성공 - 스시호 (1234567)
[통합 검색] Step 4/5: 네이버 지도 검색 (2/3) - query=사사노하
[통합 검색] Step 4/5: 검색 성공 - 사사노하 (2345678)
[통합 검색] Step 4/5: 네이버 지도 검색 (3/3) - query=김태완스시
[통합 검색] Step 4/5: 검색 실패 - query=김태완스시, error=...
[통합 검색] Step 4/5: 네이버 지도 검색 완료 - 성공=2, 실패=1
[통합 검색] Step 5/5: 결과 통합 완료 - 총 추출=3, 총 발견=2

---

📌 에러 처리 전략

단계	에러 상황	처리 방식
Instagram 파싱	실패	HTTPException(400) - 전체 중단
caption 없음	빈 caption	빈 결과 반환 (정상 응답)
LLM 추출	API 실패	빈 배열 반환 (기존 로직)
네이버 검색	개별 실패	failed_searches에 추가, 계속 진행

핵심 원칙: Instagram 파싱 실패만 전체 중단, 나머지는 부분 실패 허용

---

📌 참고사항

• 응답 시간: 네이버 지도 검색은 Playwright 브라우저 사용으로 장소당 약 5초 소요
• 순차 검색: Playwright 리소스 제한으로 병렬 검색 불가, 순차 처리
• 향후 개선: 브라우저 풀 구현으로 병렬 검색, 캐싱으로 중복 검색 방지 가능