Thiết lập trò chuyện AI¶

Info

Trò chuyện AI yêu cầu Gramps Web API phiên bản 2.5.0 trở lên. Phiên bản 3.6.0 đã giới thiệu khả năng gọi công cụ để tương tác thông minh hơn.

Gramps Web API hỗ trợ việc đặt câu hỏi về cơ sở dữ liệu gia phả bằng cách sử dụng các mô hình ngôn ngữ lớn (LLM) thông qua một kỹ thuật gọi là tạo ra thông tin tăng cường (RAG) kết hợp với việc gọi công cụ.

Cách hoạt động¶

Trợ lý AI sử dụng hai phương pháp bổ sung:

Tạo ra thông tin tăng cường (RAG): Một mô hình nhúng vector tạo ra một chỉ mục của tất cả các đối tượng trong cơ sở dữ liệu Gramps dưới dạng các vector số liệu mã hóa ý nghĩa của các đối tượng. Khi một người dùng đặt câu hỏi, câu hỏi đó cũng được chuyển đổi thành một vector và so sánh với các đối tượng trong cơ sở dữ liệu. Tìm kiếm ngữ nghĩa này trả về các đối tượng có ý nghĩa tương tự nhất với câu hỏi.

Gọi công cụ (v3.6.0+): Trợ lý AI hiện có thể sử dụng các công cụ chuyên biệt để truy vấn dữ liệu gia phả của bạn trực tiếp. Những công cụ này cho phép trợ lý tìm kiếm trong cơ sở dữ liệu, lọc người/sự kiện/gia đình/nơi chốn theo các tiêu chí cụ thể, tính toán mối quan hệ giữa các cá nhân và lấy thông tin chi tiết về đối tượng. Điều này làm cho trợ lý có khả năng trả lời các câu hỏi gia phả phức tạp một cách chính xác hơn.

Để kích hoạt điểm cuối trò chuyện trong Gramps Web API, cần thực hiện ba bước:

Cài đặt các phụ thuộc cần thiết,
Kích hoạt tìm kiếm ngữ nghĩa,
Thiết lập nhà cung cấp LLM.

Ba bước này được mô tả dưới đây. Cuối cùng, một chủ sở hữu hoặc quản trị viên phải cấu hình ai có thể truy cập tính năng trò chuyện trong cài đặt Quản lý Người dùng.

Cài đặt các phụ thuộc cần thiết¶

Trò chuyện AI yêu cầu các thư viện Sentence Transformers và PyTorch được cài đặt.

Các hình ảnh docker tiêu chuẩn cho Gramps Web đã có sẵn các thư viện này được cài đặt sẵn cho các kiến trúc amd64 (ví dụ: máy tính để bàn 64-bit) và arm64 (ví dụ: Raspberry Pi 64-bit). Không may, trò chuyện AI không được hỗ trợ trên kiến trúc armv7 (ví dụ: Raspberry Pi 32-bit) do thiếu hỗ trợ PyTorch.

Khi cài đặt Gramps Web API qua pip (điều này không cần thiết khi sử dụng các hình ảnh Docker), các phụ thuộc cần thiết được cài đặt với

pip install gramps_webapi[ai]

Kích hoạt tìm kiếm ngữ nghĩa¶

Nếu các phụ thuộc cần thiết đã được cài đặt, việc kích hoạt tìm kiếm ngữ nghĩa có thể đơn giản như việc thiết lập tùy chọn cấu hình VECTOR_EMBEDDING_MODEL (ví dụ: bằng cách thiết lập biến môi trường GRAMPSWEB_VECTOR_EMBEDDING_MODEL), xem Cấu hình Máy chủ. Đây có thể là bất kỳ chuỗi nào của một mô hình được hỗ trợ bởi thư viện Sentence Transformers. Xem tài liệu của dự án này để biết chi tiết và các mô hình có sẵn.

Warning

Lưu ý rằng các hình ảnh docker mặc định không bao gồm phiên bản PyTorch có hỗ trợ GPU. Nếu bạn có quyền truy cập vào GPU (điều này sẽ tăng tốc độ lập chỉ mục ngữ nghĩa một cách đáng kể), vui lòng cài đặt phiên bản PyTorch có hỗ trợ GPU.

Có một số điều cần cân nhắc khi chọn mô hình.

