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.

Tính năng này được cung cấp bởi 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.

​

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:

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.

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.

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:

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:

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.

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

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.

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

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.

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:

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.

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.