지도 인식 AI 어시스턴트는 뷰포트, 선택 장소, 필터, 승인된 위치 같은 구조화된 지도 컨텍스트를 사용해 질문을 해석하고 근거 있는 답변과 지도 작업을 함께 반환하는 대화형 인터페이스입니다. 마커 배치, 결과 영역 맞춤, 지역 강조, 경로 요청, 선택 피처 포커스가 가능합니다. 네 가지 책임을 분리하세요. 호스트는 상태와 권한, 신뢰 시스템은 사실, 공간 도구는 지리 계산을 담당하며 AI 계층은 의도를 해석하고 지원되는 작업을 제안합니다.
아래에서는 공유 상태, 작업 어휘, 렌더러 어댑터, Kaleidr Chat 연결, 근거 설정, 흔한 실수를 다룹니다. 제품 정보는 Kaleidr Spatial AI를 확인하세요. SDK 구조는 AI 지도 SDK란?, 렌더러 마운트는 Mapbox, Google Maps, MapLibre의 AI 채팅, 자격 증명과 비공개 레코드는 지도 API 인증 및 AI 지도 워크플로의 비공개 위치 데이터를 참고하세요.
어시스턴트 핵심 사항
- 픽셀이 아니라 상태를 공유: 경계, 선택 ID, 필터, 결과 ID를 전달하고 모델이 지도를 이미지로 읽게 하지 마세요.
- 뷰포트는 컨텍스트: 사용자가 이 영역 검색을 요청하지 않았다면 보이는 경계는 순위에만 반영합니다.
- 의미 작업만 사용:
show_places또는fit_places를 출력하고 렌더러 JavaScript는 출력하지 마세요.- 발생 원인을 태그: 사용자 이동과 어시스턴트 카메라 이동이 모델을 다시 실행하지 않아야 합니다.
- 사실을 근거화: 영업시간, 식별 정보, 도형, 이동 시간은 권위 있는 시스템에서 가져옵니다.
지도 인식 AI 어시스턴트는 무엇이 다른가요?
지도 옆의 텍스트 전용 어시스턴트는 파리가 프랑스에 있다는 사실을 알 수 있습니다. 지도 인식 제품은 중심, 보이는 경계, 확대 수준, 선택 피처, 필터, 현재 경로, 이전 결과, 승인된 위치, 호스트 앱 상태 등 사용자가 지도에서 무엇을 하는지도 압니다. “이 중 호텔에서 가장 가까운 곳은?”은 계약 없이는 모호합니다. “이 중”은 현재 결과, “호텔”은 선택된 호텔이나 세션 출발점, “가까운”은 거리 또는 이동 시간 계산을 뜻합니다. 유용한 출력은 답변과 선택 장소, 지도 포커스, 이유를 함께 제공합니다.
기존 지도 검색은 카테고리, 반경, 현재 영업 같은 구조화된 컨트롤에서 시작합니다. “이 주변에서 고객 미팅에 적합하고 조용하며 오후 7시 이후에도 여는 카페”처럼 고정 필터로 표현하기 어려운 조건이 섞이면 대화가 유용합니다. AI는 카테고리, 지역, 선호, 시간, 용도를 해석합니다. 장소 식별, 영업시간, 도형, 이동 시간, 경로, 적격성은 결정론적 시스템이 계속 담당해야 합니다. 모델은 요청을 해석하는 데 쓰고 지리 사실의 유일한 출처로 사용하지 마세요.
| 기능 | 지도 옆 텍스트 어시스턴트 | 지도 인식 AI 어시스턴트 |
|---|---|---|
| 자연어 이해 | 예 | 예 |
| 보이는 지도 영역 인식 | 항상은 아님 | 제공하면 가능 |
| 선택 장소 인식 | 항상은 아님 | 예 |
| 현재 필터 사용 | 보통 안 함 | 가능 |
| 지도 작업 적용 | 보통 제한적 | 예 |
| 호스트 상태 공유 | 약함 | 명시적 |
공유 지도 상태를 어떻게 설계해야 하나요?
운영 루프는 사용자 질문, 호스트 컨텍스트 스냅샷, 의도 해석, 승인된 검색, 공간 계산, 근거 있는 답변, 검증된 지도 작업, 렌더러 업데이트입니다. 모델이 화면을 추론하길 기대하지 말고 명시적 상태 계약에서 시작하세요. 선택 피처 ID, 현재 결과 ID, 관련 필터, 필요할 때 보이는 경계, 경로 컨텍스트, 승인된 출발점, 상태 버전 등 현재 작업에 필요한 것만 포함합니다. 선택 장소는 오래된 결과 목록보다, 사용자가 지정한 목적지는 기본 출발점보다 우선한다는 규칙을 정하세요.
뷰포트를 숨은 하드 필터로 취급하지 마세요. 보이는 경계는 카메라 밖을 조용히 제외하지 않고 결과 순위를 조정할 수 있습니다. “두 번째 카페”가 지도 이동 후에도 같은 레코드를 가리키도록 대화 간 안정적인 장소 ID를 유지하세요. 식별과 생성 설명을 분리합니다. 호스트는 place_id와 원본 필드를 저장하고, 모델은 적합한 이유를 설명할 수 있지만 새 식별자를 만들면 안 됩니다.
양방향 상태는 단방향 채팅보다 강합니다. 이동, 확대, 선택, 필터는 사용자 이벤트로 태그된 호스트 저장소를 업데이트합니다. 장소 표시, 결과 맞춤, 장소 열기, 경로 표시는 검증과 어댑터를 거쳐 어시스턴트 이벤트로 태그됩니다. 다음 턴에 필요할 때만 새 스냅샷을 모델에 반환하세요. 루프 가드는 어시스턴트가 만든 카메라 이동이 자동으로 다음 모델 요청을 시작하지 않도록 합니다.
지도 작업을 렌더러와 독립적으로 유지하려면 어떻게 하나요?
장소 표시, 장소 맞춤, 장소 열기, 피처 강조, 경로 표시, 결과 지우기라는 작은 작업 어휘를 설계하세요. 각 작업을 스키마로 검증하고 객체 권한을 확인한 뒤 렌더러 어댑터에서 의미 카드를 Mapbox, Google Maps, MapLibre 호출로 변환합니다. 모델이 임의 JavaScript를 출력하게 하지 마세요. OWASP의 2025 프롬프트 인젝션 지침은 검색 또는 대화 콘텐츠가 도구 동작을 바꾸려 할 수 있다고 설명합니다. 모델이 조작되더라도 승인되지 않은 코드나 객체에 접근할 수 없어야 합니다.
임시 AI 결과 레이어와 영구 호스트 데이터를 분리해 대화를 지워도 저장된 장소가 삭제되지 않게 하세요. 결과 없음과 모호함은 가짜 마커가 아니라 명시적 빈 집합과 후속 질문으로 처리합니다. 순위는 승인된 필드로 설명 가능해야 합니다. 어시스턴트가 카메라 이동을 제안해도 이후 사용자 이동이 우선합니다. 대화 지연을 줄이기 위해 토큰은 스트리밍하고 장소가 해결될 때까지 카메라 이동을 미룹니다.
Kaleidr Chat은 기존 지도에 어떻게 연결되나요?
현재 Chat 문서에 따르면 SDK는 실행 중인 Mapbox, MapLibre, Google Maps 또는 Leaflet 지도에 연결하고, 해결된 장소를 표시하며, 대화가 위치를 해결할 때 카메라를 맞출 수 있습니다(Chat attach). 호스트는 계속 지도를 렌더링하고 Chat은 대화형 공간 계층을 추가합니다. Mapbox, Google Maps, MapLibre 가이드가 있습니다. 브라우저는 ai 범위의 게시 가능 키를 사용하며, 이를 오리진에 묶인 단기 세션으로 교환합니다(Auth & Scopes). 헤드리스 모드는 테스트나 채팅 전용 UI를 위해 map을 생략합니다. 현재 kaleidr.js를 로드하고 라이브 지도 객체가 만들어진 뒤 마운트하세요.
// myMap must already be a live supported map instance
const chatHandle = Kaleidr.mount("#map-chat", {
product: "chat",
publishableKey: "kld_pk_live_REPLACE_ME",
map: myMap,
enabled: true
});
비공개 비즈니스 데이터는 호스트 인증과 최소 검색 뒤에 둡니다(Endpoints). 사용자 위치는 동의 기반이어야 합니다. 불필요한 정밀 좌표나 대화 로그를 브라우저 또는 분석에 보내지 마세요. 권한 판단이 아니라 안정적인 공개 사실을 캐시하세요. 채팅 횟수만 세지 말고 장소 선택, 길찾기 열기, 부동산 후보 추가 같은 위치 작업 완료를 측정하세요. 출시 전에 공유 상태 경합, 지리적 모호성, 악의적 작업 페이로드를 테스트합니다.
팀이 피해야 할 실수는 무엇인가요?
| 실수 | 위험 | 더 나은 방법 |
|---|---|---|
| 상태를 모르는 지도 옆에 텍스트 어시스턴트 배치 | “이것”, “여기”가 모호함 | 구조화 지도 상태 공유 |
| 뷰포트를 숨은 필터로 사용 | 유효한 인근 결과 누락 | 요청하지 않으면 경계를 컨텍스트로 사용 |
| 모델이 렌더러 JavaScript 출력 | 인젝션과 공급업체 종속 | 의미 작업 + 어댑터 |
| 모든 카메라 이동에 모델 재실행 | 피드백 루프와 비용 | 출처 태그 + 루프 가드 |
| 글에서 장소 ID 생성 | 중복 또는 가짜 레코드 | 신뢰 데이터의 안정 ID |
| 첫 토큰에 카메라 이동 | 불안정한 지도 | 장소 해결을 기다림 |
| AI 레이어와 저장 데이터 혼합 | 우발적 삭제 | 임시 결과 레이어 분리 |
| 서버 키를 브라우저에 전송 | 자격 증명 도난 | 게시 가능 키 + ai 범위 |
| 결과 없음 상태 생략 | 가짜 마커 | 빈 집합 + 후속 질문 |
| 채팅 양만 측정 | 허영 지표 | 지도 작업 완료 측정 |
최종 결론
지도 인식 AI 어시스턴트는 대화와 라이브 지도가 명시적 상태 및 작업 계약을 공유할 때 작동합니다. 호스트는 권한과 렌더러 호출, 신뢰 시스템은 식별과 운영 사실, 공간 엔진은 거리·경로·도형을 담당합니다. 언어 모델은 그 경계 안에서 의도를 해석하고 순위를 조정하며 결과를 설명합니다. Kaleidr Chat은 게시 가능 브라우저 키와 Mapbox, Google Maps, MapLibre 가이드를 사용해 호스트가 이미 렌더링하는 지도에 대화 계층을 연결합니다. 상태 계약을 먼저 설계하세요. 채팅 패널은 마지막 화면이지 아키텍처가 아닙니다.
기존 지도에 AI 채팅 추가하기
Kaleidr Chat을 실행 중인 Mapbox, Google Maps, MapLibre 또는 Leaflet 지도에 연결하고 호스트를 공식 렌더러로 유지하세요. 마운트 옵션, 헤드리스 테스트, 현재 키 범위는 **Kaleidr Chat 문서**를 확인하세요.
자주 묻는 질문
지도 인식 AI 어시스턴트란 무엇인가요?
선택 장소, 보이는 영역, 필터, 출발점 같은 구조화 지도 컨텍스트를 받아 근거 있는 결과와 지원되는 지도 작업을 반환하는 대화형 인터페이스입니다.
텍스트 전용 어시스턴트와 어떻게 다른가요?
텍스트 어시스턴트는 주로 글을 교환합니다. 지도 인식 어시스턴트는 상태를 공유하고 지리 검색, 공간 계산, 마커, 카메라, 경로, 선택을 조정합니다.
AI가 지도를 이미지로 읽어야 하나요?
애플리케이션 상태에는 보통 아닙니다. 경계, 피처 ID, 필터, 결과 ID를 제공하세요. 시각 이해가 다른 흐름에 유용할 수 있지만 상태는 명시적이어야 합니다.
현재 뷰포트가 검색 결과를 항상 제한해야 하나요?
아닙니다. 하드 필터가 아닌 컨텍스트로 쓸 수 있습니다. 사용자나 제품이 “이 영역 검색”을 명시한 경우만 경계로 사용하세요.
어시스턴트는 어떤 지도 상태를 알아야 하나요?
선택 피처, 결과 ID, 관련 필터, 필요할 때 보이는 경계, 경로 컨텍스트, 승인된 출발점 등 현재 작업에 필요한 것만 알면 됩니다.
AI는 지도를 어떻게 제어해야 하나요?
show_places, fit_places, open_place, show_route 같은 작은 구조화 작업 어휘를 검증하고 호스트에서 변환하세요.
모델이 Mapbox나 Google Maps JavaScript를 출력해야 하나요?
주요 제어 방식으로는 안 됩니다. 의미 작업이 더 안전하고 렌더러에 독립적입니다.
비공개 비즈니스 데이터를 사용할 수 있나요?
호스트가 사용자를 인증하고 테넌트, 객체, 필드 권한을 적용하며 필요한 승인 레코드만 검색한다면 가능합니다.
Kaleidr Chat을 기존 지도에 연결할 수 있나요?
예. 실시간 Mapbox, MapLibre, Google Maps 또는 Leaflet 지도에 연결해 장소를 표시하고 카메라를 맞출 수 있습니다.
Kaleidr Chat이 지도 렌더러를 대체하나요?
아닙니다. 호스트가 계속 렌더링하고 Chat은 대화형 공간 계층을 추가합니다.
브라우저에서 어떤 키를 사용하나요?
ai 범위의 게시 가능 키를 사용하고 오리진에 묶인 단기 세션으로 교환합니다.
지도 없이도 작동하나요?
대화 계층은 가능합니다. map을 생략하는 헤드리스 모드는 테스트나 채팅 전용 UI에 유용합니다.
어떻게 측정해야 하나요?
장소 선택·저장, 길찾기 열기, 부동산 후보 추가, 매장 선택, 예약 완료 등 유용한 위치 작업 완료를 측정하세요.
참고 자료
- Kaleidr. AI Maps You Can Talk To — Spatial AI. 2026년 8월 20일 확인. https://kaleidr.com/ai
- Kaleidr. Attach Kaleidr AI to a Google Map. Kaleidr Developer Docs. 2026년 8월 20일 확인. https://docs.kaleidr.com/guides/attach-ai-to-google-maps
- Kaleidr. Attach Kaleidr AI to a Mapbox Map. Kaleidr Developer Docs. 2026년 8월 20일 확인. https://docs.kaleidr.com/guides/attach-ai-to-mapbox
- Kaleidr. Attach Kaleidr AI to a MapLibre Map. Kaleidr Developer Docs. 2026년 8월 20일 확인. https://docs.kaleidr.com/guides/attach-ai-to-maplibre
- Kaleidr. Auth & Scopes. Kaleidr Developer Docs. 2026년 8월 20일 확인. https://docs.kaleidr.com/platform-api/auth-and-scopes
- Kaleidr. Chat — Attach AI to Your Map. Kaleidr Developer Docs. 2026년 8월 20일 확인. https://docs.kaleidr.com/sdk/chat-attach
- Kaleidr. Endpoints. Kaleidr Developer Docs. 2026년 8월 20일 확인. https://docs.kaleidr.com/platform-api/endpoints
- Kaleidr. kaleidr.js — the Loader. Kaleidr Developer Docs. 2026년 8월 20일 확인. https://docs.kaleidr.com/sdk/kaleidr-js
- Google. Load the Maps JavaScript API. Google Maps Platform documentation. 2026년 8월 20일 확인. https://developers.google.com/maps/documentation/javascript/load-maps-js-api
- Mapbox. Get started with Mapbox GL JS using a CDN. Mapbox GL JS documentation. 2026년 8월 20일 확인. https://docs.mapbox.com/mapbox-gl-js/guides/get-started/use-with-cdn/
- MapLibre. Display a map. MapLibre GL JS documentation. 2026년 8월 20일 확인. https://maplibre.org/maplibre-gl-js/docs/examples/display-a-map/
- OWASP Gen AI Security Project. LLM01:2025 Prompt Injection. 2026년 8월 20일 확인. https://genai.owasp.org/llmrisk/llm01-prompt-injection/
@misc{kaleidr_chat_attach_2026,
title = {Chat -- Attach AI to Your Map},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 20 August 2026},
url = {https://docs.kaleidr.com/sdk/chat-attach}
}
@misc{kaleidr_spatial_ai_2026,
title = {AI Maps You Can Talk To -- Spatial AI},
author = {{Kaleidr}},
note = {Accessed 20 August 2026},
url = {https://kaleidr.com/ai}
}
@misc{kaleidr_auth_scopes_2026,
title = {Auth and Scopes},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 20 August 2026},
url = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}
@misc{kaleidr_attach_mapbox_2026,
title = {Attach Kaleidr AI to a Mapbox Map},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 20 August 2026},
url = {https://docs.kaleidr.com/guides/attach-ai-to-mapbox}
}
@misc{kaleidr_attach_google_2026,
title = {Attach Kaleidr AI to a Google Map},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 20 August 2026},
url = {https://docs.kaleidr.com/guides/attach-ai-to-google-maps}
}
@misc{kaleidr_attach_maplibre_2026,
title = {Attach Kaleidr AI to a MapLibre Map},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 20 August 2026},
url = {https://docs.kaleidr.com/guides/attach-ai-to-maplibre}
}
@misc{kaleidr_endpoints_2026,
title = {Endpoints},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 20 August 2026},
url = {https://docs.kaleidr.com/platform-api/endpoints}
}
@misc{kaleidr_js_loader_2026,
title = {kaleidr.js -- the Loader},
author = {{Kaleidr}},
note = {Kaleidr Developer Docs; accessed 20 August 2026},
url = {https://docs.kaleidr.com/sdk/kaleidr-js}
}
@misc{google_maps_js_loader_2026,
title = {Load the Maps JavaScript API},
author = {{Google}},
note = {Google Maps Platform documentation; accessed 20 August 2026},
url = {https://developers.google.com/maps/documentation/javascript/load-maps-js-api}
}
@misc{mapbox_cdn_guide_2026,
title = {Get started with Mapbox GL JS using a CDN},
author = {{Mapbox}},
note = {Mapbox GL JS documentation; accessed 20 August 2026},
url = {https://docs.mapbox.com/mapbox-gl-js/guides/get-started/use-with-cdn/}
}
@misc{maplibre_display_map_2026,
title = {Display a map},
author = {{MapLibre}},
note = {MapLibre GL JS documentation; accessed 20 August 2026},
url = {https://maplibre.org/maplibre-gl-js/docs/examples/display-a-map/}
}
@misc{owasp_llm01_prompt_injection_2025,
title = {LLM01:2025 Prompt Injection},
author = {{OWASP Gen AI Security Project}},
note = {Accessed 20 August 2026},
url = {https://genai.owasp.org/llmrisk/llm01-prompt-injection/}
}