Khi bạn thay đổi mô hình, bạn phải tự tay tái tạo chỉ mục tìm kiếm ngữ nghĩa cho cây của bạn (hoặc tất cả các cây trong một thiết lập đa cây), nếu không bạn sẽ gặp lỗi hoặc kết quả vô nghĩa. Gramps Web phát hiện khi mô hình nhúng được cấu hình không còn khớp với chỉ mục hiện có và hiển thị một thông báo liên tục cho các quản trị viên nhắc họ kích hoạt một lần lập chỉ mục lại toàn bộ từ Cài đặt Quản trị.
Các mô hình là một sự đánh đổi giữa độ chính xác/tính tổng quát ở một bên và thời gian tính toán/kho lưu trữ ở bên kia. Nếu bạn không chạy Gramps Web API trên một hệ thống có quyền truy cập vào một GPU mạnh mẽ, các mô hình lớn hơn thường quá chậm trong thực tế.
Trừ khi toàn bộ cơ sở dữ liệu của bạn bằng tiếng Anh và tất cả người dùng của bạn chỉ được mong đợi đặt câu hỏi trò chuyện bằng tiếng Anh, bạn sẽ cần một mô hình nhúng đa ngôn ngữ, mà hiếm hơn so với các mô hình tiếng Anh thuần túy.

Nếu mô hình không có trong bộ nhớ cache cục bộ, nó sẽ được tải xuống khi Gramps Web API được khởi động lần đầu tiên với cấu hình mới. Mô hình sentence-transformers/distiluse-base-multilingual-cased-v2 đã có sẵn cục bộ khi sử dụng các hình ảnh docker tiêu chuẩn. Mô hình này là một điểm khởi đầu tốt và hỗ trợ đầu vào đa ngôn ngữ.

Hãy chia sẻ những hiểu biết về các mô hình khác nhau với cộng đồng!

Info

Thư viện sentence transformers tiêu tốn một lượng lớn bộ nhớ, điều này có thể khiến các tiến trình làm việc bị giết. Như một quy tắc chung, với tìm kiếm ngữ nghĩa được kích hoạt, mỗi tiến trình Gunicorn tiêu tốn khoảng 200 MB bộ nhớ và mỗi tiến trình celery khoảng 500 MB bộ nhớ ngay cả khi không hoạt động, và lên đến 1 GB khi tính toán các nhúng. Xem Giới hạn CPU và sử dụng bộ nhớ để biết các cài đặt giới hạn việc sử dụng bộ nhớ. Ngoài ra, nên cung cấp một phân vùng hoán đổi đủ lớn để ngăn ngừa lỗi OOM do các đỉnh sử dụng bộ nhớ tạm thời.

Sử dụng API nhúng từ xa¶

Như một lựa chọn thay thế cho việc chạy một mô hình Sentence Transformers cục bộ, bạn có thể sử dụng một API nhúng tương thích với OpenAI từ xa cho tìm kiếm ngữ nghĩa. Điều này hữu ích nếu bạn muốn chuyển tải việc tính toán nhúng cho một dịch vụ riêng biệt (ví dụ: Ollama), sử dụng một nhà cung cấp nhúng đám mây (ví dụ: OpenAI), hoặc tránh việc tải các thư viện Sentence Transformers và PyTorch vào bộ nhớ.

API từ xa phải tương thích với điểm cuối nhúng OpenAI (/v1/embeddings).

Để sử dụng API nhúng từ xa, hãy thiết lập các tùy chọn cấu hình sau (xem Cấu hình Máy chủ):

Key	Mô tả
`VECTOR_EMBEDDING_MODEL`	Tên mô hình để gửi đến nhà cung cấp từ xa
`VECTOR_EMBEDDING_BASE_URL`	URL cơ sở của API từ xa
`VECTOR_EMBEDDING_API_KEY`	Khóa API (chỉ cần nếu nhà cung cấp yêu cầu xác thực)

Sử dụng Ollama cho nhúng¶

Khi triển khai Gramps Web với Docker Compose, bạn có thể thêm một dịch vụ Ollama và sử dụng nó cho cả nhúng và (tùy chọn) LLM:

services:
  grampsweb: &grampsweb
    # ... cấu hình hiện có ...
    environment:
      GRAMPSWEB_VECTOR_EMBEDDING_MODEL: nomic-embed-text
      GRAMPSWEB_VECTOR_EMBEDDING_BASE_URL: http://ollama:11434

  grampsweb_celery: &grampsweb_celery
    # ... cấu hình hiện có ...
    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:

Sau khi khởi động các dịch vụ, hãy kéo mô hình nhúng vào Ollama:

docker compose exec ollama ollama pull nomic-embed-text

Info

Khi sử dụng Ollama cho nhúng, các thư viện Sentence Transformers và PyTorch không cần thiết, điều này giảm đáng kể việc sử dụng bộ nhớ của các tiến trình Gramps Web API.

Sử dụng OpenAI cho nhúng¶

