TinyVietLM

TinyVietLM is a project to build a small Vietnamese decoder-only language model from scratch with PyTorch. The repository currently includes the reproducible foundation, corpus preparation pipeline, and Byte-Level BPE tokenizer tooling. No production corpus has been approved and no language model has been trained. The local viwiki cleaner-v3 pilot is byte-reproducible, produced 6,355 accepted records, and passed audit schema 3. It is still not eligible for training because manual corpus review and production use remain unapproved.

Project pause status

Trạng thái: tạm dừng chủ động từ ngày 2026-09-09. Không có tiến trình TinyVietLM nào đang chạy và không cần chạy lại cleaner hoặc automated audit khi tiếp tục.

Mốc an toàn tại thời điểm dừng:

• Corpus cleaner-v3 có 6.355 record được chấp nhận từ 20.000 input record.
• Human review đã hoàn tất 1/200 record; còn 199 record pending.
• Ollama AI pre-screen đã lưu 4/200 suggestion trong artifact local hiện có.
• Gemini chưa được gọi, chưa gửi record nào và chưa tạo artifact Gemini.
• Tokenizer 16K và language model chưa được train hoặc phê duyệt để train.
• Không có manual-review approval hoặc pilot-tokenizer authorization thật.

Các artifact đang làm được giữ nguyên trong data/ và runs/. Không sửa tay, di chuyển hoặc xóa chúng trong thời gian tạm dừng. Khi tiếp tục, trước tiên chạy:

cd /Users/linhto/Developer/TinyVietLM
git status --short
.venv/bin/ruff check .
.venv/bin/python -m pytest

Sau đó chọn một trong hai hướng: tiếp tục human review bằng lệnh có --resume, hoặc chạy pilot Gemini tối đa 5 record theo hướng dẫn bên dưới. Không chạy đủ 200 record bằng cloud trước khi pilot và calibration được đánh giá.

Current scope

• Typed and validated YAML model configurations.
• Portable CPU, Apple MPS, and CUDA device selection.
• Reproducible random seed setup.
• A forward/backward environment check.
• Strict UTF-8 JSONL document validation.
• Provider-neutral source registry separating authority, rights, and access.
• Multi-source corpus audit and production tokenizer release gate.
• Streaming, checksum-verified dump acquisition and Wikipedia XML extraction.
• Bounded, deterministic SHA-256 top-K pilot extraction with artifact metadata.
• Deterministic normalization, exact deduplication, and document-level splits.
• Dataset manifests containing statistics and SHA-256 checksums.
• Streaming corpus audit and deterministic manual-review sampling.
• Optional Ollama/Gemini AI pre-screen with local verification and human gates.
• Byte-Level BPE training and held-out tokenizer benchmarks.
• Unit tests, linting, and CPU CI.

Requirements

• Python 3.10 or newer.
• Apple Silicon with MPS, an NVIDIA CUDA environment, or a CPU.

Setup

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Verification

python scripts/check_environment.py
ruff check .
pytest

Use an explicit CPU check when validating portability:

python scripts/check_environment.py --device cpu

Corpus preparation

Source acquisition

viwiki is approved only for the bounded local pilot and has a verified dated dump and publisher checksum. vbpl remains metadata-only because no documented bulk access path or redistribution decision has been approved. Verify the small Wikimedia checksum list without downloading the dump again:

python scripts/fetch_viwiki_dump.py \
  --config configs/sources/viwiki.yaml \
  --check-only

Khánh Linh approved the viwiki source-config hash recorded in docs/approvals/viwiki-20260201-pilot.md for a local 20,000-document pilot. Public redistribution and production training remain unapproved. The pinned dump has already been acquired, so extract it without downloading it again:

python scripts/extract_viwiki.py \
  --config configs/sources/viwiki.yaml \
  --pilot-config configs/pilot_viwiki.yaml \
  --input data/raw/viwiki/20260201/viwiki-20260201-pages-articles-multistream.xml.bz2 \
  --output data/interim/viwiki/20260201/pilot-20000.jsonl

