Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Membangun gateway AI dengan perutean, Model Armor, dan cache semantik

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Tutorial ini menunjukkan cara mengonfigurasi dan menggunakan Apigee sebagai gateway AI yang merutekan permintaan model bahasa besar (LLM) ke berbagai model backend berdasarkan aturan perutean yang fleksibel dan berbasis kebijakan. Gateway AI membantu Anda mengamankan, mengatur, dan mengoptimalkan traffic model untuk mengelola biaya dan mencegah penyebaran model.

Setiap tahap tutorial dibuat berdasarkan konfigurasi sebelumnya dengan menambahkan kemampuan tertentu melalui file Template Fitur Apigee (AFT) yang dapat digunakan kembali:

Tahap 1: Deploy proxy API minimal yang mengarah ke satu penyedia LLM.
Tahap 2: Tambahkan sanitasi perintah dan respons Model Armor untuk memfilter input berbahaya dan mencegah kebocoran data sensitif.
Tahap 3: Tambahkan perutean model lintas penyedia dan cache semantik yang didukung oleh Penelusuran Vektor Agent Platform.
Tahap 4: Konfigurasikan penggantian lintas penyedia untuk otomatis mencoba ulang permintaan terhadap penyedia sekunder jika target utama menampilkan kode status HTTP 4xx atau 5xx.

Untuk menambahkan kemampuan, tambahkan satu baris ke blok features di template Anda. Untuk melihat atau mendownload kumpulan lengkap file contoh, termasuk file AFT dan skrip bantuan, lihat Repositori Template Apigee di GitHub.

Sebelum memulai

Sebelum menyelesaikan tutorial ini, pastikan Anda memiliki hal berikut:

Project Google Cloud aktif dengan penagihan diaktifkan.
Lingkungan Komprehensif yang tersedia di instance Apigee Anda. Anda hanya dapat men-deploy kebijakan Model Armor, SemanticCacheLookup, dan SemanticCachePopulate di lingkungan Komprehensif.
Google Cloud CLI (gcloud) diinstal dan dikonfigurasi dengan Kredensial Default Aplikasi (ADC). Untuk membuat kredensial, jalankan gcloud auth application-default login.
Akun layanan runtime dengan peran IAM berikut:
- roles/aiplatform.user
- roles/modelarmor.user
Akun layanan juga memerlukan akses ke kredensial khusus penyedia.
Untuk tahap 2, 3, dan 4, tentukan jalur resource template Model Armor. Misalnya, projects/YOUR_PROJECT/locations/us-central1/templates/apigee-aft-demo-ma.
Untuk tahap 3 dan 4: Peta nilai kunci (KVM) Apigee bernama openai-credentials di lingkungan Anda yang berisi entri api-key dengan kunci OpenAI API yang valid.
Untuk tahap 3 dan 4: Endpoint indeks Vertex AI Vector Search yang di-deploy untuk cache semantik. Untuk penyiapan indeks langkah demi langkah, lihat README Repositori Template Apigee di GitHub.

Ringkasan

