Kết nối nhà cung cấp bên thứ ba và tự lưu trữ

Libre WebUI 0.16.0 bổ sung không gian chuyên biệt Provider connections trong Settings > Plugins. Tại đây, bạn có thể kích hoạt nhà cung cấp tích hợp sẵn, trỏ một plugin tương thích đến API khác, xem danh mục mô hình thực tế hoặc kết nối cổng tự lưu trữ trên mạng tin cậy.

Kết nối nhà cung cấp Libre WebUI với tìm kiếm, chọn nhà cung cấp, điều khiển kết nối, làm mới mô hình và danh mục khả năng theo nhà cung cấp.

Libre WebUI hiện hỗ trợ các định dạng giao tiếp nhà cung cấp sau:

OpenAI Chat Completions;
OpenAI Responses;
Anthropic Messages; và
nội dung và lệnh gọi hàm của Google Gemini.

Các định nghĩa Anthropic và Gemini tích hợp sẵn dùng bộ điều hợp chuyên biệt được chọn theo danh tính nhà cung cấp. Nhà cung cấp mới nhập sử dụng ngữ nghĩa OpenAI Chat Completions hoặc OpenAI Responses; việc trỏ nhà cung cấp đó đến API tương thích Anthropic hoặc Gemini không tự động chọn các bộ điều hợp tích hợp sẵn này. Nhà cung cấp có cấu trúc yêu cầu, luồng dữ liệu, lệnh gọi công cụ hoặc phản hồi khác cần một bộ điều hợp ở backend. JSON của plugin chỉ mô tả định tuyến và cấu hình, không chuyển đổi một giao thức không liên quan.

Mở trang kết nối nhà cung cấp

Đăng nhập và mở Settings > Plugins.
Tìm nhà cung cấp ở bảng bên trái.
Chọn một nhà cung cấp để xem trạng thái kích hoạt và danh mục mô hình thực tế.
Kích hoạt nhà cung cấp đó cho tài khoản của bạn.
Chỉ chọn Configure khi cần lưu thông tin xác thực hoặc ghi đè một cài đặt kết nối.

Khu vực cấu hình nhà cung cấp được thu gọn theo mặc định. Quản trị viên thấy các cài đặt kết nối trước; những điều khiển lấy mẫu như nhiệt độ và giới hạn token vẫn nằm trong mục Advanced parameters được thu gọn riêng. Giá trị mặc định kế thừa chỉ xuất hiện dưới dạng gợi ý, không được điền sẵn thành giá trị ghi đè cho tài khoản.

Định nghĩa plugin là cấu hình dùng chung cho toàn bộ phiên bản triển khai, nên chỉ quản trị viên mới có thể nhập, cài đặt, cập nhật hoặc xóa chúng. Mỗi người dùng đã xác thực tự quản lý trạng thái kích hoạt, thông tin xác thực và các cài đặt tạo sinh được phép của mình.

Thêm nhanh một kết nối

Settings > Connections là lối tắt cho trường hợp phổ biến: một endpoint tương thích OpenAI và một khóa API. Quản trị viên sẽ thấy một thẻ cho môi trường Ollama cục bộ cùng trạng thái hoạt động và phiên bản, danh sách các kết nối tương thích OpenAI hiện có và một biểu mẫu nhỏ để thêm kết nối mới.

Để thêm kết nối, bạn cần tên hiển thị, URL chat completions đầy đủ và khóa API tùy chọn. Libre WebUI tạo ID kết nối từ tên, cài đặt định nghĩa nhà cung cấp, lưu khóa ở phía máy chủ, kích hoạt kết nối và hỏi endpoint về các mô hình mà endpoint phục vụ. Những mô hình được phát hiện sẽ thay thế danh mục tạm thời và xuất hiện trong bộ chọn mô hình của Chat.

Mỗi hàng hiển thị endpoint, số lượng mô hình, trạng thái lưu khóa, nút bật/tắt kích hoạt, thao tác làm mới mô hình và thao tác xóa. Các tùy chọn nâng cao hơn — như chế độ Responses API, ghi đè Base URL, danh mục theo từng khả năng và chính sách tham số tạo sinh — vẫn nằm trong không gian Settings > Plugins đầy đủ hơn được mô tả ở trên.

