# thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

> OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-11-13 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/thesysdev-openui-giao-dien-ai-streaming

OpenUI là framework full-stack để xây giao diện do mô hình AI sinh ra theo thời gian thực. Thay vì chỉ trả về văn bản, mô hình có thể tạo bảng, biểu đồ, biểu mẫu, bố cục hoặc các thành phần tương tác. OpenUI nhận luồng kết quả đó và render dần thành giao diện đang hiển thị.

Repo phù hợp với dev xây chatbot, copilot, dashboard AI hoặc sản phẩm cần giao diện thay đổi theo câu hỏi của người dùng. Người làm sản phẩm cũng có thể dùng nó để hình dung cách tạo một app chat có UI dựng sẵn. Điểm đáng giá nhất là OpenUI Lang được thiết kế cho streaming và có thể dùng ít hơn tới 67% token so với JSON tương đương trong các benchmark của dự án.

Repo hiện có khoảng 15.181 sao và 1.008 fork. Mã nguồn chính dùng TypeScript, giấy phép MIT. OpenUI hỗ trợ nhiều runtime và có các gói dựng sẵn cho React, Vue, Svelte, Angular, LangChain, A2UI và các trường hợp nhúng qua trình duyệt.

```repo
- repo | thesysdev/openui
- kind | Framework
- desc | Framework tạo giao diện sinh bởi AI theo thời gian thực, hỗ trợ React, Vue, Svelte và Angular.
- stars | 15k
- lang | TypeScript
- license | MIT
```

## OpenUI làm được gì

### Sinh giao diện có cấu trúc thay vì chỉ trả lời bằng chữ

OpenUI Lang là ngôn ngữ nhỏ gọn dành cho kết quả UI do mô hình tạo ra. Bạn định nghĩa các component mà ứng dụng cho phép dùng, sau đó mô hình sinh cấu trúc dựa trên thư viện đó. Cách này phù hợp với chatbot cần trả lời bằng bảng, biểu đồ, form hoặc bố cục có thể tương tác.

Lợi ích thực tế là giao diện không phải lúc nào cũng cố định trước. Một câu hỏi về doanh thu có thể hiển thị bảng hoặc biểu đồ. Một yêu cầu nhập thông tin có thể hiển thị form. Những thành phần đó vẫn nằm trong tập component mà bạn đăng ký.

### Render streaming theo từng phần

OpenUI có streaming renderer. Khi model gửi output về theo từng token, renderer có thể phân tích và hiển thị dần. Người dùng không cần chờ toàn bộ kết quả mới thấy giao diện.

Đây là điểm hữu ích cho chat AI và copilot. Một dashboard dài, bảng dữ liệu hoặc form có thể bắt đầu xuất hiện trong lúc phần còn lại vẫn đang được sinh.

### Giới hạn giao diện bằng component library

Bạn có thể dùng component library dựng sẵn hoặc mở rộng bằng component của mình. Component library đóng vai trò như giới hạn an toàn cho nội dung mà model được phép tạo.

Cách làm này giúp sản phẩm giữ được giao diện nhất quán. Model không tự ý sinh mọi loại HTML hay component không được ứng dụng hỗ trợ. Bạn cũng có thể tạo prompt từ chính thư viện component đã cho phép.

### Tự tạo system prompt từ thư viện component

OpenUI hỗ trợ sinh hướng dẫn cho model trực tiếp từ component library. Thay vì tự viết thủ công toàn bộ mô tả component, bạn có thể để công cụ tạo phần chỉ dẫn dựa trên những component đã đăng ký.

Tính năng này phù hợp khi thư viện UI có nhiều prop hoặc khi team muốn cập nhật prompt cùng với định nghĩa component. Repo cũng có CLI hỗ trợ tạo system prompt hoặc JSON schema từ một library definition.

### Dùng với nhiều framework frontend

