Experiential: cổng API gom nhiều mô hình AI, kiểm soát chi phí — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
Experiential là một gateway và router mã nguồn mở cho các quy trình dùng agent AI. Nó gom mô hình hosted, BYOK và local sau một API tương thích OpenAI, cho phép đặt ngân sách theo người dùng, và học từ traffic để tối ưu chi phí. Cài bằng pip install experiential rồi chạy exp, cần Python 3.12 trở lên.
Experiential là một cổng API (gateway) mã nguồn mở cho các quy trình dùng agent AI. Nó đứng giữa ứng dụng của bạn và các nhà cung cấp mô hình, rồi cho bạn gọi mô hình hosted, mô hình dùng key của chính bạn (BYOK) và mô hình chạy local qua một API duy nhất, tương thích OpenAI.
Nếu bạn đang dùng nhiều công cụ AI cùng lúc (Claude Code, Cursor, Codex, script tự viết…) và bắt đầu thấy khó kiểm soát ai dùng mô hình nào, tốn bao nhiêu tiền, thì repo này dành cho bạn. Nó cũng hợp với lập trình viên muốn đổi nhà cung cấp mô hình mà không phải sửa code ở khắp nơi.
Điểm đáng giá nhất: ngoài việc làm cổng trung gian, Experiential còn biến traffic thật của bạn thành một router, hoặc một mô hình riêng, tối ưu theo chất lượng, tốc độ và chi phí. Hiện repo có khoảng 16.700 sao và 302 fork, giấy phép Apache-2.0, viết chủ yếu bằng Python.
experientiallabs/experiential
Cổng API mã nguồn mở tương thích OpenAI: gom mô hình cloud, BYOK và local vào một chỗ, giới hạn ngân sách, rồi tối ưu router từ traffic thật.
I.Experiential làm được gì
A.Một API cho nhiều loại mô hình
Bạn gọi mô hình hosted, mô hình dùng key riêng và mô hình local qua cùng một địa chỉ kiểu OpenAI. Lợi ích thực tế: code của bạn chỉ cần biết một cách gọi. Muốn đổi mô hình thì đổi cấu hình ở gateway, không đụng vào ứng dụng.
B.Tên gọi chung (alias) cho mô hình
Khi cài lần đầu, bạn đặt một tên công khai như opus-5. Ứng dụng chỉ gọi tên đó. Phía sau muốn trỏ sang mô hình nào là việc của gateway.
C.Kiểm soát người dùng, agent và ngân sách
README nói bạn có thể quy định ai và agent nào được dùng mô hình nào, cho tác vụ nào, và được tiêu tối đa bao nhiêu. Trình cài đặt ban đầu còn gợi ý sẵn mức ngân sách mặc định $50.00 cho lệnh. Với người quản lý nhóm, đây là cách để tránh hóa đơn bất ngờ.
D.Gateway tự chạy trên máy bạn hoặc dùng bản hosted
Bạn có thể chạy gateway local bằng lệnh exp. Nếu không muốn tự chạy, có nền tảng hosted với API tại https://api.experientiallabs.ai/v1, hỗ trợ cả OpenAI lẫn Anthropic Messages. Ở bản hosted, bạn có thể nối key của OpenAI, Anthropic, Gemini, Azure, Bedrock, Fireworks hoặc OpenRouter theo kiểu BYOK.
E.Agent lập trình và làm việc văn phòng có sẵn
Lệnh exp code chạy exp-code, một agent mã nguồn mở xây trên Pi, dùng cho cả lập trình lẫn việc văn phòng (cowork). Nó dùng gateway bạn đang chạy hoặc gateway hosted sau khi exp login.
F.Thu traffic và tối ưu từ traffic
Bạn có thể thu trace từ agent hiện tại (định dạng OpenTelemetry), dựng một dự án mô phỏng rồi tối ưu router trên đó. Sau đó có thể tinh chỉnh một mô hình mã nguồn mở của riêng bạn bằng Tinker. Đây là phần khác biệt so với một gateway thông thường.
II.Cần chuẩn bị gì
Theo tư liệu của repo:
- Python 3.12 trở lên.
pyproject.tomlyêu cầu>=3.12. - Một cửa sổ terminal. Mọi thao tác đều qua dòng lệnh.
- Key của nhà cung cấp mô hình nếu bạn muốn dùng mô hình của họ. File
.env.exampleliệt kê tên các biến nhưOPENAI_API_KEY,ANTHROPIC_API_KEY,OPENROUTER_API_KEY,AZURE_OPENAI_API_KEY, nhóm biến AWS,TINKER_API_KEY,E2B_API_KEY,EXA_API_KEY… Bạn không cần điền tất cả. Trình cài đặt sẽ hỏi bạn chọn nhà cung cấp nào. - Node.js 22.19 trở lên nếu muốn dùng
exp code. - macOS và Python 3.13 trở lên nếu muốn dùng tính năng
exp capture(thu traffic từ ứng dụng desktop). Tính năng này còn thử nghiệm. - Tài khoản trên nền tảng hosted chỉ khi bạn chọn dùng gateway hosted.
README không nói gì về yêu cầu GPU hay dung lượng ổ đĩa, nên mình không đưa ra con số nào.
III.Cài đặt từng bước
- Kiểm tra PythonChắc chắn máy có Python 3.12 trở lên
- Cài góiChạy pip install experiential
- Chạy lần đầuGõ exp, đi qua trình hướng dẫn chọn nhà cung cấp, mô hình, tên alias
- Lưu keyChép khoá dùng một lần mà trình cài đặt in ra
- Gửi thửDùng curl gọi gateway ở cổng 8000
A.Kiểm tra phiên bản Python
Mở terminal (PowerShell hoặc Terminal trên macOS/Linux) và kiểm tra phiên bản:
python --versionNếu kết quả thấp hơn 3.12, bạn cần cài bản Python mới hơn trước. Đây là chỗ người mới hay vấp nhất, vì máy có thể cài sẵn Python cũ.
B.Cài gói experiential
Tên gói Python là experiential. Chạy đúng lệnh trong README:
pip install experientialLệnh này tải gói về và tạo lệnh exp để bạn dùng trong terminal. Bạn không cần tải mã nguồn từ GitHub để dùng bản cài này.
C.Chạy lần đầu và đi qua trình hướng dẫn
expLần chạy đầu tiên, trình hướng dẫn (setup wizard) sẽ cho bạn chọn nhà cung cấp, mô hình và mức reasoning effort. Nó lưu lại kết nối của mọi nhà cung cấp bạn đã chọn. Sau đó nó hiện giá trị mặc định cho tên alias công khai, danh tính và ngân sách $50.00 cho lệnh, rồi in ra một khoá dùng một lần.
Khoá này chỉ hiện một lần, nên hãy chép lại ngay vào nơi an toàn.
Khoá gateway chỉ in ra một lần. Đừng dán nó vào chat, ảnh chụp màn hình hay kho mã công khai. Key của OpenAI, Anthropic… mà bạn nhập vào cũng vậy. Hãy đặt ngân sách vừa phải khi mới thử.
D.Đặt khoá vào biến môi trường và gửi yêu cầu thử
Chọn một alias như opus-5, lấy khoá đã được cấp, rồi gửi yêu cầu. Lệnh dưới đây là bản trong README, viết cho shell kiểu bash:
export EXP_GATEWAY_KEY=...
curl http://127.0.0.1:8000/v1/chat/completions \
-H "Authorization: Bearer $EXP_GATEWAY_KEY" \
-H 'Content-Type: application/json' \
-d '{"model":"opus-5","messages":[{"role":"user","content":"Help me"}]}'Thay dấu ... bằng khoá thật của bạn. Địa chỉ 127.0.0.1:8000 nghĩa là gateway chạy ngay trên máy bạn. Giữ cửa sổ đang chạy exp mở, rồi mở thêm một cửa sổ terminal khác để chạy lệnh curl.
README chỉ đưa cú pháp bash. Nếu bạn dùng Windows, chưa có thông tin chính thức về cách chạy riêng cho PowerShell. Bạn nên xem SETUP.md và thư mục docs/ trong repo.
E.Hoặc dùng gateway hosted
Nếu không muốn chạy gateway trên máy, README trỏ sang SETUP.md. File này có các prompt để bạn đưa cho agent lập trình của mình (Claude Code, Cursor, Codex…) rồi để agent làm giúp. Có bốn prompt: tải trace lên làm telemetry, nối key BYOK, bắt đầu gọi mô hình qua gateway bằng key dạng xpl_, và quy trình onboarding đầy đủ. Mình không chép nội dung các prompt ở đây vì README không đưa nguyên văn. Hãy mở SETUP.md để lấy.
IV.Kiểm tra đã chạy được chưa
Có ba dấu hiệu theo tư liệu:
- Gõ
expxong, trình hướng dẫn chạy và in ra một khoá dùng một lần. - Lệnh
curlở trên trả về phản hồi JSON theo kiểu OpenAI từ mô hình bạn đã chọn, thay vì báo lỗi kết nối. - Nếu dùng
exp code, giao diện terminal tương tác mở lên.
Nếu muốn kiểm tra riêng cấu hình telemetry, dùng lệnh sau:
exp config telemetry statusREADME không mô tả chính xác nội dung phản hồi mẫu, nên bạn chỉ cần thấy có câu trả lời từ mô hình là gateway đã hoạt động.
V.Dùng vào việc thật
A.Lập trình viên đổi nhà cung cấp mà không sửa code
Bối cảnh: bạn có một ứng dụng nhỏ gọi mô hình AI và không muốn bị trói vào một hãng. Cách làm: để ứng dụng gọi gateway local với alias bạn đặt (ví dụ opus-5), như lệnh curl ở phần cài đặt. Khi muốn đổi mô hình phía sau, bạn chỉnh ở gateway. Kết quả: code ứng dụng giữ nguyên, bạn quản lý mô hình ở một chỗ.
Đặt tên gọi chung cho mô hình, rồi để gateway lo phần còn lại.
Ông T
B.Trưởng nhóm muốn giới hạn chi tiêu AI
Bối cảnh: cả nhóm dùng chung key và cuối tháng không ai biết tiền đi đâu. Cách làm: dùng gateway làm cổng duy nhất, đặt danh tính và ngân sách ngay trong trình hướng dẫn (mặc định gợi ý $50.00). README nói bạn có thể kiểm soát người dùng và agent nào được dùng mô hình nào, cho tác vụ nào. Chi tiết cách cấu hình cho từng người nằm trong tài liệu của dự án, bạn xem ở thư mục docs/. Kết quả: mỗi người dùng khoá riêng thay vì chia sẻ key gốc.
C.Nhân viên văn phòng nhờ agent tổng hợp file
Bối cảnh: bạn có file sales.csv và cần một báo cáo Word. Cách làm: đảm bảo máy có Node.js 22.19 trở lên và gateway đang chạy, rồi gõ lệnh mẫu trong README:
exp code -p "Summarize sales.csv into report.docx"Chữ trong ngoặc kép là yêu cầu bằng tiếng Anh. Bạn có thể thử viết yêu cầu tiếng Việt, nhưng README chưa nói rõ chất lượng sẽ thế nào, nên hãy kiểm tra kỹ kết quả. Muốn làm việc qua giao diện tương tác thì chỉ cần gõ exp code. Kết quả mong đợi theo ví dụ: một file report.docx tóm tắt dữ liệu.
D.Đội dùng agent tối ưu chi phí từ traffic thật
Bối cảnh: agent hỗ trợ khách hàng của bạn gọi mô hình đắt cho cả những câu hỏi đơn giản. Cách làm theo README: thu trace OpenTelemetry từ agent hiện tại. Nếu chỉ muốn thử, tải bộ dữ liệu mẫu công khai:
curl -L -o traces.otel.jsonl \
https://huggingface.co/datasets/experiential-labs/wmo-terminal-tasks-traces/resolve/540883e451dc13d34fb50fdd36b143cb0f1fb0db/traces.otel.jsonlSau đó dựng dự án. Lệnh này hướng dẫn bạn chọn nhà cung cấp, mô hình, ngân sách và hỏi file trace:
exp build support-agentKhi đã có traffic đi qua router, bạn có thể tinh chỉnh một mô hình mã nguồn mở của riêng bạn bằng Tinker:
exp optimize model support-agentFile .env.example có liệt kê biến TINKER_API_KEY. Bạn nên xem tài liệu để biết khi nào cần đến nó. Sau khi có router, bạn có thể gọi nó từ Python:
import exp
with exp.load_router("my-project") as client:
response = client.chat.completions.create(
model="my-project",
messages=[{"role": "user", "content": "hello"}],
)Kết quả: một router được tối ưu theo chất lượng, tốc độ và chi phí dựa trên dữ liệu của chính bạn.
VI.Lỗi hay gặp và cách xử lý
A.pip báo không tìm thấy gói hoặc không tương thích
Nguyên nhân hay gặp nhất là Python cũ hơn 3.12. Chạy python --version để kiểm tra. Nếu thấp hơn, hãy cài Python mới hơn rồi chạy lại pip install experiential.
B.Gõ exp báo không nhận ra lệnh
Sau khi cài, terminal có thể chưa thấy lệnh mới. Hãy đóng terminal, mở lại và thử lần nữa. Nếu vẫn lỗi, kiểm tra xem pip bạn dùng có đúng là của Python 3.12 trở lên không. README chưa nói gì thêm về lỗi này.
C.curl báo không kết nối được tới 127.0.0.1:8000
Gateway chưa chạy hoặc bạn đã tắt cửa sổ đang chạy exp. Hãy mở lại, để nó chạy, rồi gửi yêu cầu từ một cửa sổ terminal khác.
D.Gateway từ chối khoá (lỗi xác thực)
Khoá bị chép thiếu, sai, hoặc biến EXP_GATEWAY_KEY chưa được đặt trong cửa sổ bạn đang dùng. Biến môi trường chỉ có hiệu lực trong cửa sổ terminal bạn đặt nó. Khoá chỉ hiện một lần, nên nếu mất khoá, hãy xem tài liệu của dự án để biết cách cấp lại.
E.exp code không chạy hoặc exp capture không dùng được
exp code cần Node.js 22.19 trở lên. exp capture cần macOS, Python 3.13 trở lên, và phải được cho phép cài tiện ích mở rộng cùng chứng chỉ. README cũng nói rõ capture còn thử nghiệm và độ ổn định mạng trên macOS vẫn đang được điều tra. Với tính năng này, bạn nên thử trên máy không chứa dữ liệu nhạy cảm trước.
VII.Có nên dùng không
Điểm mạnh. Một API duy nhất cho nhiều loại mô hình. Có kiểm soát người dùng, agent và ngân sách. Chạy được trên máy bạn hoặc dùng bản hosted. Giấy phép Apache-2.0, repo vẫn được cập nhật trong vài tháng gần đây. Và quan trọng nhất, nó có đường đi từ traffic thật đến router hoặc mô hình riêng, điều mà các gateway đơn giản không có.
Giới hạn. Repo chia thành nhiều phần (gateway, agent, capture, tối ưu), nên người mới sẽ thấy khá nhiều thứ. Bạn nên bắt đầu chỉ với pip install experiential và exp, các phần còn lại để sau. Phần capture còn thử nghiệm và yêu cầu macOS. README viết bằng tiếng Anh và ví dụ lệnh theo kiểu bash, nên người dùng Windows có thể phải tự tìm hiểu thêm.
Về dữ liệu. README cho biết telemetry sản phẩm ẩn danh qua PostHog được bật mặc định. Nó không gồm prompt, trace, đường dẫn, tên mô hình, thông tin xác thực hay nội dung khách hàng. Bạn có thể tắt bằng exp config telemetry disable. Tuỳ chọn được lưu trong .exp/settings.toml.
Khi nào chọn cách khác. Nếu bạn chỉ dùng một mô hình của một hãng, không cần quản lý ngân sách và không quan tâm chi phí, gọi thẳng API của hãng đó sẽ đơn giản hơn. Còn nếu bạn dùng nhiều mô hình, nhiều người, nhiều agent và muốn nhìn thấy tiền đi đâu, Experiential rất đáng thử.
Câu hỏi thường gặp
Experiential có miễn phí không?
Repo là mã nguồn mở với giấy phép Apache-2.0, nên bạn cài và chạy gateway local không mất tiền cho phần mềm. Tuy nhiên, bạn vẫn phải trả tiền cho nhà cung cấp mô hình nếu dùng key của họ. README không nêu bảng giá của nền tảng hosted, nên chưa có thông tin về chi phí đó.
Cần Python phiên bản nào để cài?
File pyproject.toml yêu cầu Python 3.12 trở lên. Riêng tính năng exp capture cần Python 3.13 trở lên và macOS. Nếu dùng exp code thì cần thêm Node.js 22.19 trở lên.
Có cần GPU không?
README không nói đến yêu cầu GPU cho gateway. Phần tinh chỉnh mô hình dùng Tinker theo README, nhưng tư liệu không nêu chi tiết phần cứng. Bạn nên xem thư mục docs/ trong repo để biết thêm.
Chạy được trên Windows không?
README không ghi rõ Windows có được hỗ trợ hay không, và các lệnh ví dụ viết theo kiểu bash. Riêng exp capture thì yêu cầu rõ là macOS. Với Windows, bạn nên xem SETUP.md và docs/ trước khi cài.
Dữ liệu và prompt của tôi có bị gửi đi đâu không?
Theo README, telemetry sản phẩm ẩn danh qua PostHog bật mặc định và không chứa prompt, trace, đường dẫn, tên mô hình, thông tin xác thực hay nội dung khách hàng. Bạn tắt được bằng exp config telemetry disable. Khi dùng gateway local, yêu cầu của bạn đi tới nhà cung cấp mô hình mà bạn đã chọn.
Experiential khác gì việc gọi thẳng API của OpenAI hay Anthropic?
Gọi thẳng thì bạn làm việc với từng hãng riêng. Experiential đặt một cổng ở giữa để gom nhiều mô hình vào một API kiểu OpenAI, kiểm soát ai được dùng gì và chi bao nhiêu, rồi học từ traffic để tối ưu. README không so sánh trực tiếp với từng công cụ cụ thể khác.
Dùng gateway hosted thay vì tự chạy được không?
Được. README nói nền tảng hosted phục vụ cùng API tương thích OpenAI và Anthropic Messages tại api.experientiallabs.ai/v1. Các prompt hướng dẫn nằm trong file SETUP.md để bạn đưa cho agent lập trình của mình làm giúp.


