Hướng dẫn cài đặt và sử dụng — AI

Yêu cầu hệ thống

Server Digiforce đang chạy (phiên bản ≥ 1.0)
API key từ ít nhất một LLM provider (OpenAI, Anthropic, Google AI, DeepSeek, hoặc Ollama chạy local)
Node.js ≥ 18 (cần cho LangChain runtime)

Bước 1: Kích hoạt plugin

Vào Settings → Plugin Manager, tìm plugin-ai và bật. Khởi động lại server để plugin nạp đầy đủ các collection và resource.

TIP

Plugin AI đăng ký hơn 12 collection và 10 resource — quá trình khởi động có thể mất vài giây thêm.

Bước 2: Cấu hình LLM Provider

Vào Settings → AI → LLM Services, nhấn Add để thêm nhà cung cấp mô hình ngôn ngữ:

Trường	Mô tả	Ví dụ
Provider	Nhà cung cấp LLM	`openai`, `anthropic`, `google-genai`, `deepseek`, `ollama`, `kimi`, `dashscope`
API Key	Khóa xác thực API	`sk-...`
Base URL	URL gốc API (tuỳ chọn)	`https://api.openai.com/v1`
Default Model	Model mặc định khi tạo bot	`gpt-4o`, `claude-3.5-sonnet`, `gemini-pro`

Danh sách provider được hỗ trợ sẵn

Provider	SDK sử dụng	Ghi chú
OpenAI (Responses API)	`@langchain/openai`	Hỗ trợ GPT-4o, GPT-4, GPT-3.5
OpenAI (Completions API)	`@langchain/openai`	API cũ hơn, tương thích ngược
Anthropic	`@langchain/anthropic`	Claude 3.5, Claude 3
Google GenAI	`@langchain/google-genai`	Gemini Pro, Gemini Flash
DeepSeek	Tương thích OpenAI	DeepSeek Chat, DeepSeek Coder
DashScope	Tương thích OpenAI	Alibaba Cloud Qwen
Ollama	`@langchain/ollama`	Chạy local, không cần API key
Kimi	Tương thích OpenAI	Moonshot AI

Bước 3: Tạo AI Bot

Vào Settings → AI → Bots, nhấn Create để tạo bot mới:

Trường	Mô tả	Bắt buộc
Name	Tên hiển thị của bot	Có
Username	Định danh duy nhất (dạng slug)	Có
System Prompt	Hướng dẫn hành vi và tính cách của bot	Có
LLM Service	Chọn provider đã cấu hình ở Bước 2	Có
Model	Chọn model cụ thể từ provider	Có
Tools	Gán các AI tools cho bot (tuỳ chọn)	Không
Skills	Gán knowledge base / RAG skills (tuỳ chọn)	Không

WARNING

Các bot có username fronta, nero, dara là Builder AI — chỉ được gán cho role admin do có quyền mạnh (coding, thay đổi schema).

Bước 4: Sử dụng Chat

Mở giao diện chat bằng biểu tượng AI trên toolbar
Chọn bot muốn trò chuyện
Nhập tin nhắn và nhấn gửi
Bot trả lời dựa trên LLM và các tools/skills được gán

Tạo báo cáo phân tích (Business analysis report)

Nếu bot được gán tool Business report, bạn có thể yêu cầu bot tạo một báo cáo dạng “dashboard” có nội dung markdown và biểu đồ (ECharts) trong cùng một lần tạo.

Cách bật cho bot: vào Settings → AI → Bots → chọn bot → phần Tools → bật businessReportGenerator.
Cách dùng: trong chat, mô tả mục tiêu + khoảng thời gian + KPI bạn muốn xem. Ví dụ:
- “Tạo báo cáo doanh thu 30 ngày gần nhất: tổng doanh thu, số đơn, AOV, top 10 sản phẩm; kèm 2 biểu đồ xu hướng và cơ cấu theo kênh.”
- “Phân tích churn theo tháng, nêu rủi ro và khuyến nghị; kèm biểu đồ cohort.”

Khi tool chạy thành công, giao diện chat có thể hiển thị thẻ báo cáo và mở modal báo cáo để xem chi tiết.

Luồng xử lý tin nhắn

Tích hợp Workflow

Plugin đăng ký hai thành phần workflow thông qua plugin-workflow:

Thành phần	Vai trò	Cách sử dụng
AI Bot Trigger	Workflow kích hoạt khi user gửi message cho bot	Tạo workflow mới → chọn trigger `ai-bot`
LLM Instruction Node	Node gọi LLM với prompt tuỳ chỉnh, nhận kết quả	Thêm node `llm` vào workflow

Tích hợp MCP (Model Context Protocol)

Kết nối MCP servers để mở rộng khả năng của AI bots với các tools bên ngoài:

Vào Settings → AI → MCP Clients
Nhấn Add và nhập thông tin MCP server
Các tools từ MCP server sẽ tự động khả dụng cho AI bots

Cron Job dọn dẹp

Plugin tự động đăng ký cron job chạy lúc 2:00 AM hàng ngày để xoá các LangChain checkpoints cũ hơn 48 giờ, tránh database phình to.

Lưu ý quan trọng

API key phải có đủ quota và quyền truy cập model — kiểm tra billing trên dashboard của provider
Ollama chạy hoàn toàn local, không cần API key nhưng cần cài đặt riêng trên server
Chi phí API tính theo token sử dụng — theo dõi usage trên LLM provider dashboard
Mỗi conversation lưu lịch sử chat; tạo conversation mới để bắt đầu cuộc trò chuyện mới
Không phải model nào cũng hỗ trợ function calling (cần GPT-4, Claude 3+ để dùng tools)