Core của OpenUI không gắn cứng với React. Repo có runtime cho React, Vue 3, Svelte 5 và Angular. React có thêm thư viện component, layout chat và các UI dựng sẵn.

Nếu app đang dùng Vue, Svelte hoặc Angular, bạn có thể chọn runtime tương ứng thay vì chuyển toàn bộ frontend sang React. Nếu backend hoặc lớp prompt không cần frontend cụ thể, gói lang-core cung cấp parser, prompt generation, runtime evaluation và type layer độc lập framework.

### Kết nối với agent và hệ sinh thái LangChain

Gói `@openuidev/langchain` dành cho LangChain và LangGraph agent. Gói này có agent transformer và server helpers để stream OpenUI qua AG-UI.

Điều đó hữu ích khi agent đã có sẵn logic gọi tool, truy xuất dữ liệu hoặc lập kế hoạch. Bạn có thể thêm lớp UI có cấu trúc vào luồng agent thay vì chỉ trả về câu trả lời văn bản.

### Dựng nhanh chat UI và nhúng không cần build

Gói `@openuidev/react-ui` có chat layout dựng sẵn, UI primitives và hai component library tích hợp. Gói `@openuidev/react-headless` dành cho trường hợp bạn muốn tự thiết kế chat UI nhưng vẫn dùng state và streaming adapter của OpenUI.

Nếu cần nhúng vào CDN, iframe hoặc trang không có quy trình build, `@openuidev/browser-bundle` cung cấp renderer, UI library, React và styles dưới dạng script cùng stylesheet.

### Hỗ trợ email, A2UI và quan sát hoạt động

`@openuidev/react-email` cung cấp định nghĩa component React Email và tùy chọn prompt cho email do model sinh. `@openuidev/a2ui` là client giao thức A2UI v1.0 độc lập framework, có renderer React tùy chọn.

Repo cũng có các gói server và observability. `@openuidev/observability-cloud` dùng để gom các event OpenUI và gửi tới OpenUI Gateway trong Thesys console.

## Cần chuẩn bị gì

Bạn cần Node.js đáp ứng yêu cầu trong `package.json`: `^20.19.0 || >=22.12.0`. Nói đơn giản, hãy dùng Node thuộc dòng 20 với phiên bản từ 20.19.0 trở lên, hoặc Node từ 22.12.0 trở lên.

Repo dùng TypeScript. Cấu trúc có `package.json`, `pnpm-lock.yaml` và `pnpm-workspace.yaml`, cho thấy đây là một workspace nhiều package. Tuy vậy, README quick start hướng dẫn bắt đầu bằng CLI thông qua `npx`.

Bạn cần một terminal có thể chạy lệnh `npx`. README không nêu hệ điều hành cụ thể, nên tài liệu được cung cấp chưa đủ căn cứ để khẳng định mọi cách chạy trên Windows, macOS hay Linux.

README không nêu API key, tài khoản dịch vụ AI, loại model bắt buộc, GPU hay phần cứng đặc biệt. Các yêu cầu đó có thể phụ thuộc vào ứng dụng và agent mà bạn tích hợp sau này. Bạn không nên tự thêm key vào repo nếu tài liệu của ví dụ chưa yêu cầu.

Nếu muốn dùng một framework cụ thể, bạn chọn package tương ứng: React, Vue, Svelte, Angular, LangChain, A2UI hoặc gói framework-agnostic. Nếu muốn đóng góp hoặc nghiên cứu nội bộ, repo có thêm thư mục `examples/`, `docs/`, `packages/`, `benchmarks/` và `spec/`.

## Cài đặt từng bước

```steps
- Kiểm tra Node | Đảm bảo Node đáp ứng phiên bản mà package.json yêu cầu
- Tạo ứng dụng | Dùng CLI để scaffold một app OpenUI có sẵn streaming và UI
- Chọn package | Cài runtime phù hợp nếu muốn tích hợp vào app hiện có
- Đọc ví dụ | Xem examples và docs để nối component, prompt, model và renderer
```

