Xây dựng hệ thống tài liệu cho dự án

3.4. Xây dựng hệ thống tài liệu cho dự án#

3.4.1. Triết lý Tài liệu Hiện đại: “Docs as Code”#

Trước khi đi vào chi tiết, hãy thống nhất về triết lý:

  • Docs as Code (Tài liệu như Mã nguồn): Tài liệu nên được lưu trữ cùng với mã nguồn trong Git. Nó phải trải qua cùng một quy trình review (Pull Request) và được phiên bản hóa như code. Điều này đảm bảo tài liệu luôn cập nhật và chính xác.

  • Tự động hóa: Tự động tạo tài liệu từ mã nguồn bất cứ khi nào có thể (ví dụ: tạo tài liệu API từ OpenAPI specs, tạo biểu đồ quan hệ thực thể từ code dbt).

  • Hướng đến đối tượng: Mỗi tài liệu nên được viết cho một đối tượng cụ thể (Developer, Data Scientist, DevOps, Business User).

  • “Living Document”: Tài liệu không phải là thứ viết một lần rồi bỏ. Nó phải được cập nhật liên tục cùng với sự phát triển của dự án.

3.4.2. ✨ Thư mục đặc biệt: .ai-context (Hỗ trợ AI viết code)#

Đây là một ý tưởng hiện đại và rất mạnh mẽ. Để AI (như tôi) có thể hỗ trợ bạn viết code, fix bug, hoặc thiết kế giải pháp hiệu quả, nó cần bối cảnh (context). Bạn nên tạo một thư mục .ai-context ở thư mục gốc của mỗi repo con. Khi bạn cần sự trợ giúp, bạn có thể cung cấp nội dung của thư mục này cho AI.

Thư mục .ai-context nên chứa:

  • architecture.md: Một file Markdown mô tả kiến trúc tổng thể của repo này và mối quan hệ của nó với các repo khác. Nên nhúng sơ đồ (Mermaid.js là lựa chọn tuyệt vời vì nó là text) hoặc link đến file .drawio.

  • adr/ (Architectural Decision Records): Một thư mục chứa các file ghi lại những quyết định kiến trúc quan trọng. Mỗi file là một quyết định. Ví dụ: 001-chon-feast-cho-feature-store.md.

    • Template cho một ADR: Status (Proposed, Accepted, Deprecated), Context (Vấn đề cần giải quyết), Decision (Quyết định được đưa ra), Consequences (Hệ quả của quyết định).

  • schemas/: Thư mục chứa định nghĩa cấu trúc dữ liệu (data contracts) dưới dạng code.

    • Pydantic Models (.py): Cho các object Python.

    • JSON Schema (.json): Cho các payload API hoặc cấu trúc dữ liệu JSON.

  • api_contracts/: (Chủ yếu cho repo ml-model-services) Chứa các file đặc tả API.

    • OpenAPI Specification (openapi.yaml): Định nghĩa tất cả endpoints, request/response bodies, authentication.

  • business_logic_overview.md: Giải thích bằng ngôn ngữ tự nhiên về logic nghiệp vụ cốt lõi mà repo này xử lý. Đây là phần cực kỳ quan trọng cho AI. Ví dụ: “Mô hình fraud detection này tính điểm rủi ro dựa trên 3 nhóm feature chính: tần suất giao dịch, giá trị giao dịch bất thường, và vị trí địa lý. Điểm > 0.8 được coi là rủi ro cao.”

  • examples/: Một thư mục chứa các file ví dụ về input và output.

    • sample_request.json: Một ví dụ về request body gửi đến API.

    • sample_response.json: Ví dụ về response tương ứng.

    • sample_feature_vector.csv: Ví dụ về một dòng dữ liệu training.

3.4.3. Phần A: Các loại tài liệu Bắt buộc cho Mọi Dự án Dữ liệu#

