Настройка 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 из-за временных всплесков использования памяти.

Использование удаленного 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 (Text Generation Inference). 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: 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, пожалуйста, поддержите сообщество, заполнив эту документацию любыми недостающими деталями.

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

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