콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

이미 한 답변으로 응답하는 AI 게이트웨이

지원 어시스턴트는 하루 종일 조금씩 다른 표현으로 같은 질문을 받습니다. 모델 앞에 있는 게이트웨이는 모델을 다시 호출하는 대신, 의미가 충분히 가까운 이전 질문에 대해 했던 답변으로 질문에 응답할 수 있습니다. 이 워크스페이스는 그러한 게이트웨이를, 답변을 보관하는 저장소와 함께 Kubernetes 매니페스트로 컴파일합니다.

이를 수행하는 Feature는 core/semantic-caching입니다. 다른 호출자의 요청이 만들어 낸 답변 중 어떤 답변을 한 호출자에게 제공할 수 있는지가 이 페이지에서 가장 많은 분량을 할애하는 질문입니다. 잘못된 호출자들 사이에서 공유되는 캐시는 다른 사람을 위해 생성된 답변을 한 사람에게 넘겨주기 때문입니다.

이 워크스페이스는 자체 카탈로그 엔티티를 작성하지 않습니다. 여기 있는 세 개의 엔티티 파일, 즉 Aggregate, Manifest, Release가 누구든 작성하는 내용의 전부입니다.

구성되는 내용

인스턴스카탈로그 Component여기서의 역할
routercore/gateway/litellmAI 게이트웨이: 채팅 별칭 assistant와 임베딩 별칭 embedder를 제공하며, 각각 models 소켓에 연결된 모델에서 응답합니다
chatcore/ai-model/openaiassistant 뒤에 있는 채팅 모델로, OpenAI 자체 API를 참조로 사용합니다. 이를 위해 클러스터에서 실행되는 것은 없습니다
embeddingscore/ai-model/openai-embeddingembedder 뒤에 있는 임베딩 모델로, 같은 방식으로 사용합니다
cachecore/datastore/redis게이트웨이가 응답을 보관하는 저장소

uses 엣지는 세 개입니다. 두 개는 게이트웨이의 models 소켓으로 들어가 각 모델에 하나씩 연결되며, 각각 게이트웨이가 해당 모델에 제시하는 키를 credential로 전달합니다. 나머지 하나는 cache_store 소켓으로 들어가며, 캐시가 저장소에 제시하는 비밀번호를 credential로 전달합니다. 게이트웨이에는 Feature 연결이 두 개 있습니다. 관리용 키인 api_key와 캐시인 answers입니다. 저장소에는 저장소가 요구하는 비밀번호인 password가 하나 있습니다. 두 비밀번호 연결은 하나의 파라미터 cache_password를 읽고, 두 모델 자격 증명은 또 다른 파라미터 openai_key를 읽으며, Release가 둘 다 채웁니다. answers 연결은 각 프롬프트를 벡터로 바꾸는 임베딩 별칭, 두 프롬프트가 얼마나 비슷해야 하는지(코사인 유사도로 0.9), 그리고 저장된 응답이 유지되는 기간(한 시간)을 지정합니다. scope는 생략하므로 기본값 end_user를 사용합니다.

예제 생성하기

아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.

예제 이름을 딴 새 폴더에 예제를 씁니다:

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

그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:

Terminal window
cd ai-gateway-semantic-cache

빌드

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

release는 빌드하기 전에 lockfile이 필요하며, lockfile은 배포되지 않고 생성되므로 새로 clone한 저장소에는 lockfile이 없습니다. 먼저 lockfile을 해석하여 생성하거나, 빌드가 채우도록 합니다:

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

이 워크스페이스는 .aggrega-config.yaml이 지정하는 기본 레지스트리에서 카탈로그 엔티티를 해석합니다. 캐시의 실현 과정에서는 컴파일러에도 카탈로그에도 포함되지 않은 플러그인 하나, 즉 게이트웨이 구성 단계인 pipeline-step/litellm-gateway-config를 실행하며, 해석 과정은 이 플러그인을 default_registry가 지정하는 레지스트리인 hub.aggrega.ai에서 가져옵니다.

빌드는 다음을 출력하며, <workspace>는 이 예제의 폴더를 나타냅니다.