Bất kể quy mô hay loại dự án, mỗi repo con của bạn nên có ít nhất các tài liệu sau ở thư mục gốc:

  1. README.md:

    • Đây là “cửa chính” của repo.

    • Nội dung:

      • Tên dự án/repo và mô tả ngắn gọn (nó làm gì?).

      • Huy hiệu (badges) về trạng thái build, coverage (tích hợp từ CI/CD).

      • Quick Start: Các bước nhanh nhất để một developer có thể chạy được dự án trên máy local (clone, cài dependencies, chạy một lệnh chính).

      • Link đến các tài liệu quan trọng khác (kiến trúc, contributing, runbook).

  2. CONTRIBUTING.md:

    • Hướng dẫn cách đóng góp vào dự án.

    • Nội dung:

      • Quy trình Git Flow (cách tạo nhánh, đặt tên, tạo Pull Request).

      • Tiêu chuẩn code (coding standards), link đến linter config.

      • Hướng dẫn chạy tests.

      • Quy trình review code.

  3. CHANGELOG.md:

    • Ghi lại những thay đổi quan trọng qua các phiên bản.

    • Giúp mọi người biết có gì mới, sửa lỗi gì, thay đổi gì lớn.

    • Có thể được tạo tự động nếu bạn tuân thủ quy ước commit (ví dụ: Conventional Commits).

  4. Operations Handbook / Runbook (OPERATIONS.md hoặc trong wiki):

    • Hướng dẫn vận hành.

    • Nội dung:

      • Cách triển khai (deploy) phiên bản mới.

      • Cách rollback về phiên bản cũ.

      • Cách theo dõi (monitoring) hệ thống, link đến dashboards.

      • Các cảnh báo (alerts) phổ biến và cách xử lý.

      • Các sự cố thường gặp và cách khắc phục (troubleshooting).

3.4.4. Phần B: Tài liệu Chi tiết theo từng Module MLOps#

Dưới đây là các tài liệu đặc thù nên có trong từng repo con của bạn.

3.4.4.1. 1. Repo: feature-store-management#

  • Mục tiêu: Cung cấp một nguồn features đáng tin cậy, dễ khám phá và dễ sử dụng.

  • Đối tượng: Data Engineer, Data Scientist.

  • Tài liệu đặc thù:

    • README.md: Giải thích mục đích của Feature Store, cách cấu trúc repo, và link đến các hướng dẫn bên dưới.

    • Data Dictionary / Feature Catalog (trong docs/feature_catalog.md):

      • Đây là tài liệu quan trọng nhất. Nó nên được tạo tự động một phần từ các file định nghĩa feature.

      • Liệt kê tất cả FeatureView, FeatureService. Với mỗi feature: mô tả nghiệp vụ, kiểu dữ liệu, nguồn gốc, chủ sở hữu (owner), ví dụ giá trị.

    • Data Source Onboarding Guide (docs/onboarding_new_source.md):

      • Hướng dẫn từng bước cách thêm một nguồn dữ liệu mới (từ DWH, Kafka,…) vào hệ thống để tạo feature.

    • Feature Definition Handbook (docs/defining_features.md):

      • Quy tắc và hướng dẫn cách định nghĩa một FeatureView mới, quy ước đặt tên, cách viết transformation logic (dbt, Spark).

    • Feast Configuration Explained (docs/feast_config.md):

      • Giải thích các thiết lập trong feature_store.yaml (registry, provider, online/offline stores).

