URL cơ sở API OpenAI của Open WebUI: Hướng dẫn Cài đặt Flatkey

Cài đặt URL cơ sở API OpenAI của Open WebUI là một trường nhỏ quyết định liệu Open WebUI sẽ gửi lưu lượng trò chuyện đến một nhà cung cấp ngược dòng, một máy chủ mô hình cục bộ, hay một bộ định tuyến như Flatkey. Đối với việc triển khai cho đội nhóm, trường đó không nên được xem như một chi tiết sao chép-dán. Nó cần được kiểm tra cùng với khóa API, ID mô hình, hành vi khám phá mô hình, hoàn thành cuộc trò chuyện, truyền phát và nhật ký sử dụng.

Hướng dẫn này được viết cho các nhà phát triển, đội ngũ sản phẩm AI, người xây dựng tự động hóa, kỹ sư nền tảng, người vận hành tài chính và người đánh giá mua sắm muốn Open WebUI sử dụng Flatkey như một bộ định tuyến mô hình tương thích OpenAI. Nó chỉ ra đường dẫn kết nối Open WebUI hiện tại, URL cơ sở của Flatkey cần xác minh, khi nào nên sử dụng bộ lọc mô hình, cách chạy kiểm tra sơ bộ bằng curl, và những gì cần ghi lại trước khi triển khai cài đặt cho nhiều người dùng hơn.

Lưu ý về nguồn: thông tin này đã được kiểm tra vào ngày 29 tháng 6 năm 2026 dựa trên tài liệu Tương thích OpenAI chính thức của Open WebUI, trang chủ Flatkey đang hoạt động, và trang giá Flatkey đang hoạt động. Không có khóa API Flatkey hoặc phiên bản Open WebUI nào đang hoạt động trong môi trường chạy này, vì vậy các lệnh dưới đây là các mẫu để bạn chạy với khóa, bí danh mô hình và triển khai Open WebUI của riêng mình.

Câu trả lời nhanh: URL cơ sở API OpenAI của Open WebUI cho Flatkey

Đối với một tuyến Flatkey, hãy đặt URL cơ sở API OpenAI của Open WebUI thành URL cơ sở của nhà cung cấp Flatkey hiện tại từ tài khoản của bạn. Trang chủ công khai của Flatkey được kiểm tra cho bài viết này cho biết hãy trỏ các client tương thích OpenAI đến https://console.flatkey.ai/v1. Trong Open WebUI, hãy sử dụng URL cơ sở đó, dán khóa API Flatkey, thêm chính xác các ID mô hình Flatkey nếu việc khám phá mô hình bị nhiễu hoặc thất bại, sau đó lưu kết nối.

Phiên bản ngắn gọn là: cấu hình URL, khóa và bộ lọc mô hình, sau đó kiểm tra một yêu cầu trò chuyện và xác nhận yêu cầu đó xuất hiện trong nhật ký sử dụng của Flatkey. Phần còn lại của hướng dẫn URL cơ sở API OpenAI của Open WebUI này sẽ biến điều đó thành một danh sách kiểm tra cài đặt và khắc phục sự cố có thể lặp lại.

Những gì tài liệu Open WebUI hiện tại xác nhận

Hướng dẫn chính thức tương thích OpenAI của Open WebUI nói rằng Open WebUI có thể kết nối với bất kỳ máy chủ hoặc nhà cung cấp nào triển khai API tương thích OpenAI. Tài liệu này định hình việc tích hợp xung quanh các giao thức tiêu chuẩn, đặc biệt là giao thức Hoàn thành cuộc trò chuyện của OpenAI, thay vì một mô-đun tùy chỉnh cho mỗi nhà cung cấp. Điều đó biến việc tích hợp Flatkey thành một nhiệm vụ cấu hình URL cơ sở, khóa và lựa chọn mô hình.

Cùng hướng dẫn đó cũng cung cấp đường dẫn quản trị hiện tại: mở Open WebUI, đi đến Cài đặt quản trị, sau đó là Kết nối, rồi OpenAI, sau đó nhấp vào Thêm kết nối. Từ đó, điền vào URL của nhà cung cấp và khóa API. Nếu việc khám phá mô hình tự động không hoạt động, hãy thêm ID mô hình vào ID mô hình (Bộ lọc) và lưu lại.

