Troubleshooting & Optimization

Bài học cuối cùng tổng hợp các lỗi thường gặp và cách tối ưu hóa hệ thống để chạy nhanh hơn, ổn định hơn.

1. Troubleshooting (Xử lý sự cố)

Lỗi 1: 429 You exceeded your current quota

• Nguyên nhân: Gemini model hết quota free tier
• Khắc phục:
  • Hệ thống tự động fallback sang model khác
  • Nếu tất cả models đều hết → chờ quota reset (thường 24h)
  • Hoặc chuyển sang OpenAI (trả phí)

⚠️ Model 'gemini-2.0-flash' đã hết quota!
🔄 Đang chuyển sang model: gemini-1.5-flash
✅ Đã chuyển sang model: gemini-1.5-flash

Lỗi 2: Executable doesn't exist (khi build EXE)

• Nguyên nhân: Playwright browsers chưa được bundle đúng
• Khắc phục:
  • Đảm bảo copy cả chromium-* và chromium_headless_shell-*
  • Set PLAYWRIGHT_BROWSERS_PATH trong runtime hook

Lỗi 3: Image input modality is not enabled

• Nguyên nhân: Model không hỗ trợ phân tích ảnh (TTS, audio models)
• Khắc phục: Hệ thống tự động lọc models không phù hợp:

EXCLUDED_PATTERNS = [
    "tts", "image-generation", "embedding", 
    "audio", "robotics", "live"
]

Lỗi 4: AI output bị cắt ngắn ("Nhập", "Nhấn nút")

• Nguyên nhân: max_output_tokens quá thấp hoặc model response bị truncate
• Khắc phục: Tăng max_output_tokens lên 256 và validate output:

if len(result.split()) >= 3:
    return result
return action_hint  # Fallback

2. Optimization (Tối ưu hóa)

2.1. Chọn Model phù hợp

Model	RPD (Free)	Chất lượng	Khuyến nghị
gemma-3-27b	14,400	Tốt	⭐ Cho production
gemini-2.5-flash	20	Rất tốt	Cho demo
gemini-1.5-flash	1,500	Tốt	Backup

2.2. Tối ưu chi phí AI

• Chọn model có RPD cao: gemma-3-27b có 14.4K requests/ngày
• Viewport cố định: 1280x800 đủ để AI đọc, không cần 4K
• Fallback về code-based: Khi không cần mô tả đẹp

2.3. Tối ưu tốc độ Replay

# Trong replayer.py - wait time đã được tối ưu
page.wait_for_timeout(800)  # Đủ để page ổn định
page.wait_for_load_state('domcontentloaded', timeout=3000)

2.4. Cấu hình qua Environment

# .env - Chọn model cụ thể thay vì auto-detect
GEMINI_MODEL=gemma-3-27b

# Hoặc để trống để auto-detect
# GEMINI_MODEL=

Ưu điểm của việc cấu hình qua .env

• ✅ Không cần sửa code
• ✅ Dễ thay đổi giữa các môi trường
• ✅ Có thể override bằng interactive mode

3. Bảo mật (Security Checklist)

Trước khi commit code:

• [ ] API Keys: Đảm bảo .env nằm trong .gitignore
• [ ] Không hardcode: API keys phải đọc từ environment

Trước khi public tài liệu:

• [ ] PII Check: Kiểm tra ảnh không lộ email, SĐT, password thật
• [ ] Token Check: Không lộ JWT, session ID trong screenshots
• [ ] Internal URLs: Không lộ URL nội bộ (staging, dev server)

Khi build EXE để phân phối:

• [ ] Không bundle .env: Chỉ bundle .env.example
• [ ] README rõ ràng: Hướng dẫn user tự tạo API key

4. Đánh giá tổng thể

Ưu điểm của hệ thống

Tiêu chí	Đánh giá
Tự động hóa	⭐⭐⭐⭐⭐ Giảm 90% thời gian viết docs
Chất lượng output	⭐⭐⭐⭐ AI viết tự nhiên, dễ đọc
Độ tin cậy	⭐⭐⭐⭐ Fallback 3 tầng
Chi phí	⭐⭐⭐⭐⭐ Free tier đủ dùng
Khả năng mở rộng	⭐⭐⭐ Modular nhưng chưa có plugin system

Nhược điểm cần cải thiện

• Recording chưa bundle được vào EXE (cần Python)
• Chưa hỗ trợ multi-language (chỉ tiếng Việt)
• Chưa có video generation

Lời kết

Hệ thống Auto Docs Generator minh chứng cho sức mạnh của Automation + AI. Với kiến trúc modular và cơ chế fallback thông minh, tool có thể hoạt động ổn định trong nhiều điều kiện khác nhau.

Tài liệu tham khảo:

• Playwright Documentation
• Google Gemini API
• OpenAI Vision API

Happy Automating! 🚀