3.4.4.2. 2. Repo: ml-model-development#

  • Mục tiêu: Tái lập (reproducible) các quá trình huấn luyện và đánh giá mô hình.

  • Đối tượng: Data Scientist, ML Engineer.

  • Tài liệu đặc thù:

    • README.md: Giải thích cấu trúc thư mục (mỗi model một folder), cách sử dụng common_ml_utils, và quy trình phát triển model tổng thể.

    • Model Card (trong mỗi folder model, ví dụ models/fraud_detection_xgboost/MODEL_CARD.md):

      • Business Problem: Mô tả bài toán nghiệp vụ mà model giải quyết.

      • Model Architecture: Kiến trúc mô hình (ví dụ: XGBoost, ResNet50), tại sao chọn nó.

      • Data: Mô tả dữ liệu training/validation (link đến Feature Catalog).

      • Evaluation Metrics: Các chỉ số đánh giá (AUC, F1, MAE,…) và kết quả trên tập test.

      • Fairness & Bias: Phân tích về thiên vị (nếu có).

      • Usage: Hướng dẫn cách chạy train.py, evaluate.py.

    • Experiment Tracking Guide (docs/experiment_tracking.md):

      • Hướng dẫn cách sử dụng MLFlow Tracking: quy ước đặt tên experiment, các tags bắt buộc phải log, cách log params, metrics, artifacts.

3.4.4.3. 3. Repo: ml-model-services#

  • Mục tiêu: Cung cấp các API ổn định, hiệu năng cao và được tài liệu hóa tốt.

  • Đối tượng: ML Engineer, Software Engineer (sử dụng API).

  • Tài liệu đặc thù:

    • API Documentation (tự động tạo): Đây là tài liệu quan trọng nhất.

      • FastAPI có thể tự động tạo tài liệu OpenAPI (Swagger UI, ReDoc) từ code (Pydantic models, docstrings). Link đến /docs và /redoc của service phải được nêu bật trong README.md của từng service.

    • Service README (trong mỗi folder service, ví dụ services/fraud_detection_api/README.md):

      • Mô tả service làm gì.

      • Các biến môi trường cần thiết để chạy service.

      • Link đến API documentation.

      • Ví dụ về một request curl để test service.

    • Label Engine Rulebook (docs/label_engine_rules.md):

      • Giải thích cách Label Engine hoạt động, cách các quy tắc nghiệp vụ được áp dụng.

      • Hướng dẫn cho business users cách cập nhật các rules (nếu có giao diện hoặc file config).

    • Local Development Guide (docs/local_development.md):

      • Hướng dẫn cách chạy một service API trên máy local dùng Docker Compose, bao gồm cả các dependencies (Redis, DB giả lập).

3.4.4.4. 4. Repo: mlops-orchestration-pipelines#

  • Mục tiêu: Cung cấp cái nhìn rõ ràng về tất cả các luồng công việc tự động.

  • Đối tượng: ML Engineer, Data Engineer, DevOps Engineer.

  • Tài liệu đặc thù:

    • DAG Docstrings (trong từng file DAG): Mỗi file DAG phải có một docstring chi tiết ở đầu file, viết bằng Markdown.

      • Nội dung: Mục đích của DAG, lịch chạy (schedule), các tham số đầu vào (params), các tasks chính và luồng dữ liệu giữa chúng, các dependencies bên ngoài (connections, variables).

      • Airflow UI sẽ hiển thị docstring này, rất hữu ích cho việc vận hành.

    • README.md: Giải thích quy ước đặt tên DAGs, cấu trúc thư mục, cách Airflow được cấu hình.

    • DAG Authoring Guide (docs/authoring_dags.md):

      • Các best practices khi viết DAG (tránh top-level code, dùng TaskFlow API,…).

      • Hướng dẫn cách sử dụng các custom operators/hooks của dự án (từ thư mục plugins/).

    • Connection & Variable Management (docs/connections_variables.md):

      • Mô tả cách quản lý connections và variables trong Airflow (qua UI, CLI, hoặc IaC), quy ước đặt tên.

