OpenWebUI API: Chat với mọi trang web bằng mô hình của bạn

Nếu bạn đang chạy OpenWebUI, phần khó nhất coi như bạn đã làm xong. Mô hình đã được thiết lập, các khóa API được quản lý tập trung, có thể là Ollama trên máy chủ ở nhà, thêm một hai nhà cung cấp đám mây, và vài mô hình tùy chỉnh trong không gian làm việc do bạn tự thiết lập.

Có điều OpenWebUI không hoạt động ngay trong những trang bạn đang duyệt. Muốn hỏi mô hình về bài báo, file PDF hay trang tài liệu đang đọc, bạn vẫn phải sao chép rồi dán sang một tab khác.

Đây là lúc SurfMind phát huy tác dụng. OpenWebUI không chỉ là giao diện chat. Thông qua OpenWebUI API, nó còn hoạt động như một máy chủ API, nên SurfMind có thể dùng nó làm backend. Bạn vẫn quản lý mô hình trong OpenWebUI, còn SurfMind trở thành giao diện ngay trong trình duyệt cho các mô hình đó.

Hướng dẫn này giải thích OpenWebUI API là gì, nó liên quan thế nào đến SurfMind, chính xác những URL cần dán, và cách sửa những lỗi mà người dùng thực sự hay gặp.

OpenWebUI và SurfMind: bề ngoài giống nhau, nhiệm vụ khác nhau

Thoạt nhìn, hai công cụ này có vẻ là đối thủ. Cả hai đều là giao diện AI, đều kết nối được với nhiều nhà cung cấp LLM, và đều cho bạn chat với mô hình. Tuy nhiên, mỗi công cụ phục vụ một nhu cầu khác nhau:

OpenWebUI là không gian làm việc AI tự host. SurfMind là AI ngay trong trình duyệt bạn đang dùng. Dòng quan trọng nhất là dòng in đậm. Vì OpenWebUI có thể cung cấp mô hình của bạn qua API, hai công cụ này bổ trợ cho nhau rất ăn ý.

Vì sao nên kết nối OpenWebUI với SurfMind?

Hãy hình dung một thiết lập quen thuộc. Bạn có OpenWebUI trên máy chủ ở nhà hoặc một VPS nhỏ, và phía sau nó là:

• Llama, Qwen hoặc Gemma chạy cục bộ qua Ollama
• Các mô hình GPT hoặc Claude qua API key đám mây
• Một mô hình được vLLM phục vụ trên GPU của chính bạn
• Vài mô hình tùy chỉnh trong không gian làm việc (workspace model) bạn tạo trong OpenWebUI, mỗi mô hình có chỉ dẫn hệ thống và cấu hình riêng

Tất cả đều dùng được từ trang chat của OpenWebUI. Giờ bạn còn muốn thêm những gì mà một trợ lý trình duyệt làm tốt: hỏi về trang hiện tại, tóm tắt một chuỗi thảo luận dài, so sánh thông tin giữa các tab, hoặc soạn câu trả lời mà không cần rời trang.

Bạn có thể thêm lại từng nhà cung cấp vào SurfMind: Ollama, rồi OpenAI key, rồi endpoint vLLM. Làm vậy vừa mất công, vừa phải quản lý key ở hai nơi, mà các mô hình tùy chỉnh trong không gian làm việc bạn đã tạo cũng không theo sang được.

Hoặc bạn chỉ cần thêm một kết nối: SurfMind → OpenWebUI. Mọi mô hình mà OpenWebUI thấy được đều xuất hiện trong bộ chọn mô hình của SurfMind. Bạn vẫn quản lý mô hình, người dùng và quyền hạn trong OpenWebUI như trước giờ, còn SurfMind giúp bạn dùng các mô hình đó ngay trong trình duyệt.

Cách này cũng thuận tiện khi cả nhóm muốn dùng chung một cấu hình. Nếu cả nhóm dùng chung một bản cài đặt OpenWebUI, mỗi người có thể tự tạo API key riêng và dùng các mô hình của nhóm ngay từ trình duyệt. Họ có đúng những quyền như trong OpenWebUI, và không ai cần đến key của nhà cung cấp.

Bước 1: Tạo API key cho OpenWebUI

API key bị tắt theo mặc định, nên lần đầu sẽ mất khoảng một phút.

Nếu bạn là admin, hãy bật API key:

1. Đăng nhập vào OpenWebUI bằng tài khoản quản trị viên.
2. Vào Settings → Admin → Authentication.
3. Bật API Keys và nhấp Save.

Nếu bạn không phải admin, hãy nhờ admin cấp cho bạn quyền tính năng API Keys. Admin thiết lập quyền này trong Admin Panel → Users → Groups, hoặc ở Default Permissions cho tất cả mọi người, hoặc trong một nhóm cụ thể.

Sau đó tạo key của bạn:

1. Nhấp vào biểu tượng hồ sơ ở góc dưới bên trái.
2. Mở Settings → Account.
3. Trong mục API keys, nhấp Show bên cạnh Secrets. Mục này được thu gọn theo mặc định, nên thấy trống trơn ở đây là chuyện bình thường.
4. Nhấp Create new secret key và sao chép key. Key bắt đầu bằng sk-.

