HydraLLM: Bộ điều phối thông minh

HydraLLM: Bộ điều phối thông minh

HydraLLM là một gateway nhận biết ngữ cảnh được thiết kế để tận dụng hiệu quả nhiều tài nguyên LLM. Nó định tuyến yêu cầu trên Gemini / Groq / Cerebras, cung cấp circuit breaker theo từng nhà cung cấp, xoay vòng khóa ngẫu nhiên (bao gồm cooldown nhận biết quota), khả năng tăng cường web theo thời gian thực, và xây dựng API tương thích OpenAI trên nền Clean Architecture nghiêm ngặt (Domain rồi đến Services rồi đến Adapters rồi đến API).

• Phiên bản: 1.3.0 (pyproject.toml)
• Python: 3.10+
• Điểm vào chạy: python main.py
• UI tích hợp: http://localhost:8000/ui
• Endpoint tương thích OpenAI: POST /v1/chat/completions

Tài liệu đặc tả kỹ thuật HydraLLM (SPEC)

1. Tổng quan

HydraLLM là một gateway LLM độ sẵn sàng cao tuân thủ Clean Architecture. Nó cung cấp định tuyến thông minh giữa nhiều nhà cung cấp, cô lập lỗi dựa trên circuit breaker, khả năng tăng cường web theo thời gian thực, và hỗ trợ hoàn toàn đặc tả OpenAI API.

2. Đặc tả các thành phần cốt lõi

2.1 Gateway (src/services/gateway.py)

• Điều phối: Điều phối luồng tải phiên -> phân tích ngữ cảnh -> tăng cường web -> thực thi có khả năng phục hồi -> lưu trữ bền vững.
• Lý do định tuyến kỹ thuật: Mọi phản hồi đều bao gồm cơ sở ra quyết định dưới dạng các hằng số rõ ràng.
  • USER_HINT: người dùng chỉ định rõ ràng
  • TOKEN_OPTIMIZED: tối ưu hóa dựa trên số lượng token
  • WEB_INTENT_SEARCH: kết quả phân tích ý định tìm kiếm trên web
  • MULTIMODAL_ANALYSIS: phát hiện nhu cầu xử lý hình ảnh
  • KEY_AVAILABILITY: trạng thái khóa và kết quả failover

2.2 Context Analyzer (src/services/analyzer.py)

• Thuật toán định tuyến: Phân tích độ dài token, tính đa phương thức, và ý định tìm kiếm web để tạo RoutingDecision tối ưu.
• Lọc khả dụng động: Phản ánh trạng thái thời gian thực của KeyManager để loại các model của nhà cung cấp không có khóa hoạt động khỏi tập lựa chọn.

2.3 Key Manager (src/services/key_manager.py)

• Xoay vòng khóa: Chọn ngẫu nhiên trong pool khóa hoạt động và theo dõi mức sử dụng.
• Quản lý sự cố: Áp dụng cooldown phân biệt theo từng loại lỗi.
  • 403 Forbidden: 24 giờ (ứng phó lỗi vĩnh viễn ở cấp độ khóa)
  • 429 Rate Limit / Quota: 1 giờ
  • Các lỗi giao tiếp khác: 5 phút

2.4 Web Context Service (src/services/web_context_service.py)

• Tăng cường dữ liệu: Thu thập thông tin thời gian thực dựa trên Playwright/Scrapling và chèn vào prompt.
• Theo dõi hiệu năng: Ghi lại tỷ lệ thành công, số ký tự thu thập, và độ trễ thông qua bảng scraping_metrics.

3. Mô hình phục hồi và khắc phục sự cố (Troubleshooting Insights)

• Concurrency Guard: Áp dụng asyncio.Lock và threading.Lock cho các thao tác ghi của KeyManager và SessionManager để đảm bảo tính toàn vẹn dữ liệu trong điều kiện tải cao.
• Self-Healing Scraper: Kích hoạt cơ chế tự động khởi động lại khi phát hiện browser instance bị sập.
• Unpacking Guard: Tuân thủ kiểu trả về nghiêm ngặt (tuple[list, str | None]) và guard để ngăn lỗi NoneType có thể phát sinh khi xử lý dữ liệu tăng cường.