Integrace AI

Konfigurace AI chatu, návrhů oprav chyb LaTeXu, přístupu uživatelů, kvót a volitelných vyhledávacích služeb.

Tuto funkci poskytuje ayaka-notes/ayakaleaf-pro a je k dispozici od verze v6.3.0. Pokud narazíte na jakékoli problémy, uvítáme vaši zpětnou vazbu.

​

AI asistent a asistent pro chyby LaTeXu

Ayakaleaf Pro přináší funkce AI do editoru dvěma způsoby.

• AI asistent může jako kontext použít dokumenty vašeho projektu a aktuální výběr, odpovídat na otázky a navrhovat úpravy, které si můžete zkontrolovat.
• Asistent pro chyby navrhne cílenou opravu, když vyberete chybu kompilace LaTeXu.

​

Konfigurace Toolkitu

Přidejte do souboru config/variables.env ve svém nasazení Toolkitu následující nastavení a nahraďte ukázkovou URL, klíč a model hodnotami od svého poskytovatele:

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

Skutečné API klíče uchovávejte v souboru prostředí nasazení a mimo správu verzí. Výše uvedené hodnoty jsou zástupné, nejde o funkční přihlašovací údaje.

Kvalita návrhů AI závisí na zvoleném modelu. Pokud již máte předplatné Codex nebo ChatGPT, můžete jej připojit přes endpoint kompatibilní s OpenAI v CLIProxyAPI.

AI_BASE_URL je základní URL API kompatibilního s OpenAI, včetně prefixu verze poskytovatele, pokud je vyžadován. Nepřidávejte /chat/completions, protože tuto část připojujeme interně. Brána i model musí podporovat streamované chat completions a funkční nástroje (function tools). Obě funkce odesílají na tuto bránu kontext dokumentu; chat může při použití modelu, který je přijímá, odesílat i nahrané obrázky a soubory PDF.

Toolkit předává config/variables.env do aplikačního kontejneru. Ponechte zde uvedené názvy proměnných; nepřidávejte prefix OVERLEAF_. Po změně těchto proměnných znovu vytvořte aplikační kontejner z adresáře Toolkitu:

bin/up -d

​

Nastavení brány

Proměnná	Výchozí	Účel
AI_ENABLED	false	Nastavte přesně na true, abyste pro instanci povolili chat a návrhy oprav chyb. Pokud není nastaveno nebo má jinou hodnotu, zůstanou zakázány. Je také vyžadována funkční konfigurace brány.
AI_BASE_URL	Žádná; povinné	Základní URL API kompatibilního s OpenAI.
AI_API_KEY	Žádná; povinné	API klíč pro tuto bránu, používaný serverem.
AI_MODEL	Žádná; povinné	Textový model používaný výchozí konfigurací chatu a návrhy oprav chyb LaTeXu.
AI_IMAGE_MODEL	Nenastaveno	Volitelný model podporující obrázky na stejné bráně, používající stejný API klíč.
AI_PDF_MODEL	Nenastaveno	Volitelný model na stejné bráně pro chaty se soubory PDF, používající stejný API klíč. Od verze v6.4.0.
AI_MAX_STEPS	20	Maximální počet volání nástrojů na jednu zprávu uživatele v AI chatu, včetně automatických pokračování. Použijte kladné celé číslo.
AI_PROXY_URL	Nenastaveno	Volitelná URL HTTP proxy pro volání AI brány. Nekonfiguruje klienty pro vyhledávání na webu ani v dokumentaci.
AI_TOKEN_QUOTA	0	Limit tokenů na uživatele za každé období, sdílený chatem a návrhy oprav chyb. Nenastaveno nebo 0 znamená bez omezení; pro limit použijte kladné celé číslo.
AI_TOKEN_QUOTA_PERIOD	month	month se resetuje první den v 00:00 UTC; week se resetuje v pondělí v 00:00 UTC. Ostatní hodnoty použijí month.

Pro nahrávání obrázků nastavte AI_IMAGE_MODEL na model, který přijímá obrázkový vstup a podporuje nástroje používané chatem. Tento model použije každý požadavek chatu, jehož historie obsahuje obrázkovou přílohu, včetně pozdějších zpráv v dané konverzaci. Bez tohoto nastavení používají požadavky s obrázky běžný model chatu, který pak musí obrázky sám podporovat. Návrhy oprav chyb LaTeXu nadále používají AI_MODEL.

