設定 LLM 回覆和其他流量的串流

預先發布版 — 串流

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前功能是依「原樣」提供，支援服務可能受限。 詳情請參閱推出階段說明。

本文說明如何在 API Gateway 設定串流。

API Gateway 支援串流。串流功能可讓閘道提供長時間執行的連線，並以區塊形式傳輸要求和回應串流的資料。

串流的常見用途是提供大型語言模型 (LLM)。模型會逐一傳送答案的詞元，因此用戶端可以在模型生成文字時顯示文字。如需已完成樣本，瞭解如何從 vLLM 在 Cloud Run 提供的 Gemma 模型串流回覆，請參閱「串流 LLM 的回覆」。

支援的串流通訊協定

啟用後，API Gateway 支援下列串流方法：

• 遞增回應傳送：HTTP/2 DATA 框架或 HTTP/1.1 分塊傳輸編碼，視用戶端協商結果而定。
• 伺服器傳送事件 (SSE)：從伺服器到用戶端的單向串流。
• WebSockets：透過單一 TCP 連線的全雙工通訊管道。
• gRPC 雙向串流：使用 gRPC 進行全雙工串流。

必要條件

使用串流功能前，請確認後端服務支援必要通訊協定 (例如 HTTP/2 或 WebSocket)，且 API 設定正確。

設定後端通訊協定

如要支援串流流量，您必須根據串流類型設定後端的通訊協定：

• gRPC：您必須將後端設為使用 HTTP/2 (h2)。
• WebSockets：必須使用 http/1.1。WebSocket 需要 HTTP/1.1 Connection: Upgrade 握手。
• 伺服器傳送事件 (SSE) 和遞增回應傳遞：後端可以使用 HTTP/1.1 或 HTTP/2 (h2)。建議使用 HTTP/2 (h2) 提升效能。

在 OpenAPI 規格中，按照下列方式設定後端通訊協定：

範例 (OpenAPI 3.x)

在 x-google-api-management.backends 物件中，設定具名後端定義的 protocol 欄位。您也必須在根層級或作業層級使用 x-google-backend 參照這個後端。

x-google-api-management:
  backends:
    gemma:
      address: https://my-gemma-service.run.app
      protocol: h2 # Use 'http/1.1' for WebSockets
x-google-backend: gemma

範例 (OpenAPI 2.0)

在 x-google-backend 擴充功能中設定 protocol 欄位。

x-google-backend:
  address: https://my-gemma-service.run.app
  protocol: h2 # Use 'http/1.1' for WebSockets

設定串流期限

deadline 欄位會控管要求 (一元或串流) 的執行時間長度。

下表說明逾時設定如何套用至各類要求：

方法	閒置逾時 (訊息間隔時間上限)	要求逾時 (要求總時間長度上限)
非串流	不適用：閒置逾時僅適用於串流	預設為 15 秒；設定 deadline 即可變更，啟用串流的閘道最多可設為 3,600 秒
透過 HTTP 串流 (SSE、分塊傳輸)	不適用：實際上無限，只有要求逾時才會結束串流	預設為 15 秒；設定 deadline 即可變更，啟用串流的閘道最多可設為 3,600 秒
透過 gRPC 或 WebSocket 串流	預設為 300 秒；設定 deadline 即可變更，啟用串流的閘道最多可設為 3,600 秒。在 WebSockets 上，系統會忽略小於 300 秒的 deadline，並套用 300 秒的下限	如果閘道已啟用串流功能，則一律為 3,600 秒，無法設定

注意：除了 gRPC 串流和 WebSocket 以外，預設值只有 15 秒，對大多數串流來說太短。即使串流仍在傳送資料，一旦要求逾時，串流就會中斷，因此請在每個串流端點明確設定 deadline。

注意：後端會強制執行自己的要求逾時，無論傳輸多少流量，逾時都會結束連線。deadline 不會變更。Cloud Run 後端預設為 300 秒，因此會在開啟串流 5 分鐘後關閉。Gemma 指南會使用 --timeout 600 部署服務，因此串流會在 10 分鐘後結束。如要在下列兩個範例中使用 3,600 秒的 deadline，請使用 --timeout 3600 部署服務。詳情請參閱「設定服務的要求逾時時間」。

範例 (OpenAPI 3.x)

在具名後端定義中設定 deadline 欄位。

x-google-api-management:
  backends:
    gemma:
      address: https://my-gemma-service.run.app
      protocol: h2
      deadline: 3600.0
x-google-backend: gemma

範例 (OpenAPI 2.0)

在 x-google-backend 擴充功能中設定 deadline 欄位。

x-google-backend:
  address: https://my-gemma-service.run.app
  protocol: h2
  deadline: 3600.0