Một cảnh báo của Open WebUI đặc biệt quan trọng đối với các thiết lập bộ định tuyến. Khi một kết nối được thêm vào, Open WebUI sẽ xác minh nó thông qua điểm cuối /models của nhà cung cấp bằng một mã thông báo bearer tiêu chuẩn. Tài liệu nói rằng một số nhà cung cấp không triển khai /models, sử dụng hành vi không chuẩn, hoặc trả về một danh sách mô hình khó sử dụng. Lỗi danh sách mô hình không tự động có nghĩa là việc hoàn thành cuộc trò chuyện không tương thích. Điều đó có nghĩa là bạn có thể cần phải thêm ID mô hình theo cách thủ công và kiểm tra trực tiếp điểm cuối trò chuyện.

Để tương thích hoàn toàn, Open WebUI liệt kê /v1/models là được khuyến nghị và /v1/chat/completions là điểm cuối trò chuyện cốt lõi bắt buộc. Nó cũng chuyển các tham số OpenAI phổ biến như temperature, top_p, max_tokens hoặc max_completion_tokens, stop, seed, và logit_bias. Việc sử dụng công cụ được hỗ trợ khi mô hình và máy chủ hỗ trợ tools và tool_choice.

Các giá trị Flatkey cần xác minh trước khi thay đổi Open WebUI

Trang chủ Flatkey được kiểm tra vào ngày 29 tháng 6 năm 2026 có tiêu đề One API gateway for production AI teams và mô tả quyền truy cập mô hình thống nhất, định tuyến, thanh toán, phân tích sử dụng và kiểm soát hoạt động. Nó cũng nói rằng các đội nhóm nên trỏ một client tương thích OpenAI đến https://console.flatkey.ai/v1 và giữ nguyên mẫu SDK hoặc client hiện có.

Trang giá của Flatkey được kiểm tra trong cùng ngày cho biết danh mục công khai có 633 mô hình được kích hoạt trên 23 nhà cung cấp. Nó cũng hiển thị các họ điểm cuối bao gồm /v1/chat/completions, /v1/responses, /v1/messages, /v1/images/generations, và /v1/video/generations. Đối với trò chuyện Open WebUI, hãy bắt đầu với một mô hình có sẵn thông qua đường dẫn hoàn thành trò chuyện và được phê duyệt cho khóa bạn dự định sử dụng.

Đừng cho rằng mọi mô hình trong danh mục đều là mô hình tốt cho Open WebUI. URL cơ sở API OpenAI của Open WebUI trỏ đến một bộ định tuyến, nhưng trải nghiệm người dùng phụ thuộc vào bí danh mô hình được chọn, hỗ trợ điểm cuối, độ trễ, hành vi ngữ cảnh, hỗ trợ công cụ và liệu mô hình có xuất hiện rõ ràng trong bộ chọn mô hình của Open WebUI hay không.

Hướng dẫn từng bước: thêm Flatkey làm kết nối OpenAI

1. Chọn phạm vi Open WebUI. Quyết định xem đây là kết nối toàn quản trị viên, một phiên bản thử nghiệm hay một triển khai tự lưu trữ được quản lý thông qua các biến môi trường.
2. Tạo hoặc chọn một khóa Flatkey. Sử dụng một khóa chuyên dụng cho việc thử nghiệm Open WebUI để có thể ghi nhận và giới hạn việc sử dụng.
3. Chọn một mô hình khởi đầu. Sao chép chính xác bí danh mô hình từ trang giá của Flatkey, bảng điều khiển Flatkey hoặc danh sách mô hình hiển thị trong tài khoản của bạn.
4. Mở màn hình kết nối. Trong Open WebUI, đi tới Admin Settings > Connections > OpenAI > Add Connection.
5. Dán URL Flatkey. Sử dụng https://console.flatkey.ai/v1 nếu tài khoản của bạn xác nhận. Giá trị này nên bao gồm /v1 nhưng không bao gồm /chat/completions.
6. Dán khóa Flatkey. Sử dụng khóa được tạo cho việc triển khai Open WebUI này, không phải khóa nhà cung cấp cá nhân hoặc khóa nhà cung cấp thượng nguồn không liên quan.
7. Thêm ID mô hình khi cần. Nếu việc khám phá mô hình thất bại, trả về quá nhiều tùy chọn hoặc hiển thị các mô hình ngoài chính sách, hãy thêm các bí danh được phê duyệt chính xác vào Model IDs (Filter).
8. Lưu và giữ tuyến đường trước đó ở gần. Open WebUI cho phép bật hoặc tắt các kết nối, vì vậy hãy giữ lại một tuyến đường để quay lại trong khi thử nghiệm.
9. Chạy một lời nhắc rủi ro thấp. Sử dụng một lời nhắc đơn giản trong Open WebUI, sau đó xác nhận yêu cầu trong phần sử dụng của Flatkey theo dấu thời gian, khóa, mô hình, số lượng token và chi phí.
10. Ghi lại thông tin chủ sở hữu. Ghi lại ai sở hữu khóa, ai có thể xoay vòng khóa, những mô hình nào được phê duyệt và hạn ngạch nào được áp dụng trước khi mở rộng quyền truy cập.