Downloads use a temporary .part file and verify the checksum list published by Wikimedia before replacing any existing artifact. Extraction keeps main-namespace non-redirect pages and writes one provenance-bearing document per page. Pilot mode selects the globally lowest deterministic hash ranks in one streaming pass, keeps only the bounded top-K raw candidates in temporary SQLite, cleans only the final sample, and writes a checksum-bearing .metadata.json sidecar. A selected document whose body cleans to empty retains a title-only provenance fallback so selection remains stable; pipeline 1.2 deterministically rejects that fallback as insufficient prose. Omitting --pilot-config preserves the existing full-extraction behavior. Cleaner version wikitext-clean-v3 handles malformed references, comments, controlled HTML/extension tags, nested templates, image links, tables, Wiki headings, and residual structural markers with bounded deterministic passes. Its version is recorded in pilot metadata.

Prepare and audit

Each input line must be a JSON object with four required fields:

{
  "id": "doc-1",
  "source": "source-name",
  "license": "license-id",
  "text": "Nội dung tiếng Việt..."
}

Optional title and url fields may be strings or null. Input must already be extracted plain text; acquisition and source-specific markup removal are outside the core pipeline.

python scripts/prepare_corpus.py \
  --config configs/data.yaml \
  --input data/raw/documents.jsonl \
  --output-dir data/processed

The output directory contains train.jsonl, validation.jsonl, rejected.jsonl, and manifest.json. Existing artifacts are protected unless --force is explicitly supplied. Split hashing uses an independent domain from upstream sampling and the manifest records sha256-document-split-v1.

Run the automated gate and create a deterministic sample for human review:

python scripts/audit_corpus.py \
  --dataset-dir data/processed \
  --source-config configs/sources/viwiki.yaml \
  --output data/processed/quality-report.json \
  --sample-output data/processed/manual-review-sample.jsonl \
  --sample-size 100 \
  --seed 2026

The audit exits non-zero while any represented source is still a candidate or if checksums, schema, provenance, Unicode, HTML, or Wiki-markup gates fail. A passing automated report does not replace manual review. Repeat --source-config for each source actually present in a future mixed corpus; unregistered and unused entries are rejected.

Do not pass configs/sources/vbpl.yaml for acquisition or for a corpus that does not contain VBPL records. It is a governance record, not an implemented scraper.

Human-in-the-loop corpus review

Phần này ghi lại đầy đủ quy trình kiểm định thủ công đang được sử dụng cho Milestone 2F–2G. Đây là Human-in-the-loop Manual Data Quality Review, không phải huấn luyện tokenizer hoặc language model.

Automated audit kiểm tra toàn bộ corpus bằng các quy tắc xác định trước. Human review kiểm tra những yếu tố khó xác nhận hoàn toàn bằng code như chất lượng tiếng Việt, nội dung bị cắt, tiêu đề không khớp, thông tin cá nhân, lỗi ngữ nghĩa và near-duplicate. Automated audit đã pass không thay thế human review.

Approval boundary

Luồng kiểm định và phát hành là:

cleaner-v3-codecheck-5 corpus
              |
              v
automated audit: passed
              |
              v
200-record manual-review sample
              |
              v
working human decisions --resume--> final reviewed decisions
              |
              v
manual-review approval + separate pilot-tokenizer authorization
              |
              v
cryptographic validator
              |
              v
16K tokenizer training gate

Không được bỏ qua bước con người bằng cách tự động điền reviewer, timestamp hoặc approval. Flag cũ --manual-review-approved không thể mở khóa tokenizer 16K. Language-model training luôn nằm ngoài phạm vi milestone này.

Authoritative artifacts

Chỉ sử dụng bộ cleaner-v3-codecheck-5:

data/processed/viwiki-20260201-pilot-cleaner-v3-codecheck-5/
runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/

Không review các file trong:

runs/data/viwiki-20260201-pilot-cleaner-v2/