如要瞭解串流連線適用的其他限制，請參閱「限制」。

在閘道啟用串流

建立閘道時，您可指定是否要啟用串流功能。請注意以下行為：

• 未明確停用：沒有明確停用串流的旗標。如果省略 --enable-streaming 旗標，API Gateway 會在建立時，根據 API 設定和平台預設值解析模式：設定模型路由器的 API 設定一律會產生串流閘道。讀取閘道的僅供輸出 effectiveStreamingMode 欄位，查看建立閘道時使用的模式。
• 不可變動：串流模式在建立時即固定，日後無法修改。

如要指定閘道的串流，請使用 --enable-streaming 旗標和 gcloud api-gateway gateways create 指令：

gcloud api-gateway gateways create GATEWAY_ID \
    --api=API_ID \
    --api-config=CONFIG_ID \
    --location=GCP_REGION \
    --enable-streaming

如要進一步瞭解閘道部署選項，請參閱「將 API 部署至閘道」。

注意：模型路由器閘道會自動啟用串流。

閘道串流屬性

閘道資源中的下列欄位可控制串流行為：

欄位	屬性	值
streamingMode	字串 (不可變，選填)	STREAMING_MODE_UNSPECIFIED (預設：由服務選取模式) STREAMING_MODE_ENABLED
effectiveStreamingMode	字串 (OUTPUT_ONLY)	EFFECTIVE_STREAMING_MODE_DISABLED EFFECTIVE_STREAMING_MODE_ENABLED

使用 REST API 建立閘道時，您可以在要求主體中指定串流：

{
  "apiConfig": "projects/...",
  "streamingMode": "STREAMING_MODE_ENABLED"
}

確認已啟用串流功能

如要確認閘道是否正在串流，請使用 gcloud CLI 描述閘道：

gcloud api-gateway gateways describe GATEWAY_ID \
    --location=GCP_REGION

在輸出內容中尋找 effectiveStreamingMode 欄位。如果啟用串流，輸出內容會包含：

effectiveStreamingMode: EFFECTIVE_STREAMING_MODE_ENABLED

呼叫 Google Cloud API

串流閘道可以呼叫 Google Cloud API (例如 aiplatform.googleapis.com)，因此您可以透過閘道，從 Agent Platform 上的 Gemini 模型串流回覆。閘道會使用存取權杖 (而非 ID 權杖) 向這些後端進行驗證。詳情請參閱「保護後端服務」。

串流 LLM 的回覆

這個範例會在 vLLM 於 Cloud Run 提供的 Gemma 模型前方，設定串流閘道，並透過閘道串流對話完成。vLLM 提供與 OpenAI 相容的 API，可將回覆串流為伺服器傳送事件 (SSE)。

開始之前，請先完成設定開發環境，包括設定用於建立 API 設定的服務帳戶。閘道會使用該服務帳戶呼叫 Cloud Run 服務。

部署模型

按照「使用 vLLM 容器部署 Gemma 4 模型」一文的指示部署 Gemma 模型。請記下服務名稱、服務網址、區域，以及您部署的模型名稱，例如 google/gemma-4-E4B-it。

注意：指南中的部署指令會從 Hugging Face 下載模型權重，不需驗證。如果 Hugging Face 限制下載頻率，服務記錄會顯示 HTTP Error 429，容器無法通過啟動探測，且修訂版本不會進入就緒狀態。為避免這種情況，請在 HF_TOKEN 環境變數中設定 Hugging Face 存取權杖，如指南的部署設定表格所示。

授予閘道服務存取權

本指南會使用 --no-allow-unauthenticated 部署服務。閘道會使用服務帳戶的 ID 權杖呼叫服務，您在建立 API 設定時，會將該權杖傳遞為 --backend-auth-service-account。將服務的 Cloud Run 叫用者角色 (roles/run.invoker) 授予該服務帳戶：

gcloud run services add-iam-policy-binding SERVICE_NAME \
    --region=REGION \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL \
    --role=roles/run.invoker

更改下列內容：

• SERVICE_NAME：Cloud Run 服務名稱
• REGION：部署服務的區域
• SERVICE_ACCOUNT_EMAIL：閘道服務帳戶的電子郵件地址

建立 API 設定

將下列 OpenAPI 規格儲存為 gemma-api.yaml，並將 https://my-gemma-service.run.app 替換為您的服務網址：

openapi: 3.0.3
info:
  title: Gemma API
  version: 1.0.0
x-google-api-management:
  backends:
    gemma:
      address: https://my-gemma-service.run.app
      protocol: h2
      deadline: 570.0
