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

# Integrasi AI

> Konfigurasikan chat AI, saran perbaikan error LaTeX, akses pengguna, kuota, dan layanan pencarian opsional.

> [!NOTE]
>
> Fitur ini disediakan oleh [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro) dan tersedia sejak v6.3.0. Kami menyambut masukan Anda jika Anda mengalami masalah.

## Asisten AI dan asisten error LaTeX

Ayakaleaf Pro menghadirkan fitur AI ke dalam editor melalui 2 cara.

* AI Assistant dapat menggunakan dokumen proyek dan pilihan teks Anda saat ini sebagai konteks untuk menjawab pertanyaan dan menyarankan suntingan untuk Anda tinjau.
* Error Assistant mengusulkan perbaikan yang tepat sasaran saat Anda memilih error kompilasi 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)

### Konfigurasi Toolkit

Tambahkan yang berikut ke `config/variables.env` di deployment Toolkit Anda, dengan mengganti contoh URL, key, dan model dengan nilai dari penyedia Anda:

```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
```

Simpan API key asli di file lingkungan deployment Anda dan jauhkan dari version control. Nilai-nilai di atas hanyalah placeholder, bukan kredensial yang berfungsi.

> [!NOTE]
>
> Kualitas saran AI bergantung pada model yang Anda pilih. Jika Anda sudah memiliki langganan Codex atau ChatGPT, Anda dapat menghubungkannya melalui endpoint kompatibel OpenAI dari [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI).

`AI_BASE_URL` adalah base URL API yang kompatibel dengan OpenAI, termasuk prefiks versi penyedia jika diperlukan. Jangan menambahkan `/chat/completions` karena kami akan menambahkannya secara internal. Gateway dan model harus mendukung streaming chat completions dan function tools. Kedua fitur mengirimkan konteks dokumen ke gateway ini; chat juga dapat mengirimkan gambar dan file PDF yang diunggah jika menggunakan model yang menerimanya.

Toolkit meneruskan `config/variables.env` ke dalam kontainer aplikasi. Gunakan nama variabel seperti yang ditunjukkan di sini; jangan tambahkan prefiks `OVERLEAF_`. Dari direktori Toolkit, buat ulang kontainer aplikasi setelah mengubah variabel-variabel ini:

```sh theme={null}
bin/up -d
```

### Pengaturan gateway

| Variabel | Default | Kegunaan |
| - | - | - |
| `AI_ENABLED` | `false` | Atur tepat ke `true` untuk mengaktifkan chat dan saran perbaikan error untuk instans. Jika tidak diatur atau bernilai lain, fitur tetap nonaktif. Konfigurasi gateway yang berfungsi juga diperlukan. |
| `AI_BASE_URL` | Tidak ada; wajib | Base URL API yang kompatibel dengan OpenAI. |
| `AI_API_KEY` | Tidak ada; wajib | API key untuk gateway tersebut, digunakan oleh server. |
| `AI_MODEL` | Tidak ada; wajib | Model teks yang digunakan oleh konfigurasi chat default dan oleh saran perbaikan error LaTeX. |
| `AI_IMAGE_MODEL` | Tidak diatur | Model opsional yang mendukung gambar pada gateway yang sama, menggunakan API key yang sama. |
| `AI_PDF_MODEL` | Tidak diatur | Model opsional pada gateway yang sama untuk chat dengan file PDF, menggunakan API key yang sama. Mulai v6.4.0. |
| `AI_MAX_STEPS` | `20` | Jumlah maksimum pemanggilan tool per pesan pengguna di chat AI, termasuk kelanjutan otomatis. Gunakan bilangan bulat positif. |
| `AI_PROXY_URL` | Tidak diatur | URL proxy HTTP opsional untuk panggilan ke gateway AI. Ini tidak mengonfigurasi klien pencarian web atau dokumentasi. |
| `AI_TOKEN_QUOTA` | `0` | Batas token per pengguna yang digunakan bersama oleh chat dan saran perbaikan error untuk setiap periode. Tidak diatur atau `0` berarti tanpa batas; gunakan bilangan bulat positif untuk menetapkan batas. |
| `AI_TOKEN_QUOTA_PERIOD` | `month` | `month` direset pada hari pertama pukul 00:00 UTC; `week` direset setiap Senin pukul 00:00 UTC. Nilai lain menggunakan `month`. |

Untuk unggahan gambar, atur `AI_IMAGE_MODEL` ke model yang menerima input gambar dan mendukung tool yang digunakan oleh chat. Setiap permintaan chat yang riwayatnya berisi lampiran gambar akan menggunakan model ini, termasuk pesan-pesan berikutnya dalam percakapan tersebut. Tanpa pengaturan ini, permintaan gambar menggunakan model chat biasa, yang harus mendukung gambar. Saran perbaikan error LaTeX tetap menggunakan `AI_MODEL`.