Cleaner-v2 là bằng chứng cũ đã bị supersede. Việc file cleaner-v2 đang được mở trong IDE không làm thay đổi dữ liệu mà Terminal đang review, nhưng không được dùng nội dung đó làm quyết định cho cleaner-v3.

Các artifact human review chính:

Vai trò	Đường dẫn	Có được sửa trực tiếp?
Mẫu cần đọc	runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review.jsonl	Không
Decision template	runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions.jsonl	Không
Kết quả đang làm	runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions-working.jsonl	Chỉ qua công cụ review
Kết quả hoàn tất	runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions-reviewed.jsonl	Không ghi đè
Approval template	runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-approval.template.json	Sao chép, không dùng làm approval thật
Approval thật	runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-approval.json	Chỉ người phê duyệt tạo

Input sample và decision template là immutable. Công cụ dùng temporary file và atomic replace để việc thoát hoặc lỗi giữa chừng không làm hỏng working file. Final reviewed file không được tạo khi còn record pending và không bị ghi đè nếu đã tồn tại.

Current corpus and review snapshot

Snapshot dưới đây được ghi nhận ngày 2026-09-08. Dùng các lệnh ở phần kiểm tra tiến độ để lấy số mới nhất thay vì coi README là trạng thái động.

Metric	Giá trị
Input documents	20,000
Accepted documents	6,355
Train documents	6,210
Validation documents	145
Rejected documents	13,645
Manual-review sample	200
Sample train / validation	195 / 5
Human-reviewed	1
Accept	1
Needs remediation	0
Reject	0
Pending	199
Final reviewed artifact	Chưa có
Manual approval	Chưa có
Pilot-tokenizer authorization	not-approved
Tokenizer/model training	Chưa chạy

Working review SHA-256 tại snapshot này là 1cbd55c3f594335be290b6e0a75e0abe736bcdca02c1154d5d52adbac01fa6b7. Hash sẽ thay đổi sau mỗi record được lưu; đó là hành vi đúng.

Start or resume the review

Chạy từ repository root:

cd /Users/linhto/Developer/TinyVietLM

.venv/bin/python scripts/review_manual_sample.py \
  --sample runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review.jsonl \
  --template runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions.jsonl \
  --output runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions-working.jsonl \
  --final-output runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions-reviewed.jsonl \
  --reviewer "Khánh Linh" \
  --resume

--resume tiếp tục từ working file hiện tại và không xóa record đã lưu. Tên reviewer chỉ được ghi vào một record sau khi người dùng thực sự hoàn tất câu trả lời cho record đó.

Menu chính:

[r] review  [n] next  [b] back  [f] finalize  [q] quit

• r: đánh giá record đang hiển thị.
• n: chuyển sang record tiếp theo; lệnh này không tự bỏ qua record đã duyệt.
• b: quay lại record trước để xem hoặc sửa.
• f: tạo final reviewed file; chỉ hoạt động khi đủ 200 record.
• q: thoát an toàn; mỗi record hợp lệ đã được lưu ngay khi hoàn tất.

Một record chỉ được ghi sau khi toàn bộ câu hỏi của record đó hợp lệ. Nội dung đang nhập nhưng chưa đi qua trường notes chưa được lưu.

Review field reference

Tám trường checklist có cùng lựa chọn:

1 = pass
2 = fail
3 = uncertain

Trường	Điều cần xác nhận
metadata_valid	ID, source, license, split, URL và text hash đầy đủ, nhất quán
language_quality	Tiếng Việt rõ ràng; không có lỗi chính tả, lặp từ hoặc câu hỏng đáng kể
markup_clean	Không còn HTML, Wiki markup, template, bảng, ảnh hoặc comment syntax
title_content_match	Nội dung thực sự nói về chủ đề trong tiêu đề
truncation_ok	Mở đầu và kết thúc hoàn chỉnh, không bị cắt ngang
sensitive_pii_absent	Không có địa chỉ riêng, số điện thoại, email, giấy tờ hoặc dữ liệu cá nhân nhạy cảm
attribution_checked	Source, URL, snapshot và license giữ đủ provenance cần thiết
topic_quality	Chủ đề hữu ích cho corpus, không phải quảng cáo, spam hoặc văn bản nhiễu

