Bài 11. Tài liệu hóa cấu hình và quy trình vận hành

1. Đặt vấn đề

Một hệ thống AI local có thể được một người cài đặt rất nhanh, nhưng nếu không tài liệu hóa, sau vài tháng sẽ khó vận hành: không ai nhớ model lưu ở đâu, service nào chạy, API gọi endpoint nào, FAISS index nằm thư mục nào, backup chạy lúc nào, log lưu ở đâu, prompt template bản mới nhất là gì, khi lỗi phải xử lý ra sao. Nếu người cài đặt nghỉ hoặc chuyển công tác, hệ thống trở thành “hộp đen”.

Tài liệu hóa cấu hình và quy trình vận hành là điều kiện để AI local trở thành hệ thống bệnh viện chính thức, không phụ thuộc cá nhân.

2. Cần tài liệu hóa những gì?

Cần tài liệu hóa:

• Kiến trúc tổng thể.
• Máy chủ.
• Hệ điều hành.
• GPU/CPU/RAM/ổ cứng.
• Ollama version.
• Danh sách model.
• Thư mục model.
• API trung gian.
• Nginx.
• RAG/FAISS.
• Embedding model.
• Metadata database.
• Kho tài liệu.
• Backup.
• Log.
• User/role.
• Quy trình start/stop/restart.
• Quy trình cập nhật.
• Quy trình xử lý sự cố.
• Quy trình bảo trì.
• Quy định bảo mật.

3. Tài liệu kiến trúc

Nên có sơ đồ:

Người dùng → Nginx → Web/API trung gian → RAG/FAISS → Ollama → Response

Nếu có Drupal/QMS/HIS, cần thể hiện rõ luồng dữ liệu và phân quyền. Sơ đồ giúp người mới hiểu hệ thống.

4. Tài liệu cấu hình máy chủ

Cần ghi:

• Hostname.
• IP.
• OS version.
• GPU.
• RAM.
• Ổ cứng.
• Mount point.
• RAID nếu có.
• UPS.
• Người phụ trách.
• Vai trò máy chủ.
• Các service đang chạy.

Không nên ghi mật khẩu trực tiếp trong tài liệu.

5. Tài liệu Ollama

Cần ghi:

• Cách kiểm tra service.
• Cách restart.
• Thư mục model.
• Danh sách model sản xuất.
• Model thử nghiệm.
• Modelfile.
• Context/parameter.
• Cách pull model.
• Cách xóa model.
• Cách kiểm tra GPU.
• Cách test API.

6. Tài liệu RAG/FAISS

Cần ghi:

• Nguồn tài liệu.
• Pipeline xử lý.
• Cách làm sạch.
• Cách chunking.
• Embedding model.
• Thư mục FAISS index.
• Metadata store.
• Cách rebuild index.
• Cách update incremental.
• Cách backup.
• Cách rollback.
• Bộ câu hỏi test.

7. Tài liệu API và Nginx

Cần ghi:

• Endpoint.
• Port nội bộ.
• Domain.
• File cấu hình Nginx.
• Cách restart Nginx.
• Cách kiểm tra log.
• Cơ chế xác thực.
• Rate limit.
• Timeout.
• Biến môi trường.
• Service systemd/Docker liên quan.

Thông tin bí mật như token, key nên được quản lý riêng, không ghi lộ trong tài liệu thường.

8. Tài liệu backup

Cần ghi:

• Backup những gì.
• Lịch backup.
• Thư mục backup.
• Retention.
• Script backup.
• Log backup.
• Cách kiểm tra backup thành công.
• Cách restore.
• Người phụ trách.

Backup không có tài liệu restore thì chưa đủ.

9. Tài liệu xử lý sự cố

Nên có SOP cho:

• Ollama không chạy.
• Model treo.
• GPU không nhận.
• VRAM đầy.
• RAM đầy.
• Ổ cứng đầy.
• API timeout.
• RAG không trả nguồn.
• Nginx lỗi.
• Backup lỗi.
• UPS cảnh báo.
• Log tăng bất thường.

Mỗi SOP nên có: dấu hiệu, nguyên nhân thường gặp, lệnh kiểm tra, bước xử lý, khi nào báo cấp trên.

10. Quản lý phiên bản tài liệu

Tài liệu vận hành cũng cần version:

• Ngày cập nhật.
• Người cập nhật.
• Nội dung thay đổi.
• Phiên bản áp dụng.
• Trạng thái còn hiệu lực.

Nếu cấu hình thay đổi nhưng tài liệu không cập nhật, tài liệu sẽ gây sai.

11. Không lưu bí mật trong tài liệu thường

Không ghi trực tiếp:

• Mật khẩu.
• API key.
• Token.
• Private key.
• Chuỗi kết nối database có mật khẩu.
• Thông tin nhạy cảm người dùng.

Bí mật cần được lưu trong password manager, vault hoặc file cấu hình có quyền hạn chặt.

12. Bàn giao và đào tạo

Tài liệu hóa chỉ có giá trị khi người phụ trách khác có thể dùng được. Cần:

• Đào tạo nhân sự CNTT.
• Thực hành restart/test.
• Thực hành restore backup.
• Thực hành rebuild RAG.
• Thực hành xử lý lỗi giả lập.
• Cập nhật tài liệu sau mỗi thay đổi.

13. Kết luận

Tài liệu hóa cấu hình và quy trình vận hành là nền tảng để hệ thống AI local bệnh viện không phụ thuộc vào một cá nhân. Cần ghi rõ kiến trúc, service, model, RAG, API, backup, log, bảo trì, xử lý sự cố và bảo mật. Một hệ thống AI local được tài liệu hóa tốt sẽ dễ bảo trì, dễ mở rộng, dễ bàn giao và an toàn hơn trong vận hành lâu dài.