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 mã nguồn mở giúp mô hình AI sinh giao diện có cấu trúc thay vì chỉ trả về văn bản. Bạn có thể tạo chatbot, biểu mẫu, bảng, biểu đồ và màn hình tương tác với dữ liệu được render dần. Cài bản mẫu khá dễ bằng CLI, nhưng muốn tích hợp sâu cần biết JavaScript hoặc TypeScript và chọn runtime phù hợp.
OpenUI là framework full-stack, độc lập framework, dùng để xây giao diện do mô hình AI sinh ra theo thời gian thực. Thay vì chỉ hiển thị câu trả lời dạng chữ, ứng dụng có thể trả về bảng, biểu đồ, biểu mẫu, bố cục và các thành phần tương tác khác.
Điểm trung tâm của OpenUI là OpenUI Lang, một ngôn ngữ nhỏ gọn, ưu tiên streaming cho đầu ra giao diện. Mô hình được hướng dẫn dựa trên thư viện thành phần mà bạn cho phép, sau đó trình render đọc dữ liệu khi nó đang được sinh và cập nhật giao diện dần. Theo README, OpenUI Lang dùng ít hơn tới 67% token so với JSON tương đương trong các kịch bản benchmark.
Repo phù hợp với đội ngũ muốn làm chatbot có giao diện, trợ lý nội bộ, copilot, dashboard sinh động hoặc quy trình nhập liệu do AI điều khiển. Người mới có thể bắt đầu bằng CLI để tạo ứng dụng mẫu. Dev TypeScript có thể chọn từng package riêng cho React, Vue, Svelte, Angular, LangChain, email hoặc trình duyệt không cần build.
thesysdev/openui
Framework tạo giao diện sinh bởi AI theo thời gian thực, hỗ trợ React, Vue, Svelte, Angular và nhiều thư viện thành phần.
I.OpenUI làm được gì
Sinh giao diện có cấu trúc bằng OpenUI Lang: Mô hình không chỉ viết câu trả lời mà còn tạo ra cấu trúc UI theo ngôn ngữ riêng. Cách này phù hợp với bảng dữ liệu, form, biểu đồ, layout và các màn hình tương tác.
Render streaming: Giao diện được parse và render dần khi token từ mô hình trả về. Người dùng có thể nhìn thấy kết quả sớm hơn, thay vì chờ toàn bộ JSON hoặc toàn bộ câu trả lời hoàn tất.
Giới hạn thành phần được phép sinh: Bạn định nghĩa và đăng ký component library trước. Mô hình chỉ được hướng dẫn tạo các thành phần trong thư viện đó, giúp đầu ra có tính kiểm soát và gần với design system của sản phẩm hơn.
Tự tạo prompt từ thư viện component: OpenUI có thể tạo hướng dẫn cho mô hình dựa trên những component bạn cho phép. Bạn không phải tự viết toàn bộ mô tả cấu trúc và thuộc tính từ đầu.
Có component dựng sẵn: Các thư viện tích hợp bao gồm bảng, biểu đồ, form, layout và nhiều thành phần khác. Package React UI còn có layout chat dựng sẵn và hai thư viện component tích hợp để rút ngắn thời gian làm bản thử nghiệm.
Hỗ trợ nhiều frontend: Core không phụ thuộc React, Angular, Vue hay Svelte. Repo có runtime cho React, Vue 3, Svelte 5 và Angular, nên bạn có thể giữ framework hiện tại thay vì đổi toàn bộ ứng dụng.
Tích hợp agent: Package LangChain hỗ trợ LangChain và LangGraph, gồm agent transformer cùng helper phía server để stream OpenUI thông qua AG-UI. Đây là lựa chọn phù hợp khi ứng dụng đã có workflow agent.
Tạo chat UI và app surface: Bạn có thể dùng headless chat state, streaming adapter hoặc layout chat dựng sẵn. Cùng một nền tảng có thể phục vụ chatbot, copilot và các luồng tương tác rộng hơn.
Hỗ trợ email và embed: Package React Email dùng cho email được AI sinh và xuất HTML. Browser bundle cung cấp renderer, UI library, React và style dưới dạng script cùng stylesheet, phù hợp với CDN, iframe hoặc trang không có bước build.
Có A2UI và công cụ quan sát: Package A2UI cung cấp client giao thức A2UI v1.0 độc lập framework, kèm renderer React tùy chọn. Package observability-cloud có thể gom sự kiện OpenUI và gửi tới OpenUI Gateway để theo dõi trong console của Thesys.
Có benchmark về token: README cung cấp benchmark cho bảy kịch bản, gồm bảng đơn giản, biểu đồ, form liên hệ, dashboard, trang giá, panel cài đặt và sản phẩm thương mại điện tử. Tổng benchmark ghi nhận OpenUI Lang dùng 4.800 token, so với 10.180 và 9.948 token của hai định dạng JSON được so sánh.
Repo hiện có khoảng 15.181 sao và 1.008 fork. Dự án dùng TypeScript, giấy phép MIT và vẫn còn được cập nhật. Các thư mục packages/, examples/, docs/, spec/ và benchmarks/ giúp bạn đi từ package cụ thể đến ví dụ và cách đo hiệu năng.
II.Cần chuẩn bị gì
- Máy có Node.js phù hợp với yêu cầu trong
package.json:^20.19.0 || >=22.12.0. - Một terminal để chạy CLI hoặc cài package npm.
- Kiến thức cơ bản về JavaScript hoặc TypeScript nếu bạn muốn tích hợp vào ứng dụng thật.
- Một framework frontend phù hợp nếu dùng runtime tương ứng: React, Vue 3, Svelte 5 hoặc Angular.
- Nếu dùng LangChain, LangGraph, A2UI hoặc một package riêng, bạn cần chuẩn bị các package liên quan theo đúng hướng dẫn của ứng dụng.
- README được cung cấp không nêu nhà cung cấp mô hình, API key cụ thể hay biến môi trường bắt buộc cho quick start. Vì vậy không nên tự đoán tên key. Hãy xem ví dụ trong
examples/, tài liệu trongdocs/hoặc package bạn chọn để biết phần kết nối mô hình.
OpenUI có thể được bắt đầu từ CLI mà không cần tự dựng toàn bộ cấu trúc dự án. Nếu bạn chỉ muốn tìm hiểu cú pháp và cách render, có thể xem Playground của dự án. Nếu muốn chạy mã nguồn repo, hãy đọc package.json, pnpm-workspace.yaml và các ví dụ trước khi chọn lệnh cài dependency; README không đưa quy trình cài dependency cho toàn bộ monorepo.
Không đưa API key vào prompt, mã nguồn frontend hoặc repository công khai. README không chỉ định dịch vụ mô hình cụ thể, nên hãy kiểm tra đúng tài liệu của integration bạn chọn trước khi cấu hình chi phí và quyền truy cập.
III.Cài đặt từng bước
- Kiểm tra Node.jsĐảm bảo phiên bản Node đáp ứng package.json
- Tạo ứng dụng mẫuDùng CLI để scaffold app OpenUI có streaming
- Chọn packageCài runtime hoặc integration đúng với framework
- Đọc ví dụĐối chiếu examples và docs trước khi thêm mô hình thật
A.Kiểm tra phiên bản Node
Mở PowerShell hoặc terminal tại máy bạn và kiểm tra Node.js. README chỉ nêu yêu cầu trong package.json, không đưa lệnh kiểm tra cụ thể. Lệnh phổ thông sau giúp bạn xem phiên bản đang dùng:
node --versionKết quả cần thuộc một trong hai khoảng mà package yêu cầu: Node 20 với nhánh ^20.19.0, hoặc Node từ 22.12.0 trở lên. Nếu terminal báo không tìm thấy node, hãy cài Node.js trước. Nếu phiên bản thấp hơn yêu cầu, CLI hoặc dependency có thể lỗi ngay cả khi câu lệnh được viết đúng.
B.Tạo ứng dụng OpenUI mẫu
README đưa quick start bằng CLI như sau:
npx @openuidev/cli@latest create --name genui-chat-appLệnh này tải và chạy bản CLI mới nhất, sau đó tạo ứng dụng có tên genui-chat-app. README mô tả đây là cách nhanh nhất để bắt đầu. App mẫu có OpenUI Lang, prompt dựa trên thư viện component, streaming và nền tảng ứng dụng có thể chạy tiếp.
Chạy lệnh từ thư mục mà bạn muốn đặt dự án. Tên sau --name là tên scaffold được README dùng; nếu bạn thay tên, nên dùng tên thư mục hợp lệ và kiểm tra lại kết quả CLI. README không cung cấp lệnh chạy dev tiếp theo, nên không nên tự thêm một lệnh npm run nếu chưa xem package.json được sinh ra.
C.Cài package theo loại ứng dụng
Nếu bạn đã có ứng dụng JavaScript hoặc TypeScript, README đưa các lệnh cài trực tiếp sau đây.
React với renderer và component dựng sẵn:
npm install @openuidev/react-lang @openuidev/react-uiBackend độc lập framework hoặc Edge cần tạo prompt:
npm install @openuidev/lang-coreAgent dùng LangChain hoặc LangGraph:
npm install @openuidev/langchain @langchain/langgraphRuntime cho Vue, Svelte và Angular:
npm install @openuidev/vue-lang
npm install @openuidev/svelte-lang
npm install @openuidev/angular-langA2UI với payload component OpenUI Lang:
npm install @openuidev/a2ui zodMỗi lệnh cài package vào project hiện tại, vì vậy bạn cần mở terminal đúng thư mục có package.json của ứng dụng. Không cài tất cả package chỉ vì chúng đều nằm trong repo. Chọn package theo framework và chức năng bạn thật sự dùng. Với React, react-lang đảm nhiệm runtime, còn react-ui là đường nhanh hơn để có layout và component dựng sẵn.
D.Chọn package cho nhu cầu cụ thể
README liệt kê thêm các package chính. @openuidev/react-headless phù hợp khi bạn muốn tự thiết kế chat UI nhưng vẫn cần state, adapter streaming và bộ chuyển đổi định dạng message. @openuidev/react-email dành cho email sinh bằng mô hình và xuất HTML.
Nếu muốn nhúng bằng script hoặc iframe, xem @openuidev/browser-bundle. Nếu ứng dụng dùng assistant-ui, xem @openuidev/assistant-ui. Với server utility, xem @openuidev/server. Với theo dõi sự kiện trên console của Thesys, xem @openuidev/observability-cloud.
README cũng ghi OpenUI có plugin cho OpenClaw workspace và CLI có khả năng tạo system prompt hoặc JSON schema từ định nghĩa thư viện. Tuy nhiên, phần quick start không trình bày toàn bộ quy trình cấu hình từng integration. Khi cần chi tiết, bắt đầu từ docs/, thư mục examples/ và package.json của package tương ứng.
E.Cài Agent Skill nếu dùng coding agent
OpenUI có Agent Skill để các coding assistant hỗ trợ scaffold, build và debug ứng dụng Generative UI. README đưa lệnh cài như sau:
npx skills add thesysdev/skills --skill openuiSkill tập trung vào thiết kế component library, cú pháp OpenUI Lang, tạo system prompt, Renderer, SDK package và xử lý đầu ra LLM sai định dạng. Đây là phần bổ trợ cho coding agent, không phải điều kiện bắt buộc để chạy OpenUI.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra đầu tiên là chạy thành công lệnh scaffold:
npx @openuidev/cli@latest create --name genui-chat-appNếu CLI tạo được app genui-chat-app mà không dừng vì lỗi phiên bản Node hoặc dependency, phần quick start đã hoàn tất. README mô tả app tạo ra có streaming, component dựng sẵn và hỗ trợ OpenUI Lang. Khi mở app theo hướng dẫn trong chính project được sinh ra, bạn cần thấy luồng giao diện được cập nhật dần thay vì chỉ nhận một đoạn text tĩnh.
Nếu cài package riêng, kiểm tra package.json của ứng dụng và lockfile để xác nhận package đã được thêm. Sau đó đối chiếu import, component library và renderer với ví dụ gần nhất trong examples/. README không nêu một lệnh test hoặc một màn hình kết quả cố định cho toàn bộ repo, vì OpenUI có nhiều runtime và nhiều package.
Kết quả đúng về mặt kiến trúc là: thư viện component tạo được hướng dẫn cho mô hình, mô hình trả về OpenUI Lang stream, renderer parse stream và giao diện hiện dần. Nếu bạn chỉ nhận được text, hãy kiểm tra xem mình đã dùng renderer và format đầu ra OpenUI Lang chưa.
V.Dùng vào việc thật
A.Chủ shop làm màn hình sản phẩm
Chủ shop có thể dùng OpenUI để xây trợ lý tư vấn sản phẩm. Khi khách hỏi về một nhóm hàng, mô hình có thể trả về layout sản phẩm, bảng so sánh hoặc form thu thập nhu cầu, thay vì chỉ trả lời bằng đoạn văn.
Cách triển khai là đăng ký các component được phép như bảng, card, form và layout. Sau đó tạo prompt từ component library, gửi prompt cùng câu hỏi của khách đến mô hình, rồi stream OpenUI Lang về renderer. Component được giới hạn trước giúp màn hình giữ cùng phong cách và giảm khả năng mô hình sinh ra cấu trúc không được ứng dụng hỗ trợ.
Kết quả là khách thấy phần tư vấn xuất hiện dần, có thể xem thông tin theo bảng hoặc điền form ngay trong luồng chat. README có benchmark cho kịch bản e-commerce-product, nhưng không hứa hẹn chất lượng dữ liệu sản phẩm; phần dữ liệu và nghiệp vụ vẫn do bạn kết nối.
B.Nhân viên văn phòng tạo báo cáo tương tác
Một nhân viên có thể dùng chatbot nội bộ để yêu cầu “tóm tắt doanh số theo nhóm và trình bày thành bảng”. Nếu thư viện component có table, chart và layout, ứng dụng có thể render báo cáo có cấu trúc thay vì trả về danh sách số liệu dài.
Đội phát triển định nghĩa component, tạo system prompt từ thư viện, lấy dữ liệu từ hệ thống nội bộ rồi gửi ngữ cảnh cho mô hình. Renderer cập nhật bảng hoặc biểu đồ khi output đến. Nếu cần tự làm giao diện chat, chọn @openuidev/react-headless; nếu muốn đi nhanh với layout có sẵn, xem @openuidev/react-ui.
Kết quả thực tế phụ thuộc dữ liệu và quyền truy cập của hệ thống nội bộ. OpenUI cung cấp lớp tạo và render giao diện, không tự đảm bảo người dùng được phép xem mọi dữ liệu.
Giao diện AI hữu ích nhất khi mô hình được tự do trong phạm vi component mà sản phẩm kiểm soát.
Ông T
C.Dev xây copilot với LangGraph
Dev đã có agent LangGraph có thể thêm @openuidev/langchain và @langchain/langgraph. Package LangChain cung cấp agent transformer và helper server để stream OpenUI thông qua AG-UI.
Luồng làm việc là agent nhận yêu cầu, dùng component library để tạo hướng dẫn, sinh OpenUI Lang stream rồi gửi về client. Client dùng runtime tương ứng để render. Cách này phù hợp với copilot có nhiều bước, chẳng hạn agent vừa truy vấn dữ liệu vừa hiển thị form xác nhận hoặc bảng kết quả.
Không nên coi OpenUI là nơi thay thế LangGraph. LangGraph vẫn quản lý workflow agent; OpenUI đảm nhiệm cách biểu diễn kết quả thành giao diện có cấu trúc.
D.Dev cần hỗ trợ nhiều frontend
Một đội có sản phẩm React nhưng muốn mở rộng sang Vue, Svelte hoặc Angular có thể dùng cùng ý tưởng OpenUI Lang và chọn runtime theo frontend. README liệt kê @openuidev/react-lang, @openuidev/vue-lang, @openuidev/svelte-lang và @openuidev/angular-lang.
Phần dùng chung có thể đặt ở lớp core bằng @openuidev/lang-core, còn lớp render chọn theo ứng dụng. Với Svelte, README ghi rõ binding dành cho Svelte 5; với Vue là Vue 3. Nhờ vậy đội không phải biến toàn bộ ứng dụng sang một framework khác chỉ để thử Generative UI.
Kết quả tốt nhất khi component contract được thiết kế nhất quán giữa các runtime. Hãy xem ví dụ tương ứng trong examples/ thay vì giả định API của React sẽ giống hoàn toàn Vue, Svelte hoặc Angular.
VI.Lỗi hay gặp và cách xử lý
A.Node.js không đúng phiên bản
Dấu hiệu là CLI hoặc dependency báo lỗi khi cài, hoặc app không khởi động dù câu lệnh đúng. Kiểm tra bằng node --version, rồi đối chiếu yêu cầu ^20.19.0 || >=22.12.0 trong package.json. Nâng Node lên phiên bản được hỗ trợ và chạy lại trong đúng thư mục dự án.
B.Cài nhầm package cho framework
Bạn có thể cài React runtime vào ứng dụng Vue hoặc chỉ cài lang-core rồi mong có sẵn UI. Hãy xác định bạn cần parser và prompt generation, renderer, chat UI hay agent integration. Dùng bảng Packages trong README và các lệnh npm được cung cấp để chọn đúng package.
C.Mô hình trả về text hoặc JSON nhưng không render được
OpenUI cần prompt phù hợp, OpenUI Lang stream và renderer tương ứng. Nếu chỉ gửi câu hỏi thông thường cho mô hình, đầu ra có thể không phải format mà renderer hiểu. Kiểm tra component library đã được định nghĩa, prompt có được tạo từ library chưa và client có đang đọc stream bằng runtime đúng không.
D.Giao diện sinh ra thành phần ngoài dự kiến
Nguyên nhân thường là component library hoặc system prompt cho phép quá rộng. Chỉ đăng ký các component ứng dụng thực sự hỗ trợ, định nghĩa prop và cấu trúc bằng contract rõ ràng, rồi tạo lại prompt từ library. README nhấn mạnh controlled rendering và typed component contracts; hãy tận dụng hai lớp kiểm soát này.
E.Không biết lấy API key hoặc lệnh chạy app ở đâu
README được cung cấp không nêu nhà cung cấp mô hình, API key hay lệnh chạy dev chung cho mọi app. Đừng tự đoán tên biến môi trường. Mở package.json của app đã scaffold, sau đó xem examples/ và docs/ của integration cụ thể để tìm cấu hình chính xác.
VII.Có nên dùng không
Nên dùng OpenUI nếu bạn muốn mô hình sinh ra UI có cấu trúc, cần streaming, đã dùng React/Vue/Svelte/Angular hoặc đang xây agent bằng LangChain/LangGraph. Quick start bằng CLI khá dễ, package được tách rõ và repo có sẵn ví dụ, benchmark, runtime, component library cùng công cụ cho chat.
Điểm mạnh nổi bật là OpenUI Lang nhỏ gọn, hỗ trợ streaming và có cơ chế tạo prompt từ component library. README công bố mức giảm token tới 67% trong benchmark, nhưng đây là kết quả của các kịch bản đo cụ thể, không phải cam kết cho mọi ứng dụng. Giấy phép MIT cũng thuận tiện cho việc thử nghiệm và tích hợp.
Giới hạn là bạn vẫn cần hiểu frontend, component contract và luồng kết nối mô hình. OpenUI không tự cung cấp dữ liệu nghiệp vụ, không thay thế agent framework và README chưa ghi một cách cài đặt duy nhất cho toàn bộ monorepo. API key, chi phí mô hình, xác thực người dùng và bảo mật dữ liệu cũng vẫn là trách nhiệm của ứng dụng.
Nếu sản phẩm chỉ cần chatbot văn bản đơn giản, OpenUI có thể là một lớp phức tạp không cần thiết. Nếu bạn cần kiểm soát UI chặt, muốn giảm việc viết JSON thủ công và chấp nhận đầu tư vào component library, đây là lựa chọn đáng thử. Hãy bắt đầu bằng app scaffold, sau đó đọc ví dụ gần với framework và use case của bạn trước khi đưa dữ liệu thật vào.
Câu hỏi thường gặp
OpenUI có miễn phí không?
Repo dùng giấy phép MIT. README không nêu chi phí dịch vụ mô hình, OpenUI Gateway hay console quan sát, nên chi phí vận hành bên ngoài repo chưa được xác định từ tư liệu này.
OpenUI có cần GPU không?
README không nói OpenUI cần GPU. Đây là framework và các package JavaScript/TypeScript; yêu cầu phần cứng của mô hình hoặc dịch vụ AI mà bạn kết nối chưa được nêu.
OpenUI chạy trên Windows được không?
README không nêu hệ điều hành được hỗ trợ cụ thể. Vì cách bắt đầu dùng Node.js, npm và npx, bạn có thể kiểm tra khả năng chạy trên môi trường của mình bằng cách đáp ứng phiên bản Node trong package.json.
Có bắt buộc dùng React không?
Không. OpenUI có core độc lập framework và runtime cho React, Vue 3, Svelte 5 và Angular. Repo cũng có package cho browser bundle, server, email và các integration khác.
OpenUI có cần API key không?
README không chỉ định nhà cung cấp mô hình hay tên API key. Khi kết nối mô hình thật, bạn cần xem tài liệu của integration cụ thể và không nên tự đoán biến môi trường.
OpenUI khác gì chatbot chỉ trả lời bằng văn bản?
OpenUI cho mô hình sinh UI có cấu trúc như bảng, biểu đồ, form và layout, rồi render dần khi output streaming về. Chatbot văn bản thông thường không mặc định có component library, renderer hoặc controlled rendering như vậy.
Có thể dùng OpenUI với LangChain hoặc LangGraph không?
Có. README liệt kê package `@openuidev/langchain` và lệnh cài cùng `@langchain/langgraph`. Package này cung cấp agent transformer và helper server để stream OpenUI qua AG-UI.


