Bedrock através do LiteLLM

Utilize esta página quando a sua organização encaminhar o Codex para o Amazon Bedrock através do LiteLLM. Se já existir um gateway LiteLLM, ligue primeiro o Codex. Implemente o LiteLLM apenas quando a sua organização precisar de um novo gateway.

Outros produtos de gateway seguem os mesmos requisitos do gateway e o mesmo processo de ligação do Codex.

Ligar a um gateway existente

Obtenha estes valores junto do administrador do gateway:

• O URL base HTTPS, como https://gateway.example.com/v1.
• O alias de modelo que o LiteLLM encaminha para um modelo Bedrock aprovado.
• O ID do fornecedor a utilizar na configuração do Codex.
• Uma credencial de gateway com âmbito limitado ou um utilitário de autenticação que a devolva.
• Qualquer catálogo de modelos distribuído com a configuração da sua organização.

Em seguida, conclua a ligação por esta ordem:

1. Peça à equipa responsável pelo gateway que confirme que o gateway disponibiliza POST /v1/responses, transmite respostas em fluxo, preserva as interações subsequentes e as chamadas de ferramentas e encaminha o alias aprovado. Consulte Compatibilidade do gateway.
2. Siga Ligar a um gateway para configurar o fornecedor, o modelo e a credencial.
3. Verifique o fornecedor e o alias ativos, envie o prompt curto gateway-ok do guia de ligação e confirme que o registo do LiteLLM apresenta o utilizador e o alias esperados.
4. Para distribuir a toda a organização, continue com Implementar o Codex através de um gateway.

A sua credencial de gateway autentica-o no LiteLLM. O gateway gere as suas próprias credenciais do Bedrock; não precisa de copiar essas credenciais para a sua estação de trabalho.

Preparar um gateway

Utilize esta secção apenas quando precisar de criar um gateway LiteLLM antes de ligar o Codex.

Antes de implementar

Confirme que dispõe de:

• Permissão para implementar a arquitetura LiteLLM aprovada no seu ambiente AWS.
• Acesso no Bedrock aos modelos ou perfis de inferência que irá encaminhar.
• Uma imagem LiteLLM e um padrão de implementação revistos.
• Um nome de anfitrião HTTPS e um certificado de confiança.
• Um intervalo de rede de clientes restrito.

Para o exemplo de Runtime abaixo, a identidade AWS do gateway precisa de bedrock:InvokeModel para o perfil de inferência selecionado e para o projeto predefinido da conta. Consulte as instruções de configuração do GPT-6 Sol da AWS para conhecer as permissões necessárias.

Arquitetura

A implementação mantém o LiteLLM entre o Codex e o Bedrock, com HTTPS na interface com o cliente. O balanceador de carga e o LiteLLM encontram-se dentro do perímetro do gateway da sua organização; a credencial do fornecedor permanece no gateway.

Restrinja o acesso de entrada aos clientes aprovados, mantenha privadas as portas da base de dados e da cache e conceda ao gateway apenas as permissões do Bedrock de que necessita. Fixe a imagem implementada pelo respetivo digest para que um reinício não altere silenciosamente a implementação.

Os prompts, os excertos de código-fonte e os resultados de ferramentas passam pelo gateway e podem ser incluídos nos respetivos registos. Decida as políticas de retenção, acesso e ocultação de dados sensíveis antes de ativar o registo de pedidos. Os MCP servers e os plugins têm ligações e autenticação separadas; esta configuração do gateway não os configura.

Pontos de verificação da implementação

Conclua estes pontos de verificação por ordem antes de entregar o gateway aos programadores:

As secções abaixo abordam cada ponto de verificação. Para a disponibilização em produção, teste também as interações subsequentes, as ferramentas e a revogação de credenciais.

Escolher a rota do Bedrock

A rota a montante do LiteLLM determina o endpoint do Bedrock, o identificador do modelo e o método de autenticação. Mantenha estas escolhas em conjunto ao implementar ou alterar o gateway.

Utilize o Bedrock Runtime para novas configurações. O exemplo abaixo utiliza o respetivo endpoint Responses compatível com a OpenAI.

Consulte a integração do Bedrock Mantle do LiteLLM para conhecer a rota alternativa.

Para um exemplo de implementação na AWS, utilize a referência do LiteLLM no ECS fixada numa versão específica. Essa implementação utiliza o Bedrock Runtime e atualiza a autenticação a partir da função da tarefa do ECS. Siga os respetivos passos de implementação e autenticação em conjunto e reveja os requisitos de produção face às suas políticas de rede, TLS, registo de eventos e retenção de recursos.

Seja qual for a rota escolhida, verifique a combinação implementada de versão do gateway, endpoint a montante e modelo face à Compatibilidade do gateway. O facto de um modelo a montante aparecer na lista de modelos do gateway não comprova que a transmissão em fluxo, a continuação e o comportamento das ferramentas funcionam com o Codex.

