# experiential: gateway AI tối ưu chi phí — hướng dẫn cài đặt và dùng

> Experiential là gateway và router mã nguồn mở cho quy trình làm việc với AI agent. Bạn có thể dùng mô hình hosted, BYOK hoặc local qua một API tương thích OpenAI, sau đó tối ưu lựa chọn model từ dữ liệu truy cập. Cài bản local khá gọn bằng pip, nhưng các tính năng capture và coding agent có thêm 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-toi-uu-chi-phi

Experiential là một gateway và router mã nguồn mở cho các quy trình làm việc với AI agent. Repo gom nhiều mô hình vào một API tương thích OpenAI, giúp bạn đổi provider hoặc model mà không phải sửa toàn bộ ứng dụng đang gọi API.

Công cụ này phù hợp với dev, nhóm sản phẩm, nhân viên văn phòng dùng coding agent và doanh nghiệp muốn kiểm soát quyền truy cập, ngân sách, tốc độ và chất lượng. Điểm đáng giá là Experiential có thể học từ traffic thực tế để đề xuất router tốt hơn, tối ưu chi phí và tiến tới huấn luyện một model chuyên biệt do bạn sở hữu.

Bạn có thể chạy gateway trên máy cá nhân, dùng gateway hosted, kết nối khóa API của mình hoặc gọi các model qua một alias riêng. 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 | CLI
- desc | 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.
- stars | 17k
- lang | Python
- license | Apache-2.0
```

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

Experiential tập trung vào bốn việc chính: làm lớp trung gian cho model, kiểm soát việc sử dụng, tối ưu lựa chọn model và hỗ trợ coding agent.

### Gom nhiều model sau một API

Gateway cung cấp API tương thích OpenAI. Ứng dụng của bạn có thể gửi request tới một endpoint chung thay vì tích hợp riêng từng provider. README cũng nêu API Anthropic Messages cho gateway hosted.

Cách này hữu ích khi bạn muốn thử model khác mà không phải viết lại phần gọi API. Bạn chỉ cần thay endpoint, key hoặc tên model theo cấu hình của gateway.

### Dùng hosted, BYOK hoặc model local

Bạn có thể chạy gateway local bằng lệnh `exp`, hoặc dùng gateway hosted. Với BYOK, bạn kết nối khóa của các provider của mình để request đi qua lớp gateway. README liệt kê các lựa chọn như OpenAI, Anthropic, Gemini, Azure, Bedrock, Fireworks và OpenRouter cho hosted setup.

Mô hình này giúp nhóm giữ quyền kiểm soát khóa provider, đồng thời có một nơi để quản lý cách ứng dụng gọi model. Chi phí của việc dùng provider vẫn phụ thuộc vào tài khoản và chính sách của provider đó.

### Đặt quyền, mục đích sử dụng và ngân sách

Experiential cho phép kiểm soát user hoặc agent nào được dùng model nào, cho mục đích nào và được chi bao nhiêu. Khi chạy wizard lần đầu, gateway hiển thị alias công khai, identity và ngân sách lệnh mặc định 50 đô la Mỹ.

Đây là phần hữu ích với nhóm có nhiều agent hoặc nhiều người cùng dùng AI. Bạn có thể giới hạn việc sử dụng thay vì để mọi request dùng chung một cấu hình không kiểm soát.

### Tối ưu router từ traffic thật

Bạn có thể thu thập OpenTelemetry traces từ agent hiện tại, sau đó dùng `exp build` để tạo project và tối ưu router dựa trên các trace đó. Router có thể hướng tới cân bằng chất lượng, tốc độ và chi phí.

Thay vì chọn một model duy nhất cho mọi việc, bạn có thể dùng dữ liệu thực tế để tìm cách phân luồng phù hợp hơn với từng loại tác vụ.

### Tối ưu hoặc huấn luyện model riêng

Sau khi thu thập traces từ router, lệnh `exp optimize model` hỗ trợ fine-tune một model mã nguồn mở mà bạn sở hữu, thông qua Tinker.

Tính năng này phù hợp khi một nhóm có nhiều dữ liệu tác vụ lặp lại và muốn xây dựng model chuyên biệt. README không mô tả chi tiết chi phí, loại model cụ thể hoặc cấu hình phần cứng cho bước fine-tune.

### Chạy coding agent qua `exp code`

`exp code` chạy exp-code, coding và cowork agent mã nguồn mở xây dựng trên Pi. 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ể dùng giao diện terminal tương tác hoặc truyền prompt trực tiếp. Các chế độ print, JSON và RPC của exp-code cũng hoạt động thông qua lệnh này.

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

Nếu chỉ muốn chạy gateway local, README cung cấp cách cài bằng pip và yêu cầu gói `experiential`. Repo khai báo Python >=3.12 trong `pyproject.toml`.

Nếu muốn chạy coding agent với `exp code`, bạn cần Node.js 22.19 hoặc mới hơn.

Nếu muốn dùng tính năng capture, bạn cần macOS, Python 3.13 hoặc mới hơn, đồng thời phải phê duyệt extension và certificate. README ghi rõ capture đang ở trạng thái experimental và độ ổn định mạng trên macOS vẫn đang được điều tra.

Nếu dùng model hoặc provider cần xác thực, bạn cần khóa tương ứng. File `.env.example` có các tên biến như `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `AZURE_OPENAI_API_KEY`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `TINKER_API_KEY`, `E2B_API_KEY` và `EXA_API_KEY`. Tài liệu được cung cấp không nói khóa nào là bắt buộc cho mọi cách dùng.

