Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

Một gateway APISIX giữ các mô hình của nó trong một ngân sách token

Một nhóm đặt hai mô hình OpenAI sau một gateway và muốn có một mức trần cho lượng mà gateway chi cho chúng mỗi ngày, tính bằng token. Workspace này biên dịch một gateway như vậy thành các manifest Kubernetes: Apache APISIX đứng trước hai mô hình, với core/period-budget được gắn vào.

Trang này cũng cho thấy một semantic cache cần gì từ gateway này trước khi nó được xây dựng: các bên gọi mà nó có thể phân biệt, mỗi bên qua khóa mà bên đó xuất trình, và một kho lưu trữ cho các phản hồi.

Workspace này không tự định nghĩa entity catalog nào. Ba tệp entity ở đây — một Aggregate, một Manifest và một Release — là toàn bộ những gì cần viết.

Những gì ví dụ này xây dựng

instanceComponent trong catalogvai trò ở đây
gatewaycore/gateway/apisixgateway, phục vụ hai alias: assistant, từ model chat, và summarizer, từ model mini
chatcore/ai-model/openaigpt-4o của OpenAI, được truy cập dưới dạng tham chiếu: không có gì chạy cho nó trong cluster
minicore/ai-model/openaigpt-4o-mini của OpenAI, được truy cập theo cùng cách

Hai cạnh uses đi vào socket models của gateway, mỗi cạnh tới một model, mỗi cạnh mang theo credential của nó là khóa mà gateway xuất trình cho model đó; cả hai đều đọc một tham số, openai_key, do Release cung cấp. Một Feature được gắn vào gateway, budget: Aggregate ghi rõ thứ được đếm, total_tokens, và lưu lượng của ai thuộc phạm vi một giới hạn, gateway — mọi thứ mà gateway phục vụ — còn Release ghi rõ bao nhiêu và trong bao lâu: hai triệu token mỗi ngày.

Manifest ánh xạ gateway tới apisix-chart, realization render chart APISIX của chính dự án, ở phiên bản APISIX 3.18.0, và phục vụ các model được nối với gateway. Khi đã nối một model, gateway đọc các route của nó từ một tệp được render cùng với nó, nên nó không cần kết nối etcd và không cần khóa Admin API; Aggregate không nối thứ nào trong hai thứ đó.

Tạo ví dụ

Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.

Ghi ví dụ vào một thư mục mới đặt theo tên của nó:

Terminal window
aggrega scaffold --example apisix-token-budget

Sau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:

Terminal window
cd apisix-token-budget

Build

Terminal window
aggrega build --release release.yaml --auto-pull

Một release cần có lockfile trước khi build, và lockfile được tạo ra chứ không được phân phối kèm, nên một bản clone mới sẽ không có. Hãy resolve một lockfile trước, hoặc để quá trình build tự điền vào:

Terminal window
aggrega pull --release release.yaml # resolve once, then build with no flag
aggrega build --release release.yaml --auto-pull # or resolve during the build

Việc resolve sẽ ghim chart APISIX mà Recipe của gateway kết xuất, được tải về từ chính kho lưu trữ của chart đó, nên cần có kết nối mạng. Workspace này resolve các thực thể trong catalog từ registry mặc định mà .aggrega-config.yaml chỉ định.

Bản build in ra như sau, với <workspace> đại diện cho thư mục của ví dụ này:

[… omitted: two warnings, one per model connection's credential, that the declared-sensitive origin reaches the target with no per-key sensitivity marking, because the realization maps it through a valuesMapping, the resolution's summary, a notice that core/referenced-secret declares origin in both of its pillars, and a total build time, which differs per run]
Build completed: 8 files written to <workspace>/dist

Với trợ lý AI

Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.

Chỉ dùng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục workspace chưa có thư mục `apisix-token-budget`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `apisix-token-budget` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `apisix-token-budget` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `apisix-token-budget`, `release` đặt thành `release.yaml`, `auto_pull` đặt thành true và `write` đặt thành true. Hãy cho tôi biết bản build đã ghi những tệp nào; chúng nằm trong `apisix-token-budget/dist/`.

