Chat profile là một bộ cấu hình để EzyAI gọi tới một nhà cung cấp AI: api

key, endpoint, model, giới hạn token, thời gian chờ, nguồn dữ liệu tri thức

và các skill được gắn vào. Mỗi dịch vụ AI (CHATGPT, CLAUDE, DEEPSEEK,

GEMINI, GROK, QWEN) có thể có nhiều profile, ví dụ một profile cho

trợ lý bán hàng, một profile cho trợ lý hỗ trợ kỹ thuật.

Tài liệu này hướng dẫn tạo một chat profile từ trang quản trị, gắn skill,

chat thử và nhúng chatbot lên website.

Các bước tổng quát

flowchart LR
    A["Chuẩn bị<br/>api key"] --> B["Chọn dịch vụ AI"]
    B --> C["Thêm profile"]
    C --> D["Tạo skill<br/>(tuỳ chọn)"]
    D --> E["Gắn skill<br/>vào profile"]
    E --> F["Chat thử"]
    F --> G["Nhúng lên website"]

Chuẩn bị

EzyPlatform đã cài các plugin ezyai-admin-plugin, ezyai-socket-plugin
và ezychat.
Tài khoản quản trị có quyền vào menu EzyAI.
Api key của nhà cung cấp AI muốn dùng, lấy từ trang quản lý của nhà cung
cấp (OpenAI, Anthropic, DeepSeek, Google AI Studio, xAI, Alibaba Cloud).

Api key chỉ được nhập ở trang quản trị. Không ghi api key vào mã nguồn,

file cấu hình hay tài liệu trong repo.

Chọn dịch vụ AI

Vào trang quản trị, mở menu EzyAI → Các dịch vụ AI chat
(/ezyai/ai-chat-services).
Chọn dịch vụ muốn dùng, ví dụ CLAUDE. Trang chi tiết dịch vụ
(/ezyai/ai-chat-services/CLAUDE) hiển thị danh sách profile hiện có.
Nếu muốn dịch vụ này là dịch vụ mặc định khi nơi gọi không chỉ định tên
dịch vụ, bấm Đặt làm mặc định ở danh sách dịch vụ.

Thêm profile

Ở trang chi tiết dịch vụ, bấm Thêm cấu hình để mở form

/ezyai/ai-chat-services/{serviceName}/profiles/add.

Trường	Bắt buộc	Mô tả
Tên cấu hình	Có	Tên profile, không được trùng với profile khác của cùng dịch vụ
API key	Có	Api key của nhà cung cấp, được lưu mã hoá trong setting kiểu `PASSWORD`
Endpoint	Có	Điền sẵn endpoint mặc định của dịch vụ, chỉ đổi khi dùng proxy hoặc endpoint riêng
Mô hình	Có	Chọn từ danh sách hoặc tích Nhập tên mô hình thủ công để tự gõ
Số token tối đa	Không	Giới hạn token của câu trả lời, mặc định `4096`, không được âm
Thời gian chờ (giây)	Không	Timeout khi gọi nhà cung cấp, mặc định `60`, không được âm
Nguồn dữ liệu	Không	Nguồn tri thức mà tool tìm kiếm sẽ dùng, thường chọn `DEFAULT`
Tên bộ sưu tập RAG	Không	Metadata `rag_collection_name`, được truyền vào context khi AI gọi tool
Trạng thái	Có	`ACTIVATED` để dùng được, `INACTIVATED` để tạm tắt

Bấm Lưu. Nếu có lỗi, form hiển thị ngay dưới trường tương ứng:

Lỗi	Nguyên nhân
`profileName: required` / `duplicated`	Chưa nhập tên hoặc tên đã tồn tại trong dịch vụ
`apiKey: required`	Chưa nhập api key
`endpoint: required`, `model: required`	Thiếu endpoint hoặc model
`maxTokens: invalid`, `timeoutInSecond: invalid`	Giá trị âm
`serviceName: invalid`	Dịch vụ chưa được đăng ký trong hệ thống

Một số lưu ý:

Danh sách mô hình được lấy bằng cách gọi API models của nhà cung cấp
với api key của profile mặc định của dịch vụ. Khi tạo profile đầu
tiên, chưa có profile mặc định nên danh sách chỉ có model mặc định; nếu
cần model khác, tích Nhập tên mô hình thủ công.
Profile đầu tiên của một dịch vụ tự động được đặt làm profile mặc
định. Các profile sau cần đặt mặc định thủ công nếu muốn.
Có thể khai báo thêm các trường metadata cho profile qua setting
ezyai_additional_ai_profile_meta_keys, form sẽ hiển thị thêm ô nhập cho
từng meta key.

Điều gì xảy ra khi lưu

sequenceDiagram
    participant A as Admin
    participant API as Admin API
    participant P as EzyAIChatProfileService
    participant DB as Database

    A->>API: POST /api/v1/ai-chat-services/{serviceName}/profiles/add
    API->>API: Kiểm tra dịch vụ và các trường
    API->>P: addProfile(serviceName, model)
    P->>DB: Lưu ChatProfile (tên, endpoint, model, ...)
    P->>DB: Lưu api key vào setting PASSWORD<br/>ezyai_[service]_profile_[id]_api_key
    P->>DB: Lưu metadata vào data_meta
    API->>P: Đặt làm profile mặc định nếu dịch vụ chưa có
    API-->>A: id của profile mới

