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

# Tích hợp AI

> Cấu hình trò chuyện AI, gợi ý sửa lỗi LaTeX, quyền truy cập của người dùng, hạn mức và các dịch vụ tìm kiếm tùy chọn.

> [!NOTE]
>
> Tính năng này được cung cấp bởi [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro) và khả dụng từ v6.3.0. Chúng tôi rất mong nhận được phản hồi của bạn nếu gặp bất kỳ vấn đề nào.

## Trợ lý AI và trợ lý lỗi LaTeX

Ayakaleaf Pro đưa các tính năng AI vào trình soạn thảo theo 2 cách.

* Trợ lý AI (AI Assistant) có thể dùng các tài liệu trong dự án và vùng chọn hiện tại làm ngữ cảnh để trả lời câu hỏi và đề xuất chỉnh sửa để bạn xem xét.
* Trợ lý lỗi (Error Assistant) đề xuất một bản sửa có mục tiêu khi bạn chọn một lỗi biên dịch 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)

### Cấu hình Toolkit

Thêm nội dung sau vào `config/variables.env` trong triển khai Toolkit của bạn, thay URL, khóa và mô hình mẫu bằng các giá trị từ nhà cung cấp của bạn:

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

Hãy lưu các API key thực trong tệp môi trường triển khai và không đưa chúng vào hệ thống quản lý phiên bản. Các giá trị ở trên chỉ là giá trị giữ chỗ, không phải thông tin xác thực dùng được.

> [!NOTE]
>
> Chất lượng gợi ý của AI phụ thuộc vào mô hình bạn chọn. Nếu bạn đã có gói đăng ký Codex hoặc ChatGPT, bạn có thể kết nối nó thông qua endpoint tương thích OpenAI của [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI).

`AI_BASE_URL` là URL gốc của API tương thích OpenAI, bao gồm tiền tố phiên bản của nhà cung cấp nếu cần. Đừng thêm `/chat/completions` vào cuối vì chúng tôi sẽ tự thêm phần này ở bên trong. Gateway và mô hình phải hỗ trợ streaming chat completions và function tools. Cả hai tính năng đều gửi ngữ cảnh tài liệu tới gateway này; tính năng trò chuyện cũng có thể gửi ảnh và tệp PDF được tải lên khi sử dụng mô hình chấp nhận chúng.

Toolkit chuyển tiếp `config/variables.env` vào container ứng dụng. Hãy giữ nguyên tên biến như trình bày ở đây; không thêm tiền tố `OVERLEAF_`. Từ thư mục Toolkit, hãy tạo lại container ứng dụng sau khi thay đổi các biến này:

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

### Cài đặt gateway

| Biến | Mặc định | Mục đích |
| - | - | - |
| `AI_ENABLED` | `false` | Đặt chính xác là `true` để bật trò chuyện và gợi ý sửa lỗi cho phiên bản. Nếu không đặt hoặc đặt giá trị khác, các tính năng này vẫn bị tắt. Cũng cần có cấu hình gateway hoạt động được. |
| `AI_BASE_URL` | Không có; bắt buộc | URL gốc của API tương thích OpenAI. |
| `AI_API_KEY` | Không có; bắt buộc | API key của gateway đó, được máy chủ sử dụng. |
| `AI_MODEL` | Không có; bắt buộc | Mô hình văn bản được dùng bởi cấu hình trò chuyện mặc định và bởi tính năng gợi ý sửa lỗi LaTeX. |
| `AI_IMAGE_MODEL` | Không đặt | Mô hình hỗ trợ hình ảnh tùy chọn trên cùng gateway, dùng cùng API key. |
| `AI_PDF_MODEL` | Không đặt | Mô hình tùy chọn trên cùng gateway cho các cuộc trò chuyện có tệp PDF, dùng cùng API key. Từ v6.4.0. |
| `AI_MAX_STEPS` | `20` | Số lần gọi công cụ tối đa cho mỗi tin nhắn của người dùng trong trò chuyện AI, bao gồm cả các lần tiếp tục tự động. Dùng một số nguyên dương. |
| `AI_PROXY_URL` | Không đặt | URL proxy HTTP tùy chọn cho các lời gọi tới gateway AI. Biến này không cấu hình các client tìm kiếm web hoặc tìm kiếm tài liệu. |
| `AI_TOKEN_QUOTA` | `0` | Giới hạn token cho mỗi người dùng, dùng chung cho trò chuyện và gợi ý sửa lỗi trong mỗi chu kỳ. Không đặt hoặc `0` nghĩa là không giới hạn; dùng một số nguyên dương để đặt giới hạn. |
| `AI_TOKEN_QUOTA_PERIOD` | `month` | `month` đặt lại vào ngày đầu tiên lúc 00:00 UTC; `week` đặt lại vào thứ Hai lúc 00:00 UTC. Các giá trị khác sẽ dùng `month`. |

