Experiential: làm gateway AI tiết kiệm hơn — 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 AI agent, hỗ trợ mô hình hosted, BYOK và local qua API tương thích OpenAI. Bạn có thể chạy gateway cục bộ, dùng nền tảng hosted, kiểm soát ngân sách và tối ưu router từ trace. Cài bản cơ bản khá ngắn bằng pip, nhưng các tính năng như coding agent và capture có yêu cầu riêng.
Experiential là gateway và router mã nguồn mở cho các workflow dùng mô hình AI và coding agent. Repo gom nhiều mô hình hosted, BYOK và local vào một API tương thích OpenAI, giúp ứng dụng không phải tích hợp riêng từng nhà cung cấp.
Điểm đáng giá nhất là bạn có thể kiểm soát việc ai được dùng mô hình nào, dùng cho mục đích gì và tiêu bao nhiêu. Khi đã có dữ liệu truy cập, Experiential còn có thể xây router tối ưu theo chất lượng, tốc độ và chi phí. Repo hiện có khoảng 16.775 sao và 302 fork, dùng giấy phép Apache-2.0.
experientiallabs/experiential
Gateway Python tương thích OpenAI để 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ì
A.Gom nhiều nhà cung cấp sau một API
Gateway cung cấp API tương thích OpenAI. Ứng dụng hoặc agent chỉ cần gọi một địa chỉ gateway thay vì phải thay đổi mã nguồn cho từng nhà cung cấp mô hình. README cũng nêu gateway hỗ trợ hosted, BYOK và local models.
Điều này phù hợp khi bạn muốn thử nhiều mô hình, chuyển nhà cung cấp hoặc giữ cấu hình gọi mô hình ở một chỗ. Gateway local có thể chạy trên loopback, còn gateway hosted dùng API tương thích OpenAI và Anthropic Messages.
B.Kiểm soát người dùng, agent và ngân sách
Bạn có thể đặt quy tắc về người dùng hoặc agent nào được dùng mô hình nào, cho trường hợp sử dụng nào và với mức chi bao nhiêu. Khi chạy lần đầu, trình hướng dẫn local hiển thị ngân sách lệnh mặc định 50 USD để bạn xác nhận.
Tính năng này hữu ích với nhóm có nhiều coding agent hoặc nhiều nhân viên cùng dùng AI. Bạn có thể tạo một lớp kiểm soát chung thay vì để từng công cụ tự giữ khóa và tự phát sinh chi phí.
C.Tối ưu router từ traffic thực tế
Experiential nhận OpenTelemetry traces từ agent hiện có. Từ các trace này, lệnh build có thể tạo một project simulation rồi tối ưu router theo dữ liệu thực tế.
Router được hướng tới ba mục tiêu: chất lượng, tốc độ và chi phí. Đây là cách phù hợp hơn việc chọn một mô hình duy nhất bằng cảm tính, vì dữ liệu tối ưu đến từ các tác vụ mà hệ thống của bạn thật sự đã chạy.
D.Dùng router riêng trong Python
Thư viện Python có thể tải một project router bằng exp.load_router. Client trả về hoạt động như OpenAI client chính thức, nên ứng dụng Python có thể gọi chat.completions.create qua gateway riêng của project.
E.Chạy coding agent trong terminal
Lệnh exp code chạy exp-code, coding và cowork agent mã nguồn mở của Experiential. Agent dùng gateway local đang chạy, hoặc gateway hosted sau khi bạn đăng nhập bằng exp login.
Bạn có thể mở giao diện terminal tương tác hoặc truyền thẳng một yêu cầu bằng tham số -p. Các chế độ print, JSON và RPC của exp-code cũng được chuyển qua exp code.
F.Capture traffic từ một số ứng dụng desktop
Tính năng capture được thiết kế để thu thập trace được hỗ trợ từ ứng dụng desktop Codex và Claude Code, trong khi request đi trực tiếp tới OpenAI hoặc Anthropic. Experiential dùng dữ liệu này làm middleware để kiểm soát chi phí, áp dụng guardrail và tối ưu chất lượng.
Tính năng này còn được ghi là experimental. README cũng lưu ý độ ổn định mạng trên macOS đang được điều tra.
G.Fine-tune mô hình mã nguồn mở của bạn
Sau khi thu thập trace từ router, bạn có thể dùng lệnh optimize để fine-tune một mô hình mã nguồn mở thông qua Tinker. Kết quả hướng tới một mô hình chuyên biệt mà bạn sở hữu, thay vì chỉ phụ thuộc vào mô hình dùng chung.
H.Telemetry có thể bật hoặc tắt
Telemetry sản phẩm tổng hợp ẩn danh của PostHog được bật mặc định. README nói dữ liệu này không bao gồm prompt, trace, action, observation, path, tên mô hình, credential hoặc nội dung khách hàng thô.
Bạn có thể xem trạng thái, tắt hoặc bật lại telemetry bằng lệnh cấu hình. Tùy chọn được lưu cục bộ trong .exp/settings.toml.
II.Cần chuẩn bị gì
Bản cài chính của gói experiential yêu cầu Python 3.12 trở lên. README cung cấp cách cài nhanh bằng pip và lệnh exp.
Khi chạy gateway local lần đầu, bạn cần chọn provider, model và reasoning effort trong setup wizard. Wizard sẽ lưu connection của provider, sau đó hỏi public alias, identity và ngân sách lệnh trước khi in ra một key dùng một lần.
Nếu dùng BYOK, bạn cần có key của provider mà mình muốn kết nối. File .env.example liệt kê các biến có thể liên quan, gồm OPENAI_API_KEY, ANTHROPIC_API_KEY, AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, OPENROUTER_API_KEY, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_REGION, AWS_DEFAULT_REGION, TINKER_API_KEY, E2B_API_KEY, EXA_API_KEY và một số biến riêng của Experiential.
Nếu dùng exp code, cần Node.js 22.19 trở lên. Agent này sử dụng gateway local đang chạy hoặc gateway hosted sau khi đăng nhập.
Nếu dùng exp capture, README yêu cầu macOS, Python 3.13 trở lên và quyền phê duyệt cho extension cùng certificate. Đây không phải yêu cầu của gateway local cơ bản.
Nếu dùng gateway hosted, bạn cần tạo tài khoản bằng email, kết nối key inference provider của mình và nhận key dạng xpl_. README mô tả nền tảng này hỗ trợ các key của OpenAI, Anthropic, Gemini, Azure, Bedrock, Fireworks và OpenRouter.
III.Cài đặt từng bước
- Cài gói PythonCài experiential bằng pip
- Khởi động gatewayChạy exp và hoàn thành setup wizard
- Gửi request thửDùng key một lần để gọi API tương thích OpenAI
- Chạy coding agentDùng exp code khi cần làm việc trong terminal
- Tối ưu từ traceDùng exp build sau khi có dữ liệu OpenTelemetry
A.Cài gói Python
Mở terminal tại thư mục bạn muốn làm việc. Máy cần có Python 3.12 trở lên. Lệnh dưới đây là lệnh cài đặt được README cung cấp:
pip install experientialLệnh này cài gói Python có tên experiential. Sau khi cài xong, terminal sẽ có lệnh exp. Nếu terminal báo không tìm thấy pip, hãy kiểm tra lại Python và môi trường cài đặt trước khi tiếp tục; README không cung cấp lệnh sửa riêng cho lỗi này.
B.Khởi động gateway local
Chạy lệnh sau:
expLần chạy đầu tiên, setup wizard dùng các bộ chọn provider, model và reasoning effort dùng chung. Bạn chọn connection của provider, sau đó wizard lưu connection đã chọn.
Tiếp theo, wizard hiển thị các giá trị mặc định cho public alias, identity và ngân sách lệnh 50 USD. Hãy chọn một public alias, chẳng hạn opus-5, rồi giữ lại key được in ra. README mô tả đây là key dùng một lần, vì vậy bạn nên sao chép ngay khi wizard hiển thị.
Gateway local chạy API trên loopback. README cũng cho biết có thể khởi động bằng exp run, nhưng luồng Getting Started dùng exp.
C.Gửi request đầu tiên
Đặt key đã nhận từ wizard 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"}]}'export lưu key cho phiên terminal hiện tại. curl gửi request tới gateway ở địa chỉ loopback và cổng 8000. Header Authorization truyền key, header Content-Type báo rằng phần thân là JSON, còn -d gửi model cùng message.
Nếu bạn chọn public alias khác, hãy thay giá trị opus-5 trong trường model bằng alias mình đã chọn. Không nên ghi key trực tiếp vào mã nguồn hoặc gửi key vào nơi công khai.
D.Dùng gateway hosted
Nếu không muốn tự chạy gateway, README hướng dẫn dùng gateway hosted và xem SETUP.md để có các prompt copy-paste cho Claude Code, Cursor, Codex và công cụ tương tự.
Quy trình hosted gồm bốn nhóm việc: tạo tài khoản bằng email và tải trace lên làm telemetry; kết nối key provider của bạn theo mô hình BYOK; thực hiện request /v1 đầu tiên bằng OpenAI SDK hoặc Anthropic SDK với key xpl_; hoặc hoàn tất onboarding rồi trỏ các coding agent hiện có qua gateway.
README không đưa lệnh cài đặt terminal đầy đủ cho hosted gateway. Vì vậy, hãy dùng các prompt và hướng dẫn trong SETUP.md của repo thay vì tự đoán endpoint hoặc biến môi trường.
E.Chạy coding agent
Sau khi gateway local đang chạy, hoặc sau khi đã đăng nhập gateway hosted bằng exp login, bạn có thể chạy giao diện terminal:
exp code # interactive terminal UI
exp code -p "Summarize sales.csv into report.docx"Lệnh đầu mở giao diện tương tác. Lệnh thứ hai gửi yêu cầu tóm tắt file sales.csv thành report.docx. File đầu vào và quyền ghi file cần tồn tại trong môi trường mà agent đang chạy. README chỉ nêu ví dụ này, không mô tả thêm định dạng file hay quy trình xác thực nội dung.
F.Thu thập trace và xây project router
Nếu chưa có trace để thử, README cung cấp lệnh tải dataset OTLP công khai:
curl -L -o traces.otel.jsonl \
https://huggingface.co/datasets/experiential-labs/wmo-terminal-tasks-traces/resolve/540883e451dc13d34fb50fdd36b143cb0f1fb0db/traces.otel.jsonlSau đó chạy lệnh build:
# Build simulation from your agent traces and optimize a router against it
exp build support-agentLệnh build sẽ hướng dẫn chọn provider, model và ngân sách, đồng thời yêu cầu file trace. Trong ví dụ, project có tên support-agent. Bạn có thể dùng project này để thử luồng tối ưu router theo trace.
G.Fine-tune mô hình bằng trace
Khi đã thu thập trace từ router và có key phù hợp, chạy:
exp optimize model support-agentLệnh này dùng project support-agent để tối ưu một mô hình mã nguồn mở thông qua Tinker. README không mô tả chi tiết số bước fine-tune, loại mô hình cụ thể hoặc chi phí, nên cần xem tài liệu trong repo trước khi chạy trên dữ liệu thật.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra cơ bản là chạy exp, hoàn thành wizard và nhận được key một lần. Sau đó request curl phải gửi được tới http://127.0.0.1:8000/v1/chat/completions với public alias đã chọn.
Bạn cũng có thể kiểm tra các route cấu hình telemetry:
exp config telemetry statusLệnh này cho biết trạng thái telemetry. Để kiểm tra việc bật tắt hoạt động, README cung cấp:
exp config telemetry disable
exp config telemetry enableNếu muốn kiểm tra bộ mã nguồn trong môi trường phát triển, repo cung cấp các lệnh sau:
uv sync --extra dev
uv run ruff format --check .
uv run ruff check .
uv run ty check
uv run pytest -qKết quả mong đợi là các bước kiểm tra hoàn tất mà không báo lỗi. Đây là luồng dành cho phát triển repo, không bắt buộc cho người chỉ cài gói từ pip.
V.Dùng vào việc thật
A.Chủ shop muốn tổng hợp dữ liệu bán hàng
Chủ shop có thể chạy coding agent và yêu cầu xử lý file doanh thu:
exp code -p "Summarize sales.csv into report.docx"Kết quả mong đợi theo ví dụ README là một báo cáo report.docx được tạo từ sales.csv. Trước khi chạy, bạn cần bảo đảm file có trong môi trường làm việc và agent có quyền xử lý file đó.
B.Nhân viên văn phòng muốn dùng nhiều mô hình qua một cấu hình
Nhân viên hoặc nhóm vận hành có thể chạy gateway local, chọn provider và model trong wizard, rồi cho các công cụ gọi API qua alias chung. Request mẫu dùng model là public alias, nên việc đổi connection được giữ ở gateway thay vì phải sửa từng ứng dụng.
Cách này phù hợp khi nhóm cần giới hạn model và ngân sách theo agent. Gateway cũng cho phép đặt quy tắc người dùng hoặc agent nào được sử dụng model nào cho từng mục đích.
C.Dev muốn router cân bằng chất lượng và chi phí
Dev có thể tải trace OTLP để thử hoặc dùng trace từ agent hiện tại:
exp build support-agentTrong quá trình build, chọn provider, model, ngân sách và file trace. Sau đó Experiential tạo simulation và tối ưu router theo traffic. Kết quả phù hợp khi team muốn quyết định model dựa trên tác vụ thật thay vì chọn một model duy nhất cho mọi request.
D.Dev Python muốn gọi project router như OpenAI client
Trong ứng dụng Python, tải router bằng đoạn mã README cung cấp:
import exp
with exp.load_router("my-project") as client:
response = client.chat.completions.create(
model="my-project",
messages=[{"role":"user", "content":"hello"}],
)Đoạn mã mở client cho project my-project, gửi message hello, rồi đóng client khi ra khỏi khối with. Bạn có thể dùng mẫu này khi đã có project router tương ứng.
Một gateway tốt không chỉ giúp gọi được model, mà còn biến traffic thật thành dữ liệu để chọn model tốt hơn.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Python thấp hơn phiên bản yêu cầu
Gói chính yêu cầu Python 3.12 trở lên. Nếu cài đặt hoặc chạy lệnh thất bại vì phiên bản, hãy kiểm tra phiên bản Python đang dùng và cài lại trong môi trường có Python phù hợp. Capture có yêu cầu riêng là Python 3.13 trở lên trên macOS.
B.Gửi sai key hoặc quên giữ key một lần
Key được in sau setup wizard và README gọi là one-time key. Nếu request trả về lỗi xác thực, hãy kiểm tra biến EXP_GATEWAY_KEY, header Bearer và việc terminal vẫn còn biến đó. Không công khai key; nếu đã làm lộ, hãy xử lý theo quy trình quản lý key của provider hoặc nền tảng.
C.Model không khớp public alias
Trong request mẫu, trường model là opus-5, đúng với alias người dùng chọn trong wizard. Nếu bạn đặt alias khác mà vẫn gửi opus-5, gateway có thể không tìm thấy model tương ứng. Hãy dùng đúng alias đã chọn.
D.exp code không chạy được
exp code cần Node.js 22.19 trở lên và cần gateway local đang chạy hoặc phiên đăng nhập hosted. Kiểm tra hai điều kiện này trước; README không cung cấp lệnh sửa cụ thể cho lỗi Node hoặc đăng nhập.
E.Capture không hoạt động ổn định
Capture chỉ dành cho macOS, yêu cầu Python 3.13 trở lên và quyền cho extension cùng certificate. README cũng cảnh báo tính năng này experimental và độ ổn định mạng macOS đang được điều tra. Nếu chưa cần capture, hãy bắt đầu bằng gateway local hoặc hosted.
F.Không muốn gửi telemetry
Telemetry tổng hợp ẩn danh được bật mặc định. Kiểm tra trạng thái và tắt bằng:
exp config telemetry status
exp config telemetry disableTùy chọn được lưu trong .exp/settings.toml. README nói telemetry không chứa prompt, trace, credential hoặc nội dung khách hàng thô.
Không đưa API key, gateway key hoặc dữ liệu khách hàng vào log, prompt thử nghiệm hay kho mã nguồn. Khi dùng trace thật, hãy kiểm tra chính sách dữ liệu và quyền truy cập trước khi upload.
VII.Có nên dùng không
Nên dùng Experiential nếu bạn cần một lớp gateway chung cho nhiều mô hình, muốn dùng BYOK, cần kiểm soát ngân sách của agent hoặc muốn tối ưu routing từ traffic thực tế. Người dùng Python có thể bắt đầu nhanh bằng pip, còn team phát triển có thêm lệnh kiểm tra, router và fine-tune.
Điểm mạnh là API tương thích OpenAI, có gateway local, có lựa chọn hosted, hỗ trợ coding agent và có luồng từ trace đến router chuyên biệt. Giấy phép Apache-2.0 cũng phù hợp để nghiên cứu và tích hợp theo điều kiện của giấy phép.
Giới hạn là các tính năng nâng cao cần nhiều thành phần hơn: exp code cần Node.js mới, capture chỉ hỗ trợ macOS với yêu cầu riêng, còn tối ưu và fine-tune cần trace, provider cùng key phù hợp. README cũng chưa nói đầy đủ về giá hosted, giới hạn sử dụng, khả năng chạy Windows hay quy trình khôi phục key.
Nếu bạn chỉ cần gọi một model duy nhất từ một ứng dụng nhỏ, tích hợp trực tiếp SDK có thể đơn giản hơn. Nếu bạn cần quản trị nhiều agent, nhiều provider và chi phí theo traffic, Experiential đáng để thử trước bằng gateway local.
Câu hỏi thường gặp
Experiential có miễn phí không?
Repo là mã nguồn mở và dùng giấy phép Apache-2.0. README cũng có gateway hosted và BYOK, nhưng không nêu đầy đủ bảng giá hoặc giới hạn của dịch vụ hosted. Vì vậy chưa thể kết luận toàn bộ nền tảng hosted là miễn phí.
Có cần GPU để chạy Experiential không?
README không nói rằng gateway local cần GPU. Tài liệu mô tả việc dùng hosted, BYOK và local models, nhưng không nêu yêu cầu phần cứng chi tiết cho từng loại model. Bạn nên kiểm tra tài liệu của model nếu muốn chạy model local.
Experiential chạy được trên Windows không?
README không nêu rõ khả năng hỗ trợ Windows cho gateway cơ bản. Tính năng capture được ghi rõ là yêu cầu macOS, nhưng điều đó không đủ để kết luận các tính năng khác có hỗ trợ Windows hay không.
Dữ liệu và API key có an toàn không?
README nói telemetry tổng hợp ẩn danh không bao gồm prompt, trace, credential, tên model hoặc nội dung khách hàng thô. Tuy vậy, khi dùng BYOK hoặc upload trace, bạn vẫn cần tự quản lý key và kiểm tra dữ liệu trước khi gửi lên nền tảng.
Experiential khác gì so với gọi OpenAI hoặc Anthropic trực tiếp?
Experiential đặt một gateway tương thích OpenAI ở giữa ứng dụng và provider. Nó thêm khả năng dùng nhiều provider, kiểm soát agent, ngân sách và tối ưu router từ traffic, trong khi gọi SDK trực tiếp thường đơn giản hơn cho một provider duy nhất.
Có cần Node.js khi chỉ dùng gateway Python không?
Không có yêu cầu Node.js cho luồng cài gateway cơ bản bằng `pip install experiential` và `exp`. Node.js 22.19 trở lên là yêu cầu riêng của `exp code`.
Có thể dùng key của nhà cung cấp riêng không?
Có. Mô tả và README đều nói về BYOK, tức dùng key của provider riêng. File `.env.example` liệt kê nhiều biến như `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, các biến Azure và AWS; cách kết nối cụ thể được thực hiện qua setup wizard hoặc hướng dẫn hosted.


