Streaming für LLM-Antworten und anderen Traffic konfigurieren

Vorschau – Streaming

Diese Funktion unterliegt den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

In diesem Dokument wird beschrieben, wie Sie Streaming in API Gateway konfigurieren.

API Gateway unterstützt Streaming. Durch Streaming können Gateways Verbindungen mit langer Laufzeit bedienen und Daten sowohl für das Anfrage- als auch für das Antwort-Streaming in Chunks übertragen.

Streaming wird häufig zum Bereitstellen eines Large Language Model (LLM) verwendet. Das Modell sendet seine Antwort Token für Token, sodass ein Client den Text anzeigen kann, während das Modell ihn noch generiert. Ein vollständiges Beispiel für das Streamen von Antworten von einem Gemma-Modell, das von vLLM in Cloud Run bereitgestellt wird, finden Sie unter Antworten von einem LLM streamen.

Unterstützte Streamingprotokolle

Wenn aktiviert, unterstützt API Gateway die folgenden Streamingmethoden:

• Inkrementelle Antwortübermittlung: HTTP/2-DATA-Frames oder HTTP/1.1-Chunked-Transfer-Encoding, je nachdem, was der Client aushandelt.
• Vom Server gesendete Ereignisse (SSE): Unidirektionales Streaming vom Server zum Client.
• WebSockets: Vollduplex-Kommunikationskanäle über eine einzelne TCP-Verbindung.
• Bidirektionales gRPC-Streaming: Vollduplex-Streaming mit gRPC.

Vorbereitung

Bevor Sie Streaming verwenden können, muss Ihr Backend-Dienst das erforderliche Protokoll (z. B. HTTP/2 oder WebSockets) unterstützen und Ihre API-Konfiguration muss richtig eingerichtet sein.

Backend-Protokoll konfigurieren

Damit Streaming-Traffic unterstützt wird, müssen Sie das Protokoll für Ihr Backend entsprechend dem Streamingtyp konfigurieren:

• gRPC: Sie müssen Ihr Back-End für die Verwendung von HTTP/2 (h2) konfigurieren.
• WebSockets: Sie müssen http/1.1 verwenden. Für WebSockets ist der HTTP/1.1-Handshake Connection: Upgrade erforderlich.
• Server-Sent Events (SSE) und inkrementelle Antwortübermittlung: Ihr Backend kann entweder HTTP/1.1 oder HTTP/2 (h2) verwenden. Wir empfehlen HTTP/2 (h2) für eine bessere Leistung.

Konfigurieren Sie das Backend-Protokoll in Ihrer OpenAPI-Spezifikation so:

Beispiel (OpenAPI 3.x)

Legen Sie das Feld protocol in der benannten Backend-Definition im Objekt x-google-api-management.backends fest. Sie müssen auch mit x-google-backend auf der Stamm- oder Vorgangsebene auf dieses Backend verweisen.

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

Beispiel (OpenAPI 2.0)

Legen Sie das Feld protocol in der Erweiterung x-google-backend fest.

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

Stream-Deadline festlegen

Das Feld deadline gibt an, wie lange eine Anfrage (unär oder Streaming) ausgeführt werden darf.

In der folgenden Tabelle sehen Sie, wie die Zeitüberschreitungen für die einzelnen Anfragetypen gelten:

Methode	Zeitlimit bei Inaktivität (maximaler Abstand zwischen Nachrichten)	Zeitüberschreitung bei Anfrage (maximale Gesamtdauer der Anfrage)
Nicht-Streaming	Nicht zutreffend: Das Zeitlimit für Inaktivität gilt nur für Streams.	Standardmäßig 15 Sekunden; lege deadline fest, um den Wert zu ändern (bis zu 3.600 Sekunden für Gateways mit Streamingfunktion)
Streaming over HTTP (SSE, Chunked Transfer)	Nicht zutreffend: effektiv unendlich; der Stream wird nur durch das Zeitlimit für Anfragen beendet.	Standardmäßig 15 Sekunden; lege deadline fest, um den Wert zu ändern (bis zu 3.600 Sekunden für Gateways mit Streamingfunktion)
Streaming über gRPC oder WebSockets	Standardmäßig 300 Sekunden. Legen Sie deadline fest, um den Wert zu ändern. Bei Gateways mit Streaming-Funktion sind bis zu 3.600 Sekunden möglich. Bei WebSockets wird ein deadline von weniger als 300 Sekunden ignoriert und es gilt ein Minimum von 300 Sekunden.	Immer 3.600 Sekunden für Streaming-fähige Gateways, nicht konfigurierbar

