Налаштування 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 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, який підтримує API, сумісні з OpenAI. Це дозволяє використовувати локально розгорнуту LLM через Ollama (див. Сумісність Ollama з OpenAI) або хостингові API, такі як OpenAI, Anthropic або Hugging Face TGI (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, будь ласка, підтримайте громаду, доповнивши цю документацію будь-якими відсутніми деталями.

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

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