Mẫu biến môi trường tùy chọn

Nếu việc triển khai của bạn được quản lý thông qua các biến môi trường, hãy sử dụng các tên được hỗ trợ bởi phiên bản Open WebUI và phương thức triển khai của bạn. Các ví dụ về nhà cung cấp của Open WebUI cho thấy các mẫu OPENAI_API_BASE_URL và OPENAI_API_KEY cho các backend tương thích với OpenAI, nhưng bảng quản trị cũng có thể quản lý các kết nối. Hãy coi đây là một mẫu triển khai để xác minh với phiên bản của bạn.

OPENAI_API_BASE_URL=https://console.flatkey.ai/v1
OPENAI_API_KEY=fk_thay_the_bang_khoa_flatkey

Nếu bạn cũng định tuyến các tính năng nhúng, tạo hình ảnh, giọng nói hoặc các tính năng kiểu OpenAI khác thông qua Open WebUI, hãy chỉ cấu hình các biến URL cơ sở và khóa dành riêng cho tính năng đó sau khi xác nhận Flatkey và mô hình được chọn hỗ trợ họ điểm cuối đó. Đối với lần triển khai URL cơ sở API OpenAI của Open WebUI đầu tiên, hãy tập trung thử nghiệm vào việc hoàn thành trò chuyện.

Kiểm tra trước tuyến Flatkey trước khi đổ lỗi cho Open WebUI

Một lệnh kiểm tra trước bằng curl giúp tách biệt các vấn đề về bộ định tuyến và thông tin xác thực khỏi các vấn đề về giao diện người dùng của Open WebUI. Chạy lệnh này từ một vị trí mạng tương đương với máy chủ Open WebUI.

export FLATKEY_API_KEY="fk_thay_the_bang_khoa_cua_ban"
export FLATKEY_BASE_URL="https://console.flatkey.ai/v1"
export FLATKEY_OPEN_WEBUI_MODEL="thay-the-bang-bi-danh-mo-hinh-flatkey"

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_OPEN_WEBUI_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "Trả về từ ok."
      }
    ],
    "stream": false,
    "max_tokens": 16
  }'

Nếu yêu cầu đó thất bại, hãy sửa khóa Flatkey, URL, bí danh mô hình, quyền tài khoản hoặc tuyến mạng trước khi thay đổi Open WebUI một lần nữa. Nếu thành công, hãy lặp lại thông qua Open WebUI và so sánh nhật ký sử dụng của Flatkey.

Để có trải nghiệm trò chuyện trực tuyến (streaming), hãy kiểm tra việc streaming một cách riêng biệt. Một phản hồi không streaming chứng tỏ tuyến đường có thể trả lời. Điều đó không chứng minh rằng reverse proxy, việc triển khai Open WebUI và trình duyệt của máy khách của bạn xử lý streaming mà không bị đệm hoặc hết thời gian chờ.

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_OPEN_WEBUI_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "Truyền trực tuyến ba gạch đầu dòng ngắn."
      }
    ],
    "stream": true,
    "max_tokens": 96
  }'

Danh sách kiểm tra khám phá và lọc mô hình

Thiết lập URL cơ sở API OpenAI của Open WebUI an toàn nhất là sử dụng bộ lọc mô hình một cách có chủ đích. Một bộ định tuyến có thể hiển thị nhiều mô hình, và một danh sách mô hình rộng không phải lúc nào cũng là điều mà quản trị viên muốn người dùng nhìn thấy.

Các chế độ lỗi cần gỡ lỗi trước tiên

Sổ tay vận hành sản xuất cho Open WebUI và Flatkey

Trước khi bạn thực hiện thay đổi URL cơ sở API OpenAI của Open WebUI cho một nhóm lớn hơn, hãy ghi lại các thông tin vận hành hỗ trợ quyền sở hữu, khôi phục và xem xét chi phí.

Vị trí của điều này trong cụm tích hợp công cụ Flatkey

Open WebUI chỉ là một bề mặt có thể sử dụng một tuyến đường tương thích với OpenAI. Nếu nhóm của bạn đang chuẩn hóa nhiều công cụ, hãy sử dụng cùng một mẫu trên toàn cụm: một URL cơ sở hiện tại, một khóa do tài khoản sở hữu cho mỗi bề mặt, các bí danh mô hình chính xác, một bài kiểm tra khói nhỏ, bằng chứng sử dụng và ghi chú khôi phục.

