214 214
215### `upstreams`215### `upstreams`
216 216
217`upstreams` ist eine geordnete Liste. Das Gateway leitet Inference an den ersten Upstream weiter, der das angeforderte Modell auflöst.217`upstreams` ist eine geordnete Liste. Das Gateway leitet Inferenz an den ersten Upstream weiter, der das angeforderte Modell auflöst, und überspringt jeden Upstream, dessen [`groups`-Liste](#send-each-team-to-its-own-upstream) den Entwickler nicht einschließt.
218 218
219Bei `5xx`, `429`, `401`, `403`, `404` oder Timeout führt das Gateway ein Failover zum nächsten Upstream durch; bei anderen `4xx` nicht, da diese Fehler der Anfrage statt dem Upstream zuzuordnen sind. Ein `401` oder `403` bedeutet, dass der Upstream die Anmeldedaten, die das Gateway verwendet hat, abgelehnt oder ihnen den Zugriff verweigert hat, zum Beispiel auf das angeforderte Modell. Ein `404` bedeutet, dass dieser Upstream das angeforderte Modell nicht bereitstellt, daher kann ein späterer Upstream in der Liste es immer noch tun.219Bei `5xx`, `429`, `401`, `403`, `404` oder Timeout führt das Gateway ein Failover zum nächsten Upstream durch; bei anderen `4xx` nicht, da diese Fehler der Anfrage statt dem Upstream zuzuordnen sind. Ein `401` oder `403` bedeutet, dass der Upstream die Anmeldedaten, die das Gateway verwendet hat, abgelehnt oder ihnen den Zugriff verweigert hat, zum Beispiel auf das angeforderte Modell. Ein `404` bedeutet, dass dieser Upstream das angeforderte Modell nicht bereitstellt, daher kann ein späterer Upstream in der Liste es immer noch tun.
220 220
231Das Gateway gibt die Fehlerantwort eines Upstreams oder sein eigenes `502` zurück, je nachdem, wie die Upstreams antworteten:231Das Gateway gibt die Fehlerantwort eines Upstreams oder sein eigenes `502` zurück, je nachdem, wie die Upstreams antworteten:
232 232
233* **Ein Upstream gab einen Status zurück, bei dem das Gateway kein [Failover](#multiple-upstreams) durchführt**: die Antwort dieses Upstreams. Das Gateway versucht keine weiteren Upstreams.233* **Ein Upstream gab einen Status zurück, bei dem das Gateway kein [Failover](#multiple-upstreams) durchführt**: die Antwort dieses Upstreams. Das Gateway versucht keine weiteren Upstreams.
234* **Jeder Upstream, den das Gateway versuchte, schlug auf eine Weise fehl, bei der es ein [Failover](#multiple-upstreams) durchführt**: das letzte `429`. Wenn keiner ein `429` zurückgab, bevorzugt das Gateway in der Reihenfolge das letzte `401` oder `403`, das letzte `404` und das letzte `501`. Wenn keiner davon zurückgegeben wurde, das eigene `502` des Gateways, `all upstreams failed (N attempted)`, wobei N jeden Eintrag in [`upstreams`](#upstreams) zählt, einschließlich Einträgen, die das Gateway übersprungen hat, weil sie das angeforderte Modell nicht bereitstellen.234* **Jeder Upstream, den das Gateway versucht hat, ist auf eine Weise fehlgeschlagen, bei der es ein [Failover durchführt](#multiple-upstreams)**: der letzte `429`. Wenn keiner einen `429` zurückgegeben hat, bevorzugt das Gateway in dieser Reihenfolge den letzten `401` oder `403`, den letzten `404` und den letzten `501`. Wenn keiner davon zurückgegeben wurde, das eigene `502` des Gateways, `all upstreams failed (N attempted)`. N zählt Ihre [`upstreams`](#upstreams)-Einträge einschließlich übersprungener, abzüglich derer, deren [`groups`](#send-each-team-to-its-own-upstream)-Liste den Entwickler nicht einschließt.
235 235
236Wenn das Gateway eine Upstream-Antwort zurückgibt, behält es den Statuscode des Upstreams. Ob es die Nachricht des Upstreams behält, hängt vom Anbieter ab. Der Fehler-Body eines Anthropic-API-Upstreams erreicht den Entwickler unverändert.236Wenn das Gateway eine Upstream-Antwort zurückgibt, behält es den Statuscode des Upstreams. Ob es die Nachricht des Upstreams behält, hängt vom Anbieter ab. Der Fehler-Body eines Anthropic-API-Upstreams erreicht den Entwickler unverändert.
237 237
361 # keep the quotes: a bare 1 fails at boot361 # keep the quotes: a bare 1 fails at boot
362```362```
363 363
364> [!WARNING]
365>
366> Das Gateway unterstützt keine Guardrail-Eingabe-Tags. Es fügt Prompts keine Guard-Content-Tags hinzu, daher wird ein Guardrail-Filter, den Amazon Bedrock nur auf getaggte Eingaben anwendet, bei Traffic über das Gateway nicht ausgeführt. Welche Filter von Eingabe-Tags abhängen, erfahren Sie unter [Eingabe-Tags](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html) in der Amazon Bedrock-Dokumentation.
367
368Gewähren Sie außerdem `bedrock:ApplyGuardrail` auf die Guardrail dem Principal, der die Anfragen dieses Upstreams signiert: dem AWS-Principal des Gateways oder, mit [`assume_role`](#bedrock-in-another-aws-account), der in `role_arn` benannten Rolle.364Gewähren Sie außerdem `bedrock:ApplyGuardrail` auf die Guardrail dem Principal, der die Anfragen dieses Upstreams signiert: dem AWS-Principal des Gateways oder, mit [`assume_role`](#bedrock-in-another-aws-account), der in `role_arn` benannten Rolle.
369 365
370Setzen Sie `guardrail` auf jedem `bedrock`-Upstream oder auf keinem. Bei einer Mischung weigert sich das Gateway zu starten, da [Failover](#multiple-upstreams) eine Anfrage sonst an einen Bedrock-Upstream ohne Guardrail senden könnte.366Setzen Sie `guardrail` auf jedem `bedrock`-Upstream oder auf keinem. Bei einer Mischung weigert sich das Gateway zu starten, da [Failover](#multiple-upstreams) eine Anfrage sonst an einen Bedrock-Upstream ohne Guardrail senden könnte.
373 369
374Wenn eine `/v1/messages`-Anfrage, deren Body ein `amazon-bedrock-*`-Feld wie `amazon-bedrock-guardrailConfig` enthält, einen Bedrock-Upstream mit gesetztem `guardrail` erreicht, antwortet das Gateway mit 400, statt sie weiterzuleiten.370Wenn eine `/v1/messages`-Anfrage, deren Body ein `amazon-bedrock-*`-Feld wie `amazon-bedrock-guardrailConfig` enthält, einen Bedrock-Upstream mit gesetztem `guardrail` erreicht, antwortet das Gateway mit 400, statt sie weiterzuleiten.
375 371
372> [!WARNING]
373>
374> Standardmäßig fügt das Gateway Prompts keine Eingabe-Tags hinzu, sodass ein Guardrail-Filter, den Amazon Bedrock nur auf getaggte Eingaben anwendet, bei Datenverkehr über das Gateway nicht ausgeführt wird. Um die Tags hinzuzufügen, setzen Sie [`input_tagging`](#add-guardrail-input-tags). Welche Filter von Eingabe-Tags abhängen, erfahren Sie unter [Eingabe-Tags](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html) in der Amazon-Bedrock-Dokumentation.
375
376##### Guardrail-Eingabe-Tags hinzufügen
377
378Damit das Gateway die Eingabe-Tags hinzufügt, die der [Filter für Prompt-Angriffe](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-prompt-attack.html) eines Amazon-Bedrock-Guardrails benötigt, setzen Sie `input_tagging` im `guardrail`-Block und starten Sie das Gateway neu. Setzen Sie denselben Wert auf jedem `bedrock`-Upstream, sonst startet das Gateway nicht. Erfordert Claude Code v2.1.316 oder höher auf dem Gateway-Server. Ein Gateway mit einer Version ohne diesen Schlüssel beendet sich beim Start mit `Unrecognized key(s) in object: 'input_tagging'`.
379
380> [!WARNING]
381>
382> Laut der [Dokumentation von Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html) wertet jeder Filter im Guardrail nicht getaggte Inhalte nicht mehr aus, sobald eine Anfrage Eingabe-Tags enthält. Testen Sie `input_tagging` auf einem Test-Gateway, bevor Sie es auf einem Gateway setzen, das Entwickler nutzen.
383
384`input_tagging` nimmt einen dieser Werte an:
385
386| `input_tagging` | Wo das Gateway Text taggt | Nachdem der Guardrail einen Prompt blockiert hat |
387| :- | :- | :- |
388| `last_message` | Die `user`-Nachrichten seit Claudes letzter Antwort | In Claude Code kann der nächste Prompt durchgehen, und Claude erhält den blockierten Prompt dann als Teil der Konversation |
389| `user_messages` | `user`-Nachrichten | Spätere Prompts in der Sitzung können ebenfalls blockiert werden, bis der Entwickler den blockierten Prompt entfernt |
390| `all_messages` | `user`- und `assistant`-Nachrichten | Wie bei `user_messages` |
391| `all_messages_and_system` | Der System-Prompt und jede Nachricht, einschließlich [Systemnachrichten mitten in der Konversation](https://code.claude.com/docs/de/llm-gateway-protocol.md#feature-pass-through) | Wie bei `user_messages` |
392
393Wenn bei `last_message` die `user`-Nachrichten seit Claudes letzter Antwort keinen taggbaren Text enthalten, taggt das Gateway stattdessen die Systemnachrichten mitten in der Konversation seit dieser Antwort. Ein Tool-Aufruf zählt als Antwort.
394
395Die Empfehlung von Amazon Bedrock für den Filter für Prompt-Angriffe lautet, [Benutzereingaben so zu taggen, dass der System-Prompt ausgeschlossen ist](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-prompt-attack.html). Wenn Sie `all_messages_and_system` setzen, kann ein Filter, der den eigenen System-Prompt von Claude Code kennzeichnet, Anfragen blockieren.
396
397Das folgende Beispiel taggt Text in jeder `user`-Nachricht:
398
399```yaml theme={null}
400upstreams:
401 - provider: bedrock
402 region: us-east-1
403 auth: {}
404 guardrail:
405 id: gr-abc123
406 version: "1"
407 input_tagging: user_messages
408```
409
410`user`-Nachrichten können auch Text enthalten, den Claude Code hinzufügt, etwa [System-Erinnerungen](https://code.claude.com/docs/de/glossary.md#system-reminder); prüfen Sie daher auf dem Test-Gateway, dass gewöhnliche Anfragen nicht blockiert werden.
411
412In Tests von Anthropic behielt eine getaggte Sitzung ihre [Prompt-Cache](https://code.claude.com/docs/de/prompt-caching.md)-Lesezugriffe von einem Prompt zum nächsten bei, und die Tags fügten keine Eingabe-Token hinzu.
413
414##### Was Eingabe-Tags nicht abdecken
415
416Kein `input_tagging`-Wert hält einen Entwickler auf, der absichtlich Text dort platziert, wo kein Tag gesetzt wird. Verlassen Sie sich nicht darauf, dass der Guardrail diese Teile einer Anfrage auswertet:
417
418* **Inhalte, die das Gateway nicht taggt**: unter anderem Nachrichten, die Ihr `input_tagging`-Wert auslässt, Tool-Definitionen, Eingaben von Tool-Aufrufen, Bilder und PDFs. Sofern Sie nicht `all_messages_and_system` setzen, ist auch der System-Prompt nicht getaggt.
419* **Tool-Ergebnisse**: Diese enthalten, was Claudes Tools zurückgeben, etwa Dateiinhalte und Webseiten. In Tests von Anthropic hat ein Wortfilter sie nicht ausgewertet, weder mit noch ohne Tags.
420
421Wenn Ihr AWS-Konto oder Ihre Organisation einen Guardrail erzwingt, erfahren Sie in der [Dokumentation von Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-enforcements.html), wie dieser Guardrail Eingabe-Tags behandelt.
422
423##### Protokollieren, welcher Guardrail-Filter ausgelöst hat
424
425Um herauszufinden, welcher Amazon-Bedrock-Guardrail-Filter die Anfrage eines Entwicklers blockiert hat, setzen Sie `guardrail_trace: true` für den Bedrock-Upstream, starten Sie das Gateway neu und lassen Sie den Entwickler die Anfrage erneut senden. Suchen Sie dann das `guardrail.trace`-Ereignis der Anfrage im [Audit-Log](https://code.claude.com/docs/de/claude-apps-gateway-deploy.md#logs). Erfordert Claude Code v2.1.314 oder höher auf dem Gateway-Server. Ein früheres Gateway startet nicht, wenn es `guardrail_trace` findet.
426
427```yaml theme={null}
428upstreams:
429 - provider: bedrock
430 region: us-east-1
431 auth: {}
432 guardrail:
433 id: gr-abc123
434 version: "1"
435 guardrail_trace: true # default false; beside guardrail, not inside it
436```
437
438Das Gateway schreibt ein `guardrail.trace`-Ereignis ohne den gefundenen Text, wenn ein Filter ausgelöst hat oder die Aktion der Guardrail `INTERVENED` ist. Finden Sie die Ereignisse des Entwicklers über `email` oder `sub`. Eine gestreamte Anfrage kann mehrere Ereignisse erzeugen, und eines davon kann eine leere `filters`-Liste haben; lesen Sie daher jedes Ereignis mit derselben `request_id`:
439
440| Feld | Inhalt |
441| - | - |
442| `request_id` | Die ID der Anfrage |
443| `sub`, `email` | Benutzer-ID und E-Mail des Entwicklers |
444| `upstream` | Der Upstream, von dem die Antwort kam |
445| `action` | Die Aktion der Guardrail, etwa `INTERVENED` |
446| `filters` | Die Filter, die ausgelöst haben. Die Liste ist leer, wenn AWS keine Filterdetails sendet |
447| `filters[].side` | `input` oder `output` |
448| `filters[].guardrail` | Die ID der Guardrail |
449| `filters[].policy` | Die Bedrock-Richtlinie und -Liste, etwa `contentPolicy.filters` oder `sensitiveInformationPolicy.piiEntities` |
450| Weitere `filters[]`-Felder | Ein Eintrag kann auch Felder wie `action`, `name`, `type`, `confidence`, `filterStrength`, `score` und `threshold` enthalten |
451
452Das Ereignis lässt den Text weg, den ein Filter gefunden hat, einschließlich des `match`-Felds des Bedrock-Trace. Entwickler erhalten die Trace-Daten von Bedrock nicht, da das Gateway sie aus jeder Antwort entfernt, ob gestreamt oder nicht.
453
454Wenn ein Client ein `amazon-bedrock-*`-Feld im Body einer `/v1/messages`-Anfrage sendet, antwortet das Gateway bei einem Upstream, der `guardrail_trace` setzt, mit 400.
455
376##### Bedrock in einem anderen AWS-Konto456##### Bedrock in einem anderen AWS-Konto
377 457
378Setzen Sie `assume_role` auf einem Bedrock-Upstream, und das Gateway verwendet seine eigene AWS-Identität nur, um `sts:AssumeRole` für eine von Ihnen benannte Rolle aufzurufen, die sich in einem anderen AWS-Konto als das Gateway befinden kann. Jede Bedrock-Anfrage von diesem Upstream wird mit den einstündigen Anmeldedaten signiert, die STS zurückgibt, sodass kein langlebiger Zugriffsschlüssel Kontogrenzen überschreitet.458Setzen Sie `assume_role` auf einem Bedrock-Upstream, und das Gateway verwendet seine eigene AWS-Identität nur, um `sts:AssumeRole` für eine von Ihnen benannte Rolle aufzurufen, die sich in einem anderen AWS-Konto als das Gateway befinden kann. Jede Bedrock-Anfrage von diesem Upstream wird mit den einstündigen Anmeldedaten signiert, die STS zurückgibt, sodass kein langlebiger Zugriffsschlüssel Kontogrenzen überschreitet.
415* Wenn STS ablehnt oder nicht erreichbar ist, sendet das Gateway die Anfrage nicht mit den eigenen Anmeldedaten des Upstreams. Es protokolliert den STS-Fehler zusammen mit dem, was zu prüfen ist, und versucht dann den nächsten aufgelisteten Upstream. [Upstream-Fehlermeldungen](#upstream-error-messages) beschreibt, was der Client erhält, wenn kein Upstream erfolgreich ist. Ein späterer Upstream ohne `assume_role` würde die Anfrage mit seinen eigenen Anmeldedaten bedienen, listen Sie einen solchen also nur auf, wenn Sie das wollen.495* Wenn STS ablehnt oder nicht erreichbar ist, sendet das Gateway die Anfrage nicht mit den eigenen Anmeldedaten des Upstreams. Es protokolliert den STS-Fehler zusammen mit dem, was zu prüfen ist, und versucht dann den nächsten aufgelisteten Upstream. [Upstream-Fehlermeldungen](#upstream-error-messages) beschreibt, was der Client erhält, wenn kein Upstream erfolgreich ist. Ein späterer Upstream ohne `assume_role` würde die Anfrage mit seinen eigenen Anmeldedaten bedienen, listen Sie einen solchen also nur auf, wenn Sie das wollen.
416* Das Gateway ruft den regionalen STS-Endpunkt `sts.<region>.amazonaws.com` auf, den sein Netzwerk erreichen muss. Für den FIPS-Endpunkt setzen Sie `AWS_USE_FIPS_ENDPOINT=true` in der Umgebung des Gateways statt `use_fips_endpoint` in einer AWS-Konfigurationsdatei.496* Das Gateway ruft den regionalen STS-Endpunkt `sts.<region>.amazonaws.com` auf, den sein Netzwerk erreichen muss. Für den FIPS-Endpunkt setzen Sie `AWS_USE_FIPS_ENDPOINT=true` in der Umgebung des Gateways statt `use_fips_endpoint` in einer AWS-Konfigurationsdatei.
417* `assume_role` gilt nur für `provider: bedrock` und benötigt SigV4-Quell-Anmeldedaten: Das Gateway weigert sich zu starten, wenn es neben `aws_bearer_token` gesetzt ist.497* `assume_role` gilt nur für `provider: bedrock` und benötigt SigV4-Quell-Anmeldedaten: Das Gateway weigert sich zu starten, wenn es neben `aws_bearer_token` gesetzt ist.
418* Jeder Entwickler, den das Gateway zulässt, kann diesen Upstream verwenden; [`managed`](#managed) regelt, welche Entwickler welche Modelle verwenden dürfen. Damit ein über die Rolle bereitgestelltes Modell nicht auch aus einem anderen Konto bereitgestellt wird, geben Sie ihm eine benutzerdefinierte ID, deren `upstream_model`-Zuordnung nur den Namen dieses Upstreams enthält. Für eine solche ID überspringt das Gateway jeden anderen Upstream, sodass weder die Anfrage noch die Token-Zählung für eine abgebrochene Anfrage per Failover an ein anderes Konto gehen kann. Eine Anfrage für einen integrierten Modellnamen kann diesen Upstream weiterhin [erreichen](#multiple-upstreams), und das Gateway signiert sie mit derselben Rolle. Listen Sie diesen Upstream zuletzt auf, sofern sein Konto diese Modelle nicht ebenfalls bedienen soll.498* Ohne eine [`groups`-Liste](#send-each-team-to-its-own-upstream) kann jeder Entwickler, den das Gateway zulässt, diesen Upstream verwenden. Um einzuschränken, welche Modelle ein Entwickler verwenden kann, setzen Sie `availableModels` in einer [`managed`](#managed)-Richtlinie.
499* Damit ein über die Rolle bereitgestelltes Modell nicht auch von einem anderen Konto bereitgestellt wird, geben Sie ihm eine benutzerdefinierte ID, deren `upstream_model`-Zuordnung nur den Namen dieses Upstreams enthält. Bei einer solchen ID überspringt das Gateway jeden anderen Upstream, sodass weder die Anfrage noch die Token-Zählung für eine abgebrochene Anfrage per Failover an ein anderes Konto gehen kann.
500* Eine Anfrage für einen integrierten Modellnamen kann diesen Upstream dennoch [erreichen](#multiple-upstreams), und das Gateway signiert sie mit derselben Rolle. Führen Sie diesen Upstream zuletzt auf, sofern sein Konto diese Modelle nicht ebenfalls bereitstellen soll.
419 501
420Dieses Beispiel gibt einem Modell eine benutzerdefinierte ID, die nur der isolierte Upstream bereitstellt:502Dieses Beispiel gibt einem Modell eine benutzerdefinierte ID, die nur der isolierte Upstream bereitstellt:
421 503
627 709
628`429` ist Kapazität pro Upstream, daher führt die Erschöpfung von Provisioned Throughput (PT) zu einem Failover auf On-Demand. Wenn Sie [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run) auf einem Upstream setzen, ist ein `429` auf eine Anfrage, die die E-Mail des Entwicklers trug, stattdessen eine Ablehnung pro Benutzer und führt nicht zu einem Failover.710`429` ist Kapazität pro Upstream, daher führt die Erschöpfung von Provisioned Throughput (PT) zu einem Failover auf On-Demand. Wenn Sie [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run) auf einem Upstream setzen, ist ein `429` auf eine Anfrage, die die E-Mail des Entwicklers trug, stattdessen eine Ablehnung pro Benutzer und führt nicht zu einem Failover.
629 711
630Jede Anfrage beginnt beim ersten Upstream. Eine Anfrage erreicht einen späteren Upstream nur, wenn jeder Upstream davor fehlgeschlagen ist oder das angeforderte Modell nicht bereitstellt.712Eine Anfrage geht nur in diesen Fällen über einen Upstream hinaus:
713
714* Der Upstream ist fehlgeschlagen
715* Der Upstream stellt das angeforderte Modell nicht bereit
716* Der Upstream hat eine [`groups`-Liste](#send-each-team-to-its-own-upstream), in der der Entwickler nicht enthalten ist
631 717
632Das Gateway führt keine Aufzeichnung über fehlgeschlagene Upstreams, daher versucht, während ein Upstream ausgefallen ist, jede Anfrage, die ihn erreicht, ihn weiterhin und wartet auf sein Fehlschlagen, bevor sie weitergeht.718Das Gateway führt keine Aufzeichnung über fehlgeschlagene Upstreams, daher versucht, während ein Upstream ausgefallen ist, jede Anfrage, die ihn erreicht, ihn weiterhin und wartet auf sein Fehlschlagen, bevor sie weitergeht.
633 719
680| - | - |766| - | - |
681| Verschiedene Regionen | Ein Amazon Bedrock-Upstream pro Region, jeder mit seiner eigenen `region:`. Mit [`auto_include_builtin_models: true`](#models) leiten die Cross-Region-Inference-Profile automatisch weiter; für an eine Region gebundene Bereitstellungen verwenden Sie einen `models:`-Block. |767| Verschiedene Regionen | Ein Amazon Bedrock-Upstream pro Region, jeder mit seiner eigenen `region:`. Mit [`auto_include_builtin_models: true`](#models) leiten die Cross-Region-Inference-Profile automatisch weiter; für an eine Region gebundene Bereitstellungen verwenden Sie einen `models:`-Block. |
682| Verschiedene Konten | Ein Amazon Bedrock-Upstream pro Konto. Die Standard-Kette (`auth: {}`) verwendet die Identität des Pods; für ein zweites Konto fügen Sie [`assume_role`](#bedrock-in-another-aws-account) hinzu, um es mit kurzlebigen Anmeldedaten zu erreichen, oder setzen explizite Anmeldedaten oder ein Bearer-Token in `auth:`. |768| Verschiedene Konten | Ein Amazon Bedrock-Upstream pro Konto. Die Standard-Kette (`auth: {}`) verwendet die Identität des Pods; für ein zweites Konto fügen Sie [`assume_role`](#bedrock-in-another-aws-account) hinzu, um es mit kurzlebigen Anmeldedaten zu erreichen, oder setzen explizite Anmeldedaten oder ein Bearer-Token in `auth:`. |
769| Verschiedene Teams | Geben Sie dem Upstream jedes Teams eine `groups`-Liste, sodass nur Entwickler in diesen IdP-Gruppen ihn erreichen. Siehe [Jedes Team an seinen eigenen Upstream senden](#send-each-team-to-its-own-upstream). |
683| Provisioned Throughput | Ordnen Sie das Modell in `models:` für den Namen dieses Upstreams der Provisioned-Throughput-ARN zu. Andere Upstreams behalten die On-Demand-ID, daher wird die PT-Kapazität vor dem Failover ausgeschöpft. |770| Provisioned Throughput | Ordnen Sie das Modell in `models:` für den Namen dieses Upstreams der Provisioned-Throughput-ARN zu. Andere Upstreams behalten die On-Demand-ID, daher wird die PT-Kapazität vor dem Failover ausgeschöpft. |
684| VPC / FIPS-Endpunkte | Setzen Sie `base_url:` auf dem Upstream auf Ihre VPC-Endpunkt- oder FIPS-Endpunkt-URL |771| VPC / FIPS-Endpunkte | Setzen Sie `base_url:` auf dem Upstream auf Ihre VPC-Endpunkt- oder FIPS-Endpunkt-URL |
685| Modellbezogenes Routing | Nur eine benutzerdefinierte Modell-`id`, also eine, die kein integriertes Claude-Modell ist, überspringt die Upstreams, die in ihrer `upstream_model:`-Zuordnung fehlen. Ein `mantle`-Upstream wird nur für die Modelle versucht, die in seinem [`models`-Feld](#amazon-bedrock-mantle-endpoint) aufgeführt sind. Auf jedem anderen Upstream versucht das Gateway integrierte Modelle der Reihe nach und verwendet die Standard-ID des Anbieters, wo die Zuordnung keinen Eintrag hat, daher ändert die Zuordnung für integrierte Modelle, welche ID ein Upstream erhält, statt ob er versucht wird; ein Upstream, der die ID ablehnt, folgt den gleichen [Failover-Regeln](#upstreams) wie jeder andere Upstream-Fehler. |772| Modellbezogenes Routing | Eine benutzerdefinierte Modell-`id`, also eine, die kein integriertes Claude-Modell ist, überspringt die Upstreams, die in ihrer `upstream_model:`-Zuordnung fehlen. Ein Upstream mit einer `models`-Liste, die ein [`mantle`-Upstream](#amazon-bedrock-mantle-endpoint) haben muss, wird nur für diese Modelle probiert. |
773| Routing integrierter Modelle | Bei einem Upstream ohne `models`- oder `groups`-Liste probiert das Gateway integrierte Modelle der Reihe nach und verwendet die Standard-ID des Anbieters, wenn die `upstream_model:`-Zuordnung keinen Eintrag enthält. Für ein integriertes Modell, für das der Anbieter eine Standard-ID hat, ändert die Zuordnung, welche ID ein Upstream erhält, nicht aber, ob er probiert wird. Ein Upstream, der die ID ablehnt, folgt denselben [Failover-Regeln](#upstreams) wie bei jedem anderen Upstream-Fehler. |
686 774
687Ein Failover zwischen Cloud-Anbietern oder zur direkten Anthropic API ändert, welche Vereinbarung, Geografie und anderen Bedingungen für die Anfrage gelten.775Ein Failover zwischen Cloud-Anbietern oder zur direkten Anthropic API ändert, welche Vereinbarung, Geografie und anderen Bedingungen für die Anfrage gelten.
688 776
689Die CLI wendet dasselbe Feature-Gating auf Gateways an, unabhängig davon, welcher Upstream eine bestimmte Anfrage bedient, daher sendet ein Failover standardmäßig kein Body-Feld, das ein Upstream ablehnen würde. Wenn Sie die [einstündige Cache-TTL](#one-hour-prompt-cache) in einer Richtlinie setzen, geht sie an jeden Upstream in der Liste, setzen Sie sie also nur, wenn alle sie akzeptieren.777Die CLI wendet dasselbe Feature-Gating auf Gateways an, unabhängig davon, welcher Upstream eine bestimmte Anfrage bedient, daher sendet ein Failover standardmäßig kein Body-Feld, das ein Upstream ablehnen würde. Wenn Sie die [einstündige Cache-TTL](#one-hour-prompt-cache) in einer Richtlinie setzen, geht sie an jeden Upstream in der Liste, setzen Sie sie also nur, wenn alle sie akzeptieren.
690 778
779#### Jedes Team an seinen eigenen Upstream senden
780
781Um die Anfragen jedes Teams an ein eigenes AWS-Konto oder Google Cloud-Projekt zu senden, führen Sie einen Upstream pro Team auf und geben Sie jedem eine `groups`-Liste. Nur Entwickler in einer aufgeführten IdP-Gruppe erreichen diesen Upstream, sowohl beim ersten Versuch als auch beim [Failover](#multiple-upstreams). Jeder Anbieter unterstützt `groups`. Erfordert Claude Code v2.1.314 oder höher auf dem Gateway-Server.
782
783Dieses Beispiel gibt den Gruppen `payments-eng` und `search-eng` jeweils ein eigenes AWS-Konto und fügt einen Upstream ohne `groups`-Liste hinzu, den jeder Entwickler verwenden kann:
784
785```yaml theme={null}
786upstreams:
787 - name: bedrock-payments
788 provider: bedrock
789 region: us-east-1
790 auth: {}
791 assume_role:
792 role_arn: arn:aws:iam::111111111111:role/claude-gateway-bedrock
793 groups: [payments-eng]
794 - name: bedrock-search
795 provider: bedrock
796 region: us-east-1
797 auth: {}
798 assume_role:
799 role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
800 groups: [search-eng]
801 - name: bedrock-shared # no groups: open to everyone, so listed last
802 provider: bedrock
803 region: us-east-1
804 auth: {}
805```
806
807Mit der Beispielkonfiguration beginnen die Anfragen jedes Entwicklers beim ersten Upstream in seiner Zeile und gehen beim Failover zum nächsten über:
808
809| Gruppen des Entwicklers | Upstreams, in Reihenfolge |
810| - | - |
811| `payments-eng` | `bedrock-payments`, dann `bedrock-shared` |
812| `search-eng` | `bedrock-search`, dann `bedrock-shared` |
813| `payments-eng` und `search-eng` | `bedrock-payments`, dann `bedrock-search`, dann `bedrock-shared` |
814| Keine von beiden | `bedrock-shared` |
815
816Wenn der Upstream eines Teams das angeforderte Modell mit einem `403` verweigert, probiert das Gateway den nächsten Upstream in der Zeile dieses Teams, der das Modell bereitstellt. Um das Team auf einem Upstream zu halten, geben Sie jedem Upstream eine `groups`-Liste und stellen Sie sicher, dass kein anderer Upstream eine Gruppe aufführt, in der die Entwickler des Teams Mitglied sind. Dieses Team hat dann kein Failover, und Anfragen von Entwicklern, die in keiner aufgeführten Gruppe sind, [schlagen mit einem `400` fehl](#what-happens-when-a-developer-is-in-no-listed-group).
817
818Damit jeder Entwickler den vorgesehenen Upstream erreicht, schreiben Sie Einträge, die exakt übereinstimmen, und setzen Sie offene Upstreams an das Ende:
819
820* **Einträge**: Schreiben Sie jede Gruppe genau so, wie Ihr IdP sie im [Groups-Claim](#oidc) sendet, den auch [`match.groups`](#managed) liest. Das Gateway startet nicht, wenn es eine leere Liste oder einen leeren Eintrag findet. Es prüft einen Eintrag nicht gegen Ihren IdP, sodass ein Eintrag, der auf niemanden zutrifft, keine Warnung auslöst.
821* **Reihenfolge**: Setzen Sie einen Upstream ohne `groups`-Liste an das Ende. Er bedient alle; steht er weiter vorn, übernimmt er die Anfragen eines Teams vor dessen eigenem Upstream.
822
823> [!WARNING]
824>
825> Ein Gateway vor v2.1.314 startet nicht, wenn es `groups` findet. Aktualisieren Sie daher jedes Replikat, bevor Sie es hinzufügen.
826>
827> Bevor Sie ein Rollback durchführen, entfernen Sie jeden Upstream mit einer `groups`-Liste sowie jeden `upstream_model`-Schlüssel und jede Preisüberschreibung, die ihn benennt, und behalten Sie mindestens einen Upstream bei. Wird nur der Schlüssel `groups` entfernt, ist dieser Upstream für jeden Entwickler offen. Ein Schlüssel oder eine Überschreibung, die noch einen entfernten Upstream benennt, verhindert den Start des Gateways mit `references unknown upstream`.
828
829##### Was passiert, wenn ein Entwickler in keiner aufgeführten Gruppe ist
830
831Wenn jeder Upstream eine `groups`-Liste hat, sieht ein Entwickler, der in keiner dieser Gruppen ist, diesen Fehler, und das Gateway kontaktiert keinen Anbieter:
832
833```text theme={null}
834API Error: 400 you aren't in a group that can use this gateway. Ask your administrator to add you to one
835```
836
837Fügen Sie den Entwickler in Ihrem IdP zu einer aufgeführten Gruppe hinzu, oder fügen Sie einen Upstream ohne `groups`-Liste hinzu.
838
839Das Gateway liest die Gruppen eines Entwicklers bei jeder Token-Aktualisierung erneut. Wenn Ihr IdP bei einer Aktualisierung keine Gruppen mitsendet, hat der Entwickler danach keine:
840
841* **[`oidc.allowed_groups`](#oidc) ist gesetzt**: Das Gateway lehnt die Aktualisierung ab, und die Sitzung endet
842* **Andernfalls, wenn ein Upstream keine `groups`-Liste hat**: Die Anfragen des Entwicklers gehen an diesen Upstream
843* **Andernfalls, wenn jeder Upstream eine `groups`-Liste hat**: Die Anfragen des Entwicklers schlagen mit diesem Fehler fehl
844
845Wenn der Userinfo-Endpunkt Ihres IdP den Groups-Claim zurückgibt und `oidc.google_groups` nicht gesetzt ist, setzen Sie [`oidc.userinfo_fallback`](#oidc) auf `true`, um die Gruppen von dort zu ergänzen.
846
691## Optionale Abschnitte847## Optionale Abschnitte
692 848
693### `admin`849### `admin`
782 938
783#### Sätze an angemeldete Clients senden939#### Sätze an angemeldete Clients senden
784 940
785Mit v2.1.268 oder später auf dem Gateway-Server fügt das Gateway die Sätze aus `pricing` auch in die [`managed`](#managed)-Richtlinien ein, die es bedient, als die [`modelPricing`](https://code.claude.com/docs/de/settings-reference#modelpricing)-verwaltete Einstellung. Entwickler, die von einer Richtlinie abgeglichen werden, sehen dann die `pricing`-Sätze für den ersten Upstream, der jede Modell-ID in `/usage`, der Statuszeile und OpenTelemetry bedient. Ein Entwickler, der keine Richtlinie abgleicht, erhält keine verwalteten Einstellungen, sodass seine Zahlen beim Listenpreis bleiben. Clients wenden die Einstellung in Claude Code v2.1.242 oder später an.941Mit v2.1.268 oder höher auf dem Gateway-Server fügt das Gateway die Preise aus `pricing` außerdem in die [`managed`](#managed)-Richtlinien ein, die es ausliefert, und zwar als verwaltete Einstellung [`modelPricing`](https://code.claude.com/docs/de/settings-reference#modelpricing).
942
943Entwickler, auf die eine Richtlinie zutrifft, sehen die `pricing`-Preise dann in `/usage`, in der Statuszeile und in OpenTelemetry. Ein Entwickler, auf den keine Richtlinie zutrifft, erhält keine verwalteten Einstellungen, sodass seine Zahlen beim Listenpreis bleiben. Clients wenden die Einstellung ab Claude Code v2.1.242 an.
786 944
787* Was das Gateway hinzufügt: Sofern der `cli`-Block einer Richtlinie nicht bereits `modelPricing` setzt, fügt das Gateway den `multiplier` und für jede Modell-ID, die ein Client anfordern kann, die Überschreibungszeile des ersten Upstream hinzu, der diese ID bedient. Ein Satz, den nur ein Failover-Upstream berechnet, bleibt beim Gateway.945* Was das Gateway hinzufügt: Sofern der `cli`-Block einer Richtlinie nicht bereits `modelPricing` setzt, fügt das Gateway den `multiplier` und für jede Modell-ID, die ein Client anfordern kann, die Überschreibungszeile des ersten Upstream hinzu, der diese ID bedient. Ein Satz, den nur ein Failover-Upstream berechnet, bleibt beim Gateway.
946* Upstreams mit einer [`groups`-Liste](#send-each-team-to-its-own-upstream): Ist ein solcher Upstream der erste, der eine Modell-ID bedient, fügt das Gateway für diese ID keine Zeile hinzu. Entwickler sehen dann den eigenen Preis von Claude Code für diese ID, also den Standardpreis des Modells, wenn Claude Code die ID erkennt, multipliziert mit dem `multiplier`.
788* Eine Richtlinie ausschließen: Setzen Sie `modelPricing` auf `{}` im `cli`-Block dieser Richtlinie, und ihre Entwickler bleiben beim Listenpreis.947* Eine Richtlinie ausschließen: Setzen Sie `modelPricing` auf `{}` im `cli`-Block dieser Richtlinie, und ihre Entwickler bleiben beim Listenpreis.
789* Sätze einer Richtlinie behalten: Eine Richtlinie, deren `cli`-Block `modelPricing` mit ihrem eigenen `multiplier` oder `overrides` setzt, behält dieses `modelPricing` ganz, und das Gateway fügt keine eigenen Sätze hinzu.948* Sätze einer Richtlinie behalten: Eine Richtlinie, deren `cli`-Block `modelPricing` mit ihrem eigenen `multiplier` oder `overrides` setzt, behält dieses `modelPricing` ganz, und das Gateway fügt keine eigenen Sätze hinzu.
790 949
808 967
809### `managed`968### `managed`
810 969
811Der `managed`-Block definiert rollenbasierte Zugriffsrichtlinien, die nach IdP-Gruppen oder E-Mail-Domäne geschlüsselt sind. Richtlinien werden in Reihenfolge ausgewertet; die erste Übereinstimmung wird ausgewählt und dann mit der `match: {}`-Catch-All-Basis zusammengeführt. Sie werden pro Benutzer unter `GET /managed/settings` mit ETag/304-Caching bedient.970Der Block `managed` definiert rollenbasierte Zugriffsrichtlinien, die an IdP-Gruppen oder E-Mail-Domains geknüpft sind. Richtlinien werden der Reihe nach ausgewertet; standardmäßig wird die erste Übereinstimmung ausgewählt und dann mit der Basis des Catch-all `match: {}` zusammengeführt. Ein Benutzer, auf den zwei Rollenrichtlinien zutreffen, erhält nur die erste, sodass die deny-Regeln der zweiten Richtlinie nicht gelten, es sei denn, Sie [wenden jede zutreffende Richtlinie an](#apply-every-matching-policy). Richtlinien werden pro Benutzer unter `GET /managed/settings` mit ETag/304-Caching ausgeliefert.
812 971
813```yaml theme={null}972```yaml theme={null}
814managed:973managed:
849 1008
850Ein authentifizierter Benutzer, der keine Richtlinie abgleicht, erhält die Standardwerte des Gateways, was bedeutet, jedes Modell im Katalog und keine verwalteten Einstellungen. Fügen Sie eine `match: {}`-Catch-All zuletzt hinzu, wenn Sie eine garantierte Standardrichtlinie möchten.1009Ein authentifizierter Benutzer, der keine Richtlinie abgleicht, erhält die Standardwerte des Gateways, was bedeutet, jedes Modell im Katalog und keine verwalteten Einstellungen. Fügen Sie eine `match: {}`-Catch-All zuletzt hinzu, wenn Sie eine garantierte Standardrichtlinie möchten.
851 1010
1011Legen Sie organisationsweite deny-Regeln in die Richtlinie `match: {}`, da die Regeln einer Gruppenrichtlinie nur gelten, solange das Token des Benutzers diese Gruppe enthält.
1012
852> [!NOTE]1013> [!NOTE]
853>1014>
854> Das Gateway führt kein eigenes Benutzerverzeichnis. Es autorisiert jede Anfrage anhand des IdP-Tokens des Benutzers, liest die Gruppenmitgliedschaft aus dem `groups`-Anspruch des Tokens und wertet Richtlinien dagegen aus. Es gibt kein Verzeichnis zum Aufzählen und keine Konten zum Vorab-Erstellen, und daher keinen SCIM-Endpunkt, da es nichts gibt, in das SCIM synchronisieren könnte.1015> Das Gateway führt kein eigenes Benutzerverzeichnis. Es autorisiert jede Anfrage anhand des IdP-Tokens des Benutzers, liest die Gruppenmitgliedschaft aus dem `groups`-Anspruch des Tokens und wertet Richtlinien dagegen aus. Es gibt kein Verzeichnis zum Aufzählen und keine Konten zum Vorab-Erstellen, und daher keinen SCIM-Endpunkt, da es nichts gibt, in das SCIM synchronisieren könnte.
862>1023>
863> Claude Desktop folgt [seinem eigenen Zeitplan](#when-a-policy-change-reaches-claude-desktop).1024> Claude Desktop folgt [seinem eigenen Zeitplan](#when-a-policy-change-reaches-claude-desktop).
864 1025
1026#### Jede zutreffende Richtlinie anwenden
1027
1028Ein Benutzer, auf den mehrere Rollenrichtlinien zutreffen, erhält nur die erste, es sei denn, Sie setzen `policy_mode: layered` neben `policies`. Mit `layered` gilt jede Richtlinie, die auf den Benutzer zutrifft, bis hinunter zur ersten Richtlinie `match: {}`.
1029
1030`policy_mode` erfordert Claude Code v2.1.316 oder höher auf dem Gateway-Server. Ein Gateway mit einer Version, der dieser Schlüssel fehlt, verweigert den Start, wenn es ihn findet. Aktualisieren Sie jedes Replikat, bevor Sie den Schlüssel hinzufügen, und entfernen Sie den Schlüssel, bevor Sie auf eine frühere Version zurückgehen. In diesem Beispiel verliert eine Gruppe `WebFetch` und eine andere erhält Opus:
1031
1032```yaml theme={null}
1033managed:
1034 policy_mode: layered
1035 policies:
1036 - match: { groups: [no-web] }
1037 cli:
1038 permissions: { deny: ["WebFetch"] }
1039 - match: { groups: [opus-users] }
1040 cli:
1041 availableModels: [opus, sonnet]
1042 - match: {}
1043 cli:
1044 availableModels: [sonnet]
1045 enforceAvailableModels: true
1046```
1047
1048Die Tabelle zeigt, was ein Benutzer in `no-web` und `opus-users` unter dem Standard `first_match` und unter `layered` erhält.
1049
1050| Einstellung | `first_match` | `layered` |
1051| - | - | - |
1052| `availableModels` | `sonnet` | `opus`, `sonnet` |
1053| `enforceAvailableModels` | `true` | `true` |
1054| `permissions.deny` | `WebFetch` | `WebFetch` |
1055
1056Das Gateway führt jede zutreffende Richtlinie mit den darunter aufgeführten zusammen, nach denselben [Regeln zum Zusammenführen](#managed) wie bei der Basisebene:
1057
1058* **Allowlists, Einzelwerte und Blöcke wie `sandbox`**: Jeder Wert stammt vollständig aus der zuerst aufgeführten zutreffenden Richtlinie, die ihn setzt, sodass sich die `availableModels`-Listen zweier Gruppen nicht addieren.
1059* **Denylists und Hook-Arrays**: Diese addieren sich über jede zutreffende Richtlinie, sodass ein Benutzer in zwei Gruppen die deny-Regeln beider Gruppen erhält.
1060* **`env`, `modelOverrides` und `skillOverrides`**: Einträge werden nach Namen zusammengeführt, und die zuerst aufgeführte zutreffende Richtlinie, die einen Namen setzt, liefert dessen Wert.
1061* **`desktop`-Schlüssel**: Diese werden nach [den Regeln für den Basisblock `desktop`](#how-a-role-policy-inherits-the-base-desktop-block) zusammengeführt.
1062
1063> [!WARNING]
1064>
1065> Richtlinien können sich zu lockereren Regeln addieren, als jede einzelne für sich ergibt. Beispiel: Die Richtlinie `match: {}` setzt `sandbox.enabled: true`, die Richtlinie einer Gruppe setzt `permissions.allow: ["Bash"]` und die einer anderen Gruppe `sandbox.enabled: false`. Ein Benutzer in beiden Gruppen erhält `Bash` erlaubt bei ausgeschalteter Sandbox. Führen Sie in diesem Fall die Richtlinie, die `Bash` erlaubt, zuerst auf und kopieren Sie den gesamten `sandbox`-Block der Richtlinie `match: {}` hinein.
1066
1067Mit `layered` verweigert das Gateway bei einigen Einstellungen den Start, darunter diese:
1068
1069* **Ein `!`-Muster**: eine [`!`-Negation](https://code.claude.com/docs/de/permissions#special-characters-and-negation) in einer `Read`- oder `Edit`-Regel in der Liste `permissions.deny` oder `permissions.ask` einer beliebigen Richtlinie, die der Richtlinie `match: {}` eingeschlossen
1070* **Eine Einschränkung von Hooks außerhalb des Catch-all**: `disableAllHooks`, `allowedHttpHookUrls` oder `httpHookAllowedEnvVars` in einer anderen Richtlinie als `match: {}`
1071
865#### Sitzungen mit einem Modell starten, das die Richtlinie zulässt1072#### Sitzungen mit einem Modell starten, das die Richtlinie zulässt
866 1073
867Wenn `availableModels` das Standardmodell von Claude Code nicht enthält, erhalten Sitzungen `400`-Antworten, bis der Entwickler ein aufgelistetes Modell auswählt, zum Beispiel mit `/model`. In Gateway-Sitzungen ist der Standard das Opus-Modell, zu dem der Alias `opus` aufgelöst wird, und `availableModels` allein ändert daran nichts.1074Wenn `availableModels` das Standardmodell von Claude Code nicht enthält, erhalten Sitzungen `400`-Antworten, bis der Entwickler ein aufgelistetes Modell auswählt, zum Beispiel mit `/model`. In Gateway-Sitzungen ist der Standard das Opus-Modell, zu dem der Alias `opus` aufgelöst wird, und `availableModels` allein ändert daran nichts.
