# FreeLLMAPI: gom LLM miễn phí vào một API — hướng dẫn cài đặt và dùng

> FreeLLMAPI là router self-hosted gom các gói miễn phí từ nhiều nhà cung cấp LLM vào một endpoint OpenAI-compatible duy nhất. Công cụ hỗ trợ tự định tuyến, chuyển dự phòng, quản lý quota và dùng được với nhiều SDK, CLI, coding agent. Cài khá dễ bằng Docker hoặc bộ cài Windows; bạn vẫn cần tự thêm API key của các nhà cung cấp.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-05-12 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/freellmapi-gom-llm-mien-phi-api

FreeLLMAPI là một router self-hosted gom nhiều nhà cung cấp mô hình ngôn ngữ miễn phí vào một API OpenAI-compatible duy nhất. Thay vì tự tích hợp từng SDK, tự theo dõi từng giới hạn và sửa từng cấu hình khi một dịch vụ lỗi, bạn thêm các key vào một dashboard rồi trỏ ứng dụng về endpoint cục bộ.

Repo phù hợp với người muốn thử nhiều LLM, dev cần một endpoint chung cho ứng dụng, nhân viên văn phòng muốn dùng chatbot qua công cụ tương thích OpenAI, hoặc chủ shop muốn tự động hóa nội dung mà chưa muốn trả phí cho một nhà cung cấp duy nhất. Điểm đáng giá nhất là router có thể chọn model, theo dõi quota theo từng key và tự chuyển sang model hoặc provider khác khi request bị giới hạn.

FreeLLMAPI hiện gom khoảng 87 provider, 736 họ model và 1.313 endpoint miễn phí theo mô tả của dự án. Các key được mã hóa trong SQLite, còn ứng dụng của bạn chỉ cần dùng một unified key. Repo có giấy phép MIT và chạy được trên Windows, macOS, Linux hoặc máy ARM nhỏ như Raspberry Pi.

```repo
- repo | tashfeenahmed/freellmapi
- kind | Ứng dụng
- desc | FreeLLMAPI gom nhiều nhà cung cấp LLM miễn phí vào một API OpenAI-compatible, tự định tuyến và chuyển dự phòng khi lỗi.
- stars | 52k
- lang | TypeScript
- license | MIT
```

## FreeLLMAPI làm được gì

- Một endpoint cho nhiều provider: ứng dụng chỉ cần gọi `http://localhost:3001/v1` thay vì biết từng URL, SDK và định dạng riêng của Google, Groq, Mistral, OpenRouter hay các provider khác. Điều này giúp bạn đổi model hoặc thêm provider mà ít phải sửa mã nguồn.

- Tự chọn model theo chiến lược: model ảo `auto` cho phép router chọn theo tốc độ, khả năng và độ ổn định. Bạn cũng có thể dùng các lựa chọn như `auto:fast`, `auto:smart`, profile đã đặt tên hoặc chỉ rõ model id.

- Tự chuyển dự phòng khi lỗi: nếu provider trả về lỗi giới hạn tốc độ hoặc lỗi máy chủ 5xx, router thử model kế tiếp trong chuỗi. Cơ chế cooldown và xoay key giúp giảm việc một ứng dụng bị dừng chỉ vì một endpoint tạm thời không dùng được.

- Theo dõi quota theo từng key: router ghi nhận RPM, RPD, TPM và TPD theo platform, model và key. Nhờ vậy chuỗi định tuyến có thể tránh vượt giới hạn miễn phí đã biết của từng provider.

- Tương thích nhiều giao diện API: ngoài Chat Completions, dự án hỗ trợ Responses, Completions, Images, Videos, Audio, Transcriptions, Embeddings và Models. Vì vậy nó có thể phục vụ chatbot, autocomplete, tạo ảnh, đọc hoặc chép lời âm thanh và embedding nếu provider tương ứng có model phù hợp.

