# Cấu hình hiển thị

> Tùy chỉnh phạm vi hiển thị, điều kiện hiển thị và giao diện widget của Trợ lý AI.

**Quyền truy cập:** Cần quyền **Cập nhật Chatbot** **Điều hướng:** `Trợ lý AI > Danh sách > [Chatbot] > Phạm vi hiển thị`

***

## Tổng quan

Cấu hình hiển thị (Display Rules) cho phép bạn kiểm soát khi nào và ở đâu Trợ lý AI xuất hiện cho người dùng. Bạn có thể thiết lập các điều kiện dựa trên vai trò người dùng, trang hiện tại, khóa học, nhóm, và nhiều tiêu chí khác.

Cấu hình hiển thị nằm trong tab **Phạm vi hiển thị** của trang cài đặt chatbot.

***

## Giao diện cài đặt chatbot

Trang cài đặt chatbot có 4 tab:

| Tab                  | Chức năng                                                                 |
| -------------------- | ------------------------------------------------------------------------- |
| **Tổng quan**        | Tên, model (chỉ đọc sau khi tạo), mô tả, ảnh đại diện, thông tin hệ thống |
| **Cơ sở tri thức**   | Gán/gỡ cơ sở tri thức với chatbot                                         |
| **Thiết lập trợ lý** | Playground thử tương tác + Cấu hình (System prompt, cài đặt nâng cao)     |
| **Phạm vi hiển thị** | Bật/tắt hiển thị, điều kiện hiển thị, giới hạn nâng cao                   |

***

## Cấu hình hiển thị cơ bản

### Bật/tắt hiển thị

| Trường        | Mô tả                                                                                    |
| ------------- | ---------------------------------------------------------------------------------------- |
| **isVisible** | Bật/tắt hiển thị chatbot. Chỉ chatbot có `isVisible = true` mới xuất hiện cho người dùng |

> **Quan trọng:** Chatbot chỉ hiển thị khi **tất cả** điều kiện sau đều thỏa mãn:
>
> * `status` = **Hoạt động**
> * `endpointStatus` = **Sẵn sàng**
> * `displayRules.isVisible` = `true`

### Phạm vi (Scope Type)

| Giá trị                  | Mô tả                                      |
| ------------------------ | ------------------------------------------ |
| **Công khai**            | Hiển thị cho tất cả người dùng             |
| **Học viên đã ghi danh** | Chỉ hiển thị cho học viên đã ghi danh      |
| **Phạm vi khóa học**     | Chỉ hiển thị trong phạm vi khóa học cụ thể |

### Độ ưu tiên

| Trường              | Mô tả                                                                                                              |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **displayPriority** | Số càng cao càng ưu tiên. Khi nhiều chatbot đều khớp điều kiện, chatbot có độ ưu tiên cao nhất được hiển thị trước |

### Ẩn khi hết hạn mức

| Trường                     | Mô tả                                                               |
| -------------------------- | ------------------------------------------------------------------- |
| **hideWhenLimitExhausted** | Nếu bật, chatbot sẽ tự động ẩn khi người dùng đã hết credit sử dụng |

***

## Điều kiện hiển thị nâng cao (Rule Set)

Hệ thống hỗ trợ tập hợp các điều kiện (conditions) để kiểm soát chi tiết việc hiển thị chatbot. Các điều kiện được đánh giá theo logic **AND** (tất cả phải đúng).

### Các trường điều kiện (Left Field)

| Trường                       | Mô tả                    |
| ---------------------------- | ------------------------ |
| `user.role`                  | Vai trò của người dùng   |
| `user.id`                    | ID của người dùng        |
| `page.path` / `page.urlPath` | Đường dẫn trang hiện tại |
| `course.id`                  | ID khóa học              |
| `lang`                       | Ngôn ngữ hiện tại        |
| `device.type`                | Loại thiết bị            |
| `group.id`                   | ID nhóm người dùng       |

### Các toán tử so sánh (Operator)

| Toán tử                       | Mô tả                     |
| ----------------------------- | ------------------------- |
| **Bằng**                      | Bằng                      |
| **Không bằng**                | Không bằng                |
| **Lớn hơn hoặc bằng**         | Lớn hơn hoặc bằng         |
| **Nhỏ hơn hoặc bằng**         | Nhỏ hơn hoặc bằng         |
| **Chứa**                      | Chứa                      |
| **Không chứa**                | Không chứa                |
| **Nằm trong danh sách**       | Nằm trong danh sách       |
| **Không nằm trong danh sách** | Không nằm trong danh sách |
| **Đạt đến**                   | Đạt đến                   |
| **Biểu thức chính quy**       | Khớp biểu thức chính quy  |

### Quy tắc đặc biệt cho Biểu thức chính quy trên đường dẫn URL

