Integracja AI

Skonfiguruj czat AI, sugestie dotyczące błędów LaTeX, dostęp użytkowników, limity oraz opcjonalne usługi wyszukiwania.

Ta funkcja jest dostarczana przez ayaka-notes/ayakaleaf-pro i jest dostępna od wersji v6.3.0. Jeśli napotkasz jakiekolwiek problemy, chętnie poznamy Twoją opinię.

​

Asystent AI i asystent błędów LaTeX

Ayakaleaf Pro wprowadza funkcje AI do edytora na 2 sposoby.

• Asystent AI może wykorzystywać dokumenty projektu i bieżące zaznaczenie jako kontekst, aby odpowiadać na pytania i proponować zmiany do Twojej weryfikacji.
• Asystent błędów proponuje ukierunkowaną poprawkę po zaznaczeniu błędu kompilacji LaTeX.

​

Konfiguracja Toolkit

Dodaj poniższe wpisy do config/variables.env we wdrożeniu Toolkit, zastępując przykładowy URL, klucz i model wartościami od swojego dostawcy:

AI_ENABLED=true
AI_BASE_URL=https://ai-gateway.example.com/v1
AI_API_KEY=REPLACE_WITH_YOUR_GATEWAY_API_KEY
AI_MODEL=YOUR_TEXT_MODEL_ID

Przechowuj prawdziwe klucze API w pliku środowiskowym wdrożenia, poza systemem kontroli wersji. Powyższe wartości są symbolami zastępczymi, a nie działającymi danymi uwierzytelniającymi.

Jakość sugestii AI zależy od wybranego modelu. Jeśli masz już subskrypcję Codex lub ChatGPT, możesz ją podłączyć za pośrednictwem endpointu zgodnego z OpenAI w CLIProxyAPI.

AI_BASE_URL to bazowy URL API zgodnego z OpenAI, zawierający prefiks wersji dostawcy, jeśli jest wymagany. Nie dopisuj /chat/completions, ponieważ dodajemy to wewnętrznie. Bramka i model muszą obsługiwać strumieniowe uzupełnienia czatu (streaming chat completions) oraz narzędzia funkcyjne (function tools). Obie funkcje wysyłają kontekst dokumentu do tej bramki; czat może również wysyłać przesłane obrazy i pliki PDF, jeśli używany jest model, który je akceptuje.

Toolkit przekazuje config/variables.env do kontenera aplikacji. Zachowaj podane tutaj nazwy zmiennych; nie dodawaj prefiksu OVERLEAF_. Po zmianie tych zmiennych odtwórz kontener aplikacji z katalogu Toolkit:

bin/up -d

​

Ustawienia bramki

Zmienna	Domyślnie	Przeznaczenie
AI_ENABLED	false	Ustaw dokładnie true, aby włączyć czat i sugestie dotyczące błędów dla instancji. Brak wartości lub dowolna inna wartość pozostawia je wyłączone. Wymagana jest również działająca konfiguracja bramki.
AI_BASE_URL	Brak; wymagane	Bazowy URL API zgodnego z OpenAI.
AI_API_KEY	Brak; wymagane	Klucz API dla tej bramki, używany przez serwer.
AI_MODEL	Brak; wymagane	Model tekstowy używany przez domyślną konfigurację czatu oraz przez sugestie dotyczące błędów LaTeX.
AI_IMAGE_MODEL	Nieustawione	Opcjonalny model obsługujący obrazy w tej samej bramce, korzystający z tego samego klucza API.
AI_PDF_MODEL	Nieustawione	Opcjonalny model w tej samej bramce do czatów z plikami PDF, korzystający z tego samego klucza API. Od wersji v6.4.0.
AI_MAX_STEPS	20	Maksymalna liczba wywołań narzędzi na jedną wiadomość użytkownika w czacie AI, łącznie z automatycznymi kontynuacjami. Użyj dodatniej liczby całkowitej.
AI_PROXY_URL	Nieustawione	Opcjonalny URL proxy HTTP dla wywołań bramki AI. Nie konfiguruje klientów wyszukiwania w sieci ani w dokumentacji.
AI_TOKEN_QUOTA	0	Limit tokenów na użytkownika, wspólny dla czatu i sugestii dotyczących błędów w każdym okresie. Brak wartości lub 0 oznacza brak limitu; użyj dodatniej liczby całkowitej, aby ustawić limit.
AI_TOKEN_QUOTA_PERIOD	month	month resetuje się pierwszego dnia miesiąca o 00:00 UTC; week resetuje się w poniedziałek o 00:00 UTC. Inne wartości działają jak month.