### Kiểm tra phiên bản Node

Mở terminal trên máy và kiểm tra Node đang dùng. Phiên bản phải đáp ứng yêu cầu `^20.19.0 || >=22.12.0` trong `package.json`.

```bash
node --version
```

Nếu phiên bản thấp hơn yêu cầu, hãy nâng Node trước khi chạy CLI. README không cung cấp lệnh cài hoặc nâng Node cụ thể, nên bạn cần dùng cách quản lý Node phù hợp với máy của mình.

### Tạo ứng dụng OpenUI nhanh nhất

README giới thiệu đây là cách nhanh nhất để bắt đầu. Lệnh sau tạo một ứng dụng tên `genui-chat-app`.

```bash
npx @openuidev/cli@latest create --name genui-chat-app
```

Bạn chạy lệnh trong thư mục nơi muốn tạo dự án. Giá trị sau `--name` là tên thư mục hoặc tên app được scaffold. Nếu terminal báo không tìm thấy `npx`, hãy kiểm tra lại Node.js vì `npx` thường đi cùng môi trường Node, nhưng README không có hướng dẫn xử lý riêng cho lỗi này.

Ứng dụng scaffold có sẵn nền tảng end-to-end với OpenUI Lang, prompt dựa trên library, streaming và UI tích hợp. README chưa ghi lệnh tiếp theo để khởi động app sau khi tạo. Vì vậy, sau khi scaffold xong, hãy mở `package.json` của dự án mới và xem các script được khai báo.

### Lấy mã nguồn repo để xem ví dụ

Nếu muốn đọc toàn bộ workspace, các package và ví dụ tích hợp, bạn có thể clone repo rồi đi vào thư mục repo.

```bash
git clone https://github.com/thesysdev/openui.git
cd openui
```

README cho biết `examples/` chứa cookbook và các implementation tham khảo. Bạn cũng có thể xem `examples/README.md` để tìm ví dụ tập trung. Repo có các nhóm ví dụ về agent framework, app framework, cookbook, design system, harness và các trường hợp khác.

### Cài package cho React

Với một ứng dụng React đã có, README đưa ra gói cơ bản để dùng renderer và component dựng sẵn:

```bash
npm install @openuidev/react-lang @openuidev/react-ui
```

`@openuidev/react-lang` dùng để định nghĩa component library, tạo prompt và render OpenUI Lang streaming trong React. `@openuidev/react-ui` phù hợp nếu bạn muốn có layout chat, UI primitives và component library dựng sẵn.

Nếu muốn tự xây giao diện chat, README cũng có gói headless:

```bash
npm install @openuidev/react-headless
```

Gói này cung cấp chat state, streaming adapters và message format converters. README không đưa một đoạn code hoàn chỉnh để nối các gói này vào app cụ thể, nên bạn cần xem docs hoặc examples trước khi triển khai.

### Cài package cho backend hoặc agent

Nếu phần tạo prompt cần độc lập với frontend, dùng gói core:

```bash
npm install @openuidev/lang-core
```

Nếu app dùng LangChain hoặc LangGraph, README đưa lệnh sau:

```bash
npm install @openuidev/langchain @langchain/langgraph
```

Gói OpenUI cung cấp agent transformer và server helpers để stream qua AG-UI. Bạn vẫn cần tự chuẩn bị agent và luồng model của ứng dụng. README không nêu một API key cụ thể hoặc một nhà cung cấp model bắt buộc.

### Cài runtime cho Vue, Svelte hoặc Angular

README cung cấp từng lệnh riêng cho các runtime frontend:

```bash
npm install @openuidev/vue-lang
npm install @openuidev/svelte-lang
npm install @openuidev/angular-lang
```