* Nhiều điều kiện **Biểu thức chính quy** trên `page.urlPath` được xử lý theo logic **OR** (chỉ cần một điều kiện đúng)
* Pattern tự động thêm tiền tố `^` để đảm bảo khớp từ đầu chuỗi
* Pattern tự động loại bỏ protocol và domain (chỉ giữ phần đường dẫn)
* Ký tự đại diện `*` được tự động chuyển thành `.*`
* Độ dài pattern tối đa 200 ký tự
* Hệ thống từ chối các pattern có nguy cơ gây lỗi hiệu suất (catastrophic backtracking)

**Ví dụ pattern:**

```
/classroom/.*          -> Khớp tất cả trang trong classroom
/manage/ai/.*          -> Khớp tất cả trang AI admin
/course/my-course/.*   -> Khớp tất cả trang của khóa học cụ thể
```

***

## Giới hạn nâng cao (Advanced Limits)

Ngoài điều kiện hiển thị, bạn có thể giới hạn chatbot chỉ hiển thị cho các đối tượng cụ thể:

| Loại giới hạn | Mô tả                          |
| ------------- | ------------------------------ |
| **users**     | Danh sách ID người dùng cụ thể |
| **groups**    | Danh sách ID nhóm              |
| **courses**   | Danh sách ID khóa học          |

***

## Ngữ cảnh tự động (Context Enrichment)

Khi đánh giá điều kiện hiển thị, hệ thống tự động bổ sung ngữ cảnh:

* **courseId từ URL:** Nếu người dùng đang ở trang `/classroom/:courseSlug`, hệ thống tự động tra cứu `courseId` từ slug của khóa học
* **Cache:** Kết quả tra cứu course slug được cache 5 phút để tăng hiệu suất

***

## Cài đặt giao diện Widget

Cấu hình giao diện chat widget hiển thị cho người dùng cuối:

| Trường             | Mô tả                       |
| ------------------ | --------------------------- |
| **themeColor**     | Màu chủ đạo của widget      |
| **position**       | Vị trí hiển thị trên trang  |
| **iconSize**       | Kích thước icon             |
| **launcherShape**  | Hình dạng nút mở chat       |
| **welcomeTitle**   | Tiêu đề chào mừng           |
| **welcomeMessage** | Nội dung tin nhắn chào mừng |

Cấu hình widget được truy xuất qua phương thức `AI.chat.widgetAppearance`, trả về cấu hình từ Settings của hệ thống.

***

## Tab Thiết lập trợ lý

Tab này chia thành 2 phần:

### Playground (bên trái)

* Giao diện chat thử nghiệm để tương tác trực tiếp với chatbot
* Giúp kiểm tra hành vi trước khi triển khai

### Cấu hình (bên phải)

**Sub-tab Hướng dẫn (Instructions):**

* Chỉnh sửa system prompt (hướng dẫn trả lời)
* Hiển thị trạng thái đồng bộ prompt

**Sub-tab Cài đặt (Settings):**

| Trường              | Mô tả                                                  | Giới hạn     |
| ------------------- | ------------------------------------------------------ | ------------ |
| **maxTokens**       | Số token tối đa cho mỗi câu trả lời                    | 128 - 16.384 |
| **temperature**     | Độ sáng tạo của câu trả lời                            | 0 - 1        |
| **topP**            | Xác suất tích lũy của token                            | 0 - 1        |
| **topK**            | Số lượng token ứng viên                                | 0 - 10       |
| **retrievalMethod** | Phương pháp truy xuất: `none` hoặc `include_citations` | -            |

***

## Lưu ý

* **Chatbot phải ở trạng thái Hoạt động và endpointStatus là Sẵn sàng** mới có thể hiển thị cho người dùng.
* **isVisible mặc định là `false`** khi tạo chatbot mới. Bạn cần bật thủ công.
* **Regex pattern** nên ngắn gọn và cụ thể. Pattern quá rộng có thể ảnh hưởng hiệu suất.
* **Độ ưu tiên** quan trọng khi có nhiều chatbot. Chatbot có `displayPriority` cao nhất sẽ được ưu tiên hiển thị.
* **Thay đổi display rules** có hiệu lực ngay lập tức, không cần khởi động lại.

***

## Xem thêm

* [Tạo trợ lý AI](https://docs.noova.vn/tri-tue-nhan-tao/06-ai-tro-ly/tao-chatbot) -- Tạo chatbot mới
* [Cơ sở tri thức](https://docs.noova.vn/tri-tue-nhan-tao/06-ai-tro-ly/co-so-tri-thuc) -- Quản lý tài liệu cho chatbot
* [Credits](https://docs.noova.vn/tri-tue-nhan-tao/06-ai-tro-ly/credits) -- Quản lý hạn mức sử dụng