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 được tải lên khi sử dụng mô hình hỗ trợ hình ảnh.

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

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 các 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.
• features.aiUsageQuota thực tế của người dùng phải khớp với cấp không giới hạn đã cấu hình (mặc định là unlimited), hoặc quyền cũ features.aiErrorAssistant hiện có phải được bật. Các tính năng thực tế bao gồm cả các ghi đè tính năng tài khoản áp dụng được.

Chỉ bật hộp kiểm thôi không làm thay đổi gói của người dùng. Trường aiUsageQuota là một cấp quyền, không phải hạn mức token dạng số. AI_TOKEN_QUOTA là một giới hạn riêng đượ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ở. Hãy làm mới trình soạn thảo để cập nhật các điều khiển hiển thị sau khi thay đổi quyề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; các mô-đun này không cung cấp tệp dự án dưới dạng MCP server, cũng không cung cấp sổ đăng ký MCP server đa dụng.

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.