Přílohy PDF jsou dostupné od verze v6.4.0. Uživatelé mohou podobně jako obrázky přikládat soubory PDF o velikosti až 2 MB. Chat odesílá každý soubor PDF tak, jak je, jako část file rozhraní Chat Completions, takže brána i model musí přijímat vstup ve formátu PDF: vizuální modely OpenAI to umí, zatímco mnoho self-hosted bran, například vLLM, přijímá obrázky, ale soubory PDF odmítá. Nastavte AI_PDF_MODEL na model, který umí číst soubory PDF; použije jej každý chat, jehož historie obsahuje soubor PDF, včetně pozdějších zpráv a všech obrázků v dané konverzaci, takže by měl přijímat i obrázky. Bez tohoto nastavení používají chaty s PDF AI_MODEL. Když model soubor PDF odmítne, chat uživateli sdělí, ať požádá administrátora o nastavení AI_PDF_MODEL.

Například pro povolení obrázkového modelu a týdenního limitu AI:

AI_IMAGE_MODEL=YOUR_IMAGE_CAPABLE_MODEL_ID
AI_TOKEN_QUOTA=100000
AI_TOKEN_QUOTA_PERIOD=week

​

Přístup uživatelů a souhlas

Dostupnost pro instanci a oprávnění uživatele jsou oddělené. Dostupnost pro instanci řídí AI_ENABLED a konfigurace brány. Přihlášený uživatel musí navíc projít stávající kontrolou účtu: aiFeatures.enabled nesmí být false. Toto stávající databázové pole řídí jak chat, tak návrhy oprav chyb LaTeXu. Pokud není nastaveno, jsou funkce AI pro uživatele povoleny.

AI_TOKEN_QUOTA je limit uplatňovaný stejně na každého oprávněného uživatele; současný modul neposkytuje individuální číselný limit pro jednotlivé účty.

V seznamu uživatelů v administraci vyberte uživatele a otevřete Update account info → AI features. Enable AI features aktualizuje aiFeatures.enabled při uložení změn účtu. Server kontroluje aktuální oprávnění u nových požadavků AI, včetně požadavků z již otevřeného editoru. Uživatel bez oprávnění AI asistenta v editoru stále vidí, ale nemůže odesílat zprávy.

​

Využití a reset

Karta AI features v administraci zobrazuje na jednom řádku Usage, Limit a tlačítko Reset pro aktuální období. Využití se načte při otevření karty; průběžně se neobnovuje. Chcete-li vidět nejnovější počet, otevřete kartu znovu po dokončení chatu nebo návrhu opravy chyby. Reset se projeví okamžitě, vymaže pouze počítadlo daného uživatele pro aktuální období a poté znovu načte zobrazené využití. Nevyžaduje uložení zbytku formuláře účtu.

Využití chatu a návrhů oprav chyb sdílí jedno počítadlo v Redisu, které se po dokončení požadavku aktualizuje podle celkového počtu tokenů nahlášeného poskytovatelem modelu. To zahrnuje vstupní i výstupní tokeny napříč kroky modelu. Vstup může zahrnovat historii konverzace, kontext dokumentu a výsledky nástrojů, takže navazující dotaz může spotřebovat více tokenů než samotná nová zpráva. Využití se zaznamenává i tehdy, když je limit Unlimited. Požadavky bez nahlášeného celkového počtu tokenů se do počítadla nepřičítají; historické nezaznamenané využití modul nedokáže zpětně zrekonstruovat.

Kontroly kvóty probíhají před zahájením streamování. Jeden požadavek nebo několik souběžných požadavků může zbývající limit překročit dříve, než jsou další požadavky zablokovány. Jde tedy o limit využití, nikoli o striktní strop výdajů u poskytovatele. Pokud se dotaz na kvótu nezdaří, požadavek je povolen a chyba se zaznamená do logu.

Obě funkce používají AI_TOKEN_QUOTA; návrhy oprav chyb nemají samostatný limit počtu požadavků. Reset počítadla nemění oprávnění, souhlas, nakonfigurovaný limit ani vlastní záznamy o účtování u poskytovatele. Počítadla používají klíče období v UTC a vyprší po 40 dnech; zachování dat v Redisu uchová aktuální využití i po restartu aplikace.

​

Volitelné vyhledávací služby

Vyhledávání na webu používá API kompatibilní s Tavily. Je k dispozici, pokud je nakonfigurován API klíč pro vyhledávání. Tato nastavení jsou nezávislá na AI bráně:

Proměnná	Výchozí	Účel
TAVILY_API_KEY	Nenastaveno	API klíč pro vyhledávání. Má přednost před WEB_SEARCH_API_KEY.
WEB_SEARCH_API_KEY	Nenastaveno	Alternativní název API klíče pro vyhledávání.
WEB_SEARCH_URL	https://api.tavily.com/search	Endpoint vyhledávání; vlastní endpointy musí přijímat formát požadavků a odpovědí Tavily.
WEB_SEARCH_MAX_RESULTS	5	Počet požadovaných výsledků na jedno vyhledávání; použijte kladné celé číslo podporované službou.
WEB_SEARCH_DEPTH	basic	Hloubka vyhledávání, obvykle basic nebo advanced.
WEB_SEARCH_PROVIDER	tavily	Současná implementace podporuje pouze protokol kompatibilní s Tavily; změna této hodnoty nevybere jiný adaptér.
DOCS_MCP_URL	https://docs.overleaf.com/~gitbook/mcp	Endpoint pro vyhledávání v dokumentaci. Nastavením na prázdný řetězec vyhledávání v dokumentaci zakážete.

Například:

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

Vyhledávání v dokumentaci volá nástroj searchDocumentation nakonfigurovaného endpointu GitBook MCP a přijímá odpovědi ve formátu JSON nebo SSE. Jde o MCP klienta pro vyhledávání v dokumentaci. Chcete-li umožnit práci na projektu AI klientům mimo Ayakaleaf, viz MCP Server.

Čtení webových stránek je dostupné od verze v6.4.0. Chat umí přečíst stránku podle její URL, například odkaz zadaný uživatelem nebo výsledek vyhledávání. Stránku stahuje přes proxy pro odkazované URL, tedy stejnou službu, která stahuje soubory z externích URL, takže se na ni vztahují i síťová omezení popsaná v External URL. Žádné další nastavení není potřeba.

Vyhledávací dotazy se odesílají do nakonfigurované vyhledávací služby. Výsledky vyhledávání pak mohou být zahrnuty do požadavků na AI bránu. Nabídka Tools v chatu umožňuje uživatelům pro své požadavky povolit nebo zakázat Web a Documentation; aby byl nástroj modelu k dispozici, musí být také nakonfigurován na serveru.

​

Otázky a odpovědi

AI asistent se v editoru nezobrazuje

Odpověď: AI asistent se v levém panelu editoru zobrazí pouze tehdy, když je AI_ENABLED=true a jsou nastaveny všechny proměnné AI_BASE_URL, AI_API_KEY a AI_MODEL. Pokud některá z nich chybí, je AI asistent skrytý pro všechny uživatele.

Po změně config/variables.env znovu vytvořte kontejner pomocí bin/up -d. Samotné obnovení prohlížeče nové proměnné nepoužije. Přepínač Enable AI features v administraci AI asistenta nezobrazuje ani neskrývá; rozhoduje pouze o tom, zda uživatel může odesílat zprávy.

Odešlu zprávu, ale AI asistent neodpovídá

Odpověď: Nejprve ověřte, že uživatel přijal kartu se souhlasem s AI zobrazenou v AI asistentovi. Do té doby nelze zprávy odesílat.

Poté vyhledejte chyby v logu služby web:

bin/logs web

Zpráva v logu	Význam
workbench AI chat requested but no AI gateway is configured	V běžícím kontejneru chybí některá z proměnných AI_ENABLED, AI_BASE_URL, AI_API_KEY nebo AI_MODEL. Znovu jej vytvořte pomocí bin/up -d.
workbench chat stream error	Brána vrátila chybu. Uživatel uvidí „The AI service returned an error“. Zalogovaná chyba obsahuje stavový kód a zprávu brány.
workbench chat failed	Požadavek selhal před streamováním nebo během něj, například proto, že brána není dostupná.

Pokud přehled vašeho poskytovatele neukazuje žádné využití, požadavek se k poskytovateli nedostal. Časté příčiny jsou:

• AI_BASE_URL je chybná, například chybí nebo přebývá /v1, nebo je k ní připojeno /chat/completions.
• Server se k bráně nemůže připojit. Pokud musí odchozí provoz procházet přes proxy, nastavte AI_PROXY_URL.
• AI_MODEL není ID modelu, které brána zná.

Pokud poskytovatel požadavky ukazuje, ale chat přesto selhává, ověřte, že model podporuje streamované chat completions a funkční nástroje.

Uchovává se historie chatu?

Odpověď: Ne. Chat se uchovává pouze v otevřené záložce prohlížeče. Obnovením nebo zavřením stránky se smaže a Start new chat nahradí aktuální chat. Neexistuje seznam dřívějších chatů a každý projekt zobrazuje vždy jeden chat.