`vue-lang` dành cho Vue 3, `svelte-lang` dành cho Svelte 5 và `angular-lang` dành cho Angular. Các gói này hỗ trợ định nghĩa component library và render OpenUI Lang streaming trong framework tương ứng.

### Cài hỗ trợ A2UI

Nếu ứng dụng cần giao thức A2UI với payload component của OpenUI Lang, README đưa lệnh:

```bash
npm install @openuidev/a2ui zod
```

`@openuidev/a2ui` là client A2UI v1.0 độc lập framework, có renderer React tùy chọn. `zod` được cài cùng theo hướng dẫn của README. Không nên tự đổi tên package hoặc bỏ package này nếu bạn đang làm đúng theo ví dụ A2UI.

## Kiểm tra đã chạy được chưa

Cách kiểm tra đầu tiên là lệnh tạo app hoàn tất mà không báo lỗi:

```bash
npx @openuidev/cli@latest create --name genui-chat-app
```

Kết quả mong đợi theo README là một app scaffold có OpenUI Lang, prompt dựa trên component library, streaming và nền tảng UI dựng sẵn. README chưa ghi chính xác màn hình terminal sau khi tạo hoặc lệnh chạy app, nên không nên tự khẳng định một URL hay cổng cụ thể.

Nếu cài package trong app hiện có, kiểm tra package xuất hiện trong `package.json` và không có lỗi dependency. Với `@openuidev/react-lang`, dấu hiệu đúng là bạn đã có package để định nghĩa component library, tạo prompt và render luồng OpenUI Lang. Với `@openuidev/lang-core`, dấu hiệu đúng là lớp parser, prompt, runtime và type đã được thêm vào dự án.

Để kiểm tra sâu hơn, mở các ví dụ trong `examples/` hoặc các tài liệu trong `docs/`. Playground của dự án cũng được README giới thiệu như nơi thử tạo UI trực tiếp với component library mặc định, nhưng README không mô tả thêm các bước thao tác cụ thể.

## Dùng vào việc thật

### Chủ shop cần chatbot trả lời bằng bảng sản phẩm

Một chủ shop có thể dùng OpenUI để xây chatbot không chỉ trả lời “sản phẩm còn hàng”. Với component library gồm bảng, form và layout, chatbot có thể trả về bảng sản phẩm hoặc form thu thập nhu cầu.

Cách làm là định nghĩa các component được phép, tạo system prompt từ library, gửi prompt đó cho model rồi stream OpenUI Lang về frontend. Với app React, có thể bắt đầu bằng `@openuidev/react-lang` và `@openuidev/react-ui`.

Kết quả nhận được là UI có cấu trúc và hiển thị dần. Tuy nhiên, README không cung cấp prompt nghiệp vụ bán hàng cụ thể, nên nội dung như giá, tồn kho hoặc chính sách vận chuyển vẫn phải do hệ thống của bạn cung cấp.

### Nhân viên văn phòng cần tạo báo cáo nhanh

Một nhân viên văn phòng có thể dùng app chat để yêu cầu hiển thị báo cáo theo bảng hoặc biểu đồ. OpenUI có component library cho charts, forms, tables và layouts, nên đây là nhóm giao diện phù hợp với khả năng được mô tả trong README.

Bạn giới hạn component mà app cho phép, tạo hướng dẫn model từ library và truyền dữ liệu báo cáo vào luồng agent hoặc backend. Renderer sẽ hiển thị kết quả dần thay vì chờ toàn bộ cấu trúc hoàn tất.

Điểm cần nhớ là OpenUI phụ trách cách sinh và render UI. README không nói app tự kết nối với dữ liệu doanh nghiệp, nên phần lấy dữ liệu và phân quyền vẫn cần được thiết kế trong ứng dụng của bạn.

### Dev xây copilot cho sản phẩm nội bộ

Dev có thể dùng `@openuidev/react-headless` nếu muốn tự thiết kế giao diện chat nhưng cần state, adapter streaming và bộ chuyển đổi định dạng message. Nếu muốn dùng layout có sẵn, chọn `@openuidev/react-ui`.

