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

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

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