> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Integracja AI

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

> [!NOTE]
>
> Ta funkcja jest dostarczana przez [ayaka-notes/ayakaleaf-pro](https://github.com/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.

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-49.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=609d6a28104dfb16264790c00123eeb4)

### 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:

```dotenv theme={null}
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.

> [!NOTE]
>
> 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](https://github.com/router-for-me/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:

```sh theme={null}
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:

```dotenv theme={null}
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.

![](https://mintcdn.com/ayakaleaf-pro/x9kfDjtWlyyhG_mR/images/on-premises/img-2f5a5399.png?fit=max\&auto=format\&n=x9kfDjtWlyyhG_mR\&q=85\&s=3c52c12aa1551cda22f218ec2dfda63b)

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:

```dotenv theme={null}
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](https://ayakaleaf-pro.mintlify.site/pl/on-premises/configuration/overleaf-toolkit/integrations/mcp-server.md).

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](https://ayakaleaf-pro.mintlify.site/pl/on-premises/configuration/overleaf-toolkit/external-url.md). Ż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

> [accordion] 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.

> [accordion] 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:
>
> ```sh theme={null}
> 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.

> [accordion] 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.