Agent có thể sử dụng LangChain hoặc LangGraph, sau đó nối qua `@openuidev/langchain`. Luồng cơ bản là agent nhận yêu cầu, tạo output OpenUI Lang, server stream output qua AG-UI và frontend render từng phần.

Cách này phù hợp với copilot cần trả về kết quả có hành động hoặc dữ liệu tương tác, thay vì một đoạn văn dài. Phần tool nào được phép gọi và dữ liệu nào được trả về vẫn phải do app kiểm soát.

### Team frontend cần giữ một bộ UI nhất quán

Team có thể định nghĩa component library riêng để model chỉ sử dụng những component đã được đăng ký. Prompt được tạo từ library giúp mô tả đúng contract của component, còn renderer đảm nhiệm việc hiển thị output.

Nếu team dùng Vue, Svelte hoặc Angular, chọn runtime tương ứng. Nếu cần chia sẻ parser, prompt và type giữa nhiều frontend, xem `@openuidev/lang-core`.

Kết quả là cùng một nền tảng sinh UI nhưng mỗi framework vẫn có runtime riêng. Đây là lựa chọn đáng cân nhắc cho team có design system và muốn kiểm soát output của model.

> Giao diện AI tốt không chỉ là model trả lời đúng, mà còn là model trả về đúng loại thành phần mà sản phẩm cho phép.
>
> — Ông T

### Team muốn nhúng nhanh một trải nghiệm OpenUI

Nếu sản phẩm cần nhúng qua CDN, iframe hoặc trang không có build pipeline, team có thể xem `@openuidev/browser-bundle`. README mô tả package này là browser bundle có renderer, UI library, React và styles dưới dạng script cùng stylesheet.

Cách này phù hợp với một trang thử nghiệm, khu vực nhúng hoặc prototype cần tích hợp nhanh. Trước khi dùng cho dữ liệu thật, hãy kiểm tra kỹ phạm vi script, styles và quyền truy cập dữ liệu của trang chứa nó.

```note
OpenUI không có cryptocurrency, token hoặc coin chính thức. README cảnh một trang tin tức tài sản dùng tên OpenUI là không liên kết và không được maintainer xác nhận.

Với ứng dụng thật, hãy kiểm soát component được đăng ký, dữ liệu truyền vào model và thông tin nhạy cảm trong luồng streaming. README không cung cấp chính sách chi phí model hoặc yêu cầu API key cụ thể.
```

## Lỗi hay gặp và cách xử lý

### Node không đáp ứng phiên bản yêu cầu

Nếu CLI hoặc package báo lỗi tương thích, kiểm tra `node --version`. `package.json` yêu cầu `^20.19.0 || >=22.12.0`, nên Node quá cũ sẽ không phù hợp. Nâng Node rồi chạy lại lệnh scaffold.

### Chạy lệnh trong sai thư mục

Lệnh `git clone` tạo thư mục repo, còn lệnh cài package phải chạy trong thư mục dự án phù hợp. Nếu terminal không tìm thấy `package.json`, hãy dùng `cd` vào đúng thư mục trước khi chạy `npm install`.

### Chọn sai package cho framework

Dùng `vue-lang` cho ứng dụng Vue, `svelte-lang` cho Svelte 5 và `angular-lang` cho Angular. Với React, chọn `react-lang`; nếu cần UI dựng sẵn thì thêm `react-ui`. Đừng mặc định cài toàn bộ package nếu app chỉ dùng một runtime.

### Chờ một lệnh chạy app không có trong README

README có lệnh scaffold nhưng chưa ghi lệnh khởi động ứng dụng sau đó. Hãy mở `package.json` của app mới và xem phần scripts, hoặc đọc Quickstart và các ví dụ trong repo. Không nên tự đoán tên script.

