# 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. **Topics** + [Configurações de destino](#gateway-target-inference-provider-config) + [Criação de um alvo de inferência do provedor](#gateway-target-inference-provider-create) + [Invocando um alvo de inferência do provedor](#gateway-target-inference-provider-invoke) + [Model-based roteamento](#gateway-target-inference-provider-routing) + [Streaming](#gateway-target-inference-provider-streaming) + [Autorização de saída](#gateway-target-inference-provider-auth) ## 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) — Quando`true`, os clientes podem usar IDs de modelo sem o prefixo do provedor (por exemplo, `claude-opus-4-7` em vez de`anthropic.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 (como`claude-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](#gateway-target-inference-provider-routing). 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 exemplo`v1/chat/completions`,`v1/responses`, ou`v1/messages`). ### Usando o OpenAI SDK Defina o `/inference/v1` caminho do gateway como`base_url`: ``` from openai import OpenAI client = OpenAI( base_url="https://.gateway.bedrock-agentcore.us-west-2.amazonaws.com/inference/v1", api_key="" ) response = client.chat.completions.create( model="gpt-5.5", messages=[{"role": "user", "content": "Hello!"}] ) ``` ### Usando o Anthropic SDK Defina o `/inference` caminho do gateway como`base_url`: ``` import anthropic client = anthropic.Anthropic( base_url="https://.gateway.bedrock-agentcore.us-west-2.amazonaws.com/inference", api_key="" ) 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.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). 1. **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. 1. **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": true`Definido 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.