[… 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

AI 어시스턴트 사용

Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.

Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. 워크스페이스 폴더에 아직 `ai-gateway-semantic-cache` 폴더가 없으면 `example`에 `ai-gateway-semantic-cache`를 지정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 예제가 새 `ai-gateway-semantic-cache` 폴더에 쓰입니다. 그런 다음 `workspace_root`에 `ai-gateway-semantic-cache`, `release`에 `release.yaml`, `auto_pull`에 true, `write`에 true를 지정하여 `build` 도구를 호출하십시오. 빌드가 어떤 파일을 썼는지 알려 주십시오. 파일은 `ai-gateway-semantic-cache/dist/` 아래에 있습니다.

렌더링된 트리

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

cache attachment는 자체 파일을 가져오지 않습니다. 그 동작은 gateway의 구성에 기록됩니다. 각 모델은 하나의 파일, 즉 클러스터 내부 이름을 OpenAI의 API 호스트에 매핑하는 Service를 렌더링하며, 모델 연결의 각 자격 증명은 gateway와 연결의 alias를 따라 이름이 붙은 자체 Secret을 렌더링합니다.

제공하는 모델

게이트웨이 구성 본문의 시작 부분인 라우팅 테이블에는 models 소켓의 연결마다 항목이 하나씩 있습니다. 각 항목은 각 모델이 게시하는 내용, 즉 엔드포인트, OpenAI의 API 기본 URL, 모델 이름으로 작성되며, 게이트웨이의 Recipe가 해당 연결의 키를 전달하는 변수의 이름을 지정합니다:

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

게이트웨이가 읽는 캐시

다음은 게이트웨이의 구성 본문, 즉 dist/helm/router/litellm-gateway-config/configmap.yaml의 config.yaml 키를 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

여기서 읽어 낼 만한 점이 다섯 가지 있습니다.

저장소의 주소는 여기에 없습니다. host와 port는 게이트웨이 자체의 간접 참조를 통해 두 환경 변수를 지정하며, 게이트웨이의 Recipe가 그 변수들을 cache_store 에지에서 설정합니다. 다음은 dist/helm/router-deployment.yaml에서 게이트웨이 컨테이너의 env입니다:

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는 저장소 자체의 Recipe가 내보내는 Service로, 그 Recipe가 게시하는 내용에서 읽은 것이며, 6379는 그것이 게시하는 포트입니다. 캐시는 저장소의 비밀번호를 REDIS_PASSWORD에서 읽는데, 이는 cache_store 에지의 credential이 렌더링하는 Secret인 router-replies.credential에 대한 참조이며, 비밀번호 자체는 결코 읽지 않습니다. 저장소는 같은 파라미터 cache-password로 자체 Secret을 렌더링하고, 거기서 읽은 --requirepass로 시작하므로, 캐시가 제시하는 비밀번호와 저장소가 요구하는 비밀번호는 한 번 작성된 하나의 값입니다. cache_store 에지가 없으면 저장소의 주소와 비밀번호를 전달하는 세 변수 중 어느 것도 렌더링되지 않으며, 응답을 보관할 곳이 없는 캐시는 아래와 같이 빌드를 중단시킵니다. 세 번째와 네 번째 항목은 모델들의 키로, 각각 자기 연결의 자격 증명이 렌더링하는 Secret에서 라우팅 테이블의 해당 항목이 지정하는 변수로 참조됩니다. helm provider는 Secret에서 읽는 모든 항목을 일반 항목보다 앞에 씁니다.

임베딩 모델은 게이트웨이 자체 맵의 별칭입니다. 게이트웨이는 각 프롬프트를 호출자의 요청이 거치는 것과 같은 맵을 통해 embedder로 보내므로, 캐시는 자체 주소나 자격 증명을 갖지 않습니다. 맵이 게시하지 않는 별칭을 지정하면 빌드가 중단되며, 게시된 별칭들이 나열됩니다.

수명은 저장소의 것입니다. 각 응답은 ttl을 만료 시간으로 하여 기록되므로, Redis는 저장된 지 한 시간 후에 응답을 제거합니다. 그 프롬프트에 대한 다음 요청은 모델이 응답하고 새로 저장됩니다.

캐시가 프롬프트를 읽는 요청 종류만 지정됩니다. 스트리밍 여부와 관계없이 채팅 요청과 responses 및 messages API가 캐시됩니다. completions 요청은 캐시되지 않으며 embeddings 요청도 마찬가지입니다. 기본값에 맡기면 게이트웨이는 모든 embeddings 요청의 응답을 저장하면서 그렇게 하려고 각 입력을 한 번 더 임베딩하지만, 그중 어느 것도 다시 제공하지 않습니다.

인덱스는 게이트웨이와 연결을 따라 이름 붙여지므로(router-answers), 하나의 Release에서 저장소를 공유하는 두 게이트웨이는 응답을 별도의 인덱스에 보관합니다.

하나의 캐시 항목으로 누가 응답을 받는가

저장된 응답은 해당 버킷을 구성하는 모든 요소가 일치하고, 프롬프트가 그 응답이 답한 프롬프트와 최소 0.9 이상 유사할 때에만 이후 요청에 제공됩니다.

  • 게이트웨이가 검증한 요청이 제시하는 키와, 그 키의 팀 및 조직
  • end_user 아래에서는 요청이 지정하는 최종 사용자
  • 요청이 요구하는 모델과 요청의 기타 매개변수 — temperature가 다르면 다른 버킷입니다.

게이트웨이는 키, 키의 팀 및 조직, 최종 사용자를 요청 자체에 기록합니다. chat 요청에서는 이를 요청의 metadata에 기록하며, 호출자가 그곳에 보낸 값을 덮어씁니다. responses 또는 messages 요청에서는 이를 호출자의 metadata와 분리하여 보관하고, 호출자가 그 안에 쓴 팀, 조직 또는 최종 사용자 필드를 제거하며, 게이트웨이의 Recipe가 제공하는 요청 가드는 그곳에서 키를 지정하는 요청, 즉 metadata.user_api_key를 해당 필드를 명시한 HTTP 400으로 거부합니다. 따라서 어떤 요청도 이름을 지정하는 방식으로 다른 키의 버킷에 들어갈 수 없습니다.

요청 자체의 metadata는 여전히 요청이 제시하는 키의 버킷들 사이에서 요청을 이동시킬 수 있습니다. responses 요청에서는 model_group이 버킷에서 요청이 요구하는 모델을 대신합니다. responses 또는 messages 요청에서는 caching_groups를 통해 동일한 모델 별칭 그룹을 지정하는 요청들이 그 별칭들에 걸쳐 응답을 공유할 수 있습니다. responses 또는 chat 요청에서는 redis_namespace가 네임스페이스를 지정하는 요청을 지정하지 않는 요청과 별도의 버킷에 둡니다. 이 중 어느 것도 다른 키의 버킷에는 도달하지 않습니다.

이 게이트웨이의 키는 관리 키이며, 모든 호출자가 이를 보유합니다. 게이트웨이에는 장부 데이터베이스가 연결되어 있지 않으므로 자체 키를 발급하지 않습니다. 모든 호출자는 api_key에 연결된 키를 제시하며, 키가 없거나 게이트웨이가 발급하지 않은 키를 가진 요청은 어떤 조회도 하기 전에 거부됩니다. 따라서 여기서 키는 호출자를 서로 구분하지 않으며, 기본 범위에서 두 호출자를 구분하는 것은 각 요청이 지정하는 최종 사용자입니다.

기본값인 end_user에서는 항목이 동일한 최종 사용자를 지정하는 요청에 제공됩니다. 게이트웨이는 요청에서 최종 사용자를 읽습니다. x-litellm-end-user-id 또는 x-litellm-customer-id 헤더, 또는 본문의 user, metadata.user_id, litellm_metadata.user 또는 safety_identifier 필드입니다. alice를 위해 저장된 응답은 alice의 비슷한 표현의 질문에 제공되고, bob의 질문에는 제공되지 않습니다.

여기서 두 가지가 따르며, 둘 다 구성이 아니라 게이트웨이의 동작입니다.

  • 게이트웨이는 이러한 이름을 전혀 검증하지 않습니다. 키를 가진 사람은 누구든 어떤 최종 사용자든 지정할 수 있으며 그 최종 사용자를 위해 저장된 것을 제공받습니다. 키는 자신의 최종 사용자가 누구인지 아는 애플리케이션에 두고, 애플리케이션이 그들을 지정하게 하십시오. 키를 최종 사용자 본인에게 건네지 마십시오.
  • 최종 사용자를 지정하지 않는 요청은 하나의 캐시를 공유합니다. 동일한 키를 제시하는 그러한 요청은 누가 보냈든 모두 동일한 항목에서 제공받습니다.

key에서는 키를 제시하는 모든 호출자가 하나의 캐시에서 제공받습니다. 연결의 values에 scope: key를 추가하고 다시 빌드하면, 구성의 semantic_cache_scope가 key가 되고 렌더링된 출력의 다른 부분은 바뀌지 않습니다. 이때 헤더가 지정하는 최종 사용자는 버킷의 일부가 아니므로, x-litellm-end-user-id 헤더로 지정된 alice를 위해 저장된 응답이 같은 방식으로 지정된 bob의 비슷한 표현의 질문에도 제공되며, 그 안의 도구 호출도 포함됩니다. 다만 본문의 user 필드는 요청의 기타 매개변수 중 하나이므로, 그곳에 서로 다른 최종 사용자를 지정한 두 요청은 두 temperature가 그렇듯 여전히 다른 버킷에 속합니다. 이는 모든 사람에게 동일한 답변의 캐시에만 적합합니다.

빌드를 중단시키는 것

다음 각 경우에 빌드는 무엇을 바꿔야 하는지 알려 주는 문장을 출력합니다.

  • 관리 키가 없는 경우. api_key 연결을 제거하면 아무것도 렌더링되기 전에 빌드가 중단됩니다:

    [… 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"
  • 저장소가 없는 경우. cache_store 에지를 제거하면 연결할 소켓을 지목하며 빌드가 중단됩니다.

  • vector_search를 게시하지 않는 저장소. 소켓은 키-값 저장소를 받아들이며, 게이트웨이의 Recipe는 캐시가 응답을 검색하는 데 사용하는 Redis 쿼리 엔진의 벡터 검색을 제공한다고 명시하지 않는 저장소에서 중단됩니다. 8.0 이전 릴리스의 Redis나 Valkey는 모든 요청이 여전히 성공하는 동안 아무것도 캐시하지 않습니다.

  • 게이트웨이에 두 번째 core/semantic-caching 연결: 게이트웨이의 캐시는 하나뿐입니다.

  • 같은 게이트웨이의 core/data-masking. 캐시는 마스킹 이후에 요청의 키를 정하므로, 마스킹이 대체하는 내용만 다른 두 요청이 하나의 저장된 응답을 공유하게 됩니다. 그래서 둘은 충돌을 선언합니다.

저장소를 사용할 수 없을 때

게이트웨이는 시작할 때가 아니라 처음 요청을 처리할 때 저장소에 연결합니다. 게이트웨이가 저장소를 사용할 수 없으면 — 저장소가 게이트웨이에 주어지지 않은 비밀번호를 요구하거나, 주어진 비밀번호를 거부하면 — 모든 조회가 실패하고 아무것도 저장되지 않지만, 모든 요청은 여전히 모델이 응답합니다. 이를 알려 주는 것은 게이트웨이 자체의 로그뿐입니다. 그래서 비밀번호의 양쪽 끝, 즉 저장소의 password 슬롯과 cache_store 엣지의 credential이 하나의 파라미터를 읽습니다.

컴파일러가 해석하지 않는 부분

컴파일러는 store의 Service 이름과 포트를 store의 Recipe에서 gateway의 환경 변수로 문자열로 전달하고, 별칭과 숫자 값은 gateway의 구성으로 전달합니다. 컴파일러는 store에 연결하지 않으며, cache-default:6379에서 무언가가 응답하는지 알지 못하고, 최종 사용자가 무엇인지도 알지 못합니다. 위의 각 중단은 카탈로그 자체의 엔터티가 선언한 것으로, realization이나 gateway의 Recipe에 있는 어설션이거나 두 Features가 선언하는 충돌이며, 그 어느 것도 트래픽에 대한 이해에 기반하지 않습니다.

응용하기

  • 키마다 캐시 하나를 공유합니다. 모든 호출자가 같은 응답을 받아야 하는 경우, answers 연결에 scope: key를 추가합니다.
  • 비밀번호 없이 저장소를 실행합니다. 저장소의 password 연결과 cache_store 엣지의 credential을 함께 제거하고, Aggregate와 Release의 cache_password 파라미터도 함께 제거합니다. 그러면 게이트웨이의 REDIS_PASSWORD가 빈 값으로 렌더링되어 비밀번호 없이 연결합니다. 두 연결 중 하나만 제거하면 캐시가 저장소를 사용할 수 없게 됩니다.
  • 더 많거나 더 적은 프롬프트를 일치시킵니다. 더 가까운 일치만 제공하려면 similarity_threshold를 높이고, 더 많이 제공하려면 낮춥니다. 어떤 값이 적합한지는 임베딩 모델에 따라 다릅니다.