- Hỗ trợ Anthropic, Gemini và Ollama: endpoint Anthropic Messages cho phép Claude Code và SDK Anthropic dùng cùng router. Gemini CLI có thể dùng giao diện `/v1beta`, còn chế độ Ollama tùy chọn phục vụ các client cần NDJSON chat, generate, tags, metadata hoặc embeddings.

- Tool calling và structured outputs: các tham số `tools`, `response_format`, `seed`, `logprobs`, penalties cùng các tham số sampling được truyền theo khả năng của provider. Router cũng cố gắng chuyển các lời gọi tool dạng văn bản thành `tool_calls` thật.

- Fusion để tổng hợp nhiều câu trả lời: khi gọi model ảo `fusion`, router gửi prompt tới một nhóm model miễn phí song song rồi dùng model judge để tổng hợp thành một câu trả lời. Tính năng này hữu ích khi bạn muốn có nhiều góc nhìn cho cùng một câu hỏi.

- Profile fallback có tên riêng: bạn có thể tạo chuỗi cho từng mục đích, chẳng hạn chuỗi coding hoặc vision, rồi chọn profile từ dashboard hoặc trong request. Điều này tiện hơn việc lặp lại một danh sách model dài trong từng ứng dụng.

- Giữ mạch hội thoại: sticky session giữ cuộc trò chuyện trên cùng một model trong 30 phút. Nếu buộc phải chuyển model giữa chừng, tùy chọn context handoff có thể tạo ghi chú tóm tắt để model mới tiếp tục đúng ngữ cảnh hơn.

- Dashboard quản trị: giao diện React cho phép thêm key, sắp xếp fallback chain, chạy playground và xem các chỉ số p50, p95, TTFT trong những khoảng thời gian khác nhau. Dashboard có đăng nhập, giao diện sáng/tối và hỗ trợ nhiều ngôn ngữ.

- MCP server cho ChatGPT và agent: client MCP có thể gọi inference, xem model đang dùng được, kiểm tra health, usage, cache và metadata định tuyến, đồng thời quản lý chiến lược routing qua `/mcp`.

- Tự cập nhật catalog: router đồng bộ catalog đã ký hai lần mỗi ngày. Catalog chứa model mới, thay đổi quota và bản sửa tương thích. Bản miễn phí dùng snapshot theo tháng nên model mới có thể đến chậm hơn; cài đặt premium nhận catalog trực tiếp trong ngày cập nhật.

- Bảo vệ key ở lớp lưu trữ: provider key được mã hóa bằng AES-256-GCM trong SQLite và chỉ giải mã trong bộ nhớ khi cần. Ứng dụng bên ngoài chỉ nhìn thấy một bearer token dạng `freellmapi-…`.

## Cần chuẩn bị gì

- Một máy chạy Windows, macOS hoặc Linux. Dự án cũng nói có thể chạy trên máy ARM nhỏ, bao gồm Raspberry Pi.

- Node.js 20 trở lên nếu bạn chạy router theo cách cài đặt dựa trên Node. README khẳng định dự án chạy ở mọi nơi Node 20+ chạy được.

- Docker nếu dùng lệnh cài nhanh bằng script. README ghi rõ one-liner yêu cầu Docker.

- API key của các provider bạn muốn dùng. FreeLLMAPI không tự cấp các key này; bạn phải lấy từ từng provider được hỗ trợ rồi thêm vào trang Keys.

- Trình duyệt để mở dashboard tại `http://localhost:3001`, thêm provider key, sắp xếp Fallback Chain và lấy unified API key.

- Nếu dùng ứng dụng hoặc SDK bên ngoài, ứng dụng đó cần hỗ trợ OpenAI-compatible API, Anthropic, Gemini, Ollama hoặc MCP tùy giao diện bạn chọn.