Đối với các thiết lập liền kề, hãy xem hướng dẫn thiết lập API Cherry Studio để biết về kỷ luật URL cơ sở của máy khách để bàn, hướng dẫn CC Switch Claude Code Flatkey để định tuyến công cụ dành cho nhà phát triển và sổ tay di chuyển API tương thích OpenAI rộng hơn để biết về các thay đổi URL cơ sở, xác minh bí danh mô hình và khôi phục. Sử dụng bảng giá Flatkey để xem xét phạm vi phủ sóng của mô hình và điểm cuối hiện tại, sau đó nhận khóa cho không gian làm việc sở hữu lần triển khai Open WebUI đầu tiên.

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

Tôi nên điền gì vào trường URL cơ sở API OpenAI của Open WebUI?

Sử dụng URL cơ sở của nhà cung cấp Flatkey hiện tại từ tài khoản của bạn. Trang chủ công khai của Flatkey được kiểm tra vào ngày 29 tháng 6 năm 2026 chỉ các máy khách tương thích với OpenAI đến https://console.flatkey.ai/v1. Không bao gồm đường dẫn đầy đủ /chat/completions trong trường URL cơ sở.

Tại sao Open WebUI hiển thị lỗi khám phá mô hình?

Open WebUI xác minh một kết nối mới tương thích với OpenAI bằng cách gọi /models. Tài liệu chính thức cảnh báo rằng một số nhà cung cấp không triển khai điểm cuối đó, sử dụng hành vi không chuẩn hoặc trả về danh sách mô hình rất lớn. Nếu các hoàn thành trò chuyện hoạt động, hãy thêm ID mô hình chính xác vào bộ lọc và kiểm tra lại.

Tôi có thể hiển thị mọi mô hình Flatkey cho Open WebUI không?

Về mặt kỹ thuật, một router có thể hiển thị nhiều mô hình, nhưng quản trị viên sản xuất nên bắt đầu với một danh sách cho phép hẹp. Chọn các mô hình phù hợp với nhu cầu trò chuyện của Open WebUI, hỗ trợ điểm cuối, kỳ vọng về độ trễ, chính sách sử dụng và kiểm soát ngân sách.

Flatkey có thay thế cài đặt của Open WebUI không?

Không. Flatkey cung cấp tuyến đường tương thích với OpenAI, khóa, quyền truy cập mô hình, khả năng hiển thị sử dụng và kiểm soát thanh toán. Open WebUI vẫn kiểm soát các cài đặt kết nối, bộ chọn mô hình, quyền truy cập của người dùng, hành vi của lời nhắc và mạng ở cấp độ triển khai của riêng nó.

Làm cách nào để biết thiết lập đang hoạt động?

Chạy một lệnh curl preflight đến /chat/completions, lưu kết nối Open WebUI, gửi một lời nhắc an toàn và xác nhận yêu cầu xuất hiện trong phần sử dụng của Flatkey với khóa, mô hình, dấu thời gian, token, trạng thái và chi phí dự kiến.

Danh sách kiểm tra cuối cùng

• URL cơ sở của Flatkey đã được xác nhận từ nguồn tài khoản hiện tại.
• Khóa Flatkey chuyên dụng đã được tạo cho việc triển khai Open WebUI.
• Một bí danh mô hình trò chuyện đã được phê duyệt được chọn trước tiên.
• URL cơ sở API OpenAI của Open WebUI được đặt thành URL cơ sở của nhà cung cấp, không phải là điểm cuối đầy đủ.
• ID mô hình được thêm thủ công khi việc khám phá thất bại hoặc trả về quá nhiều tùy chọn.
• Trò chuyện không phát trực tuyến và có phát trực tuyến đã được kiểm tra.
• Hàng sử dụng của Flatkey đã được xác nhận sau lời nhắc đầu tiên của Open WebUI.
• Chủ sở hữu, hạn ngạch, danh sách cho phép mô hình và đường dẫn khôi phục đã được ghi lại.

Sau khi các kiểm tra đó được thông qua, URL cơ sở API OpenAI của Open WebUI không chỉ đơn thuần là một trường kết nối. Nó trở thành một tuyến đường Flatkey được kiểm soát với một khóa, các mô hình được phê duyệt, khả năng hiển thị sử dụng và một kế hoạch khôi phục rõ ràng.