Skip to content

_BUILD_GUIDE.md

Latest commit

 

History

History
185 lines (143 loc) · 11.4 KB

_BUILD_GUIDE.md

File metadata and controls

185 lines (143 loc) · 11.4 KB
Raw

BUILD GUIDE — Understand Anything LLM

Tài liệu này để bất kỳ phiên Claude mới nào tiếp tục dự án mà KHÔNG cần context của phiên cũ. Đọc file này + index.html là đủ để làm tiếp paper 07→13 với đúng phong cách, không giảm chất lượng.

1. Dự án là gì

Website docs kiểu GitBook tên Understand Anything LLM, giải thích cực dễ hiểu, tiếng Việt, cho người mới về 13 paper nền tảng LLM nằm trong Papers/docs/. Mỗi paper được chia thành nhiều trang nhỏ (ELI5), nhiều ví dụ đời thường, sơ đồ SVG tự vẽ + ảnh gốc trích từ PDF.

Toàn bộ website là MỘT file index.html (SPA tự viết: HTML + CSS + JS, không framework, không build step). Mở bằng trình duyệt là chạy (file://, không cần server).

Yêu cầu phong cách (bắt buộc giữ nguyên):

  • Tiếng Việt, giọng ELI5, ưu tiên trực giác hơn toán. Thuật ngữ kỹ thuật giữ tiếng Anh.
  • Mỗi khái niệm khó → kèm 1 ví dụ đời thường (box analogy).
  • Mỗi paper: trang đầu có TL;DR, trang cuối có glossary + "Đọc gì tiếp theo" (nối sang paper khác trong lộ trình).
  • Nối mạch giữa các paper (vd residual của Paper 03 xuất hiện lại ở Paper 01/06).

2. Đường dẫn (QUAN TRỌNG)

Thứ Host path (dùng cho Read/Write/Edit và xem ảnh)
File chính (canonical, sửa trực tiếp ở đây) /Users/haiquan/Downloads/Papers/understandanythingllm/index.html
Thư mục ảnh /Users/haiquan/Downloads/Papers/understandanythingllm/assets/
PDF nguồn /Users/haiquan/Downloads/Papers/docs/0X_*.pdf
Build guide này /Users/haiquan/Downloads/Papers/understandanythingllm/_BUILD_GUIDE.md

Lưu ý phiên mới:

  • Thư mục outputs scratch bị xoá giữa các phiên → làm việc trực tiếp trên file canonical trong Papers/understandanythingllm/ (đây là folder user mount, có quyền read+write). Không cần copy qua scratch.
  • Bash chạy trong VM với path khác: prefix /sessions/<TÊN-PHIÊN-MỚI>/mnt/.... Đầu phiên, xem mục "Shell access" trong system prompt để biết mapping của Papers/. Ví dụ phiên cũ: /Users/haiquan/Downloads/Papers ↔ /sessions/<name>/mnt/Papers.
  • Read tool chạy trên HOST → xem ảnh phải dùng host path (/Users/haiquan/Downloads/...), KHÔNG dùng /sessions/... (sẽ lỗi).

3. Kiến trúc file index.html

Thứ tự trong file:

  1. <head> + toàn bộ CSS (biến màu, layout, dark mode, callout, figure, table, pager...). Không cần sửa.
  2. <body>: sidebar (#sidebar), topbar mobile, #content, #toc.
  3. <div id="pages" style="display:none"> ... </div> — chứa tất cả nội dung trang dưới dạng <div id="page-XXX">...</div>. Router JS show/hide theo location.hash.
  4. <script>: mảng NAV (cấu trúc sidebar) + ORDER (tự sinh, cho nút prev/next) + routing/search/theme/TOC.

Cơ chế routing

  • Mỗi trang = <div id="page-XXX">. Link #XXX → JS hiện đúng div đó.
  • Thứ tự trang trong file KHÔNG quan trọng (router tìm theo id). Pager prev/next tự sinh từ NAV.

4. Quy ước đặt tên

ID trang: p<số>-<slug>, ví dụ p7-overview, p7-glossary.

Prefix ảnh theo paper (để assets gọn, không đụng nhau):

Paper Prefix Paper Prefix
01 Attention fig1_, fig2_ 08 Chain-of-Thought cot_
02 GPT-3 g3_ 09 InstructGPT igpt_
03 ResNet rn_ 10 Constitutional AI cai_
04 Scaling Laws sl_ 11 LoRA lora_
05 Chinchilla cc_ 12 QLoRA qlora_
06 FFN KV kv_ 13 GPTQ gptq_
07 ROME rome_

Ảnh tham chiếu trong HTML bằng path tương đối: <img src="assets/rome_fig1_xxx.png">.

5. Các class CSS có sẵn (dùng lại, đừng tự thêm CSS)

  • Callout box: <div class="box note|tip|analogy|warn"><div class="bx-t">🔑 Tiêu đề</div><p>...</p></div>
    • tip (xanh lá, dùng cho TL;DR / điểm chốt), note (xanh dương, ghi chú/câu hỏi dẫn đường), analogy (tím, ví dụ đời thường), warn (cam, cảnh báo/hạn chế).
  • Eyebrow + tiêu đề trang: <span class="eyebrow">Paper 0X · Mục</span> + <h1> + <p class="lead">...</p>.
  • Meta đầu trang overview: <div class="page-meta"><span><b>Tác giả:</b> ...</span>...</div>.
  • Công thức: <div class="formula">... <div class="small">chú thích</div></div>.
  • Bảng: <div class="tbl"><table>...</table></div>. Ô nhấn mạnh: <td class="hl">.
  • Hình ảnh: <figure><img src="assets/..." alt="..." [style="max-width:520px"]><figcaption>Hình X (trích từ paper gốc). ...</figcaption></figure>.
  • Sơ đồ SVG tự vẽ: <figure><div class="svgwrap"><svg viewBox="0 0 720 H" ...>...</svg></div><figcaption>...</figcaption></figure>. Dùng biến màu CSS: var(--accent), var(--heading), var(--muted), var(--tip), var(--analogy-bg)... để tự hợp dark mode.

6. Khung chuẩn một trang (copy & sửa)

<!-- ===== P7 OVERVIEW ===== -->
<div id="page-p7-overview">
  <span class="eyebrow">Paper 07 · Tổng quan</span>
  <h1>Tên paper (tiếng Anh hoặc Việt-hoá)</h1>
  <p class="lead">1–3 câu mở: paper này giải quyết gì, vì sao đáng quan tâm.</p>
  <div class="page-meta">
    <span><b>Tác giả:</b> ...</span><span><b>Năm:</b> ...</span>
    <span><b>Độ khó:</b> ⭐⭐</span><span><b>Thời gian đọc:</b> ~N phút</span>
  </div>
  <div class="box tip"><div class="bx-t">⚡ TL;DR</div><p>...</p></div>
  <h2>Vì sao bài này quan trọng?</h2> ...
  <div class="box analogy"><div class="bx-t">🎯 Ví dụ: ...</div><p>...</p></div>
  <h2>Bạn sẽ học gì</h2><ol>...</ol>
</div>

Trang cuối luôn có: section "Toàn bộ paper trong N ý" (<ol>), 1 box analogy "Một phép so sánh cuối", "Bảng tra thuật ngữ" (tbl), "Đọc gì tiếp theo?" (nối sang paper khác), và box tip "🎓 Hoàn thành Paper 0X!".

7. QUY TRÌNH 4 BƯỚC mỗi paper

Bước 1 — Đọc paper

Read PDF Papers/docs/0X_*.pdf (dùng pages:"1-5" rồi đọc thêm phần kết quả/hạn chế). Nắm: vấn đề, ý tưởng cốt lõi, cơ chế, kết quả, hạn chế.

Bước 2 — Trích hình từ PDF (qua bash/python)

Cài 1 lần: pip install pymupdf --break-system-packages -q. Công thức:

import fitz; from PIL import Image
doc = fitz.open("<VM_PATH>/Papers/docs/0X_....pdf")
# render trang cần (index = số trang - 1) ở 3x
doc[PNO].get_pixmap(matrix=fitz.Matrix(3,3)).save("<VM_ASSETS>/xx_pPAGE.png")
# tạo thumbnail 1/3 để tìm toạ độ crop nhanh
im=Image.open("<VM_ASSETS>/xx_pPAGE.png"); im.resize((im.width//3,im.height//3)).save("<VM_ASSETS>/_t.png")
# crop: trang 3x có size 1836x2376; toạ độ crop nhân theo tỉ lệ từ thumbnail
Image.open("<VM_ASSETS>/xx_pPAGE.png").crop((L,T,R,B)).save("<VM_ASSETS>/xx_figN_name.png")
  • Xem để căn: Read ảnh bằng host path assets/...png. Xem thumbnail trước để ước toạ độ, crop, xem lại, chỉnh. Tiết kiệm context: hạn chế số vòng xem lại (ước toạ độ kỹ từ thumbnail trước khi crop; xem 1–2 lần là chốt).
  • Paper cho phép tái sử dụng hình cho mục đích học thuật → OK. Luôn ghi "(trích từ paper gốc)" trong figcaption.
  • Xoá file thô không dùng nếu được (xx_pPAGE.png, _t.png). Nếu rm báo "Operation not permitted" thì kệ — chỉ cần KHÔNG tham chiếu chúng và KHÔNG copy chúng vào deploy.

Bước 3 — Viết nội dung + cập nhật NAV

  1. NAV: trong index.html, đổi entry paper từ soon:true, children:[] → done:true, children:[ {id:"p7-overview",title:"..."}, ... ]. (Mẫu xem entry paper 01–06.)
  2. Thẻ trang chủ: đổi <a class="pcard soon" href="#soon"> của paper đó → <a class="pcard" href="#p7-overview"> (bỏ class soon, đổi href). Tìm bằng text 0X · trong khu card-grid.
  3. Chèn các trang: chèn các <div id="page-p7-..."> vào trong #pages. Hai anchor tiện dùng cho Edit:
    • Ngay sau dòng mở: <div id="pages" style="display:none"> (chèn batch đầu).
    • Trước comment <!-- ===== HOME ===== --> (chèn batch sau). Anchor này là duy nhất, luôn dùng được.
    • Viết 1 paper thường cần 2 lần Edit (mỗi lần 3–4 trang) để khối không quá lớn.

Bước 4 — Kiểm tra & "deploy"

Vì sửa trực tiếp file canonical nên KHÔNG cần copy. Chỉ cần kiểm tra rồi present_files.

cd <VM>/Papers/understandanythingllm
# 1. page divs khớp nav ids?
grep -o 'id="page-p7-[a-z]*"' index.html | sed 's/id="page-//;s/"//' | sort
grep -o '{id:"p7-[a-z]*"' index.html | sed 's/{id:"//;s/"//' | sort
# 2. div cân bằng?
echo "open $(grep -o '<div' index.html|wc -l) / close $(grep -o '</div>' index.html|wc -l)"
# 3. mọi ảnh tham chiếu đều tồn tại?
for f in $(grep -o 'assets/[a-z0-9_]*\.png' index.html|sort -u); do [ -f "$f" ]&&echo "OK $f"||echo "MISSING $f"; done

Tất cả OK → mcp__cowork__present_files với /Users/haiquan/Downloads/Papers/understandanythingllm/index.html.

Cuối phiên: cập nhật mục "Tiến độ" bên dưới trong chính file này (đánh dấu paper vừa xong).

8. Tiến độ

  • 01 — Attention Is All You Need (10 trang) — prefix fig1_/fig2_
  • 02 — GPT-3 Few-Shot Learners (9 trang) — g3_
  • 03 — ResNet (7 trang) — rn_
  • 04 — Scaling Laws / Kaplan (7 trang) — sl_
  • 05 — Chinchilla (6 trang) — cc_
  • 06 — FFN as Key-Value Memories (7 trang) — kv_
  • 07 — ROME: Locating & Editing Facts (7 trang) — rome_
  • 08 — Chain-of-Thought Prompting (7 trang) — cot_
  • 09 — InstructGPT (RLHF) (7 trang) — igpt_
  • 10 — Constitutional AI (6 trang) — cai_
  • 11 — LoRA (6 trang) — lora_
  • 12 — QLoRA (6 trang) — qlora_ (nối từ LoRA)
  • 13 — GPTQ (6 trang) — gptq_

🎉 HOÀN THÀNH TOÀN BỘ 13 PAPER.

  • 00 — Các khái niệm đầu tiên (mục nhập môn, 7 trang p0-*, toàn SVG tự vẽ, không ảnh) — group num:"00" đứng trước "Papers" trong NAV, card ở đầu home.

Gợi ý độ dài: 6–8 trang/paper. Luôn có overview (TL;DR) + glossary (cuối).

9. Gotchas (lỗi đã gặp)

  • Read ảnh phải dùng host path, không phải /sessions/... (Read chạy trên host).
  • Crop hay lệch: luôn render 3x → tạo thumbnail 1/3 → ước toạ độ → crop → xem host path → chỉnh. Trục/nhãn hay bị cắt; chừa lề.
  • Một số PNG thô không xoá được (giới hạn quyền mount) → vô hại, chỉ cần đừng tham chiếu. Trong assets/ hiện có page3_full.png, page4_full.png thừa từ Paper 01 — bỏ qua.
  • Đừng tự thêm CSS mới — tái dùng class có sẵn để đồng nhất giao diện & dark mode.
  • Chèn HTML: dùng Edit với anchor <!-- ===== HOME ===== --> (duy nhất). Kiểm tra div cân bằng sau mỗi paper.
  • Tiết kiệm context: mỗi paper chỉ đọc trang PDF cần thiết, hạn chế vòng xem-lại crop. Một paper ≈ một phiên là thoải mái.