Nếu dùng hosted gateway, README mô tả quy trình tạo tài khoản bằng email, kết nối khóa provider và nhận key dạng `xpl_`. Nếu dùng gateway local, wizard sẽ cấp một key dùng một lần sau khi bạn chọn provider, model và reasoning effort.

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

```steps
- Cài gói experiential | Cài CLI và thư viện Python
- Khởi động gateway | Chạy wizard cấu hình local
- Lưu key và alias | Ghi lại thông tin wizard cấp
- Gửi request thử | Gọi endpoint OpenAI-compatible
- Chọn hosted hoặc coding agent | Dùng gateway hosted hoặc exp code khi cần
```

### Cài gói Python

Mở Terminal hoặc PowerShell ở thư mục bạn muốn làm việc. README dùng pip để cài gói `experiential`.

```bash
pip install experiential
```

Lệnh này cài gói Python và CLI `exp`. Python của bạn cần đáp ứng yêu cầu từ `pyproject.toml`, tức Python 3.12 trở lên.

Người mới thường chạy nhầm `pip` của một Python khác với Python đang dùng. Nếu lệnh cài xong nhưng `exp` không chạy, hãy kiểm tra lại môi trường Python và PATH trước khi cài thêm gói khác. README không cung cấp lệnh xử lý riêng cho lỗi PATH.

### Khởi động gateway local

Sau khi cài xong, chạy:

```bash
exp
```

Bạn cũng có thể khởi động bằng:

```bash
exp run
```

Ở lần chạy đầu, setup wizard sẽ hỏi provider, model và reasoning effort. Wizard lưu các kết nối provider đã chọn, sau đó hiển thị alias công khai, identity và ngân sách lệnh mặc định 50 đô la Mỹ. Cuối cùng, nó in ra một key dùng một lần.

Hãy chọn một alias dễ nhớ, chẳng hạn `opus-5`, rồi chép lại key mà wizard cấp. Không đưa key này vào mã nguồn công khai hoặc gửi vào nhóm chat không cần thiết.

### Gửi request đầu tiên