Codex (đăng nhập ChatGPT)

Nhà cung cấp tích hợp sẵn Codex (ChatGPT) không cần khóa API. Khi tài khoản hệ điều hành trên máy chủ đã đăng nhập Codex CLI bằng codex login, nhà cung cấp này xuất hiện cho quản trị viên và cung cấp họ mô hình Codex được ghi trong tài liệu thông qua phiên ChatGPT. Token truy cập được đọc từ tệp auth.json của CLI, làm mới bằng chính OAuth client mà CLI sử dụng rồi ghi lại để CLI tiếp tục hoạt động; giá trị token không bao giờ xuất hiện trong nhật ký.

Vì các yêu cầu được gửi từ backend — không bao giờ từ bên trong vùng chứa tác vụ — những mô hình này cũng có thể vận hành Work qua vòng lặp công cụ được cô lập như bình thường. Nhà cung cấp chỉ dành cho quản trị viên vì mỗi lệnh gọi đều sử dụng gói thuê bao ChatGPT của chủ máy chủ. Ẩn hoàn toàn bằng CODEX_OAUTH_MODELS_ENABLED=false, hoặc dùng CODEX_HOME để trỏ đến một phiên đăng nhập khác.

Chọn nhà cung cấp tích hợp sẵn hoặc được nhập

Libre WebUI có các định nghĩa cho OpenAI, Anthropic, Gemini, Groq, Mistral, OpenRouter, Kimi Code của Moonshot AI, Hugging Face, GitHub Models, MLX LM cục bộ cùng những dịch vụ mô hình hoặc đa phương tiện khác. Hãy bắt đầu bằng một mục tích hợp sẵn khi giao thức và cơ chế xác thực của mục đó phù hợp với dịch vụ bạn muốn dùng.

Quản trị viên có thể nhập JSON plugin. Ví dụ cổng tương thích OpenAI tối thiểu:

{
  "id": "private-ai-gateway",
  "name": "Private AI Gateway",
  "type": "completion",
  "endpoint": "http://ai-gateway:8080/v1/chat/completions",
  "api_mode": "chat_completions",
  "auth": {
    "header": "Authorization",
    "prefix": "Bearer ",
    "key_env": "PRIVATE_AI_GATEWAY_API_KEY"
  },
  "model_map": ["gateway-chat"]
}

Nhập tệp từ Settings > Plugins, kích hoạt nhà cung cấp rồi lưu khóa API cho tài khoản sẽ dùng kết nối. Thêm các biến kết nối vào định nghĩa khi quản trị viên cần những trường có thể chỉnh sửa cho Base URL, đường dẫn, khám phá mô hình hoặc endpoint theo từng khả năng. Tệp plugins/openai.json tích hợp sẵn là một ví dụ đầy đủ.

Với cổng được chủ ý thiết lập không cần xác thực trên mạng tin cậy, hãy đặt cả auth.header và auth.key_env thành chuỗi rỗng rồi bỏ auth.prefix. Khi đó Libre WebUI sẽ không yêu cầu hoặc gửi khóa API cho plugin này.

Chọn Chat Completions hoặc Responses

Các plugin hoàn tất tương thích OpenAI có thể dùng một trong hai chế độ API:

Chế độ API	Đường dẫn yêu cầu mặc định	Trường yêu cầu thường dùng
`chat_completions`	`/chat/completions`	`messages`
`responses`	`/responses`	`input`

Nhà cung cấp OpenAI tích hợp sẵn hiển thị API Mode trong phần cấu hình. Libre WebUI ánh xạ đầu ra Responses đã hoàn tất và đang truyền theo luồng trở lại Chat và Work, bao gồm trạng thái phát lại có giới hạn cho quá trình suy luận và lệnh gọi công cụ.

Việc đổi chế độ sẽ thay đổi đường dẫn thao tác mặc định, nhưng không thay đổi giao thức mà máy chủ đầu nguồn sử dụng. Vì vậy, chỉ chọn Responses khi máy chủ đó triển khai cấu trúc yêu cầu và sự kiện Responses tương thích.

Cấu hình Base URL hoặc endpoint đầy đủ

Libre WebUI xác định tuyến hoàn tất theo thứ tự sau:

Giá trị ghi đè endpoint đầy đủ và khác mặc định.
base_url cộng api_path tùy chọn.
Endpoint được khai báo trong định nghĩa plugin.

Dùng Base URL cho gốc API:

https://gateway.example/v1

Khi không có đường dẫn tùy chỉnh, chế độ Chat Completions gửi yêu cầu đến:

https://gateway.example/v1/chat/completions

Thay vào đó, chế độ Responses gửi yêu cầu đến:

https://gateway.example/v1/responses

Dùng API Path khi nhà cung cấp cung cấp một thao tác tương thích tại đường dẫn khác tính từ gốc này. Chỉ dùng Legacy Full Endpoint khi cần cung cấp URL thao tác hoàn chỉnh; một endpoint đầy đủ thực sự được ưu tiên hơn Base URL và API Path.

Các hậu tố endpoint đã biết như /chat/completions, /completions và /responses cũng xác định ngữ nghĩa của yêu cầu. Một đường dẫn thao tác tùy chỉnh không được nhận diện sẽ giữ nguyên chế độ API đã chọn rõ ràng.

Sau khi đổi tuyến hoặc khóa API, hãy lưu lại nhà cung cấp trước khi kiểm tra trong Chat. Khi plugin khai báo xác thực, tuyến kết nối tùy chỉnh cần thông tin xác thực do chính tài khoản đó lưu. Plugin được chủ ý thiết lập không cần xác thực có thể để trống cả hai trường xác thực. Libre WebUI không gửi khóa trong biến môi trường do người vận hành quản lý đến đích do người dùng định nghĩa; cơ chế dùng khóa môi trường dự phòng chỉ dành cho tuyến tích hợp sẵn đáng tin cậy.

Khám phá và Duy trì ID Mô hình

Chọn một nhà cung cấp Chat đang hoạt động rồi dùng Refresh models để chạy quá trình khám phá. Libre WebUI sẽ tải lại cả danh mục của nhà cung cấp đã chọn và danh sách mô hình của Chat.

Quá trình khám phá cũng tự chạy: danh mục của một nhà cung cấp đang hoạt động sẽ được khám phá lại khi bị thiếu hoặc đã cũ hơn PLUGIN_MODEL_DISCOVERY_TTL_MS, nhờ đó các mô hình hiển thị luôn bám theo nhà cung cấp thay vì thời điểm bạn kích hoạt. Refresh models buộc hệ thống kiểm tra ngay và báo kết quả:

Kết quả	Ý nghĩa
Danh mục đã cập nhật	Nhà cung cấp phản hồi và danh sách mô hình khác với danh sách đã lưu
Danh mục đã là mới nhất	Nhà cung cấp phản hồi bằng cùng một danh sách
Cần khóa API	Không có khóa dùng được nên không gửi yêu cầu; danh mục trước đó vẫn được hiển thị
Không thể tải danh mục	Không thể kết nối tới nhà cung cấp hoặc phản hồi không chứa dữ liệu dùng được

Khóa chỉ được đặt trong biến môi trường sẽ không được dùng cho nhà cung cấp chạy bằng một định nghĩa đã cài đặt thay vì định nghĩa tích hợp sẵn; thông báo sẽ nêu rõ khi trường hợp này xảy ra. Các mô hình giọng nói, hình ảnh và embedding được tìm thấy trong danh mục nhà cung cấp sẽ xuất hiện tại đây cùng nhãn khả năng, nhưng không được đưa vào bộ chọn mô hình của Chat.

Với tuyến tương thích OpenAI, URL danh sách mô hình được suy ra như sau:

kết thúc /models thì dùng nguyên;
/chat/completions, /completions, /responses, /embeddings, /messages được thay bằng /models; hoặc
nếu không, thêm /models.

Ví dụ, cả hai tuyến hoàn tất sau đều tạo ra cùng một URL khám phá:

https://gateway.example/v1/chat/completions
https://gateway.example/v1/responses

-> https://gateway.example/v1/models

Nếu suy ra sai, khai báo models_endpoint trong variables:

{
  "name": "models_endpoint",
  "type": "string",
  "label": "Models Endpoint",
  "default": "https://gateway.example/v1/models"
}