### Output của model không render như mong muốn

Kiểm tra component library, system prompt và contract props. OpenUI chỉ render tốt những component đã được định nghĩa và đăng ký đúng. Nếu output malformed, xem docs, examples và phần Agent Skill mà repo giới thiệu để tìm hướng dẫn về cú pháp OpenUI Lang, prompt và debugging.

## Có nên dùng không

OpenUI đáng dùng nếu bạn cần giao diện AI có cấu trúc, streaming và có thể kiểm soát bằng component library. Repo có hệ sinh thái rộng: runtime cho bốn framework frontend, gói React dựng sẵn, tích hợp LangChain/LangGraph, A2UI, email, server, browser bundle và observability. MIT cũng là một giấy phép thuận tiện cho nhiều dự án.

Điểm mạnh rõ nhất là OpenUI Lang hướng tới kết quả UI streaming và có benchmark cho thấy mức giảm token đáng kể trong bảy kịch bản. Tuy nhiên, con số “tới 67%” là kết quả benchmark của dự án, không phải cam kết cho mọi ứng dụng. README cũng không cung cấp đầy đủ code hoàn chỉnh cho từng loại sản phẩm.

Bạn nên cân nhắc công cụ khác nếu chỉ cần chatbot văn bản đơn giản, không cần UI có cấu trúc hoặc không muốn quản lý component contract. Bạn cũng cần tự xây phần dữ liệu, agent, xác thực, phân quyền, chi phí model và vận hành production nếu ứng dụng yêu cầu. README chưa nói đủ về các phần này.

Nếu muốn thử nhanh, hãy bắt đầu bằng CLI. Nếu đang có app hiện hữu, chọn đúng package theo framework và đọc examples trước khi tích hợp sâu. Với một team muốn model sinh UI nhưng vẫn giữ quyền kiểm soát thiết kế, OpenUI là lựa chọn đáng xem xét.

## Câu hỏi thường gặp

### OpenUI có miễn phí không?

Repo có giấy phép MIT. README được cung cấp không nêu chi phí sử dụng dịch vụ model, chi phí hosting hoặc bảng giá riêng, nên chưa thể kết luận toàn bộ hệ thống đều không phát sinh phí.

### Có cần GPU để chạy OpenUI không?

README không nêu yêu cầu GPU. Repo là framework và có các package frontend, backend, renderer cùng CLI; yêu cầu phần cứng của model hoặc dịch vụ AI bạn tích hợp chưa được tài liệu này xác định.

### OpenUI cần Node phiên bản nào?

`package.json` yêu cầu Node `^20.19.0 || >=22.12.0`. Bạn nên dùng Node 20 từ 20.19.0 trở lên hoặc Node từ 22.12.0 trở lên.

### Có thể dùng OpenUI với React, Vue, Svelte và Angular không?

Có. README liệt kê runtime cho React, Vue 3, Svelte 5 và Angular. React còn có các gói UI và chat dựng sẵn.

### OpenUI có cần API key không?

README không nêu API key cụ thể hoặc nhà cung cấp model bắt buộc. Khi tích hợp model hay agent vào ứng dụng thật, yêu cầu xác thực sẽ phụ thuộc vào dịch vụ bạn chọn.

### OpenUI khác gì cách trả về JSON thông thường?

OpenUI Lang là ngôn ngữ nhỏ gọn, ưu tiên streaming và được thiết kế cho model-generated UI. Benchmark trong README cho thấy OpenUI Lang dùng ít token hơn các định dạng JSON được so sánh, nhưng kết quả thực tế phụ thuộc kịch bản.

### Dữ liệu gửi qua OpenUI có an toàn không?

README không đưa ra cam kết bảo mật dữ liệu chung hoặc mô hình lưu trữ dữ liệu. Bạn cần tự kiểm soát dữ liệu đưa vào model, quyền truy cập component, agent và các gói observability khi triển khai.
