Перейти к содержанию

Настройка 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, необходимо выполнить три шага:

  1. Установить необходимые зависимости,
  2. Включить семантический поиск,
  3. Настроить поставщика 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 из-за временных всплесков использования памяти.

Использование удаленного API встраивания

В качестве альтернативы запуску локальной модели Sentence Transformers вы можете использовать удаленный API встраивания, совместимый с OpenAI, для семантического поиска. Это полезно, если вы хотите разгрузить вычисление встраиваний на отдельный сервис (например, Ollama), использовать облачного поставщика встраиваний (например, OpenAI) или избежать загрузки библиотек Sentence Transformers и PyTorch в память.

Удаленный API должен быть совместим с конечной точкой встраиваний OpenAI (/v1/embeddings).

Чтобы использовать удаленный API встраивания, установите следующие параметры конфигурации (см. Конфигурация сервера):

Ключ Описание
VECTOR_EMBEDDING_MODEL Имя модели, которое передается удаленному поставщику
VECTOR_EMBEDDING_BASE_URL Базовый URL удаленного API
VECTOR_EMBEDDING_API_KEY API ключ (требуется только если поставщик требует аутентификации)

Использование Ollama для встраиваний

При развертывании Gramps Web с помощью Docker Compose вы можете добавить сервис Ollama и использовать его как для встраиваний, так и (по желанию) для LLM:

services:
  grampsweb: &grampsweb
    # ... существующая конфигурация ...
    environment:
      GRAMPSWEB_VECTOR_EMBEDDING_MODEL: nomic-embed-text
      GRAMPSWEB_VECTOR_EMBEDDING_BASE_URL: http://ollama:11434

  grampsweb_celery: &grampsweb_celery
    # ... существующая конфигурация ...
    environment:
      GRAMPSWEB_VECTOR_EMBEDDING_MODEL: nomic-embed-text
      GRAMPSWEB_VECTOR_EMBEDDING_BASE_URL: http://ollama:11434

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

volumes:
  ollama_data:

После запуска сервисов загрузите модель встраивания в Ollama:

docker compose exec ollama ollama pull nomic-embed-text

Info

При использовании Ollama для встраиваний библиотеки Sentence Transformers и PyTorch не требуются, что значительно снижает использование памяти рабочих процессов Gramps Web API.

Использование OpenAI для встраиваний

Чтобы использовать API встраиваний OpenAI, установите базовый URL на API OpenAI и предоставьте свой API ключ:

environment:
  GRAMPSWEB_VECTOR_EMBEDDING_MODEL: text-embedding-3-small
  GRAMPSWEB_VECTOR_EMBEDDING_BASE_URL: https://api.openai.com
  GRAMPSWEB_VECTOR_EMBEDDING_API_KEY: sk-...

Warning

Изменение модели встраивания требует переиндексации всех записей для вашего дерева (или всех деревьев в многодеревной настройке), так как разные модели производят векторы с разными размерами.

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

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

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

При использовании API OpenAI 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: ваш-api-ключ-mistral-здесь
  GRAMPSWEB_VECTOR_EMBEDDING_MODEL: sentence-transformers/distiluse-base-multilingual-cased-v2

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

Ollama — удобный способ запускать LLM локально. Пожалуйста, обратитесь к документации Ollama для получения подробностей. Обратите внимание, что LLM требуют значительных вычислительных ресурсов, и все, кроме самых маленьких моделей, вероятно, будут слишком медленными без поддержки GPU. Поскольку помощник полагается на вызов инструментов, выберите модель, которая поддерживает инструменты, такие как qwen2.5. Начните с небольшой вариации, такой как qwen2.5:7b, и попробуйте более крупную, если ответы недостаточно хороши. Пожалуйста, делитесь любым опытом с сообществом!

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

services:
  grampsweb: &grampsweb
    # ... существующая конфигурация ...
    environment:
      GRAMPSWEB_LLM_MODEL: ollama:qwen2.5:7b
      GRAMPSWEB_LLM_BASE_URL: http://ollama:11434/v1/

  grampsweb_celery: &grampsweb_celery
    # ... существующая конфигурация ...
    environment:
      GRAMPSWEB_LLM_MODEL: ollama:qwen2.5:7b
      GRAMPSWEB_LLM_BASE_URL: http://ollama:11434/v1/

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

volumes:
  ollama_data:

После запуска сервисов загрузите модель в Ollama:

docker compose exec ollama ollama pull qwen2.5:7b

Несколько моментов, которые следует отметить:

  • Установите LLM_MODEL на имя модели Ollama, включая ее тег (часть после двоеточия, например, 7b), префиксируя его ollama:. Префикс заставляет Pydantic AI использовать его специфические настройки для модели Ollama, что является рекомендуемой настройкой.
  • LLM_BASE_URL должен заканчиваться на /v1/, например, http://ollama:11434/v1/.
  • С префиксом ollama: ни OPENAI_API_KEY, ни переменная окружения OLLAMA_BASE_URL не нужны. Если LLM_BASE_URL не установлен, Gramps Web возвращается к OLLAMA_BASE_URL.
  • В качестве альтернативы вы можете оставить префикс (например, LLM_MODEL: qwen2.5:7b) и использовать Ollama через его общий API, совместимый с OpenAI. В этом случае вам также нужно будет установить переменную окружения OPENAI_API_KEY на ollama (любое ненулевое значение подойдет).

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

Info

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

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

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