Aby umożliwić przesyłanie obrazów, ustaw AI_IMAGE_MODEL na model, który przyjmuje obrazy jako dane wejściowe i obsługuje narzędzia używane przez czat. Każde żądanie czatu, którego historia zawiera załącznik graficzny, korzysta z tego modelu — również kolejne wiadomości w tej rozmowie. Bez tego ustawienia żądania z obrazami używają zwykłego modelu czatu, który sam musi obsługiwać obrazy. Sugestie dotyczące błędów LaTeX nadal używają AI_MODEL.

Załączniki PDF są dostępne od wersji v6.4.0. Użytkownicy mogą dołączać pliki PDF o rozmiarze do 2 MB, podobnie jak obrazy. Czat wysyła każdy plik PDF w niezmienionej postaci jako część file w Chat Completions, więc bramka i model muszą akceptować dane wejściowe PDF: modele OpenAI z obsługą obrazu to robią, natomiast wiele samodzielnie hostowanych bramek, takich jak vLLM, akceptuje obrazy, ale odrzuca pliki PDF. Ustaw AI_PDF_MODEL na model, który odczytuje pliki PDF; każdy czat, którego historia zawiera plik PDF, korzysta z niego — również kolejne wiadomości i wszelkie obrazy w tej rozmowie — dlatego powinien on także akceptować obrazy. Bez tego ustawienia czaty z plikami PDF używają AI_MODEL. Gdy model odrzuci plik PDF, czat poinformuje użytkownika, aby poprosił administratora o ustawienie AI_PDF_MODEL.

Na przykład, aby włączyć model obsługujący obrazy i tygodniowy limit AI:

AI_IMAGE_MODEL=YOUR_IMAGE_CAPABLE_MODEL_ID
AI_TOKEN_QUOTA=100000
AI_TOKEN_QUOTA_PERIOD=week

​

Dostęp użytkowników i zgoda

Dostępność w instancji i uprawnienia użytkownika to odrębne kwestie. AI_ENABLED oraz konfiguracja bramki decydują o dostępności w instancji. Zalogowany użytkownik musi ponadto przejść istniejącą kontrolę konta: aiFeatures.enabled nie może mieć wartości false. To istniejące pole bazy danych steruje zarówno czatem, jak i sugestiami dotyczącymi błędów LaTeX. Gdy nie jest ustawione, funkcje AI są dla użytkownika włączone.

AI_TOKEN_QUOTA to limit stosowany jednakowo do każdego uprawnionego użytkownika; obecny moduł nie zapewnia indywidualnego limitu liczbowego dla poszczególnych kont.

Na liście użytkowników w panelu administratora wybierz użytkownika i otwórz Update account info → AI features. Enable AI features aktualizuje aiFeatures.enabled po zapisaniu zmian konta. Serwer sprawdza bieżące uprawnienia przy nowych żądaniach AI, w tym przy żądaniach z już otwartego edytora. Użytkownik bez uprawnień nadal widzi asystenta AI w edytorze, ale nie może wysyłać wiadomości.

​

Zużycie i resetowanie