3.4.4.5. 5. Repo: mlops-platform-infrastructure#

  • Mục tiêu: Cung cấp một bản thiết kế chi tiết và có thể tái tạo của toàn bộ hạ tầng.

  • Đối tượng: DevOps Engineer, ML Engineer.

  • Tài liệu đặc thù:

    • README.md: Điểm vào chính, link đến tất cả các tài liệu hạ tầng khác.

    • Infrastructure Overview (docs/infrastructure_overview.md):

      • Mô tả chi tiết kiến trúc hạ tầng: vai trò của 3 server, sơ đồ mạng, luồng dữ liệu giữa các server.

      • Giải thích lựa chọn công nghệ (tại sao dùng Jenkins, tại sao dùng Prometheus,…).

    • IaC Usage Guide (docs/iac_usage.md):

      • Hướng dẫn cách sử dụng Terraform/Ansible để tạo mới hoặc cập nhật hạ tầng.

    • Secrets Management Policy (docs/secrets_management.md):

      • Rất quan trọng: Quy trình quản lý secrets (API keys, passwords, certificates), công cụ sử dụng (ví dụ: HashiCorp Vault, AWS Secrets Manager, hoặc biến môi trường được inject bởi CI/CD).

    • Disaster Recovery Plan (docs/disaster_recovery.md):

      • Kế hoạch khôi phục khi có thảm họa: quy trình backup, các bước để khôi phục từng thành phần (PostgreSQL, MLFlow, Jenkins config,…).

    • CI/CD Pipeline Guide (docs/cicd_pipelines.md):

      • Giải thích chức năng của từng Jenkinsfile, các stage chính, các tham số đầu vào, và cách trigger.

3.4.4.6. 6. Repo: ml-reporting-and-monitoring-logic#

  • Mục tiêu: Giúp mọi người hiểu và sử dụng các công cụ giám sát và báo cáo một cách hiệu quả.

  • Đối tượng: DevOps Engineer, Data Scientist, Business Analyst.

  • Tài liệu đặc thù:

    • README.md: Tổng quan về repo.

    • Dashboard Catalog (docs/dashboard_catalog.md):

      • Liệt kê tất cả các dashboard chính trong Grafana/Kibana.

      • Với mỗi dashboard: mục đích, các biểu đồ chính có ý nghĩa gì, đối tượng người xem là ai, và link trực tiếp đến dashboard.

    • Alerting Runbook (docs/alerting_runbook.md):

      • Liệt kê các cảnh báo quan trọng đã được thiết lập.

      • Với mỗi cảnh báo: ý nghĩa, mức độ nghiêm trọng, các bước cần thực hiện ngay lập tức để kiểm tra và khắc phục.

    • Custom Report Generation Guide (docs/report_generation.md):

      • Hướng dẫn cách chạy các script trong custom_reports/ để tạo báo cáo đột xuất.

Bằng cách xây dựng một bộ tài liệu có cấu trúc và toàn diện như trên, bạn không chỉ giúp đội ngũ hiện tại làm việc hiệu quả mà còn giảm đáng kể thời gian onboarding cho thành viên mới và đảm bảo sự bền vững của toàn bộ hệ thống MLOps.

3.4.5. Nơi lưu trữ 1 số loại tài liệu#

3.4.5.1. 1. Tài liệu Kiến trúc (Architecture Documents)#

Tài liệu kiến trúc có nhiều cấp độ, vì vậy chúng nên được đặt ở những nơi khác nhau.

3.4.5.1.1. a. Kiến trúc tổng thể của hệ thống MLOps#

  • Nội dung: Sơ đồ mô tả cách tất cả các repo con (feature-store, ml-models, services…) tương tác với nhau, luồng dữ liệu chính, và vai trò của 3 server. Đây là “bản thiết kế tổng thể”.

  • Vị trí đặt: Repo mlops-platform-infrastructure. Đây là nơi hợp lý nhất vì nó mô tả “khung xương” của toàn bộ nền tảng.

    • Cụ thể: mlops-platform-infrastructure/docs/SYSTEM_ARCHITECTURE.md

  • Lý do: Ai quan tâm đến hạ tầng (DevOps, ML Engineer) sẽ tìm đến repo này đầu tiên. Nó cũng ít thay đổi và là tài liệu nền tảng cho mọi thành phần khác.