Keempat tahap menerima bentuk permintaan OpenAI Chat Completions di /v1/chat/completions[-stageN], sehingga SDK klien yang sama berfungsi di setiap tahap. Awalan kolom model mendorong keputusan perutean: permintaan untuk model google/* dirutekan ke Gemini di Agent Platform, dan semua permintaan lainnya dirutekan ke OpenAI. Default terbalik ini memastikan bahwa keluarga model OpenAI baru, seperti o1-*, o3-*, dan chatgpt-*, dirutekan dengan benar, bukan diam-diam tidak memiliki kecocokan awalan gpt-*.

Tahap	Kemampuan ditambahkan	Base path
1	Halo LLM (permintaan berformat OpenAI ke Gemini di Agent Platform)	`/v1/chat/completions`
2	Model Armor (filter injeksi perintah, AI yang bertanggung jawab, dan Sensitive Data Protection)	`/v1/chat/completions-stage2`
3	Perutean lintas penyedia dan cache semantik Penelusuran Vektor Agent Platform	`/v1/chat/completions-stage3`
4	Penggantian lintas penyedia (gateway AI lengkap)	`/v1/chat/completions-stage4`

Tahap 1: Halo LLM

Proxy minimal ini mengarahkan ke satu target Gemini melalui endpoint yang kompatibel dengan OpenAI. Dua file fitur kecil menyediakan kerangka proxy dasar dan ekstraktor JSON. Ekstraktor menyalin $.model dan $.messages[-1].content ke dalam flow variable llm.model dan llm.prompt sehingga tahap selanjutnya memiliki input yang konsisten.

llm-base.yaml menentukan kerangka proxy dasar:

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 mengekstrak kolom permintaan berbentuk 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 menentukan target Agent Platform yang menggunakan endpoint yang kompatibel dengan OpenAI:

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

Susun file fitur ke dalam template Tahap 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

Deploy template:

gcloud beta apigee apis import aft-demo-01-hello-llm \
  --from-template=01-hello-llm.yaml \
  --organization=APIGEE_ORG

Uji proxy:

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"}]}'

Ganti kode berikut:

APIGEE_ORG: nama organisasi Apigee Anda.
APIGEE_HOSTNAME: nama host grup lingkungan Apigee Anda, biasanya load balancer Google Cloud .

Tahap 2: Menambahkan Model Armor

Model Armor memeriksa perintah yang masuk untuk mendeteksi injeksi perintah, konten yang tidak diizinkan, dan data sensitif sebelum panggilan target. Kemudian, Model Armor memindai respons model sebelum respons tersebut sampai ke klien.

Tambahkan satu file fitur ke template, 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)}"

Template Tahap 2, 02-add-model-armor.yaml, menambahkan satu baris:

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

Parameter MA_TEMPLATE_PATH ditetapkan secara default ke template bernama apigee-aft-demo-ma di us-central1. Untuk menggunakan template Model Armor Anda sendiri, ganti parameter di blok parameters template.

Tahap 3: Menambahkan pemilihan rute lintas penyedia dan cache semantik

Pada Tahap 3, Anda akan menambahkan target kedua (OpenAI), mengganti aturan rute tunggal dengan pemilihan rute berbasis model, dan mengonfigurasi cache semantik yang didukung oleh Penelusuran Vektor Agent Platform di depan kedua target.

Untuk mengonfigurasi Tahap 3, tambahkan tiga file fitur ke blok features di template Anda:

target-openai-gpt.yaml: Menambahkan OpenAI sebagai endpoint target sekunder.
llm-routing.yaml: Merutekan permintaan secara dinamis berdasarkan nama model yang diminta.
llm-semantic-cache.yaml: Menambahkan cache semantik di depan kedua penyedia.

Contoh berikut menunjukkan cara file fitur llm-routing.yaml menentukan logika pemilihan rute:

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

Cache semantik menjalankan SemanticCacheLookup di PreFlow permintaan dan SemanticCachePopulate di PostFlow respons, hanya saat cache tidak ditemukan. Kedua kebijakan tersebut menggunakan endpoint indeks Penelusuran Vektor Agent Platform yang Anda sediakan secara terpisah. Kutipan berikut menunjukkan bagian-bagian penting dari definisi kebijakan:

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)

Template Tahap 3 menyusun semua file fitur:

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"

Deploy template menggunakan perintah gcloud beta apigee apis import yang sama dengan flag --from-template yang Anda gunakan di Tahap 1.

Tahap 4: Tambahkan penggantian lintas penyedia

Tahap 4 melampirkan DefaultFaultRule ke kedua target. Saat target utama menampilkan status 4xx atau 5xx, aturan kesalahan akan mengirimkan ServiceCallout dengan perintah yang sama ke penyedia lain dan menampilkan respons tersebut ke klien. Klien menerima respons 200 yang berhasil dengan penyelesaian normal dan tidak memerlukan logika percobaan ulang atau penanganan error-nya sendiri.

File fitur llm-fallback.yaml menambahkan perilaku ini. Contoh berikut disingkat. Untuk file lengkap, lihat repositori 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

Penggantian bergantung pada dua setelan:

success.codes: 2XX di kedua blok httpTargetConnection. Apigee memperlakukan respons target non-2xx sebagai kegagalan target dan langsung beralih ke alur kesalahan.
Kebijakan RaiseFault di PostFlow respons setiap target, yang dibatasi pada response.status.code >= 400. Kebijakan ini menjamin bahwa DefaultFaultRule berjalan untuk setiap respons error.

Buat template Tahap 4, yang menambahkan satu baris ke template Tahap 3:

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

Deploy template:

gcloud beta apigee apis import aft-demo-04-add-fallback \
  --from-template=04-add-fallback.yaml \
  --organization=APIGEE_ORG

Memverifikasi perilaku menyeluruh

Repositori GitHub menyertakan skrip routing-diagnostic.sh yang menjalankan semua jalur pemilihan rute dan penggantian dengan perintah yang beragam topiknya. Karena cache semantik memotong perintah yang serupa, setiap perintah pengujian harus diucapkan dengan jelas.

STAGE=4 ./routing-diagnostic.sh

Skrip mengirimkan lima permintaan melalui proxy Tahap 4:

Model OpenAI kanonis
Model Gemini dengan awalan google/
Nama model Gemini tanpa awalan, yang merutekan ke OpenAI di bawah default terbalik
Model penalaran OpenAI
Nama model dengan awalan openai/

Untuk setiap permintaan, skrip melaporkan penyedia upstream mana yang menayangkan respons dan apakah terjadi penggantian.

Untuk melihat setiap langkah kebijakan, panggilan target, dan transisi aturan kesalahan untuk satu permintaan, buat sesi debug Apigee terhadap revisi yang di-deploy:

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"