Bedrock a través de LiteLLM

Usa esta página cuando tu organización dirija Codex a Amazon Bedrock a través de LiteLLM. Si ya existe una pasarela LiteLLM, conecta primero Codex. Despliega LiteLLM solo cuando tu organización necesite una pasarela nueva.

Otros productos de pasarela siguen los mismos requisitos de las pasarelas y el mismo flujo de conexión de Codex.

Conectarse a una pasarela existente

Obtén estos valores del administrador de tu pasarela:

• La URL base HTTPS, como https://gateway.example.com/v1.
• El alias de modelo que LiteLLM dirige a un modelo de Bedrock aprobado.
• El ID del proveedor que se debe usar en la configuración de Codex.
• Una credencial de pasarela con alcance limitado o un asistente de autenticación que la devuelva.
• Cualquier catálogo de modelos distribuido con la configuración de tu organización.

Después, completa la conexión en este orden:

1. Pide al equipo de la pasarela que confirme que esta sirve POST /v1/responses, transmite las respuestas, conserva los turnos de seguimiento y las llamadas a herramientas, y dirige el alias aprobado. Consulta Compatibilidad de las pasarelas.
2. Sigue Conectarse a una pasarela para configurar el proveedor, el modelo y la credencial.
3. Verifica el proveedor y el alias activos, envía el prompt breve gateway-ok de la guía de conexión y confirma que el registro de LiteLLM muestre el usuario y el alias esperados.
4. Para la distribución en toda la organización, continúa con Desplegar Codex a través de una pasarela.

Tu credencial de pasarela te autentica en LiteLLM. La pasarela administra sus propias credenciales de Bedrock; no necesitas copiarlas a tu estación de trabajo.

Preparar una pasarela

Usa esta sección solo cuando necesites crear una pasarela LiteLLM antes de conectar Codex.

Antes del despliegue

Confirma que dispones de:

• Permiso para desplegar la arquitectura de LiteLLM aprobada en tu entorno de AWS.
• Acceso en Bedrock a los modelos o perfiles de inferencia a los que dirigirás las solicitudes.
• Una imagen de LiteLLM y un patrón de despliegue revisados.
• Un nombre de host HTTPS y un certificado de confianza.
• Un rango de red de clientes restringido.

Para el ejemplo de Runtime que aparece a continuación, la identidad de AWS de la pasarela necesita bedrock:InvokeModel para el perfil de inferencia seleccionado y el proyecto predeterminado de la cuenta. Consulta las instrucciones de configuración de GPT-6 Sol de AWS para conocer los permisos necesarios.

Arquitectura

El despliegue mantiene LiteLLM entre Codex y Bedrock, con HTTPS en el límite del cliente. El balanceador de carga y LiteLLM están dentro del límite de la pasarela de tu organización; la credencial del proveedor permanece en la pasarela.

Restringe el acceso entrante a los clientes aprobados, mantén privados los puertos de la base de datos y de la caché, y concede a la pasarela solo los permisos de Bedrock que necesite. Fija la imagen desplegada mediante su digest para que un reinicio no cambie silenciosamente la implementación.

Los prompts, los fragmentos de código fuente y los resultados de herramientas pasan por la pasarela y pueden incluirse en sus registros. Decide la retención, el acceso y la ocultación de datos sensibles antes de habilitar el registro de solicitudes. Los MCP servers y los plugins tienen conexiones y autenticación independientes; esta configuración de pasarela no los configura.

Puntos de control del despliegue

Completa estos puntos de control en orden antes de entregar la pasarela a los desarrolladores:

Las secciones siguientes cubren cada punto de control. Para una implementación en producción, prueba también los turnos de seguimiento, las herramientas y la revocación de credenciales.

Elegir la ruta de Bedrock

La ruta de origen de LiteLLM determina el endpoint de Bedrock, el identificador del modelo y el método de autenticación. Mantén estas elecciones coordinadas cuando despliegues o cambies la pasarela.

Usa Bedrock Runtime para las configuraciones nuevas. El siguiente ejemplo utiliza su endpoint de Responses compatible con OpenAI.

Consulta la integración de Bedrock Mantle de LiteLLM para conocer la ruta alternativa.

Para ver un ejemplo de despliegue en AWS, usa la referencia de LiteLLM en ECS fijada a una versión. Esa implementación utiliza Bedrock Runtime y renueva la autenticación desde el rol de tarea de ECS. Sigue conjuntamente sus pasos de despliegue y autenticación, y revisa sus requisitos de producción según tus políticas de red, TLS, registro y retención de recursos.

