本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
本頁說明如何以 YAML 格式將 API Proxy 定義為 Apigee 功能範本，並使用 Google Cloud CLI 部署。您會先建構簡單的 Proxy，然後建構更完整的範例，做為 Gemini 模型的前端。
如需背景資訊，請參閱「使用 YAML 設定 Proxy」。如需完整結構定義，請參閱 API Proxy YAML 設定參考資料。
事前準備
- 在 Google Cloud 雲端專案中啟用 Vertex AI API，讓 Proxy 能與 Gemini 模型通訊。
gcloud services enable aiplatform.googleapis.com
- 安裝並初始化 Google Cloud CLI。
- 如要存取本教學課程中使用的指令，請安裝 gcloud Beta 版元件：
gcloud components install beta
- 擁有 Apigee 機構和至少一個環境。請記下機構和環境名稱；範例使用 ORG 和 ENV 做為預留位置。第 2 部分的 AI 閘道還需要中級或綜合環境 (而非基本環境)；請參閱「Apigee 環境類型」。
- 請確認您具備必要權限：
- 如要匯入 (建立) API Proxy，您必須具備「API 管理員」角色 (
roles/apigee.apiAdmin)，或具備可授予apigee.proxies.create的同等角色。 - 如要部署 API Proxy，您必須在目標環境中具備環境管理員 (
roles/apigee.environmentAdmin) 權限，並在專案層級具備 API 讀取者 (roles/apigee.apiReaderV2) 權限。 - 如要在第 2 部分的步驟 6 中建立 API 產品、開發人員和產生 API 金鑰的應用程式，您需要 API 管理員 (
roles/apigee.apiAdmin) 和開發人員管理員 (roles/apigee.developerAdmin) 角色。如需完整角色清單，請參閱 Apigee 角色。
- 如要匯入 (建立) API Proxy，您必須具備「API 管理員」角色 (
第 1 部分：建立簡單的 API Proxy
在本節中，您將建立 Proxy，將要求轉送至 Apigee 模擬目標服務，並強制執行速率限制。
步驟 1：建立範本
範本是您部署的檔案。這個檔案會定義 Proxy 的基本路徑、路由和後端目標，並列出要納入的功能。
為 Proxy 建立目錄，然後建立名為 hello-proxy.yaml 的檔案：
gateway: apigee schemaVersion: 1.0.0 name: hello-proxy type: template description: A simple proxy to the Apigee mock target, protected by a rate limit. features: - spike-arrest.yaml endpoints: - name: default basePath: /hello routes: - name: default target: default targets: - name: default url: https://mocktarget.apigee.net
這個範本定義了：
- 以基本路徑
/hello做為 端點。用戶端會在這個路徑呼叫 Proxy。 - 將要求傳送至名為
default的目標的路徑。 - 指向後端網址的目標。
- 您接下來要建立的功能
spike-arrest.yaml。
步驟 2：建立功能
功能是可重複使用的設定單元，內含政策。範本無法直接包含政策，因此速率限制政策會位於功能中。
在範本所在的目錄中，建立名為 spike-arrest.yaml 的檔案：
gateway: apigee schemaVersion: 1.0.0 name: spike-arrest displayName: Spike Arrest type: feature description: Protects the backend by smoothing traffic spikes. categories: - traffic parameters: - name: RATE displayName: RATE description: Maximum request rate, for example 30ps (per second) or 100pm (per minute). default: 30ps examples: - 30ps - 100pm defaultEndpoint: name: default flows: - name: PreFlow mode: Request steps: - name: SA-SpikeArrest policies: - name: SA-SpikeArrest type: SpikeArrest content: SpikeArrest: metadata: name: SA-SpikeArrest enabled: "true" continueOnError: "false" DisplayName: SA-SpikeArrest Rate: "{RATE}"
這項功能：
- 定義限制要求頻率的 SpikeArrest 政策。
- 使用
defaultEndpoint.flows將政策新增至要求 PreFlow，因此每項要求都會執行這項政策。 - 宣告參數
RATE，當編譯 Proxy 時，系統會將預設值 (30ps) 替換為{RATE}。
步驟 3：匯入 Proxy
匯入範本，建立 API Proxy 修訂版本。在含有檔案的目錄中執行這項指令：
gcloud beta apigee apis import hello-proxy \
--from-template=hello-proxy.yaml \
--organization=ORGCLI 會將範本及其功能編譯成 API Proxy 套件、上傳，並列印新的 Proxy 修訂版本。匯入作業會建立修訂版本，但不會部署。
步驟 4：部署 Proxy
將修訂版本部署至環境：
gcloud apigee apis deploy \
--api=hello-proxy \
--environment=ENV \
--organization=ORG根據預設，這項指令會部署最新修訂版本。如要部署特定修訂版本，請將其編號做為第一個引數傳遞，例如 gcloud apigee apis deploy 1 --api=hello-proxy --environment=ENV。如果已在相同基本路徑部署其他 Proxy，請新增 --override，以零停機時間取代該 Proxy。
步驟 5：呼叫 Proxy
如要透過網路呼叫已部署的 Proxy，您的環境必須附加至具有可路由主機名稱的環境群組。如果您剛建立機構，請先確認已完成設定，再呼叫 Proxy；詳情請參閱「關於環境和環境群組」。
找出包含環境的環境群組主機名稱：
- 在 Google Cloud 控制台中，依序前往「Apigee」「管理」「環境」。
- 選取「環境群組」分頁標籤。
- 找出包含環境的環境群組，然後從「主機名稱」欄複製值。
使用範本中的基本路徑，在該主機名稱呼叫 Proxy：
curl https://HOSTNAME/hello
將 HOSTNAME 替換為您複製的主機名稱。成功的回應來自模擬目標服務。
第 2 部分：為 Gemini 建立 AI 閘道
本節將建構更完整的 Proxy：AI 閘道，可將要求轉送至 Vertex AI 上的 Gemini 模型、強制執行速率限制，並要求提供 API 金鑰。這個範例會使用一個範本、三項功能和一個服務帳戶。
與第 1 部分中的簡單 Proxy 不同，這個 Proxy 會呼叫 Google Cloud 服務 (Vertex AI)。gemini-target 功能會使用 auth: GoogleAccessToken，因此 Apigee 會在每個 Vertex AI 要求中附加 Google OAuth 權杖。該權杖是為您建立的服務帳戶核發，然後在部署 Proxy 時提供，因此這個部分會新增建立該服務帳戶的步驟 (步驟 3)。
步驟 1：建立範本
建立名為 ai-gateway.yaml 的檔案：
gateway: apigee schemaVersion: 1.0.0 name: ai-gateway type: template description: AI gateway that fronts a Gemini model with throttling and API key enforcement. features: - spike-arrest.yaml - verify-api-key.yaml - gemini-target.yaml endpoints: - name: gemini basePath: /v1/gemini routes: - name: default target: gemini
步驟 2：建立功能
在同一個目錄中，建立三個功能檔案。
重複使用第 1 部分的 spike-arrest.yaml 功能。
建立 verify-api-key.yaml，在 x-api-key 標頭中要求 API 金鑰：
gateway: apigee schemaVersion: 1.0.0 name: verify-api-key displayName: Verify API Key type: feature description: Requires a valid API key in the x-api-key request header. categories: - security defaultEndpoint: name: default flows: - name: PreFlow mode: Request steps: - name: VA-VerifyAPIKey policies: - name: VA-VerifyAPIKey type: VerifyAPIKey content: VerifyAPIKey: metadata: name: VA-VerifyAPIKey enabled: "true" continueOnError: "false" DisplayName: VA-VerifyAPIKey APIKey: metadata: ref: request.header.x-api-key
建立 gemini-target.yaml，以透過 Google 存取權杖驗證，然後將要求傳送至 Gemini 模型：
gateway: apigee schemaVersion: 1.0.0 name: gemini-target displayName: Gemini Target type: feature description: Routes requests to a Gemini model on Vertex AI, authenticated with a Google access token. categories: - llm targets: - name: gemini url: https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent auth: GoogleAccessToken scopes: - https://www.googleapis.com/auth/cloud-platform
將 PROJECT_ID 替換為您的 Google Cloud 雲端專案 ID，並將 REGION 替換為您使用的 Vertex AI 區域 (例如 us-central1)。這項功能會使用 auth: GoogleAccessToken，讓 Apigee 將 Google 存取權杖附加至對 Vertex AI 的每個要求。
模型並非在所有地點都適用，網址則取決於您使用的地點。上述網址是區域形式，適用於從特定區域 (例如 gemini-2.5-flash 中的 us-central1) 放送的模型。其他模型只會透過全域端點提供，該端點使用不同的主機和 locations/global：
url: https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL:generateContent
如要查看模型支援的服務地區，請參閱「Vertex AI 生成式 AI 服務地區」。
步驟 3：為 Proxy 建立服務帳戶
由於 gemini-target 功能使用 auth: GoogleAccessToken，部署的 Proxy 會以服務帳戶身分呼叫 Vertex AI。建立該服務帳戶，授予存取 Vertex AI 的權限，並允許 Apigee 服務代理程式使用該帳戶。您會在步驟 5 中部署 Proxy 時提供這個服務帳戶。詳情請參閱「使用 Google 驗證」。
- 在與 Apigee 機構相同的 Google Cloud 專案中，建立使用者管理的服務帳戶。(系統不接受 Compute Engine 預設服務帳戶)。如要瞭解其他建立方式，請參閱「建立及管理服務帳戶」。
gcloud iam service-accounts create SA_NAME \ --project=PROJECT_ID \ --display-name="Apigee AI gateway"這會建立服務帳戶
SA_NAME@PROJECT_ID.iam.gserviceaccount.com。 - 授予服務帳戶其呼叫的後端存取權。如要以 Vertex AI 為目標，請授予 Vertex AI 使用者角色 (
roles/aiplatform.user)：gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/aiplatform.user"如果專案的 IAM 政策已包含條件角色繫結，請在這個指令中加入
--condition=None。 - 將服務帳戶的服務帳戶權杖建立者角色 (
roles/iam.serviceAccountTokenCreator) 授予 Apigee 服務代理，允許該代理為服務帳戶產生權杖：gcloud iam service-accounts add-iam-policy-binding \ SA_NAME@PROJECT_ID.iam.gserviceaccount.com \ --project=PROJECT_ID \ --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator"如要尋找 PROJECT_NUMBER，請執行
gcloud projects describe PROJECT_ID --format='value(projectNumber)'。
步驟 4：匯入 Proxy
匯入範本，建立 API Proxy 修訂版本：
gcloud beta apigee apis import ai-gateway \
--from-template=ai-gateway.yaml \
--organization=ORG請記下指令輸出中的修訂版本號碼，您會在步驟 5 中用到。如要只列印修訂版本號碼，請在匯入指令中加入 --format="value(revision)"。
步驟 5：使用服務帳戶部署 Proxy
部署 AI 閘道與第 1 部分中的簡單 Proxy 有兩項差異：
- 您必須提供在「步驟 3」中建立的服務帳戶。如果部署時沒有這類檔案，部署作業會失敗，並顯示
MISSING_SERVICE_ACCOUNT錯誤。 - 您必須部署至中等或全方位環境。 這個 Proxy 使用可擴充的政策，但「Base」環境不支援這項政策，因此部署至該環境會失敗，並顯示「Extensible proxy can not be deployed to a base environment」(可擴充的 Proxy 無法部署至 Base 環境) 錯誤訊息。請參閱「Apigee 環境類型」一文。
Apigee 使用者介面：部署 Proxy，並在系統提示輸入服務帳戶時，輸入 SA_NAME@PROJECT_ID.iam.gserviceaccount.com。
如需相關步驟，請參閱部署 API 代理伺服器。
Deployment API：呼叫 deployments API，並將服務帳戶做為 serviceAccount 查詢參數傳遞。將 REVISION 替換為步驟 4 中的修訂版本號碼：
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST \ "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments?serviceAccount=SA_NAME@PROJECT_ID.iam.gserviceaccount.com"
部署要求會立即傳回，部署作業則為非同步。輪詢修訂版本的部署狀態，直到狀態變成 READY 為止，系統會回報 PROGRESSING：
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments"
編譯 Proxy 時，spike-arrest 和 verify-api-key 功能會將政策新增至要求 PreFlow (先進行速率限制，再檢查 API 金鑰)，而 gemini-target 功能則會新增 Vertex AI 後端。部署完成後，Proxy 會以服務帳戶的身分向 Vertex AI 進行驗證。
步驟 6：取得 API 金鑰
verify-api-key 功能會拒絕任何未攜帶有效 API 金鑰的要求，因此您必須先取得金鑰，才能呼叫 Proxy。API 金鑰是與包含這個 Proxy 的 API 產品相關聯的開發人員應用程式憑證。完成下列工作 (詳情請參閱「發布總覽」)：
- 建立 API 產品，其中包含
ai-gatewayProxy 和您部署該 Proxy 的環境。 - 註冊應用程式開發人員。
- 註冊與該 API 產品相關聯的開發人員應用程式。
註冊應用程式後，系統就會產生金鑰。如要擷取這項資訊，請參閱「查看 API 金鑰和密鑰」。
步驟 7：呼叫 Proxy
如要找出環境群組的主機名稱，請按照第 1 部分的步驟 5操作，然後在基本路徑 /v1/gemini 呼叫 Proxy。在 x-api-key 標頭中傳遞 API 金鑰，並傳送 Gemini generateContent 要求主體：
curl -X POST https://HOSTNAME/v1/gemini \
-H "x-api-key: API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents":[{"role":"user","parts":[{"text":"Say hello in one sentence."}]}]}'將 HOSTNAME 替換為環境群組主機名稱，並將 API_KEY 替換為步驟 6 中的金鑰。成功的回應是模型的 JSON 輸出內容。如果省略金鑰，VerifyAPIKey 政策會傳回授權失敗訊息，確認 verify-api-key 功能已生效。如要瞭解傳遞金鑰的其他方式，請參閱「提交含有有效 API 金鑰的要求」。