Tên người, tác giả hoặc nhà khoa học xuất hiện trong bối cảnh bách khoa không tự động được coi là sensitive PII. Tên Latin, tiếng Nhật, tiếng Anh chuyên ngành và tên riêng cũng không tự động làm language_quality fail nếu phần tiếng Việt vẫn mạch lạc.

duplicate_status:

1 = unique
2 = near_duplicate
3 = duplicate
4 = uncertain

Automated audit đã loại exact duplicate nhưng không chứng minh semantic near-duplicate. Nếu phát hiện hoặc không chắc, phải chọn đúng trạng thái và ghi lý do; không mặc định unique chỉ vì automated_flags rỗng.

severity:

1 = none
2 = minor
3 = major
4 = blocker

• none: không tìm thấy vấn đề.
• minor: lỗi nhỏ nhưng có thật, ví dụ một số lỗi chính tả hoặc lặp từ.
• major: chất lượng hoặc nội dung có vấn đề đáng kể.
• blocker: không được sử dụng record trước khi giải quyết.

decision:

1 = accept
2 = reject
3 = needs_remediation

• accept: record đạt các checklist.
• reject: record không nên giữ trong corpus.
• needs_remediation: record có ích nhưng cần sửa, làm sạch hoặc xem xét lại.

finding_codes là danh sách mã ngắn, phân cách bằng dấu phẩy, ví dụ:

language_typo,repeated_phrase
markup_residue,truncated_text
possible_pii,near_duplicate

Không nhập câu giải thích dài vào finding_codes. Nội dung giải thích phải đặt trong notes, ví dụ:

finding_codes: language_typo,repeated_phrase
notes: Có lỗi chính tả “tiệu diệt” và cụm từ bị lặp “khiến cho cho”.

Nhập - để xóa giá trị hiện có khỏi finding_codes hoặc notes. Nhấn Enter để giữ giá trị đang hiển thị.

Decision consistency rules

notes bắt buộc nếu xảy ra ít nhất một điều sau:

• checklist là fail hoặc uncertain;
• duplicate status không phải unique;
• severity không phải none;
• decision là reject hoặc needs_remediation;
• finding_codes không rỗng.

Một approval trạng thái approved không được chứa record reject hoặc needs_remediation, checklist fail/uncertain, duplicate uncertainty hoặc severity blocker. Không nên đổi một phát hiện thật thành pass chỉ để vượt gate; phải remediation dữ liệu rồi tạo artifact mới có provenance rõ ràng.

Fast path for a clean record

Sau khi thực sự đọc và xác nhận một record hoàn toàn sạch, chuỗi lựa chọn thường là:

metadata_valid                 1
language_quality               1
markup_clean                   1
title_content_match            1
truncation_ok                  1
sensitive_pii_absent           1
attribution_checked            1
topic_quality                  1
duplicate_status               1
severity                       1 hoặc Enter nếu đang là none
decision                       1
finding_codes                  Enter
notes                          Enter

Đây không phải mẫu trả lời dùng cho tất cả 200 record. Mỗi record phải được đọc riêng. Nếu có lỗi, chọn trường tương ứng, severity, decision, finding codes và notes một cách trung thực.

Correct a mistaken input

Nếu nhập câu giải thích dài nhầm vào finding_codes và vẫn đang ở prompt notes, để notes trống rồi nhấn Enter. Validator của record sẽ từ chối lưu vì finding codes cần notes, sau đó quay lại menu để nhập lại đúng.

Nếu record đã được lưu:

1. Dùng b để quay lại record đó.
2. Chọn r.
3. Nhấn Enter để giữ các trường đúng.
4. Nhập mã ngắn đúng tại finding_codes.
5. Nhập giải thích đầy đủ tại notes.

Working file được cập nhật atomically sau khi record hợp lệ nên record trước đó không mất khi một record mới nhập sai.