- Không bắt buộc GPU theo README. Router chủ yếu kết nối tới provider bên ngoài. Nếu thêm một endpoint custom như Ollama, llama.cpp, LM Studio hoặc vLLM thì phần model đó có thể cần phần cứng riêng, nhưng README không nêu cấu hình GPU cụ thể.

```note
Provider key vẫn có thể phát sinh giới hạn, quota hoặc chi phí theo chính sách của provider. Chỉ thêm key vào router riêng của bạn, không đưa key vào Git, prompt, MCP URL hoặc tệp cấu hình công khai.
```

## Cài đặt từng bước

```steps
- Chọn cách cài | Dùng Docker, bộ cài Windows hoặc ứng dụng desktop theo hệ điều hành
- Khởi động router | Chạy script cài nhanh hoặc mở bộ cài từ Releases
- Mở dashboard | Truy cập http://localhost:3001 trên máy đã chạy router
- Thêm provider key | Vào Keys, thêm các key bạn muốn dùng và sắp xếp Fallback Chain
- Lấy unified key | Sao chép key trong phần đầu trang Keys để cấp cho ứng dụng
- Kết nối client | Trỏ OpenAI SDK hoặc công cụ tương thích về http://localhost:3001/v1
```

### Chọn cách cài phù hợp

Nếu bạn đã có Docker, README cung cấp cách cài nhanh bằng một lệnh. Script sẽ tạo thư mục `~/freellmapi`, tạo encryption key, tải image và khởi động container. Chạy lệnh trong terminal có quyền dùng Docker.

Trên Windows, README nói cách dễ nhất là dùng bộ cài `.exe` trong Releases. Cách này phù hợp với người không muốn tự dựng Docker hoặc không quen terminal. macOS cũng có bộ cài `.dmg`; bản Apple Silicon và Intel được cung cấp riêng.

README còn có hướng dẫn riêng cho Docker Compose, local development, production build, truy cập LAN, backup và desktop app trong `docs/en/install/01-install.md`. Vì các lệnh chi tiết đó không xuất hiện trong phần tư liệu được cung cấp, mình không chép thêm lệnh cài đặt khác.

### Cài nhanh bằng Docker

Mở terminal trên máy có Docker rồi chạy đúng lệnh sau:

```bash
curl -fsSL https://freellmapi.co/install.sh | bash
```

`curl` tải script cài đặt, còn `bash` thực thi script đó. Script tự chuẩn bị thư mục, tạo encryption key, tải image và khởi động container. Nếu chạy lại, `.env` và encryption key được giữ lại, container được cập nhật lên tag `:latest` theo README.

Nếu terminal báo không tìm thấy `curl`, `bash` hoặc Docker chưa chạy, cách cài này chưa thể tiếp tục. Bạn cần mở Docker trước và kiểm tra môi trường terminal. Người dùng Windows có thể chuyển sang bộ cài `.exe` được README khuyến nghị.

### Cài bằng bộ cài desktop

Trên Windows, tải và chạy bộ cài `.exe` từ mục Releases của dự án. Trên macOS, dùng bộ cài `.dmg` tương ứng với Apple Silicon hoặc Intel. README cho biết desktop app chạy router và dashboard cục bộ từ menu bar hoặc tray.

Sau khi mở ứng dụng, tìm popover của tray để xem trạng thái và unified API key. README nói desktop app không yêu cầu tài khoản hoặc mật khẩu thiết lập; credential cần dùng là unified API key lấy từ tray popover. Nếu muốn tự build desktop app hoặc cần biết vị trí dữ liệu, xem phần desktop app trong `docs/en/install/01-install.md`.

### Mở dashboard và thêm key

Sau khi router chạy, mở trình duyệt tại địa chỉ sau:

```text
http://localhost:3001
```

Vào trang `Keys` và thêm API key của những provider bạn muốn dùng. Sau đó mở `Fallback Chain` để sắp xếp thứ tự hoặc tạo profile riêng. Bạn nên bắt đầu với một vài provider mà mình đã có key, rồi kiểm tra từng key trước khi thêm nhiều provider hơn.