Achtung :Außerhalb von gRPC-Streaming und WebSockets beträgt der Standardwert nur 15 Sekunden, was für die meisten Streams zu kurz ist. Ein Stream wird beendet, sobald das Zeitlimit für die Anfrage abläuft, auch wenn noch Daten gesendet werden. Legen Sie deadline daher explizit für jeden Streaming-Endpunkt fest.

Hinweis :Ihr Backend erzwingt ein eigenes Zeitlimit für Anfragen. Dieses Zeitlimit beendet die Verbindung unabhängig davon, wie viel Traffic übertragen wird. deadline ändert daran nichts. Wenn ein Cloud Run-Backend mit dem Standardwert von 300 Sekunden verwendet wird, wird ein Stream fünf Minuten nach dem Öffnen geschlossen. Im Gemma-Leitfaden wird der Dienst mit --timeout 600 bereitgestellt, sodass die Streams nach 10 Minuten enden. Wenn Sie die 3.600 Sekunden lange deadline in den beiden folgenden Beispielen verwenden möchten, stellen Sie den Dienst mit --timeout 3600 bereit. Weitere Informationen finden Sie unter Anfrage-Zeitlimit für Dienste konfigurieren.

Beispiel (OpenAPI 3.x)

Legen Sie das Feld deadline in der benannten Backend-Definition fest.

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

Beispiel (OpenAPI 2.0)

Legen Sie das Feld deadline in der Erweiterung x-google-backend fest.

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

Informationen zu den anderen Limits für Streamingverbindungen finden Sie unter Einschränkungen.

Streaming auf einem Gateway aktivieren

Das Streaming wird beim Erstellen des Gateways angegeben. Beachten Sie Folgendes:

• Keine explizite Deaktivierung: Es gibt kein Flag, mit dem das Streaming explizit deaktiviert werden kann. Wenn Sie das Flag --enable-streaming weglassen, wird der Modus beim Erstellen von API Gateway aus der API-Konfiguration und dem Plattformstandard aufgelöst: Eine API-Konfiguration, die einen Modellrouter konfiguriert, führt immer zu einem Streaming-Gateway. Lesen Sie das effectiveStreamingMode-Feld des Gateways (nur Ausgabe), um den Modus zu sehen, mit dem es erstellt wurde.
• Unveränderlichkeit: Der Streamingmodus wird bei der Erstellung festgelegt und kann später nicht mehr geändert werden.

Verwenden Sie das Flag --enable-streaming mit dem Befehl gcloud api-gateway gateways create, um das Streaming auf einem Gateway anzugeben:

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

Weitere Informationen zu den Bereitstellungsoptionen für Gateways finden Sie unter API auf einem Gateway bereitstellen.

Hinweis :Bei Model Router-Gateways wird das Streaming automatisch aktiviert.

Gateway-Streaming-Eigenschaften

Die folgenden Felder in der Gateway-Ressource steuern das Streamingverhalten:

Feld	Attribute	Werte
streamingMode	String (UNVERÄNDERLICH, OPTIONAL)	STREAMING_MODE_UNSPECIFIED (Standard: Dienst wählt Modus aus) STREAMING_MODE_ENABLED
effectiveStreamingMode	String (OUTPUT_ONLY)	EFFECTIVE_STREAMING_MODE_DISABLED EFFECTIVE_STREAMING_MODE_ENABLED

Wenn Sie die REST API zum Erstellen eines Gateways verwenden, können Sie das Streaming im Anfragetext angeben:

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

Prüfen, ob Streaming aktiviert ist

So prüfen Sie, ob das Streaming auf Ihrem Gateway aktiv ist: Beschreiben Sie das Gateway mithilfe der gcloud CLI:

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

Suchen Sie in der Ausgabe nach dem Feld effectiveStreamingMode. Wenn das Streaming aktiviert ist, enthält die Ausgabe Folgendes:

effectiveStreamingMode: EFFECTIVE_STREAMING_MODE_ENABLED

Antworten von einem LLM streamen

In diesem Beispiel wird ein Streaming-Gateway vor ein Gemma-Modell gestellt, das von vLLM in Cloud Run bereitgestellt wird, und eine Chat-Vervollständigung wird über das Gateway gestreamt. vLLM stellt eine OpenAI-kompatible API bereit, die Antworten als Server-Sent Events (SSE) streamt.

Bevor Sie beginnen, führen Sie die Schritte unter Entwicklungsumgebung konfigurieren aus, einschließlich Dienstkonto zum Erstellen von API-Konfigurationen konfigurieren. Das Gateway verwendet dieses Dienstkonto, um den Cloud Run-Dienst aufzurufen.

Modell bereitstellen

Stellen Sie ein Gemma-Modell bereit, indem Sie der Anleitung unter Gemma 4-Modell mit einem vLLM-Container bereitstellen folgen. Notieren Sie sich den Dienstnamen, die Dienst-URL, die Region und den Namen des Modells, das Sie bereitstellen, z. B. google/gemma-4-E4B-it.

Hinweis :Mit dem Bereitstellungsbefehl im Leitfaden werden die Modellgewichte ohne Authentifizierung von Hugging Face heruntergeladen. Wenn Hugging Face den Download drosselt, wird in den Dienstlogs HTTP Error 429 angezeigt, der Container besteht die Startbereitschaftsprüfung nicht und die Revision wird nicht bereit. Um dies zu vermeiden, legen Sie ein Hugging Face-Zugriffstoken in der Umgebungsvariable HF_TOKEN fest, wie in der Tabelle mit den Bereitstellungseinstellungen im Leitfaden beschrieben.

Gateway Zugriff auf den Dienst gewähren

Im Leitfaden wird der Dienst mit --no-allow-unauthenticated bereitgestellt. Das Gateway ruft den Dienst mit einem ID-Token für sein Dienstkonto auf, das Sie beim Erstellen der API-Konfiguration als --backend-auth-service-account übergeben. Weisen Sie dem Dienstkonto die Rolle „Cloud Run Invoker“ (roles/run.invoker) für den Dienst zu:

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

Ersetzen Sie Folgendes:

• SERVICE_NAME: der Name des Cloud Run-Dienstes
• REGION: die Region, in der Sie den Dienst bereitgestellt haben
• SERVICE_ACCOUNT_EMAIL: die E-Mail-Adresse des Dienstkontos des Gateways

API-Konfiguration erstellen

Speichern Sie die folgende OpenAPI-Spezifikation als gemma-api.yaml und ersetzen Sie https://my-gemma-service.run.app durch Ihre Dienst-URL:

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.

Die deadline von 570 Sekunden ist 30 Sekunden kürzer als die --timeout 600, die im Gemma-Leitfaden für den Dienst festgelegt ist. Daher wird ein Stream, der zu lange läuft, durch das deadline des Gateways und nicht durch das Dienst-Timeout beendet. Die Standardeinstellung für x-google-backend auf oberster Ebene ist pathTranslation: APPEND_PATH_TO_ADDRESS. Das Gateway hängt den Anfragepfad an die Backend-Adresse an, sodass eine Anfrage an /v1/chat/completions den vLLM-Chat-Vervollständigungs-Endpunkt erreicht.

Durch die security-Anforderung lehnt das Gateway alle Anfragen ab, die kein von Google signiertes ID-Token mit der Zielgruppe gemma-api enthalten. Sie können einen anderen Zielgruppenstring auswählen, solange Anrufer denselben anfordern, wenn sie ein Token erstellen. Weitere Informationen finden Sie unter Nutzer mit Google-ID-Tokens authentifizieren.

Achtung :Ein ID-Token identifiziert den Aufrufer, schränkt aber nicht ein, welche Google-Identität das ist. Jede Identität, die ein Token für die Zielgruppe gemma-api erstellen kann, kann Anfragen an Ihr Modell senden. Sie zahlen für die GPU-Instanzen, die durch ihre Anfragen gestartet werden. Wenn Sie auch einen API-Schlüssel benötigen möchten, lesen Sie den Abschnitt API-Schlüssel verwenden. Informationen dazu, wie Sie die Anzahl der Anfragen pro Minute für jedes Nutzerprojekt begrenzen können, finden Sie unter Kontingente.