Để sử dụng API nhúng OpenAI, hãy thiết lập URL cơ sở thành API OpenAI và cung cấp khóa API của bạn:

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

Thay đổi mô hình nhúng yêu cầu phải lập chỉ mục lại tất cả các bản ghi cho cây của bạn (hoặc tất cả các cây trong một thiết lập đa cây), vì các mô hình khác nhau tạo ra các vector với các kích thước khác nhau.

Thiết lập nhà cung cấp LLM¶

Giao tiếp với LLM sử dụng khung AI Pydantic, hỗ trợ các API tương thích với OpenAI. Điều này cho phép sử dụng một LLM được triển khai cục bộ qua Ollama (xem tính tương thích OpenAI của Ollama) hoặc các API được lưu trữ như OpenAI, Anthropic hoặc Hugging Face TGI (Text Generation Inference). LLM được cấu hình thông qua các tham số cấu hình LLM_MODEL và LLM_BASE_URL.

Sử dụng LLM được lưu trữ qua API OpenAI¶

Khi sử dụng API OpenAI, LLM_BASE_URL có thể để trống, trong khi LLM_MODEL phải được thiết lập thành một trong các mô hình OpenAI, ví dụ: gpt-4o-mini. LLM sử dụng cả RAG và gọi công cụ để trả lời câu hỏi: nó chọn thông tin liên quan từ các kết quả tìm kiếm ngữ nghĩa và có thể truy vấn trực tiếp cơ sở dữ liệu bằng cách sử dụng các công cụ chuyên biệt. Nó không yêu cầu kiến thức sâu về gia phả hoặc lịch sử. Do đó, bạn có thể thử xem một mô hình nhỏ/rẻ có đủ hay không.

Bạn cũng sẽ cần đăng ký một tài khoản, lấy khóa API và lưu trữ nó trong biến môi trường OPENAI_API_KEY.

Info

LLM_MODEL là một tham số cấu hình; nếu bạn muốn thiết lập nó qua một biến môi trường, hãy sử dụng GRAMPSWEB_LLM_MODEL (xem Cấu hình). OPENAI_API_KEY không phải là một tham số cấu hình mà là một biến môi trường được thư viện Pydantic AI sử dụng trực tiếp, vì vậy không nên có tiền tố.

Sử dụng Mistral AI¶

Để sử dụng các mô hình được lưu trữ của Mistral AI, hãy thêm tiền tố mistral: vào tên mô hình khi thiết lập LLM_MODEL.

Bạn sẽ cần đăng ký một tài khoản Mistral AI, lấy một khóa API và lưu trữ nó trong biến môi trường MISTRAL_API_KEY. Không cần thiết lập LLM_BASE_URL vì Pydantic AI sẽ tự động sử dụng điểm cuối API Mistral chính xác.

Ví dụ cấu hình khi sử dụng docker compose với các biến môi trường:

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

Sử dụng LLM cục bộ qua Ollama¶

Ollama là một cách tiện lợi để chạy LLM cục bộ. Vui lòng tham khảo tài liệu của Ollama để biết chi tiết. Xin lưu ý rằng LLM yêu cầu tài nguyên tính toán đáng kể và tất cả các mô hình lớn hơn sẽ có thể quá chậm nếu không có hỗ trợ GPU. Bạn có thể thử xem liệu tinyllama có đáp ứng nhu cầu của bạn không. Nếu không, hãy thử một trong các mô hình lớn hơn. Hãy chia sẻ bất kỳ kinh nghiệm nào với cộng đồng!

Khi triển khai Gramps Web với Docker Compose, bạn có thể thêm một dịch vụ Ollama

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

volumes:
    ollama_data:

và sau đó thiết lập tham số cấu hình LLM_BASE_URL thành http://ollama:11434/v1. Thiết lập LLM_MODEL thành một mô hình được Ollama hỗ trợ, và kéo nó xuống trong container của bạn với ollama pull <model>. Cuối cùng, thiết lập OPENAI_API_KEY thành ollama.

Để khắc phục sự cố với Ollama, bạn có thể kích hoạt ghi nhật ký gỡ lỗi bằng cách thiết lập biến môi trường OLLAMA_DEBUG=1 trong môi trường dịch vụ Ollama.

Info

Nếu bạn đang sử dụng Ollama cho trò chuyện AI Gramps Web, vui lòng hỗ trợ cộng đồng bằng cách hoàn thiện tài liệu này với bất kỳ chi tiết nào còn thiếu.

Sử dụng các nhà cung cấp khác¶

Xin vui lòng gửi tài liệu cho các nhà cung cấp khác và chia sẻ kinh nghiệm của bạn với cộng đồng!