Настройка AI чата¶

Info

AI чат требует Gramps Web API версии 2.5.0 или выше. Версия 3.6.0 представила возможности вызова инструментов для более интеллектуальных взаимодействий.

Gramps Web API поддерживает задавание вопросов о генеалогической базе данных с использованием больших языковых моделей (LLM) через технику, называемую генерацией с дополнением извлечения (RAG), в сочетании с вызовом инструментов.

Как это работает¶

AI помощник использует два взаимодополняющих подхода:

Генерация с дополнением извлечения (RAG): векторная модель встраивания создает индекс всех объектов в базе данных Gramps в виде числовых векторов, которые кодируют значение объектов. Когда пользователь задает вопрос, этот вопрос также преобразуется в вектор и сравнивается с объектами в базе данных. Этот семантический поиск возвращает объекты, которые наиболее семантически схожи с вопросом.

Вызов инструментов (v3.6.0+): AI помощник теперь может использовать специализированные инструменты для прямого запроса ваших генеалогических данных. Эти инструменты позволяют помощнику искать в базе данных, фильтровать людей/события/семьи/места по конкретным критериям, вычислять отношения между индивидами и извлекать подробную информацию об объектах. Это делает помощника гораздо более способным точно отвечать на сложные генеалогические вопросы.

Для включения конечной точки чата в Gramps Web API необходимо выполнить три шага:

Установить необходимые зависимости,
Включить семантический поиск,
Настроить поставщика LLM.

Три шага описаны ниже по порядку. Наконец, владелец или администратор должен настроить, какие пользователи могут получить доступ к функции чата в настройках управления пользователями.

Установка необходимых зависимостей¶

AI чат требует установки библиотек Sentence Transformers и PyTorch.

Стандартные образы Docker для Gramps Web уже имеют их предустановленными для архитектур amd64 (например, 64-битный настольный ПК) и arm64 (например, 64-битный Raspberry Pi). К сожалению, AI чат не поддерживается на архитектуре armv7 (например, 32-битный Raspberry Pi) из-за отсутствия поддержки PyTorch.

При установке Gramps Web API через pip (это не требуется при использовании образов Docker) необходимые зависимости устанавливаются с помощью

pip install gramps_webapi[ai]

Включение семантического поиска¶

Если необходимые зависимости установлены, включение семантического поиска может быть таким же простым, как установка параметра конфигурации VECTOR_EMBEDDING_MODEL (например, установив переменную окружения GRAMPSWEB_VECTOR_EMBEDDING_MODEL), см. Конфигурация сервера. Это может быть любая строка модели, поддерживаемой библиотекой Sentence Transformers. См. документацию этого проекта для получения подробностей и доступных моделей.

Warning

Обратите внимание, что стандартные образы Docker не включают версию PyTorch с поддержкой GPU. Если у вас есть доступ к GPU (что значительно ускорит семантическую индексацию), пожалуйста, установите версию PyTorch с поддержкой GPU.

Существует несколько соображений при выборе модели.

Когда вы меняете модель, вам нужно вручную воссоздать индекс семантического поиска для вашего дерева (или всех деревьев в многодревесной настройке), в противном случае вы столкнетесь с ошибками или бессмысленными результатами. Gramps Web обнаруживает, когда настроенная модель встраивания больше не соответствует существующему индексу, и показывает постоянное уведомление администраторам, побуждая их инициировать полную переиндексацию из Настроек администрирования.
Модели представляют собой компромисс между точностью/универсальностью с одной стороны и вычислительным временем/объемом памяти с другой. Если вы не запускаете Gramps Web API на системе с доступом к мощному GPU, более крупные модели обычно слишком медленны на практике.
Если ваша вся база данных не на английском языке и все ваши пользователи не ожидаются, чтобы задавать вопросы в чате только на английском, вам потребуется многоязычная модель встраивания, которые встречаются реже, чем чисто английские модели.

Если модель отсутствует в локальном кэше, она будет загружена при первом запуске Gramps Web API с новой конфигурацией. Модель sentence-transformers/distiluse-base-multilingual-cased-v2 уже доступна локально при использовании стандартных образов Docker. Эта модель является хорошей отправной точкой и поддерживает многоязычный ввод.

Пожалуйста, делитесь знаниями о различных моделях с сообществом!

Info

