이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.
Apigee Edge 문서 보기
이 튜토리얼에서는 유연한 정책 기반 라우팅 규칙에 따라 대규모 언어 모델 (LLM) 요청을 다양한 백엔드 모델로 라우팅하는 AI 게이트웨이로 Apigee를 구성하고 사용하는 방법을 보여줍니다. AI 게이트웨이를 사용하면 모델 트래픽을 보호하고, 관리하고, 최적화하여 비용을 관리하고 모델 확산을 방지할 수 있습니다.
튜토리얼의 각 단계는 재사용 가능한 Apigee 기능 템플릿 (AFT) 파일을 통해 특정 기능을 추가하여 이전 구성을 기반으로 합니다.
- 1단계: 단일 LLM 제공업체를 프런트하는 최소 API 프록시를 배포합니다.
- 2단계: Model Armor 프롬프트 및 대답 정제를 추가하여 악성 입력을 필터링하고 민감한 정보 유출을 방지합니다.
- 3단계: 교차 제공업체 모델 라우팅과 Agent Platform 벡터 검색으로 지원되는 시맨틱 캐시를 추가합니다.
- 4단계: 기본 대상이
4xx또는5xxHTTP 상태 코드를 반환하는 경우 보조 제공업체에 대해 요청을 자동으로 재시도하도록 교차 제공업체 대체 구성을 구성합니다.
기능을 추가하려면 템플릿의 features 블록에 한 줄을 추가합니다. AFT 파일 및 도우미 스크립트를 포함한 전체 예시 파일 세트를 보거나 다운로드하려면 GitHub의 Apigee 템플릿 저장소를 참조하세요.
시작하기 전에
이 튜토리얼을 완료하기 전에 다음이 있는지 확인하세요.
- 결제가 사용 설정된 활성 Google Cloud 프로젝트
- Apigee 인스턴스에서 사용할 수 있는 종합 환경 Model Armor,
SemanticCacheLookup,SemanticCachePopulate정책은 종합 환경에만 배포할 수 있습니다. - 애플리케이션 기본 사용자 인증 정보 (ADC)로 설치 및 구성된 Google Cloud CLI (
gcloud) 사용자 인증 정보를 생성하려면gcloud auth application-default login를 실행합니다. - 다음 IAM 역할이 있는 런타임 서비스 계정:
roles/aiplatform.userroles/modelarmor.user
- 2단계, 3단계, 4단계에서는 Model Armor 템플릿 리소스 경로를 지정합니다. 예를 들면 다음과 같습니다.
projects/YOUR_PROJECT/locations/us-central1/templates/apigee-aft-demo-ma. - 3단계 및 4단계: 유효한 OpenAI API 키가 포함된
api-key항목이 환경에 있는openai-credentials라는 Apigee 키-값 맵 (KVM) - 3단계 및 4단계: 시맨틱 캐시용으로 배포된 Vertex AI 벡터 검색 색인 엔드포인트 단계별 색인 설정은 GitHub의 Apigee 템플릿 저장소 리드미를 참조하세요.
개요
네 단계 모두 /v1/chat/completions[-stageN]에서 OpenAI Chat Completions 요청 형식을 허용하므로 동일한 클라이언트 SDK가 모든 단계에서 작동합니다. model 필드 접두사는 라우팅 결정을 주도합니다. google/* 모델에 대한 요청은 Agent Platform의 Gemini로 라우팅되고 다른 모든 요청은 OpenAI로 라우팅됩니다. 이 반전된 기본값은 o1-*, o3-*, chatgpt-*와 같은 새로운 OpenAI 모델 계열이 gpt-* 프리픽스 일치를 자동으로 누락하지 않고 올바르게 라우팅되도록 합니다.
| 단계 | 기능 추가됨 | 기본 경로 |
|---|---|---|
| 1 | Hello LLM (에이전트 플랫폼에서 Gemini에 대한 OpenAI 형식 요청) | /v1/chat/completions |
| 2 | Model Armor (프롬프트 인젝션, 책임감 있는 AI, Sensitive Data Protection 필터) | /v1/chat/completions-stage2 |
| 3 | 교차 제공업체 라우팅 및 Agent Platform 벡터 검색 시맨틱 캐시 | /v1/chat/completions-stage3 |
| 4 | 교차 제공업체 대체 (완전한 AI 게이트웨이) | /v1/chat/completions-stage4 |
1단계: Hello LLM
최소 프록시는 OpenAI 호환 엔드포인트를 통해 단일 Gemini 타겟을 프런트합니다. 두 개의 작은 기능 파일은 기본 프록시 스켈레톤과 JSON 추출기를 제공합니다. 추출기는 이후 단계에 일관된 입력이 있도록 $.model 및 $.messages[-1].content를 llm.model 및 llm.prompt 흐름 변수에 복사합니다.
llm-base.yaml은 기본 프록시 스켈레톤을 정의합니다.
gateway: apigee schemaVersion: 1.0.0 name: llm-base type: feature parameters: - name: BASE_PATH default: /v1/chat/completions endpoints: - name: default basePath: "{BASE_PATH}" routes: - name: primary target: gemini-target
llm-openai-format.yaml는 OpenAI 모양의 요청 필드를 추출합니다.
gateway: apigee schemaVersion: 1.0.0 name: llm-openai-format type: feature defaultEndpoint: name: default flows: - name: PreFlow mode: Request steps: - name: EV-ExtractOpenAIRequest policies: - name: EV-ExtractOpenAIRequest type: ExtractVariables content: ExtractVariables: metadata: name: EV-ExtractOpenAIRequest continueOnError: "true" Source: _text: request JSONPayload: Variable: - metadata: name: model JSONPath: _text: "$.model" - metadata: name: prompt JSONPath: _text: "$.messages[-1].content" VariablePrefix: _text: llm
target-vertex-gemini.yaml은 OpenAI 호환 엔드포인트를 사용하는 Agent Platform 대상을 정의합니다.
gateway: apigee schemaVersion: 1.0.0 name: target-vertex-gemini type: feature targets: - name: gemini-target httpTargetConnection: URL: https://aiplatform.googleapis.com/v1/projects/{organization.name}/locations/global/endpoints/openapi/chat/completions Authentication: GoogleAccessToken: Scopes: Scope: https://www.googleapis.com/auth/cloud-platform
기능 파일을 1단계 템플릿인 01-hello-llm.yaml에 작성합니다.
gateway: apigee schemaVersion: 1.0.0 name: aft-demo-01-hello-llm features: - llm-base.yaml - llm-openai-format.yaml - target-vertex-gemini.yaml
템플릿을 배포합니다.
gcloud beta apigee apis import aft-demo-01-hello-llm \ --from-template=01-hello-llm.yaml \ --organization=APIGEE_ORG
프록시를 테스트합니다.
curl -X POST https://APIGEE_HOSTNAME/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"google/gemini-2.5-flash", "messages":[{"role":"user","content":"Explain how AI works in a few words"}]}'
다음을 바꿉니다.
APIGEE_ORG: Apigee 조직 이름입니다.APIGEE_HOSTNAME: Apigee 환경 그룹의 호스트 이름(일반적으로 Google Cloud 부하 분산기)
2단계: Model Armor 추가
Model Armor는 대상 호출 전에 수신되는 프롬프트에서 프롬프트 인젝션, 허용되지 않는 콘텐츠, 민감한 정보를 검사합니다. 그런 다음 응답이 클라이언트에 도달하기 전에 모델 응답을 스캔합니다.
템플릿에 기능 파일 1개(llm-model-armor.yaml)를 추가합니다.
gateway: apigee schemaVersion: 1.0.0 name: llm-model-armor type: feature parameters: - name: MA_TEMPLATE_PATH default: projects/{organization.name}/locations/us-central1/templates/apigee-aft-demo-ma defaultEndpoint: name: default flows: - name: PreFlow mode: Request steps: - name: MA-SanitizeUserPrompt - name: PostFlow mode: Response steps: - name: MA-SanitizeModelResponse policies: - name: MA-SanitizeUserPrompt type: SanitizeUserPrompt content: SanitizeUserPrompt: metadata: name: MA-SanitizeUserPrompt ModelArmor: TemplateName: _text: "{MA_TEMPLATE_PATH}" UserPromptSource: _text: "{llm.prompt}" - name: MA-SanitizeModelResponse type: SanitizeModelResponse content: SanitizeModelResponse: metadata: name: MA-SanitizeModelResponse ModelArmor: TemplateName: _text: "{MA_TEMPLATE_PATH}" UserPromptSource: _text: "{llm.prompt}" LLMResponseSource: _text: "{jsonPath('$.choices[-1].message.content',response.content,true)}"
2단계 템플릿 02-add-model-armor.yaml에 한 줄이 추가됩니다.
gateway: apigee schemaVersion: 1.0.0 name: aft-demo-02-add-model-armor features: - llm-base.yaml - llm-openai-format.yaml - target-vertex-gemini.yaml - llm-model-armor.yaml # <-- the change from Stage 1 parameters: - name: BASE_PATH default: /v1/chat/completions-stage2
MA_TEMPLATE_PATH 매개변수는 기본적으로 us-central1의 apigee-aft-demo-ma라는 템플릿으로 설정됩니다. 자체 Model Armor 템플릿을 사용하려면 템플릿의 parameters 블록에서 파라미터를 재정의합니다.
3단계: 교차 제공업체 라우팅 및 시맨틱 캐시 추가
3단계에서는 두 번째 대상 (OpenAI)을 추가하고, 단일 라우팅 규칙을 모델 기반 라우팅으로 바꾸고, 두 대상 앞에 Agent Platform 벡터 검색에서 지원하는 시맨틱 캐시를 구성합니다.
3단계를 구성하려면 템플릿의 features 블록에 세 가지 기능 파일을 추가합니다.
target-openai-gpt.yaml: OpenAI를 보조 대상 엔드포인트로 추가합니다.llm-routing.yaml: 요청된 모델 이름을 기반으로 요청을 동적으로 라우팅합니다.llm-semantic-cache.yaml: 두 제공업체 앞에 시맨틱 캐시를 추가합니다.
다음 예는 llm-routing.yaml 기능 파일이 라우팅 로직을 정의하는 방법을 보여줍니다.
gateway: apigee schemaVersion: 1.0.0 name: llm-routing type: feature parameters: - name: BASE_PATH default: /v1/chat/completions endpoints: - name: default basePath: "{BASE_PATH}" routes: - name: gemini condition: llm.model StartsWith "google/" target: gemini-target - name: openai target: openai-target # default when the condition is false
시맨틱 캐시는 캐시 부적중 시에만 요청 PreFlow에서 SemanticCacheLookup를 실행하고 응답 PostFlow에서 SemanticCachePopulate를 실행합니다. 두 정책 모두 별도로 프로비저닝하는 Agent Platform 벡터 검색 색인 엔드포인트를 사용합니다. 다음 발췌문에서는 정책 정의의 주요 부분을 보여줍니다.
policies: - name: SCLLookup type: SemanticCacheLookup content: SemanticCacheLookup: UserPromptSource: _text: "{llm.prompt}" Embeddings: VertexAI: URL: _text: "https://{EMBEDDINGS_LOCATION}-aiplatform.googleapis.com/v1/projects/{organization.name}/locations/{EMBEDDINGS_LOCATION}/publishers/google/models/{EMBEDDINGS_MODEL}:predict" SimilaritySearch: VertexAI: URL: _text: "https://{VECTOR_INDEX_ENDPOINT_SUBDOMAIN}.{EMBEDDINGS_LOCATION}-{PROJECT_NUMBER}.vdb.vertexai.goog/v1/projects/{organization.name}/locations/{EMBEDDINGS_LOCATION}/indexEndpoints/{VECTOR_INDEX_ENDPOINT_ID}:findNeighbors" DeployedIndexID: _text: "{DEPLOYED_INDEX_ID}" Threshold: _text: "{THRESHOLD}" - name: SCPPopulate type: SemanticCachePopulate # ... (see the GitHub repository for the full definition)
3단계 템플릿은 모든 기능 파일을 구성합니다.
gateway: apigee schemaVersion: 1.0.0 name: aft-demo-03-add-routing-and-cache features: - llm-base.yaml - llm-openai-format.yaml - target-vertex-gemini.yaml - llm-model-armor.yaml - target-openai-gpt.yaml # <-- add OpenAI target - llm-routing.yaml # <-- add model-name routing - llm-semantic-cache.yaml # <-- add semantic cache parameters: - name: BASE_PATH default: /v1/chat/completions-stage3 - name: VECTOR_INDEX_ENDPOINT_ID default: "YOUR_INDEX_ENDPOINT_ID" - name: VECTOR_INDEX_ID default: "YOUR_INDEX_ID" - name: VECTOR_INDEX_ENDPOINT_SUBDOMAIN default: "YOUR_SUBDOMAIN" - name: PROJECT_NUMBER default: "YOUR_PROJECT_NUMBER" - name: DEPLOYED_INDEX_ID default: "YOUR_DEPLOYED_INDEX_ID"
1단계에서 사용한 --from-template 플래그와 함께 동일한 gcloud beta apigee apis import 명령어를 사용하여 템플릿을 배포합니다.
4단계: 교차 제공업체 대체 추가
4단계에서는 두 타겟 모두에 DefaultFaultRule를 연결합니다. 기본 대상이 4xx 또는 5xx 상태를 반환하면 오류 규칙은 동일한 프롬프트가 포함된 ServiceCallout를 다른 제공업체에 전송하고 해당 응답을 클라이언트에 반환합니다. 클라이언트는 정상 완료와 함께 성공적인 200 응답을 수신하며 자체 재시도 로직이나 오류 처리가 필요하지 않습니다.
llm-fallback.yaml 기능 파일은 이 동작을 추가합니다. 다음 예시는 축약되어 있습니다. 전체 파일은 GitHub 저장소를 참조하세요.
gateway: apigee schemaVersion: 1.0.0 name: llm-fallback type: feature targets: # Vertex primary; on 4xx/5xx, fall back to OpenAI. - name: gemini-target httpTargetConnection: Properties: Property: metadata: name: success.codes _text: "2XX" URL: https://aiplatform.googleapis.com/v1/projects/{organization.name}/locations/global/endpoints/openapi/chat/completions Authentication: GoogleAccessToken: Scopes: Scope: https://www.googleapis.com/auth/cloud-platform flows: - name: PostFlow mode: Response steps: - name: RF-TargetErrorToFault condition: response.status.code >= 400 defaultFaultRule: name: FallbackToOpenAI steps: - name: KVM-GetOpenAIKey - name: AM-BuildOpenAIFallbackRequest - name: SC-FallbackToOpenAI - name: AM-CopyOpenAIFallbackResponse # OpenAI primary; on 4xx/5xx, fall back to Vertex. - name: openai-target httpTargetConnection: Properties: Property: metadata: name: success.codes _text: "2XX" URL: https://api.openai.com/v1/chat/completions flows: - name: PreFlow mode: Request steps: - name: JS-StripOpenAIModelPrefix - name: KVM-GetOpenAIKey - name: AM-SetOpenAIAuth - name: PostFlow mode: Response steps: - name: RF-TargetErrorToFault condition: response.status.code >= 400 defaultFaultRule: name: FallbackToVertex steps: - name: AM-BuildVertexFallbackRequest - name: SC-FallbackToVertex - name: AM-CopyVertexFallbackResponse policies: # RaiseFault converts a target 4xx/5xx into a fault so DefaultFaultRule fires. - name: RF-TargetErrorToFault type: RaiseFault content: RaiseFault: IgnoreUnresolvedVariables: "true" # empty FaultResponse -- DefaultFaultRule builds the real response # ... AM-Build*, SC-Fallback*, AM-Copy* policies -- see GitHub repository
대체는 다음 두 가지 설정에 따라 달라집니다.
success.codes: 2XX(두httpTargetConnection블록 모두) Apigee는2xx가 아닌 모든 대상 응답을 대상 실패로 처리하고 오류 흐름으로 바로 전환합니다.- 각 타겟의 응답 PostFlow에 있는
RaiseFault정책으로,response.status.code >= 400에 따라 게이트됩니다. 이 정책은 모든 오류 응답에 대해DefaultFaultRule가 실행되도록 보장합니다.
3단계 템플릿에 한 줄을 추가하는 4단계 템플릿을 작성합니다.
gateway: apigee schemaVersion: 1.0.0 name: aft-demo-04-add-fallback features: - llm-base.yaml - llm-openai-format.yaml - target-vertex-gemini.yaml - llm-model-armor.yaml - target-openai-gpt.yaml - llm-routing.yaml - llm-semantic-cache.yaml - llm-fallback.yaml # <-- the change from Stage 3 parameters: - name: BASE_PATH default: /v1/chat/completions-stage4 # ... Model Armor and Vector Search parameters as in Stage 3
템플릿을 배포합니다.
gcloud beta apigee apis import aft-demo-04-add-fallback \ --from-template=04-add-fallback.yaml \ --organization=APIGEE_ORG
엔드 투 엔드 동작 확인
GitHub 저장소에는 주제별로 다양한 프롬프트를 사용하여 모든 라우팅 및 대체 경로를 실행하는 routing-diagnostic.sh 스크립트가 포함되어 있습니다. 의미 캐시는 유사한 프롬프트를 단락시키므로 각 테스트 프롬프트는 명확하게 표현해야 합니다.
STAGE=4 ./routing-diagnostic.sh
스크립트는 4단계 프록시를 통해 5개의 요청을 전송합니다.
- 표준 OpenAI 모델
google/프리픽스가 있는 Gemini 모델- 접두사가 없는 Gemini 모델 이름으로, 반전된 기본값에 따라 OpenAI로 라우팅됩니다.
- OpenAI 추론 모델
openai/프리픽스가 있는 모델 이름
각 요청에 대해 스크립트는 응답을 제공한 업스트림 제공업체와 대체가 발생했는지 여부를 보고합니다.
단일 요청에 대한 모든 정책 단계, 대상 호출, 오류 규칙 전환을 보려면 배포된 버전에 대해 Apigee 디버그 세션을 만듭니다.
DEBUG_URL="https://apigee.googleapis.com/v1/organizations/APIGEE_ORG/environments/APIGEE_ENV/apis/aft-demo-04-add-fallback/revisions/REVISION/debugsessions" curl -X POST -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json" \ -d '{"filter":"","count":10,"timeout":"600","validity":600}' \ "$DEBUG_URL"
다음을 바꿉니다.
APIGEE_ORG: Apigee 조직 이름입니다.APIGEE_ENV: 프록시를 배포한 환경입니다.REVISION: 배포된aft-demo-04-add-fallback프록시의 버전 번호입니다.
그런 다음 대체 기능을 실행하는 요청을 전송합니다.
curl -X POST https://APIGEE_HOSTNAME/v1/chat/completions-stage4 \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o-mini", "messages":[{"role":"user","content":"Describe nuclear fusion in stars in two sentences."}]}'
Apigee API를 사용하여 캡처된 디버그 세션 메시지를 가져오면 trace에 다음 실행 흐름이 표시됩니다.
- 요청 변수 추출: Apigee는 수신 페이로드에서
llm.model및llm.prompt변수를 추출합니다. - 안전 정책 평가: 요청이 Model Armor 보안 필터링을 통과합니다.
- 시맨틱 캐시 확인: 조회에서 시맨틱 캐시를 놓치므로 요청이 타겟으로 계속됩니다.
- 라우팅 조건 평가:
llm.model StartsWith "google/"조건은false로 평가됩니다. - 기본 대상으로 라우팅: Apigee가 요청을
openai-target로 전달합니다. - 대상 오류 처리: OpenAI 대상은
2xx이외의 HTTP 상태 코드를 반환하므로 Apigee에서 대상 오류가 발생합니다. - 오류 규칙 실행:
DefaultFaultRule는AM-BuildVertexFallbackRequest,SC-FallbackToVertex,AM-CopyVertexFallbackResponse를 실행하여 대체 시퀀스를 트리거합니다. - 응답 반환: 클라이언트는 Agent Platform의 Gemini에서 생성된 페이로드가 포함된 HTTP
200응답을 수신합니다.
다음 단계
- 인증 구성: 프록시 앞에 제휴 JWT, OpenID Connect (OIDC) 또는 Apigee API 키를 구현하여 테넌트별 토큰 할당량과 제공업체 액세스 제어를 적용합니다.
- 비용 및 지연 시간 모니터링: Apigee 분석 대시보드를 API 프록시에 연결하여 모델별로 지연 시간과 운영 비용을 추적합니다.
- 테넌트별 안전 정책 적용:
MA_TEMPLATE_PATH매개변수를 사용하여 테넌트별 Model Armor 템플릿을 구성하여 엔터프라이즈, 개발자, 공개 트래픽 전반에 맞춤형 삭제 규칙을 적용합니다. - 샘플 구성 살펴보기:
llm-fallback.yaml템플릿, 기능 파일 8개,routing-diagnostic.sh스크립트, KVM, Model Armor, Agent Platform 벡터 검색을 위한 프로비저닝 스크립트를 포함한 전체 예시 세트를 다운로드하려면 GitHub의 Apigee 점진적 AI 게이트웨이 저장소를 참조하세요.