Sea cual sea la ruta elegida, verifica la combinación desplegada de versión de la pasarela, endpoint de origen y modelo según Compatibilidad de las pasarelas. Que un modelo de origen aparezca en la lista de modelos de la pasarela no demuestra que su comportamiento de transmisión, continuación y herramientas funcione con Codex.

Configurar una ruta de modelo de Runtime

Asigna un alias estable para Codex al modelo de origen aprobado. Confirma el acceso en tu cuenta y región de AWS antes de usar este ejemplo 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

Proporciona una API key de Bedrock válida como AWS_BEARER_TOKEN_BEDROCK mediante tu sistema de administración de secretos. Para una clave de corta duración, emite un reemplazo antes de que venza, actualiza el entorno del proceso de la pasarela y reinicia o vuelve a desplegar los procesos de trabajo que la utilicen. En cambio, la referencia de ECS renueva las credenciales dentro del proceso desde su rol de tarea; usa conjuntamente su configuración y su punto de entrada.

El prefijo openai/ selecciona el adaptador de LiteLLM compatible con OpenAI; el valor configurado de api_base envía solicitudes a Bedrock Runtime. El perfil de inferencia Global puede dirigir solicitudes fuera de la región de origen. Elige un perfil y una región que cumplan tus requisitos de permisos de AWS y residencia de datos, y reemplaza ambos valores según sea necesario.

El cliente envía company-coding-model; LiteLLM utiliza la ruta de origen configurada. Este alias personalizado requiere el catálogo de cliente correspondiente que se describe a continuación. Una pasarela genérica no hereda los ajustes de metadatos del proveedor de Bedrock integrado.

Preparar el catálogo del cliente

Para este ejemplo de GPT-6 Sol/Runtime con Codex 0.158.0, empieza con la entrada completa gpt-6-sol del catálogo de modelos de esa versión. Aplica todos estos cambios a esa entrada:

Conserva los demás campos, incluidas las instrucciones del modelo y los límites de contexto. Mantén la entrada editada en el arreglo models de nivel superior del catálogo. Estos cambios reflejan los ajustes de metadatos de Bedrock y la restricción de búsqueda de Runtime publicados. Vuelve a comprobarlos con el código fuente correspondiente cuando cambies la versión del cliente o el modelo de origen.

Distribuye el archivo JSON completo y configura model_catalog_json siguiendo Desplegar Codex a través de una pasarela. Mantén web_search = "disabled" en la configuración del cliente de Runtime. Verifica el catálogo editado a través de la pasarela antes de distribuirlo a más usuarios.

Verificar la compatibilidad con Responses

Expón POST /v1/responses en el endpoint HTTPS orientado al cliente. Configura el balanceador de carga y cualquier proxy inverso para que pasen los eventos de transmisión sin almacenarlos en búfer. Conserva los turnos de seguimiento y los resultados de llamadas a funciones. Un endpoint funcional de Chat Completions por sí solo no basta para esta conexión.

Completa las comprobaciones de Compatibilidad de las pasarelas antes de distribuir la configuración del cliente. Prueba con el mismo nombre de host, los mismos controles de red y la misma ruta de autenticación que utilizarán tus usuarios.

Emitir una credencial de prueba

Crea una clave virtual de LiteLLM con alcance limitado para un usuario de prueba. Restríngela al alias aprobado y configura el vencimiento, los límites de frecuencia y un presupuesto. Consulta la documentación de claves virtuales de LiteLLM para conocer los controles aplicables.

Distribuye la clave mediante tu proceso de administración de secretos o un asistente de autenticación. No entregues a los usuarios la clave administrativa de LiteLLM ni incrustes credenciales de pasarela en config.toml.

Verificar la conexión del usuario

Completa estas comprobaciones antes de ampliar el acceso:

1. Confirma que el certificado HTTPS coincida con el nombre de host de la pasarela y que el servicio funcione correctamente.
2. Conecta a un usuario siguiendo Conectarse a una pasarela.
3. Ejecuta un prompt breve, un turno de seguimiento y una tarea de herramienta de solo lectura.
4. Confirma que los registros de la pasarela muestren la identidad, el alias y la ruta de origen esperados sin exponer credenciales ni contenido sensible del prompt.
5. Prueba el vencimiento o la revocación de credenciales y confirma que se rechacen los alias de modelos no autorizados.

Guarda la versión de la imagen desplegada, la configuración de las rutas y los resultados de las pruebas junto con el registro de la implementación. Continúa con Desplegar Codex a través de una pasarela para la distribución al equipo y las operaciones continuas.

Solucionar problemas de conexión

Usa la capa que falla para delimitar el problema:

Vuelve a probar la misma ruta del usuario después de aplicar una corrección. Una comprobación de estado exitosa de la pasarela no verifica una solicitud de inferencia autenticada ni un turno completo de Codex.