Để tải ảnh lên, hãy đặt `AI_IMAGE_MODEL` là một mô hình chấp nhận đầu vào hình ảnh và hỗ trợ các công cụ mà tính năng trò chuyện sử dụng. Mọi yêu cầu trò chuyện có lịch sử chứa ảnh đính kèm đều dùng mô hình này, kể cả các tin nhắn sau đó trong cuộc hội thoại. Nếu không có cài đặt này, các yêu cầu có hình ảnh sẽ dùng mô hình trò chuyện thông thường, và mô hình đó phải tự hỗ trợ hình ảnh. Gợi ý sửa lỗi LaTeX vẫn tiếp tục dùng `AI_MODEL`.

Tệp PDF đính kèm được giới thiệu từ v6.4.0 trở lên. Người dùng có thể đính kèm tệp PDF có dung lượng tối đa 2 MB, giống như hình ảnh. Tính năng trò chuyện gửi nguyên trạng từng tệp PDF dưới dạng một phần `file` của Chat Completions, vì vậy gateway và mô hình phải chấp nhận đầu vào PDF: các mô hình vision của OpenAI hỗ trợ điều này, trong khi nhiều gateway tự triển khai, chẳng hạn như vLLM, chấp nhận hình ảnh nhưng từ chối tệp PDF. Hãy đặt `AI_PDF_MODEL` là một mô hình đọc được tệp PDF; mọi cuộc trò chuyện có lịch sử chứa tệp PDF đều dùng mô hình này, kể cả các tin nhắn sau đó và mọi hình ảnh trong cuộc hội thoại, vì vậy mô hình này cũng nên chấp nhận hình ảnh. Nếu không có cài đặt này, các cuộc trò chuyện có PDF sẽ dùng `AI_MODEL`. Khi mô hình từ chối một tệp PDF, tính năng trò chuyện sẽ nhắc người dùng yêu cầu quản trị viên đặt `AI_PDF_MODEL`.

Ví dụ, để bật mô hình hình ảnh và hạn mức AI theo tuần:

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

### Quyền truy cập và sự đồng ý của người dùng

Tính khả dụng trên phiên bản và quyền của người dùng là hai vấn đề riêng biệt. `AI_ENABLED` và cấu hình gateway kiểm soát tính khả dụng trên phiên bản. Người dùng đã đăng nhập cũng phải vượt qua kiểm tra tài khoản hiện có: `aiFeatures.enabled` không được là `false`. Trường cơ sở dữ liệu hiện có này kiểm soát cả trò chuyện lẫn gợi ý sửa lỗi LaTeX. Khi trường này không được đặt, các tính năng AI được bật cho người dùng.

`AI_TOKEN_QUOTA` là một giới hạn được áp dụng như nhau cho mỗi người dùng được cấp quyền; mô-đun hiện tại không cung cấp giới hạn dạng số riêng cho từng tài khoản.

Trong danh sách người dùng của trang quản trị, hãy chọn một người dùng và mở **Update account info → AI features**. **Enable AI features** sẽ cập nhật `aiFeatures.enabled` khi các thay đổi tài khoản được lưu. Máy chủ kiểm tra quyền hiện tại trên các yêu cầu AI mới, bao gồm cả yêu cầu từ trình soạn thảo đang mở. Người dùng không có quyền vẫn thấy trợ lý AI trong trình soạn thảo, nhưng không thể gửi tin nhắn.

### Mức sử dụng và đặt lại

Tab AI features trong trang quản trị hiển thị **Usage** (mức sử dụng), **Limit** (giới hạn) của chu kỳ hiện tại và nút **Reset** trên cùng một hàng. Mức sử dụng được đọc khi tab được mở; nó không được làm mới liên tục. Hãy mở lại tab sau khi một cuộc trò chuyện hoặc gợi ý sửa lỗi kết thúc để xem số liệu mới nhất. Reset có hiệu lực ngay lập tức và chỉ xóa bộ đếm của chu kỳ hiện tại của người dùng đó, sau đó tải lại mức sử dụng được hiển thị. Thao tác này không yêu cầu lưu phần còn lại của biểu mẫu tài khoản.

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

