TL;DR

ziwei-doushu là engine an sao Tử Vi Đẩu Số mã nguồn mở do tác giả Renhuai123 phát hành trên GitHub. Repo dựa trên hệ thống Thiên Kỷ (天纪) của Ni Haixia, bundle 3 thứ thường bị các platform bói toán thương mại giấu kín: thuật toán an sao đầy đủ, hệ tứ hóa (Hóa Lộc - Hóa Quyền - Hóa Khoa - Hóa Kỵ), và dataset 518,400 mẫu lá số. Stack Next.js 14 + TypeScript, license MIT cho code, dataset chỉ cần giữ attribution.

Vấn đề: thuật toán Tử Vi bị giấu sau paywall

Tử Vi Đẩu Số (紫微斗数, Ziwei Doushu) là hệ thống chiêm tinh truyền thống Trung Hoa, dùng 14 chính tinh cộng phụ tinh phân bố trên 12 cung để luận giải bản mệnh. Ở Việt Nam, người ta gọi nôm na là Tử Vi - cùng gốc nhưng khác biến thể.

Vấn đề cố hữu của domain này: hầu hết engine an sao đều đóng. App thương mại chỉ trả về kết quả luận đoán đã qua xử lý, không cho lập trình viên hay nhà nghiên cứu chạm vào pipeline thật sự. Muốn build tool riêng, build dataset cho AI, hay đơn giản kiểm tra một cách cục - bạn phải tự code lại từ đầu hoặc trả tiền cho API hộp đen.

Tác giả của ziwei-doushu chọn cách tiếp cận ngược: mở chính thuật toán ra, vì giá trị thực nằm ở chiều sâu luận giải và trải nghiệm, không phải ở việc dấu công thức an sao.

Có gì bên trong repo

Kiến trúc ziwei-doushu: cổ tịch, thuật toán an sao, tứ hóa, dataset 518K mẫu, 1100+ cách cục

Bốn lớp của engine: cổ tịch nguyên văn, thuật toán an sao và tứ hóa, dataset lá số, knowledge base cách cục.

Repo bundle bốn thành phần đan vào nhau:

  • Thuật toán an sao: toàn bộ pipeline từ tính cung, an chính tinh, phụ tinh đến gán dữ liệu hành can chi - viết bằng TypeScript, có thể import như module thuần.

  • Hệ tứ hóa: 4 chế biến quan trọng nhất của Tử Vi (Hóa Lộc, Hóa Quyền, Hóa Khoa, Hóa Kỵ) cùng cơ chế phi hóa giữa các cung.

  • Knowledge base cách cục: hơn 1,100 entry có cấu trúc về các cách (pattern) tổ hợp sao - dữ liệu khô đã được normalize, không phải plain text rời rạc.

  • Cổ tịch nguyên văn: Cốt Tủy Phú (骨髓赋), Tử Vi Đẩu Số Toàn Tập (紫微斗数全集) và các thư tịch khác thuộc public domain, đính kèm reader trên web.

Dataset 518,400 mẫu lá số

Phần dữ liệu là điểm khiến repo này đặc biệt thú vị với cộng đồng AI engineer. Tác giả tính sẵn 518,400 lá số phủ toàn bộ tổ hợp năm Can Chi - tháng - ngày - giờ - giới tính. Đây không phải mẫu sinh ngẫu nhiên, mà là từng combo trong không gian đầu vào hữu hạn của Tử Vi.

Hệ quả: có thể dùng dataset này cho ba việc rất khác nhau:

  • Fine-tune LLM để model học pattern an sao trực tiếp thay vì lý luận lại bằng code.

  • RAG / vector search để hệ thống tra cứu lá số tương đồng làm reference cho luận đoán.

  • Nghiên cứu học thuật về phân bố sao theo lịch, tần suất xuất hiện các cách cục - dạng phân tích thống kê hệ chiêm tinh trước giờ rất hiếm khi có dữ liệu đủ rộng.

Stack và cách chạy thử

Web app dùng Next.js 14 App Router, TypeScript, Tailwind CSS, Framer Motion, kèm lunar-javascript cho lịch âm. Không cố gắng kiến trúc cầu kỳ - phù hợp với người muốn fork về build product riêng.

git clone https://github.com/Renhuai123/ziwei-doushu.git
cd ziwei-doushu
npm install
cp .env.example .env.local
npm run dev

Tính năng web đã có sẵn: lưới 12 cung trực quan, hợp bàn (synastry) giữa hai lá số, AI interpretation, reader cổ tịch, hai chế độ sáng tối. Demo public tại wdyziweidoushu666.com (đã ICP filing cho thị trường Trung Quốc đại lục).

License và điều kiện dùng thương mại

Phần code license MIT - dùng thương mại tự do, fork tự do, không cần xin phép. Dataset 518K mẫu có ràng buộc nhẹ: nếu tích hợp vào product, cần để link attribution về repo GitHub gốc ở trang About hoặc footer. Cổ tịch là public domain, không có vấn đề gì.

Cấu trúc license này khá thân thiện cho startup tử vi và team build SaaS bói toán. Bạn không bị khoá vào API key của ai, không trả phí per-request, và toàn bộ data flow nằm trong tay bạn.

Khi nào nên dùng

Nên fork về khi:

  • Build app Tử Vi / Tử Vi Đẩu Số mà không muốn dành 3-6 tháng code lại pipeline an sao đầy lỗi vặt.

  • Cần dataset cho project AI domain divination - không nguồn nào khác phủ đủ tổ hợp đầu vào như thế này.

  • Là practitioner muốn truy cập cổ tịch nguyên văn cộng với KB cách cục có structure để cross-reference khi luận giải.

Một số điểm cần lưu ý: dataset có bias từ hệ phái Ni Haixia, không phải universal truth của tất cả trường phái Tử Vi. Repo cũng nói rõ là divination tool, không thay thế tư vấn y tế, tài chính hay pháp lý. Hợp lý cho người làm tool, không hợp cho người đi tìm lời tiên tri tuyệt đối.

Kết

ziwei-doushu là một trong số rất ít engine chiêm tinh truyền thống mở hoàn chỉnh cả thuật toán, dataset và corpus cổ tịch dưới license MIT. Với cộng đồng dev và AI engineer ở Việt Nam quan tâm domain Tử Vi, đây có lẽ là điểm khởi đầu sạch nhất để build tool hoặc nghiên cứu nghiêm túc via Renhuai123/ziwei-doushu.