Giá trị kế thừa hoặc lưu bởi quản trị viên được ưu tiên. Thuộc tính models_endpoint cấp cao không được đọc. Phản hồi phải có mảng data:

{
  "data": [{ "id": "gateway-chat" }, { "id": "gateway-code" }]
}

Các ID được phát hiện được lưu riêng theo từng người dùng và không ghi đè tệp plugin dùng chung. Nếu nhà cung cấp không hỗ trợ quy trình khám phá tương thích, hãy duy trì các ID mô hình dự phòng trong model_map của JSON plugin. Danh mục trong Provider connections chỉ cho phép đọc; nhãn khả năng mô tả tuyến plugin nào liệt kê mô hình, chứ không phải kết quả kiểm tra tình trạng hoạt động.

ID mô hình không phải là duy nhất trên toàn hệ thống. Chat lưu ID mô hình nguyên bản cùng danh tính chính xác của nhà cung cấp Ollama hoặc plugin, nên một mô hình Ollama và nhiều plugin có thể cùng cung cấp một tên mà vẫn an toàn. Nếu nhà cung cấp đã lưu không còn khả dụng, Libre WebUI sẽ đánh dấu lựa chọn đó là không khả dụng thay vì âm thầm định tuyến yêu cầu sang nhà cung cấp khác.

Cấu hình riêng tính năng tạo hình ảnh

Nhà cung cấp OpenAI tích hợp sẵn cung cấp tính năng tạo hình ảnh qua https://api.openai.com/v1/images/generations và hiện đặt gpt-image-2 làm mặc định cho cấu hình mới. Các ID GPT Image cũ hơn vẫn còn trong danh mục dự phòng để hỗ trợ những hệ thống triển khai tương thích hiện có.

Tuyến Chat và tuyến hình ảnh được chủ ý tách biệt. Base URL tùy chỉnh của Chat không tự động nhận yêu cầu hình ảnh. Hãy để trống image_endpoint để dùng endpoint hình ảnh được khai báo trong plugin, hoặc đặt giá trị này thành URL thao tác Image API tương thích và đầy đủ khi nhà cung cấp có hỗ trợ.

Lựa chọn mô hình hình ảnh cũng gắn với danh tính nhà cung cấp, giống như lựa chọn trong Chat. Nếu hai plugin đang hoạt động cung cấp cùng một ID mô hình hình ảnh, Libre WebUI chỉ gửi yêu cầu đến nhà cung cấp được chọn trong bảng hình ảnh.

Kết nối cổng HTTP một cách an toàn

Endpoint của nhà cung cấp có thể dùng URL HTTP hoặc HTTPS tuyệt đối. HTTP hữu ích cho cổng tự lưu trữ trên LAN, mạng Tailscale hoặc mạng vùng chứa riêng đáng tin cậy, nhưng sẽ truyền 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. Hãy ưu tiên HTTPS bất cứ khi nào tuyến đi qua ranh giới mạng hoặc cổng hỗ trợ TLS.

Các yêu cầu bắt nguồn từ backend của Libre WebUI, không phải từ trình duyệt. Hãy chọn một địa chỉ mà backend đó có thể truy cập:

Vị trí backend	Ví dụ về gốc nhà cung cấp
Tiến trình gốc trên cùng máy	`http://127.0.0.1:8081/v1`
Dịch vụ Docker Compose	`http://ai-gateway:8080/v1`
Từ vùng chứa đến máy chủ được hỗ trợ	`http://host.docker.internal:8081/v1`
Máy chủ trên LAN hoặc Tailscale tin cậy	`http://192.168.1.20:8081/v1`

Bên trong vùng chứa, localhost chỉ chính vùng chứa Libre WebUI. Nó không chỉ một dịch vụ Compose khác và cũng không tự động truy cập được máy chủ.

Libre WebUI chỉ chấp nhận URL nhà cung cấp dùng HTTP hoặc HTTPS, xác minh đích cuối trước khi chọn thông tin xác thực và không đi theo chuyển hướng trong yêu cầu nhà cung cấp hoặc khám phá. Hãy cấu hình trực tiếp URL thao tác cuối cùng.

Xác minh cổng trước khi kích hoạt

