Utilización de la pasarela de modelos en IBM Cloud (vista previa)

Variables de entorno y claves

Para utilizar la pasarela de modelos en IBM Cloud, debe proporcionar claves de API para los proveedores de LLM compatibles que tenga previsto utilizar. Se recomienda configurar variables de entorno para todas sus claves.

Además de las claves API del proveedor LLM, se recomienda utilizar variables de entorno para el seguimiento de otras claves API (como para IBM Cloud IAM) y para otros valores de configuración como las URL. Para los ejemplos de este tema, exporte el host URL de la pasarela modelo IBM Cloud a la variable de entorno GATEWAY_URL y la clave API de IAM a IBM_CLOUD_APIKEY.

export GATEWAY_URL="https://ca-tor.ml.cloud.ibm.com/ml/gateway"
export IBM_CLOUD_APIKEY="xxxx" # See below for more info on how to create an IBM Cloud IAM API key.

Configuración de la autenticación

Para autenticar las solicitudes, utilice IBM Cloud Identity and Access Management (IAM).

Para trabajar con la API, autentique su aplicación o servicio incluyendo su token de acceso IAM de IBM Cloud en las solicitudes de API.

1. Crear una nueva clave API IAM

   • Para crear una clave de API de IAM en la interfaz de usuario IBM Cloud, consulte Crear una clave de API de usuario en la interfaz de usuario.
   • Para crear una clave de API de IAM en la CLI de IBM Cloud, utilice el siguiente comando:

ibmcloud iam api-key-create MyKey -d "this is my API key" --file key_file --action-if-leaked "DELETE"

Para más información, consulte Gestión de claves API de usuario

2. Crear un IBM Cloud Secrets Manager

   Para utilizar la pasarela de modelos, aprovisione y vincule una IBM Secrets Manager instancia.

• Para configurar usando la IU, consulte Crear una instancia Secrets Manager en la IU.

• Para configurarlo mediante la CLI, utilice el siguiente comando.
  Sustituya <region> por ca-tor. Sustituya <plan> por uno de los siguientes ID de plan de precios:
  • Juicio : 869c191a-3c2a-4faf-98be-18d48f95ba1f
  • Plan estándar : 7713c3a8-3be8-4a9a-81bb-ee822fcaac3d

 ibmcloud login
 ibmcloud target -r <region> -g <resource_group_name>
 ibmcloud resource service-instance-create <instance_name> secrets-manager <plan> -p '{"allowed_network": "public-and-private"}'
 ibmcloud resource service-instances # Optional, verifies that the service instance was created successfully.

Para obtener más información, consulte Creación de una instancia de Secrets Manager desde la CLI.

3. Autorizar Secrets Manager

   Antes de autorizar, asegúrese de que tiene el rol de servicio SecretsReader o superior en su instancia Secrets Manager. Para más información, consulte Autorización de un servicio IBM Cloud para acceder a Secrets Manager.

   • Para autorizar mediante la interfaz de usuario, consulte Creación de una autorización en la consola.
   • Para autorizar utilizando la CLI IBM Cloud, se pueden utilizar los siguientes comandos:

  ibmcloud login -a https://cloud.ibm.com --apikey ${IBM_CLOUD_APIKEY}
  ibmcloud iam authorization-policy-create SecretsReader \
      --source-service-name pm-20 \
      --target-service-name secrets-manager

Nota: pm-20 es el nombre del servicio para el tiempo de ejecución watsonx.ai.

Para obtener más información, consulte Utilización de autorizaciones para otorgar acceso entre servicios.

Ahora puede utilizar IBM_CLOUD_APIKEY como un token de portador válido para el modelo de pasarela en IBM Cloud.

curl ${GATEWAY_URL}/v1/...  \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${IBM_CLOUD_APIKEY}" \
  ...

Ejemplo

 curl ${GATEWAY_URL}/v1/tenant  \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ${IBM_CLOUD_APIKEY}" \
   -d @- <<EOF
  {
    "name": "test",
    "secrets_manager": "${SECRETS_MANAGER}"
  }
  EOF

2. Puede configurar proveedores LLM para su cuenta. Para configurar cada proveedor, envíe una solicitud a
   POST /v1/providers/<PROVIDER TYPE>. El cuerpo de la solicitud incluirá:

   • name - Un identificador personalizado definido por el usuario para esta credencial de proveedor LLM. Este identificador puede ser cualquier cosa, pero tiene que ser único. Los ejemplos de este tema utilizan "my-xxxx-provider" para cada tipo de proveedor.
   • data - Contiene los argumentos de configuración suministrados para establecer la conexión con el proveedor. Normalmente, se requiere algún tipo de apiKey . Algunos proveedores pueden requerir o suministrar opcionalmente parámetros de configuración adicionales.

   La respuesta a esta solicitud incluye un UUID para el proveedor que debe ser anotado para su uso en pasos posteriores para habilitar modelos en el proveedor.

  {
    "uuid": "de972dcf-7042-4cag-e7a3-d90a16229e5b",
    "name": "my-openai-provider",
    "type": "openai"
  }