Dashboard cũng là nơi lấy unified API key. Đây là key mà ứng dụng OpenAI-compatible sẽ gửi tới router. Provider key nằm trong cơ sở dữ liệu SQLite của router; ứng dụng bên ngoài không cần biết từng key riêng lẻ.

### Kết nối Claude Code hoặc coding agent

README cung cấp generator để cấu hình các agent được hỗ trợ. Ví dụ sau cấu hình Claude Code với router đang chạy trên cổng 3001:

```bash
npx freellmapi setup-claude --url http://localhost:3001 --api-key <unified-key>
```

Thay `<unified-key>` bằng unified key thật lấy từ dashboard. Không gõ nguyên dấu `< >` nếu terminal coi đó là ký hiệu đặc biệt. Generator đọc catalog, sao lưu cấu hình hiện có rồi hợp nhất cấu hình mới theo mô tả của README.

FreeLLMAPI cũng liệt kê Codex CLI, Gemini CLI, Cursor, Cline, Roo Code, OpenCode, Aider và nhiều agent khác. Mỗi công cụ có recipe riêng; nếu dùng Claude Code hoặc Codex, README còn nhắc đến `npx freellmapi launch` và `launch-codex` để giữ credential khỏi tệp cấu hình.

### Kết nối một OpenAI client

Trong ứng dụng Python đã có thư viện OpenAI, đặt `base_url` về router và dùng unified key:

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3001/v1",
    api_key="freellmapi-your-unified-key",
)

resp = client.chat.completions.create(
    model="auto",  # let the router pick; or "auto:fast", "auto:smart", a profile, or a model id
    messages=[{"role": "user", "content": "Summarise the fall of Rome in one sentence."}],
)
print(resp.choices[0].message.content)
print("Routed via:", resp.headers.get("x-routed-via"))
```

Bạn thay `freellmapi-your-unified-key` bằng key thật. `model="auto"` để router tự chọn; có thể thay bằng `auto:fast`, `auto:smart`, profile hoặc model id. Header `x-routed-via` cho biết model nào đã xử lý request.

## Kiểm tra đã chạy được chưa

Cách kiểm tra trực quan là mở `http://localhost:3001`. Nếu dashboard hiện ra, bạn có thể vào `Keys`, thêm provider key và lấy unified API key. Với desktop app, kiểm tra tray popover hiển thị router và thông tin thống kê request.

Sau khi kết nối client, gửi một request chat đơn giản với `model="auto"`. Kết quả mong đợi là nội dung nằm trong `resp.choices[0].message.content`, đồng thời header `x-routed-via` cho biết model đã được chọn.

Nếu provider key hợp lệ và còn quota, request sẽ được route tới một endpoint trong chain. Khi một endpoint bị rate-limit hoặc lỗi 5xx, router có thể thử endpoint kế tiếp. Bạn có thể xem health, usage, cache và routing metadata trong dashboard hoặc qua MCP để biết request đã đi qua đâu.

## Dùng vào việc thật

### Chủ shop tạo nội dung sản phẩm

Chủ shop có thể dùng một client OpenAI-compatible hiện có, trỏ base URL về `http://localhost:3001/v1` và chọn `model="auto"`. Prompt mẫu:

```text
Viết 5 mô tả ngắn cho sản phẩm bình giữ nhiệt 600 ml, giọng thân thiện, mỗi mô tả không quá 40 từ.
```

Router tự chọn model trong các provider đã thêm. Nếu model đầu tiên bị giới hạn, request có thể chuyển sang model khác trong fallback chain. Kết quả là shop dùng cùng một cấu hình client dù provider phía sau thay đổi.

### Nhân viên văn phòng tóm tắt tài liệu

Nhân viên có thể gọi Chat Completions từ ứng dụng nội bộ hoặc dùng một công cụ tương thích OpenAI. Prompt mẫu:

```text
Tóm tắt nội dung sau thành 5 ý chính, giữ nguyên số liệu và nêu rõ 3 việc cần làm tiếp theo:
[nội dung tài liệu]
```

Có thể đặt profile riêng cho công việc văn phòng và chọn `auto:smart` nếu muốn router ưu tiên chiến lược thông minh hơn. Nếu cuộc trò chuyện kéo dài, sticky session giúp giữ trên cùng model trong 30 phút; khi chuyển model, context handoff tùy chọn giúp giữ mạch.

### Dev mới thử nhiều model qua một SDK

Dev có thể viết ứng dụng bằng OpenAI SDK và không phải học 87 SDK riêng. Chỉ cần thay `base_url`, unified key và model. Khi cần kiểm tra model nào thực sự xử lý request, đọc header `x-routed-via` hoặc xem analytics trong dashboard.

Một prompt thử nghiệm có thể là:

```text
Giải thích đoạn TypeScript sau cho người mới, chỉ ra lỗi tiềm ẩn và đề xuất bản sửa ngắn gọn:
[dán đoạn mã]
```

Khi ứng dụng cần tool calling hoặc structured output, router có các bề mặt tương ứng của OpenAI và truyền các tham số theo khả năng từng provider. Bạn vẫn nên kiểm tra kết quả với provider và model cụ thể trước khi đưa vào quy trình quan trọng.

### Coding agent dùng pool model dự phòng

Người dùng Claude Code có thể chạy lệnh setup của README, sau đó để agent gọi router cục bộ. Với Codex CLI, Gemini CLI, Cursor, Cline, Roo Code, OpenCode hoặc Aider, dùng recipe tương ứng trong tài liệu dự án và cung cấp cùng unified key.

Cách này phù hợp khi bạn muốn agent tiếp tục hoạt động nếu một model bị giới hạn. Router quản lý chuỗi fallback và key rotation ở phía sau, còn agent chỉ nhìn thấy endpoint chung.

> Một endpoint chung biến việc thử nhiều LLM miễn phí từ bài toán quản lý hàng chục key thành một cấu hình có thể kiểm soát.
>
> — Ông T

## Lỗi hay gặp và cách xử lý

### Dashboard không mở được ở cổng 3001

Thường là router hoặc container chưa khởi động, Docker chưa chạy, hoặc cổng đang bị chương trình khác dùng. Kiểm tra lại cửa sổ terminal, trạng thái Docker và cách cài đã chọn. Nếu dùng desktop app, mở lại ứng dụng và kiểm tra tray popover.

### Request bị từ chối vì key không hợp lệ

Phân biệt provider key với unified API key. Provider key được thêm trong trang `Keys`; ứng dụng bên ngoài phải dùng unified key do dashboard cấp. Nếu dùng Claude Code hoặc agent generator, chạy lại lệnh với đúng giá trị thay cho `<unified-key>`.

### Request lỗi 429 hoặc hết quota

Một provider có thể đã chạm giới hạn miễn phí. Kiểm tra usage, key health và Fallback Chain trong dashboard, sau đó thêm provider khác hoặc sắp xếp lại chain. Router có automatic failover, nhưng chỉ hoạt động nếu còn endpoint và key hợp lệ trong chuỗi.

### Model không xuất hiện hoặc hành vi tương thích chưa đúng

Catalog của bản miễn phí là snapshot theo tháng nên model mới có thể xuất hiện chậm hơn live feed. Router cũng chỉ truyền tham số theo khả năng của từng provider. Hãy kiểm tra catalog, chọn model khác hoặc dùng model id đã biết là tương thích với chức năng cần thiết.

### Vô tình làm lộ key

Không đưa provider key hoặc unified key vào Git, prompt, MCP URL hay tệp cấu hình chia sẻ. README nêu rõ key nên được quản lý ở router; với ChatGPT qua Secure MCP Tunnel, base URL và bearer authentication nằm trong cấu hình tunnel-client.

