# AI Models



Assistant Core hỗ trợ nhiều AI model cho chat, voice và realtime conversation. Tùy plan, bạn sẽ thấy các model phù hợp trong phần cấu hình assistant.

Providers [#providers]

| Provider          | Hỗ trợ                                               |
| ----------------- | ---------------------------------------------------- |
| OpenAI            | Chat, Text to Speech, Speech to Text, Realtime Voice |
| Anthropic         | Chat                                                 |
| Google AI         | Chat, Realtime Voice                                 |
| X.AI              | Chat, Text to Speech, Speech to Text, Realtime Voice |
| DeepSeek          | Chat                                                 |
| ElevenLabs        | Text to Speech, Speech to Text                       |
| Soniox            | Text to Speech, Speech to Text                       |
| Local/Open Source | Voice Activity Detection                             |

Model Types [#model-types]

| Type                     | Dùng để làm gì                                                                    |
| ------------------------ | --------------------------------------------------------------------------------- |
| Chat                     | Trả lời câu hỏi, reasoning, tool use và xử lý multimodal content nếu model hỗ trợ |
| Voice Activity Detection | Phát hiện lúc user bắt đầu hoặc ngừng nói                                         |
| Speech to Text           | Transcribe audio thành text                                                       |
| Text to Speech           | Tạo audio từ text                                                                 |
| Realtime Voice           | Voice conversation hai chiều với latency thấp                                     |

Voice Models [#voice-models]

Voice Activity Detection [#voice-activity-detection]

| Provider          | Models     |
| ----------------- | ---------- |
| Local/Open Source | Silero VAD |

Speech To Text [#speech-to-text]

| Provider   | Models                                    |
| ---------- | ----------------------------------------- |
| OpenAI     | GPT-4o Transcribe, GPT-4o Mini Transcribe |
| ElevenLabs | ElevenLabs Scribe v2                      |
| Soniox     | Soniox STT Real-Time v4                   |
| X.AI       | xAI Grok STT                              |

Text To Speech [#text-to-speech]

| Provider   | Models                |
| ---------- | --------------------- |
| OpenAI     | GPT-4o Mini TTS       |
| ElevenLabs | ElevenLabs Flash v2.5 |
| X.AI       | Grok 2 TTS            |
| Soniox     | Soniox TTS RT v1      |

Realtime Voice [#realtime-voice]

| Provider  | Models                              |
| --------- | ----------------------------------- |
| OpenAI    | GPT Realtime 1.5, GPT Realtime Mini |
| Google AI | Gemini 2.5 Flash Live               |
| X.AI      | xAI Grok Voice Agent                |

Chat Models [#chat-models]

| Provider  | Models                                                                            |
| --------- | --------------------------------------------------------------------------------- |
| OpenAI    | GPT-5.4, GPT-5.4 Mini, GPT-5.4 Nano, GPT-5.1, GPT-4.1, GPT-4.1 Mini, GPT-4.1 Nano |
| Anthropic | Claude Sonnet 4.5, Claude Haiku 4.5                                               |
| Google AI | Gemini 2.5 Pro, Gemini 2.5 Flash, Gemma 4 31B                                     |
| X.AI      | Grok 4.3                                                                          |
| DeepSeek  | DeepSeek V4 Flash, DeepSeek V4 Pro                                                |

Plan Access [#plan-access]

| Plan       | Models có thể dùng                                                               |
| ---------- | -------------------------------------------------------------------------------- |
| Free       | Gemini 2.5 Flash, GPT-4.1 Mini                                                   |
| Go         | Các Gemini models, gồm Gemini 2.5 Flash, Gemini 2.5 Pro và Gemini 2.5 Flash Live |
| Plus       | OpenAI GPT models và Gemini models                                               |
| Pro        | Tất cả supported models                                                          |
| Enterprise | Tất cả supported models                                                          |

Default Models [#default-models]

Khi bạn tạo tài khoản hoặc join một assistant, các model sau sẽ được chọn sẵn. Bạn có thể thay đổi trong phần **Settings** bất kỳ lúc nào.

| Loại                     | Model mặc định       |
| ------------------------ | -------------------- |
| Chat (LLM)               | GPT-4.1 Mini         |
| Text to Speech           | Grok 2 TTS           |
| Speech to Text           | xAI Grok STT         |
| Voice Activity Detection | Silero VAD           |
| Realtime Voice           | xAI Grok Voice Agent |

<Callout type="info">
  Default model giống nhau cho mọi plan. Sự khác biệt giữa các plan nằm ở **danh sách model khả dụng** — plan cao hơn mở khóa thêm nhiều model để bạn chuyển đổi.
</Callout>

<Callout type="info">
  Một số capability như realtime voice, daily messages, devices, Knowledge Base documents và voice minutes vẫn phụ thuộc vào quota của từng plan.
</Callout>


# Tạo Tài Khoản



Tùy Chọn Đăng Ký [#tùy-chọn-đăng-ký]

Bạn có thể tạo tài khoản bằng:

1. **Email & Mật khẩu** — Nhập email và tạo mật khẩu
2. **Google** — Đăng nhập bằng tài khoản Google (một chạm)
3. **GitHub** — Đăng nhập bằng tài khoản GitHub (một chạm)

Các Bước [#các-bước]

Cách 1: Email & Mật khẩu [#cách-1-email--mật-khẩu]

1. Truy cập **Bảng Điều Khiển** tại [admin.assistantcore.com](https://admin.assistantcore.com)
2. Nhấn **Đăng Ký**
3. Nhập địa chỉ email và tạo mật khẩu
4. Nhấn **Tạo Tài Khoản**
5. Bạn sẽ được chuyển đến bảng điều khiển

Cách 2: Google hoặc GitHub [#cách-2-google-hoặc-github]

1. Truy cập **Bảng Điều Khiển**
2. Nhấn **Tiếp tục với Google** hoặc **Tiếp tục với GitHub**
3. Cho phép ứng dụng truy cập
4. Bạn sẽ được chuyển đến bảng điều khiển tự động

<Callout type="info">
  Tạo tài khoản miễn phí. Mỗi trợ lý mới bắt đầu với **gói Miễn Phí** với các
  tính năng cơ bản.
</Callout>

Tiếp Theo? [#tiếp-theo]

<Cards>
  <Card title="Tạo Trợ Lý Đầu Tiên" href="/create-assistant" />
</Cards>


# Tạo Assistant Đầu Tiên



Tổng Quan [#tổng-quan]

**Assistant** là AI agent của bạn. Nó có Knowledge Base riêng, model config, voice settings, và có thể được share hoặc embed vào website.

Tạo Assistant [#tạo-assistant]

1. Trong **Admin Dashboard**, nhấn **New Assistant**
2. Điền thông tin:
   * **Tên** — Đặt tên mô tả (ví dụ: "Bot Hỗ Trợ Khách Hàng")
   * **Mô tả** — Miêu tả ngắn gọn chức năng
   * **System Prompt** — Hướng dẫn cách assistant hoạt động

<Callout type="tip">
  System prompt tốt là chìa khóa. Ví dụ: *"Bạn là nhân viên hỗ trợ thân thiện
  của công ty ABC. Trả lời câu hỏi dựa trên tài liệu. Lịch sự và ngắn gọn."*
</Callout>

3. Nhấn **Tạo**

Cấu Hình AI Model [#cấu-hình-ai-model]

1. Vào **Assistant Settings → Models**
2. Chọn LLM model theo plan:
   * **Gemini 2.5 Flash** — Có trong Free plan
   * **Gemini 2.5 Pro** — Có trong Go plan trở lên
   * **GPT-5.4 / GPT-4.1** — Có trong Plus plan trở lên
   * **Claude Sonnet 4.5 / Grok 4.3 / DeepSeek V4 Pro** — Có trong Pro và Enterprise plan
3. Nhấn **Lưu**

Thêm Knowledge Base (Tùy chọn) [#thêm-knowledge-base-tùy-chọn]

1. Vào tab **Knowledge Base**
2. Nhấn **Upload Documents**
3. Kéo thả file (PDF, DOCX, TXT, XLSX)
4. Đợi xử lý hoàn tất

Tiếp Theo? [#tiếp-theo]

<Cards>
  <Card title="AI Models" href="/ai-models" />

  <Card title="Upload Documents" href="/knowledge-base/upload-documents" />

  <Card title="Tools & MCP" href="/tools-mcp" />
</Cards>


# Chào mừng đến với Assistant Core



Assistant Core là gì? [#assistant-core-là-gì]

Assistant Core là nền tảng giúp bạn tạo AI assistant sử dụng documents của riêng bạn, kết hợp voice và triển khai đa kênh.

Bạn có thể làm gì [#bạn-có-thể-làm-gì]

* **Upload documents** và để AI trả lời câu hỏi dựa trên nội dung
* **Bật voice** cho conversation tự nhiên (Auto hoặc Realtime mode)
* **Nhúng chatbot** vào bất kỳ website nào
* **Kết nối ESP32 device** cho hardware voice assistant
* **Chọn AI model** — GPT-5.4, Gemini, Claude, Grok, DeepSeek và nhiều hơn

Bắt Đầu Nhanh [#bắt-đầu-nhanh]

<Cards>
  <Card title="Tạo Tài Khoản" description="Đăng ký bằng Email, Google hoặc GitHub" href="/create-account" />

  <Card title="Tạo Assistant Đầu Tiên" description="Cấu hình AI model, system prompt và Knowledge Base" href="/create-assistant" />

  <Card title="AI Models" description="GPT, Gemini, Claude, Grok, DeepSeek — xem plan access" href="/ai-models" />
</Cards>

Khám Phá Tính Năng [#khám-phá-tính-năng]

<Cards>
  <Card title="Knowledge Base" description="Upload tài liệu để AI trả lời dựa trên nội dung" href="/knowledge-base/upload-documents" />

  <Card title="Memory" description="AI ghi nhớ thông tin cá nhân xuyên các cuộc hội thoại" href="/memory/overview" />

  <Card title="Voice" description="Hội thoại giọng nói với Auto hoặc Realtime mode" href="/voice/enable-voice" />

  <Card title="Tools & MCP" description="Kết nối API, MCP server và công cụ thiết bị" href="/tools-mcp" />

  <Card title="Nhúng Chatbot" description="Thêm widget chat vào website với một đoạn mã" href="/embed-integrate/embed-chatbot" />

  <Card title="Thiết Bị ESP32" description="Kết nối phần cứng cho voice assistant vật lý" href="/devices" />

  <Card title="Firmware" description="Nạp firmware ESP32 trực tiếp từ trình duyệt" href="/firmware" />

  <Card title="Plans & Pricing" description="So sánh gói Free, Plus, Pro và Enterprise" href="/billing/plans-pricing" />
</Cards>


# Quản Lý Đăng Ký



Tổng Quan [#tổng-quan]

Đăng ký của bạn là **toàn cục theo người dùng** — một gói áp dụng cho mức sử dụng của bạn trên tất cả trợ lý bạn tương tác.

Nâng Cấp [#nâng-cấp]

1. Vào **Tài Khoản** → **Đăng Ký Của Tôi**
2. Nhấn **Nâng Cấp Gói**
3. Chọn gói mong muốn (Plus, Pro, hoặc Enterprise)
4. Chọn chu kỳ thanh toán (Hàng tháng hoặc Hàng năm)
5. Hoàn tất thanh toán qua SePay
6. Gói mới được kích hoạt ngay lập tức

Hạ Cấp [#hạ-cấp]

1. Vào **Đăng Ký Của Tôi**
2. Nhấn **Đổi Gói**
3. Chọn gói thấp hơn
4. Việc hạ cấp có hiệu lực vào cuối kỳ thanh toán hiện tại

<Callout type="warn">
  Khi hạ cấp, bạn có thể mất quyền truy cập tính năng và quota sẽ bị giảm.
  Hãy đảm bảo điều chỉnh mức sử dụng trước khi thay đổi có hiệu lực.
</Callout>

Hủy [#hủy]

1. Vào **Đăng Ký Của Tôi**
2. Nhấn **Hủy Đăng Ký**
3. Xác nhận hủy
4. Tài khoản của bạn chuyển về gói **Miễn Phí** ngay lập tức

Chu Kỳ Thanh Toán [#chu-kỳ-thanh-toán]

* **Hàng tháng** — Gia hạn mỗi 30 ngày
* **Hàng năm** — Gia hạn mỗi 365 ngày (tiết kiệm \~20%)
* **Thời gian ân hạn** — 3 ngày sau khi hết hạn trước khi tự động hạ về gói Miễn Phí

Phương Thức Thanh Toán [#phương-thức-thanh-toán]

Hiện hỗ trợ qua cổng thanh toán **SePay** với chuyển khoản ngân hàng (VND).


# Plans & Pricing



Plan Comparison [#plan-comparison]

| Feature             | Free        | Plus         | Pro            | Enterprise     |
| ------------------- | ----------- | ------------ | -------------- | -------------- |
| **Price**           | $0/tháng    | $9.99/tháng  | $29.99/tháng   | Liên hệ        |
| **Messages/day**    | 50          | 200          | 1,000          | Không giới hạn |
| **Auto Voice**      | 5 phút/ngày | 30 phút/ngày | 120 phút/ngày  | Không giới hạn |
| **Realtime Voice**  | ❌           | 15 phút/ngày | 60 phút/ngày   | Không giới hạn |
| **KB Documents**    | 5           | 20           | 50             | Không giới hạn |
| **Devices**         | 1           | 3            | 10             | Không giới hạn |
| **Users/assistant** | 1           | 6            | 22             | Không giới hạn |
| **Assistants**      | 1           | 3            | 10             | Không giới hạn |
| **Memory**          | 7 ngày      | 30 ngày      | Không giới hạn | Không giới hạn |

AI Model Access [#ai-model-access]

| Plan           | Models khả dụng                                     |
| -------------- | --------------------------------------------------- |
| **Miễn Phí**   | Gemini 2.5 Flash, GPT-4.1 Mini                      |
| **Go**         | Các Gemini models (Flash, Pro, Flash Live)          |
| **Plus**       | + GPT models, Gemini models                         |
| **Pro**        | Tất cả models (GPT, Claude, Grok, DeepSeek, Gemini) |
| **Enterprise** | Tất cả models                                       |

Feature Access [#feature-access]

| Feature        | Free | Plus | Pro | Enterprise |
| -------------- | ---- | ---- | --- | ---------- |
| Public Share   | ❌    | ✅    | ✅   | ✅          |
| Widget Embed   | ❌    | ❌    | ✅   | ✅          |
| Custom Domain  | ❌    | ❌    | ✅   | ✅          |
| White Labeling | ❌    | ❌    | ❌   | ✅          |
| API Access     | ❌    | ❌    | ❌   | ✅          |
| MCP Tools      | ❌    | ✅    | ✅   | ✅          |
| Realtime Voice | ❌    | ✅    | ✅   | ✅          |

Annual Pricing [#annual-pricing]

Tiết kiệm \~20% khi thanh toán hàng năm:

| Plan | Monthly      | Annual (per month) |
| ---- | ------------ | ------------------ |
| Plus | $9.99/tháng  | $7.99/tháng        |
| Pro  | $29.99/tháng | $23.99/tháng       |

<Callout type="info">
  Subscription của bạn là **user-global** — một plan áp dụng cho mức sử dụng
  của bạn và tất cả assistant bạn sở hữu.
</Callout>


# Sử Dụng & Quota



Xem Mức Sử Dụng [#xem-mức-sử-dụng]

1. Vào **Tài Khoản** → **Đăng Ký Của Tôi**
2. **Tổng quan sử dụng** hiển thị mức tiêu thụ hàng ngày của bạn:
   * Tin nhắn đã gửi hôm nay / giới hạn ngày
   * Phút Auto Voice đã dùng / giới hạn ngày
   * Phút Realtime Voice đã dùng / giới hạn ngày

Quota Hàng Ngày [#quota-hàng-ngày]

Quota tính **theo người dùng** và được đặt lại mỗi ngày lúc 00:00 (UTC):

| Quota              | Theo dõi gì                              |
| ------------------ | ---------------------------------------- |
| **Tin nhắn**       | Tin nhắn chat bạn gửi trên tất cả trợ lý |
| **Auto Voice**     | Phút hội thoại giọng nói theo lượt       |
| **Realtime Voice** | Phút hội thoại giọng nói thời gian thực  |

<Callout type="info">
  Quota sử dụng là toàn cục theo người dùng. Số tin nhắn hàng ngày được chia sẻ
  trên tất cả trợ lý bạn tương tác.
</Callout>

Giới Hạn Tài Nguyên [#giới-hạn-tài-nguyên]

Đây là tổng số trên mỗi trợ lý (không theo ngày), dựa trên gói của **chủ sở hữu trợ lý**:

| Tài nguyên      | Theo dõi gì                         |
| --------------- | ----------------------------------- |
| **Tài liệu KB** | Tổng số tệp trong cơ sở tri thức    |
| **Thiết bị**    | Thiết bị ESP32/phần cứng đã kết nối |
| **Người dùng**  | Người có quyền truy cập trợ lý      |
| **Trợ lý**      | Tổng số trợ lý bạn có thể tạo       |

Giới Hạn Theo Gói [#giới-hạn-theo-gói]

| Quota / Tài nguyên  | Miễn Phí | Plus    | Pro   | Enterprise |
| ------------------- | -------- | ------- | ----- | ---------- |
| Tin nhắn/ngày       | 50       | 200     | 1,000 | ∞          |
| Auto Voice/ngày     | 5 phút   | 30 phút | 2 giờ | ∞          |
| Realtime Voice/ngày | —        | 15 phút | 1 giờ | ∞          |
| Tài liệu KB         | 5        | 20      | 50    | ∞          |
| Thiết bị            | 1        | 3       | 10    | ∞          |
| Người dùng/trợ lý   | 1        | 6       | 22    | ∞          |
| **Trợ lý sở hữu**   | 1        | 3       | 10    | ∞          |
| Lưu trữ bộ nhớ      | 7 ngày   | 30 ngày | ∞     | ∞          |

Khi Hết Giới Hạn? [#khi-hết-giới-hạn]

* **Tin nhắn** — Người dùng thấy thông báo "Đã hết giới hạn tin nhắn"
* **Giọng nói** — Nút micro bị vô hiệu trong ngày
* **Tài liệu KB** — Không thể tải thêm tệp cho đến khi xóa bớt hoặc nâng cấp
* **Thiết bị** — Không thể đăng ký thiết bị mới
* **Trợ lý** — Không thể tạo trợ lý mới cho đến khi xóa bớt hoặc nâng cấp

Cần Thêm? [#cần-thêm]

[So sánh các gói](/billing/plans-pricing) để tìm gói phù hợp với mức sử dụng của bạn, hoặc [liên hệ chúng tôi](mailto:support@assistantcore.com) để biết giá Enterprise.


# Tùy Chỉnh Giao Diện



import { Callout } from "fumadocs-ui/components/callout";
import { Steps } from "fumadocs-ui/components/steps";

Tổng Quan [#tổng-quan]

Một số thiết bị ESP32 có màn hình có thể hiển thị chữ, emoji cảm xúc, hình nền và trạng thái hội thoại. Tính năng tùy chỉnh giao diện cho phép bạn tạo một gói giao diện riêng rồi gửi xuống thiết bị.

Bạn có thể dùng tính năng này để:

* Chọn font phù hợp với ngôn ngữ của trợ lý.
* Đổi bộ emoji/cảm xúc hiển thị trên màn hình.
* Chọn màu nền hoặc ảnh nền cho chế độ sáng/tối.
* Cấu hình lệnh đánh thức nếu firmware và chip hỗ trợ.

Khi Nào Nên Tùy Chỉnh? [#khi-nào-nên-tùy-chỉnh]

| Nhu cầu                                          | Gợi ý                                                           |
| ------------------------------------------------ | --------------------------------------------------------------- |
| Trợ lý dùng tiếng Việt                           | Chọn font hỗ trợ tiếng Việt tốt.                                |
| Thiết bị đặt ở cửa hàng, showroom hoặc văn phòng | Dùng màu nền, emoji và font khớp với thương hiệu.               |
| Thiết bị có màn hình nhỏ                         | Ưu tiên font dễ đọc, emoji kích thước vừa phải và nền đơn giản. |
| Thiết bị dùng wake word riêng                    | Kiểm tra chip/firmware có hỗ trợ lệnh đánh thức tùy chỉnh.      |

Quy Trình Tạo Giao Diện [#quy-trình-tạo-giao-diện]

<Steps>
  Bước 1: Chọn thiết bị [#bước-1-chọn-thiết-bị]

  Chọn đúng board, chip và kích thước màn hình. Nếu chọn sai độ phân giải, hình nền hoặc emoji có thể bị méo hoặc hiển thị không đúng vị trí.

  Bước 2: Chọn font [#bước-2-chọn-font]

  Chọn font có đủ ký tự cho ngôn ngữ trợ lý đang dùng. Với tiếng Việt, nên dùng font hỗ trợ dấu tiếng Việt đầy đủ.

  Bước 3: Chọn emoji và hình nền [#bước-3-chọn-emoji-và-hình-nền]

  Chọn bộ emoji biểu cảm và màu nền/ảnh nền cho màn hình. Hình nền càng đơn giản thì chữ và trạng thái hội thoại càng dễ đọc.

  Bước 4: Xuất gói giao diện [#bước-4-xuất-gói-giao-diện]

  Sau khi xem trước, xuất gói giao diện thành file `assets.bin`.

  Bước 5: Gửi xuống thiết bị [#bước-5-gửi-xuống-thiết-bị]

  Vào **Thiết Bị** trong Bảng Điều Khiển, chọn thiết bị ESP32 và upload file `assets.bin`. Thiết bị sẽ tải gói giao diện và áp dụng sau khi cập nhật xong.
</Steps>

Lưu Ý Khi Chọn Nội Dung [#lưu-ý-khi-chọn-nội-dung]

| Thành phần    | Lưu ý                                                                                                 |
| ------------- | ----------------------------------------------------------------------------------------------------- |
| **Font chữ**  | Chọn font đủ ký tự cho ngôn ngữ chính của trợ lý. Font quá lớn có thể làm gói giao diện nặng hơn.     |
| **Emoji**     | Dùng bộ emoji có kích thước phù hợp với màn hình. Ảnh động đẹp hơn nhưng có thể cần nhiều bộ nhớ hơn. |
| **Hình nền**  | Tránh ảnh quá nhiều chi tiết vì chữ trên màn hình sẽ khó đọc.                                         |
| **Wake word** | Không phải chip/firmware nào cũng hỗ trợ lệnh đánh thức tùy chỉnh.                                    |

Thiết Bị Hỗ Trợ [#thiết-bị-hỗ-trợ]

Tùy chỉnh giao diện chỉ áp dụng cho thiết bị ESP32 có màn hình và firmware hỗ trợ gói giao diện. Thiết bị không có màn hình, web chat hoặc watch client sẽ không dùng phần này.

<Callout type="warning">
  Nếu thiết bị không áp dụng giao diện mới, hãy kiểm tra đúng board, đúng kích thước màn hình và phiên bản firmware. Sau đó khởi động lại thiết bị và thử upload lại gói giao diện.
</Callout>


# Tổng Quan



Thiết bị là phần cứng có thể kết nối với trợ lý để nghe, nói, hiển thị trạng thái, nhận lệnh và cung cấp khả năng riêng. Phổ biến nhất là các board ESP32 chạy firmware giọng nói, nhưng cùng một mô hình có thể mở rộng cho thiết bị có màn hình, cảm biến, đèn, loa hoặc module điều khiển ngoại vi.

Mỗi thiết bị được đăng ký trong Bảng Điều Khiển và liên kết với một trợ lý cụ thể. Sau khi liên kết, thiết bị sẽ nhận cấu hình từ nền tảng, bắt đầu hội thoại giọng nói và có thể thực hiện các lệnh mà trợ lý gửi xuống.

Thiết Bị Gồm Những Gì? [#thiết-bị-gồm-những-gì]

Một thiết bị thường bao gồm:

| Thành phần              | Vai trò                                                                                      |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| **Firmware**            | Chạy trên ESP32 hoặc phần cứng tương thích, xử lý audio, màn hình, nút bấm và kết nối mạng   |
| **Thông tin thiết bị**  | Tên, MAC, board, phiên bản firmware, trợ lý đang liên kết và trạng thái online               |
| **Phiên giọng nói**     | Cuộc hội thoại thời gian thực giữa thiết bị và trợ lý                                        |
| **Công cụ thiết bị**    | Khả năng mà trợ lý có thể gọi, ví dụ đổi màu LED, đọc cảm biến hoặc điều khiển phần cứng     |
| **Giao diện tùy chỉnh** | Font, emoji, nền chat và wake word được đóng gói thành `assets.bin` cho thiết bị có màn hình |

Kiến Trúc Kết Nối [#kiến-trúc-kết-nối]

<Mermaid
  chart={`graph LR
  subgraph Device["🔌 ESP32 Device"]
      MIC["🎤 Micro"]
      SPK["🔊 Loa"]
      LCD["📱 Màn hình"]
  end
  subgraph Gateway["☁️ MQTT Gateway"]
      MQTT["MQTT Broker\n(Điều khiển)"]
      UDP_T["UDP Transport\n(Audio)"]
  end
  subgraph Core["⚡ Assistant Core"]
      VOICE["Voice Pipeline"]
      CHAT["Chat / LLM"]
      TOOLS["Tools & MCP"]
      KB["Knowledge Base"]
      MEM["Memory"]
  end
  MIC -->|"Opus Audio"| UDP_T
  UDP_T -->|"Voice Session"| VOICE
  VOICE --> CHAT
  CHAT --> TOOLS
  CHAT --> KB
  CHAT --> MEM
  VOICE -->|"TTS Audio"| UDP_T
  UDP_T -->|"Opus Audio"| SPK
  Device <-->|"Status & Commands"| MQTT
  MQTT <-->|"Admin API"| Core`}
/>

Thiết bị không nói chuyện trực tiếp với toàn bộ hệ thống phía sau. Nó chỉ cần kết nối tới MQTT Gateway; gateway chịu trách nhiệm chuyển tiếp trạng thái, âm thanh và lệnh tới đúng phiên trợ lý.

Vòng Đời Thiết Bị [#vòng-đời-thiết-bị]

<Mermaid
  chart={`graph TD
  A["1. Flash Firmware"] --> B["2. Kết nối Wi-Fi"]
  B --> C["3. Lấy cấu hình OTA"]
  C --> D{"Đã liên kết?"}
  D -->|"Chưa"| E["Hiển thị mã 6 số"]
  E --> F["4. Nhập mã trong Admin"]
  F --> G["5. Liên kết trợ lý"]
  D -->|"Rồi"| G
  G --> H["6. Sẵn sàng hội thoại"]
  H --> I["7. Cập nhật OTA"]
  I --> H`}
/>

Bạn Muốn Làm Gì? [#bạn-muốn-làm-gì]

| Nhu cầu                                    | Trang liên quan                               |
| ------------------------------------------ | --------------------------------------------- |
| Thêm thiết bị mới vào workspace            | [Đăng Ký Thiết Bị](/devices/register-device)  |
| Cập nhật firmware từ xa                    | [Cập Nhật Firmware OTA](/devices/ota-updates) |
| Xem tài liệu kỹ thuật về giao thức kết nối | [Giao Thức MQTT](/devices/mqtt-protocol)      |
| Tùy chỉnh font, emoji, nền và wake word    | [Tùy Chỉnh Giao Diện](/devices/custom-assets) |
| Cho trợ lý gọi khả năng trên thiết bị      | [Device Tools](/tools-mcp/device-tools)       |

<Callout type="info">
  Nếu bạn chỉ muốn kết nối ESP32 để nói chuyện với trợ lý, hãy bắt đầu từ trang đăng ký thiết bị. Trang MQTT Protocol dành cho người đang phát triển firmware hoặc triển khai hạ tầng kết nối.
</Callout>


# Giao Thức MQTT





import { Callout } from "fumadocs-ui/components/callout";
import { Steps } from "fumadocs-ui/components/steps";

Tổng Quan [#tổng-quan]

Thiết bị ESP32 dùng **MQTT Gateway** để giữ kết nối thời gian thực với Assistant Core. Gateway đứng giữa thiết bị và nền tảng, giúp thiết bị gửi trạng thái, mở phiên giọng nói, truyền âm thanh và nhận lệnh điều khiển từ trợ lý.

Ở mức khái niệm, kết nối gồm ba phần:

* **MQTT**: kênh điều khiển cho trạng thái, sự kiện và lệnh.
* **UDP audio**: kênh truyền âm thanh độ trễ thấp cho phiên giọng nói.
* **Kết nối nội bộ tới Assistant Core**: gateway chuyển tiếp phiên thiết bị vào hệ thống xử lý hội thoại.

Kiến Trúc Kết Nối [#kiến-trúc-kết-nối]

<img alt="Sơ đồ MQTT Gateway kết nối ESP32 Device với Assistant Core" src={__img0} placeholder="blur" />

Thiết bị không nói chuyện trực tiếp với toàn bộ hệ thống phía sau. Nó chỉ cần kết nối tới MQTT Gateway; gateway chịu trách nhiệm chuyển tiếp trạng thái, âm thanh và lệnh tới đúng phiên trợ lý.

Luồng Hoạt Động [#luồng-hoạt-động]

<Steps>
  1. Thiết bị lấy cấu hình kết nối [#1-thiết-bị-lấy-cấu-hình-kết-nối]

  Khi khởi động, thiết bị kiểm tra OTA để nhận thời gian hệ thống, thông tin firmware, mã kích hoạt nếu chưa liên kết và địa chỉ kết nối tới gateway.

  2. Thiết bị mở kênh MQTT [#2-thiết-bị-mở-kênh-mqtt]

  Thiết bị dùng MQTT để báo online, gửi sự kiện và nhận lệnh. Đây là kênh điều khiển chính, không dùng để truyền audio liên tục.

  3. Thiết bị bắt đầu phiên giọng nói [#3-thiết-bị-bắt-đầu-phiên-giọng-nói]

  Khi người dùng đánh thức thiết bị hoặc nhấn nút nói, thiết bị gửi tín hiệu bắt đầu phiên. Gateway tạo phiên tương ứng trong Assistant Core.

  4. Âm thanh đi qua kênh UDP [#4-âm-thanh-đi-qua-kênh-udp]

  Trong phiên giọng nói, audio từ micro được gửi qua UDP để giảm độ trễ. Phản hồi TTS từ trợ lý cũng được gửi ngược về thiết bị qua kênh audio.

  5. Lệnh điều khiển đi qua MQTT [#5-lệnh-điều-khiển-đi-qua-mqtt]

  Các lệnh như đổi trạng thái, cập nhật giao diện, gọi công cụ thiết bị hoặc kết thúc phiên được gửi qua MQTT để thiết bị xử lý.
</Steps>

MQTT Dùng Cho Việc Gì? [#mqtt-dùng-cho-việc-gì]

| Nhóm dữ liệu            | Ví dụ                                                 |
| ----------------------- | ----------------------------------------------------- |
| **Trạng thái thiết bị** | Online/offline, sẵn sàng nói chuyện, đang trong phiên |
| **Sự kiện thiết bị**    | Wake word, nhấn nút, bắt đầu/kết thúc phiên           |
| **Lệnh từ trợ lý**      | Hiển thị text, đổi trạng thái, gọi công cụ thiết bị   |
| **Quản lý phiên**       | Mở phiên giọng nói, đóng phiên, báo lỗi               |

UDP Audio Dùng Cho Việc Gì? [#udp-audio-dùng-cho-việc-gì]

MQTT phù hợp cho tin nhắn điều khiển nhỏ, nhưng không phù hợp để truyền audio liên tục với độ trễ thấp. Vì vậy âm thanh được tách sang kênh UDP:

* Micro của thiết bị gửi audio lên gateway.
* Assistant Core xử lý hội thoại và tạo phản hồi.
* Audio phản hồi được gửi lại thiết bị để phát qua loa.

Thiết kế này giúp phiên giọng nói phản hồi nhanh hơn và tránh làm nghẽn kênh điều khiển MQTT.

Trạng Thái Kết Nối Thường Gặp [#trạng-thái-kết-nối-thường-gặp]

| Trạng thái           | Ý nghĩa                                                       |
| -------------------- | ------------------------------------------------------------- |
| **Chưa liên kết**    | Thiết bị đã lấy được cấu hình nhưng chưa gắn với trợ lý.      |
| **Online**           | Thiết bị đã kết nối MQTT Gateway và sẵn sàng nhận lệnh.       |
| **Đang trong phiên** | Thiết bị đang truyền audio và nhận phản hồi từ trợ lý.        |
| **Offline**          | Thiết bị mất nguồn, mất mạng hoặc không kết nối được gateway. |

Khi Cần Troubleshoot [#khi-cần-troubleshoot]

1. Nếu thiết bị không online, kiểm tra Wi-Fi, nguồn và firmware.
2. Nếu thiết bị có mã kích hoạt nhưng chưa dùng được, kiểm tra đã liên kết đúng trợ lý chưa.
3. Nếu thiết bị online nhưng không nói chuyện được, kiểm tra giọng nói đã bật cho trợ lý và thiết bị có nhận được cấu hình OTA mới nhất.
4. Nếu âm thanh bị trễ hoặc ngắt quãng, kiểm tra chất lượng mạng và firewall có chặn kết nối audio không.
5. Nếu lệnh thiết bị không chạy, kiểm tra firmware có hỗ trợ công cụ tương ứng không.

<Callout type="info">
  Trang này mô tả kiến trúc giao thức ở mức vận hành. Các chi tiết như chữ ký xác thực, payload JSON đầy đủ hoặc cấu hình Docker là phần dành cho tài liệu triển khai nội bộ.
</Callout>


# Cập Nhật Firmware (OTA)



Tổng Quan [#tổng-quan]

OTA (Over-The-Air) cho phép thiết bị kiểm tra và nhận bản firmware mới từ nền tảng mà không cần cắm vào máy tính. Thiết bị có thể dùng thông tin này để tải firmware phù hợp với board và tự khởi động lại sau khi cập nhật.

Trong Assistant Core, OTA không chỉ dùng để cập nhật firmware. Đây cũng là bước thiết bị lấy thời gian hệ thống, thông tin kết nối, mã kích hoạt và trạng thái liên kết với trợ lý.

Cập Nhật Tự Động [#cập-nhật-tự-động]

Nếu bật **Cập Nhật Tự Động**:

1. Thiết bị kiểm tra OTA khi khởi động hoặc theo chu kỳ của firmware
2. Nền tảng trả về firmware mới nhất phù hợp với board
3. Thiết bị tải firmware, xác minh gói cập nhật và cài đặt
4. Thiết bị khởi động lại với phiên bản mới

Bật Cập Nhật Tự Động [#bật-cập-nhật-tự-động]

1. Vào **Thiết Bị** → chọn thiết bị
2. Bật **Cập Nhật Tự Động**
3. Nhấn **Lưu**

Cập Nhật Thủ Công [#cập-nhật-thủ-công]

1. Vào **Thiết Bị** → chọn thiết bị
2. So sánh phiên bản hiện tại với phiên bản mới nhất
3. Nhấn **Cập Nhật Ngay** nếu có bản mới

Quản Lý Firmware [#quản-lý-firmware]

Quản trị viên nền tảng có thể quản lý các bản firmware được phân phối qua OTA:

1. Vào **Admin → OTA Firmware**
2. Upload firmware package cho từng board hoặc target
3. Đặt phiên bản đang **active**
4. Thiết bị bật cập nhật tự động sẽ nhận phiên bản đang hoạt động trong lần kiểm tra tiếp theo

Thiết Bị Nhận Gì Khi Kiểm Tra OTA? [#thiết-bị-nhận-gì-khi-kiểm-tra-ota]

| Nhóm dữ liệu               | Mục đích                                            |
| -------------------------- | --------------------------------------------------- |
| **Thời gian hệ thống**     | Đồng bộ thời gian cho thiết bị                      |
| **Firmware**               | Phiên bản mới nhất và URL tải firmware              |
| **Kết nối thời gian thực** | Thông tin kết nối để thiết bị nói chuyện với trợ lý |
| **Kích hoạt**              | Mã kích hoạt nếu thiết bị chưa được liên kết        |

<Callout type="info">
  Nếu thiết bị không online hoặc không bắt đầu được phiên giọng nói, hãy kiểm tra OTA trước. Kết nối thời gian thực phụ thuộc vào thông tin mà bước này trả về.
</Callout>


# Đăng Ký Thiết Bị



Tổng Quan [#tổng-quan]

Đăng ký thiết bị là bước thêm một board phần cứng vào Bảng Điều Khiển để trợ lý có thể nhận diện và sử dụng thiết bị đó. Sau khi đăng ký, nền tảng biết thiết bị thuộc không gian làm việc nào, đang dùng board và firmware nào, được liên kết với trợ lý nào và có thể nhận cấu hình, phiên giọng nói, giao diện tùy chỉnh hoặc lệnh điều khiển.

Với thiết bị ESP32, cách khuyến nghị là dùng **mã kích hoạt 6 số**. Mã này xuất hiện khi thiết bị đã online nhưng chưa được liên kết với trợ lý.

Trước Khi Bắt Đầu [#trước-khi-bắt-đầu]

* Thiết bị đã được flash firmware tương thích.
* Thiết bị đã kết nối Wi-Fi và có thể lấy cấu hình từ nền tảng.
* Bạn có quyền quản lý trợ lý hoặc thiết bị trong Bảng Điều Khiển.
* Nếu đăng ký thủ công, bạn cần biết địa chỉ MAC và model board.

Đăng Ký Bằng Mã Kích Hoạt [#đăng-ký-bằng-mã-kích-hoạt]

1. Bật nguồn ESP32
2. Chờ thiết bị kết nối Wi-Fi và hiển thị **mã 6 số**
3. Vào **Thiết Bị** trong Bảng Điều Khiển
4. Nhấn **Thêm Thiết Bị → Nhập Mã**
5. Nhập mã kích hoạt
6. Chọn trợ lý để liên kết
7. Nhấn **Liên Kết**

Sau khi liên kết, thiết bị sẽ nhận cấu hình trợ lý trong lần kiểm tra OTA tiếp theo và có thể bắt đầu phiên giọng nói.

Đăng Ký Thủ Công [#đăng-ký-thủ-công]

Đăng ký thủ công phù hợp khi thiết bị không có màn hình, không hiển thị được mã kích hoạt hoặc bạn muốn tạo thông tin thiết bị trước khi thiết bị online.

1. Vào **Thiết Bị** → **Thêm → Thủ Công**
2. Nhập **MAC**, **tên gọi** và **mẫu board**
3. Chọn trợ lý để liên kết
4. Nhấn **Đăng Ký**

Thông Tin Thiết Bị [#thông-tin-thiết-bị]

| Trường               | Mô tả                                                  |
| -------------------- | ------------------------------------------------------ |
| **Tên gọi**          | Tên thân thiện trong Bảng Điều Khiển                   |
| **Trợ lý**           | Trợ lý đang xử lý phiên giọng nói và lệnh cho thiết bị |
| **Board**            | Mẫu phần cứng hoặc loại firmware                       |
| **MAC**              | Định danh phần cứng duy nhất                           |
| **Firmware**         | Phiên bản firmware hiện tại                            |
| **Lần online cuối**  | Thời điểm thiết bị gần nhất kết nối với nền tảng       |
| **Cập nhật tự động** | Bật/tắt cập nhật firmware qua OTA                      |

Chuyển Thiết Bị Sang Trợ Lý Khác [#chuyển-thiết-bị-sang-trợ-lý-khác]

1. Vào **Thiết Bị** và chọn thiết bị cần đổi
2. Nhấn **Đổi trợ lý**
3. Chọn trợ lý mới
4. Nhấn **Lưu**

<Callout type="info">
  Một thiết bị chỉ nên được liên kết với một trợ lý tại một thời điểm để phiên giọng nói, bộ nhớ và công cụ thiết bị không bị trộn ngữ cảnh.
</Callout>


# Tên Miền Riêng



Yêu Cầu [#yêu-cầu]

* Gói **Pro** trở lên
* Quyền quản lý DNS của tên miền

Cài Đặt [#cài-đặt]

1. Vào **Cài Đặt Trợ Lý → Thương Hiệu**
2. Nhập tên miền tại ô **Tên miền riêng** (ví dụ: `chat.congty.com`)
3. Hướng dẫn DNS sẽ hiển thị ngay bên dưới — thêm bản ghi theo hướng dẫn

Cấu Hình DNS [#cấu-hình-dns]

**Subdomain** (khuyến nghị, ví dụ: `chat.congty.com`):

| Loại  | Name   | Value                                 | TTL  |
| :---- | :----- | :------------------------------------ | :--- |
| CNAME | `chat` | `5c2806ade7622a0e.vercel-dns-017.com` | Auto |

**Apex domain** (ví dụ: `myassistant.ai`):

| Loại | Name | Value          | TTL  |
| :--- | :--- | :------------- | :--- |
| A    | `@`  | `216.198.79.1` | Auto |

4. Lưu cài đặt trợ lý
5. Chứng chỉ **SSL** được cấp tự động bởi Vercel (Let's Encrypt)

<Callout type="info">
  DNS có thể mất tới 24–48 giờ để lan truyền. Trong thời gian chờ, trợ lý vẫn truy cập được qua subdomain mặc định.
</Callout>

<Callout type="warn">
  Quản trị viên hệ thống cần thêm tên miền vào 

  **Vercel Dashboard → Settings → Domains**

   trước khi người dùng cấu hình DNS.
</Callout>

White Labeling [#white-labeling]

* Thay **logo** riêng tại mục Thương Hiệu
* Đặt **màu chủ đạo** tùy chỉnh
* Xóa "Powered by Assistant Core" (gói Enterprise)


# Nhúng Chatbot



Lấy Mã Nhúng [#lấy-mã-nhúng]

1. Vào **Cài Đặt Trợ Lý → Nhúng**
2. Sao chép đoạn mã:

```html
<script
  src="https://cdn.assistantcore.com/embed/embed.js"
  data-assistant-id="ID_TRỢ_LÝ"
  data-api-base="https://api.assistantcore.com"
  async
></script>
```

3. Dán vào HTML website, trước thẻ đóng `</body>`

Cấu Hình Tên Miền Nhúng [#cấu-hình-tên-miền-nhúng]

Widget chỉ hoạt động trên các tên miền đã được đăng ký. Nếu bạn nhúng widget trên trang web khác (không phải custom domain hoặc subdomain của trợ lý), bạn cần thêm tên miền đó vào danh sách.

1. Vào **Tích Hợp** → **Tên miền nhúng Widget**
2. Nhập tên miền (không kèm `https://`), ví dụ: `www.mysite.com`
3. Nhấn **Thêm** → **Lưu tên miền**

<Callout type="warn">
  Nếu không đăng ký tên miền, widget sẽ không thể kết nối API và chat sẽ không hoạt động.
</Callout>

Nơi Thêm Mã [#nơi-thêm-mã]

* **WordPress** — Giao diện → Theme Editor → Footer
* **HTML** — Trước `</body>` trong file HTML
* **React/Next.js** — Dùng `next/script` component

<Callout type="info">
  Widget nhúng có từ gói **Plus** trở lên. Gói Miễn Phí dùng chat tại
  [chat.assistantcore.com](https://chat.assistantcore.com).
</Callout>


# Assistant Core 1.83" 2-Mic



Thông Số Kỹ Thuật [#thông-số-kỹ-thuật]

| Thông số       | Giá trị           |
| -------------- | ----------------- |
| **Chip**       | ESP32-S3          |
| **Flash**      | 16MB              |
| **PSRAM**      | 8MB               |
| **Kết nối**    | WiFi 2.4GHz       |
| **Microphone** | 2× I2S MEMS       |
| **Loa**        | I2S DAC           |
| **Màn hình**   | LCD 1.83" 240×280 |

Tính Năng [#tính-năng]

* ✅ WiFi kết nối
* ✅ Dual microphone beamforming
* ✅ Voice Activity Detection (VAD)
* ✅ Acoustic Echo Cancellation (AEC)
* ✅ Màn hình LCD hiển thị trạng thái + emoji
* ✅ OTA cập nhật tự động
* ✅ Hỗ trợ wake word (WakeNet)
* ✅ Opus audio codec
* ✅ WebSocket streaming

Nạp Firmware [#nạp-firmware]

<Callout type="warn">
  Yêu cầu trình duyệt **Google Chrome** hoặc **Microsoft Edge** 89+.
</Callout>

<FirmwareFlashButton boardType="assistantcore-1.83-2mic" chipFamily="ESP32-S3" />

Hướng Dẫn Kết Nối [#hướng-dẫn-kết-nối]

1. Kết nối board với máy tính qua cáp USB-C
2. Đảm bảo đã cài driver **CP210x** hoặc **CH340**
3. Nhấn nút **Boot** trên board khi nạp firmware (nếu cần)

Sau Khi Nạp [#sau-khi-nạp]

1. Board sẽ tự khởi động lại
2. Màn hình LCD hiển thị mã kích hoạt 6 số
3. Kết nối WiFi qua **BluFi** hoặc cấu hình mạng
4. Đăng ký thiết bị trên [Bảng Điều Khiển](/devices/register-device)


# Bread Compact WiFi



Thông Số Kỹ Thuật [#thông-số-kỹ-thuật]

| Thông số       | Giá trị     |
| -------------- | ----------- |
| **Chip**       | ESP32-S3    |
| **Flash**      | 16MB        |
| **PSRAM**      | 8MB         |
| **Kết nối**    | WiFi 2.4GHz |
| **Microphone** | I2S MEMS    |
| **Loa**        | I2S DAC     |

Tính Năng [#tính-năng]

* ✅ WiFi kết nối
* ✅ Voice Activity Detection (VAD)
* ✅ Acoustic Echo Cancellation (AEC)
* ✅ OTA cập nhật tự động
* ✅ Hỗ trợ wake word (WakeNet)
* ✅ Opus audio codec
* ✅ WebSocket streaming

Nạp Firmware [#nạp-firmware]

<Callout type="warn">
  Yêu cầu trình duyệt **Google Chrome** hoặc **Microsoft Edge** 89+.
</Callout>

<FirmwareFlashButton boardType="bread-compact-wifi" chipFamily="ESP32-S3" />

Hướng Dẫn Kết Nối [#hướng-dẫn-kết-nối]

1. Kết nối board với máy tính qua cáp USB-C
2. Đảm bảo đã cài driver **CP210x** hoặc **CH340**
3. Nhấn nút **Boot** trên board khi nạp firmware (nếu cần)

Sau Khi Nạp [#sau-khi-nạp]

1. Board sẽ tự khởi động lại
2. Kết nối WiFi qua **BluFi** hoặc cấu hình mạng
3. Đăng ký thiết bị trên [Bảng Điều Khiển](/devices/register-device)


# Custom Flash



Sử dụng công cụ bên dưới để nạp file firmware (.bin) tùy chỉnh vào thiết bị ESP32.

<Callout type="warn">
  Yêu cầu trình duyệt **Google Chrome** hoặc **Microsoft Edge** phiên bản 89+.
</Callout>

Công Cụ Nạp [#công-cụ-nạp]

<CustomFirmwareUpload />

Hướng Dẫn [#hướng-dẫn]

Chế Độ Nạp Nhanh [#chế-độ-nạp-nhanh]

Sử dụng khi bạn có **một file firmware đã merge** (merged binary). File này sẽ được nạp vào địa chỉ `0x0`.

Để tạo merged binary từ ESP-IDF:

```bash
idf.py merge-bin -o merged.bin
```

Chế Độ Nâng Cao [#chế-độ-nâng-cao]

Sử dụng khi bạn có nhiều file binary riêng lẻ (bootloader, partition table, application). Mỗi file cần được gán đúng địa chỉ offset:

| File                   | Offset thường dùng |
| ---------------------- | ------------------ |
| `bootloader.bin`       | `0x0`              |
| `partition-table.bin`  | `0x8000`           |
| `ota_data_initial.bin` | `0xD000`           |
| `app.bin`              | `0x10000`          |

<Callout type="info">
  Địa chỉ offset có thể khác nhau tùy cấu hình partition table của firmware. Kiểm tra file `partitions.csv` hoặc output của `idf.py build` để xác định chính xác.
</Callout>


# Tổng Quan



Nạp firmware cho thiết bị ESP32 trực tiếp từ trình duyệt web bằng Web Serial API.

<Callout type="warn">
  Tính năng nạp firmware yêu cầu trình duyệt **Google Chrome** hoặc **Microsoft Edge** phiên bản 89 trở lên.
  Safari và Firefox không hỗ trợ Web Serial API.
</Callout>

Firmware Có Sẵn [#firmware-có-sẵn]

<FirmwareCatalog />

Nạp Firmware Tùy Chỉnh [#nạp-firmware-tùy-chỉnh]

Nếu bạn có file firmware riêng (.bin), hãy sử dụng [công cụ nạp tùy chỉnh](/firmware/custom-upload).

Hướng Dẫn Sử Dụng [#hướng-dẫn-sử-dụng]

1. Kết nối thiết bị ESP32 với máy tính qua cáp USB
2. Chọn board phù hợp từ danh sách trên
3. Nhấn **Nạp Vào Thiết Bị** trên trang chi tiết firmware
4. Chọn cổng Serial khi trình duyệt yêu cầu
5. Chờ quá trình nạp hoàn tất — thiết bị sẽ tự khởi động lại

<Callout type="info">
  Bạn có thể cần cài đặt driver USB phù hợp (CP210x hoặc CH340) nếu máy tính không nhận diện được thiết bị.
</Callout>


# Xingzhi Cube 1.54" TFT



Thông Số Kỹ Thuật [#thông-số-kỹ-thuật]

| Thông số       | Giá trị           |
| -------------- | ----------------- |
| **Chip**       | ESP32-S3          |
| **Flash**      | 16MB              |
| **PSRAM**      | 8MB               |
| **Kết nối**    | WiFi 2.4GHz       |
| **Microphone** | I2S MEMS          |
| **Loa**        | I2S DAC           |
| **Màn hình**   | TFT 1.54" 240×240 |

Tính Năng [#tính-năng]

* ✅ WiFi kết nối
* ✅ Voice Activity Detection (VAD)
* ✅ Acoustic Echo Cancellation (AEC)
* ✅ Màn hình TFT hiển thị trạng thái + emoji
* ✅ OTA cập nhật tự động
* ✅ Hỗ trợ wake word (WakeNet)
* ✅ Opus audio codec
* ✅ WebSocket streaming
* ✅ Thiết kế nhỏ gọn dạng khối

Nạp Firmware [#nạp-firmware]

<Callout type="warn">
  Yêu cầu trình duyệt **Google Chrome** hoặc **Microsoft Edge** 89+.
</Callout>

<FirmwareFlashButton boardType="xingzhi-cube-1.54tft-wifi" chipFamily="ESP32-S3" />

Hướng Dẫn Kết Nối [#hướng-dẫn-kết-nối]

1. Kết nối board với máy tính qua cáp USB-C
2. Đảm bảo đã cài driver **CP210x** hoặc **CH340**
3. Nhấn nút **Boot** trên board khi nạp firmware (nếu cần)

Sau Khi Nạp [#sau-khi-nạp]

1. Board sẽ tự khởi động lại
2. Màn hình TFT hiển thị mã kích hoạt 6 số
3. Kết nối WiFi qua **BluFi** hoặc cấu hình mạng
4. Đăng ký thiết bị trên [Bảng Điều Khiển](/devices/register-device)


# Mẹo Hay



Cấu Trúc Tài Liệu [#cấu-trúc-tài-liệu]

* Dùng **tiêu đề** (H1, H2, H3) để tổ chức nội dung
* Giữ mỗi mục tập trung **một chủ đề**
* Dùng danh sách để trình bày rõ ràng

Nội Dung Hiệu Quả [#nội-dung-hiệu-quả]

| Loại nội dung       | Hiệu quả AI    |
| ------------------- | -------------- |
| FAQ                 | ⭐⭐⭐⭐⭐ Xuất sắc |
| Tài liệu sản phẩm   | ⭐⭐⭐⭐⭐ Xuất sắc |
| Hướng dẫn từng bước | ⭐⭐⭐⭐ Tốt       |
| Tài liệu chính sách | ⭐⭐⭐⭐ Tốt       |

Nên Tránh [#nên-tránh]

* **Ảnh scan không OCR** — AI không đọc được PDF chỉ có ảnh
* **Tài liệu quá dài** (500+ trang) — Chia thành file nhỏ hơn
* **Nội dung trùng lặp** — Xóa tài liệu thừa
* **Dữ liệu nhạy cảm** — Không tải mật khẩu, API key


# Tải Tài Liệu



Định Dạng Hỗ Trợ [#định-dạng-hỗ-trợ]

| Định dạng    | Đuôi file       | Ghi chú                  |
| ------------ | --------------- | ------------------------ |
| **PDF**      | `.pdf`          | Trích xuất văn bản + OCR |
| **Word**     | `.docx`         | Hỗ trợ đầy đủ            |
| **Excel**    | `.xlsx`, `.xls` | Trích xuất dữ liệu bảng  |
| **Văn bản**  | `.txt`          | Văn bản thuần            |
| **Markdown** | `.md`           | Giữ nguyên định dạng     |

Cách Tải [#cách-tải]

1. Vào **Trợ Lý** → tab **Knowledge Base**
2. Nhấn **Tải Tài Liệu** hoặc kéo thả file
3. Đợi xử lý: phân tích, chia đoạn, tạo embedding
4. Trạng thái hiển thị **Hoàn Tất** khi sẵn sàng

Giới Hạn Tài Liệu [#giới-hạn-tài-liệu]

| Gói        | Tối đa         |
| ---------- | -------------- |
| Miễn Phí   | 5              |
| Plus       | 20             |
| Pro        | 50             |
| Enterprise | Không giới hạn |

<Callout type="tip">
  Tải tài liệu có cấu trúc rõ ràng với tiêu đề và mục để AI truy xuất tốt hơn.
</Callout>


# Thu Thập Web



Cách Thu Thập [#cách-thu-thập]

1. Vào tab **Knowledge Base**
2. Nhấn **Thêm từ URL**
3. Nhập URL website (ví dụ: `https://example.com/docs`)
4. Cấu hình: số trang tối đa, độ sâu
5. Nhấn **Bắt Đầu**

<Callout type="info">
  Thu thập web dùng **Firecrawl** — dịch vụ tối ưu AI để trích xuất nội dung
  sạch từ website.
</Callout>

Phù Hợp Với [#phù-hợp-với]

* Tài liệu công ty, trung tâm hỗ trợ
* Bài viết blog
* Trang sản phẩm, FAQ

<Callout type="warn">
  Chỉ thu thập website bạn có quyền sử dụng.
</Callout>


# Hướng Dẫn Sử Dụng



Bật / Tắt Bộ Nhớ [#bật--tắt-bộ-nhớ]

Bộ nhớ dài hạn được **bật mặc định**. Bạn có thể tắt nếu muốn:

1. Vào **Settings** (biểu tượng ⚙️)
2. Chọn tab **Bộ Nhớ**
3. Tắt công tắc **"Tham chiếu memory đã lưu"**

<Callout type="info">
  Khi tắt, AI sẽ không truy xuất memory dài hạn trong cuộc trò chuyện. Các memory đã lưu trước đó vẫn được giữ nguyên — bạn có thể bật lại bất cứ lúc nào.
</Callout>

AI Tự Động Ghi Nhớ [#ai-tự-động-ghi-nhớ]

Sau mỗi lượt trò chuyện, AI **tự động phân tích** nội dung và quyết định có thông tin nào đáng ghi nhớ không. Quá trình này diễn ra ở nền (background) và không làm chậm cuộc hội thoại.

Ví Dụ Thực Tế [#ví-dụ-thực-tế]

**Bạn:** "Mình dị ứng tôm nên đừng gợi ý món có tôm nhé"

→ AI tự động lưu: `[health] Dị ứng tôm, tránh món có tôm`

**Bạn:** "Cuối tuần này mình định đi Đà Lạt"

→ AI tự động lưu: `[plan] Dự định đi Đà Lạt cuối tuần`

Những Gì AI Ghi Nhớ [#những-gì-ai-ghi-nhớ]

| Ghi nhớ ✅                   | Bỏ qua ❌                  |
| --------------------------- | ------------------------- |
| Sở thích, thói quen         | Lời chào hỏi thông thường |
| Thông tin cá nhân           | Kiến thức chung           |
| Kế hoạch, quyết định        | Tin nhắn xác nhận ngắn    |
| Cảm xúc, giá trị quan trọng | Câu hỏi một lần           |

Dữ Liệu Nhạy Cảm [#dữ-liệu-nhạy-cảm]

<Callout type="warning">
  Với thông tin nhạy cảm (cảm xúc, sức khỏe, mối quan hệ), AI sẽ **hỏi ý kiến** trước khi lưu: *"Bạn có muốn mình ghi nhớ thông tin này không?"*
</Callout>

Yêu Cầu AI Ghi Nhớ Qua Chat [#yêu-cầu-ai-ghi-nhớ-qua-chat]

Ngoài tự động, bạn có thể **chủ động yêu cầu** AI ghi nhớ, cập nhật, hoặc xóa thông tin:

Ghi Nhớ Mới [#ghi-nhớ-mới]

> "Nhớ giúp mình là mình thích uống trà sữa ít đường"

Cập Nhật Memory [#cập-nhật-memory]

> "Cập nhật lại nhé — mình đã chuyển sang uống cà phê rồi"

Xóa Memory [#xóa-memory]

> "Xóa thông tin về việc mình dị ứng hải sản đi, mình không bị nữa"

Tìm Kiếm Memory [#tìm-kiếm-memory]

> "Mình đã nói gì về kế hoạch du lịch trước đây?"

Cập Nhật Hồ Sơ Cá Nhân (Bio) [#cập-nhật-hồ-sơ-cá-nhân-bio]

**Bio** là phần hồ sơ cá nhân ngắn gọn được đưa vào **mọi cuộc hội thoại**. Khác với memory thông thường (chỉ được recall khi liên quan), Bio luôn có mặt trong context.

Thông Tin Phù Hợp Cho Bio [#thông-tin-phù-hợp-cho-bio]

* Tên, nghề nghiệp, vị trí
* Kỹ năng chính, lĩnh vực chuyên môn
* Mục tiêu dài hạn
* Phong cách giao tiếp ưa thích

Cách Cập Nhật [#cách-cập-nhật]

Nói với AI trong chat:

> "Cập nhật bio: Mình là Vector, developer ở TP.HCM, đam mê AI và IoT"

<Callout type="tip">
  Bio nên chứa thông tin **ổn định, ít thay đổi**. Thông tin hay thay đổi (sở thích ăn uống, kế hoạch ngắn hạn) nên để AI lưu dạng memory thông thường.
</Callout>


# Quản Lý Memory



Xem Danh Sách Memory [#xem-danh-sách-memory]

1. Vào **Settings** (biểu tượng ⚙️)
2. Chọn tab **Bộ Nhớ**
3. Nhấn **"Xem tất cả"** để mở danh sách đầy đủ

Mỗi memory hiển thị:

* **Nội dung** — Thông tin đã được ghi nhớ
* **Loại** — Phân loại (preference, fact, plan, ...)
* **Thời gian** — Ngày giờ tạo hoặc cập nhật gần nhất

Chỉnh Sửa Memory [#chỉnh-sửa-memory]

Bạn có thể sửa nội dung của memory đã lưu:

1. Mở danh sách memory từ **Settings → Bộ Nhớ**
2. Nhấn vào memory muốn chỉnh sửa
3. Cập nhật **nội dung** và/hoặc **loại memory**
4. Nhấn **Lưu** để xác nhận

<Callout type="info">
  Khi bạn chỉnh sửa nội dung, embedding vector sẽ được tự động cập nhật để đảm bảo tìm kiếm ngữ nghĩa vẫn chính xác.
</Callout>

Xóa Memory [#xóa-memory]

Để xóa một memory:

1. Mở danh sách memory
2. Nhấn biểu tượng **xóa** (🗑️) bên cạnh memory
3. Xác nhận xóa

<Callout type="warning">
  Memory đã xóa **không thể khôi phục**. Hãy chắc chắn trước khi xóa.
</Callout>

Lọc Memory Theo Loại [#lọc-memory-theo-loại]

Danh sách memory có thể lọc theo loại để dễ quản lý:

| Bộ lọc       | Mô tả                   |
| ------------ | ----------------------- |
| Tất cả       | Hiển thị toàn bộ memory |
| Preference   | Sở thích cá nhân        |
| Fact         | Thông tin thực tế       |
| Decision     | Quyết định              |
| Plan         | Kế hoạch                |
| Emotion      | Cảm xúc                 |
| Value        | Giá trị                 |
| Relationship | Mối quan hệ             |
| Health       | Sức khỏe                |
| Interest     | Đam mê, sở thích        |

Quản Lý Memory (Admin) [#quản-lý-memory-admin]

Nếu bạn là quản trị viên (admin) của trợ lý, bạn có thể xem memory của tất cả người dùng từ **Admin Dashboard**:

* Xem memory theo trợ lý (assistant)
* Lọc theo người dùng cụ thể
* Lọc theo loại memory
* Phân trang cho danh sách lớn

<Callout type="tip">
  Admin chỉ có quyền xem memory — người dùng luôn có toàn quyền xóa và chỉnh sửa memory của mình.
</Callout>


# Tổng Quan



Bộ Nhớ Là Gì? [#bộ-nhớ-là-gì]

Bộ Nhớ (Memory) là tính năng giúp AI **ghi nhớ thông tin quan trọng** về bạn qua các cuộc hội thoại. Nhờ đó, AI có thể cá nhân hóa câu trả lời — ví dụ nhớ tên bạn, sở thích ăn uống, hoặc dự định du lịch mà bạn từng chia sẻ.

<Callout type="tip">
  Memory giúp AI hiểu bạn hơn theo thời gian mà không cần bạn nhắc lại thông tin mỗi lần trò chuyện.
</Callout>

Hai Tầng Bộ Nhớ [#hai-tầng-bộ-nhớ]

Hệ thống hoạt động với 2 tầng bộ nhớ bổ sung cho nhau:

| Tầng                | Mô tả                                           | Phạm vi                   |
| ------------------- | ----------------------------------------------- | ------------------------- |
| **Bộ nhớ ngắn hạn** | Lịch sử tin nhắn trong cuộc hội thoại hiện tại  | Trong 1 cuộc trò chuyện   |
| **Bộ nhớ dài hạn**  | Thông tin được trích xuất và lưu lại xuyên suốt | Xuyên các cuộc trò chuyện |

<Mermaid
  chart={`graph TD
  A["💬 User & Assistant\ntrò chuyện"] --> B["🤖 Memory Agent\nphân tích nội dung"]
  B --> C{"Có thông tin\nđáng nhớ?"}
  C -->|"Không"| D["⏭️ Bỏ qua"]
  C -->|"Có"| E["🔍 Tìm memory\ntương tự"]
  E --> F{"Đã tồn tại?"}
  F -->|"Có"| G["✏️ Cập nhật memory"]
  F -->|"Không"| H["➕ Thêm memory mới"]
  G --> I["📐 Tạo Embedding"]
  H --> I
  I --> J[("💾 pgvector\nDatabase")]
  K["💬 Cuộc hội thoại mới"] --> L["🔎 Semantic Search"]
  J --> L
  L --> M["📋 Memories liên quan"]
  M --> N["🤖 LLM nhận context\n+ memories"]`}
/>

Bộ Nhớ Ngắn Hạn [#bộ-nhớ-ngắn-hạn]

Đây là **lịch sử tin nhắn** trong cuộc trò chuyện đang diễn ra. AI đọc lại các tin nhắn trước để hiểu ngữ cảnh và trả lời chính xác hơn.

* Tự động lưu mọi tin nhắn (user + assistant)
* Chỉ tồn tại trong phạm vi cuộc hội thoại
* Không cần cấu hình

Bộ Nhớ Dài Hạn [#bộ-nhớ-dài-hạn]

Đây là hệ thống **ghi nhớ thông tin quan trọng** giữa các cuộc hội thoại. AI tự động phân tích nội dung trò chuyện và trích xuất những thông tin đáng nhớ.

* Tự động trích xuất sau mỗi lượt hội thoại
* Lưu trữ vĩnh viễn cho đến khi bạn xóa
* Tìm kiếm ngữ nghĩa (semantic search) để recall chính xác
* Hỗ trợ bật/tắt từ Settings

Các Loại Memory [#các-loại-memory]

AI phân loại thông tin vào **9 loại** để tổ chức và truy xuất hiệu quả:

| Loại           | Mô tả                | Ví dụ                          |
| -------------- | -------------------- | ------------------------------ |
| `preference`   | Sở thích cá nhân     | "Thích cà phê đen không đường" |
| `fact`         | Thông tin thực tế    | "Làm việc tại công ty ABC"     |
| `decision`     | Quyết định đã đưa ra | "Chọn học Python thay vì Java" |
| `plan`         | Kế hoạch tương lai   | "Dự định đi Đà Nẵng tháng 7"   |
| `emotion`      | Cảm xúc, tâm trạng   | "Đang lo lắng về deadline"     |
| `value`        | Giá trị cá nhân      | "Coi trọng work-life balance"  |
| `relationship` | Mối quan hệ          | "Có em gái tên Linh"           |
| `health`       | Thông tin sức khỏe   | "Dị ứng hải sản"               |
| `interest`     | Sở thích, đam mê     | "Đam mê chụp ảnh phong cảnh"   |

Phạm Vi Theo Trợ Lý [#phạm-vi-theo-trợ-lý]

Memory được lưu **riêng biệt cho từng trợ lý** (assistant). Điều này có nghĩa:

* Trợ lý A không đọc được memory của trợ lý B
* Mỗi trợ lý có bộ nhớ riêng phù hợp với vai trò của nó
* Bạn có toàn quyền quản lý memory cho từng trợ lý

<Callout type="info">
  Ví dụ: Memory về "sở thích ăn uống" được lưu ở trợ lý tư vấn ẩm thực sẽ không hiển thị khi bạn dùng trợ lý hỗ trợ kỹ thuật.
</Callout>


# Mời Người Dùng



Mời Người Dùng [#mời-người-dùng]

1. Vào **Cài Đặt Trợ Lý → Người Dùng**
2. Nhấn **Mời**
3. Nhập email
4. Chọn **vai trò** (Người Dùng hoặc Quản Trị)
5. Nhấn **Gửi Lời Mời**

Giới Hạn [#giới-hạn]

| Gói        | Tối đa         |
| ---------- | -------------- |
| Miễn Phí   | 1 (chủ sở hữu) |
| Plus       | 6              |
| Pro        | 22             |
| Enterprise | Không giới hạn |

<Callout type="info">
  Tất cả người dùng chia sẻ quota tin nhắn và giọng nói của trợ lý.
</Callout>


# Vai Trò & Quyền



Loại Vai Trò [#loại-vai-trò]

| Vai trò        | Mô tả                                       |
| -------------- | ------------------------------------------- |
| **Chủ Sở Hữu** | Toàn quyền — người tạo trợ lý               |
| **Quản Trị**   | Quản lý cài đặt, người dùng, Knowledge Base |
| **Người Dùng** | Chỉ chat với trợ lý                         |

Bảng Quyền [#bảng-quyền]

| Hành động          | Chủ SH | Quản Trị | Người Dùng   |
| ------------------ | ------ | -------- | ------------ |
| Chat với trợ lý    | ✅      | ✅        | ✅            |
| Xem lịch sử chat   | ✅      | ✅        | Chỉ của mình |
| Tải tài liệu       | ✅      | ✅        | ❌            |
| Đổi cài đặt        | ✅      | ✅        | ❌            |
| Quản lý người dùng | ✅      | ✅        | ❌            |
| Quản lý đăng ký    | ✅      | ❌        | ❌            |
| Xóa trợ lý         | ✅      | ❌        | ❌            |


# Built-in Tools



Built-in Tools là các capability có sẵn trong Assistant Core. Bạn không cần cấu hình endpoint riêng; chỉ cần bật feature liên quan trong assistant settings khi Admin UI hỗ trợ.

Available Tools [#available-tools]

| Tool             | Dùng khi nào                                                                  | Ghi chú                                                                                                  |
| ---------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Knowledge Base   | User hỏi về documents đã upload hoặc website đã crawl                         | Assistant có thể search documents, list documents, search theo file name và read specific files          |
| Memory           | Cần remember hoặc recall thông tin về user                                    | Có thể search, add, update hoặc delete memories tùy context                                              |
| Web              | Cần current information, web page, location, research paper, image hoặc video | Hỗ trợ web search, URL scraping, maps, scholar search, image search, video search và lens-style analysis |
| Image Generation | User yêu cầu tạo hoặc chỉnh sửa ảnh                                           | Có trong chat; generated image được trả trực tiếp trong conversation                                     |
| Music            | User trong voice yêu cầu phát nhạc                                            | Dùng trong voice session, có thể phát bài cụ thể hoặc bài random                                         |
| End Conversation | User trong voice muốn kết thúc conversation                                   | Assistant nói goodbye rồi đóng voice session                                                             |

<Callout type="info">
  Deep Research có trong system nhưng hiện chưa được bật như default tool trong chat hoặc voice.
</Callout>

Enable Hoặc Disable Features [#enable-hoặc-disable-features]

1. Mở **Admin Dashboard**.
2. Chọn assistant cần cấu hình.
3. Vào **Assistant Settings**.
4. Trong **Features**, enable hoặc disable các capability như Knowledge, Web Search, Memory, Voice, File Upload hoặc MCP.
5. Nhấn **Save Changes**.

Khi Nào Assistant Tự Gọi Tool? [#khi-nào-assistant-tự-gọi-tool]

Assistant tự quyết định gọi tool khi request cần thêm data hoặc cần thực hiện action. Ví dụ:

* Hỏi về internal documents: assistant ưu tiên Knowledge Base.
* Hỏi current information hoặc một URL cụ thể: assistant dùng Web.
* Yêu cầu tạo ảnh: assistant dùng Image Generation.
* Nói trong voice “phát bài...” hoặc “kết thúc đi”: assistant dùng voice tool phù hợp.

Prompting Tip [#prompting-tip]

Nếu bạn muốn assistant ưu tiên một tool, hãy ghi rõ trong system prompt. Ví dụ:

```text
Khi user hỏi về chính sách công ty, luôn search Knowledge Base trước khi trả lời.
Nếu Knowledge Base không có thông tin liên quan, hãy nói rõ là chưa tìm thấy.
```

Tránh yêu cầu web search cho mọi câu hỏi, vì điều đó làm response chậm hơn và có thể dùng external data khi không cần thiết.


# Custom API Tools



Custom API Tools phù hợp khi bạn có một HTTP API đơn giản và muốn assistant gọi API đó khi cần. Ví dụ: lookup order, tạo support ticket, kiểm tra inventory, lấy appointment hoặc gửi data vào internal system.

Tạo Tool [#tạo-tool]

1. Mở **Admin Dashboard**.
2. Chọn assistant.
3. Vào **Tools**.
4. Nhấn **New Tool**.
5. Điền tool details.
6. Nhấn **Create** hoặc **Save**.

Fields [#fields]

| Field       | Ý nghĩa                                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| Name        | Tên ngắn gọn để assistant nhận biết tool. Nên dùng tên mô tả action, ví dụ `lookup_order`               |
| Description | Mô tả khi nào nên dùng tool. Phần này rất quan trọng vì AI dùng nó để quyết định có call tool hay không |
| Method      | HTTP method: GET, POST, PUT, PATCH hoặc DELETE                                                          |
| API URL     | Endpoint mà Assistant Core sẽ call                                                                      |
| Parameters  | Data assistant cần lấy từ user trước khi call API                                                       |
| Strict      | Khi bật, parameter schema được kiểm soát chặt hơn để giảm unexpected input                              |

Parameters [#parameters]

Mỗi parameter gồm:

| Field       | Ý nghĩa                                                       |
| ----------- | ------------------------------------------------------------- |
| Name        | Parameter name gửi đến API                                    |
| Type        | Data type: string, number, integer, boolean hoặc array        |
| Description | Giải thích rõ parameter này là gì                             |
| Required    | Bắt buộc hay không                                            |
| Enum values | Allowed values nếu assistant chỉ nên chọn trong một số option |
| Items type  | Item type nếu parameter là array                              |

Request Format [#request-format]

| Method | Parameter format |
| ------ | ---------------- |
| GET    | Query string     |
| DELETE | Query string     |
| POST   | JSON body        |
| PUT    | JSON body        |
| PATCH  | JSON body        |

Ví Dụ [#ví-dụ]

Một order lookup tool có thể cấu hình:

| Field       | Value                                                                  |
| ----------- | ---------------------------------------------------------------------- |
| Name        | `lookup_order`                                                         |
| Description | Tìm shipping status theo order ID khi user hỏi về trạng thái giao hàng |
| Method      | GET                                                                    |
| API URL     | `https://api.example.com/orders/status`                                |
| Parameter   | Required string parameter tên `order_id`                               |

Khi user hỏi “đơn hàng A123 của tôi tới đâu rồi?”, assistant có thể call API với `order_id=A123`, rồi summarize result cho user.

Security Notes [#security-notes]

* Không đặt API key trực tiếp trong URL nếu URL có thể bị lộ.
* Nên tạo proxy endpoint nếu original API cần authentication phức tạp.
* Tool description càng rõ, assistant càng ít call nhầm.
* Nếu một tool có thể thay đổi data, hãy ghi rõ trong description để assistant chỉ call khi user thật sự muốn thực hiện action.


# Device Tools



Device Tools dùng khi một device đã connect với Assistant Core và expose capability riêng trong voice session. Ví dụ: device có thể báo sensor status, đổi theme, restart, điều khiển đèn hoặc thực hiện action mà firmware hỗ trợ.

Hai Loại Device Tools [#hai-loại-device-tools]

| Type       | Dùng để làm gì                                                                       |
| ---------- | ------------------------------------------------------------------------------------ |
| Device MCP | Device tự publish tool list theo MCP                                                 |
| Device IoT | Device publish properties và control actions như bật/tắt, đổi value, kiểm tra status |

Requirements [#requirements]

* Device đã được register và attach với assistant.
* Device đang online trong voice session.
* Firmware hỗ trợ MCP hoặc IoT descriptors.
* Assistant đã enable voice.

Cách Hoạt Động Trong Voice [#cách-hoạt-động-trong-voice]

1. Device mở voice session với Assistant Core.
2. Nếu device hỗ trợ MCP, server yêu cầu device gửi tool list.
3. Nếu device cung cấp IoT descriptors, properties và actions được chuyển thành tools.
4. Khi user nói một request phù hợp, assistant call tool qua device connection.
5. Device thực hiện action hoặc trả data lại cho assistant.

Ví Dụ [#ví-dụ]

| User nói                       | Device tool có thể chạy                            |
| ------------------------------ | -------------------------------------------------- |
| “Bật đèn phòng khách”          | Call light control action nếu firmware hỗ trợ      |
| “Nhiệt độ hiện tại bao nhiêu?” | Read temperature sensor property                   |
| “Đổi theme trên device”        | Call theme update tool nếu device hỗ trợ           |
| “Restart device”               | Call restart action nếu firmware expose action này |

Check Device Tools [#check-device-tools]

Trong một số device screens, Assistant Core có thể gửi MCP commands như `tools/list` hoặc `tools/call` đến device để inspect capabilities device đang expose.

Nếu tools không xuất hiện:

* Kiểm tra device có online không.
* Kiểm tra firmware có hỗ trợ MCP hoặc IoT descriptors không.
* Kiểm tra device đã attach đúng assistant chưa.
* Restart device sau khi update firmware.

<Callout type="info">
  Device Tools phụ thuộc vào firmware. Hai devices cùng board type có thể expose capability khác nhau nếu chạy firmware khác nhau.
</Callout>


# Tools & MCP



Tools giúp assistant/agent làm nhiều việc hơn ngoài việc trả lời bằng context có sẵn. Tùy use case, bạn có thể dùng Built-in Tools, thêm Custom API Tool, kết nối MCP Server, hoặc để device cung cấp tool trong voice session.

Nên Dùng Loại Nào? [#nên-dùng-loại-nào]

| Nhu cầu                                                                      | Nên dùng                                        |
| ---------------------------------------------------------------------------- | ----------------------------------------------- |
| Assistant tìm trong documents, dùng memory, web search hoặc image generation | [Built-in Tools](/tools-mcp/built-in-tools)     |
| Gọi một HTTP API đơn giản của bạn                                            | [Custom API Tools](/tools-mcp/custom-api-tools) |
| Kết nối một MCP server đã có sẵn qua URL                                     | [MCP Server](/tools-mcp/mcp-server)             |
| Dùng MCP cho voice hoặc device theo realtime                                 | [MCP Endpoint](/tools-mcp/mcp-endpoint)         |
| Điều khiển capability do ESP32 device cung cấp                               | [Device Tools](/tools-mcp/device-tools)         |

Assistant Gọi Tool Như Thế Nào? [#assistant-gọi-tool-như-thế-nào]

Khi user hỏi một việc cần external data hoặc action, assistant sẽ tự quyết định có gọi tool hay không. Kết quả từ tool thường được đưa lại cho LLM để synthesize thành câu trả lời tự nhiên.

Một số tool trả kết quả trực tiếp cho user. Ví dụ, Image Generation trả ảnh ngay trong chat; Music tool trong voice có thể trả audio file để phát.

<Mermaid
  chart={`graph TD
  A["👤 User hỏi câu hỏi"] --> B["🤖 LLM phân tích"]
  B -->|"Không cần tool"| C["💬 Trả lời trực tiếp"]
  B -->|"Cần tool"| D["🔧 UnifiedToolHandler"]
  D --> E["📚 Built-in\nKB · Memory · Web · Image"]
  D --> F["🌐 Custom API\nHTTP endpoint"]
  D --> G["🔌 MCP Server\nExternal tools"]
  D --> H["📡 MCP Endpoint\nRealtime tools"]
  D --> I["🤖 Device Tools\nESP32 hardware"]
  E --> J["Tool Result"]
  F --> J
  G --> J
  H --> J
  I --> J
  J -->|"REQLLM"| K["🤖 LLM tổng hợp\ncâu trả lời"]
  J -->|"RESPONSE"| L["📤 Trả trực tiếp\ncho user"]`}
/>

Plan Access [#plan-access]

| Feature                | Free  | Go       | Plus     | Pro              | Enterprise |
| ---------------------- | ----- | -------- | -------- | ---------------- | ---------- |
| Built-in chat tools    | Có    | Có       | Có       | Có               | Có         |
| Custom API Tools       | Có    | Có       | Có       | Có               | Có         |
| MCP Tools              | Không | Có       | Có       | Có               | Có         |
| Realtime voice với MCP | Không | Giới hạn | Giới hạn | Giới hạn cao hơn | Custom     |

<Callout type="info">
  Nếu bạn không thấy MCP trong Admin UI, hãy kiểm tra plan hiện tại và role permissions của tài khoản trong assistant.
</Callout>

Related Pages [#related-pages]

<Cards>
  <Card title="Built-in Tools" description="KB, Memory, Web Search, Image Generation" href="/tools-mcp/built-in-tools" />

  <Card title="Custom API Tools" description="Tạo HTTP tool gọi API của bạn" href="/tools-mcp/custom-api-tools" />

  <Card title="MCP Server" description="Kết nối MCP server qua URL" href="/tools-mcp/mcp-server" />

  <Card title="MCP Endpoint" description="MCP cho voice và device sessions" href="/tools-mcp/mcp-endpoint" />

  <Card title="Device Tools" description="ESP32 cung cấp tools cho assistant" href="/tools-mcp/device-tools" />
</Cards>


# MCP Endpoint



MCP Endpoint là realtime connection path cho voice và device workflows. Khi bật, Assistant Core tạo một WebSocket URL có encrypted token cho assistant. Voice session dùng URL này để connect đến MCP Endpoint server và call tools trong lúc conversation đang diễn ra.

MCP Server Vs MCP Endpoint [#mcp-server-vs-mcp-endpoint]

| MCP Server                                            | MCP Endpoint                                                       |
| ----------------------------------------------------- | ------------------------------------------------------------------ |
| Bạn cấu hình từng MCP server bằng Server URL          | Assistant Core tạo một Endpoint URL cho assistant                  |
| Phù hợp cho chat và voice khi server MCP đã connected | Phù hợp cho realtime voice và device sessions                      |
| Tools được discover từ connected MCP servers          | Tools được cung cấp qua MCP Endpoint server trong realtime session |
| Quản lý ở trang **MCP Server**                        | Quản lý ở trang **MCP Endpoint**                                   |

Enable MCP Endpoint [#enable-mcp-endpoint]

1. Mở **Admin Dashboard**.
2. Chọn assistant.
3. Vào **MCP Endpoint**.
4. Bật **MCP Endpoint**.
5. Copy Endpoint URL nếu bạn cần cấu hình device hoặc external service.
6. Nhấn **Fetch Tools** để kiểm tra available tools.

Nếu UI báo MCP Endpoint chưa được cấu hình, backend environment cần được system admin cấu hình trước.

Endpoint URL Là Gì? [#endpoint-url-là-gì]

Endpoint URL chứa encrypted token để nhận diện assistant. Không chia sẻ URL này công khai. Bất kỳ service nào có URL hợp lệ đều có thể connect vào endpoint theo permissions mà hệ thống cho phép.

Khi Nào Nên Dùng MCP Endpoint? [#khi-nào-nên-dùng-mcp-endpoint]

Dùng MCP Endpoint khi:

* Bạn muốn voice assistant call tool theo realtime.
* Bạn có device hoặc service cần connect bằng WebSocket.
* Bạn muốn inspect nhanh realtime tool list bằng **Fetch Tools**.
* Bạn đang làm việc với device hỗ trợ MCP.

Check Available Tools [#check-available-tools]

Trong trang **MCP Endpoint**, nhấn **Fetch Tools**. Nếu thành công, bạn sẽ thấy tool list và số lượng parameters của từng tool.

Nếu không thấy tool:

* Kiểm tra MCP Endpoint đã enabled chưa.
* Kiểm tra MCP Endpoint server có đang chạy không.
* Kiểm tra device hoặc service đã connect endpoint chưa.
* Kiểm tra plan của bạn có hỗ trợ MCP không.

Voice Notes [#voice-notes]

Trong voice mode, MCP Endpoint có thể connect khi voice session bắt đầu. Assistant sẽ dùng realtime tools nếu câu nói của user cần external action, ví dụ điều khiển device, call API hoặc lấy data từ service đã nối vào endpoint.


# MCP Server



MCP Server dùng khi bạn đã có một server hỗ trợ **Model Context Protocol** và muốn assistant gọi tools từ server đó. Đây là cách phù hợp để kết nối CRM, database, internal tools, automation service hoặc hệ thống riêng của công ty.

Khi Nào Dùng MCP Server? [#khi-nào-dùng-mcp-server]

Dùng MCP Server khi:

* Bạn có một MCP server chạy ổn định và có URL truy cập được từ Assistant Core.
* Bạn muốn một assistant dùng nhiều tools do server đó cung cấp.
* Bạn muốn connect hoặc disconnect server theo từng assistant.

Nếu bạn chỉ cần gọi một HTTP API đơn giản, [Custom API Tools](/tools-mcp/custom-api-tools) thường dễ cấu hình hơn.

Thêm MCP Server [#thêm-mcp-server]

1. Mở **Admin Dashboard**.
2. Chọn assistant.
3. Vào **MCP Server**.
4. Nhấn **New MCP**.
5. Điền server details.
6. Nhấn **Create MCP**.
7. Bật trạng thái **Connected** cho MCP đó.

Khi MCP được connected, Assistant Core sẽ discover tool list từ server khi chat hoặc voice session bắt đầu. User không cần gọi tên tool; assistant sẽ tự dùng khi phù hợp.

Fields [#fields]

| Field              | Ý nghĩa                                                 |
| ------------------ | ------------------------------------------------------- |
| Name               | Tên MCP server để bạn dễ nhận biết                      |
| Description        | Mô tả server cung cấp tools gì                          |
| Server URL         | URL của MCP server                                      |
| Transport          | Connection type, thường là `sse` hoặc `streamable-http` |
| Authorization Type | Auth type nếu server yêu cầu                            |
| Icon URL           | Icon hiển thị trong Admin UI, nếu có                    |

<Callout type="info">
  Nếu MCP server cần auth đặc biệt, hãy chuẩn bị endpoint hoặc proxy phù hợp trước khi connect.
</Callout>

Created Vs Connected [#created-vs-connected]

Sau khi create MCP, server được attach với assistant nhưng chưa nhất thiết được dùng trong conversation.

| State        | Ý nghĩa                                                               |
| ------------ | --------------------------------------------------------------------- |
| Created      | MCP đã được lưu và attach với assistant                               |
| Connected    | Assistant sẽ connect MCP này và dùng tools của nó                     |
| Disconnected | MCP vẫn còn trong list, nhưng assistant không dùng trong conversation |

MCP Tools Được Dùng Như Thế Nào? [#mcp-tools-được-dùng-như-thế-nào]

Khi MCP đã connected:

1. Assistant Core connect tới MCP server.
2. Server trả về tool list.
3. Tools được đưa vào chat hoặc voice session.
4. Nếu user hỏi việc phù hợp, assistant call tool.
5. Tool result được assistant summarize lại cho user.

Use Cases [#use-cases]

| Nhu cầu             | MCP tool có thể cung cấp                |
| ------------------- | --------------------------------------- |
| Customer lookup     | `find_customer`, `list_recent_orders`   |
| Database access     | `query_sales_report`, `lookup_invoice`  |
| Task management     | `create_ticket`, `update_task_status`   |
| Internal operations | `restart_service`, `get_service_health` |

Troubleshooting [#troubleshooting]

| Issue                     | Check                                                          |
| ------------------------- | -------------------------------------------------------------- |
| Không thấy MCP tools      | Kiểm tra MCP đã bật **Connected** chưa                         |
| Connection fails          | Kiểm tra Server URL có truy cập được từ backend không          |
| Tool call fails           | Kiểm tra parameter schema của MCP server và server logs        |
| Assistant không dùng tool | Viết description rõ hơn hoặc thêm guidance trong system prompt |


# Auto vs Realtime



Auto Mode [#auto-mode]

<Mermaid
  chart={`graph LR
  A["🎤 User nói"] --> B["VAD\nphát hiện giọng"]
  B --> C["STT\nspeech → text"]
  C --> D["LLM\nxử lý + tools"]
  D --> E["TTS\ntext → speech"]
  E --> F["🔊 Phản hồi"]`}
/>

Realtime Mode [#realtime-mode]

<Mermaid
  chart={`graph LR
  A["🎤 User nói"] <-->|"Full-duplex\naudio stream"| B["Gemini Live /\nxAI Grok /\nOpenAI Realtime"]
  B <-->|"Phản hồi\ntức thì"| C["🔊 Phát audio"]`}
/>

So Sánh [#so-sánh]

| Tính năng      | Auto                 | Realtime               |
| -------------- | -------------------- | ---------------------- |
| **Tương tác**  | Nói → đợi → phản hồi | Hội thoại liên tục     |
| **Độ trễ**     | Trung bình           | Thấp (tức thì)         |
| **Mô hình AI** | Mọi LLM              | Gemini Live / xAI Grok |
| **Công cụ**    | Đầy đủ               | Hạn chế                |
| **Gói cần**    | Miễn Phí+            | Plus+                  |

Quota Giọng Nói [#quota-giọng-nói]

| Gói        | Auto           | Realtime       |
| ---------- | -------------- | -------------- |
| Miễn Phí   | 5 phút/ngày    | ❌              |
| Plus       | 30 phút/ngày   | 15 phút/ngày   |
| Pro        | 120 phút/ngày  | 60 phút/ngày   |
| Enterprise | Không giới hạn | Không giới hạn |


# Kết Nối ESP32



Các Bước [#các-bước]

1. Flash Firmware [#1-flash-firmware]

Tải firmware mới nhất từ Bảng Điều Khiển → **Thiết Bị → OTA** và flash vào ESP32-S3.

2. Lấy Mã Kích Hoạt [#2-lấy-mã-kích-hoạt]

1. Cấp nguồn ESP32
2. Kết nối WiFi
3. Thiết bị hiển thị **mã 6 số**

3. Liên Kết Trợ Lý [#3-liên-kết-trợ-lý]

1. Vào **Thiết Bị** trong Bảng Điều Khiển
2. Nhấn **Thêm Thiết Bị**
3. Nhập mã kích hoạt
4. Chọn trợ lý để liên kết
5. Nhấn **Liên Kết**

Giới Hạn Thiết Bị [#giới-hạn-thiết-bị]

| Gói        | Tối đa    |
| ---------- | --------- |
| Miễn Phí   | 1         |
| Plus       | 3         |
| Pro        | 10        |
| Enterprise | Tùy chỉnh |


# Bật Giọng Nói



Bật Giọng Nói [#bật-giọng-nói]

1. Vào **Cài Đặt Trợ Lý → Giọng Nói**
2. Bật **Kích Hoạt Giọng Nói**
3. Cấu hình:
   * **Giọng** — Chọn giọng nói (Kore, Puck, Ara...)
   * **Ngôn ngữ** — Chọn ngôn ngữ chính
   * **Chế độ** — Auto (mặc định) hoặc Realtime
4. Nhấn **Lưu**

Chế Độ Giọng Nói [#chế-độ-giọng-nói]

| Chế độ       | Cách hoạt động              | Phù hợp         |
| ------------ | --------------------------- | --------------- |
| **Auto**     | Nói → Đợi → Nhận phản hồi   | Hỏi đáp, hỗ trợ |
| **Realtime** | Hội thoại tự nhiên liên tục | Chat tự do      |

Thử Giọng Nói [#thử-giọng-nói]

1. Mở **Ứng Dụng Chat**
2. Nhấn biểu tượng **micro** 🎤
3. Nói câu hỏi
4. Trợ lý sẽ trả lời bằng giọng nói và văn bản

<Callout type="info">
  Giọng nói tính theo phút/ngày. Gói Miễn Phí có 5 phút Auto/ngày.
</Callout>