문서
설치
QGIS AI 는 커스텀 플러그인 저장소를 통해 설치·업그레이드됩니다. QGIS에 저장소 URL을 한 번만 등록하면, 호환되는 새 릴리스는 플러그인 관리자의 업그레이드 가능 탭에 자동으로 나타납니다 — 버튼 한 번이면 설치.
현재 배포본은 QGIS 3.28~3.99 를 지원합니다. QGIS 4.x용 배포본은 아직 제공하지 않습니다. 최신 플러그인 버전은 3.11.32입니다.
최초 설치 (저장소 1회 등록)
1단계. 플러그인 저장소 추가
- QGIS에서 플러그인 → 플러그인 관리 및 설치… 열기
- 왼쪽 설정(Settings) 탭으로 이동
- 플러그인 저장소 아래 추가… 클릭
- 아래 내용 입력 후 확인:
- 이름:
QGIS AI - URL:
https://qgis.ai/plugins.xml - 활성화: 체크
- 이름:
2단계. 플러그인 설치
- 같은 창에서 전체 플러그인 탭으로 전환
- 검색창에
QAI(또는QGIS AI) 입력 - QAI 선택 후 플러그인 설치 클릭
- 설치가 끝나면 대화창 닫기
3단계. 어시스턴트 열기
QGIS 툴바에서 AI Assistant 아이콘을 클릭하면 먼저 필수 참여계약 화면이 열립니다. AGORA에 참여하고 시작을 한 번 누르면 서비스 이용약관과 코드 기여 라이선스를 함께 수락합니다. 거부하면 채팅·설정·스킬·온라인 기능을 포함한 QAI 전체가 열리지 않습니다.
참여 후 설정 화면에서 Google OAuth 계정을 선택하세요. 이는 두 번째 동의가 아니라 참여 증빙과 코드 기여를 현재 계정·기기에 귀속하는 필수 단계입니다. 귀속을 마치면 채팅·스킬을 사용할 수 있고 VWorld API 키도 자동 발급됩니다. 재사용 가능한 성공 PyQGIS 코드는 AGORA에 필수 기여됩니다. 오류·사용 패턴 진단은 별도 선택 기능으로 새 프로필의 최초 참여에서 ON으로 시작하며, 설정에서 언제든 끌 수 있고 기존 선택은 유지됩니다.
업그레이드 — 클릭 한 번
새 버전이 배포되면 QGIS 시작 시 플러그인 관리자에 업그레이드 가능 배지가 표시됩니다.
- 플러그인 → 플러그인 관리 및 설치 → 업그레이드 가능 열기
- QAI 선택 후 플러그인 업그레이드 클릭
- 설치가 끝나면 QGIS를 재시작해 새 버전을 로드합니다
사이트 계정, 피드백 DB, Google 인증 토큰, API 키 캐시는 업그레이드 시
유지됩니다. v3.4.0 이후 사용자 데이터는 QGIS 프로필 디렉토리
(QgsApplication.qgisSettingsDirPath()/qgis_ai_assistant/) 에 저장되므로,
플러그인 폴더를 교체해도 데이터는 영향을 받지 않습니다.
3.3.x → 3.4.0 마이그레이션
구 플러그인 폴더 내부에 있던 DB(sites_credentials.db,
feedback_learning.db 등)는 3.4.0 최초 로드 시 새 외부 경로로 자동
복사됩니다. 이후 업그레이드에서는 별도 조치가 필요하지 않습니다.
수동 ZIP 설치 (네트워크 제한 환경)
저장소 URL 접근이 차단된 네트워크라면 다운로드 페이지 에서 최신 ZIP을 받아 플러그인 → 플러그인 관리 및 설치 → ZIP에서 설치 로 설치하세요. v3.4.0 이후 사용자 데이터는 이 방식에서도 QGIS 프로필 위치로 자동 마이그레이션됩니다.
시스템 요구 사항
- QGIS 3.28~3.99 (현재 QGIS 4.x 미지원)
- macOS 12+, Windows 10+, 또는 최신 Linux 배포판
- 최초 AGORA 참여와 Google 계정 귀속 시 인터넷 연결 필요
문제 해결
“저장소 URL을 추가했는데 플러그인이 목록에 안 보입니다.” — 플러그인 관리자 설정 탭에서 저장소가 활성화됨 상태인지 확인하세요. 모든 저장소 옆 새로 고침 버튼을 한 번 눌러 주세요.
“업그레이드 버튼이 뜨지 않습니다.” — 이미 최신 버전이거나 저장소
상태가 연결 오류 일 수 있습니다. URL이 정확히
https://qgis.ai/plugins.xml 인지 다시 확인하세요.
어시스턴트 도크가 보이지 않습니다. — QGIS를 재시작하고 보기 → 패널 → AI Assistant 로 활성화하세요.
참여를 거부했더니 QAI가 보이지 않습니다. — 정상 동작입니다. QAI를 사용하려면 AI Assistant 아이콘을 다시 눌러 AGORA에 참여하고 시작을 선택하고 Google 계정 귀속을 완료하세요. 참여 철회 뒤 기존 기여 권리를 행사하려면 lloa9000@gmail.com으로 요청하세요.
그 외 문의 — FAQ 를 참고하세요.