Установка и настройка¶
Плагин требует QGIS 4.0 или новее. На QGIS 3.x он не работает: сборка 3.40 LTR под macOS несёт Python 3.9, а код использует синтаксис аннотаций из Python 3.10.
1. Установка из zip¶
Для опубликованной версии скачайте файл ai_agent-<версия>.zip из
последнего релиза GitHub.
Не выбирайте автоматически созданные GitHub архивы «Source code»: имя верхней
папки в них не подходит для плагина QGIS.
Чтобы вместо этого собрать релизный архив из рабочей копии, выполните:
python3 tools/build_plugin.py
Он кладёт dist/ai_agent-<версия>.zip — ровно в том виде, который ждёт QGIS:
одна папка ai_agent/ внутри архива.
Дальше в QGIS: Модули → Управление модулями → Установить из ZIP, выбрать файл, нажать Установить модуль. После установки в меню появится AI Agent.
Скачивать zip кнопкой «Code → Download ZIP» на GitHub нельзя: архив
распаковывается папкой qgis-ai-agent-main, а имя папки задаёт имя пакета Python —
с дефисом плагин не загрузится.
2. Ключ и адрес API¶
Плагин работает с любым OpenAI-совместимым эндпоинтом. Откройте панель плагина и нажмите шестерёнку:
| Поле | Что вводить |
|---|---|
| Базовый URL API | адрес без /chat/completions — плагин допишет сам |
| Модель | идентификатор модели у вашего провайдера |
| API-ключ | хранится в базе учётных данных QGIS, а не в конфиге QGIS |
| Формат API | auto — определяется по адресу; openai или anthropic вручную |
| Тип авторизации | Bearer для большинства сервисов, OAuth для корпоративных шлюзов |
| Проверять SSL-сертификат | снимать только для внутреннего шлюза с самоподписанным сертификатом |
Кнопка Проверить подключение шлёт один короткий запрос и показывает ответ модели — так видно, что URL, ключ и имя модели согласуются между собой.
Отправка запроса передаёт настроенному эндпоинту ваш текст и базовые метаданные проекта. Разрешить конфиденциальные ГИС-данные — отдельное, по умолчанию выключенное разрешение на передачу значений атрибутов, точных экстентов карты и слоёв, фильтров и источников слоёв, категорий стилей, результатов Processing и Python, а также изображений карты и макета.
По умолчанию геокодирование выключено. В карточке Геокодирование выберите Демо Photon (разумная нагрузка) для редких интерактивных запросов или Свой Nominatim и укажите разрешённый публичный базовый HTTPS-адрес. Модель получает только аргумент с названием места и не может выбрать или заменить этот адрес. Каждый запрос по-прежнему ждёт отдельного подтверждения кнопкой Применить.
Проверенные провайдеры¶
Плагин говорит на двух форматах. auto выбирает по адресу, так что обычно
достаточно вставить URL, ключ и имя модели.
| Провайдер | Базовый URL | Формат |
|---|---|---|
| OpenAI | https://api.openai.com/v1 |
openai |
| OpenRouter | https://openrouter.ai/api/v1 |
openai |
| Anthropic | https://api.anthropic.com/v1 |
anthropic |
| Google Gemini | https://generativelanguage.googleapis.com/v1beta/openai |
openai |
| DeepSeek | https://api.deepseek.com/v1 |
openai |
| Groq | https://api.groq.com/openai/v1 |
openai |
| Mistral | https://api.mistral.ai/v1 |
openai |
| Together, Fireworks, Cerebras | адрес из их документации | openai |
OpenRouter даёт доступ к моделям почти всех вендоров через один ключ и один адрес — включая Claude и Gemini, — и для плагина остаётся обычным OpenAI-совместимым сервисом. Ставить формат вручную нужно только для шлюза, который говорит на формате Anthropic с нестандартного адреса.
Локальная модель — без ключа и без счетов¶
Для адреса на localhost ключ не требуется: поле можно оставить пустым.
Так подключаются Ollama, LM Studio, llama.cpp и любой другой сервер с
OpenAI-совместимым API.
| Сервер | Базовый URL |
|---|---|
| Ollama | http://localhost:11434/v1 |
| LM Studio | http://localhost:1234/v1 |
| llama.cpp server | http://localhost:8080/v1 |
Плагин считает эти адреса локальными, но это не гарантирует, что сервер оставит данные на этом устройстве. Проверьте, хранит ли он запросы или пересылает их.
Учтите: агент работает циклом с 65 инструментами, и небольшая модель на 7–8 миллиардов параметров будет путаться в вызовах. Осмысленный минимум — модель уровня 30B с поддержкой function calling.
Агентный цикл вызывает инструменты, поэтому модель должна уметь function calling. Если эндпоинт его не поддерживает, плагин сам переключится на текстовый JSON-протокол и запомнит выбор для этого URL.
3. Зависимости¶
Их нет. Плагину не нужно ничего, кроме самого QGIS: поставили архив — он работает. Ключи лежат в базе учётных данных QGIS, так что для их хранения не требуется никакая внешняя Python-библиотека.
Сетевые запросы остаются в сетевом стеке QGIS: обычные вызовы используют
QgsBlockingNetworkRequest, а стриминг и веб-транспорт с закреплением адреса —
QgsNetworkAccessManager с вложенным циклом событий. Последний принимает только
публичные ответы DNS, закрепляет проверенные IP на прямом маршруте при проверке
исходного TLS-имени, сохраняет имя хоста через явный прокси QGIS и следует только
редиректам в рамках origin. Сторонний HTTP-клиент не нужен; несовпадение прямых
маршрутов блокируется, а не обходится.
При первом сохранении ключа QGIS попросит мастер-пароль — тот же, которым он защищает пароли к слоям и PostGIS. Если закрыть этот диалог, ключ останется закрытым, и окно настроек об этом скажет.
До подключения проекта к удалённому провайдеру прочитайте раздел «Данные и конфиденциальность». Результаты инструментов могут содержать значения атрибутов, точные экстенты карты и слоёв, фильтры и источники слоёв, категории стилей, результаты Processing или Python, а также изображения карты и макета, а не только основные метаданные схемы.
4. Установка для разработки¶
Чтобы не пересобирать архив на каждую правку, поставьте симлинк из репозитория в каталог плагинов профиля.
Путь к каталогу: Установки → Профили пользователя → Открыть папку активного
профиля, далее python/plugins.
PLUGINS_DIR="$HOME/Library/Application Support/QGIS/QGIS4/profiles/default/python/plugins"
mkdir -p "$PLUGINS_DIR"
ln -sfn "$(pwd)/ai_agent" "$PLUGINS_DIR/ai_agent"
Ссылка ведёт на папку пакета, а не на корень репозитория: в QGIS попадает только плагин, без tests и docs. Если симлинк стоял на корень репозитория со времён старой структуры — пересоздайте его этой командой, иначе QGIS перестанет видеть плагин.
При правках кода перезагружайте плагин через Plugin Reloader (Ctrl+F5). Если
менялась структура пакетов, нужен полный перезапуск QGIS: снятие галочки не
выгружает подмодули из sys.modules. Консоль Python держит свой кэш, сбросить его
можно так:
import sys; [sys.modules.pop(n) for n in list(sys.modules) if n.startswith("ai_agent")]
5. Проверка¶
python3 -m unittest discover -s tests -t .
Команда выше запускает быстрый модульный набор и использует заглушки QGIS, когда PyQGIS недоступен. В CI отдельно выполняется сфокусированный smoke-тест импорта, иконки и реестров в официальном контейнере QGIS 4. Полные сценарии с живыми слоями и интерфейсом QGIS проверяются вручную по smoke_checklist.md.