Налаштування 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, ви можете використовувати віддалений OpenAI-сумісний API вбудовування для семантичного пошуку. Це корисно, якщо ви хочете перенести обчислення вбудовування на окремий сервіс (наприклад, 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, будь ласка, підтримайте громаду, заповнивши цю документацію будь-якими відсутніми деталями.

Використання інших постачальників¶

Будь ласка, не соромтеся надсилати документацію для інших постачальників і ділитися своїм досвідом з громадою!