Karta AI features w panelu administratora pokazuje w jednym wierszu Usage bieżącego okresu, Limit oraz przycisk Reset. Zużycie jest odczytywane przy otwarciu karty i nie jest odświeżane na bieżąco. Aby zobaczyć najnowszą wartość, otwórz kartę ponownie po zakończeniu czatu lub sugestii dotyczącej błędu. Reset działa natychmiast i zeruje wyłącznie licznik bieżącego okresu danego użytkownika, a następnie ponownie wczytuje wyświetlane zużycie. Nie wymaga zapisywania pozostałej części formularza konta.

Zużycie czatu i sugestii dotyczących błędów współdzieli jeden licznik Redis, aktualizowany po zakończeniu żądania na podstawie łącznej liczby tokenów zgłoszonej przez dostawcę modelu. Obejmuje to tokeny wejściowe i wyjściowe we wszystkich krokach modelu. Dane wejściowe mogą zawierać historię rozmowy, kontekst dokumentu i wyniki narzędzi, więc kolejna wiadomość może zużyć więcej tokenów niż sama nowa wiadomość. Zużycie jest rejestrowane nawet wtedy, gdy limit ma wartość Unlimited. Żądania bez zgłoszonej łącznej liczby tokenów nie zwiększają licznika; moduł nie może odtworzyć historycznego, niezarejestrowanego zużycia.

Sprawdzanie limitu odbywa się przed rozpoczęciem strumieniowania. Jedno żądanie lub kilka równoczesnych żądań może przekroczyć pozostały przydział, zanim kolejne żądania zostaną zablokowane. Jest to przydział zużycia, a nie ścisły limit wydatków u dostawcy. Jeśli sprawdzenie limitu się nie powiedzie, żądanie jest dopuszczane, a błąd zostaje zapisany w logach.

Obie funkcje korzystają z AI_TOKEN_QUOTA; sugestie dotyczące błędów nie mają osobnego limitu liczby żądań. Zresetowanie licznika nie zmienia uprawnień, zgody, skonfigurowanego limitu ani rozliczeń prowadzonych przez dostawcę. Liczniki używają kluczy okresów w UTC i wygasają po 40 dniach; zachowanie danych Redis pozwala utrzymać bieżące zużycie po restarcie aplikacji.

​

Opcjonalne usługi wyszukiwania

Wyszukiwanie w sieci korzysta z API zgodnego z Tavily. Jest dostępne, gdy skonfigurowano klucz API wyszukiwania. Te ustawienia są niezależne od bramki AI:

Zmienna	Domyślnie	Przeznaczenie
TAVILY_API_KEY	Nieustawione	Klucz API wyszukiwania. Ma pierwszeństwo przed WEB_SEARCH_API_KEY.
WEB_SEARCH_API_KEY	Nieustawione	Alternatywna nazwa klucza API wyszukiwania.
WEB_SEARCH_URL	https://api.tavily.com/search	Endpoint wyszukiwania; niestandardowe endpointy muszą obsługiwać format żądań i odpowiedzi Tavily.
WEB_SEARCH_MAX_RESULTS	5	Liczba wyników żądanych na jedno wyszukiwanie; użyj dodatniej liczby całkowitej obsługiwanej przez usługę.
WEB_SEARCH_DEPTH	basic	Głębokość wyszukiwania, zwykle basic lub advanced.
WEB_SEARCH_PROVIDER	tavily	Obecna implementacja obsługuje wyłącznie protokół zgodny z Tavily; zmiana tej wartości nie wybiera innego adaptera.
DOCS_MCP_URL	https://docs.overleaf.com/~gitbook/mcp	Endpoint wyszukiwania w dokumentacji. Ustaw pusty ciąg znaków, aby wyłączyć wyszukiwanie w dokumentacji.

Na przykład:

TAVILY_API_KEY=REPLACE_WITH_YOUR_SEARCH_API_KEY
WEB_SEARCH_MAX_RESULTS=5
WEB_SEARCH_DEPTH=basic
DOCS_MCP_URL=https://docs.overleaf.com/~gitbook/mcp

