experiential: gateway AI đa mô hình tiết kiệm chi phí — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về experientiallabs/experiential — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: 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à gateway và router mã nguồn mở cho workflow agent, hỗ trợ mô hình hosted, BYOK và local qua API tương thích OpenAI. Bạn có thể chạy local bằng Python hoặc dùng gateway hosted; phần cài local khá gọn, còn các tính năng tối ưu cần thêm dữ liệu trace và cấu hình nhà cung cấp.
Experiential là gateway và router mã nguồn mở cho các workflow agent. Repo gom nhiều mô hình hosted, BYOK và local vào một API tương thích OpenAI, để ứng dụng hoặc coding agent không phải tích hợp từng nhà cung cấp riêng.
Bạn có thể chạy gateway ngay trên máy bằng gói Python experiential, dùng gateway hosted, hoặc gọi một project router đã được huấn luyện từ Python. Repo hiện có khoảng 16775 sao và 302 fork, dùng giấy phép Apache-2.0. Điểm đáng giá nhất là hệ thống có thể học từ traffic thực tế để cân bằng chất lượng, tốc độ và chi phí.
Công cụ này hợp với đội phát triển sản phẩm AI, người dùng coding agent, nhóm vận hành nhiều nhà cung cấp mô hình và doanh nghiệp muốn kiểm soát quyền truy cập. Người mới vẫn có thể thử gateway local, nhưng các phần như telemetry, tối ưu router và fine-tune cần hiểu thêm về API key, trace và ngân sách.
experientiallabs/experiential
Gateway Python tương thích OpenAI giúp dùng nhiều mô hình, kiểm soát chi phí và tối ưu router từ dữ liệu truy cập.
I.Experiential làm được gì
- Gom nhiều mô hình sau một APIGateway cung cấp API tương thích OpenAI và có hỗ trợ Anthropic Messages ở gateway hosted. Ứng dụng của bạn có thể tiếp tục gọi các route quen thuộc thay vì viết lại tích hợp cho từng nhà cung cấp.
- Hỗ trợ hosted, BYOK và local modelBạn có thể dùng mô hình do nền tảng cung cấp, kết nối key của chính mình hoặc dùng mô hình local. BYOK phù hợp khi doanh nghiệp đã có tài khoản OpenAI, Anthropic, Gemini, Azure, Bedrock, Fireworks hoặc OpenRouter.
- Kiểm soát người dùng, agent và ngân sáchGateway cho phép kiểm soát ai được dùng model nào, dùng cho trường hợp nào và được chi bao nhiêu. Khi có nhiều nhân viên hoặc nhiều coding agent cùng gọi API, lớp kiểm soát này giúp giảm rủi ro dùng nhầm model đắt tiền.
- Tạo public alias cho modelTrong lần chạy đầu, trình hướng dẫn hỏi provider, model và reasoning effort, sau đó cho bạn đặt alias công khai như
opus-5. Ứng dụng chỉ cần gọi alias đó thay vì phụ thuộc trực tiếp vào tên nội bộ của nhà cung cấp. - Tối ưu router từ trafficBạn có thể thu thập OpenTelemetry traces, xây dựng một project rồi tối ưu router dựa trên dữ liệu thật. Mục tiêu là chọn cách chạy tốt hơn về chất lượng, tốc độ hoặc chi phí.
- Tải router đã fitted vào PythonHàm
exp.load_routermở một client OpenAI chính thức nhưng đi qua private gateway riêng của project. Cách này phù hợp khi bạn muốn nhúng router vào một chương trình Python hiện có. - Chạy coding agent qua
exp codeexp codechạy exp-code, một coding và cowork agent mã nguồn mở xây trên Pi. Agent có thể dùng gateway local đang chạy hoặc gateway hosted sau khi bạn đăng nhập bằngexp login. - Thu thập trace từ một số ứng dụng desktopTính năng
exp captuređược thiết kế để thu thập trace được hỗ trợ từ ứng dụng desktop Codex và Claude Code, trong khi request vẫn đi trực tiếp tới OpenAI hoặc Anthropic. Đây là tính năng thử nghiệm và hiện chỉ dành cho macOS. - Telemetry tổng hợp có thể bật hoặc tắtProduct telemetry ẩn danh từ PostHog được bật mặc định. README nói dữ liệu này không gồm prompt, trace, action, observation, path, model name, credential hoặc nội dung khách hàng thô; tùy chọn được lưu cục bộ trong
.exp/settings.toml.
II.Cần chuẩn bị gì
- Máy có Python từ 3.12 trở lên để cài gói
experientialtheo yêu cầu trongpyproject.toml. - Một terminal để chạy lệnh cài đặt và khởi động gateway.
- Provider, model và thông tin kết nối tương ứng nếu bạn muốn gateway gọi một nhà cung cấp mô hình. README không buộc một provider cụ thể cho lần thử local, vì trình hướng dẫn sẽ hỏi lựa chọn của bạn.
- API key phù hợp nếu bạn dùng BYOK. File
.env.examplecó tên biến cho Anthropic, OpenAI, OpenRouter, Azure OpenAI, AWS/Bedrock, Tinker, E2B, Exa và các kết nối của Experiential. README không cung cấp giá trị key mẫu. - Node.js 22.19 trở lên nếu muốn chạy
exp code. - macOS, Python 3.13 trở lên, cùng quyền phê duyệt extension và certificate nếu muốn dùng
exp capture. - Một file OpenTelemetry trace nếu muốn xây project từ traffic. Bạn cũng có thể dùng dataset terminal-tasks OTLP công khai được README chỉ ra.
README không nói rằng bạn cần GPU cho gateway cơ bản. README cũng không mô tả chi tiết yêu cầu phần cứng cho từng model local, nên hãy kiểm tra cấu hình của provider hoặc model bạn chọn trước khi triển khai.
III.Cài đặt từng bước
- Cài gói PythonCài experiential vào môi trường Python
- Khởi động gatewayChạy trình hướng dẫn và chọn provider, model, alias
- Lưu khóa một lầnGhi lại key được in ra sau lần chạy đầu
- Gửi request thửGọi endpoint OpenAI-compatible trên loopback
- Chạy coding agentDùng exp code nếu đã cài Node.js phù hợp
A.Cài gói Python
Mở PowerShell hoặc terminal tại thư mục bạn muốn làm việc. README cung cấp lệnh cài trực tiếp từ Python Package Index:
pip install experientialLệnh này cài gói Python có tên experiential. Nếu máy có nhiều bản Python, hãy bảo đảm terminal đang dùng đúng bản Python từ 3.12 trở lên. README không ghi thêm lệnh tạo virtual environment, nên phần đó không nên tự suy đoán là yêu cầu bắt buộc.
Nếu bạn muốn lấy mã nguồn để xem hoặc phát triển, có thể clone repo rồi đi vào thư mục:
git clone https://github.com/experientiallabs/experiential.git
cd experientialCách clone này là bước phổ thông. Cách chạy người dùng cuối được README mô tả qua gói pip install experiential; mã nguồn có pyproject.toml và uv.lock cho phần phát triển.
B.Khởi động gateway local
Sau khi cài xong, chạy lệnh sau:
expỞ lần chạy đầu, setup wizard sẽ hỏi provider, model và reasoning effort. Các kết nối provider đã chọn sẽ được lưu. Trình hướng dẫn cũng hiển thị mặc định cho public alias, identity và ngân sách command $50.00, rồi in ra một key dùng một lần.
Bạn nên chọn một public alias dễ nhớ, chẳng hạn opus-5, đúng như ví dụ trong README. Hãy giữ lại key được in trên màn hình. Key này sẽ được dùng để xác thực request tới gateway local.
README cũng cho phép khởi động bằng:
exp runGateway local phục vụ API trên loopback. Điều này có nghĩa endpoint mẫu nằm ở http://127.0.0.1:8000; bạn cần để terminal chạy gateway mở trong lúc gửi request.
C.Gửi request đầu tiên
Đặt key đã nhận vào biến môi trường rồi gọi endpoint chat completions:
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"}]}'Trên PowerShell, cú pháp đặt biến môi trường khác với Bash. README chỉ đưa lệnh export ở trên, nên nếu bạn dùng Windows PowerShell, hãy chuyển giá trị key vào cơ chế biến môi trường tương ứng của PowerShell trước khi chạy request. Quan trọng nhất là tên biến phải là EXP_GATEWAY_KEY, model trong request phải khớp public alias bạn đã chọn, và gateway vẫn đang chạy.
D.Dùng gateway hosted
Nếu không muốn chạy gateway local, README hướng dẫn dùng hosted platform. Nền tảng này cung cấp cùng API tương thích OpenAI và Anthropic Messages tại https://api.experientiallabs.ai/v1. Quy trình hosted gồm tạo account bằng email, kết nối provider key của bạn, gọi API bằng key có tiền tố xpl_, rồi có thể đổi coding agent sang gateway.
README cũng nói file SETUP.md có các prompt copy-paste để giao việc thiết lập cho Claude Code, Cursor, Codex và các coding agent tương tự. Tư liệu được cung cấp không chép nội dung cụ thể của SETUP.md, nên không nên tự thêm tên biến, lệnh đăng nhập hoặc tham số ngoài những gì README đã nêu.
E.Chạy coding agent
Nếu muốn dùng exp-code, cần Node.js 22.19 trở lên. Gateway local phải đang chạy, hoặc bạn cần đăng nhập để dùng hosted gateway. Các lệnh chính là:
exp code # interactive terminal UI
exp code -p "Summarize sales.csv into report.docx"Lệnh đầu mở giao diện terminal tương tác. Lệnh thứ hai gửi prompt trực tiếp để tóm tắt file sales.csv thành báo cáo report.docx. Mọi argument được chuyển cho exp-code, nên các chế độ print, JSON và RPC của exp-code cũng hoạt động thông qua exp code.
IV.Kiểm tra đã chạy được chưa
Gateway local được xem là đã chạy khi lệnh exp hoàn tất setup wizard và terminal tiếp tục giữ tiến trình gateway. Bạn cần thấy key dùng một lần được in ra, đồng thời có public alias để dùng trong request.
Bước kiểm tra thực tế là gửi request tới:
http://127.0.0.1:8000/v1/chat/completionsRequest phải có header Authorization: Bearer với key vừa nhận, header nội dung JSON và trường model trùng alias đã chọn. Nếu request trả về phản hồi chat thay vì lỗi xác thực hoặc lỗi kết nối, gateway local đã nhận request đúng.
Với Python, kiểm tra router bằng đoạn sau sau khi bạn đã có project router phù hợp:
import exp
with exp.load_router("my-project") as client:
response = client.chat.completions.create(
model="my-project",
messages=[{"role": "user", "content": "hello"}],
)Nếu muốn kiểm tra coding agent, chạy exp code và chờ giao diện terminal tương tác xuất hiện. Nếu dùng exp capture, hãy nhớ đây là tính năng thử nghiệm; việc lệnh chạy được chưa đồng nghĩa mọi kết nối mạng trên macOS sẽ ổn định.
V.Dùng vào việc thật
A.Chủ shop muốn tự động hóa báo cáo bán hàng
Chủ shop có file sales.csv và muốn biến dữ liệu thành báo cáo Word. Sau khi gateway và exp-code sẵn sàng, có thể chạy:
exp code -p "Summarize sales.csv into report.docx"Kết quả mong đợi là agent đọc file và thực hiện yêu cầu tạo báo cáo thông qua gateway. Đây là ví dụ trực tiếp trong README, nên phù hợp để kiểm tra nhanh khả năng xử lý file của agent.
B.Nhân viên văn phòng muốn dùng một alias ổn định
Một nhân viên đang có ứng dụng gọi API chat nhưng không muốn sửa code mỗi khi đổi provider. Trong setup wizard, họ chọn provider và model, đặt alias như opus-5, rồi cấu hình ứng dụng gọi /v1/chat/completions với model alias đó.
Lợi ích là ứng dụng chỉ cần biết một endpoint và một tên model công khai. Quyền truy cập, provider và budget được kiểm soát ở gateway, thay vì rải nhiều thông tin kết nối trong từng ứng dụng.
C.Dev muốn thử router bằng dữ liệu trace
Một dev có trace OpenTelemetry từ agent hỗ trợ khách hàng. Họ có thể tải dataset mẫu trước:
curl -L -o traces.otel.jsonl \
https://huggingface.co/datasets/experiential-labs/wmo-terminal-tasks-traces/resolve/540883e451dc13d34fb50fdd36b143cb0f1fb0db/traces.otel.jsonlSau đó chạy:
exp build support-agentLệnh build sẽ hỏi provider, model, budget và file trace. Kết quả là một project mô phỏng từ trace của agent để tối ưu router. Cách này giúp dev thử quy trình trước khi đưa dữ liệu traffic thật vào.
D.Đội kỹ thuật muốn kiểm soát chi phí nhiều agent
Một đội có Claude Code, Cursor, Codex hoặc Aider cùng dùng model. Họ có thể kết nối key của mình ở gateway hosted, gọi API bằng key xpl_, rồi repoint các coding agent về gateway. Từ đó, team có một lớp trung tâm để kiểm soát model, use case và ngân sách.
Sau khi có thêm trace, team có thể chạy:
exp optimize model support-agentREADME mô tả lệnh này dùng để fine-tune một open source model mà bạn sở hữu, thông qua Tinker. Vì vậy, đây là bước nâng cao; không cần chạy nếu mục tiêu ban đầu chỉ là dùng gateway.
Một gateway thống nhất giúp bạn biến traffic AI thành dữ liệu để chọn model tốt hơn, nhanh hơn và tiết kiệm hơn.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Terminal báo không tìm thấy lệnh exp
Thường là gói experiential chưa được cài vào Python đang được terminal sử dụng, hoặc thư mục chứa executable chưa nằm trong PATH. Hãy kiểm tra lại Python từ 3.12 trở lên và chạy lại pip install experiential. README không cung cấp thông báo lỗi cụ thể, nên không nên tự thêm cờ cài đặt khi chưa xác định nguyên nhân.
B.Request trả về lỗi xác thực
Kiểm tra bạn đã lưu đúng key được in ở lần chạy đầu chưa, biến có tên EXP_GATEWAY_KEY không, và header có đúng dạng Authorization: Bearer không. Cũng cần chắc rằng bạn không dùng key hosted xpl_ cho endpoint local nếu chưa cấu hình theo hướng đó.
C.Lỗi kết nối tới 127.0.0.1:8000
Gateway có thể chưa chạy hoặc terminal đang bị đóng. Hãy chạy exp hoặc exp run, giữ terminal mở, rồi gửi lại request. Nếu bạn dùng hosted gateway, hãy kiểm tra endpoint hosted thay vì endpoint loopback local.
D.exp code không khởi động đúng
Kiểm tra Node.js có phiên bản 22.19 trở lên. Đồng thời, gateway local phải đang chạy hoặc bạn đã đăng nhập để dùng hosted gateway. Prompt có đường dẫn file cũng cần trỏ tới file thật, chẳng hạn sales.csv trong thư mục mà agent có thể truy cập.
E.Capture không hoạt động trên máy không phải macOS
README nêu rõ exp capture yêu cầu macOS, Python 3.13 trở lên, cùng quyền phê duyệt extension và certificate. Tính năng này cũng đang thử nghiệm và độ ổn định mạng trên macOS còn đang được điều tra. Nếu chỉ cần gateway hoặc router, hãy dùng các lệnh exp, exp build và API thay vì capture.
API key và trace có thể chứa thông tin nhạy cảm hoặc dữ liệu khách hàng. Chỉ kết nối provider, tải trace và cấp quyền cho agent trong phạm vi cần thiết. README nói telemetry tổng hợp không chứa prompt, credential hay nội dung khách hàng thô, nhưng bạn vẫn cần tự kiểm soát dữ liệu trace và key đưa vào workflow.
VII.Có nên dùng không
Nên dùng Experiential nếu bạn đang có nhiều model hoặc nhiều coding agent và muốn gom chúng sau một API. Gateway local cho phép thử nhanh, public alias giúp giảm phụ thuộc vào tên provider, còn router và telemetry mở ra hướng tối ưu chi phí dựa trên traffic thật. Giấy phép Apache-2.0 cũng phù hợp cho nhiều kịch bản tích hợp và tự vận hành.
Giới hạn là phần nâng cao cần nhiều công việc hơn cài gateway. Bạn phải chuẩn bị API key, hiểu budget và quyền truy cập, có trace nếu muốn tối ưu, và cần thêm Node.js cho coding agent. Tính năng capture chỉ hỗ trợ macOS theo README, còn yêu cầu phần cứng cho từng model local chưa được tư liệu cung cấp.
Nếu bạn chỉ cần gọi một provider duy nhất từ một ứng dụng nhỏ, SDK trực tiếp của provider có thể đơn giản hơn. Nếu bạn cần kiểm soát nhiều model, nhiều agent, BYOK và muốn dùng dữ liệu vận hành để cải thiện lựa chọn model, Experiential là lựa chọn đáng thử. Hãy bắt đầu bằng gateway local và một request nhỏ, sau đó mới đưa trace thật hoặc key sản xuất vào hệ thống.
Câu hỏi thường gặp
Experiential có miễn phí không?
README mô tả đây là gateway mã nguồn mở và cho phép dùng hosted platform với BYOK pass-through miễn phí. Tuy vậy, tư liệu không nêu đầy đủ bảng giá cho mọi dịch vụ hoặc model, nên chưa thể kết luận toàn bộ workflow đều miễn phí.
Có cần GPU để chạy Experiential không?
README không yêu cầu GPU cho gateway cơ bản. Tư liệu cũng không nêu yêu cầu phần cứng cụ thể cho từng model local, nên phần này phụ thuộc model và provider bạn chọn.
Experiential chạy được trên Windows không?
README không nêu danh sách hệ điều hành cho gateway local, nhưng hướng dẫn cài bằng Python và lệnh terminal. Riêng `exp capture` yêu cầu macOS, Python 3.13 trở lên, extension và certificate được phê duyệt.
Dữ liệu và prompt có được gửi đi không?
Telemetry tổng hợp PostHog được bật mặc định nhưng README nói không chứa prompt, trace, action, observation, path, model name, credential hoặc raw customer content. Tuy vậy, request tới provider và trace bạn chủ động tải lên vẫn cần được kiểm soát theo cấu hình gateway và provider.
Có cần tự có API key không?
Nếu dùng BYOK, bạn cần key của provider tương ứng. README cũng mô tả hosted gateway có thể dùng key `xpl_`, còn lần chạy local sẽ tạo một key dùng một lần sau setup wizard.
`exp code` cần chuẩn bị gì?
Bạn cần Node.js 22.19 trở lên. Agent dùng gateway local đang chạy hoặc gateway hosted sau khi đăng nhập bằng `exp login`.
Experiential khác gì việc gọi thẳng OpenAI hoặc Anthropic?
Experiential thêm một gateway và router ở giữa để gom nhiều provider, kiểm soát quyền dùng model và budget, đồng thời tối ưu từ traffic. README không đưa bảng so sánh chi tiết với từng SDK hoặc công cụ khác.