Vài điều nên biết, theo tài liệu API key của OpenWebUI:

• Mỗi tài khoản chỉ có một key. Tạo key mới sẽ thay thế key cũ, và key cũ ngừng hoạt động ngay lập tức. Nếu một công cụ khác đang dùng key của bạn, việc tạo key mới cho SurfMind sẽ khiến công cụ đó mất quyền truy cập. Dùng một tài khoản không phải admin dành riêng cho SurfMind sẽ tránh được chuyện này.
• Key đại diện cho chính bạn. Nó thấy cùng các mô hình và có cùng quyền hạn với tài khoản đã tạo ra nó.
• Đừng dùng JWT token hiển thị cho admin trong cùng bảng đó. Đó là token phiên trình duyệt của bạn, và nó sẽ hết hạn.

Bước 2: Thêm OpenWebUI vào SurfMind

Trong SurfMind, nhấp vào tên mô hình ở dưới cùng của bảng, rồi chọn Show all → Custom → Add Custom Models. Chọn cấu hình có sẵn OpenAI-compatible và điền:

Nếu OpenWebUI chạy trên cùng máy tính với trình duyệt, host thường là http://localhost:3000 (cổng hay được map khi dùng Docker) hoặc http://localhost:8080 (khi cài bằng pip hoặc cài trực tiếp):

• API URL: http://localhost:3000/api/chat/completions
• Models URL: http://localhost:3000/api/models

Lưu lại, chọn một mô hình OpenWebUI trong danh sách, mở một bài viết bất kỳ, và nhờ SurfMind tóm tắt nó.

Hai lỗi đường dẫn cần tránh. Hãy dán endpoint đầy đủ kết thúc bằng /api/chat/completions, không phải chỉ host hay /api. Trường API URL của SurfMind không tự thêm đường dẫn giúp bạn. Và đừng thêm /v1 vào bất cứ đâu. /api/v1/chat/completions và /v1/chat/completions đều không phải endpoint chat của OpenWebUI.

Khắc phục sự cố: "tải được mô hình nhưng chat không chạy"

Đây là lỗi được người dùng OpenWebUI báo cáo nhiều nhất, nên nó có hẳn một mục riêng. Nếu danh sách mô hình hiện ra đầy đủ, tức là host, key và đường kết nối mạng của bạn đều ổn. Vấn đề nằm ở một khâu xử lý yêu cầu chat. Hãy kiểm tra lần lượt theo thứ tự dưới đây.

Trước tiên, thử bên ngoài SurfMind. Một lệnh curl đơn giản trong cửa sổ dòng lệnh sẽ cho bạn biết vấn đề nằm ở OpenWebUI hay ở cài đặt SurfMind. Thay host, key và model id bằng thông tin của bạn:

curl -X POST https://openwebui.example.com/api/chat/completions \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3.2:latest", "messages": [{"role": "user", "content": "Say hi"}]}'

Dùng model id đúng y như cách nó hiển thị trong danh sách mô hình của SurfMind (hoặc trong GET /api/models). Nếu lệnh này chạy được, hãy kiểm tra lại các trường trong SurfMind. Nếu nó cũng lỗi, thông báo lỗi trả về sẽ chỉ ra một trong các nguyên nhân dưới đây.

1. Sai đường dẫn chat. Models URL và API URL là hai trường riêng, nên có thể một cái đúng còn cái kia sai. Hãy kiểm tra API URL kết thúc chính xác bằng /api/chat/completions, không có /v1, không có dấu gạch chéo ở cuối, và không gõ nhầm.

2. Giới hạn endpoint chặn chat. Admin có thể bật API Key Endpoint Restrictions, một danh sách cho phép (allowlist) các route mà API key được gọi. Nếu danh sách có /api/models nhưng không có /api/chat/completions, bạn sẽ gặp đúng triệu chứng này, thường là lỗi 403. Hãy nhờ admin thêm /api/chat/completions.

3. Một cài đặt mô hình ép chế độ streaming. OpenWebUI có cài đặt Stream Chat Response, đặt riêng cho từng mô hình trong phần tham số nâng cao, hoặc làm mặc định của admin trong Settings → Admin → Models. Theo tài liệu của OpenWebUI, cài đặt này quyết định phản hồi có được stream hay không bất kể ứng dụng gửi yêu cầu như thế nào. Nếu một mô hình bị ép vào chế độ mà ứng dụng không hỗ trợ, phản hồi có thể trả về ở dạng ứng dụng không đọc được. Nếu chat chỉ lỗi với một số mô hình nhất định, hãy kiểm tra cài đặt này trên các mô hình đó và đặt lại về Default.

4. Reverse proxy "nuốt" mất header Authorization. Nếu OpenWebUI nằm sau một gateway dùng Authorization cho việc đăng nhập riêng của nó (basic auth, SSO, API gateway), key của bạn sẽ không bao giờ đến được OpenWebUI. OpenWebUI cũng chấp nhận key qua một header tùy chỉnh, mặc định là x-api-key. Khi đó, hãy chọn x-api-key làm API Key Header trong SurfMind. Nếu admin đã đổi tên header bằng CUSTOM_API_KEY_HEADER, proxy phải chuyển tiếp header đó.

