Feat : Gitbook

2026-09-22 13:38:31 +00:00 · 2026-05-11 11:50:24 +07:00
parent 7ad538bcf2
commit fd92af77a0
124 changed files with 34154 additions and 4 deletions
@@ -0,0 +1,351 @@
+# Troubleshooting
+
+Các vấn đề và giải pháp phổ biến khi dùng 9Router.
+
+---
+
+## "Language model did not provide messages"
+
+**Vấn đề:** Request thất bại với phản hồi rỗng hoặc thông báo lỗi.
+
+**Nguyên nhân:**
+- Hết quota provider
+- API key không hợp lệ hoặc hết hạn
+- Model không khả dụng
+
+**Giải pháp:**
+
+1. **Kiểm tra trạng thái quota:**
+   ```
+   Dashboard → Providers → View quota tracker
+   ```
+   Nếu hết quota, đợi reset hoặc đổi provider.
+
+2. **Dùng fallback combo:**
+   ```
+   Dashboard → Combos → Create fallback chain
+   Example: cc/claude-opus → glm/glm-4.7 → if/kimi-k2
+   ```
+
+3. **Xác minh kết nối provider:**
+   ```
+   Dashboard → Providers → Reconnect if needed
+   ```
+
+---
+
+## Rate Limiting
+
+**Vấn đề:** Lỗi "Rate limit exceeded" hoặc "Too many requests".
+
+**Nguyên nhân:**
+- Hết quota subscription (giới hạn 5h/ngày/tuần)
+- Đạt API rate limit
+- Quá nhiều request đồng thời
+
+**Giải pháp:**
+
+1. **Kiểm tra thời gian reset:**
+   ```
+   Dashboard → Quota Tracking → View reset countdown
+   ```
+
+2. **Chuyển sang tier rẻ:**
+   ```
+   Use: glm/glm-4.7 ($0.6/1M tokens)
+        minimax/MiniMax-M2.1 ($0.20/1M tokens)
+   ```
+
+3. **Thêm fallback combo:**
+   ```
+   Dashboard → Combos → Add backup models
+   Primary: cc/claude-opus (subscription)
+   Backup: glm/glm-4.7 (cheap)
+   Emergency: if/kimi-k2 (free)
+   ```
+
+---
+
+## OAuth Token hết hạn
+
+**Vấn đề:** Lỗi "Unauthorized" hoặc "Token expired".
+
+**Nguyên nhân:**
+- OAuth token hết hạn (auto-refresh thất bại)
+- Session provider không hợp lệ
+- Vấn đề network khi refresh
+
+**Giải pháp:**
+
+1. **Auto-refresh (mặc định):**
+   9Router tự refresh tokens. Đợi 30 giây rồi thử lại.
+
+2. **Kết nối lại thủ công:**
+   ```
+   Dashboard → Providers → [Provider Name] → Reconnect
+   → Complete OAuth flow again
+   ```
+
+3. **Kiểm tra trạng thái provider:**
+   Xác minh provider service đang online (Claude Code, Codex, v.v.)
+
+---
+
+## Chi phí cao
+
+**Vấn đề:** Sử dụng hoặc chi phí cao bất ngờ.
+
+**Nguyên nhân:**
+- Dùng model đắt không cần thiết
+- Không fallback sang tier rẻ hơn
+- Context window lớn
+
+**Giải pháp:**
+
+1. **Kiểm tra usage stats:**
+   ```
+   Dashboard → Usage Stats → View token consumption
+   → Identify high-cost models
+   ```
+
+2. **Chuyển sang model rẻ hơn:**
+   ```
+   Replace: cc/claude-opus ($20-100/month subscription)
+   With: glm/glm-4.7 ($0.6/1M tokens)
+         minimax/MiniMax-M2.1 ($0.20/1M tokens)
+   ```
+
+3. **Dùng free tier:**
+   ```
+   if/kimi-k2-thinking (FREE)
+   qw/qwen3-coder-plus (FREE)
+   kr/claude-sonnet-4.5 (FREE)
+   gc/gemini-3-flash-preview (FREE 180K/month)
+   ```
+
+4. **Tối ưu prompt:**
+   - Giảm context size
+   - Dùng streaming cho phản hồi dài
+   - Cache prompt thường dùng
+
+---
+
+## Connection Refused
+
+**Vấn đề:** Lỗi "ECONNREFUSED" hoặc "Cannot connect to localhost:20128".
+
+**Nguyên nhân:**
+- 9Router không chạy
+- Port 20128 bị chặn
+- Firewall chặn kết nối
+
+**Giải pháp:**
+
+1. **Khởi động 9Router:**
+   ```bash
+   9router
+   ```
+   Dashboard sẽ mở tại http://localhost:3000
+
+2. **Xác minh port 20128:**
+   ```bash
+   # Check if port is listening
+   lsof -i :20128
+   
+   # Or on Windows
+   netstat -ano | findstr :20128
+   ```
+
+3. **Kiểm tra firewall:**
+   - macOS: System Settings → Network → Firewall
+   - Windows: Windows Defender Firewall → Allow app
+   - Linux: `sudo ufw allow 20128`
+
+4. **Dùng cloud endpoint:**
+   Nếu localhost không hoạt động (ví dụ: Cursor IDE):
+   ```
+   Endpoint: https://9router.com/v1
+   ```
+
+---
+
+## Dashboard không mở
+
+**Vấn đề:** Dashboard không load tại http://localhost:3000.
+
+**Nguyên nhân:**
+- Port 3000 đã được dùng
+- 9Router bị crash
+- Vấn đề cache browser
+
+**Giải pháp:**
+
+1. **Kiểm tra 9Router có chạy không:**
+   ```bash
+   # Check process
+   ps aux | grep 9router
+   
+   # Check port 3000
+   lsof -i :3000
+   ```
+
+2. **Kill process xung đột:**
+   ```bash
+   # macOS/Linux
+   lsof -ti:3000 | xargs kill -9
+   
+   # Windows
+   netstat -ano | findstr :3000
+   taskkill /PID <PID> /F
+   ```
+
+3. **Khởi động lại 9Router:**
+   ```bash
+   # Stop
+   pkill -f 9router
+   
+   # Start
+   9router
+   ```
+
+4. **Xóa cache browser:**
+   - Chrome: Ctrl+Shift+Delete → Clear cache
+   - Thử chế độ ẩn danh
+
+5. **Kiểm tra cài đặt firewall:**
+   Đảm bảo port 3000 không bị chặn.
+
+---
+
+## Model Not Found
+
+**Vấn đề:** Lỗi "Model not found" hoặc "Invalid model".
+
+**Nguyên nhân:**
+- Provider chưa kết nối
+- Sai chính tả model ID
+- Provider không hoạt động
+
+**Giải pháp:**
+
+1. **Xác minh kết nối provider:**
+   ```
+   Dashboard → Providers → Check status (green = active)
+   ```
+
+2. **Kiểm tra format model ID:**
+   ```
+   Correct: cc/claude-opus-4-5-20251101
+   Wrong: claude-opus-4-5-20251101
+   
+   Format: [provider-prefix]/[model-name]
+   ```
+
+3. **Liệt kê model khả dụng:**
+   ```bash
+   curl http://localhost:20128/v1/models \
+     -H "Authorization: Bearer your-api-key"
+   ```
+
+4. **Kết nối lại provider:**
+   ```
+   Dashboard → Providers → [Provider] → Reconnect
+   ```
+
+---
+
+## Phản hồi chậm
+
+**Vấn đề:** Request mất quá lâu hoặc timeout.
+
+**Nguyên nhân:**
+- Độ trễ provider
+- Vấn đề network
+- Context/response lớn
+- Provider rate limiting
+
+**Giải pháp:**
+
+1. **Kiểm tra trạng thái provider:**
+   ```
+   Dashboard → Providers → View latency stats
+   ```
+
+2. **Chuyển sang model nhanh hơn:**
+   ```
+   Fast: cc/claude-haiku-4-5 (Haiku is faster than Opus)
+         gc/gemini-3-flash-preview
+         qw/qwen3-coder-flash
+   ```
+
+3. **Dùng streaming:**
+   ```json
+   {
+     "model": "cc/claude-opus-4-5",
+     "messages": [...],
+     "stream": true
+   }
+   ```
+
+4. **Kiểm tra network:**
+   ```bash
+   # Test latency
+   ping api.anthropic.com
+   ping api.openai.com
+   ```
+
+5. **Giảm context size:**
+   - Cắt bớt lịch sử tin nhắn
+   - Dùng prompt nhỏ hơn
+   - Bật context pruning trong CLI tool
+
+---
+
+## API Key không hợp lệ
+
+**Vấn đề:** Lỗi "Invalid API key" hoặc "Authentication failed".
+
+**Nguyên nhân:**
+- Sao chép sai API key
+- API key hết hạn
+- API key chưa được tạo
+
+**Giải pháp:**
+
+1. **Tạo lại API key:**
+   ```
+   Dashboard → Settings → API Keys → Generate New Key
+   → Copy and use new key
+   ```
+
+2. **Xác minh format key:**
+   ```
+   Correct: 9r_xxxxxxxxxxxxxxxxxxxxxxxx
+   Wrong: Missing 9r_ prefix
+   ```
+
+3. **Kiểm tra key trong CLI config:**
+   ```bash
+   # Cursor
+   Settings → Models → OpenAI API Key
+   
+   # Cline
+   Settings → API Key
+   
+   # Environment variable
+   export OPENAI_API_KEY="9r_your_key"
+   ```
+
+4. **Test API key:**
+   ```bash
+   curl http://localhost:20128/v1/models \
+     -H "Authorization: Bearer 9r_your_key"
+   ```
+
+---
+
+## Cần trợ giúp thêm?
+
+- **GitHub Issues:** [github.com/decolua/9router/issues](https://github.com/decolua/9router/issues)
+- **Documentation:** [9router.com/docs](https://9router.com/docs)
+- **FAQ:** [faq.md](faq.md)