View a markdown version of this page

Alvos do provedor de inferência - Amazon Bedrock AgentCore
Configurações de destinoCriação de um alvo de inferência do provedorInvocando um alvo de inferência do provedorModel-based roteamentoStreamingAutorização de saída

Alvos do provedor de inferência

Os alvos do provedor de inferência oferecem controle explícito sobre o endpoint, os mapeamentos do modelo e as operações de um provedor de modelos. Use uma configuração de provedor quando precisar personalizar quais modelos estão disponíveis, definir limites de token por modelo, configurar a reescrita de caminhos ou conectar-se a um provedor que não tenha um conector integrado.

Configurações de destino

A configuração de destino para um alvo do provedor de inferência usa a seguinte estrutura:

{
    "inference": {
        "provider": {
            "endpoint": "https://api.openai.com",
            "operations": [
                {
                    "path": "/v1/chat/completions",
                    "models": [
                        {"model": "gpt-5.5"},
                        {"model": "gpt-5.4"},
                        {"model": "gpt-5.4-mini"}
                    ]
                },
                {
                    "path": "/v1/responses",
                    "models": [
                        {"model": "gpt-5.5"},
                        {"model": "gpt-5.4"}
                    ]
                }
            ]
        }
    }
}

  • endpoint (obrigatório) — O URL HTTPS do provedor do modelo.

  • ModelMapping (opcional) — Configuração de tradução do ID do modelo.

    • providerPrefix (opcional) — Configura como os clientes podem omitir o prefixo do provedor dos IDs do modelo. Se omitido, nenhuma tradução de prefixo é aplicada e os clientes devem usar os IDs completos do modelo do provedor.

      • strip (opcional) — Quandotrue, os clientes podem usar IDs de modelo sem o prefixo do provedor (por exemplo, claude-opus-4-7 em vez deanthropic.claude-opus-4-7). O padrão é false.

      • separador (opcional) — O caractere separador entre o prefixo do provedor e o nome do modelo (por exemplo,). .

  • operações (opcional) — Uma lista de configurações de operação que mapeiam caminhos de solicitação para modelos compatíveis:

    • path (obrigatório) — O caminho da solicitação para essa operação (por exemplo,/v1/chat/completions).

    • providerPath (opcional) — O caminho para o qual encaminhar no provedor se for diferente do caminho da solicitação.

    • modelos (opcional) — Os modelos compatíveis com esta operação. Cada entrada inclui um campo de modelo (obrigatório) contendo um ID de modelo ou padrão global (por exemplo,anthropic.claude-opus-*).

Criação de um alvo de inferência do provedor

O exemplo a seguir cria um alvo de inferência do OpenAI usando uma configuração de provedor:

aws bedrock-agentcore-control create-gateway-target --cli-input-json '{
    "gatewayIdentifier": "GATEWAY_ID",
    "name": "openai",
    "targetConfiguration": {
        "inference": {
            "provider": {
                "endpoint": "https://api.openai.com",
                "operations": [
                    {
                        "path": "/v1/chat/completions",
                        "models": [
                            {"model": "gpt-5.5"},
                            {"model": "gpt-5.4"},
                            {"model": "gpt-5.4-mini"}
                        ]
                    },
                    {
                        "path": "/v1/responses",
                        "models": [
                            {"model": "gpt-5.5"},
                            {"model": "gpt-5.4"}
                        ]
                    }
                ]
            }
        }
    },
    "credentialProviderConfigurations": [
        {
            "credentialProviderType": "API_KEY",
            "credentialProvider": {
                "apiKeyCredentialProvider": {
                    "providerArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:token-vault/default/apikeycredentialprovider/openai-key",
                    "credentialLocation": "HEADER",
                    "credentialParameterName": "Authorization",
                    "credentialPrefix": "Bearer "
                }
            }
        }
    ]
}'

O exemplo a seguir cria um alvo de inferência do Bedrock com configuração explícita do provedor e mapeamento do modelo. A modelMapping configuração providerPrefix permite que os clientes usem nomes curtos de modelos (comoclaude-opus-4-7) enquanto o gateway os traduz em nomes com prefixo de provedor (como): anthropic.claude-opus-4-7

