Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

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

instansComponent katalogperannya di sini
routercore/gateway/litellmgateway AI: alias chat, assistant, dan alias embedding, embedder, masing-masing dilayani dari model yang terhubung ke soket models-nya
chatcore/ai-model/openaimodel chat di balik assistant, API milik OpenAI sendiri, dijangkau sebagai referensi: tidak ada yang dijalankan untuknya di dalam kluster
embeddingscore/ai-model/openai-embeddingmodel embedding di balik embedder, dijangkau dengan cara yang sama
cachecore/datastore/redispenyimpanan 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:

Terminal window
aggrega scaffold --example ai-gateway-semantic-cache

Kemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:

Terminal window
cd ai-gateway-semantic-cache

Build

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

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

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

Workspace 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>/dist

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

Lampiran 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_KEY

Cache, 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-semantic

Ada 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_key dan 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 assertions
    caused 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_store dan 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-caching kedua pada gateway, yang hanya memiliki satu cache.

  • core/data-masking pada 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: key ke lampiran answers, jika setiap pemanggil harus dilayani dengan balasan yang sama.
  • Jalankan penyimpanan tanpa kata sandi. Hapus lampiran password milik penyimpanan dan credential pada sisi cache_store secara bersamaan, beserta parameter cache_password di Aggregate dan Release; REDIS_PASSWORD milik 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_threshold untuk hanya melayani kecocokan yang lebih dekat, atau turunkan untuk melayani lebih banyak; nilai yang sesuai bergantung pada model embedding.