Kiểm tra quy trình khám phá mô hình từ máy hoặc vùng chứa đang chạy backend của Libre WebUI:

curl http://ai-gateway:8080/v1/models \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY'

Sau đó, kiểm tra thao tác tương ứng với chế độ API đã chọn.

Chat Completions:

curl http://ai-gateway:8080/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "messages": [{"role": "user", "content": "Reply with: ready"}],
    "stream": false
  }'

Responses:

curl http://ai-gateway:8080/v1/responses \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "input": "Reply with: ready",
    "store": false
  }'

Sau khi các lệnh gọi kiểm thử hoạt động, hãy cấu hình cùng tuyến, chế độ, thông tin xác thực và ID mô hình trong Provider connections. Kích hoạt nhà cung cấp, chọn Refresh models, rồi chọn mô hình gắn với nhà cung cấp đó trong Chat. Work cũng có thể dùng mô hình khi mô hình hỗ trợ lệnh gọi công cụ tương thích một cách đáng tin cậy.

Khắc phục sự cố

Triệu chứng	Kiểm tra
Yêu cầu vẫn đến endpoint tích hợp sẵn	Xóa giá trị ghi đè endpoint đầy đủ đã cũ, rồi lưu Base URL và API Path mong muốn.
Nhà cung cấp nhận dữ liệu yêu cầu không đúng	Chọn API Mode khớp với giao thức Chat Completions hoặc Responses của máy chủ đầu nguồn và xác minh hậu tố cuối cùng.
Refresh models không trả về ID	Kiểm tra `/models`, xác minh cấu trúc `data[].id`, cung cấp/cấu hình biến `models_endpoint` hoặc duy trì `model_map`.
Mô hình cũ vẫn còn sau khi sửa tuyến	Lưu thay đổi kết nối; Libre WebUI sẽ xóa danh mục khám phá lỗi thời của người dùng đó trước khi làm mới.
Hệ thống báo thiếu khóa API	Lưu thông tin xác thực riêng theo người dùng cho tuyến tùy chỉnh; cơ chế dùng biến môi trường dự phòng của bản tích hợp sẵn không đi theo giá trị ghi đè.
Bản triển khai Docker không truy cập được localhost	Dùng tên dịch vụ Compose của cổng, bí danh máy chủ được hỗ trợ hoặc địa chỉ mạng riêng có thể truy cập.
Chat hoạt động nhưng tạo hình ảnh không hoạt động	Cấu hình `image_endpoint` hoàn chỉnh và riêng biệt, rồi chọn mô hình do khả năng hình ảnh đó cung cấp.
Chat hoạt động nhưng Work từ chối mô hình	Xác nhận mô hình hỗ trợ lệnh gọi công cụ tương thích; chỉ hoàn tất văn bản thông thường là chưa đủ.
Nhà cung cấp trả về chuyển hướng	Cấu hình trực tiếp URL cuối đã được xác minh; Libre WebUI chủ ý không đi theo chuyển hướng của nhà cung cấp.

Để biết chi tiết về định tuyến, thông tin xác thực, trạng thái phát lại và hành vi phân quyền, hãy đọc Plugin. Với lỗi theo từng kiểu triển khai, xem Khắc phục sự cố.

Ghi nhận cộng đồng

Hướng dẫn này và trải nghiệm Provider connections của Libre WebUI 0.16.0 được định hình nhờ ZhengJin (@fangzhengjin). Phản hồi chi tiết của anh về nhà cung cấp bên thứ ba cùng ý tưởng UX có AI hỗ trợ trong #163 đã góp phần xác định quy trình làm việc.

Mở trang kết nối nhà cung cấp​

Thêm nhanh một kết nối​

Codex (đăng nhập ChatGPT)​

Chọn nhà cung cấp tích hợp sẵn hoặc được nhập​

Chọn Chat Completions hoặc Responses​

Cấu hình Base URL hoặc endpoint đầy đủ​

Khám phá và Duy trì ID Mô hình​

Cấu hình riêng tính năng tạo hình ảnh​

Kết nối cổng HTTP một cách an toàn​

Xác minh cổng trước khi kích hoạt​

Khắc phục sự cố​

Ghi nhận cộng đồng​

Tài liệu liên quan​