Mức sử dụng của trò chuyện và gợi ý sửa lỗi dùng chung một bộ đếm Redis, được cập nhật từ tổng số token do nhà cung cấp mô hình báo cáo sau khi yêu cầu hoàn tất. Số này bao gồm token đầu vào và đầu ra qua các bước của mô hình. Đầu vào có thể bao gồm lịch sử hội thoại, ngữ cảnh tài liệu và kết quả công cụ, vì vậy một câu hỏi tiếp theo có thể tiêu tốn nhiều token hơn so với riêng tin nhắn mới. Mức sử dụng vẫn được ghi lại ngay cả khi giới hạn là **Unlimited**. Các yêu cầu không có tổng token được báo cáo sẽ không được cộng vào bộ đếm; mô-đun không thể tái tạo lại mức sử dụng trong quá khứ chưa được ghi nhận.

Việc kiểm tra hạn mức diễn ra trước khi streaming. Một yêu cầu, hoặc nhiều yêu cầu đồng thời, có thể vượt quá hạn mức còn lại trước khi các yêu cầu sau bị chặn. Đây là hạn mức sử dụng chứ không phải giới hạn chi tiêu nghiêm ngặt của nhà cung cấp. Nếu việc tra cứu hạn mức thất bại, yêu cầu vẫn được cho phép và lỗi sẽ được ghi log.

Cả hai tính năng đều dùng `AI_TOKEN_QUOTA`; gợi ý sửa lỗi không có giới hạn riêng về số lượng yêu cầu. Việc đặt lại bộ đếm không làm thay đổi quyền, sự đồng ý, giới hạn đã cấu hình hay hồ sơ thanh toán của chính nhà cung cấp. Các bộ đếm dùng khóa chu kỳ theo UTC và hết hạn sau 40 ngày; giữ lại dữ liệu Redis sẽ bảo toàn mức sử dụng hiện tại qua các lần khởi động lại ứng dụng.

### Các dịch vụ tìm kiếm tùy chọn

Tìm kiếm web sử dụng API tương thích Tavily. Tính năng này khả dụng khi đã cấu hình search API key. Các cài đặt này độc lập với gateway AI:

| Biến | Mặc định | Mục đích |
| - | - | - |
| `TAVILY_API_KEY` | Không đặt | API key tìm kiếm. Được ưu tiên hơn `WEB_SEARCH_API_KEY`. |
| `WEB_SEARCH_API_KEY` | Không đặt | Tên thay thế cho API key tìm kiếm. |
| `WEB_SEARCH_URL` | `https://api.tavily.com/search` | Endpoint tìm kiếm; các endpoint tùy chỉnh phải chấp nhận định dạng yêu cầu và phản hồi của Tavily. |
| `WEB_SEARCH_MAX_RESULTS` | `5` | Số kết quả yêu cầu cho mỗi lần tìm kiếm; dùng một số nguyên dương mà dịch vụ hỗ trợ. |
| `WEB_SEARCH_DEPTH` | `basic` | Độ sâu tìm kiếm, thường là `basic` hoặc `advanced`. |
| `WEB_SEARCH_PROVIDER` | `tavily` | Triển khai hiện tại chỉ hỗ trợ giao thức tương thích Tavily; thay đổi giá trị này không chọn được adapter khác. |
| `DOCS_MCP_URL` | `https://docs.overleaf.com/~gitbook/mcp` | Endpoint tìm kiếm tài liệu. Đặt thành chuỗi rỗng để tắt tìm kiếm tài liệu. |

Ví dụ:

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