Библиотека sentence transformers потребляет значительное количество памяти, что может привести к завершению работы рабочих процессов. Как правило, при включенном семантическом поиске каждый рабочий процесс Gunicorn потребляет около 200 МБ памяти, а каждый рабочий процесс celery — около 500 МБ памяти даже в бездействии и до 1 ГБ при вычислении встраиваний. См. Ограничение использования CPU и памяти для настроек, которые ограничивают использование памяти. Кроме того, рекомендуется выделить достаточно большой раздел подкачки, чтобы предотвратить ошибки OOM из-за временных всплесков использования памяти.

Настройка поставщика LLM¶

Связь с LLM использует фреймворк Pydantic AI, который поддерживает совместимые с OpenAI API. Это позволяет использовать локально развернутый LLM через Ollama (см. Совместимость Ollama с OpenAI) или хостинг API, такие как OpenAI, Anthropic или Hugging Face TGI (Text Generation Inference). LLM настраивается через параметры конфигурации LLM_MODEL и LLM_BASE_URL.

Использование хостируемого LLM через OpenAI API¶

При использовании OpenAI API LLM_BASE_URL можно оставить неустановленным, в то время как LLM_MODEL должен быть установлен на одну из моделей OpenAI, например, gpt-4o-mini. LLM использует как RAG, так и вызов инструментов для ответа на вопросы: он выбирает релевантную информацию из результатов семантического поиска и может напрямую запрашивать базу данных с помощью специализированных инструментов. Он не требует глубоких генеалогических или исторических знаний. Поэтому вы можете попробовать, достаточно ли небольшой/дешевой модели.

Вам также нужно будет зарегистрироваться, получить API-ключ и сохранить его в переменной окружения OPENAI_API_KEY.

Info

LLM_MODEL является параметром конфигурации; если вы хотите установить его через переменную окружения, используйте GRAMPSWEB_LLM_MODEL (см. Конфигурация). OPENAI_API_KEY не является параметром конфигурации, а переменной окружения, непосредственно используемой библиотекой Pydantic AI, поэтому ее не следует префиксировать.

Использование Mistral AI¶

Чтобы использовать хостируемые модели Mistral AI, добавьте префикс mistral: к имени модели при установке LLM_MODEL.

Вам нужно будет зарегистрироваться для получения учетной записи Mistral AI, получить API-ключ и сохранить его в переменной окружения MISTRAL_API_KEY. Не нужно устанавливать LLM_BASE_URL, так как Pydantic AI автоматически использует правильный конечный пункт API Mistral.

Пример конфигурации при использовании docker compose с переменными окружения:

environment:
  GRAMPSWEB_LLM_MODEL: mistral:mistral-large-latest
  MISTRAL_API_KEY: your-mistral-api-key-here
  GRAMPSWEB_VECTOR_EMBEDDING_MODEL: sentence-transformers/distiluse-base-multilingual-cased-v2

Использование локального LLM через Ollama¶

Ollama — это удобный способ запускать LLM локально. Пожалуйста, обратитесь к документации Ollama для получения подробностей. Обратите внимание, что LLM требуют значительных вычислительных ресурсов, и все, кроме самых маленьких моделей, вероятно, будут слишком медленными без поддержки GPU. Вы можете попробовать, соответствует ли tinyllama вашим потребностям. Если нет, попробуйте одну из более крупных моделей. Пожалуйста, делитесь любым опытом с сообществом!

При развертывании Gramps Web с помощью Docker Compose вы можете добавить сервис Ollama

services:
  ollama:
    image: ollama/ollama
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama

volumes:
    ollama_data:

и затем установить параметр конфигурации LLM_BASE_URL на http://ollama:11434/v1. Установите LLM_MODEL на модель, поддерживаемую Ollama, и загрузите ее в ваш контейнер с помощью ollama pull <model>. Наконец, установите OPENAI_API_KEY на ollama.

Чтобы устранить проблемы с Ollama, вы можете включить отладочный логгирование, установив переменную окружения OLLAMA_DEBUG=1 в окружении сервиса Ollama.

Info

Если вы используете Ollama для AI чата Gramps Web, пожалуйста, поддержите сообщество, заполнив эту документацию любыми недостающими деталями.

Использование других поставщиков¶

Пожалуйста, не стесняйтесь предоставлять документацию для других поставщиков и делиться своим опытом с сообществом!