Erstellen Sie die API-Konfiguration:

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

Ersetzen Sie Folgendes:

• CONFIG_ID: Eine ID für die API-Konfiguration
• API_ID: Die ID der API. Wenn die API nicht vorhanden ist, wird sie durch den Befehl erstellt.

Gateway erstellen

Streaming-Gateway aus der API-Konfiguration erstellen:

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

Ersetzen Sie Folgendes:

• GATEWAY_ID: eine ID für das Gateway
• GCP_REGION: die Region für das Gateway, die sich von REGION unterscheiden kann. Informationen zu zulässigen Werten finden Sie unter API auf einem Gateway bereitstellen.

Wenn das Gateway bereit ist, rufen Sie seinen Hostnamen ab:

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

ID-Token für den Anrufer abrufen

Ein Nutzerkonto kann die Zielgruppe seines ID-Tokens nicht auswählen. Im Beispiel wird das Token daher für ein Dienstkonto erstellt, dessen Identität Sie übernehmen. Verwenden Sie für den Aufrufer ein vorhandenes Dienstkonto oder erstellen Sie ein Konto. Weitere Informationen finden Sie unter Dienstkonten erstellen. Weisen Sie sich selbst die Rolle „Ersteller von Dienstkonto-Tokens“ (roles/iam.serviceAccountTokenCreator) für dieses Dienstkonto zu, die die gcloud CLI für die Identitätsübernahme benötigt:

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

Ersetzen Sie Folgendes:

• CALLER_SERVICE_ACCOUNT_EMAIL: die E-Mail-Adresse des Dienstkontos, das das Gateway aufruft.
• USER_EMAIL: Ihre E-Mail-Adresse.

Streaming-Anfrage senden

Senden Sie eine Chat-Vervollständigungsanfrage, in der "stream": true festgelegt ist. Fügen Sie ein ID-Token für das Dienstkonto des Aufrufers im Authorization-Header ein. Das Flag -N deaktiviert die Ausgabepufferung in curl, sodass jedes Ereignis bei Eintreffen ausgegeben wird:

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

Ersetzen Sie Folgendes:

• DEFAULT_HOSTNAME: der Hostname des Gateways
• CALLER_SERVICE_ACCOUNT_EMAIL: das Dienstkonto aus dem vorherigen Schritt
• MODEL_NAME: Das Modell, das Sie bereitgestellt haben, z. B. google/gemma-4-E4B-it

Hinweis :In der Gemma-Anleitung wird keine Mindestanzahl von Instanzen festgelegt. Daher entfernt Cloud Run die Instanzen des Dienstes, wenn sie inaktiv sind. Eine Anfrage, die eingeht, wenn keine Instanz ausgeführt wird, wartet, bis eine neue Instanz gestartet und das Modell geladen wird. Dieser Vorgang kann einige Minuten dauern. Die Wartezeit wird auf die deadline des Gateways angerechnet. Informationen dazu, wie Sie eine Instanz am Laufen halten, finden Sie unter Mindestanzahl von Instanzen für Dienste festlegen. Für Instanzen, die auf diese Weise weiterhin ausgeführt werden, fallen Kosten an.

Die Antwort ist ein SSE-Stream. Das erste Ereignis hat die Rolle assistant, jedes spätere Ereignis enthält den nächsten Teil der Antwort und das letzte Ereignis vor data: [DONE] legt finish_reason fest. Die Ausgabe sieht etwa so aus:

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]

Bereinigen

Damit Ihrem Google Cloud Konto die in diesem Beispiel verwendeten Ressourcen nicht in Rechnung gestellt werden, löschen Sie das Gateway und die API-Konfiguration:

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

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

Wenn Sie die API für dieses Beispiel erstellt haben, löschen Sie sie:

gcloud api-gateway apis delete API_ID

Löschen Sie den Cloud Run-Dienst:

gcloud run services delete SERVICE_NAME \
    --region=REGION

Preise