Check current progress

Đếm quyết định đã lưu:

jq -r '.decision' \
  runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions-working.jsonl \
  | sort | uniq -c

Xem các record đã hoàn thành:

jq -c 'select(.decision != "pending") | {
  sample_index,id,split,decision,severity,reviewer,reviewed_at,
  finding_codes,notes
}' runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions-working.jsonl

Kiểm tra working-file hash:

shasum -a 256 \
  runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions-working.jsonl

Pause, resume, and finalize

Nhập q ở menu để dừng. Chạy lại nguyên lệnh có --resume để tiếp tục. Không cần chạy lại cleaner, corpus preparation hoặc automated audit.

Sau khi đủ 200 record, nhập f. Công cụ chỉ tạo:

runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions-reviewed.jsonl

nếu không còn trường pending. File final không được ghi đè. Nếu cần thay đổi sau finalization, phải giữ artifact cũ và tạo một revision/run ID mới thay vì dùng --force.

Create the human approval record

Final reviewed decisions không tự động mở khóa tokenizer. Người phê duyệt phải đưa ra hai quyết định tách biệt:

1. manual_review_decision: approved, needs-remediation, hoặc rejected.
2. tokenizer_training_authorization: approved-for-pilot-tokenizer hoặc not-approved.

Lấy hash và số lượng thực tế:

shasum -a 256 \
  runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions-reviewed.jsonl

jq -r '.decision' \
  runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions-reviewed.jsonl \
  | sort | uniq -c

Sau đó người phê duyệt có thể sao chép template:

cp \
  runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-approval.template.json \
  runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-approval.json

Người phê duyệt phải tự điền reviewer, RFC3339 timestamp có timezone, counts, final-decisions SHA-256, quyết định, authorization và notes. Không được dùng template còn pending như approval thật.

SHA-256 phát hiện artifact bị sửa sau approval nhưng không phải chữ ký số và không tự chứng minh danh tính reviewer. Quyền truy cập repository và signed Git commit, nếu được yêu cầu sau này, là các governance control riêng.

Validate the completed review

.venv/bin/python scripts/validate_manual_review.py \
  --sample runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review.jsonl \
  --decisions runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions-reviewed.jsonl \
  --audit runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/audit.json \
  --manifest data/processed/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manifest.json \
  --approval runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-approval.json

Exit codes:

Exit code	Ý nghĩa
0	Review, hashes và approved-for-pilot-tokenizer đều hợp lệ
1	Artifact malformed, mâu thuẫn, sai schema hoặc sai SHA-256
2	Còn pending, cần remediation, bị reject hoặc chưa cấp quyền tokenizer

Validator kiểm tra số record, ID/index uniqueness, thứ tự, split, text hash, Unicode NFC, enum, reviewer, timestamp, notes, decision consistency và SHA-256 của sample, decisions, audit, manifest, train và validation.

AI pre-screen versus official human review

AI pre-screen tạo suggestion table theo đúng tám checklist, duplicate status, severity, decision, finding codes và notes của human review. Kết quả được lưu riêng, luôn có non_authoritative: true và không chứa reviewer hoặc reviewed_at. Nó không thể được dùng trực tiếp làm final decisions hay approval.

Công cụ hỗ trợ hai provider mà không thêm Python dependency: Ollama local qua http://127.0.0.1:11434 và Gemini API cloud tùy chọn. Ollama từ chối endpoint ngoài localhost. Gemini chỉ dùng hostname cố định của Google, đọc credential từ GEMINI_API_KEY, yêu cầu --allow-cloud-upload và một --limit rõ ràng trước khi gửi dữ liệu.

Cả hai provider dùng structured output theo JSON Schema. Validator sau inference tiếp tục kiểm tra enum, decision consistency, Unicode và confidence. Với Gemini, văn bản được chia thành các segment tối đa 160 ký tự; model chỉ trả segment_id và máy local lấy nguyên văn segment làm evidence. Text luôn được coi là untrusted data và prompt yêu cầu không làm theo chỉ dẫn nằm trong corpus.

