Plugin
Libre WebUI dùng plugin để kết nối với nhà cung cấp AI bên ngoài và bổ sung các khả năng mô hình ngoài Ollama cục bộ.
Loại plugin
| Loại | Mục đích |
|---|---|
| Trò chuyện/hoàn tất | Mô hình văn bản và trò chuyện từ API nhà cung cấp |
| Embedding | Embedding vector cho tìm kiếm tài liệu và bộ nhớ |
| Tạo hình ảnh | Mô hình hình ảnh và backend kiểu ComfyUI |
| Văn bản thành giọng nói | Nhà cung cấp tổng hợp giọng nói |
| Giọng nói thành văn bản | Nhà cung cấp phiên âm |
| Tạo âm thanh | Nhà cung cấp tạo âm thanh |
| Tạo video | Nhà cung cấp tạo video bất đồng bộ |
Plugin có thể cung cấp ánh xạ mô hình tĩnh và, khi được hỗ trợ, làm mới các mô hình khả dụng từ API nhà cung cấp.
Nhóm nhà cung cấp tích hợp
Libre WebUI có định nghĩa nhà cung cấp cho các dịch vụ phổ biến:
- OpenAI và API tương thích OpenAI
- Anthropic
- Google Gemini
- Groq
- Kimi Code của Moonshot AI
- Mistral
- OpenRouter
- Hugging Face
- GitHub Models
- MLX LM cho suy luận Apple Silicon cục bộ
- ComfyUI
- ElevenLabs
Danh mục nhà cung cấp thay đổi thường xuyên. Khi plugin hỗ trợ khám phá mô hình trực tiếp, hãy xem giao diện là nguồn thông tin chính xác.
Quyền sở hữu và ủy quyền
Định nghĩa plugin là cấu hình dùng chung của phiên bản. Mọi tuyến /api/plugins đều cần xác thực, và chỉ quản trị viên có thể tải lên, cài đặt, cập nhật hoặc xóa định nghĩa. Kích hoạt thì khác: mỗi người dùng đã xác thực chỉ có thể bật hoặc tắt plugin dùng chung cho tài khoản mình. Trạng thái đó được lưu trong SQLite và tồn tại qua khởi động lại backend mà không ảnh hưởng nhà cung cấp đang hoạt động của người khác.
Khi nâng cấp, danh sách kích hoạt toàn cục cũ .status.json được sao chép một lần vào các tài khoản hiện có, nhưng chỉ với định nghĩa khớp chính xác điểm neo tin cậy đã biên dịch của Libre WebUI. Định nghĩa tùy chỉnh hoặc che khuất cũ vẫn bị cách ly và không hoạt động. Tài khoản tạo sau lần di chuyển đó bắt đầu không có plugin nào được bật.
Định nghĩa tích hợp sẵn chỉ được tin cậy khi nội dung chuẩn hóa khớp với hàm băm được biên dịch vào backend. Định nghĩa có thể ghi được phê duyệt trong SQLite theo đường dẫn nguồn chuẩn hóa và hàm băm đầy đủ. Khi quản trị viên cài đặt, cập nhật hoặc nhập lại, hệ thống sẽ ghi nhận phê duyệt; việc sửa trực tiếp tệp sẽ vô hiệu hóa phê duyệt đó. Quy trình phê duyệt và cập nhật xóa trạng thái kích hoạt của mọi tài khoản trước khi thay tệp, nên mỗi người dùng phải kích hoạt lại định nghĩa đã xem xét. Định nghĩa tùy chỉnh có từ trước khi nâng cấp phải được quản trị viên nhập lại trước khi xuất hiện trong danh mục, tham gia khám phá mô hình, nhận thông tin xác thực hoặc thực thi bất kỳ khả năng nào.
Các biến plugin được chia theo mục đích. Chỉ quản trị viên mới có thể lưu những biến định tuyến kết nối đã được nhận diện:
endpoint, base_url, api_path, models_endpoint, api_url,
image_endpoint, embedding_endpoint, stt_endpoint, tts_endpoint,
voice_clone_endpoint, api_mode, model và model_id. Các biến
config.endpoint_variable, config.models_endpoint_variable hoặc
config.voice_clone_endpoint_variable do một khả năng khai báo cũng được xem là định tuyến kết nối, ngay cả khi dùng tên khác.
Người dùng không phải quản trị viên vẫn có thể lưu các điều khiển tạo sinh như nhiệt độ và tùy chọn truyền luồng. Những hàng định tuyến cũ thuộc về người dùng không phải quản trị viên sẽ bị bỏ qua, không được trả về dưới dạng giá trị đã cấu hình và bị xóa khi tài khoản đó đặt lại toàn bộ biến plugin. Điều này ngăn việc thăng vai trò sau này âm thầm kích hoạt lại một tuyến đang không hoạt động.
Thông tin xác thực
Thông tin xác thực có thể đến từ biến môi trường hoặc cài đặt người dùng.
Ví dụ về biến môi trường:
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROQ_API_KEY=gsk_...
GEMINI_API_KEY=...
MISTRAL_API_KEY=...
OPENROUTER_API_KEY=sk-or-...
KIMI_API_KEY=...
GITHUB_API_KEY=github_pat_...
ELEVENLABS_API_KEY=...
Với bản triển khai dùng chung, thông tin xác thực ở cấp người dùng thường phù hợp hơn vì mỗi người tự kiểm soát chi phí và giới hạn của nhà cung cấp. Khóa môi trường hữu ích cho bản cài đặt một người dùng, bản dùng thử hoặc bản triển khai được quản lý.
Khóa môi trường chỉ là phương án dự phòng khi yêu cầu sử dụng phép chiếu định tuyến và xác thực từ một định nghĩa plugin tích hợp sẵn không bị che khuất. Định nghĩa được nhập, định nghĩa có thể ghi che khuất ID tích hợp sẵn hoặc giá trị ghi đè định tuyến kết nối do quản trị viên lưu đều yêu cầu thông tin xác thực do chính tài khoản đó lưu. Trước khi cho phép dùng biến môi trường dự phòng, Libre WebUI so sánh endpoint gốc, các trường xác thực, endpoint và bộ chọn biến endpoint của khả năng, cùng định nghĩa và giá trị mặc định của những biến định tuyến đã được nhận diện. Hàm băm manifest đã biên dịch vẫn là nguồn quyết định, kể cả khi thư mục plugin kiểu cũ và thư mục plugin tích hợp dùng chung đường dẫn như trong bố cục vùng chứa tiêu chuẩn; manifest gói bị ghi đè không thể tự thiết lập độ tin cậy.
Quy tắc này áp dụng cho khám phá, Chat, Work, kiểm tra tính khả dụng và danh mục khả năng. Nó ngăn endpoint tùy chỉnh hoặc manifest tùy chỉnh có từ trước khi nâng cấp nhận được bí mật do người vận hành quản lý.
Thông tin xác thực do người dùng lưu được liên kết với nguồn định nghĩa đang có hiệu lực, hàm băm đầy đủ của định nghĩa, hợp đồng xác thực, endpoint và bộ chọn khả năng, cùng những giá trị định tuyến có hiệu lực tại thời điểm lưu. Khi tuyến hoặc định nghĩa thay đổi, thông tin xác thực cũ sẽ không khả dụng cho đến khi người dùng xem lại đích mới và lưu lại thông tin xác thực. Thông tin xác thực kiểu cũ chưa có liên kết chỉ được chấp nhận trên tuyến tích hợp sẵn khớp chính xác với điểm neo tin cậy; lần sử dụng thành công đầu tiên sẽ ghi liên kết trước khi trả về khóa đã giải mã.
Nhà cung cấp tương thích OpenAI
Nhiều nhà cung cấp cung cấp API tương thích OpenAI. Plugin có thể định nghĩa:
- URL endpoint API đầy đủ
- Biến môi trường chứa khóa API
- Hành vi của endpoint Chat
- Hỗ trợ embedding
- Hành vi khám phá mô hình
- Bản đồ mô hình dự phòng tùy chọn
Nếu nhà cung cấp không hỗ trợ khám phá mô hình trực tiếp, Libre WebUI sẽ dùng bản đồ mô hình đã cấu hình. JSON plugin được nhập dùng để cấu hình các nhà cung cấp vốn đã giao tiếp bằng một trong những định dạng được Libre WebUI hỗ trợ: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages hoặc Gemini. Chỉ riêng JSON không thể chuyển đổi một giao thức độc quyền bất kỳ; nhà cung cấp có cấu trúc yêu cầu, truyền luồng, lệnh gọi công cụ hoặc phản hồi khác cần một bộ điều hợp nhỏ ở backend.
Tạo hình ảnh OpenAI
Nhà cung cấp OpenAI tích hợp sẵn cung cấp Image API tại https://api.openai.com/v1/images/generations. gpt-image-2 là mô hình hiện tại. Danh mục cũng giữ lại các ID gpt-image-1.5, gpt-image-1 và gpt-image-1-mini đã bị đánh dấu không còn khuyến nghị để phục vụ những bản triển khai tương thích hiện có; cấu hình mới nên chọn gpt-image-2.
Tính năng tạo hình ảnh dùng cùng thông tin xác thực OpenAI có hiệu lực như Chat: khóa đã lưu của người dùng hiện tại hoặc cơ chế dùng biến môi trường dự phòng của nhà cung cấp tích hợp sẵn đáng tin cậy. Tính năng này có giá trị ghi đè image_endpoint tùy chọn và riêng biệt để endpoint Chat tùy chỉnh không vô tình nhận yêu cầu hình ảnh. Hãy để trống image_endpoint để kế thừa endpoint Image API tích hợp sẵn.
Lựa chọn mô hình hình ảnh được gắn với danh tính nhà cung cấp. Khi hai plugin hình ảnh cung cấp cùng một ID mô hình, Libre WebUI chỉ gửi yêu cầu đến nhà cung cấp được chọn trong bảng hình ảnh. Phản hồi GPT Image dùng dữ liệu hình ảnh base64; Libre WebUI chuyển dữ liệu đó thành hình ảnh trong ứng dụng rồi lưu vào thư viện của người dùng hiện tại. Tuyến Image API yêu cầu xác thực, và yêu cầu tạo trực tiếp phải chứa cả pluginId lẫn model. Yêu cầu có thể đặt n thành số nguyên JSON từ 1 đến 10; chuỗi số và giá trị thập phân bị từ chối trước khi đến nhà cung cấp.
Chế độ API Chat Completions và Responses
Plugin hoàn tất tương thích OpenAI có thể dùng ngữ nghĩa yêu cầu chat_completions hoặc responses. Plugin OpenAI tích hợp sẵn cung cấp lựa chọn này trong Settings → Plugins.
Cài đặt kết nối được xác định theo thứ tự sau:
- Giá trị ghi đè
endpointđầy đủ, khi được cấu hình. base_urlcộng vớiapi_pathtùy chọn.endpointkiểu cũ của plugin.
Giá trị endpoint khớp chính xác với endpoint trong manifest plugin được xem là giá trị mặc định của manifest, không phải giá trị ghi đè. Cách xử lý này ngăn giá trị mặc định kiểu cũ đã lưu che khuất Base URL mới sau khi nâng cấp. Endpoint đầy đủ thực sự tùy chỉnh vẫn có mức ưu tiên cao nhất.
Đường dẫn mặc định là /chat/completions trong chế độ Chat Completions và /responses trong chế độ Responses. base_url phải là gốc API, chẳng hạn https://api.example.com/v1; dùng api_path khi nhà cung cấp tương thích cung cấp thao tác tại đường dẫn tương đối khác. Endpoint đầy đủ phải chứa toàn bộ đường dẫn thao tác và được ưu tiên hơn cả hai trường. Hậu tố đã biết /chat/completions, /completions hoặc /responses có tính quyết định đối với ngữ nghĩa yêu cầu; đường dẫn endpoint tùy chỉnh giữ nguyên api_mode đã chọn.
JSON plugin được nhập có thể cung cấp cùng các giá trị mặc định:
{
"endpoint": "https://api.example.com/v1/chat/completions",
"api_mode": "responses",
"base_url": "https://api.example.com/v1",
"api_path": "/responses"
}
Yêu cầu Responses dùng input, max_output_tokens, công cụ hàm được làm phẳng, store: false và yêu cầu nội dung suy luận được mã hóa để tiếp tục mà không cần trạng thái phía nhà cung cấp. Đầu ra Responses hoàn tất và truyền theo luồng được chuẩn hóa trở lại định dạng sự kiện Chat và Work của Libre WebUI. Trạng thái phát lại chỉ được giữ khi toàn bộ mảng Item đầu ra có thứ tự không vượt quá 64 Items và 90 KB; các Item được giữ nguyên chính xác và không bao giờ bị cắt bớt trường. Item có thể phát lại phải có ID và kiểu duy nhất, không rỗng; cấu trúc tin nhắn, suy luận và lệnh gọi hàm được xác thực trước khi phát ra bất kỳ lệnh gọi công cụ nào. Trạng thái Chat quá lớn sẽ quay về lịch sử hiển thị đã chuẩn hóa. Chat cũng loại bỏ Item lệnh gọi hàm nguyên bản vì Chat không lưu đầu ra công cụ tương ứng. Phản hồi Work có công cụ nhưng thiếu trạng thái phát lại chính xác và có giới hạn sẽ bị từ chối trước mọi hiệu ứng phụ của công cụ.
Bộ nhớ Chat dựa trên SQLite mã hóa trạng thái nhà cung cấp được giữ lại cùng tin nhắn; Work lưu trạng thái chỉ dành cho công cụ trong các hàng ngữ cảnh ẩn không được API tin nhắn trả về. Một phạm vi được băm liên kết việc phát lại với cùng nhà cung cấp, mô hình, chế độ Responses, endpoint cuối đã cấu hình và dấu vân tay một chiều không thể đọc ngược của thông tin xác thực đã chọn. Khi phạm vi đó thay đổi, kể cả sau khi xoay vòng khóa API, Libre WebUI quay về lịch sử tin nhắn đã chuẩn hóa thay vì gửi các Item dành riêng cho nhà cung cấp qua ranh giới xác thực. Lượt chạy Work đang hoạt động cũng tạo dấu vân tay cho tuyến và thông tin xác thực rồi xác thực lại ngay trước mỗi vòng với nhà cung cấp; việc thay đổi chế độ, endpoint hoặc khóa API sẽ dừng lượt chạy trước khi một yêu cầu khác có thể nhận trạng thái công cụ trước đó.
Trạng thái có công cụ phải vừa với cả giới hạn phát lại lẫn lớp bọc siêu dữ liệu bền vững hoàn chỉnh 100 KB trước khi Work thực hiện hiệu ứng phụ. Nếu một lô Work đã lưu bền vững bị gián đoạn, mọi kết quả công cụ còn thiếu sẽ được khôi phục với đúng ID lệnh gọi và cảnh báo chưa biết kết quả, để nhà cung cấp có thể kiểm tra không gian làm việc thay vì mù quáng lặp lại một hiệu ứng phụ có thể đã xảy ra. Kết quả Responses chưa hoàn tất không được xem là lượt Chat hoặc Work thành công; incomplete_details.reason của kết quả đó được giữ lại và cung cấp cho bên gọi.
Quá trình khám phá mô hình suy ra /models từ một trong hai đường dẫn thao tác. Ví dụ, https://api.example.com/v1/responses dùng https://api.example.com/v1/models để khám phá. Nhà cung cấp không có endpoint danh sách mô hình tương thích vẫn có thể dùng model_map thủ công. Khám phá được giới hạn theo biến và thông tin xác thực của người dùng hiện tại. Kết quả được lưu bền vững theo từng người dùng thay vì ghi vào manifest plugin dùng chung. Khám phá chạy sau khi kích hoạt, làm mới rõ ràng, thay đổi khóa API, thay đổi biến kết nối và đặt lại biến; việc lưu biến tạo sinh không liên quan không kích hoạt yêu cầu mạng.
Khám phá cũng tự chạy. Khi danh sách plugin được đọc, hệ thống khám phá lại mọi nhà cung cấp hoàn tất đang hoạt động nếu danh mục bị thiếu hoặc cũ hơn PLUGIN_MODEL_DISCOVERY_TTL_MS; vì vậy, tải lại ứng dụng sẽ phản ánh các mô hình hiện tại của nhà cung cấp thay vì danh mục tại thời điểm kích hoạt. Cơ chế giãn thời gian thử lại riêng cho từng nhà cung cấp tránh việc thăm dò một nhà cung cấp không thể truy cập trong mọi yêu cầu, còn thời hạn ngăn nhà cung cấp chậm làm trì hoãn phản hồi; nếu lượt làm mới vượt quá thời hạn, kết quả sẽ được phục vụ ở yêu cầu tiếp theo.
URL khám phá cuối được suy ra sẽ được kiểm tra trước khi đọc thông tin xác thực của người dùng hoặc tạo tiêu đề ủy quyền, kể cả khi URL bắt nguồn từ manifest plugin được nhập. Yêu cầu khám phá và khả năng nhà cung cấp không đi theo chuyển hướng HTTP. Hãy cấu hình trực tiếp endpoint cuối cho Chat, Work, danh sách mô hình, hình ảnh, embedding, phiên âm, giọng nói, nhân bản giọng nói, âm thanh hoặc video; điều này ngăn thông tin xác thực bị chuyển tiếp từ URL đã xác thực sang đích chuyển hướng chưa được xác thực.
Endpoint nhà cung cấp có thể dùng HTTP hoặc HTTPS. HTTP gửi khóa API, câu lệnh, kết quả công cụ và nội dung được tạo mà không mã hóa khi truyền, vì vậy chỉ dùng HTTP cho cổng tự lưu trữ trên mạng bạn tin cậy; hãy ưu tiên HTTPS bất cứ khi nào cổng hỗ trợ TLS. Yêu cầu bắt nguồn từ backend. Trong bản triển khai vùng chứa, điều đó có nghĩa là dùng URL dịch vụ như http://ai-gateway:8080/v1, còn localhost chỉ chính vùng chứa Libre WebUI. Các tuyến khả năng plugin, gồm tạo hình ảnh, xác định biến endpoint và thông tin xác thực theo tài khoản đã xác thực đang gửi yêu cầu. Libre WebUI không có chế độ một người dùng không cần xác thực.
Endpoint theo từng khả năng
Giá trị ghi đè endpoint Chat được tách biệt khỏi khả năng hình ảnh, embedding, phiên âm, chuyển văn bản thành giọng nói, âm thanh và video. Plugin có nhiều khả năng có thể cung cấp image_endpoint, embedding_endpoint, stt_endpoint, tts_endpoint hoặc một biến khác được đặt tên bằng config.endpoint_variable. Tương tự, tuyến nhân bản giọng nói có thể chỉ định config.voice_clone_endpoint_variable. Để trống các trường đó sẽ dùng endpoint khả năng do plugin khai báo; endpoint Chat chung không bao giờ được dùng làm giá trị ghi đè cho khả năng.
Plugin GitHub Models tích hợp sẵn kế thừa endpoint models.github.ai/inference/chat/completions hiện tại khi giá trị ghi đè tùy chọn để trống. Plugin Hugging Face dùng các tuyến hf-inference/models/{model} cùng dữ liệu yêu cầu riêng theo tác vụ cho embedding, hình ảnh và chuyển văn bản thành giọng nói thay vì gửi các yêu cầu đó đến endpoint Chat.
Ghi đè endpoint
Biến endpoint là URL yêu cầu hoàn chỉnh, gồm cả đường dẫn thao tác. Ví dụ, plugin trò chuyện tương thích OpenAI thường dùng URL như https://provider.example/v1/chat/completions, không chỉ https://provider.example. Cấu hình plugin kiểu cũ được nhập có thể gọi biến này là api_url; Libre WebUI chấp nhận bí danh đó, nhưng endpoint không rỗng luôn được ưu tiên khi có cả hai trường.
Hệ thống chấp nhận URL endpoint HTTP và HTTPS tuyệt đối; những giao thức khác bị từ chối. HTTP dành cho cổng tự lưu trữ trên mạng tin cậy vì nó gửi thông tin xác thực và nội dung yêu cầu mà không mã hóa khi truyền. Hãy ưu tiên HTTPS cho mọi tuyến đi ra ngoài ranh giới triển khai riêng. Để trống giá trị ghi đè sẽ dùng endpoint đầy đủ trong định nghĩa plugin; giá trị ghi đè không hợp lệ được khai báo rõ ràng sẽ bị từ chối thay vì âm thầm định tuyến đến giá trị mặc định đó.
Yêu cầu nhà cung cấp không đi theo chuyển hướng. Hãy cấu hình trực tiếp URL thao tác cuối đã được xác thực; phản hồi chuyển hướng sẽ được báo là lỗi nhà cung cấp thay vì chuyển tiếp thông tin xác thực hoặc nội dung yêu cầu sang chặng khác.
Hãy nhớ rằng yêu cầu bắt nguồn từ backend Libre WebUI. Trong vùng chứa, localhost chỉ chính vùng chứa chứ không tự động chỉ máy chủ vùng chứa hoặc dịch vụ khác. Hãy dùng tên dịch vụ vùng chứa của cổng hoặc tên mà vùng chứa có thể truy cập như host.docker.internal khi môi trường chạy vùng chứa cung cấp tên đó.
Khám phá mô hình
Settings → Plugins có không gian Provider connections dành cho quy trình này. Tìm nhà cung cấp trong bảng bên trái, chọn nhà cung cấp đó rồi dùng bảng bên phải để xem trạng thái kích hoạt và danh mục mô hình thực tế. Cấu hình nhà cung cấp vẫn được thu gọn cho đến khi chọn Configure. Nhờ vậy, endpoint, thông tin xác thực và các điều khiển tạo sinh nâng cao không xuất hiện trong giao diện mặc định.
Với nhà cung cấp trò chuyện và hoàn tất, Refresh models chạy quá trình khám phá cho nhà cung cấp đã chọn, sau đó tải lại cả danh mục plugin lẫn danh sách mô hình của Chat. Danh mục chỉ cho phép đọc: các hàng được lấy từ ID đã phát hiện của người dùng hiện tại cùng bản đồ mô hình theo khả năng trong định nghĩa plugin. Nhãn khả năng mô tả tuyến plugin nào liệt kê mô hình; chúng không phải phép kiểm tra tình trạng hoạt động. Hãy thêm ID mô hình dự phòng hoặc được duy trì thủ công qua model_map trong JSON plugin, không sửa một hàng đã phát hiện.
Khi plugin được kích hoạt, Libre WebUI thử khám phá mô hình bằng endpoint và thông tin xác thực có hiệu lực của tài khoản đó. Tuyến tùy chỉnh của quản trị viên yêu cầu thông tin xác thực do chính tài khoản đó lưu; cơ chế dùng biến môi trường dự phòng chỉ được dùng với tuyến manifest đáng tin cậy. Với API tương thích, Libre WebUI suy ra URL danh sách mô hình từ endpoint đầy đủ:
- URL kết thúc bằng
/modelsđược dùng nguyên trạng; - hậu tố thao tác đã biết như
/chat/completions,/completions,/responses,/embeddingshoặc/messagesđược thay bằng/models; - nếu không,
/modelsđược nối vào đường dẫn.
Plugin không thể dùng URL được suy ra có thể cung cấp models_endpoint làm URL danh sách mô hình đầy đủ và rõ ràng. URL này được ưu tiên hơn phép suy ra, chịu cùng chính sách URL gửi ra ngoài và được gọi mà không đi theo chuyển hướng. Việc lưu hoặc đặt lại endpoint, api_url, models_endpoint, base_url, api_path hoặc api_mode sẽ xóa rồi làm mới danh mục đã phát hiện của người dùng hiện tại trước khi giao diện tải lại.
Mọi tuyến tùy chỉnh đều được phân giải và xác thực trước khi chọn thông tin xác thực. Chính sách thông tin xác thực không được dùng khóa trong môi trường máy chủ làm phương án dự phòng cho tuyến tùy chỉnh đã lưu; thay vào đó, hãy cấu hình khóa riêng theo người dùng cho tuyến đó. Cơ chế dùng biến môi trường dự phòng được dành riêng cho endpoint do định nghĩa plugin đáng tin cậy cung cấp.
Quá trình khám phá mong đợi phản hồi tương thích OpenAI chứa ID mô hình trong mảng data. Hoạt động kích hoạt sẽ chờ lần thử đó trước khi trả về để lần làm mới danh sách plugin đầu tiên có thể gồm danh mục đã phát hiện. Kết quả thành công được lưu riêng theo từng người dùng và phủ lên chế độ xem plugin của người dùng đó; Libre WebUI không ghi lại JSON plugin dùng chung hoặc tiết lộ ID mô hình đã phát hiện của người này cho tài khoản khác. Nếu nhà cung cấp không có endpoint danh sách mô hình tương thích, không thể truy cập hoặc trả về cấu trúc phản hồi khác, hoạt động kích hoạt thông thường sẽ giữ lại kết quả khám phá trước đó của người dùng. Việc chủ ý thay đổi trường kết nối sẽ xóa danh mục lỗi thời trước, do đó dùng model_map dự phòng của plugin khi không thể khám phá tuyến mới.
Việc lưu hoặc đặt lại định tuyến kết nối sẽ xóa danh mục đã phát hiện trước đó của tài khoản trước lần khám phá tiếp theo, vì vậy các mô hình được phát hiện từ một đích không thể tiếp tục được chọn sau khi đổi tuyến.
Trạng thái plugin, tính khả dụng của Work, danh mục mô hình và tuyến khả năng dùng cùng ngữ cảnh người dùng và ranh giới thông tin xác thực. Ví dụ, tính khả dụng của mô hình hình ảnh, biến endpoint và thông tin xác thực được xác định theo người dùng đang gửi yêu cầu.
Chọn chính xác nhà cung cấp trong Trò chuyện
ID mô hình không phải là duy nhất trên toàn hệ thống. Một mô hình Ollama và nhiều plugin đang hoạt động đều có thể cung cấp mô hình mang tên example-model. Vì vậy, Chat lưu ID mô hình nguyên bản cùng danh tính nhà cung cấp tùy chọn:
providerType: "ollama"xác định tuyến Ollama cục bộ hoặc đã cấu hình;providerType: "plugin"cộng vớiproviderIdxác định chính xác một plugin.
Giá trị được gắn với nhà cung cấp và mã hóa URL chỉ được dùng làm khóa tránh xung đột trong bộ chọn mô hình. Yêu cầu vẫn gửi ID mô hình nguyên bản của nhà cung cấp. Tên mô hình trùng nhau giữa Ollama/plugin và plugin/plugin vẫn là những lựa chọn riêng biệt, và việc mở lại cuộc trò chuyện sẽ khôi phục chính xác lựa chọn đã lưu.
Danh tính nhà cung cấp được chỉ định rõ sẽ bị từ chối theo nguyên tắc an toàn khi có lỗi. Nếu plugin đã chọn bị vô hiệu hóa, xóa hoặc không còn công bố mô hình đó, Libre WebUI vẫn hiển thị lựa chọn đã lưu ở trạng thái không khả dụng và không âm thầm chuyển sang nhà cung cấp khác có cùng tên mô hình. Hãy kích hoạt lại nhà cung cấp hoặc chọn rõ ràng mô hình khác trước khi tạo nội dung lần nữa.
Phiên và tùy chọn được tạo trước khi danh tính nhà cung cấp được lưu có thể để trống providerType và providerId hoặc đặt chúng thành null. Những bản ghi kiểu cũ này giữ nguyên tuyến lịch sử chỉ dựa trên tên để tương thích vì không thể tái dựng đáng tin cậy nhà cung cấp ban đầu. Bộ chọn hiển thị các bản ghi này là "provider not recorded" thay vì đoán nhãn Ollama hoặc plugin. Việc chọn một mục nhà cung cấp cụ thể sẽ ghi lại chính xác nhà cung cấp cho các yêu cầu sau. Persona mới chọn vẫn giữ danh tính giao diện persona:<id> và được ghi nhận là dùng Ollama ở nền.
Cài đặt và kế thừa nhà cung cấp
Mở Settings → Plugins rồi chọn Configure cho một nhà cung cấp. Bảng nhà cung cấp được thu gọn theo mặc định. Quản trị viên có thể quản lý định nghĩa dùng chung và giá trị định tuyến kết nối. Người dùng đã xác thực khác có thể kích hoạt nhà cung cấp, lưu khóa API riêng và thay đổi các điều khiển tạo sinh của mình, nhưng giao diện không cung cấp cho họ chức năng tải lên, cài đặt, xuất, xóa plugin hoặc điều khiển định tuyến.
Đối với quản trị viên, giá trị ghi đè kết nối xuất hiện trước. Các điều khiển lấy mẫu và điều khiển chuyên biệt khác vẫn nằm trong Advanced parameters, mục này cũng được thu gọn theo mặc định. Giá trị kết nối và tạo sinh kế thừa được hiển thị dưới dạng ô nhập trống kèm gợi ý mặc định của nhà cung cấp. Libre WebUI không sao chép giá trị mặc định trong manifest vào cài đặt đã lưu của tài khoản chỉ vì bảng được mở.
Thao tác lưu chỉ gửi những trường đã thay đổi trong phiên chỉnh sửa hiện tại. Xóa một giá trị không nhạy cảm đã lưu sẽ xóa giá trị ghi đè của tài khoản đó và khôi phục mặc định của nhà cung cấp; trường nhạy cảm được che và để trống sẽ không thay đổi. Reset to Defaults xóa mọi giá trị ghi đè biến mà tài khoản được phép quản lý. Nếu lưu hoặc đặt lại thất bại, trình chỉnh sửa vẫn hiển thị các giá trị chưa lưu để người dùng thử lại.
Sự khác biệt này đặc biệt quan trọng với endpoint tùy chỉnh: quản trị viên để trống endpoint để kế thừa URL tích hợp của plugin, hoặc nhập URL tương thích đầy đủ để ghi đè cho kết nối nhà cung cấp của quản trị viên đó.
Plugin trong Work
Ngoài Ollama và Ollama Cloud, Work có thể dùng các plugin completion và chat đang hoạt động. Lượt chạy Work do plugin hỗ trợ chỉ được chấp nhận khi:
- plugin đang hoạt động;
- mô hình của plugin có trong danh mục đã phát hiện của người dùng hiện tại hoặc bản đồ mô hình đã cấu hình của plugin; và
- quản trị viên hiện tại có thông tin xác thực khả dụng.
Work lưu kiểu nhà cung cấp và ID plugin đã chọn cùng cả tác vụ lẫn từng lượt chạy. Do đó, tuyến dựa trên chính xác nhà cung cấp đã lưu chứ không chỉ tên mô hình. Việc kích hoạt plugin có tên mô hình trùng với mô hình Ollama không thể âm thầm định tuyến lại tác vụ hiện có.
Work điều chỉnh lệnh gọi công cụ qua các định dạng yêu cầu/phản hồi gốc tương thích OpenAI, Anthropic và Gemini. Mô hình đã chọn phải hỗ trợ lệnh gọi công cụ ngay cả khi nhà cung cấp có chức năng hoàn tất trò chuyện thông thường. Nếu nhà cung cấp từ chối công cụ hoặc trả về phản hồi không tương thích, lượt chạy sẽ thất bại mà không chuyển sang nhà cung cấp khác.
Lượt chạy Work từ xa có thể gửi nhiều yêu cầu đến nhà cung cấp. Nhà cung cấp nhận câu lệnh hệ thống của Work, ngữ cảnh hội thoại, định nghĩa công cụ và các kết quả công cụ được yêu cầu. Kết quả công cụ có thể chứa tệp nguồn, danh sách thư mục hoặc đầu ra lệnh. Libre WebUI hiển thị trong Work một thông báo về nhà cung cấp từ xa theo từng người dùng và có thể đóng; người vận hành vẫn nên xem xét chính sách giá, lưu giữ dữ liệu và huấn luyện của nhà cung cấp trước khi bật dịch vụ cho dự án nhạy cảm.
Embedding
Plugin có khả năng embedding có thể xuất hiện trong cài đặt embedding tài liệu. Libre WebUI cũng phát hiện các mô hình embedding Ollama có khả năng phù hợp như nomic-embed-text, bge, e5, gte và những tên mô hình tương tự.
Khi không phát hiện mô hình embedding nào, giao diện dùng nomic-embed-text làm ứng viên cục bộ mặc định.
Lưu ý phát triển plugin
Định nghĩa plugin phải mô tả rõ khả năng và không được mô tả như thể nhà cung cấp hỗ trợ những tính năng thực tế không được cung cấp. Giữ bản đồ mô hình đủ nhỏ để hữu ích làm phương án dự phòng, đồng thời ưu tiên khám phá đối với nhà cung cấp có API danh sách mô hình nhanh và đáng tin cậy.
Khi thêm nhà cung cấp:
- Thêm định nghĩa plugin.
- Định nghĩa khóa thông tin xác thực hoặc các trường thông tin xác thực người dùng.
- Triển khai khám phá mô hình nếu nhà cung cấp có endpoint danh sách mô hình.
- Thêm ánh xạ yêu cầu cho trò chuyện, embedding, hình ảnh, TTS hoặc STT.
- Kiểm thử trạng thái thiếu khóa, khóa không hợp lệ và lỗi nhà cung cấp.