Một AI gateway trả lời từ những gì nó đã nói
Một trợ lý hỗ trợ bị hỏi cùng những câu hỏi cả ngày bằng những từ ngữ hơi khác nhau. Gateway đứng trước mô hình của nó có thể trả lời một câu hỏi bằng câu trả lời nó đã đưa ra cho một câu hỏi trước đó đủ gần về nghĩa, thay vì gọi lại mô hình. Workspace này biên dịch một gateway như vậy thành các manifest Kubernetes, cùng với kho lưu trữ nơi nó giữ các câu trả lời đó.
Feature thực hiện việc đó là core/semantic-caching. Những câu trả lời nào do yêu cầu
của một bên gọi tạo ra có thể được phục vụ cho một bên gọi khác là câu hỏi mà trang này
dành phần lớn thời gian để bàn, vì một bộ nhớ đệm được chia sẻ giữa những bên gọi không đúng
sẽ trao cho một người câu trả lời được tạo ra cho người khác.
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
| instance | Component trong catalog | vai trò ở đây |
|---|---|---|
router | core/gateway/litellm | AI gateway: một alias chat, assistant, và một alias embedding, embedder, mỗi alias được phục vụ từ một model nối vào socket models của nó |
chat | core/ai-model/openai | model chat đứng sau assistant, chính API của OpenAI, được truy cập dưới dạng tham chiếu: không có gì chạy cho nó trong cluster |
embeddings | core/ai-model/openai-embedding | model embedding đứng sau embedder, được truy cập theo cùng cách |
cache | core/datastore/redis | kho lưu trữ nơi gateway giữ các câu trả lời của nó |
Ba cạnh uses: hai cạnh vào socket models của gateway, mỗi cạnh tới một model,
mỗi cạnh mang làm credential khóa mà gateway xuất trình cho model đó,
và một cạnh vào socket cache_store của nó, mang làm credential mật khẩu
mà cache xuất trình cho kho lưu trữ. Hai phần gắn Feature trên gateway:
api_key, khóa quản trị của nó, và answers, tức cache; và một phần gắn trên
kho lưu trữ, password, mật khẩu mà kho yêu cầu. Cả hai phần gắn mật khẩu đọc cùng một
tham số, cache_password, và cả hai thông tin xác thực của model đọc một tham số khác, openai_key;
Release đáp ứng cả hai. Phần gắn answers nêu tên alias embedding
biến mỗi prompt thành một vector, mức độ giống nhau cần có giữa hai prompt — 0.9,
theo độ tương đồng cosine — và thời gian một câu trả lời được lưu tồn tại, một giờ. Nó bỏ qua
scope, nên nhận giá trị mặc định, end_user.
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ó:
aggrega scaffold --example ai-gateway-semantic-cacheSau đó 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:
cd ai-gateway-semantic-cacheBuild
aggrega build --release release.yaml --auto-pullMộ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:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildWorkspace này phân giải các thực thể của catalog từ registry mặc định mà .aggrega-config.yaml chỉ định. Quá trình hiện thực hóa bộ nhớ đệm chạy một plugin không đi kèm trong trình biên dịch lẫn catalog, đó là bước cấu hình gateway pipeline-step/litellm-gateway-config, được quá trình phân giải tải về từ registry mà default_registry chỉ định, hub.aggrega.ai.
Bản build in ra như sau, với <workspace> đại diện cho thư mục của ví dụ này:
[… omitted: a line reporting on the gateway configuration step's plugin, five warnings, one per credential attachment, 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 and a total build time, which differ per run, and a notice that core/referenced-secret declares origin in both of its pillars]Build completed: 13 files written to <workspace>/distVớ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 `ai-gateway-semantic-cache`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `ai-gateway-semantic-cache` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `ai-gateway-semantic-cache` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `ai-gateway-semantic-cache`, `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 `ai-gateway-semantic-cache/dist/`.Cây thư mục được kết xuất
dist/helm/├── cache--password--cache-secret-cache-password.yaml├── cache-default-service.yaml├── cache-deployment.yaml├── chat-service.yaml├── embeddings-service.yaml├── router--api-zukey--router-secret-router-api-key.yaml├── router--assistant-zdcredential--router-secret-router-assistant-credential.yaml├── router--embedder-zdcredential--router-secret-router-embedder-credential.yaml├── router--replies-zdcredential--router-secret-router-replies-credential.yaml├── router-default-service.yaml├── router-deployment.yaml└── router/ ├── litellm-gateway-config/ │ └── configmap.yaml └── request-guard/ └── request-guard.yamlPhần đính kèm bộ đệm không mang theo tệp nào của riêng nó. Những gì nó làm được ghi vào cấu hình của gateway. Mỗi mô hình kết xuất một tệp, một Service ánh xạ một tên trong cụm 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.
Các mô hình mà nó phục vụ
Bảng định tuyến, phần mở đầu của nội dung cấu hình gateway, có một mục cho
mỗi kết nối trên socket models, được viết từ những gì mỗi mô hình công bố —
endpoint của nó, URL gốc của API OpenAI, và tên mô hình của nó — và nêu tên
biến mà Recipe của gateway dùng để cung cấp khóa của kết nối đó:
model_list: - model_name: "assistant" litellm_params: model: "openai/gpt-4o" api_base: "https://api.openai.com/v1" api_key: os.environ/LITELLM_MODEL_ASSISTANT_API_KEY - model_name: "embedder" litellm_params: model: "openai/text-embedding-3-small" api_base: "https://api.openai.com/v1" api_key: os.environ/LITELLM_MODEL_EMBEDDER_API_KEYBộ đệm, theo cách gateway đọc nó
Đây là phần thân cấu hình của gateway, khóa config.yaml của
dist/helm/router/litellm-gateway-config/configmap.yaml, từ
litellm_settings trở đi:
[… omitted: the routing table]litellm_settings: callbacks: - /etc/litellm-request-guard/request_field_filter.filter cache: true cache_params: host: os.environ/SEMANTIC_CACHE_STORE_HOST port: os.environ/SEMANTIC_CACHE_STORE_PORT redis_semantic_cache_embedding_model: embedder redis_semantic_cache_index_name: router-answers semantic_cache_scope: end_user similarity_threshold: 0.9 supported_call_types: - acompletion - completion - aresponses - responses - aanthropic_messages - anthropic_messages ttl: 3600 type: redis-semanticCó năm điều đáng rút ra từ đó.
Địa chỉ của kho lưu trữ không nằm trong đó. host và port chỉ định hai biến
môi trường thông qua cơ chế gián tiếp riêng của gateway, và Recipe của gateway đặt
các biến đó từ cạnh cache_store. Từ dist/helm/router-deployment.yaml, phần
env của container của gateway:
env: - name: LITELLM_MASTER_KEY valueFrom: secretKeyRef: name: router-api-key key: master-key - name: REDIS_PASSWORD valueFrom: secretKeyRef: name: router-replies.credential key: password - name: LITELLM_MODEL_ASSISTANT_API_KEY valueFrom: secretKeyRef: name: router-assistant.credential key: api-key - name: LITELLM_MODEL_EMBEDDER_API_KEY valueFrom: secretKeyRef: name: router-embedder.credential key: api-key - name: SEMANTIC_CACHE_STORE_HOST value: cache-default - name: SEMANTIC_CACHE_STORE_PORT value: "6379"cache-default là Service mà Recipe riêng của kho lưu trữ phát ra, được đọc từ những gì
Recipe đó công bố, và 6379 là cổng mà nó công bố. Bộ đệm đọc mật khẩu của kho lưu trữ từ
REDIS_PASSWORD, một tham chiếu đến Secret mà credential trên cạnh
cache_store kết xuất, router-replies.credential, và không bao giờ đọc chính
mật khẩu. Kho lưu trữ kết xuất một Secret riêng từ cùng tham số đó,
cache-password, và khởi động với --requirepass đọc từ nó, nên mật khẩu bộ đệm
xuất trình và mật khẩu kho lưu trữ yêu cầu là một giá trị, chỉ được viết một lần.
Khi không có cạnh cache_store, không biến nào trong ba biến chứa địa chỉ và mật khẩu
của kho lưu trữ được kết xuất, và bộ đệm, không có nơi nào để giữ các phản hồi của nó,
sẽ dừng quá trình build, như bên dưới. Mục thứ ba và thứ tư là khóa của các mô hình,
mỗi khóa được tham chiếu từ Secret mà credential của chính kết nối đó kết xuất, dưới
biến mà mục của nó trong bảng định tuyến chỉ định; helm provider viết mọi mục nó đọc
từ một Secret trước các mục thông thường.
Mô hình embedding là một bí danh trong bản đồ riêng của gateway. Gateway gửi
mỗi prompt đến embedder qua cùng bản đồ mà yêu cầu của người gọi đi qua,
nên bộ đệm không giữ địa chỉ hay thông tin xác thực nào của riêng nó. Nếu bạn đặt một bí danh
mà bản đồ không công bố, quá trình build sẽ dừng và liệt kê các bí danh mà nó có công bố.
Thời gian tồn tại là của kho lưu trữ. Mỗi phản hồi được ghi với ttl làm
thời hạn hết hạn, nên Redis xóa nó một giờ sau khi được lưu. Yêu cầu tiếp theo cho
prompt đó được mô hình trả lời và được lưu lại từ đầu.
Chỉ những loại yêu cầu có prompt mà bộ đệm đọc được mới được nêu tên. Các yêu cầu chat, dù streaming hay không, cùng các API responses và messages được lưu đệm. Một yêu cầu completions thì không, và một yêu cầu embeddings cũng không: nếu để theo mặc định riêng, gateway sẽ lưu phản hồi cho mọi yêu cầu embeddings, embedding mỗi đầu vào lần thứ hai để làm việc đó, mà không phục vụ lại phản hồi nào.
Chỉ mục được đặt tên theo gateway và attachment, router-answers, nên
hai gateway của cùng một Release dùng chung một kho lưu trữ sẽ giữ phản hồi của chúng trong các
chỉ mục riêng biệt.
Ai được phục vụ từ một mục bộ nhớ đệm
Một câu trả lời đã lưu chỉ được phục vụ cho một yêu cầu sau khi mọi thứ tạo nên
nhóm của nó đều khớp, và prompt giống với prompt mà nó đã trả lời ít nhất 0.9:
- khóa mà yêu cầu xuất trình, như gateway đã xác minh, cùng với nhóm và tổ chức của khóa đó;
- dưới
end_user, người dùng cuối mà yêu cầu nêu tên; - mô hình mà yêu cầu yêu cầu, và các tham số khác của yêu cầu — một temperature khác là một nhóm khác.
Gateway ghi khóa, nhóm và tổ chức của khóa và người dùng cuối vào chính
yêu cầu. Trên một yêu cầu chat, nó ghi chúng vào metadata của yêu cầu,
đè lên mọi giá trị mà bên gọi đã gửi ở đó; trên một yêu cầu responses hoặc messages, nó
giữ chúng tách biệt khỏi metadata của bên gọi, xóa khỏi đó mọi trường nhóm,
tổ chức hoặc người dùng cuối mà bên gọi đã ghi, và bộ bảo vệ yêu cầu mà Recipe
của nó cung cấp từ chối một yêu cầu nêu tên khóa ở đó, metadata.user_api_key,
với HTTP 400 nêu tên trường. Vì vậy không yêu cầu nào có thể tự nêu tên để vào nhóm
của một khóa khác.
metadata riêng của một yêu cầu vẫn có thể chuyển nó giữa các nhóm của khóa mà nó
xuất trình. Trên một yêu cầu responses, model_group thay thế mô hình mà
yêu cầu yêu cầu trong nhóm của nó. Trên một yêu cầu responses hoặc messages,
caching_groups cho phép các yêu cầu nêu tên cùng một nhóm bí danh mô hình chia sẻ
câu trả lời giữa chúng. Trên một yêu cầu responses hoặc chat, redis_namespace giữ
các yêu cầu nêu tên một namespace trong các nhóm tách biệt với những yêu cầu không nêu tên namespace nào. Không
cái nào trong số đó chạm tới nhóm của một khóa khác.
Khóa của gateway này là khóa quản trị của nó, và mọi bên gọi đều giữ nó.
Nó không gắn cơ sở dữ liệu sổ sách nào, nên nó không cấp khóa riêng nào: mọi
bên gọi xuất trình khóa được gắn vào api_key, và một yêu cầu không có khóa, hoặc
có một khóa mà gateway không cấp, bị từ chối trước khi tra cứu bất cứ thứ gì.
Vì vậy ở đây khóa không tách biệt bên gọi nào với bên gọi khác, và dưới phạm vi mặc định,
điều giữ hai bên gọi tách biệt là người dùng cuối mà mỗi yêu cầu nêu tên.
Dưới end_user, giá trị mặc định, một mục được phục vụ cho các yêu cầu nêu tên cùng một
người dùng cuối. Gateway đọc người dùng cuối từ yêu cầu: một header
x-litellm-end-user-id hoặc x-litellm-customer-id, hoặc trường user,
metadata.user_id, litellm_metadata.user hoặc safety_identifier của body. Một
câu trả lời được lưu cho alice được phục vụ cho câu hỏi có cách diễn đạt tương tự của alice, và
không cho câu hỏi của bob.
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:
- Gateway không xác minh tên nào trong số đó. Bất kỳ ai giữ khóa đều có thể nêu tên bất kỳ người dùng cuối nào và được phục vụ những gì đã được lưu cho người dùng cuối đó. Hãy giữ khóa ở ứng dụng biết người dùng cuối của nó là ai, và để ứng dụng nêu tên họ; đừng trao khóa cho chính người dùng cuối.
- Các yêu cầu không nêu tên người dùng cuối nào dùng chung một bộ nhớ đệm. Mọi yêu cầu như vậy xuất trình cùng một khóa đều được phục vụ từ cùng các mục, bất kể ai đã gửi nó.
Dưới key, mọi bên gọi xuất trình khóa đều được phục vụ từ một bộ nhớ đệm. Thêm
scope: key vào values của attachment và build lại: semantic_cache_scope của cấu hình
đọc là key, và không có gì khác trong đầu ra được render
thay đổi. Khi đó người dùng cuối mà một header nêu tên không còn là một phần của nhóm, nên một câu trả lời
được lưu cho alice, được nêu tên trong một header x-litellm-end-user-id, được phục vụ cho
câu hỏi có cách diễn đạt tương tự của bob nêu tên anh ấy theo cùng cách, kể cả
các lệnh gọi công cụ trong đó. Tuy nhiên, trường user của body là một trong các tham số khác của yêu cầu,
nên hai yêu cầu nêu tên các người dùng cuối khác nhau ở đó vẫn rơi vào
các nhóm khác nhau, như hai temperature. Điều đó phù hợp với một bộ nhớ đệm chứa các câu trả lời
giống nhau cho mọi người, và không gì khác.
Đ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:
-
Không có khóa quản trị. Gỡ bỏ phần gắn
api_keythì bản build dừng lại trước khi bất cứ thứ gì được kết xuất:[… omitted: a line reporting on the gateway configuration step's plugin, 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 assertionscaused by: FeatureRecipe "semantic-caching-litellm" instance "router" assertion "gateway_checks_the_caller": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/semantic-caching attachment "answers" on "router" needs core/gateway/litellm to check every caller's key before a cached reply is served, but its api_key credential slot is not attached, so the gateway checks no caller and a cache bucket would be made only of what each caller claims. Attach a credential to the api_key slot of "router" -
Không có kho lưu trữ. Gỡ bỏ cạnh
cache_storethì bản build dừng lại và nêu tên socket cần nối. -
Một kho lưu trữ không công bố
vector_search. Socket chấp nhận các kho khóa-giá trị, và Recipe của gateway dừng lại với một kho không khai báo rằng nó phục vụ tìm kiếm vector của công cụ truy vấn Redis, thứ mà bộ đệm dùng để tìm các câu trả lời của nó: một Redis trước bản phát hành 8.0, hoặc Valkey, sẽ không lưu đệm gì cả trong khi mọi yêu cầu vẫn thành công. -
Một phần gắn
core/semantic-cachingthứ hai trên gateway, vốn chỉ có một bộ đệm. -
core/data-maskingtrên cùng gateway. Hai thứ này khai báo xung đột, vì bộ đệm tạo khóa cho một yêu cầu sau khi che dữ liệu, nên hai yêu cầu chỉ khác nhau ở phần bị che thay thế sẽ dùng chung một câu trả lời đã lưu.
Khi không thể dùng kho lưu trữ
Gateway kết nối tới kho lưu trữ khi nó phục vụ yêu cầu đầu tiên, chứ không phải khi nó khởi động. Nếu nó không thể dùng kho lưu trữ — kho đòi một mật khẩu mà gateway không được cấp, hoặc từ chối mật khẩu mà gateway được cấp — thì mọi lần tra cứu đều trượt và không có gì được lưu, trong khi mọi yêu cầu vẫn được mô hình trả lời. Chỉ có log riêng của gateway cho biết điều đó. Đó là lý do hai đầu của mật khẩu đọc cùng một tham số: ô password của kho lưu trữ và credential trên cạnh cache_store.
Nơi trình biên dịch không diễn giải
Trình biên dịch chuyển tên Service và cổng của kho lưu trữ từ Recipe của kho lưu trữ
vào môi trường của gateway dưới dạng chuỗi, còn bí danh và các con số thì vào
cấu hình của gateway. Trình biên dịch không kết nối tới kho lưu trữ, không biết
liệu có gì trả lời tại cache-default:6379 hay không, và không biết người dùng cuối
là gì. Mỗi điểm dừng nêu 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 realization hoặc trong Recipe của gateway, hoặc dưới dạng xung đột mà hai
Features khai báo, và không điểm dừng nào dựa trên bất kỳ hiểu biết nào về lưu lượng.
Điều chỉnh ví dụ
- Dùng chung một bộ nhớ đệm cho mỗi khóa. Thêm
scope: keyvào attachmentanswers, khi mọi bên gọi cần được phục vụ cùng các câu trả lời. - Chạy kho lưu trữ không có mật khẩu. Xóa đồng thời attachment
passwordcủa kho lưu trữ vàcredentialtrên cạnhcache_store, cùng với tham sốcache_passwordtrong Aggregate và Release; khi đóREDIS_PASSWORDcủa gateway được render rỗng, nghĩa là kết nối không cần mật khẩu. Nếu chỉ xóa một trong hai attachment, bộ nhớ đệm sẽ không thể sử dụng kho lưu trữ. - Khớp nhiều hơn hoặc ít prompt hơn. Tăng
similarity_thresholdđể chỉ phục vụ các kết quả khớp gần hơn, hoặc giảm nó để phục vụ nhiều hơn; giá trị phù hợp tùy thuộc vào mô hình embedding.