x-google-backend: gemma
components:
  securitySchemes:
    google_id_token:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: ""
          scopes: {}
      x-google-auth:
        issuer: https://accounts.google.com
        jwksUri: https://www.googleapis.com/oauth2/v3/certs
        audiences:
          - gemma-api
security:
  - google_id_token: []
paths:
  /v1/chat/completions:
    post:
      operationId: createChatCompletion
      responses:
        '200':
          description: A chat completion, streamed as SSE when the request sets "stream" to true.

deadline 為 570 秒，比 Gemma 指南在服務上設定的 --timeout 600 短 30 秒。因此，如果串流執行時間過長，會由閘道的 deadline 結束，而非服務逾時。頂層 x-google-backend 預設為 pathTranslation: APPEND_PATH_TO_ADDRESS。閘道會將要求路徑附加至後端位址，因此傳送至 /v1/chat/completions 的要求會到達 vLLM 對話完成端點。

security 規定會使閘道拒絕任何不含 Google 簽署 ID 權杖 (目標對象為 gemma-api) 的要求。您可以選擇不同的目標對象字串，只要呼叫端在建立權杖時要求相同的字串即可。詳情請參閱「使用 Google ID 權杖驗證使用者」。

注意：ID 權杖會識別呼叫端，但不會限制 Google 身分。任何可為 gemma-api 目標對象建立權杖的身分，都能向模型傳送要求。您需要為要求啟動的 GPU 執行個體付費。如要同時要求 API 金鑰，請參閱「使用 API 金鑰」。如要限制每個用戶專案每分鐘可傳送的要求數量，請參閱「關於配額」。

建立 API 設定：

gcloud api-gateway api-configs create CONFIG_ID \
    --api=API_ID \
    --openapi-spec=gemma-api.yaml \
    --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

更改下列內容：

• CONFIG_ID：API 設定的 ID
• API_ID：API 的 ID。如果 API 不存在，指令會建立 API。

建立閘道

依據 API 設定建立串流閘道：

gcloud api-gateway gateways create GATEWAY_ID \
    --api=API_ID \
    --api-config=CONFIG_ID \
    --location=GCP_REGION \
    --enable-streaming

更改下列內容：

• GATEWAY_ID：閘道 ID
• GCP_REGION：閘道所在區域，可能與 REGION 不同。如要瞭解允許的值，請參閱「將 API 部署至閘道」。

閘道準備就緒後，請取得其主機名稱：

gcloud api-gateway gateways describe GATEWAY_ID \
    --location=GCP_REGION \
    --format="value(defaultHostname)"

取得呼叫端的 ID 權杖

使用者帳戶無法選擇 ID 權杖的目標對象，因此範例會為您模擬的服務帳戶建立權杖。針對呼叫端，請使用現有的服務帳戶或建立一個。詳情請參閱「建立服務帳戶」。將該服務帳戶的服務帳戶權杖建立者角色 (roles/iam.serviceAccountTokenCreator) 授予自己，gcloud CLI 才能模擬該帳戶：

gcloud iam service-accounts add-iam-policy-binding CALLER_SERVICE_ACCOUNT_EMAIL \
    --member=user:USER_EMAIL \
    --role=roles/iam.serviceAccountTokenCreator

更改下列內容：

• CALLER_SERVICE_ACCOUNT_EMAIL：呼叫閘道的服務帳戶電子郵件地址
• USER_EMAIL：您的電子郵件地址

傳送串流要求

傳送設定 "stream": true 的對話完成要求，並在 Authorization 標頭中加入呼叫端服務帳戶的 ID 權杖。-N 旗標會關閉 curl 中的輸出緩衝，因此每個事件都會在到達時輸出：

curl -N https://DEFAULT_HOSTNAME/v1/chat/completions \
    -H "Authorization: Bearer $(gcloud auth print-identity-token \
        --impersonate-service-account=CALLER_SERVICE_ACCOUNT_EMAIL \
        --audiences=gemma-api)" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "MODEL_NAME",
      "messages": [{"role": "user", "content": "Why is the sky blue?"}],
      "stream": true
    }'

更改下列內容：

• DEFAULT_HOSTNAME：閘道的主機名稱
• CALLER_SERVICE_ACCOUNT_EMAIL：上一個步驟中的服務帳戶
• MODEL_NAME：您部署的模型，例如 google/gemma-4-E4B-it

注意：Gemma 指南未設定執行個體數量下限，因此 Cloud Run 會在服務的執行個體閒置時移除這些執行個體。如果沒有執行中的執行個體，系統會先啟動新的執行個體並載入模型，再處理傳入的要求。這項作業可能需要幾分鐘才能完成，等待時間會計入閘道的deadline。如要讓執行個體保持運作，請參閱「設定服務的執行個體數量下限」。以此方式保持運作的執行個體會產生費用。