Wyszukiwanie w dokumentacji wywołuje narzędzie searchDocumentation skonfigurowanego endpointu GitBook MCP i akceptuje odpowiedzi JSON lub SSE. Jest to klient MCP do wyszukiwania w dokumentacji. Aby umożliwić klientom AI spoza Ayakaleaf pracę nad projektem, zobacz Serwer MCP.

Odczytywanie stron internetowych jest dostępne od wersji v6.4.0. Czat może odczytać stronę na podstawie jej adresu URL, np. linku podanego przez użytkownika lub wyniku wyszukiwania. Pobiera stronę przez proxy linkowanych URL — tę samą usługę, która pobiera pliki z zewnętrznych adresów URL — więc obowiązują go również ograniczenia sieciowe opisane w External URL. Żadne dodatkowe ustawienia nie są potrzebne.

Zapytania wyszukiwania trafiają do skonfigurowanej usługi wyszukiwania. Wyniki wyszukiwania mogą następnie zostać dołączone do żądań wysyłanych do bramki AI. Menu Tools w czacie pozwala użytkownikom włączać lub wyłączać Web i Documentation dla swoich żądań; aby narzędzie było dostępne dla modelu, musi być także skonfigurowane na serwerze.

​

Pytania i odpowiedzi

Asystent AI nie pojawia się w edytorze

Odpowiedź: Asystent AI pojawia się na lewym pasku edytora tylko wtedy, gdy ustawiono AI_ENABLED=true oraz wszystkie zmienne AI_BASE_URL, AI_API_KEY i AI_MODEL. Jeśli brakuje którejkolwiek z nich, asystent AI jest ukryty dla wszystkich użytkowników.

Po zmianie config/variables.env odtwórz kontener za pomocą bin/up -d. Samo odświeżenie przeglądarki nie zastosuje nowych zmiennych. Przełącznik Enable AI features w panelu administratora nie pokazuje ani nie ukrywa asystenta AI; decyduje jedynie o tym, czy użytkownik może wysyłać wiadomości.

Wysyłam wiadomość, ale asystent AI nie odpowiada

Odpowiedź: Najpierw sprawdź, czy użytkownik zaakceptował kartę zgody AI wyświetlaną w asystencie AI. Przed jej zaakceptowaniem nie można wysyłać wiadomości.

Następnie poszukaj błędów w logu usługi web:

bin/logs web

Komunikat w logu	Znaczenie
workbench AI chat requested but no AI gateway is configured	W uruchomionym kontenerze brakuje jednej ze zmiennych AI_ENABLED, AI_BASE_URL, AI_API_KEY lub AI_MODEL. Odtwórz go za pomocą bin/up -d.
workbench chat stream error	Bramka zwróciła błąd. Użytkownik widzi komunikat “The AI service returned an error”. Zarejestrowany błąd zawiera kod statusu i komunikat bramki.
workbench chat failed	Żądanie nie powiodło się przed strumieniowaniem lub w jego trakcie, na przykład dlatego, że bramka jest nieosiągalna.

Jeśli panel Twojego dostawcy nie pokazuje żadnego zużycia, żądanie do niego nie dotarło. Najczęstsze przyczyny to:

• AI_BASE_URL jest nieprawidłowy, na przykład brakuje w nim /v1 lub jest on zbędny albo dopisano do niego /chat/completions.
• Serwer nie może połączyć się z bramką. Jeśli ruch wychodzący musi przechodzić przez proxy, ustaw AI_PROXY_URL.
• AI_MODEL nie jest identyfikatorem modelu znanym bramce.

Jeśli dostawca pokazuje żądania, ale czat nadal nie działa, sprawdź, czy model obsługuje strumieniowe uzupełnienia czatu i narzędzia funkcyjne.

Czy historia czatu jest przechowywana?

Odpowiedź: Nie. Czat jest przechowywany tylko w otwartej karcie przeglądarki. Odświeżenie lub zamknięcie strony usuwa go, a Start new chat zastępuje bieżący czat. Nie ma listy wcześniejszych czatów, a każdy projekt wyświetla jednocześnie jeden czat.