Sửa profile

Ở trang chi tiết profile, bấm Sửa. Ô API key để trống thì key hiện tại

được giữ nguyên, chỉ nhập khi muốn đổi key. Thay đổi có hiệu lực ngay ở

lượt chat tiếp theo vì cấu hình không được cache.

Gắn skill vào profile

Skill quyết định AI được hướng dẫn thế nào (system prompt) và được dùng

những tool nào (ví dụ tìm kiếm bài viết, sản phẩm). Profile không gắn skill

vẫn chat được, nhưng sẽ không gọi tool nào.

Tạo skill

Vào EzyAI → Các kỹ năng AI (/ezyai/ai-skills), bấm Thêm.

Nhập tên và nội dung. Nội dung là system prompt, ví dụ:

Bạn là trợ lý bán hàng của cửa hàng. Trả lời ngắn gọn, thân thiện.
   Khi khách hỏi về sản phẩm, hãy tìm trong dữ liệu của cửa hàng trước khi
   trả lời và luôn kèm link sản phẩm.

Lưu skill, mở trang chi tiết skill. Ở mục Tên công cụ được phép,
chọn Nguồn công cụ (Admin, Web, Socket) rồi tick các tool cho
phép, ví dụ search_knowledge_data_list và
search_knowledge_data_by_type_and_id để AI tìm được dữ liệu tri thức.
Chatbot nhúng trên website chạy qua ezychat nên dùng tool của nguồn
Socket.

Gắn skill

Mở trang chi tiết profile.
Ở mục Các kỹ năng AI, tìm skill theo tên rồi bấm Thêm.
Có thể gắn nhiều skill. System prompt của các skill được ghép lại, tool
được phép là hợp các tool của những skill đó.

flowchart LR
    P["Profile<br/>Trợ lý bán hàng"] --> S1["Skill: Bán hàng<br/>prompt + search tools"]
    P --> S2["Skill: Chính sách đổi trả<br/>prompt"]
    S1 & S2 --> AI["Mỗi lượt chat:<br/>system message + tools"]

Chat thử

Mở trang chi tiết dịch vụ (/ezyai/ai-chat-services/{serviceName}),
khung Trò chuyện nằm ngay trên trang này.
Chọn profile vừa tạo (để trống là dùng profile mặc định).
Có thể ghi đè Mô hình, Số token tối đa, System message cho
lần thử; để trống thì dùng giá trị của profile.
Nhập tin nhắn và gửi. Câu trả lời hiện dần theo thời gian thực; khi xong
sẽ hiển thị model, số token và nguồn tri thức đã dùng (nếu có).

Nếu chat lỗi, kiểm tra lần lượt:

Hiện tượng	Hướng xử lý
Lỗi xác thực từ nhà cung cấp	Api key sai hoặc hết hạn, sửa profile và nhập lại key
Model không tồn tại	Tên model sai hoặc tài khoản không có quyền dùng model đó
Timeout	Tăng Thời gian chờ hoặc giảm Số token tối đa
AI không tìm dữ liệu của hệ thống	Profile chưa gắn skill có tool tìm kiếm, hoặc chưa chọn Nguồn dữ liệu
AI từ chối trả lời	Câu hỏi nằm ngoài các chủ đề cấu hình ở topic guard (`ezyai_topic_guard_allowed_topics`)

Nhúng chatbot lên website

Trang chi tiết profile cung cấp sẵn:

Embed snippet: đoạn mã để gắn khung chat vào website, bấm Sao chép
rồi dán vào trang web.
Support iframe: đoạn mã iframe cho trang hỗ trợ.
Xem giao diện: mở trang cấu hình giao diện chat của profile ở ezychat
để chỉnh màu sắc, lời chào, ...

Khi người dùng chat qua khung chat đã nhúng, ezychat gọi dịch vụ AI tương

ứng với profile thông qua ezyai-socket-plugin, dùng đúng api key, model,

skill và nguồn dữ liệu đã cấu hình.

Đặt profile mặc định và xoá profile

Đặt làm mặc định: ở trang chi tiết profile hoặc danh sách profile.
Profile mặc định được dùng khi nơi gọi không chỉ định tên profile, và
dùng để lấy danh sách model của dịch vụ. Nếu profile mặc định bị xoá hoặc
chưa đặt, hệ thống dùng profile ACTIVATED đầu tiên của dịch vụ.
Xoá: xoá profile cùng api key và toàn bộ metadata của nó. Các khung
chat đang nhúng bằng profile này sẽ không hoạt động nữa.

Hướng dẫn tạo một chat profile với EzyAI

Các bước tổng quát

Chuẩn bị

Chọn dịch vụ AI

Thêm profile

Điều gì xảy ra khi lưu

Sửa profile

Gắn skill vào profile

Tạo skill

Gắn skill

Chat thử

Nhúng chatbot lên website

Đặt profile mặc định và xoá profile

Table Of Contents

Hướng dẫn tạo một chat profile với EzyAI

Các bước tổng quát

Chuẩn bị

Chọn dịch vụ AI

Thêm profile

Điều gì xảy ra khi lưu

Sửa profile

Gắn skill vào profile

Tạo skill

Gắn skill

Chat thử

Nhúng chatbot lên website

Đặt profile mặc định và xoá profile

Table Of Contents

Sign In

Register

Forgot Password

Send Successfully