Whirl là gì?
Whirl là ứng dụng trò chuyện AI full-stack mã nguồn mở được xây dựng bằng Next.js và Convex. Đây là mã nguồn phía sau whirl.chat và được cung cấp theo giấy phép MIT, vì vậy bạn có thể kiểm tra, tự vận hành hoặc đóng góp cải tiến.
Dự án tập hợp nhiều mô hình AI, bộ nhớ lâu dài, artifact có thể chỉnh sửa, nghiên cứu web, công cụ tùy chỉnh và các cuộc trò chuyện tập trung vào quyền riêng tư trong một giao diện. Các mô hình được định tuyến qua OpenRouter, trong khi Convex cung cấp cơ sở dữ liệu, hàm backend, tính năng streaming và các tác vụ theo lịch.
Tính năng chính
- Nhiều mô hình hàng đầu: Sử dụng các mô hình AI hàng đầu trong cùng một cuộc trò chuyện và điều chỉnh mức độ suy luận.
- Artifact luôn cập nhật: Tạo tài liệu, biểu đồ và trang tương tác vẫn có thể chỉnh sửa trong bảng điều khiển bên cạnh, đồng thời có thể chia sẻ qua liên kết.
- Công cụ và kỹ năng: Kết nối các công cụ bên ngoài qua MCP, bao gồm các tích hợp dựa trên OAuth, và cài đặt những kỹ năng mở rộng hành vi của Whirl.
- Bộ nhớ lâu dài: Duy trì tùy chọn và ngữ cảnh dự án giữa các cuộc trò chuyện.
- Thông tin web hiện tại: Tìm kiếm web và đọc các trang để tạo câu trả lời dựa trên những nguồn gần đây.
- Cuộc trò chuyện riêng tư: Các cuộc trò chuyện bị khóa được mã hóa trên thiết bị của người dùng bằng mật khẩu mà máy chủ không bao giờ nhận được. Chúng chỉ sử dụng các mô hình không lưu giữ dữ liệu.
- Tính năng nâng cao năng suất: Whirl bao gồm chế độ ẩn danh, xếp hàng tin nhắn, nhập liệu bằng giọng nói, tạo ảnh, đính kèm tệp, thư mục và chia sẻ.
- Giao diện tùy chỉnh: Chọn chế độ sáng hoặc tối, đặt màu nhấn và cài đặt Whirl như một ứng dụng web trên di động.
Công nghệ sử dụng
Ứng dụng web production sử dụng Next.js 16, React 19, Tailwind CSS v4 và Motion. Convex cung cấp backend, Clerk xử lý xác thực, còn OpenRouter cung cấp quyền truy cập mô hình thông qua AI SDK. Kho mã được tổ chức dưới dạng các workspace của Bun và viết bằng TypeScript.
Chỉ Convex, Clerk và OpenRouter là bắt buộc cho thiết lập cốt lõi. Các dịch vụ khác là tùy chọn:
- Autumn để thanh toán
- Exa để tìm kiếm web
- Supermemory để quản lý bộ nhớ
- PostHog và Axiom để phân tích
- Braintrust để tracing
- Resend để gửi email
- Median cho tác nhân hỗ trợ
Nếu một dịch vụ tùy chọn chưa được cấu hình, Whirl sẽ ẩn tính năng do dịch vụ đó cung cấp thay vì yêu cầu dịch vụ này để chạy ứng dụng.
Điều kiện tiên quyết
Trước khi cài đặt Whirl, hãy chuẩn bị những thành phần sau:
- Đã cài đặt Bun trên máy tính
- Một tài khoản Convex miễn phí
- Một ứng dụng Clerk
- Một khóa API OpenRouter
- Git để sao chép kho mã
Bước 1: Sao chép và cài đặt Whirl
Sao chép kho mã, truy cập thư mục của kho và cài đặt tất cả dependency của workspace bằng Bun:
git clone https://github.com/whirlchat/whirl.git
cd whirl
bun installBước 2: Tạo backend Convex
Di chuyển vào package backend và khởi động quy trình phát triển Convex:
cd packages/backend
bunx convex devTrong lần chạy đầu tiên, Convex sẽ hướng dẫn bạn tạo dự án và deployment phát triển. Hãy để quy trình này tiếp tục chạy để các thay đổi backend được đồng bộ trong quá trình phát triển.
Bước 3: Cấu hình secret backend
Mở một terminal khác trong packages/backend. Thêm domain trình phát hành JWT của Clerk và khóa API OpenRouter vào môi trường Convex:
bunx convex env set CLERK_JWT_ISSUER_DOMAIN https://your-instance.clerk.accounts.dev
bunx convex env set OPENROUTER_API_KEY sk-or-v1-...Thay các giá trị mẫu bằng thông tin xác thực từ tài khoản Clerk và OpenRouter của bạn. Tài liệu self-hosting chi tiết giải thích template JWT của Clerk mà Convex yêu cầu.
Không commit khóa API hoặc secret xác thực vào kho mã. Lưu secret backend thông qua các lệnh môi trường của Convex và lưu cài đặt web cục bộ trong tệp môi trường phù hợp.
Bước 4: Cấu hình ứng dụng web
Di chuyển đến ứng dụng web production và tạo tệp môi trường cục bộ từ ví dụ được cung cấp:
cd ../../apps/v2
cp .env.example .env.localMở .env.local và điền bốn giá trị bắt buộc cho Convex và Clerk. Sử dụng tệp ví dụ làm nguồn tham chiếu cho tên biến chính xác thay vì tạo tên mới.
Bước 5: Khởi động môi trường phát triển
Quay lại thư mục gốc của kho mã và khởi động lệnh phát triển:
cd ../..
bun run devSau khi các dịch vụ đang chạy, mở localhost:3000. Đăng nhập thông qua ứng dụng Clerk đã cấu hình và bắt đầu trò chuyện.
Cách sử dụng cơ bản
Bắt đầu cuộc trò chuyện
Nhập yêu cầu vào trình soạn thảo trò chuyện và gửi đến mô hình đã cấu hình. Một prompt đầu tiên đơn giản có thể xác minh rằng ứng dụng web, xác thực, backend Convex và kết nối OpenRouter đang hoạt động cùng nhau:
Explain the main components of this application in five concise points.Làm việc với các mô hình
Whirl được thiết kế để cung cấp quyền truy cập vào nhiều mô hình hàng đầu thông qua OpenRouter trong một cuộc trò chuyện. Bạn cũng có thể sử dụng các mức độ suy luận có thể điều chỉnh khi ứng dụng và mô hình đã chọn hỗ trợ tính năng này.
Tạo và Tinh chỉnh Artifact
Yêu cầu Whirl tạo tài liệu, biểu đồ hoặc trang tương tác. Các artifact có thể cập nhật này vẫn chỉnh sửa được trong bảng điều khiển bên và có thể chia sẻ qua liên kết, phù hợp với những đầu ra cần tiếp tục tinh chỉnh thay vì chỉ nhận một câu trả lời duy nhất trong cuộc trò chuyện.
Sử dụng Tệp, Giọng nói và Tổ chức
Whirl hỗ trợ đính kèm tệp và nhập bằng giọng nói bên cạnh tin nhắn dạng văn bản. Các cuộc trò chuyện có thể được sắp xếp vào thư mục, trong khi tính năng chia sẻ giúp cung cấp những nội dung đã chọn cho người khác.
Tìm hiểu về Repository
Monorepo chứa nhiều ứng dụng và một backend dùng chung:
apps/v2: Ứng dụng web Next.js dùng cho Whirl trong môi trường production.apps/console: Console quản trị dựa trên Vite dành cho model, tích hợp và skill.apps/mobile: Ứng dụng native được xây dựng bằng Expo.apps/waitlist: Trang waitlist độc lập.apps/remotion: Các composition video quảng bá.apps/legacy: Ứng dụng web trước đây, được giữ lại để tham khảo nhưng không còn được duy trì.packages/backend: Schema, function Convex và pipeline AI.docs: Hướng dẫn tự lưu trữ, cấu hình và kiến trúc.brand: Logo, màu sắc, banner và biểu tượng ứng dụng.
Đối với việc phát triển web hiện tại, hãy tập trung vào apps/v2 và packages/backend. Tránh xây dựng tính năng mới trên apps/legacy vì ứng dụng này không còn được duy trì.
Mẹo Nâng cao
Thêm Dịch vụ Tùy chọn Từng bước
Bắt đầu với cấu hình Convex, Clerk và OpenRouter bắt buộc. Sau khi luồng trò chuyện cốt lõi hoạt động, hãy lần lượt thêm từng nhà cung cấp tùy chọn. Whirl tự động ẩn những chức năng có khóa bắt buộc chưa được cung cấp, giúp việc vận hành một hệ thống nhỏ gọn trở nên thực tế hơn.
Tham khảo hướng dẫn cấu hình của repository để biết các biến môi trường liên quan đến thanh toán, tìm kiếm, bộ nhớ, phân tích, tracing, email và hỗ trợ.
Chọn Chế độ Riêng tư Phù hợp
Sử dụng chế độ ẩn danh khi bạn không muốn có quy trình trò chuyện thông thường được lưu liên tục. Để được bảo vệ tốt hơn, các cuộc trò chuyện bị khóa sẽ được mã hóa trên thiết bị bằng mật khẩu mà máy chủ không bao giờ nhìn thấy và chỉ được trả lời bởi các model không lưu giữ dữ liệu. Hãy nhớ rằng việc mất mật khẩu do phía client quản lý có thể ảnh hưởng đến khả năng truy cập nội dung đã mã hóa.
Kiểm tra Pipeline Tin nhắn
Khi gỡ lỗi hoạt động streaming, lệnh gọi công cụ hoặc hành vi của model, hãy đọc hướng dẫn kiến trúc của dự án. Tài liệu này giải thích cách một tin nhắn đi từ trình soạn thảo đến model rồi quay trở lại. Phần triển khai liên quan chủ yếu được chia giữa ứng dụng web production và backend Convex.
Chuẩn bị Cẩn thận cho Production
Quick start tạo ra một môi trường phát triển. Trước khi triển khai công khai, hãy làm theo đầy đủ hướng dẫn tự lưu trữ, bao gồm các chỉ dẫn về template JWT của Clerk và triển khai production.
Đóng góp An toàn
Trước khi mở pull request, hãy xem hướng dẫn đóng góp của dự án để nắm các quy ước và bước kiểm tra. Hãy tuân thủ bộ quy tắc ứng xử và báo cáo vấn đề bảo mật theo quy trình trong SECURITY.md thay vì tạo issue công khai.
Kết luận
Whirl cung cấp một nền tảng khởi đầu giàu tính năng cho không gian làm việc trò chuyện AI tự lưu trữ, kết hợp giao diện Next.js với backend Convex, xác thực Clerk và quyền truy cập model qua OpenRouter. Hãy bắt đầu với ba dịch vụ bắt buộc, xác minh trò chuyện cục bộ tại localhost:3000, sau đó bật tính năng tìm kiếm, bộ nhớ, phân tích, thanh toán và các tích hợp khác tùy theo nhu cầu triển khai của bạn.