Nhà cung cấp AI

Vị trí trong admin: System › Settings › AI provider (/settings/ai). Nút bật module AI nằm tại đây và trong System › Admin › License & updates (/license), thẻ Module.

Chức năng

AI Chat (chat hỗ trợ tự động) và AI Agent (quản trị VM bằng ngôn ngữ tự nhiên) không đi kèm mô hình tích hợp sẵn. Bạn tự chọn nhà cung cấp của riêng mình: bất kỳ dịch vụ nào cung cấp chat/completions API tương thích OpenAI — ví dụ như OpenAI, OpenRouter, LiteLLM gateway hoặc vLLM server riêng của bạn. NexCMP lưu trữ endpoint và API key (được mã hóa) rồi sử dụng chúng cho mọi tính năng AI. Bạn thanh toán trực tiếp cho nhà cung cấp.

Yêu cầu

Hạng mục	Yêu cầu
Endpoint	Base URL tương thích OpenAI (https://api.openai.com/v1, https://ai.example.com/v1). NexCMP sẽ thêm /chat/completions vào URL kết thúc bằng /v1; với mọi URL khác, hệ thống sẽ thêm /v1/chat/completions; URL đã kết thúc bằng /chat/completions sẽ được giữ nguyên.
Model	Model hỗ trợ tool (function) calling. Cả AI Chat và Agent đều dựa vào tính năng này.
API key	Key cho endpoint đó. Nên ưu tiên key có giới hạn chi tiêu (spending cap) ở phía nhà cung cấp (ví dụ: virtual key của LiteLLM với ngân sách hàng tháng).
Mạng	Server chứa panel phải kết nối được tới endpoint qua HTTP(S). URL nhập trong form chỉ được phép trỏ ra Internet trên các cổng 80, 443, 8080 hoặc 8443; để sử dụng địa chỉ nội bộ, hãy lưu nhà cung cấp trước rồi mới kiểm tra.
Thành phần phụ thuộc	Module AI đang bật. Đối với Agent, xem AI Agent.

Chuẩn bị hạ tầng

1. Đăng ký với nhà cung cấp và tạo API key. Nếu nhà cung cấp hỗ trợ ngân sách hoặc rate limit, hãy đặt hạn mức hàng tháng.

2. Ghi lại base URL và chính xác tên model (cùng tối đa bốn fallback model tùy chọn).

3. Kiểm tra kết nối từ server NexCMP trước khi nhập:

   curl -s https://ai.example.com/v1/chat/completions \
     -H "Authorization: Bearer XXXX" -H "Content-Type: application/json" \
     -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Reply with one word: OK"}]}'

   Phản hồi JSON có choices[0].message.content đồng nghĩa endpoint hoạt động bình thường.

Kết nối trong NexCMP

1. Mở System › Settings › AI provider.

2. Tại thẻ Module AI, gạt module sang on. Cho đến khi được bật, khách hàng sẽ không thấy AI Chat hoặc AI Agent trên portal. (Bạn cũng có thể bật tính năng này trong License & updates.)

3. Tại thẻ Connection, điền:

   Trường	Ví dụ	Ghi chú
   Use this provider	bật	Cần có base URL, model và key để bật.
   Tên hiển thị	LiteLLM	Tối đa 60 ký tự.
   Base URL (OpenAI-compatible)	https://ai.example.com/v1	http:// hoặc https://, tối đa 300 ký tự, không chứa khoảng trắng.
   Provider API key	sk-XXXX	Được lưu trữ dưới dạng mã hóa; sau đó chỉ hiển thị 4 ký tự cuối. Để trống để giữ lại key đã lưu.
   Default model	gpt-4o-mini	Chữ cái, chữ số và - _ . / : @.
   Fallback models	gemini-2.5-flash	Phân tách bằng dấu phẩy, tối đa 4 model. Được sử dụng khi default model gặp sự cố.
   Reasoning effort	Default (not sent)	Minimal, Low, Medium hoặc High. Đối với các reasoning model (Gemini, o-series), mức thấp sẽ phản hồi nhanh hơn nhiều. Để Default đối với các model thông thường.

4. Nhấp vào Save, sau đó chọn Test connection. Quá trình kiểm tra sẽ gửi một câu hỏi ngắn và hiển thị Connected — <model>, <ms> ms hoặc lỗi do nhà cung cấp trả về.

Cơ chế hoạt động khi lưu

• Cấu hình nhà cung cấp được lưu dưới dạng một mục cấu hình duy nhất và key được mã hóa bằng AES-256-GCM cho mục đích này bằng master key của bản cài đặt.
• Cài đặt hỗ trợ Primary model và Fallback model (được AI Chat sử dụng) sẽ tự động được gán thành default model và fallback model đầu tiên của bạn.
• Thay đổi được ghi vào audit log (endpoint, model, trạng thái thay đổi key — tuyệt đối không ghi lại key).

Kiểm tra

1. Test connection hiển thị màu xanh lá.
2. Đăng nhập vào portal với tư cách khách hàng thử nghiệm: menu lúc này sẽ hiển thị AI Chat (hoặc bong bóng chat) và AI Agent.
3. Hỏi AI Chat "What is my balance?". Câu trả lời trích dẫn đúng số dư thực tế cho thấy provider xử lý tool calls chính xác.

Hạn mức & lưu ý

• Một provider duy nhất. NexCMP sử dụng một provider được cấu hình duy nhất cho Chat, Agent và điều tra ticket. Các model dự phòng mang lại khả năng dự phòng linh hoạt trong chính provider đó.
• Bảo mật key. Key đã lưu chỉ được gửi đến endpoint đã lưu. Nếu bạn thay đổi Base URL, bạn phải nhập lại key trước khi kiểm tra.
• Giới hạn theo từng khách hàng. AI Chat chỉ dành cho khách hàng đã đăng nhập, có giới hạn tin nhắn theo phút và theo phiên chat. Agent có giới hạn số lượt gọi hàng ngày cho mỗi tài khoản. Xem AI Chat và AI Agent.
• Quyền riêng tư. Các câu hỏi của khách hàng và dữ liệu AI đọc cho khách hàng đó (chỉ đọc) sẽ được gửi đến provider của bạn. Hãy nêu rõ điều này trong chính sách quyền riêng tư của bạn.
• Kiểm soát chi phí. NexCMP không đo lường chi phí AI; hãy sử dụng các tính năng quản lý ngân sách của chính provider.
• Module có thể tắt bất cứ lúc nào: các mục menu AI sẽ biến mất và các route AI sẽ trả về 404 module_disabled. Một số tác vụ nền của AI Chat (điều tra ticket, phản hồi trễ) sẽ áp dụng thay đổi ở lần khởi động lại tiếp theo của panel.

Xử lý sự cố

Hiện tượng	Nguyên nhân	Cách khắc phục
base_url must be an http(s) URL	Thiếu scheme hoặc khoảng trắng	Dùng https://host/v1.
api_key is required to enable the provider	Chưa lưu key	Nhập key và lưu.
base_url and model are required to enable the provider	Trường để trống	Điền cả hai.
"Base URL bị chặn: chỉ http(s) công khai, cổng 80/443/8080/8443"	Kiểm tra địa chỉ nội bộ chưa lưu hoặc port khác	Lưu provider trước, sau đó kiểm tra.
api_key is required (enter the key again when you change the endpoint)	Base URL khác với URL đã lưu	Nhập lại key.
model: letters, digits and - _ . / : @	Ký tự không hợp lệ	Dùng chính xác model ID của provider.
fallback_models: up to 4 model names	Quá nhiều	Giữ tối đa 4 model.
Kiểm tra thất bại với mã 401	Sai khóa	Kiểm tra key và endpoint.
Kiểm tra thất bại với mã 404 hoặc "model not found"	Sai đường dẫn hoặc model	Kiểm tra base URL (/v1) và model ID.
Too many tests — wait a minute (429)	Hơn 10 lượt kiểm tra mỗi phút	Chờ một lát.
Portal vẫn không hiển thị menu AI	Module đang tắt hoặc provider chưa ở trạng thái "in use"	Bật module và kích hoạt provider.