3.4.5.1.2. b. Kiến trúc chi tiết của từng Repo/Module#

  • Nội dung: Sơ đồ và mô tả kiến trúc bên trong của một repo cụ thể. Ví dụ: kiến trúc của một service API trong ml-model-services (cách nó load model, gọi feature store, xử lý request).

  • Vị trí đặt: Trong chính repo con đó.

    • Cụ thể:

      • feature-store-management/docs/architecture.md

      • ml-model-services/.ai-context/architecture.md (phiên bản cho AI) và ml-model-services/docs/architecture.md (phiên bản chi tiết cho người đọc).

  • Lý do: Tài liệu này gắn liền với code của repo đó. Khi code thay đổi, kiến trúc bên trong có thể thay đổi, và việc đặt tài liệu ngay cạnh code giúp dễ dàng cập nhật qua cùng một Pull Request.

3.4.5.1.3. c. Ghi lại Quyết định Kiến trúc (Architectural Decision Records - ADRs)#

  • Nội dung: Ghi lại các quyết định quan trọng và lý do đằng sau chúng (ví dụ: “Tại sao chúng ta chọn Feast thay vì Tecton?”, “Tại sao API dùng FastAPI thay vì Flask?”).

  • Vị trí đặt: Trong repo có liên quan đến quyết định đó.

    • Quyết định về toàn nền tảng: mlops-platform-infrastructure/docs/adr/

    • Quyết định về một model service cụ thể: ml-model-services/services/fraud_detection_api/.ai-context/adr/

  • Lý do: Giúp người mới hiểu được bối cảnh lịch sử và tránh lặp lại các cuộc thảo luận đã có.

3.4.5.2. 2. Tài liệu Triển khai (Deployment Documents)#

Tài liệu này cũng được chia làm hai phần: mã nguồn để triển khai và hướng dẫn để triển khai.

3.4.5.2.1. a. Mã nguồn và Cấu hình Triển khai#

  • Nội dung: Các Jenkinsfile, Dockerfile, docker-compose.yml, Kubernetes manifests (.yaml). Đây là những file “thực thi” quá trình triển khai.

  • Vị trí đặt: Repo mlops-platform-infrastructure.

    • Cụ thể: mlops-platform-infrastructure/jenkins_config/, mlops-platform-infrastructure/kubernetes_deployments/, v.v.

    • Lưu ý: Nếu một service cụ thể có Dockerfile riêng, nó sẽ nằm trong repo ml-model-services cùng với code của service đó.

  • Lý do: Đây là một phần của Infrastructure as Code (IaC) và Configuration as Code. Nó phải được phiên bản hóa và quản lý tập trung.

3.4.5.2.2. b. Hướng dẫn Triển khai và Vận hành (Runbooks)#

  • Nội dung: Hướng dẫn từng bước cho con người. Ví dụ: “Làm thế nào để deploy một phiên bản mới của Fraud Detection API?”, “Các bước rollback khẩn cấp”, “Cách thêm một biến môi trường mới cho service”.

  • Vị trí đặt: Repo mlops-platform-infrastructure.

    • Cụ thể: Tạo một thư mục mlops-platform-infrastructure/docs/runbooks/ với các file như deployment_runbook.md, rollback_procedure.md.

  • Lý do: Người chịu trách nhiệm vận hành và triển khai (DevOps, MLOps Engineer) sẽ làm việc chủ yếu với repo hạ tầng. Đặt runbook ở đây giúp họ dễ dàng truy cập và cập nhật.

3.4.5.3. 3. TODOs / Quản lý công việc#