Lampiran PDF diperkenalkan mulai v6.4.0. Pengguna dapat melampirkan file PDF hingga 2 MB, seperti halnya gambar. Chat mengirimkan setiap file PDF apa adanya, sebagai bagian `file` Chat Completions, sehingga gateway dan model harus menerima input PDF: model vision OpenAI mendukungnya, sedangkan banyak gateway self-hosted, seperti vLLM, menerima gambar tetapi menolak file PDF. Atur `AI_PDF_MODEL` ke model yang dapat membaca file PDF; setiap chat yang riwayatnya berisi file PDF akan menggunakannya, termasuk pesan-pesan berikutnya dan gambar apa pun dalam percakapan tersebut, sehingga model ini sebaiknya juga menerima gambar. Tanpa pengaturan ini, chat PDF menggunakan `AI_MODEL`. Jika model menolak file PDF, chat akan memberi tahu pengguna untuk meminta administrator mengatur `AI_PDF_MODEL`.

Misalnya, untuk mengaktifkan model gambar dan jatah AI mingguan:

```dotenv theme={null}
AI_IMAGE_MODEL=YOUR_IMAGE_CAPABLE_MODEL_ID
AI_TOKEN_QUOTA=100000
AI_TOKEN_QUOTA_PERIOD=week
```

### Akses dan persetujuan pengguna

Ketersediaan instans dan izin pengguna adalah dua hal yang terpisah. `AI_ENABLED` dan konfigurasi gateway mengontrol ketersediaan instans. Pengguna yang sudah login juga harus lolos pemeriksaan akun yang ada: `aiFeatures.enabled` tidak boleh bernilai `false`. Field database yang sudah ada ini mengontrol chat maupun saran perbaikan error LaTeX. Jika tidak diatur, fitur AI diaktifkan untuk pengguna tersebut.

`AI_TOKEN_QUOTA` adalah batas yang diterapkan secara sama ke setiap pengguna yang diizinkan; modul saat ini tidak menyediakan batas numerik individual per akun.

Di daftar pengguna admin, pilih seorang pengguna dan buka **Update account info → AI features**. **Enable AI features** memperbarui `aiFeatures.enabled` saat perubahan akun disimpan. Server memeriksa izin terkini pada setiap permintaan AI baru, termasuk permintaan dari editor yang sudah terbuka. Pengguna tanpa izin tetap melihat asisten AI di editor, tetapi tidak dapat mengirim pesan.

### Penggunaan dan reset

Tab AI features di admin menampilkan **Usage**, **Limit**, dan tombol **Reset** untuk periode saat ini dalam satu baris. Penggunaan dibaca saat tab dibuka; data ini tidak diperbarui secara terus-menerus. Buka kembali tab setelah chat atau saran perbaikan error selesai untuk melihat jumlah terbaru. Reset berlaku seketika dan hanya menghapus penghitung periode saat ini milik pengguna tersebut, lalu memuat ulang penggunaan yang ditampilkan. Reset tidak memerlukan penyimpanan bagian lain dari formulir akun.

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

Penggunaan chat dan saran perbaikan error berbagi satu penghitung Redis, yang diperbarui berdasarkan total token yang dilaporkan oleh penyedia model setelah permintaan selesai. Ini mencakup token input dan output di seluruh langkah model. Input dapat mencakup riwayat percakapan, konteks dokumen, dan hasil tool, sehingga pesan lanjutan dapat menghabiskan lebih banyak token daripada pesan baru itu sendiri. Penggunaan tetap dicatat meskipun batasnya **Unlimited**. Permintaan tanpa total token yang dilaporkan tidak menambah penghitung; penggunaan historis yang tidak tercatat tidak dapat direkonstruksi oleh modul.

Pemeriksaan kuota dilakukan sebelum streaming. Satu permintaan, atau beberapa permintaan bersamaan, dapat melampaui sisa jatah sebelum permintaan berikutnya diblokir. Ini adalah jatah penggunaan, bukan batas pengeluaran penyedia yang ketat. Jika pencarian kuota gagal, permintaan tetap diizinkan dan kegagalan tersebut dicatat di log.

Kedua fitur menggunakan `AI_TOKEN_QUOTA`; saran perbaikan error tidak memiliki batas jumlah permintaan tersendiri. Mereset penghitung tidak mengubah izin, persetujuan, batas yang dikonfigurasi, maupun catatan penagihan milik penyedia. Penghitung menggunakan kunci periode UTC dan kedaluwarsa setelah 40 hari; mempertahankan data Redis akan menjaga penggunaan saat ini meskipun aplikasi dimulai ulang.

### Layanan pencarian opsional

Pencarian web menggunakan API yang kompatibel dengan Tavily. Fitur ini tersedia jika API key pencarian telah dikonfigurasi. Pengaturan ini tidak bergantung pada gateway AI:

| Variabel | Default | Kegunaan |
| - | - | - |
| `TAVILY_API_KEY` | Tidak diatur | API key pencarian. Lebih diutamakan daripada `WEB_SEARCH_API_KEY`. |
| `WEB_SEARCH_API_KEY` | Tidak diatur | Nama alternatif untuk API key pencarian. |
| `WEB_SEARCH_URL` | `https://api.tavily.com/search` | Endpoint pencarian; endpoint kustom harus menerima format permintaan dan respons Tavily. |
| `WEB_SEARCH_MAX_RESULTS` | `5` | Jumlah hasil yang diminta per pencarian; gunakan bilangan bulat positif yang didukung oleh layanan. |
| `WEB_SEARCH_DEPTH` | `basic` | Kedalaman pencarian, biasanya `basic` atau `advanced`. |
| `WEB_SEARCH_PROVIDER` | `tavily` | Implementasi saat ini hanya mendukung protokol yang kompatibel dengan Tavily; mengubah nilai ini tidak memilih adapter lain. |
| `DOCS_MCP_URL` | `https://docs.overleaf.com/~gitbook/mcp` | Endpoint pencarian dokumentasi. Atur ke string kosong untuk menonaktifkan pencarian dokumentasi. |

Misalnya:

```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
```

Pencarian dokumentasi memanggil tool `searchDocumentation` milik endpoint MCP GitBook yang dikonfigurasi dan menerima respons JSON atau SSE. Ini adalah klien MCP untuk pencarian dokumentasi. Untuk mengizinkan klien AI di luar Ayakaleaf bekerja pada sebuah proyek, lihat [MCP Server](https://ayakaleaf-pro.mintlify.site/id/on-premises/configuration/overleaf-toolkit/integrations/mcp-server.md).

Membaca halaman web diperkenalkan mulai v6.4.0. Chat dapat membaca halaman berdasarkan URL-nya, seperti tautan yang diberikan pengguna atau hasil pencarian. Chat mengambil halaman melalui linked URL proxy, layanan yang sama yang mengambil file dari URL eksternal, sehingga pembatasan jaringan yang dijelaskan di [External URL](https://ayakaleaf-pro.mintlify.site/id/on-premises/configuration/overleaf-toolkit/external-url.md) juga berlaku untuknya. Tidak diperlukan pengaturan tambahan.

Kueri pencarian dikirim ke layanan pencarian yang dikonfigurasi. Hasil pencarian kemudian dapat disertakan dalam permintaan ke gateway AI. Menu **Tools** di chat memungkinkan pengguna mengaktifkan atau menonaktifkan **Web** dan **Documentation** untuk permintaan mereka; tool juga harus dikonfigurasi di server agar tersedia bagi model.

### Tanya Jawab

> [accordion] Asisten AI tidak muncul di editor
>
> **Jawaban:** Asisten AI muncul di rail kiri editor hanya jika `AI_ENABLED=true` dan `AI_BASE_URL`, `AI_API_KEY`, serta `AI_MODEL` semuanya diatur. Jika salah satunya tidak ada, asisten AI disembunyikan untuk semua pengguna.
>
> Setelah mengubah `config/variables.env`, buat ulang kontainer dengan `bin/up -d`. Memuat ulang browser saja tidak menerapkan variabel baru. Sakelar **Enable AI features** di panel admin tidak menampilkan atau menyembunyikan asisten AI; sakelar itu hanya menentukan apakah pengguna dapat mengirim pesan.

> [accordion] Saya mengirim pesan, tetapi asisten AI tidak membalas
>
> **Jawaban:** Pertama, pastikan pengguna telah menyetujui kartu persetujuan AI yang ditampilkan di asisten AI. Pesan tidak dapat dikirim sebelum itu.
>
> Lalu cari error di log layanan web:
>
> ```sh theme={null}
> bin/logs web
> ```
>
> | Pesan log | Arti |
> | - | - |
> | `workbench AI chat requested but no AI gateway is configured` | Salah satu dari `AI_ENABLED`, `AI_BASE_URL`, `AI_API_KEY` atau `AI_MODEL` tidak ada di kontainer yang sedang berjalan. Buat ulang dengan `bin/up -d`. |
> | `workbench chat stream error` | Gateway mengembalikan error. Pengguna melihat "The AI service returned an error". Error yang tercatat menunjukkan kode status dan pesan dari gateway. |
> | `workbench chat failed` | Permintaan gagal sebelum atau selama streaming, misalnya karena gateway tidak dapat dijangkau. |
>
> Jika dasbor penyedia Anda tidak menunjukkan penggunaan, berarti permintaan tidak sampai ke penyedia. Penyebab umumnya adalah:
>
> * `AI_BASE_URL` salah, misalnya `/v1` yang hilang atau berlebih, atau `/chat/completions` ditambahkan padanya.
> * Server tidak dapat menjangkau gateway. Jika lalu lintas keluar harus melalui proxy, atur `AI_PROXY_URL`.
> * `AI_MODEL` bukan ID model yang dikenal oleh gateway.
>
> Jika penyedia menunjukkan adanya permintaan tetapi chat tetap gagal, pastikan model mendukung streaming chat completions dan function tools.

> [accordion] Apakah riwayat chat disimpan?
>
> **Jawaban:** Tidak. Chat hanya disimpan di tab browser yang sedang terbuka. Memuat ulang atau menutup halaman akan menghapusnya, dan **Start new chat** menggantikan chat saat ini. Tidak ada daftar chat sebelumnya, dan setiap proyek menampilkan satu chat dalam satu waktu.


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