Tìm kiếm tài liệu gọi công cụ `searchDocumentation` của endpoint GitBook MCP đã cấu hình và chấp nhận phản hồi dạng JSON hoặc SSE. Đây là một MCP client dùng cho tìm kiếm tài liệu. Để cho phép các AI client bên ngoài Ayakaleaf làm việc trên một dự án, xem [MCP Server](https://ayakaleaf-pro.mintlify.site/vi/on-premises/configuration/overleaf-toolkit/integrations/mcp-server.md).

Tính năng đọc trang web được giới thiệu từ v6.4.0 trở lên. Tính năng trò chuyện có thể đọc một trang theo URL của nó, chẳng hạn như một liên kết do người dùng cung cấp hoặc một kết quả tìm kiếm. Nó tải trang thông qua linked URL proxy, cùng dịch vụ dùng để tải tệp từ URL bên ngoài, vì vậy các hạn chế mạng được mô tả trong [External URL](https://ayakaleaf-pro.mintlify.site/vi/on-premises/configuration/overleaf-toolkit/external-url.md) cũng áp dụng cho nó. Không cần thiết lập thêm.

Các truy vấn tìm kiếm được gửi tới dịch vụ tìm kiếm đã cấu hình. Kết quả tìm kiếm sau đó có thể được đưa vào các yêu cầu gửi tới gateway AI. Menu **Tools** của tính năng trò chuyện cho phép người dùng bật hoặc tắt **Web** và **Documentation** cho các yêu cầu của mình; một công cụ cũng phải được cấu hình trên máy chủ thì mô hình mới có thể sử dụng.

### Hỏi & Đáp

> [accordion] Trợ lý AI không xuất hiện trong trình soạn thảo
>
> **Trả lời:** Trợ lý AI chỉ xuất hiện trong thanh bên trái của trình soạn thảo khi `AI_ENABLED=true` và `AI_BASE_URL`, `AI_API_KEY` và `AI_MODEL` đều đã được đặt. Nếu thiếu một trong số đó, trợ lý AI sẽ bị ẩn đối với mọi người dùng.
>
> Sau khi thay đổi `config/variables.env`, hãy tạo lại container bằng `bin/up -d`. Chỉ làm mới trình duyệt sẽ không áp dụng các biến mới. Công tắc **Enable AI features** trong trang quản trị không hiển thị hay ẩn trợ lý AI; nó chỉ quyết định người dùng có thể gửi tin nhắn hay không.

> [accordion] Tôi gửi tin nhắn nhưng trợ lý AI không trả lời
>
> **Trả lời:** Trước tiên, hãy kiểm tra xem người dùng đã chấp nhận thẻ đồng ý AI hiển thị trong trợ lý AI hay chưa. Không thể gửi tin nhắn trước khi chấp nhận.
>
> Sau đó, hãy tìm lỗi trong log của dịch vụ web:
>
> ```sh theme={null}
> bin/logs web
> ```
>
> | Thông báo log | Ý nghĩa |
> | - | - |
> | `workbench AI chat requested but no AI gateway is configured` | Thiếu một trong các biến `AI_ENABLED`, `AI_BASE_URL`, `AI_API_KEY` hoặc `AI_MODEL` trong container đang chạy. Hãy tạo lại container bằng `bin/up -d`. |
> | `workbench chat stream error` | Gateway trả về lỗi. Người dùng thấy thông báo "The AI service returned an error". Lỗi được ghi log hiển thị mã trạng thái và thông báo của gateway. |
> | `workbench chat failed` | Yêu cầu thất bại trước hoặc trong khi streaming, ví dụ vì không thể kết nối tới gateway. |
>
> Nếu bảng điều khiển của nhà cung cấp không hiển thị mức sử dụng nào, yêu cầu đã không tới được nhà cung cấp. Các nguyên nhân phổ biến là:
>
> * `AI_BASE_URL` sai, ví dụ thiếu hoặc thừa `/v1`, hoặc bị thêm `/chat/completions` vào cuối.
> * Máy chủ không thể kết nối tới gateway. Nếu lưu lượng đi ra phải qua proxy, hãy đặt `AI_PROXY_URL`.
> * `AI_MODEL` không phải là ID mô hình mà gateway nhận biết.
>
> Nếu nhà cung cấp có hiển thị yêu cầu nhưng tính năng trò chuyện vẫn thất bại, hãy kiểm tra xem mô hình có hỗ trợ streaming chat completions và function tools hay không.

> [accordion] Lịch sử trò chuyện có được lưu lại không?
>
> **Trả lời:** Không. Một cuộc trò chuyện chỉ được giữ trong tab trình duyệt đang mở. Làm mới hoặc đóng trang sẽ xóa nó, và **Start new chat** sẽ thay thế cuộc trò chuyện hiện tại. Không có danh sách các cuộc trò chuyện trước đó, và mỗi dự án chỉ hiển thị một cuộc trò chuyện tại một thời điểm.


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