Lớp deterministic bổ sung dò từ/cụm từ bị lặp và tìm lexical near-duplicate candidate trong sample. Cảnh báo deterministic được lưu rõ trong artifact và có thể buộc một đề xuất LLM quá lạc quan thành needs_remediation; không có silent override. Context tự chọn 4K/8K/16K/32K theo độ dài. Nếu 32K không đủ, công cụ fail thay vì âm thầm cắt text.

Kiểm tra Ollama và model local:

ollama --version
ollama list

Tạo hoặc tiếp tục AI pre-screen local:

.venv/bin/python scripts/prescreen_manual_sample.py \
  --provider ollama \
  --sample runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review.jsonl \
  --output runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/ai-prescreen.jsonl \
  --model qwen2.5:7b \
  --resume

--resume kiểm tra sample hash, prompt hash, model và thứ tự trước khi tiếp tục. Mỗi suggestion hợp lệ được ghi atomically ngay sau inference. Có thể nhấn Ctrl+C; các dòng đã hoàn thành vẫn được giữ. Dùng --max-records 2 để smoke test trước khi chạy toàn bộ. Mặc định không tự retry một kết quả lỗi để tránh lặp lại inference dài; xử lý nguyên nhân rồi chạy lại bằng --resume.

Gemini cloud pilot

Free-tier Gemini có thể dùng input/output để cải thiện sản phẩm và có thể có human reviewer của nhà cung cấp. Chỉ dùng luồng này cho dữ liệu công khai đã được kiểm tra; không gửi dữ liệu bí mật, riêng tư hoặc nhạy cảm. Gemini request không chứa reviewer, đường dẫn local, Git metadata hoặc biến môi trường.

Nhập API key vào session hiện tại mà không ghi vào repository hoặc shell history:

read -s GEMINI_API_KEY
export GEMINI_API_KEY

Chạy pilot tối đa 5 record vào artifact riêng, không ghi đè Ollama artifact:

.venv/bin/python scripts/prescreen_manual_sample.py \
  --provider gemini \
  --model gemini-2.5-flash \
  --sample runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review.jsonl \
  --output runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/ai-prescreen-gemini-v1.jsonl \
  --limit 5 \
  --allow-cloud-upload \
  --resume

Không bỏ --limit khi dùng Gemini. Nếu cần retry tạm thời cho HTTP 429, timeout hoặc lỗi 5xx, thêm --retries 2; lỗi authentication và output sai schema không được retry. Sau khi hoàn tất, xóa credential khỏi session:

unset GEMINI_API_KEY

Unit test dùng response giả và không gọi Internet. Chưa có Gemini request thật nào được chạy trong repository này. Phải chạy pilot rồi đo p50/p95 latency và so sánh với human labels trước khi quyết định mở rộng.

Xem kết quả AI:

jq -c '{sample_index,id,decision,severity,confidence,
  finding_codes,evidence,human_attention_required}' \
  runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/ai-prescreen.jsonl

Để hiển thị AI suggestion trong công cụ human review, thêm tham số:

.venv/bin/python scripts/review_manual_sample.py \
  --sample runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review.jsonl \
  --template runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions.jsonl \
  --output runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions-working.jsonl \
  --final-output runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions-reviewed.jsonl \
  --ai-prescreen runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/ai-prescreen.jsonl \
  --reviewer "Khánh Linh" \
  --resume

Menu sẽ có [a] confirm AI khi record tương ứng đã có suggestion. Người dùng phải tự đọc TEXT và suggestion, sau đó nhập chính xác XAC_NHAN. Chỉ lúc đó công cụ mới dùng tên reviewer và timestamp thật để ghi human decision. Không có chế độ batch accept. Nếu AI sai, chọn r và nhập đánh giá thủ công như trước.

Đo agreement trên những record đã được con người hoàn tất:

.venv/bin/python scripts/compare_ai_human_review.py \
  --sample runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review.jsonl \
  --ai-prescreen runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/ai-prescreen.jsonl \
  --human-decisions runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review-decisions-working.jsonl