回應是 SSE 串流。第一個事件會帶有 assistant 角色，後續每個事件會帶有答案的下一個部分，而 data: [DONE] 之前的最後一個事件會設定 finish_reason。輸出結果會與下列內容相似：

data: {"id":"chatcmpl-7bcd57ad-1c3c-4779-91be-2973b875e517","object":"chat.completion.chunk","created":1790099706,"model":"google/gemma-4-E4B-it","choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}],"prompt_token_ids":null}

data: {"id":"chatcmpl-7bcd57ad-1c3c-4779-91be-2973b875e517","object":"chat.completion.chunk","created":1790099706,"model":"google/gemma-4-E4B-it","choices":[{"index":0,"delta":{"content":"The"},"logprobs":null,"finish_reason":null,"token_ids":null}]}

...

data: {"id":"chatcmpl-7bcd57ad-1c3c-4779-91be-2973b875e517","object":"chat.completion.chunk","created":1790099706,"model":"google/gemma-4-E4B-it","choices":[{"index":0,"delta":{"content":""},"logprobs":null,"finish_reason":"stop","stop_reason":106,"token_ids":null}]}

data: [DONE]

清除所用資源

為避免系統向您的 Google Cloud 帳戶收取這個範例所用資源的費用，請刪除閘道和 API 設定：

gcloud api-gateway gateways delete GATEWAY_ID \
    --location=GCP_REGION

gcloud api-gateway api-configs delete CONFIG_ID \
    --api=API_ID

如果您為這個範例建立了 API，請刪除該 API：

gcloud api-gateway apis delete API_ID

刪除 Cloud Run 服務：

gcloud run services delete SERVICE_NAME \
    --region=REGION

定價

在串流公開測試期間，客戶不需支付啟用串流的閘道網路輸出費用。不過，無論發布階段為何，Service Control 仍會依 API 級別計費。

限制

公開測試期間，API Gateway 的串流功能有下列限制：

• 不可變性：您無法更新現有閘道來啟用或停用串流。您必須建立新的閘道。請注意，啟用串流功能的閘道會收到不同的主機名稱形式，因此您必須更新用戶端或 DNS 記錄。如要我們更新閘道記錄，改用新格式，請與支援團隊聯絡。API Gateway 使用下列主機名稱模式：

  • 非串流：{gateway_id}-{base36_project_number}.{shard_hash}.gateway.dev，例如 test-gateway-4jcaz8x.uc.gateway.dev
  • 串流：{gateway_id}-{project_number}.{region}.gateway.dev，例如 test-gateway-9876654321.us-central1.gateway.dev
  • 串流 (舊版)：{service}-{tenant_project_number}.{region}.run.app，例如 test-gateway-834512064953.us-central1.run.app。在區域性 *.gateway.dev 主機名稱推出前建立的閘道，會永久保留這個主機名稱，不會遷移至新模式。

  新的串流閘道會收到「串流」模式。前兩個範例是同一專案中的同一個閘道：在「串流」模式中，專案編號會以十進位而非 36 進位顯示，因此第一個標籤的空間比非串流閘道少。第一個標籤是合併的 {gateway_id}-{project_number} 字串，必須符合 63 個字元的 DNS 標籤限制。閘道 ID 長度上限為 49 個字元，可確保專案編號長度不超過 13 位數；如果專案編號較長，閘道 ID 就必須較短。

• Terraform：不支援使用 Terraform 啟用串流功能 (預計在日後版本推出)。

• 負載平衡和自訂網域：effectiveStreamingMode 為 EFFECTIVE_STREAMING_MODE_ENABLED 的閘道與 API Gateway 或無伺服器 NEG 的 HTTP(S) 負載平衡不相容。您無法將這類閘道置於無伺服器 NEG 或外部應用程式負載平衡器後方。因此，在公開預先發布版期間，這些閘道不支援自訂網域 (依賴負載平衡)。

• 期限行為：在閘道啟用串流功能，不會改變 deadline 欄位在 SSE 或分塊傳輸路徑上的行為。期限仍是完整回應的實際時間限制，因此一旦超過期限，串流就會中斷，無論傳送的資料量有多少。預設值為 15 秒，上限為 3,600 秒。在 WebSocket 上，deadline 會限制訊息之間的間隔，連線會在 3,600 秒後終止。請參閱「設定串流期限」。

• Model Context Protocol (MCP)：使用 --enable-streaming 建立閘道，並不會建立 MCP 端點串流。無論閘道的串流模式為何，MCP 回應一律為單一 application/json 主體。詳情請參閱「MCP 限制」。