## Có nên dùng không

FreeLLMAPI đáng dùng nếu bạn muốn một endpoint chung cho nhiều LLM miễn phí, cần fallback tự động hoặc thường xuyên thử các model khác nhau. Dashboard, unified key, tracking quota, nhiều giao diện API và khả năng tương thích với coding agent giúp giảm đáng kể công việc cấu hình thủ công.

Điểm mạnh khác là thiết kế local-first: provider key ở trong SQLite được mã hóa, request đi từ máy của bạn tới các provider đã bật, và catalog server không thấy prompt, completion hay provider key. MIT license cũng phù hợp với việc tự triển khai và tùy chỉnh.

Giới hạn cần nhớ là “miễn phí” phụ thuộc quota và chính sách của từng provider. Router không biến các provider thành dịch vụ ổn định vô hạn. Bản free còn nhận catalog chậm hơn live feed; premium là lựa chọn trả phí nếu bạn cần catalog cập nhật trong ngày. README cũng định vị dự án cho mục đích thử nghiệm cá nhân.

Nếu bạn chỉ dùng một provider, cần SLA rõ ràng, cần hỗ trợ doanh nghiệp hoặc muốn giảm tối đa số lớp trung gian, dùng SDK và API chính thức của provider có thể đơn giản hơn. Nếu muốn chạy model hoàn toàn cục bộ, bạn có thể dùng custom provider trỏ tới Ollama, llama.cpp, LM Studio hoặc vLLM, nhưng phần model và tài nguyên máy khi đó vẫn do bạn tự đảm nhiệm.

## Câu hỏi thường gặp

### FreeLLMAPI có miễn phí hoàn toàn không?

Router được phát hành theo giấy phép MIT và vẫn miễn phí. Tuy nhiên, provider key, quota và chính sách sử dụng thuộc về từng nhà cung cấp. Dự án có gói premium cho live catalog; README nêu router không bị khóa tính năng vì không mua premium.

### Có cần GPU để chạy FreeLLMAPI không?

README không yêu cầu GPU cho router. Router có thể chạy trên Windows, macOS, Linux và máy ARM nhỏ. Nếu bạn kết nối custom provider chạy model cục bộ như Ollama, llama.cpp, LM Studio hoặc vLLM thì yêu cầu phần cứng phụ thuộc vào model đó.

### FreeLLMAPI có chạy được trên Windows không?

Có. README nói dự án chạy ở nơi Node 20+ chạy được và cung cấp bộ cài desktop `.exe` cho Windows. Đây là cách dễ nhất trên Windows theo tài liệu dự án.

### Dữ liệu và API key có an toàn không?

Provider key được mã hóa bằng AES-256-GCM trong SQLite và chỉ giải mã trong bộ nhớ khi cần. Dự án định vị là local-first; request đi từ máy của bạn tới các provider đã bật. Bạn vẫn phải tự bảo vệ unified key và không đưa key vào Git hoặc MCP URL.

### Có dùng được với Claude Code, Codex CLI và Cursor không?

Có. README liệt kê Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, Roo Code, OpenCode, Aider và nhiều client khác. Dự án có generator setup cho agent, trong đó có lệnh cấu hình Claude Code.

### FreeLLMAPI khác gì so với việc gọi thẳng một API LLM?

FreeLLMAPI gom nhiều provider sau một endpoint OpenAI-compatible, theo dõi quota và tự chuyển dự phòng khi provider bị giới hạn hoặc lỗi. Nếu bạn chỉ dùng một provider và cần SLA rõ ràng, gọi thẳng API chính thức có thể đơn giản hơn.

### Bản miễn phí có catalog model mới ngay không?

Router tự đồng bộ catalog đã ký hai lần mỗi ngày, nhưng bản miễn phí dùng monthly snapshot. Vì vậy model mới có thể đến chậm hơn live feed; premium nhận catalog live theo mô tả của README.
