Gateway AI yang menjawab dari apa yang sudah pernah dikatakannya
Sebuah asisten dukungan ditanyai pertanyaan yang sama sepanjang hari dengan kata-kata yang sedikit berbeda. Gateway di depan modelnya dapat menjawab sebuah pertanyaan dari balasan yang telah diberikannya untuk pertanyaan sebelumnya yang cukup dekat maknanya, alih-alih memanggil model lagi. Workspace ini mengompilasi gateway semacam itu menjadi manifest Kubernetes, beserta penyimpanan tempat balasan-balasan tersebut disimpan.
Feature yang melakukannya adalah core/semantic-caching. Balasan mana yang dapat diberikan
kepada satu pemanggil padahal dihasilkan oleh permintaan pemanggil lain adalah pertanyaan yang
paling banyak dibahas halaman ini, karena cache yang dipakai bersama oleh pemanggil yang salah akan memberikan
kepada seseorang balasan yang dihasilkan untuk orang lain.
Workspace ini tidak menulis entitas katalog sendiri. Tiga berkas entitas di sini — sebuah Aggregate, sebuah Manifest, dan sebuah Release — adalah seluruh hal yang ditulis siapa pun.
Apa yang dibangunnya
| instans | Component katalog | perannya di sini |
|---|---|---|
router | core/gateway/litellm | gateway AI: alias chat, assistant, dan alias embedding, embedder, masing-masing dilayani dari model yang terhubung ke soket models-nya |
chat | core/ai-model/openai | model chat di balik assistant, API milik OpenAI sendiri, dijangkau sebagai referensi: tidak ada yang dijalankan untuknya di dalam kluster |
embeddings | core/ai-model/openai-embedding | model embedding di balik embedder, dijangkau dengan cara yang sama |
cache | core/datastore/redis | penyimpanan tempat gateway menyimpan balasannya |
Tiga edge uses: dua ke soket models milik gateway, satu ke masing-masing model,
masing-masing membawa sebagai credential-nya kunci yang diberikan gateway kepada model tersebut,
dan satu ke soket cache_store-nya, membawa sebagai credential-nya kata sandi
yang diberikan cache kepada penyimpanan. Dua lampiran Feature pada gateway:
api_key, kunci administratifnya, dan answers, cache-nya; serta satu pada
penyimpanan, password, kata sandi yang dimintanya. Kedua lampiran kata sandi membaca satu
parameter, cache_password, dan kedua kredensial model membaca parameter lain, openai_key;
Release memenuhi keduanya. Lampiran answers menyebutkan alias embedding
yang mengubah setiap prompt menjadi vektor, seberapa mirip dua prompt harus — 0.9,
sebagai cosine similarity — dan berapa lama balasan yang disimpan bertahan, satu jam. Lampiran ini menghilangkan
scope, sehingga menggunakan nilai default, end_user.
Membuat contoh
Anda dapat mem-build contoh ini dengan perintah di bawah, atau meminta asisten AI Anda mem-build-nya untuk Anda.
Tulis contoh ke folder baru yang dinamai sesuai contoh itu:
aggrega scaffold --example ai-gateway-semantic-cacheKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:
cd ai-gateway-semantic-cacheBuild
aggrega build --release release.yaml --auto-pullSebuah release memerlukan lockfile sebelum di-build, dan lockfile dihasilkan alih-alih disertakan, sehingga clone baru tidak memilikinya. Resolusikan satu terlebih dahulu, atau biarkan build mengisinya:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildWorkspace ini me-resolve entitas katalog dari registry default yang disebut .aggrega-config.yaml. Realisasi cache menjalankan satu plugin yang tidak disertakan dalam compiler maupun katalog, yaitu langkah konfigurasi gateway pipeline-step/litellm-gateway-config, yang diambil oleh proses resolusi dari registry yang ditunjuk oleh default_registry, yaitu hub.aggrega.ai.
Build mencetak keluaran berikut, dengan <workspace> mewakili folder contoh ini:
[… 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>/distDengan asisten AI
Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.
Gunakan hanya tool Aggrega, dan jangan membuat folder apa pun sendiri. Jika folder workspace belum berisi folder `ai-gateway-semantic-cache`, panggil tool `scaffold` sekali dengan `example` diatur ke `ai-gateway-semantic-cache` dan tanpa `dir`: tool itu menulis contoh ke folder baru `ai-gateway-semantic-cache`. Lalu panggil tool `build` dengan `workspace_root` diatur ke `ai-gateway-semantic-cache`, `release` diatur ke `release.yaml`, `auto_pull` diatur ke true, dan `write` diatur ke true. Beri tahu saya file mana saja yang ditulis build; file-file itu berada di bawah `ai-gateway-semantic-cache/dist/`.Pohon hasil render
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.yamlLampiran cache tidak membawa file sendiri. Apa yang dilakukannya ditulis ke dalam konfigurasi gateway. Setiap model merender satu file, sebuah Service yang memetakan nama di dalam klaster ke host API OpenAI, dan setiap kredensial pada koneksi model merender Secret tersendiri, yang dinamai menurut gateway dan alias koneksi tersebut.
Model yang dilayaninya
Tabel perutean, yaitu bagian awal isi konfigurasi gateway, memiliki satu entri
per koneksi pada soket models, yang ditulis dari apa yang dipublikasikan setiap model —
endpoint-nya, URL dasar API OpenAI, dan nama modelnya — serta menyebutkan
variabel tempat Recipe gateway mengirimkan kunci koneksi tersebut:
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_KEYCache, sebagaimana dibaca oleh gateway
Berikut adalah isi konfigurasi gateway, kunci config.yaml dari
dist/helm/router/litellm-gateway-config/configmap.yaml, mulai dari
litellm_settings:
[… 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-semanticAda lima hal yang patut dibaca darinya.
Alamat penyimpanan tidak ada di dalamnya. host dan port menyebut dua variabel
lingkungan melalui indireksi milik gateway sendiri, dan Recipe gateway menetapkan
keduanya dari edge cache_store. Dari dist/helm/router-deployment.yaml,
env milik kontainer 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 adalah Service yang dihasilkan oleh Recipe milik penyimpanan itu sendiri, dibaca dari apa yang
dipublikasikan Recipe tersebut, dan 6379 adalah port yang dipublikasikannya. Cache membaca kata sandi
penyimpanan dari REDIS_PASSWORD, sebuah referensi ke Secret yang dirender oleh credential pada
edge cache_store, yaitu router-replies.credential, dan tidak pernah membaca kata sandi itu sendiri. Penyimpanan merender Secret miliknya sendiri dari
parameter yang sama, cache-password, dan dijalankan dengan --requirepass yang dibaca darinya, sehingga
kata sandi yang diberikan cache dan kata sandi yang diminta penyimpanan adalah satu nilai,
ditulis sekali. Tanpa edge cache_store, tidak satu pun dari tiga variabel tempat alamat dan kata sandi
penyimpanan diberikan akan dirender, dan cache, yang tidak memiliki tempat untuk
menyimpan balasannya, menghentikan build, seperti dijelaskan di bawah. Entri ketiga dan keempat adalah
kunci model, masing-masing direferensikan dari Secret yang dirender oleh kredensial koneksinya sendiri,
di bawah variabel yang disebut oleh entrinya dalam tabel routing;
provider helm menulis setiap entri yang dibacanya dari Secret sebelum entri-entri
biasa.
Model embedding adalah alias dari peta milik gateway sendiri. Gateway mengirim
setiap prompt ke embedder melalui peta yang sama yang dilalui permintaan pemanggil,
sehingga cache tidak menyimpan alamat atau kredensial miliknya sendiri. Jika Anda menyebut alias yang tidak
dipublikasikan oleh peta, build akan berhenti dan mencantumkan alias yang dipublikasikannya.
Masa berlakunya adalah milik penyimpanan. Setiap balasan ditulis dengan ttl sebagai
waktu kedaluwarsanya, sehingga Redis menghapusnya satu jam setelah disimpan. Permintaan berikutnya untuk
prompt tersebut dijawab oleh model dan disimpan kembali.
Hanya jenis permintaan yang prompt-nya dibaca oleh cache yang disebutkan. Permintaan chat, baik streaming maupun tidak, serta API responses dan messages di-cache. Permintaan completions tidak, demikian pula permintaan embeddings: jika dibiarkan dengan nilai bawaannya, gateway akan menyimpan balasan untuk setiap permintaan embeddings, melakukan embedding setiap input untuk kedua kalinya demi itu, dan tidak menyajikan satu pun kembali.
Indeks dinamai menurut gateway dan attachment-nya, router-answers, sehingga
dua gateway dalam satu Release yang berbagi penyimpanan menyimpan balasannya dalam indeks
yang terpisah.
Siapa yang dilayani dari satu entri cache
Balasan yang tersimpan dilayankan ke permintaan berikutnya hanya jika semua hal yang membentuk
bucket-nya cocok, dan prompt-nya setidaknya 0.9 mirip dengan prompt yang dijawabnya:
- kunci yang diajukan permintaan, sebagaimana diverifikasi oleh gateway, beserta tim dan organisasi kunci tersebut;
- dalam
end_user, pengguna akhir yang disebutkan permintaan; - model yang diminta permintaan, dan parameter lain permintaan tersebut — temperature yang berbeda berarti bucket yang berbeda.
Gateway menuliskan kunci, tim dan organisasinya, serta pengguna akhir ke dalam
permintaan itu sendiri. Pada permintaan chat, gateway menuliskannya ke dalam metadata permintaan,
menimpa nilai apa pun yang dikirim pemanggil di sana; pada permintaan responses atau messages, gateway
menyimpannya terpisah dari metadata pemanggil, menghapus darinya setiap kolom tim,
organisasi, atau pengguna akhir yang ditulis pemanggil, dan penjaga permintaan yang dikirimkan
Recipe-nya menolak permintaan yang menyebutkan kunci di sana, metadata.user_api_key,
dengan HTTP 400 yang menyebutkan kolom tersebut. Jadi, tidak ada permintaan yang dapat masuk ke bucket
kunci lain dengan menyebutkan namanya.
metadata milik permintaan itu sendiri tetap dapat memindahkannya di antara bucket-bucket kunci yang
diajukannya. Pada permintaan responses, model_group menggantikan model yang diminta
permintaan tersebut dalam bucket-nya. Pada permintaan responses atau messages,
caching_groups memungkinkan permintaan yang menyebutkan grup alias model yang sama berbagi
balasan di antara alias tersebut. Pada permintaan responses atau chat, redis_namespace menempatkan
permintaan yang menyebutkan suatu namespace dalam bucket yang terpisah dari permintaan yang tidak menyebutkannya. Tidak satu pun
dari ketiganya mencapai bucket kunci lain.
Kunci gateway ini adalah kunci administratifnya, dan setiap pemanggil memegangnya.
Gateway ini tidak memiliki basis data pembukuan yang terpasang, sehingga tidak menerbitkan kunci sendiri: setiap
pemanggil mengajukan kunci yang dipasang ke api_key, dan permintaan tanpa kunci, atau
dengan kunci yang tidak diterbitkan gateway, ditolak sebelum apa pun dicari.
Jadi, di sini kunci tidak memisahkan satu pemanggil dari yang lain, dan dalam cakupan default,
yang memisahkan dua pemanggil adalah pengguna akhir yang disebutkan setiap permintaan.
Dalam end_user, yang merupakan default, sebuah entri dilayankan ke permintaan yang menyebutkan
pengguna akhir yang sama. Gateway membaca pengguna akhir dari permintaan: header
x-litellm-end-user-id atau x-litellm-customer-id, atau kolom user,
metadata.user_id, litellm_metadata.user, atau safety_identifier pada body. Balasan
yang disimpan untuk alice dilayankan untuk pertanyaan alice yang susunan katanya mirip, dan
tidak untuk pertanyaan bob.
Dua hal mengikutinya, dan keduanya merupakan perilaku gateway, bukan konfigurasi:
- Gateway tidak memverifikasi satu pun dari nama-nama tersebut. Siapa pun yang memegang kunci dapat menyebutkan pengguna akhir mana pun dan dilayani apa yang disimpan untuk pengguna akhir tersebut. Simpan kunci pada aplikasi yang mengetahui siapa pengguna akhirnya, dan biarkan aplikasi itu yang menyebutkan mereka; jangan berikan kunci kepada pengguna akhir itu sendiri.
- Permintaan yang tidak menyebutkan pengguna akhir berbagi satu cache. Setiap permintaan semacam itu yang mengajukan kunci yang sama dilayani dari entri yang sama, siapa pun pengirimnya.
Dalam key, setiap pemanggil yang mengajukan kunci dilayani dari satu cache. Tambahkan
scope: key ke values attachment dan lakukan build ulang: semantic_cache_scope pada konfigurasi
berisi key, dan tidak ada hal lain dalam output yang dirender yang
berubah. Pengguna akhir yang disebutkan header kemudian tidak menjadi bagian dari bucket, sehingga balasan
yang disimpan untuk alice, yang disebutkan dalam header x-litellm-end-user-id, dilayankan untuk
pertanyaan bob yang susunan katanya mirip dan menyebutkan dirinya dengan cara yang sama, termasuk
pemanggilan tool di dalamnya. Namun, kolom user pada body merupakan salah satu parameter lain permintaan,
sehingga dua permintaan yang menyebutkan pengguna akhir berbeda di sana tetap berada di
bucket yang berbeda, seperti halnya dua temperature. Hal ini cocok untuk cache berisi jawaban yang
sama bagi semua orang, dan tidak untuk yang lain.
Yang menghentikan build
Masing-masing berikut adalah kalimat yang dicetak oleh build, yang menyebutkan apa yang perlu diubah:
-
Tidak ada kunci administratif. Hapus lampiran
api_keydan build berhenti sebelum apa pun dirender:[… 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" -
Tidak ada penyimpanan. Hapus edge
cache_storedan build berhenti dengan menyebutkan soket yang harus dihubungkan. -
Penyimpanan yang tidak menerbitkan
vector_search. Soket menerima penyimpanan key-value, dan Recipe milik gateway berhenti pada penyimpanan yang tidak menyatakan bahwa ia melayani pencarian vektor dari mesin kueri Redis, yang digunakan cache untuk mencari balasannya: Redis sebelum rilis 8.0, atau Valkey, tidak akan menyimpan apa pun dalam cache sementara setiap permintaan tetap berhasil. -
Lampiran
core/semantic-cachingkedua pada gateway, yang hanya memiliki satu cache. -
core/data-maskingpada gateway yang sama. Keduanya menyatakan konflik, karena cache memberi kunci pada permintaan setelah penyamaran, sehingga dua permintaan yang hanya berbeda pada bagian yang digantikan oleh penyamaran akan berbagi satu balasan tersimpan.
Ketika penyimpanan tidak dapat digunakan
Gateway terhubung ke penyimpanan saat pertama kali melayani permintaan, bukan saat dimulai. Jika gateway tidak dapat menggunakan penyimpanan — penyimpanan meminta kata sandi yang tidak diberikan kepada gateway, atau menolak kata sandi yang diberikan — setiap pencarian meleset dan tidak ada yang disimpan, sementara setiap permintaan tetap dijawab oleh model. Hanya log milik gateway sendiri yang menyatakannya. Itulah sebabnya kedua ujung kata sandi membaca satu parameter: slot password milik penyimpanan dan credential pada edge cache_store.
Bagian yang tidak ditafsirkan oleh kompiler
Compiler menyalurkan nama Service dan port milik store dari Recipe store
ke dalam environment gateway sebagai string, serta alias dan angka-angkanya ke dalam
konfigurasi gateway. Compiler tidak terhubung ke store, tidak mengetahui
apakah ada yang menjawab di cache-default:6379, dan tidak mengetahui apa itu pengguna
akhir. Setiap penghentian di atas dideklarasikan oleh entitas katalog itu sendiri, sebagai
asersi dalam realisasi atau dalam Recipe gateway, atau sebagai konflik yang dideklarasikan oleh kedua
Features, dan tidak satu pun bergantung pada pemahaman apa pun tentang lalu lintasnya.
Menyesuaikannya
- Bagikan satu cache per kunci. Tambahkan
scope: keyke lampirananswers, jika setiap pemanggil harus dilayani dengan balasan yang sama. - Jalankan penyimpanan tanpa kata sandi. Hapus lampiran
passwordmilik penyimpanan dancredentialpada sisicache_storesecara bersamaan, beserta parametercache_passworddi Aggregate dan Release;REDIS_PASSWORDmilik gateway kemudian dirender kosong, sehingga terhubung tanpa kata sandi. Menghapus hanya salah satu dari kedua lampiran membuat cache tidak dapat menggunakan penyimpanan. - Cocokkan lebih banyak atau lebih sedikit prompt. Naikkan
similarity_thresholduntuk hanya melayani kecocokan yang lebih dekat, atau turunkan untuk melayani lebih banyak; nilai yang sesuai bergantung pada model embedding.