README minh họa việc đặt key 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"}]}'
```

Trong đó, `EXP_GATEWAY_KEY` là key bạn vừa nhận. `model` phải khớp alias bạn đã chọn trong wizard. Gateway local lắng nghe tại `127.0.0.1:8000` theo ví dụ của README.

Lệnh trên dùng cú pháp biến môi trường của shell kiểu Unix. Nếu bạn dùng Windows PowerShell, README không đưa ra bản tương đương. Bạn cần chú ý không chép nguyên dòng `export` nếu shell của bạn không hỗ trợ cú pháp này.

### Dùng thư viện Python

Bạn có thể tải một project router bằng thư viện `exp` và dùng client OpenAI được cấu hình qua gateway riêng của project:

```python
import exp

with exp.load_router("my-project") as client:
    response = client.chat.completions.create(
        model="my-project",
        messages=[{"role": "user", "content": "hello"}],
    )
```

Tên `my-project` phải là project router đã tồn tại trong môi trường của bạn. Đoạn mã gửi một tin nhắn `hello` tới model cùng tên và nhận response từ client.

### Dùng gateway hosted

Nếu không muốn chạy gateway local, README hướng dẫn dùng nền tảng hosted của Experiential. Quy trình gồm tạo tài khoản bằng email, kết nối khóa provider, thực hiện request `/v1` đầu tiên bằng OpenAI hoặc Anthropic SDK, rồi tùy chọn chuyển các coding agent hiện có sang gateway.

README nói hosted gateway phục vụ API tương thích OpenAI và Anthropic Messages tại endpoint `/v1`. Tài liệu cũng có `SETUP.md` với các prompt copy-paste cho Claude Code, Cursor, Codex và công cụ tương tự. Repo không ghi bảng giá tổng quát cho dịch vụ hosted.

### Chạy coding agent

Để dùng exp-code, cần Node.js 22.19 hoặc mới hơn. Khi gateway local đang chạy, bạn có thể mở giao diện terminal tương tác bằng:

```bash
exp code
```

Hoặc gửi prompt trực tiếp:

```bash
exp code -p "Summarize sales.csv into report.docx"
```

Mọi đối số sẽ được chuyển cho exp-code. Vì vậy các chế độ print, JSON và RPC của exp-code cũng có thể dùng qua `exp code`.

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

Cách kiểm tra cơ bản là chạy `exp`, hoàn tất wizard và nhận key dùng một lần. Nếu wizard hiển thị phần chọn provider, model, reasoning effort, alias, identity và ngân sách, gateway đã khởi động đúng.

Bước kiểm tra tiếp theo là gửi request tới:

```text
http://127.0.0.1:8000/v1/chat/completions
```

Request cần có header `Authorization: Bearer` với key của gateway và body chứa `model` cùng `messages`. Kết quả mong đợi là response chat từ alias bạn đã chọn.

Nếu kiểm tra coding agent, chạy `exp code`. Với prompt mẫu trong README, agent sẽ xử lý yêu cầu tóm tắt `sales.csv` thành `report.docx`. README không mô tả chính xác nội dung file kết quả, nên chỉ nên xem việc agent nhận prompt và chạy qua gateway là dấu hiệu kiểm tra ban đầu.

Nếu kiểm tra telemetry, chạy:

```bash
exp config telemetry status
```

Lệnh này cho biết trạng thái telemetry sản phẩm. Telemetry tổng hợp ẩn danh được bật mặc định và cài đặt được lưu cục bộ trong `.exp/settings.toml`.

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

### Chủ shop muốn xử lý dữ liệu bán hàng bằng coding agent

Một chủ shop có file `sales.csv` và muốn tạo báo cáo Word. Sau khi gateway đang chạy, có thể dùng:

```bash
exp code -p "Summarize sales.csv into report.docx"
```

Agent nhận yêu cầu qua gateway và thực hiện tác vụ với model được cấu hình. Kết quả mong đợi là một quy trình tự động hóa việc tóm tắt dữ liệu thành báo cáo. README không cam kết định dạng nội dung cụ thể của file Word, nên bạn vẫn cần kiểm tra file sau khi agent hoàn thành.

### Nhân viên văn phòng muốn đổi model mà không sửa ứng dụng

Một nhóm đang có ứng dụng gọi API theo chuẩn OpenAI. Nhóm có thể cấu hình ứng dụng gọi endpoint gateway và dùng alias model đã chọn trong wizard, thay vì tích hợp trực tiếp từng provider.

Ví dụ request dùng `model` là `opus-5`. Khi muốn thay provider hoặc cách định tuyến phía sau, nhóm có thể điều chỉnh gateway mà không cần đổi toàn bộ logic gọi chat trong ứng dụng.

### Nhóm phát triển muốn phân luồng request theo dữ liệu thật

Một nhóm đã có agent chạy trong môi trường production và muốn giảm chi phí hoặc cải thiện tốc độ. Trước tiên, nhóm thu thập OpenTelemetry traces. Nếu chỉ muốn thử, README cung cấp dataset `terminal-tasks` và lệnh tải file:

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

Sau đó tạo project router:

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

Lệnh build sẽ hỏi provider, model, ngân sách và file trace. Project `support-agent` có thể dùng làm cơ sở để mô phỏng và tối ưu router cho agent hỗ trợ.

### Nhóm AI muốn thử model riêng

Sau khi router đã có traces, nhóm có thể chạy:

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

Mục tiêu là fine-tune một model mã nguồn mở mà nhóm sở hữu bằng Tinker. Đây là hướng phù hợp khi nhóm muốn model chuyên biệt cho tác vụ của mình, nhưng cần chuẩn bị thêm việc đánh giá chất lượng, quản lý chi phí và bảo vệ dữ liệu trace.

> Dùng một gateway chung để biến traffic AI thành dữ liệu tối ưu chi phí, tốc độ và chất lượng.
>
> — Ông T

### Người dùng muốn kiểm soát telemetry

Nếu nhóm không muốn bật telemetry sản phẩm, kiểm tra trạng thái bằng:

```bash
exp config telemetry status
```

Tắt bằng:

```bash
exp config telemetry disable
```

Có thể bật lại bằng:

```bash
exp config telemetry enable
```

README nói telemetry này chỉ là dữ liệu sản phẩm tổng hợp ẩn danh, không bao gồm prompt, traces, actions, observations, paths, model names, credentials hoặc raw customer content.

```note
Không đưa API key hoặc dữ liệu khách hàng vào prompt, file trace hay kho mã nguồn. Kiểm tra quyền truy cập và chi phí của từng provider trước khi chuyển agent sang gateway.
```

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

### Python không đáp ứng phiên bản yêu cầu

`pyproject.toml` yêu cầu Python >=3.12. Nếu môi trường đang dùng Python cũ, cài đặt hoặc chạy CLI có thể thất bại. Hãy chuyển sang môi trường Python đáp ứng yêu cầu rồi chạy lại `pip install experiential`.

### Lệnh `exp` không được nhận diện

Trường hợp này thường xảy ra khi gói đã cài nhưng thư mục chứa executable chưa có trong PATH, hoặc bạn cài bằng một Python khác. Kiểm tra terminal đang dùng đúng môi trường Python. README không đưa lệnh sửa PATH cụ thể, nên không nên tự đoán thêm biến môi trường của repo.

### Request bị từ chối vì sai key hoặc alias

Key trong `EXP_GATEWAY_KEY` phải là key wizard cấp. Giá trị `model` cũng phải khớp alias công khai bạn đã chọn. Hãy chạy lại wizard hoặc kiểm tra chính xác hai giá trị này, đồng thời giữ gateway local đang chạy.

### `exp code` không chạy được

Coding agent cần Node.js 22.19 hoặc mới hơn và cần gateway local đang chạy, hoặc cần đăng nhập để dùng hosted gateway. Kiểm tra phiên bản Node.js, mở gateway trước rồi thử lại `exp code`.

### Capture không hoạt động ổn định

Capture chỉ dành cho macOS, cần Python 3.13 trở lên và phải được phê duyệt extension cùng certificate. README cũng cảnh báo tính năng này đang experimental, trong đó độ tin cậy mạng trên macOS vẫn đang được điều tra. Nếu chưa cần capture, bạn có thể dùng gateway và OpenTelemetry traces theo các luồng còn lại.

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

Experiential đáng thử nếu bạn cần một lớp gateway chung cho nhiều model, muốn dùng BYOK, kiểm soát ngân sách hoặc bắt đầu tối ưu router từ traffic thực tế. Cách cài local ngắn, API tương thích OpenAI và có thêm CLI cho coding agent.

Repo cũng phù hợp với nhóm muốn tự lưu trữ hoặc muốn tiến tới model chuyên biệt. Giấy phép Apache-2.0 cho phép bạn xem xét và sử dụng mã nguồn theo điều kiện của giấy phép.

Giới hạn cần cân nhắc là tài liệu chưa mô tả đầy đủ mọi chi tiết triển khai, giá dịch vụ hosted, yêu cầu phần cứng cho fine-tune hoặc cách cấu hình Windows PowerShell cho request mẫu. Tính năng capture còn experimental. Ngoài ra, việc tối ưu router chỉ có ý nghĩa khi bạn có traces đủ đại diện và quy trình đánh giá kết quả rõ ràng.

Nếu bạn chỉ cần gọi một provider duy nhất với một SDK đơn giản, gateway có thể là lớp trung gian nhiều hơn nhu cầu. Nếu bạn cần quản trị nhiều agent, nhiều model, ngân sách và dữ liệu truy cập, Experiential có lý do rõ ràng để được đưa vào thử nghiệm trước.

## 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 không nêu đầy đủ bảng giá cho gateway hosted; phần BYOK trên hosted được mô tả là free pass-through, còn chi phí provider vẫn cần xem theo tài khoản tương ứng.

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

README không nói gateway local cần GPU. Tài liệu cũng không nêu yêu cầu phần cứng cụ thể cho bước fine-tune model qua Tinker, nên chưa thể khẳng định cấu hình GPU cần thiết.

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

README cung cấp lệnh cài Python và lệnh CLI nhưng không nêu ma trận hệ điều hành cho gateway local. Riêng tính năng capture yêu cầu macOS, nên không nên suy rộng yêu cầu của capture cho toàn bộ repo.

### Có cần API key không?

Gateway local cấp một key dùng một lần sau khi wizard hoàn tất. Nếu kết nối provider hoặc dùng hosted gateway, bạn cần các khóa provider tương ứng; `.env.example` liệt kê nhiều biến API key và thông tin xác thực.

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

README nói telemetry sản phẩm tổng hợp ẩn danh không chứa prompt, traces, actions, observations, paths, model names, credentials hoặc raw customer content. Tuy vậy, bạn vẫn cần tự kiểm soát API key, trace và dữ liệu gửi tới provider.

### Experiential khác gì việc gọi thẳng OpenAI hoặc Anthropic?

Experiential thêm một gateway và router tương thích OpenAI, cho phép gom nhiều provider, đặt quyền và ngân sách, rồi tối ưu lựa chọn model từ traffic. Nếu bạn chỉ dùng một provider và không cần các lớp quản trị này, gọi trực tiếp có thể đơn giản hơn.

### Có thể dùng Experiential cho coding agent không?

Có. `exp code` chạy exp-code, cần Node.js 22.19 trở lên và dùng gateway local đang chạy hoặc hosted gateway sau khi đăng nhập bằng `exp login`. README có ví dụ gửi prompt trực tiếp để tạo báo cáo từ file CSV.
