# Experiential: làm gateway AI tiết kiệm hơn — hướng dẫn cài đặt và dùng

> 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.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-10-13 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/experiential-gateway-ai-tiet-kiem-chi-phi

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.

```repo
- repo | experientiallabs/experiential
- kind | Ứng dụng
- desc | 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.
- stars | 17k
- lang | Python
- license | Apache-2.0
```

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

### 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.

### 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í.

### 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ù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.

### 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`.

### 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.

### 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.

### 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`.

## 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.

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

```steps
- Cài gói Python | Cài experiential bằng pip
- Khởi động gateway | Chạ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 agent | Dùng exp code khi cần làm việc trong terminal
- Tối ưu từ trace | Dùng exp build sau khi có dữ liệu OpenTelemetry
```

### 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:

```bash
pip install experiential
```

Lệ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.

### Khởi động gateway local

Chạy lệnh sau:

```bash
exp
```

Lầ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`.

### 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:

```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"}]}'
```

`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ù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.

### 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:

```bash
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.

### 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:

```bash
curl -L -o traces.otel.jsonl \
  https://huggingface.co/datasets/experiential-labs/wmo-terminal-tasks-traces/resolve/540883e451dc13d34fb50fdd36b143cb0f1fb0db/traces.otel.jsonl
```

Sau đó chạy lệnh build:

```bash
# Build simulation from your agent traces and optimize a router against it
exp build support-agent
```

Lệ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.

### Fine-tune mô hình bằng trace

Khi đã thu thập trace từ router và có key phù hợp, chạy:

```bash
exp optimize model support-agent
```

Lệ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.

## 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:

```bash
exp config telemetry status
```

Lệ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:

```bash
exp config telemetry disable
exp config telemetry enable
```

Nế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:

```bash
uv sync --extra dev
uv run ruff format --check .
uv run ruff check .
uv run ty check
uv run pytest -q
```

Kế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.

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

### 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:

```bash
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 đó.

### 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.

### 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:

```bash
exp build support-agent
```

Trong 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.

### 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:

```python
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

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

### 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.

### 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.

### 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.

### `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.

### 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.

### 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:

```bash
exp config telemetry status
exp config telemetry disable
```

Tù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ô.

```note
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.
```

## 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.