5. Model id không khớp. Hãy chọn từ danh sách thả xuống thay vì tự gõ. Id của các mô hình Ollama trong OpenWebUI có kèm tag (llama3.2:latest), còn mô hình tùy chỉnh trong không gian làm việc dùng id bạn đã đặt, không phải tên hiển thị.

6. Nhà cung cấp phía sau OpenWebUI đang lỗi. Khi nhà cung cấp mô hình phía sau OpenWebUI từ chối một yêu cầu, OpenWebUI sẽ chuyển nguyên mã trạng thái của họ về. Lỗi 429 là do giới hạn tốc độ (rate limit) của nhà cung cấp, không phải do OpenWebUI hay SurfMind. Hãy thử cùng mô hình đó trong trang chat của chính OpenWebUI. Nếu ở đó cũng lỗi, vấn đề nằm ở nhà cung cấp mô hình.

Các lỗi khác, xem nhanh

Với các quy tắc chung áp dụng cho mọi custom endpoint (cổng, http hay https, URL gốc hay endpoint đầy đủ), hãy xem hướng dẫn kết nối AI tùy chỉnh của chúng tôi.

Nên dùng OpenWebUI, SurfMind, hay cả hai?

Bạn không nhất thiết phải chọn một trong hai.

• Chỉ OpenWebUI là đủ nếu phần lớn thời gian dùng AI của bạn là những cuộc trò chuyện dài trong một tab riêng: chat với tài liệu trong knowledge base, chạy pipeline, quản lý mô hình cho cả nhóm.
• Chỉ SurfMind là đủ nếu phần lớn việc dùng AI của bạn bắt đầu từ những gì đang hiện trên màn hình, và bạn thấy thoải mái khi kết nối trực tiếp các nhà cung cấp hoặc một trình chạy cục bộ như Ollama.
• Cả hai là hợp lý khi bạn đã đầu tư công sức vào thiết lập OpenWebUI và muốn dùng nó trên mọi trang mà không phải cấu hình mọi thứ hai lần.

Cách phân chia rất đơn giản: OpenWebUI quản lý mô hình, còn SurfMind giúp bạn sử dụng chúng ngay trong trình duyệt.

Câu hỏi thường gặp

OpenWebUI có API không? Có. OpenWebUI API là một REST API xác thực bằng Bearer token. Hai endpoint mà hầu hết công cụ cần là GET /api/models để liệt kê mô hình và POST /api/chat/completions để chat, endpoint này chấp nhận yêu cầu theo định dạng OpenAI.

OpenWebUI API có tương thích OpenAI không? Định dạng yêu cầu và phản hồi thì có. Còn đường dẫn thì không theo chuẩn: OpenWebUI dùng /api/chat/completions thay vì /v1/chat/completions. Bất kỳ ứng dụng nào cho phép đặt URL endpoint đầy đủ, như SurfMind, đều dùng được.

Tôi tìm API key OpenWebUI ở đâu? Vào Settings → Account → API keys, nhấp Show, rồi Create new secret key. Nếu không thấy mục này, admin cần bật API Keys trong Settings → Admin → Authentication và cấp quyền API Keys cho tài khoản của bạn.

Tôi có dùng được mô hình tùy chỉnh trong không gian làm việc của OpenWebUI trong SurfMind không? Được. Workspace model được /api/models liệt kê như mọi mô hình khác. Khi bạn gọi chúng, OpenWebUI sẽ áp dụng các cài đặt đã lưu của chúng.

Kết nối OpenWebUI có gửi dữ liệu của tôi lên máy chủ của SurfMind không? Với custom endpoint, SurfMind gửi yêu cầu đến URL bạn đã cấu hình, ở đây là máy chủ OpenWebUI của bạn. Sau đó máy chủ OpenWebUI chuyển tiếp yêu cầu đến mô hình bạn đã chọn. Nếu mô hình đó chạy cục bộ, nội dung trang sẽ chỉ nằm trên phần cứng do bạn kiểm soát.

Có miễn phí không? Có. Custom endpoint trong SurfMind hoàn toàn miễn phí và chúng tôi không giới hạn mức sử dụng. Bạn chỉ trả những gì nhà cung cấp của bạn tính phí, và với mô hình cục bộ thì không tốn đồng nào.

Vẫn chưa được?

Nếu lệnh curl chạy được mà SurfMind vẫn không chat được với các mô hình OpenWebUI của bạn, hãy gửi email cho chúng tôi tại wave@surfmind.ai. Kèm theo API URL của bạn (không có key), mã trạng thái HTTP, và cho biết lỗi xảy ra với một vài mô hình hay tất cả. Các thiết lập tự host rất đa dạng, và những báo cáo như vậy giúp chúng tôi làm cho SurfMind chạy trơn tru với chúng.

Tải SurfMind →