Para más detalles y ejemplos de cada uno de los proveedores admitidos, consulte Elegir un proveedor de LLM.

3. Para recuperar información sobre los proveedores de modelos configurados, llame a GET /v1/providers indicando el nombre de la credencial.

   El siguiente ejemplo muestra cómo recuperar el UUID de su proveedor my-openai-provider OpenAI exportando el UUID de la respuesta a una variable de entorno. Los UUID de los proveedores se utilizarán en el siguiente paso para habilitar los modelos.

  export OPENAI_PROVIDER_UUID=$(curl -sS ${GATEWAY_URL}/v1/providers  \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${IBM_CLOUD_APIKEY}" \
  | jq -r --arg name "my-openai-provider" '.[] | select(.name == $name) | .uuid')

4. Una vez añadido un proveedor de modelos, puede activar los modelos que desee utilizar a través de dicho proveedor llamando a POST /v1/providers/{provider_id}/models con el UUID del proveedor y proporcionando el ID del modelo en la solicitud. El ID del modelo debe ser un identificador único existente para un modelo conocido por el proveedor de LLM. A menudo los modelos son proporcionados por varios proveedores; los alias de modelo son nombres personalizados definidos por el usuario que pueden utilizarse para identificar el modelo en lugar del ID. Para ver ejemplos, consulte Modelos de habilitación para proveedores de LLM.

Elegir un proveedor de LLM

El modelo de pasarela puede ser utilizado por cualquier proveedor que admita un punto final OpenAI-compatible mediante:

1. Seleccionar OpenAI como proveedor
2. Sustitución de la base_url por la nueva url

Ejemplo

Para aprovisionar un punto final de Gemini OpenAI-compatible utilice el siguiente comando:

export OPENAI_APIKEY="xxxx"
export BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai"

curl -sS ${GATEWAY_URL}/v1/providers/openai \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $IBM_CLOUD_APIKEY" \
  -d "$(jq -n \
        --arg name "my-gemini-provider" \
        --arg apikey "$OPENAI_APIKEY" \
        --arg base_url "$BASE_URL"
        '{name: $name, data: {apikey: $apikey, base_url: $base_url}}')"

IBM sólo certifica los siguientes tipos de proveedores de LLM:

• OpenAI
• IBM watsonx.ai
• Azure OpenAI
• Anthropic
• AWS Bedrock
• Cerebras
• NVIDIA NIM

export OPENAI_APIKEY="xxxx"

curl -sS ${GATEWAY_URL}/v1/providers/openai \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $IBM_CLOUD_APIKEY" \
  -d "$(jq -n \
        --arg name "my-openai-provider" \
        --arg apikey "$OPENAI_APIKEY" \
        '{name: $name, data: {apikey: $apikey}}')"

export WATSONX_AI_APIKEY="xxxx"
export WATSONX_AI_PROJECT_ID="xxxx"

curl -sS ${GATEWAY_URL}/v1/providers/watsonxai \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $IBM_CLOUD_APIKEY" \
  -d "$(jq -n \
        --arg name "my-watsonxai-provider" \
        --arg apikey "$WATSONX_AI_APIKEY" \
        --arg projectid "$WATSONX_AI_PROJECT_ID" \
        '{name: $name, data: {apikey: $apikey, project_id: $projectid}}')"

export AZURE_OPENAI_APIKEY="xxxx"
export AZURE_OPENAI_RESOURCE_NAME="xxxx"

curl -sS ${GATEWAY_URL}/v1/providers/azure-openai \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $IBM_CLOUD_APIKEY" \
  -d "$(jq -n \
        --arg name "my-azure-openai-provider" \
        --arg apikey "$AZURE_OPENAI_APIKEY" \
        --arg resourcename "$AZURE_OPENAI_RESOURCE_NAME" \
        '{name: $name, data: {apikey: $apikey, resource_name: $resourcename}}')"

export ANTHROPIC_APIKEY="xxxx"

curl -sS ${GATEWAY_URL}/v1/providers/anthropic \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $IBM_CLOUD_APIKEY" \
  -d "$(jq -n \
        --arg name "my-anthropic-provider" \
        --arg apikey "$ANTHROPIC_APIKEY" \
        '{name: $name, data: {apikey: $apikey}}')"

export AWS_BEDROCK_KEY_ID="xxxx"
export AWS_BEDROCK_ACCESS_KEY="xxxx"
export AWS_BEDROCK_REGION="us-east-1"

curl -sS ${GATEWAY_URL}/v1/providers/bedrock \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $IBM_CLOUD_APIKEY" \
  -d "$(jq -n \
        --arg name "my-bedrock-provider" \
        --arg keyid "$AWS_BEDROCK_KEY_ID" \
        --arg accesskey "$AWS_BEDROCK_ACCESS_KEY" \
        --arg region "$AWS_BEDROCK_REGION" \
        '{name: $name, data: {access_key_id: $keyid, secret_access_key: $accesskey, region: $region}}')"

export CEREBRAS_APIKEY="xxxx"

curl -sS ${GATEWAY_URL}/v1/providers/cerebras \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $IBM_CLOUD_APIKEY" \
  -d "$(jq -n \
        --arg name "my-cerebras-provider" \
        --arg apikey "$CEREBRAS_APIKEY" \
        '{name: $name, data: {apikey: $apikey}}')"

export NIM_APIKEY="xxxx"

curl -sS ${GATEWAY_URL}/v1/providers/nim \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $IBM_CLOUD_APIKEY" \
  -d "$(jq -n \
        --arg name "my-nim-provider" \
        --arg apikey "$NIM_APIKEY" \
        '{name: $name, data: {apikey: $apikey}}')"

Modelos de capacitación para proveedores de LLM

Los siguientes ejemplos muestran cómo habilitar modelos para proveedores:

Habilitar el modelo OpenAI's GPT-4o para el proveedor del usuario Azure OpenAI

  curl -X POST "${GATEWAY_URL}/v1/providers/${AZURE_OPENAI_PROVIDER_UUID}/models" \
	  -H "Content-Type: application/json" \
	  -H "Authorization: Bearer ${IBM_CLOUD_APIKEY}" \
	  -d '{ "alias": "azure/gpt-4o", "id": "scribeflowgpt4o"}'

Habilitar el modelo Sonnet de Claude 3.7 de Anthropic para el proveedor AWS Bedrock del usuario :

  curl -X POST "${GATEWAY_URL}/v1/providers/${AWS_BEDROCK_PROVIDER_UUID}/models" \
	  -H "Content-Type: application/json" \
	  -H "Authorization: Bearer ${IBM_CLOUD_APIKEY}" \
	  -d '{ "alias": "aws/claude-3-sonnet", "id": "anthropic.claude-3-7-sonnet-20250219-v1:0"}'

Listado de proveedores y modelos

Puedes listar tanto los proveedores como los modelos que hayas configurado. A continuación se muestran ejemplos para listar todos los proveedores configurados, todos los modelos de un proveedor determinado y todos los modelos de todos los proveedores configurados.

Para listar todos los proveedores de modelos configurados, utilice el siguiente comando:

curl -sS ${GATEWAY_URL}/v1/providers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${IBM_CLOUD_APIKEY}"

Para listar todos los modelos habilitados para el proveedor Azure OpenAI configurado, utilice el siguiente comando:

curl -sS "${GATEWAY_URL}/v1/providers/${AZURE_OPENAI_DALLE_PROVIDER_UUID}/models" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer ${IBM_CLOUD_APIKEY}"

Para listar todos los modelos habilitados (en todos los proveedores configurados), utilice el siguiente comando:

curl -sS "${GATEWAY_URL}/v1/models" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer ${IBM_CLOUD_APIKEY}"

Ejemplos

Finalizaciones del chat - /v1/chat/completions

curl ${GATEWAY_URL}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $IBM_CLOUD_APIKEY" \
  -d '{
    "model": "azure/gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "Please explain everything in a way a 5th grader could understand—simple language, clear steps, and easy examples."
      },
      {
        "role": "user",
        "content": "Can you explain what TLS is and how I can use it?"
      }
    ]
  }'

