thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về thesysdev/openui — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: OpenUI: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
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.
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.
thesysdev/openui
Framework tạo giao diện sinh bởi AI theo thời gian thực, hỗ trợ React, Vue, Svelte và Angular.
I.OpenUI làm được gì
A.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ý.
B.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.
C.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.
D.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.
E.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.
F.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.
G.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.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.
II.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/.
III.Cài đặt từng bước
- 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ụngDùng CLI để scaffold một app OpenUI có sẵn streaming và UI
- Chọn packageCà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
A.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.
node --versionNế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.
B.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.
npx @openuidev/cli@latest create --name genui-chat-appBạ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.
C.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.
git clone https://github.com/thesysdev/openui.git
cd openuiREADME 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.
D.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:
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:
npm install @openuidev/react-headlessGó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.
E.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:
npm install @openuidev/lang-coreNếu app dùng LangChain hoặc LangGraph, README đưa lệnh sau:
npm install @openuidev/langchain @langchain/langgraphGó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.
F.Cài runtime cho Vue, Svelte hoặc Angular
README cung cấp từng lệnh riêng cho các runtime frontend:
npm install @openuidev/vue-lang
npm install @openuidev/svelte-lang
npm install @openuidev/angular-langvue-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.
G.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:
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.
IV.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:
npx @openuidev/cli@latest create --name genui-chat-appKế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ể.
V.Dùng vào việc thật
A.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.
B.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.
C.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.
D.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
E.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ó.
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ể.
VI.Lỗi hay gặp và cách xử lý
A.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.
B.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.
C.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.
D.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.
E.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.
VII.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.