aws bedrock-agentcore-control create-gateway-target --cli-input-json '{
    "gatewayIdentifier": "GATEWAY_ID",
    "name": "bedrock",
    "targetConfiguration": {
        "inference": {
            "provider": {
                "endpoint": "https://bedrock-mantle.us-east-1.api.aws",
                "modelMapping": {
                    "providerPrefix": {"strip": true, "separator": "."}
                },
                "operations": [
                    {
                        "path": "/v1/chat/completions",
                        "models": [
                            {"model": "anthropic.claude-opus-*"},
                            {"model": "anthropic.claude-sonnet-*"},
                            {"model": "openai.gpt-oss-*"}
                        ]
                    },
                    {
                        "path": "/v1/messages",
                        "providerPath": "/anthropic/v1/messages",
                        "models": [
                            {"model": "anthropic.claude-opus-*"},
                            {"model": "anthropic.claude-sonnet-*"}
                        ]
                    }
                ]
            }
        }
    },
    "credentialProviderConfigurations": [
        {"credentialProviderType": "GATEWAY_IAM_ROLE"}
    ]
}'

Invocando um alvo de inferência do provedor

Para invocar um alvo de inferência, envie solicitações para o caminho do /inference gateway. O gateway encaminha cada solicitação para o destino correto com base no model campo no corpo da solicitação. O model valor pode ser um ID de modelo simples (por exemplo,gpt-5.5) ou um ID de modelo qualificado para o alvo no formulário {targetName}/{modelId} (por exemplo,openai/gpt-5.5). Para obter detalhes sobre como o model valor corresponde a uma meta, consulte Model-based roteamento.

O formato do URL é:

https://{gatewayId}.gateway.bedrock-agentcore.{region}.amazonaws.com/inference/{path}

{path}Substitua pelo caminho da operação de inferência (por exemplov1/chat/completions,v1/responses, ouv1/messages).

Usando o OpenAI SDK

Defina o /inference/v1 caminho do gateway comobase_url:

from openai import OpenAI

client = OpenAI(
    base_url="https://<gateway-id>.gateway.bedrock-agentcore.us-west-2.amazonaws.com/inference/v1",
    api_key="<gateway-auth-token>"
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello!"}]
)

Usando o Anthropic SDK

Defina o /inference caminho do gateway comobase_url:

import anthropic

client = anthropic.Anthropic(
    base_url="https://<gateway-id>.gateway.bedrock-agentcore.us-west-2.amazonaws.com/inference",
    api_key="<gateway-auth-token>"
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)

Usando awscurl

awscurl --service bedrock-agentcore --region us-west-2 -X POST \
    "https://<gateway-id>.gateway.bedrock-agentcore.us-west-2.amazonaws.com/inference/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -d '{"model": "gpt-5.5", "messages": [{"role": "user", "content": "Hello!"}]}'

Roteamento de modelos qualificados

Quando vários destinos atendem ao mesmo modelo, prefixe o ID do modelo com o nome do destino para rotear para um provedor específico:

# Route explicitly to the "bedrock" target
response = client.chat.completions.create(
    model="bedrock/claude-opus-4-7",
    messages=[{"role": "user", "content": "Hello!"}]
)

Model-based roteamento

O gateway encaminha as solicitações de inferência com base no model campo no corpo da solicitação:

  1. Roteamento qualificado — Se o ID do modelo contiver um / e o prefixo corresponder ao nome de um destino, a solicitação será roteada para esse destino (por exemplo, openai/gpt-5.5 rotas para o openai destino).

  2. Roteamento não qualificado — Se o ID do modelo não contiver um/, o gateway o comparará com todos os destinos configurados. Uma correspondência exata tem prioridade sobre os padrões globais. Se exatamente um destino corresponder, a solicitação será encaminhada para ele.

  3. Tratamento de colisão — Quando vários alvos correspondem ao mesmo modelo com a mesma especificidade, o gateway assume como padrão o alvo Amazon Bedrock se um estiver entre as correspondências. Caso contrário, ele distribui as solicitações entre os alvos correspondentes em ordem de rodízio. Para fixar solicitações em um alvo específico, qualifique o modelo com o nome do alvo como prefixo (por exemplo,bedrock/claude-opus-4-7).

Streaming

O streaming segue a convenção OpenAI SSE. "stream": trueDefinido no corpo da solicitação, o gateway passa pelo fluxo SSE do provedor sem transformação:

stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Write a story."}],
    stream=True
)

for chunk in stream:
    print(chunk.choices[0].delta.content, end="")

Autorização de saída

Os alvos do provedor de inferência oferecem suporte aos seguintes tipos de autorização de saída:

  • IAM (SigV4) — Use GATEWAY_IAM_ROLE para provedores que aceitam a autenticação do IAM (como o Amazon Bedrock).

  • Chave de API — Use API_KEY para provedores que exigem uma chave de API (como OpenAI e Anthropic). O gateway injeta a chave de API armazenada nas solicitações de saída.