Completar texto/Generar - /v1/completions

curl ${GATEWAY_URL}/v1/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $IBM_CLOUD_APIKEY" \
  -d '{
    "model": "ibm/llama-3-3-70b-instruct",
    "prompt": "Say this is a test",
    "max_tokens": 7,
    "temperature": 0
  }'

Generación de incrustaciones - /v1/embeddings

curl ${GATEWAY_URL}/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $IBM_CLOUD_APIKEY" \
  -d '{
    "input": "The food was delicious and the waiter...",
    "model": "text-embedding-3-large",
    "encoding_format": "float"
  }'

import os
from openai import OpenAI

# Note that since we exported GATEWAY_URL=https://us-south.ml.cloud.ibm.com/ml/gateway/, we must specify the "/v1".
# This is because the client will invoke OpenAI child paths like "/chat/completions" not "/v1/chat/completions".
gateway_url = os.getenv("GATEWAY_URL") + "v1"
ibm_cloud_api_key = os.getenv("IBM_CLOUD_APIKEY")

print("Using GATEWAY_URL:", gateway_url)
print("Using IBM_CLOUD_APIKEY:", ibm_cloud_api_key)

# Customize client to connect to the model gateway using the IBM Cloud API key.
client = OpenAI(
    base_url=gateway_url,
    api_key=ibm_cloud_api_key,
)

# Create a Chat Completions request to the model gateway.
completion = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)

print(completion.choices[0].message)