Đây là một điểm rất quan trọng: KHÔNG lưu trữ danh sách công việc (TODO list) dưới dạng file text (TODO.md) trong repo Git.

  • Vấn đề của việc dùng file text:

    • Nhanh chóng lỗi thời.

    • Không có trạng thái (To Do, In Progress, Done).

    • Không thể gán cho ai, không có deadline.

    • Khó theo dõi và báo cáo tiến độ.

  • Vị trí đặt (Giải pháp đúng): Sử dụng một công cụ quản lý dự án chuyên dụng.

    • Công cụ đề xuất:

      • Jira: Mạnh mẽ, phù hợp cho các quy trình phức tạp.

      • Trello / Asana: Đơn giản, trực quan, phù hợp cho các nhóm nhỏ.

      • GitHub Projects / GitLab Issues: Tích hợp chặt chẽ với repo Git của bạn. Đây là lựa chọn tuyệt vời.

  • Quy trình làm việc (Workflow):

    1. Tạo một Task/Issue/Ticket trong công cụ quản lý dự án (ví dụ: JIRA-123: “Build new user feature view”).

    2. Khi bắt đầu code, tạo một nhánh Git từ develop với tên chứa mã ticket: git checkout -b feature/JIRA-123-user-feature-view.

    3. Khi commit và tạo Pull Request, luôn đề cập đến mã ticket trong tiêu đề hoặc mô tả: “feat: Add user feature view (JIRA-123)”.

    4. Lợi ích: Công cụ sẽ tự động liên kết code với công việc, tạo ra một luồng thông tin liền mạch, giúp mọi người dễ dàng theo dõi từ yêu cầu nghiệp vụ đến dòng code cụ thể.

3.4.5.4. 4. Tài liệu Business, Proposal, Reports#

Những tài liệu này phục vụ đối tượng khác (quản lý, khách hàng, các phòng ban khác) và có vòng đời khác với code. KHÔNG nên đặt chúng trong repo Git.

  • Nội dung:

    • Proposal: Đề xuất dự án ban đầu.

    • Business Requirements Document (BRD): Tài liệu yêu cầu nghiệp vụ.

    • Stakeholder Reports: Báo cáo tiến độ, báo cáo hiệu quả mô hình cho các bên liên quan.

    • Meeting Notes: Ghi chú các cuộc họp quan trọng.

  • Vị trí đặt: Sử dụng một nền tảng văn phòng cộng tác (collaboration suite).

    • Công cụ đề xuất:

      • Google Workspace: Google Docs, Sheets, Slides.

      • Microsoft 365: SharePoint, Word, Excel.

      • Confluence: Rất mạnh mẽ cho việc xây dựng cơ sở tri thức (knowledge base) và liên kết với Jira.

      • Notion: Linh hoạt, phù hợp cho việc quản lý tài liệu và ghi chú.

  • Lý do:

    • Dễ truy cập cho người không biết kỹ thuật: Các bên liên quan nghiệp vụ có thể dễ dàng xem, chỉnh sửa và bình luận.

    • Tính năng cộng tác tốt hơn: Nhiều người chỉnh sửa cùng lúc, quản lý phiên bản trực quan.

    • Bảo mật và phân quyền: Dễ dàng chia sẻ tài liệu cho đúng người.

    • Tách bạch: Giữ cho repo Git sạch sẽ, chỉ tập trung vào mã nguồn và tài liệu kỹ thuật liên quan trực tiếp.

  • Mối liên kết:

    • Trong tài liệu business trên Confluence/Google Docs, bạn có thể dẫn link đến các tài liệu kiến trúc hoặc model card trong Git.

    • Ngược lại, trong README.md của một repo model, bạn có thể dẫn link đến tài liệu yêu cầu nghiệp vụ (BRD) trên Confluence để cung cấp bối cảnh.

    • Các báo cáo (ví dụ: PDF, HTML) được tạo tự động từ code trong repo ml-reporting-and-monitoring-logic có thể được CI/CD pipeline tự động tải lên một thư mục cụ thể trên Google Drive hoặc SharePoint.

Contents