Während der öffentlichen Vorschau für Streaming wird Kunden kein Netzwerk-Egress auf Streaming-fähigen Gateways in Rechnung gestellt. Die Abrechnung für Service Control erfolgt jedoch unabhängig von der Releasephase weiterhin auf API-Ebene.

Beschränkungen

Die folgenden Einschränkungen gelten für das Streaming in API Gateway während der öffentlichen Vorschau:

• Unveränderlichkeit: Sie können ein vorhandenes Gateway nicht aktualisieren, um das Streaming zu aktivieren oder zu deaktivieren. Sie müssen ein neues Gateway erstellen. Ein Streaming-fähiges Gateway erhält einen anderen Hostnamen shape. Daher müssen Sie Ihre Clients oder DNS-Einträge aktualisieren. Wenn Sie möchten, dass wir Ihren Gateway-Eintrag auf das neue Format aktualisieren, wenden Sie sich an den Support. API Gateway verwendet die folgenden Hostname-Muster:

  • Nicht-Streaming: {gateway_id}-{base36_project_number}.{shard_hash}.gateway.dev, z. B. test-gateway-4jcaz8x.uc.gateway.dev
  • Streaming: {gateway_id}-{project_number}.{region}.gateway.dev, z. B. test-gateway-9876654321.us-central1.gateway.dev
  • Streaming (alt): {service}-{tenant_project_number}.{region}.run.app, z. B. test-gateway-834512064953.us-central1.run.app. Gateways, die vor der Einführung regionaler *.gateway.dev-Hostnamen erstellt wurden, behalten diesen Hostnamen dauerhaft bei und werden nicht zum neuen Muster migriert.

  Ein neues Streaming-fähiges Gateway erhält das Streaming-Muster. Die ersten beiden Beispiele beziehen sich auf dasselbe Gateway im selben Projekt. Im Streaming-Muster wird die Projektnummer dezimal statt in Base36 dargestellt. Das erste Label hat also weniger Platz als bei einem Nicht-Streaming-Gateway. Das erste Label ist der kombinierte {gateway_id}-{project_number}-String, der das DNS-Label-Limit von 63 Zeichen nicht überschreiten darf. Durch die Begrenzung der Gateway-ID auf 49 Zeichen wird sichergestellt, dass die Gesamtlänge für Projektnummern mit bis zu 13 Ziffern nicht überschritten wird. Bei einer längeren Projektnummer muss die Gateway-ID kürzer sein.

• Terraform: Das Aktivieren von Streaming mit Terraform wird nicht unterstützt (für eine zukünftige Version geplant).

• Load-Balancing und benutzerdefinierte Domains: Gateways mit einem effectiveStreamingMode von EFFECTIVE_STREAMING_MODE_ENABLED sind nicht mit HTTP(S)-Load-Balancing für API Gateway oder serverlosen NEGs kompatibel. Sie können ein solches Gateway nicht hinter einer serverlosen NEG oder einem externen Application Load Balancer platzieren. Daher werden benutzerdefinierte Domains, die auf Load Balancing basieren, für diese Gateways während der öffentlichen Vorschau nicht unterstützt.

• Verhalten bei Fristüberschreitung: Wenn Sie das Streaming auf einem Gateway aktivieren, ändert sich das Verhalten des Felds deadline auf einem SSE- oder Chunked-Transfer-Pfad nicht. Die Frist bleibt eine Wanduhr-Grenze für die vollständige Antwort. Ein Stream wird also abgeschnitten, sobald die Frist abläuft, unabhängig davon, wie viele Daten gesendet werden. Der Standardwert ist 15 Sekunden und der Höchstwert 3.600 Sekunden. Bei einem WebSocket wird stattdessen die Lücke zwischen Nachrichten durch deadline begrenzt und die Verbindung nach 3.600 Sekunden beendet. Weitere Informationen finden Sie unter Stream-Deadline festlegen.

• Model Context Protocol (MCP): Wenn Sie das Gateway mit --enable-streaming erstellen, wird kein MCP-Endpunktstream erstellt. MCP-Antworten bleiben ein einzelner application/json-Body, unabhängig vom Streamingmodus des Gateways. Weitere Informationen finden Sie unter Einschränkungen für MCP.