Cây thư mục được kết xuất

dist/helm/
├── chat-service.yaml
├── gateway--assistant-zdcredential--gateway-secret-gateway-assistant-credential.yaml
├── gateway--summarizer-zdcredential--gateway-secret-gateway-summarizer-credential.yaml
├── gateway-configmap-default-gateway.yaml
├── gateway-deployment-default-gateway.yaml
├── gateway-service-default-gateway-gateway.yaml
├── mini-service.yaml
└── gateway/
└── model-routes.yaml

Ngân sách không mang theo tệp riêng nào. Thay vào đó, nó được ghi vào tệp định tuyến dist/helm/gateway/model-routes.yaml, một ConfigMap mà gateway gắn vào và đọc toàn bộ cấu hình định tuyến từ đó. Mỗi mô hình kết xuất một tệp, một Service ánh xạ một tên trong cluster sang máy chủ API của OpenAI, và mỗi thông tin xác thực trên một kết nối mô hình kết xuất một Secret riêng, được đặt tên theo gateway và bí danh của kết nối.

Ngân sách, theo cách gateway đọc nó

Đây là khóa apisix.yaml của ConfigMap đó:

services:
- id: "model-budget"
plugins:
ai-rate-limiting:
limit: 2000000
time_window: 86400
limit_strategy: "total_tokens"
routes:
- id: "model-assistant-chat"
uri: "/assistant/v1/chat/completions"
service_id: "model-budget"
methods:
- POST
plugins:
ai-proxy:
provider: openai-compatible
auth:
header:
Authorization: "$env://AI_PROXY_ASSISTANT_AUTHORIZATION"
options:
model: "gpt-4o"
override:
endpoint: "https://api.openai.com/v1/chat/completions"
- id: "model-summarizer-chat"
uri: "/summarizer/v1/chat/completions"
service_id: "model-budget"
[… omitted: the same route for gpt-4o-mini, presenting AI_PROXY_SUMMARIZER_AUTHORIZATION]
#END

Có năm điều đáng rút ra từ đó.

Ngân sách nằm trên một service mà cả hai route cùng tham chiếu. Cơ chế giới hạn tốc độ theo token của APISIX, ai-rate-limiting, giữ bộ đếm của nó dưới đối tượng mà nó được khai báo trên đó. Nếu được viết trên từng route, nó sẽ giữ một bộ đếm cho mỗi route; được viết một lần trên model-budget, service mà mọi route tham chiếu qua service_id, nó giữ một bộ đếm cho mọi thứ gateway phục vụ — phạm vi gateway mà phần gắn kết yêu cầu. Với scope: model, Recipe thay vào đó viết một service cho mỗi kết nối, model-assistant-budget và model-summarizer-budget, để mỗi model có giới hạn riêng.

Chu kỳ là một cửa sổ tính bằng giây. 1d được viết thành 86400. Cửa sổ mở ra với yêu cầu model đầu tiên sau khi cửa sổ trước đó đóng lại và kéo dài đúng khoảng thời gian đó; nó không bắt đầu lúc nửa đêm. Một tháng theo lịch không có số giây cố định, nên 1mo bị từ chối, như bên dưới.

Đơn vị là thứ được đếm. total_tokens là số token mà phản hồi của mỗi model báo cáo đã đọc và viết cộng lại; prompt_tokens và completion_tokens đếm một phía. Gateway đếm những gì phản hồi báo cáo và không định giá gì cả, nên nó không giữ ngân sách bằng đô la Mỹ.

Mỗi model có một route chat và không có route completion. Khi không có ngân sách, mỗi alias còn nhận thêm /<alias>/v1/completions. APISIX chỉ đọc token của một phản hồi từ yêu cầu mà nó nhận ra giao thức, và một yêu cầu completion, có phần thân mang prompt thay vì messages, không phải là yêu cầu như vậy: nó sẽ được trả lời mà không bao giờ được đếm. Vì thế, khi ngân sách được gắn, route đó không được viết ra, và một yêu cầu completion nhận phản hồi 404 Route Not Found.