Snapshot 2026-09-08: Ollama artifact có 4/200 suggestions. AI trùng 11/11 field trên human record duy nhất đã hoàn tất, nhưng cỡ mẫu 1 không đủ để tuyên bố độ chính xác. Phải có thêm nhãn người độc lập trước khi dùng agreement như một metric đáng tin cậy. SHA-256 của Ollama artifact 4 dòng là c712eafd306284548fd217c9c57885ed51ef65495cf95a9c21cbb25a531df8b4.

Local-only data

data/, root /runs/, tokenizer artifacts, checkpoints và environment .venv được loại khỏi Git. Vì vậy manual sample, working decisions, final decisions và approval thật không bị git add . đẩy lên GitHub. Source code, tests và tài liệu quy trình trong README vẫn được version-control bình thường.

Các nhóm không được đưa lên Git gồm:

.env, .env.*, .venv/
data/raw/, data/interim/, data/processed/
runs/, artifacts/, checkpoints/, models/, outputs/, logs/
*.pt, *.pth, *.ckpt, *.safetensors, *.onnx, *.gguf

Không dùng git add -f cho các đường dẫn trên. Có thể xác minh một artifact cụ thể trước khi commit bằng:

git check-ignore -v \
  runs/data/viwiki-20260201-pilot-cleaner-v3-codecheck-5/manual-review.jsonl
git status --short

Các file source trong src/, CLI trong scripts/, test trong tests/, cấu hình không chứa secret và tài liệu trong docs/ là code dự án, nên vẫn được đưa lên Git sau khi review. Không commit hoặc push chỉ vì dự án được đánh dấu tạm dừng; việc commit/push là một bước riêng do người dùng chủ động thực hiện.

Tokenizer

Train only from the manifest-verified train split:

python scripts/train_tokenizer.py \
  --config configs/tokenizer.yaml \
  --train-data data/processed/train.jsonl \
  --dataset-manifest data/processed/manifest.json \
  --output-dir artifacts/tokenizer \
  --source-config configs/sources/viwiki.yaml \
  --quality-report data/processed/quality-report.json \
  --manual-review-sample data/processed/manual-review-sample.jsonl \
  --manual-review-decisions data/processed/manual-review-decisions-reviewed.jsonl \
  --manual-review-approval data/processed/manual-review-approval.json

python scripts/benchmark_tokenizer.py \
  --tokenizer artifacts/tokenizer/tokenizer.json \
  --input data/processed/validation.jsonl \
  --output artifacts/tokenizer/benchmark.json

The 16K training command rejects a candidate source, a failed or mismatched audit, an incomplete multi-source registry, a mismatched dataset manifest, and missing or tampered human-review evidence. A legacy --manual-review-approved boolean cannot authorize training. The reviewed decisions and separate pilot-tokenizer approval must bind the sample, audit, manifest, train, and validation files by SHA-256. Repeat --source-config for every corpus source. data_smoke.yaml and tokenizer_smoke.yaml are for the synthetic test corpus. The production configs target a 16,384-token vocabulary and must not be used to claim a production artifact until an approved corpus is available.

Raw data, processed data, tokenizer artifacts, checkpoints, and experiment runs are intentionally excluded from Git.

Project structure

configs/             Source, data, tokenizer, smoke, and model configurations
docs/                Architecture and experiment records
scripts/             Environment, corpus, tokenizer, and benchmark CLIs
src/tinyvietlm/      Installable Python package
tests/               Hardware-independent unit tests

Roadmap

1. Resolve rights and bulk-access review for each proposed production source.
2. Complete the pending human review of the reproducible cleaner-v3 viwiki pilot.
3. Obtain separate approval before constructing a production corpus.
4. Train and freeze the production 16K tokenizer.
5. Implement and verify the decoder-only Transformer.
6. Run smoke training before full pretraining.
7. Evaluate, perform SFT, optimize inference, and deploy.

See the architecture and experiment protocol for project boundaries.