Biến hơn 1 tỷ token AI miễn phí thành một OpenAI API duy nhất

FreeLLMAPI là một máy chủ proxy nguồn mở tương thích với OpenAI. Nó được thiết kế để tổng hợp các gói miễn phí (free-tier) từ khoảng 14 nhà cung cấp AI khác nhau (bao gồm Google Gemini, Groq, Cerebras, SambaNova, Mistral, OpenRouter, GitHub Models, Cloudflare, Cohere, v.v.) vào một endpoint duy nhất là /v1/chat/completions.

Thay vì phải cài đặt 14 bộ SDK khác nhau và đối phó với giới hạn tốc độ (rate limit) của từng hãng, FreeLLMAPI cho phép bạn gom tất cả lại để sử dụng khoảng 1.3 tỷ token miễn phí mỗi tháng. Dự án này được thiết kế dành riêng cho mục đích thử nghiệm cá nhân (Personal experimentation).

Các tính năng nổi bật:

• Tương thích 100% với OpenAI: Hoạt động với các thư viện OpenAI chính thức, LangChain, LlamaIndex,... Chỉ cần thay đổi base_url.

• Tự động chuyển đổi dự phòng (Automatic failover): Nếu một nhà cung cấp bị lỗi 429 (vượt quá giới hạn) hoặc 5xx, bộ định tuyến sẽ tự động bỏ qua, đưa key đó vào thời gian chờ và thử lại ở model tiếp theo trong chuỗi dự phòng (fallback chain) của bạn.

• Kiểm soát giới hạn thông minh: Theo dõi số lượng request và token (RPM, RPD, TPM, TPD) cho từng API key để đảm bảo bạn không bao giờ vượt qua mức trần miễn phí.

• Bảo mật: Lưu trữ API key mã hóa bằng AES-256-GCM (với SQLite). Các ứng dụng client chỉ cần xác thực qua một token duy nhất (unified API key).

• Giao diện quản trị: Đi kèm với bảng điều khiển Admin (xây dựng bằng React + Vite) để quản lý key, sắp xếp thứ tự ưu tiên của model và xem phân tích dữ liệu.

• Hỗ trợ nâng cao: Hỗ trợ Streaming, Tool calling (gọi hàm) và lưu giữ session (Sticky sessions) để duy trì mạch trò chuyện.

Cách cài đặt

Yêu cầu hệ thống: Node.js 20+ và npm.

Các bước cài đặt:

1. Clone mã nguồn về máy:

   Bash

   git clone https://github.com/tashfeenahmed/freellmapi.git
   cd freellmapi
   

2. Cài đặt các gói phụ thuộc:

   Bash

   npm install
   

3. Tạo tệp .env và thiết lập khóa mã hóa cho API keys:

   Bash

   cp .env.example .env
   echo "ENCRYPTION_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")" >> .env
   

4. Khởi chạy server và bảng điều khiển (Dashboard):

   Bash

   npm run dev
   

Cách sử dụng

1. Thêm API Key: Mở trình duyệt và truy cập vào trang quản trị tại http://localhost:5173. Vào tab Keys để thêm các API key tương ứng của các nhà cung cấp bạn có (Google, Groq, v.v.).

2. Cấu hình chuỗi dự phòng (Fallback Chain): Sắp xếp thứ tự ưu tiên các model theo ý muốn.

3. Lấy Unified API Key: Lấy key duy nhất của FreeLLMAPI từ phần header của trang Keys (thường bắt đầu bằng freellmapi-...).

4. Viết mã (Code): Sử dụng thư viện OpenAI tiêu chuẩn, trỏ base_url về http://localhost:3001/v1 và truyền vào unified key vừa lấy.

Ví dụ bằng Python:

from openai import OpenAI

# Khởi tạo client kết nối tới FreeLLMAPI nội bộ
client = OpenAI(
    base_url="http://localhost:3001/v1",
    api_key="freellmapi-your-unified-key",
)

# Gửi yêu cầu
resp = client.chat.completions.create(
    model="auto", # 'auto' để router tự chọn model tốt nhất đang khả dụng, hoặc chỉ định tên model cụ thể (VD: 'gemini-2.5-flash')
    messages=[{"role": "user", "content": "Hãy tóm tắt sự sụp đổ của đế chế La Mã trong một câu."}]
)

print(resp.choices[0].message.content)

# Kiểm tra xem yêu cầu vừa rồi được xử lý bởi nhà cung cấp/model nào
print("Được định tuyến qua:", resp.headers.get("x-routed-via"))

⚠️ Một số hạn chế cần lưu ý

• Không dùng cho môi trường Production (Thực tế): Các tài khoản free-tier có thể thay đổi bất cứ lúc nào, tốc độ phản hồi (latency) không ổn định và dự án không có hỗ trợ SLA.

• Giới hạn tính năng: Hiện tại chỉ hỗ trợ xử lý văn bản (chat completions). Chưa hỗ trợ Embeddings, tạo ảnh (Images), âm thanh (Audio) hay đầu vào đa phương thức (Vision).

• Chất lượng Model: Bạn sẽ không truy cập được các mô hình cao cấp nhất như GPT-4 (bản đầy đủ trả phí) hay Claude Opus. Khả năng xử lý tốt nhất sẽ giới hạn ở mức Llama 3.3 70B, Gemini 2.5 Pro hay GLM-4.5.