Không có khóa nào trong đó. Mỗi route nêu tên biến chứa bearer token của kết nối của nó thông qua tham chiếu $env:// của APISIX. Từ dist/helm/gateway-deployment-default-gateway.yaml, phần env của container của gateway:

env:
- name: AI_PROXY_ASSISTANT_API_KEY
valueFrom:
secretKeyRef:
key: api-key
name: gateway-assistant.credential
- name: AI_PROXY_ASSISTANT_AUTHORIZATION
value: Bearer $(AI_PROXY_ASSISTANT_API_KEY)
[… omitted: the same two variables for summarizer]

Cùng Deployment đó chạy một bản sao, replicas: 1. Bộ đếm được giữ trong bộ nhớ của tiến trình gateway, nên một bản sao thứ hai sẽ giữ bộ đếm riêng của nó; khi một ngân sách được gắn, Recipe giữ chart ở một bản sao.

Gateway làm gì khi chạy

Với mỗi yêu cầu tới model, gateway so sánh số đếm với limit. Khi số đếm đã đạt tới đó, gateway trả lời 503 Service Temporarily Unavailable cho đến khi cửa sổ đóng, và yêu cầu không bao giờ được gửi tới model; phản hồi mang các header X-AI-RateLimit-Limit-…, X-AI-RateLimit-Remaining-… và X-AI-RateLimit-Reset-… của chính gateway. Token của một yêu cầu được cộng vào khi phản hồi của nó hoàn tất, nên yêu cầu đưa số đếm lên tới giới hạn vẫn được phục vụ, và mọi yêu cầu đang được xử lý song song với nó cũng vậy.

Từ đó có hai hệ quả, và cả hai đều là hành vi của gateway chứ không phải cấu hình:

  • Một lần khởi động lại bắt đầu một cửa sổ mới. Số đếm nằm trong bộ nhớ của tiến trình gateway, nên một pod được cập nhật cuốn chiếu hoặc khởi động lại sẽ bắt đầu đếm từ số không.
  • Một phản hồi không báo cáo token nào thì không được đếm gì. Số đếm là những gì mỗi model báo cáo; gateway yêu cầu một yêu cầu chat dạng stream báo cáo mức sử dụng của nó, và một model không báo cáo gì thì không cộng thêm gì.

Điều gì làm dừng quá trình build

Mỗi trường hợp dưới đây là một câu mà quá trình build in ra, nêu rõ điều cần thay đổi:

  • Chi phí tính bằng đô la Mỹ. Đặt unit: usd trong attachment và bản build dừng lại trước khi bất cứ thứ gì được render:

    [… omitted: what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars]
    [CATALOG_ERROR E0033]
    Recipe/FeatureRecipe assertions
    caused by: FeatureRecipe "period-budget-apisix" instance "gateway" assertion "unit_is_a_token_count": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/period-budget attachment "budget" on "gateway" asks for unit usd, but core/gateway/apisix, which declares dataplane.aggrega.ai/period-budget: tokens, counts the tokens each model's reply reports and prices nothing, so it keeps no budget in US dollars; set unit to total_tokens, prompt_tokens or completion_tokens, or attach the Feature to a gateway that counts cost
  • Ngân sách theo từng caller, scope: caller, trong khi Release không khai báo caller nào. Gateway phân biệt các caller qua key mà mỗi caller xuất trình, và khi không có infra.callers thì mọi route đều mở. Khi đã khai báo caller, như trong phần tiếp theo, mỗi caller có bộ đếm riêng trên mọi route.

  • Một tháng theo lịch, period: 1mo, và một giới hạn không phải là số nguyên token.

  • Một attachment core/period-budget thứ hai trên gateway, vốn chỉ chạy một giới hạn tốc độ token trên một route.

  • Không có gì nối vào socket models, khiến không còn route mô hình nào để đếm. Nếu chỉ gỡ hai kết nối, chính Component của gateway sẽ dừng build trước, yêu cầu kho etcd và khóa Admin API mà một gateway không có mô hình dùng để lưu giữ các route của nó.

  • Realization còn lại. Ánh xạ core/gateway/apisix sang helm/apisix trong Manifest và bản build dừng lại ở các kết nối models, nêu tên helm/apisix-chart: realization đó chạy APISIX 3.17.0 với các route nằm trong etcd và không render route nào. Nó cũng dừng lại khi có một attachment ngân sách, vì nó không có route nào để ghi attachment đó vào và, ở phiên bản 3.17.0, mỗi tiến trình gateway tự đếm riêng.