Configurar uma rota de modelo do Runtime

Mapeie um alias estável para utilização pelo Codex para o modelo aprovado a montante. Confirme o acesso na sua conta e Região AWS antes de utilizar este exemplo de Runtime.

model_list:
  - model_name: company-coding-model
    litellm_params:
      model: openai/global.openai.gpt-6-sol
      api_key: os.environ/AWS_BEARER_TOKEN_BEDROCK
      api_base: https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1

Forneça uma API key válida do Bedrock como AWS_BEARER_TOKEN_BEDROCK através do seu sistema de gestão de segredos. Para uma chave de curta duração, emita uma substituição antes de expirar, atualize o ambiente do processo do gateway e reinicie ou volte a implementar os processos de trabalho que a utilizam. A referência do ECS, por sua vez, atualiza as credenciais dentro do processo a partir da função da tarefa; utilize a respetiva configuração e o ponto de entrada em conjunto.

O prefixo openai/ seleciona o adaptador do LiteLLM compatível com a OpenAI; o api_base configurado envia pedidos para o Bedrock Runtime. O perfil de inferência Global pode encaminhar pedidos para fora da Região de origem. Escolha um perfil e uma Região que cumpram as suas permissões AWS e os requisitos de residência dos dados e substitua ambos os valores conforme necessário.

O cliente envia company-coding-model; o LiteLLM utiliza a rota a montante configurada. Este alias personalizado requer o catálogo de cliente correspondente descrito a seguir. Um gateway genérico não herda os ajustes de metadados do fornecedor Bedrock integrado.

Preparar o catálogo do cliente

Para este exemplo de GPT-6 Sol/Runtime com o Codex 0.158.0, comece pela entrada completa gpt-6-sol do catálogo de modelos dessa versão. Aplique todas estas alterações a essa entrada:

Preserve os restantes campos, incluindo as instruções e os limites de contexto do modelo. Mantenha a entrada editada no array models de nível superior do catálogo. Estas alterações refletem os ajustes de metadados do Bedrock e a restrição de pesquisa do Runtime publicados. Volte a verificá-los face ao código-fonte correspondente ao alterar a versão do cliente ou o modelo a montante.

Distribua o ficheiro JSON completo e configure model_catalog_json seguindo Implementar o Codex através de um gateway. Mantenha web_search = "disabled" na configuração do cliente Runtime. Verifique o catálogo editado através do gateway antes de o distribuir a mais utilizadores.

Verificar o suporte de Responses

Disponibilize POST /v1/responses no endpoint HTTPS acessível aos clientes. Configure o balanceador de carga e qualquer proxy inverso para transmitir eventos em fluxo sem acumulação em buffer. Preserve as interações subsequentes e os resultados das chamadas de funções. Um endpoint funcional de Chat Completions, por si só, não é suficiente para esta ligação.

Conclua as verificações em Compatibilidade do gateway antes de distribuir a configuração do cliente. Teste através do mesmo nome de anfitrião, controlos de rede e percurso de autenticação que os utilizadores irão utilizar.

Emitir uma credencial de teste

Crie uma chave virtual do LiteLLM com âmbito limitado para um utilizador de teste. Restrinja-a ao alias aprovado e configure a expiração, os limites de pedidos e um orçamento. Consulte a documentação de chaves virtuais do LiteLLM para conhecer os controlos aplicáveis.

Distribua a chave através do seu processo de gestão de segredos ou de um utilitário de autenticação. Não forneça aos utilizadores a chave administrativa do LiteLLM nem incorpore credenciais do gateway em config.toml.

Verificar a ligação do utilizador

Conclua estas verificações antes de alargar o acesso:

1. Confirme que o certificado HTTPS corresponde ao nome de anfitrião do gateway e que o serviço está a funcionar corretamente.
2. Ligue um utilizador seguindo Ligar a um gateway.
3. Execute um prompt curto, uma interação subsequente e uma tarefa de ferramenta apenas de leitura.
4. Confirme que os registos do gateway apresentam a identidade, o alias e a rota a montante esperados sem expor credenciais ou conteúdo sensível dos prompts.
5. Teste a expiração ou a revogação de credenciais e confirme que os aliases de modelos não autorizados são rejeitados.

Guarde a versão da imagem implementada, a configuração das rotas e os resultados dos testes juntamente com o registo da disponibilização. Continue com Implementar o Codex através de um gateway para a distribuição à equipa e a operação contínua.

Resolver problemas de ligação

Utilize a camada com falha para delimitar o problema:

Volte a testar o mesmo percurso do utilizador após uma correção. Uma verificação bem-sucedida do estado de funcionamento do gateway não verifica um pedido de inferência autenticado nem uma interação completa do Codex.