Bộ nhớ đệm ngữ nghĩa cần có bên gọi

APISIX 3.18.0 có sẵn một bộ nhớ đệm ngữ nghĩa, và core/semantic-caching gắn được vào gateway này. Hãy thêm một cái vào features của gateway trong aggregate.yaml:

answers:
type: core/semantic-caching
values:
embedding_model: assistant
similarity_threshold: 0.9
ttl_seconds: 3600

Manifest đã định tuyến Feature tới hiện thực APISIX của nó, và bản build dừng lại:

[… omitted: what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars]
[CATALOG_ERROR E0033]
Recipe/FeatureRecipe assertions
caused by: FeatureRecipe "semantic-caching-apisix" instance "gateway" assertion "scope_is_one_the_gateway_keeps": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/semantic-caching attachment "answers" on "gateway" asks for scope end_user, which keeps each end user the gateway identifies apart, but core/gateway/apisix tells its callers apart only by the key each presents, and cannot tell apart the end users behind one key: a value a request names for one is whatever the caller sent, which the gateway does not verify. Set scope to key, which keeps each caller infra.callers declares apart, or attach the Feature to a gateway that identifies end users

Bộ nhớ đệm giữ lại một phản hồi cho bất kỳ ai sau này hỏi điều gì đủ gần, nên việc ai dùng chung một bộ nhớ đệm quyết định ai có thể nhận được phản hồi được tạo cho người khác. Gateway này có thể tách riêng từng bên gọi theo khóa mà bên đó xuất trình, khóa mà gateway xác minh, và không chi tiết hơn thế: đặt scope: key thì bản build lại dừng, lần này vì các bên gọi chưa được cung cấp cho nó:

[… omitted: what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars]
[CATALOG_ERROR E0033]
Recipe/FeatureRecipe assertions
caused by: FeatureRecipe "semantic-caching-apisix" instance "gateway" assertion "callers_are_declared": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/semantic-caching attachment "answers" on "gateway" asks for scope key, but infra.callers of "gateway" declares no caller, so the gateway authenticates no key and every request on a route would share one cache, a reply generated for one caller served to another; declare the callers in infra.callers, with their keys through the caller_keys slot

Ba phần bổ sung giúp bản build thành công. Release nêu tên các bên gọi và khóa của chúng:

gateway:
infra:
callers: [support-agent, billing-agent]
features:
caller_keys:
type: core/referenced-secret-set
infra:
entries:
- key: support-agent
value: support-agent-key-change-me
- key: billing-agent
value: billing-agent-key-change-me
budget:
[… omitted: the budget's size, as above]

Aggregate kết nối mô hình mà bộ nhớ đệm dùng để biến mỗi prompt thành một vector, cùng một kho Redis cho các phản hồi, và nêu tên mô hình embeddings trong attachment là embedding_model: embedder, với scope: key:

models:
[… omitted: assistant and summarizer, as above]
embedder:
target: embeddings
features:
credential:
type: core/referenced-secret
values:
key: api-key
origin: "{{ .parameters.openai_key }}"
cache_store:
replies:
target: cache

với component embeddings (core/ai-model/openai-embedding, có values.model đặt thành text-embedding-3-small) và component cache (core/datastore/redis) được khai báo bên cạnh các mô hình, mỗi cái được đặt trong Release, và Manifest ánh xạ cả hai cùng core/referenced-secret-set tới hiện thực Kubernetes của nó, helm/k8s-secret-set, vốn ghi thẳng các khóa vào một Secret được render và vì vậy chỉ phù hợp với một môi trường phát triển. Sau đó tệp routes khai báo từng bên gọi và kiểm tra khóa của nó trên mọi route, và route chat mang bộ nhớ đệm:

consumers:
- username: "support-agent"
plugins:
key-auth:
key: "$env://CALLER_SUPPORT_AGENT_AUTHORIZATION"
[… omitted: billing-agent, the same way]
routes:
- id: "model-assistant-chat"
uri: "/assistant/v1/chat/completions"
service_id: "model-budget"
methods:
- POST
plugins:
key-auth:
header: Authorization
hide_credentials: true
ai-proxy:
[… omitted: the route to gpt-4o, as above]
ai-cache:
layers:
- exact
- semantic
exact:
ttl: 3600
cache_key:
share_across_routes: false
include_consumer: true
policy: redis
redis_host: "cache-default"
redis_port: 6379
semantic:
similarity_threshold: 0.9
ttl: 3600
embedding:
openai:
endpoint: "https://api.openai.com/v1/embeddings"
model: "text-embedding-3-small"
api_key: "$env://AI_PROXY_EMBEDDER_API_KEY"
vector_search:
redis:
index: "gateway-answers"
[… omitted: the same for the other connections]

Không có khóa nào của bên gọi nằm trong đó: mỗi consumer nêu tên một biến mà Deployment điền từ Secret do attachment caller_keys render, dưới chính tên của bên gọi, và ghép thành toàn bộ header:

- name: CALLER_SUPPORT_AGENT_KEY
valueFrom:
secretKeyRef:
key: support-agent
name: gateway-caller-keys
- name: CALLER_SUPPORT_AGENT_AUTHORIZATION
value: Bearer $(CALLER_SUPPORT_AGENT_KEY)
[… omitted: the same two variables for billing-agent]

Khi chạy, một yêu cầu không xuất trình khóa nào đã khai báo, dưới dạng Authorization: Bearer <key>, sẽ bị từ chối với HTTP 401, và khóa được gỡ khỏi yêu cầu mà gateway chuyển tiếp. Một phản hồi được lưu theo route và bên gọi, nên prompt được diễn đạt lại của một bên gọi sẽ nhận phản hồi đã lưu cho chính bên gọi đó và không bao giờ nhận phản hồi đã lưu cho bên khác. Phản hồi lấy từ bộ nhớ đệm không tính vào ngân sách, và vẫn được phục vụ khi đã vượt giới hạn. Kết nối embedder có các route riêng, như mọi kết nối trên socket models.

Nơi trình biên dịch không diễn giải

Trình biên dịch chuyển giới hạn, cửa sổ thời gian và đơn vị vào tệp routes dưới dạng chuỗi, cùng với endpoint và tên model của mỗi model lấy từ những gì model đó công bố. Nó không kết nối tới OpenAI, không biết liệu một phản hồi có báo cáo số token của nó hay không, và tự nó không đếm gì cả. Mỗi lần dừng ở trên đều do chính các thực thể của catalog khai báo, dưới dạng một assertion trong phần hiện thực hóa của ngân sách hoặc của cache, hoặc trong Recipe còn lại của gateway, và không lần dừng nào dựa trên bất kỳ sự hiểu biết nào về lưu lượng.

Điều chỉnh ví dụ

  • Giới hạn theo từng mô hình. Đặt scope: model: mỗi bí danh có một service và một bộ đếm riêng.
  • Giới hạn theo từng bên gọi. Khai báo các bên gọi và khóa của họ trong Release, như trong “A semantic cache needs callers” ở trên, và đặt scope: caller: mỗi bên gọi có một bộ đếm riêng trên mọi route.
  • Chỉ đếm một phía. Đặt unit: prompt_tokens để đếm những gì các mô hình đọc, hoặc completion_tokens để đếm những gì chúng viết.
  • Cửa sổ ngắn hơn hoặc dài hơn. Đặt period thành một số giây, phút, giờ hoặc ngày trong Release, như 6h hoặc 30d.