Utilizzo del gateway modello su IBM Cloud (anteprima)

Variabili d'ambiente e chiavi

Per utilizzare il gateway del modello su IBM Cloud, è necessario fornire le chiavi API per i provider LLM supportati che si intende utilizzare. Si consiglia di configurare le variabili d'ambiente per tutte le chiavi.

Oltre alle chiavi API del provider LLM, si consiglia di utilizzare le variabili d'ambiente per il tracciamento di altre chiavi API (ad esempio per IBM Cloud IAM) e per altri valori di configurazione come gli URL. Per gli esempi di questo argomento, esportare l'host URL del gateway del modello IBM Cloud nella variabile d'ambiente GATEWAY_URL e la chiave API IAM in 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.

Impostazione dell'autenticazione

Per autenticare le richieste, utilizzare IBM Cloud Identity and Access Management (IAM).

Per utilizzare l'API, autentica la tua applicazione o il tuo servizio includendo il tuo token di accesso IBM Cloud IAM nelle richieste API.

1. Creare una nuova chiave API IAM

   • Per creare una chiave API IAM nell'interfaccia utente IBM Cloud, vedere Creare una chiave API utente nell'interfaccia utente.
   • Per creare una chiave API IAM nella CLI IBM Cloud utilizzare il seguente comando:

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

Per ulteriori informazioni, vedere Gestione delle chiavi API utente

2. Creare un IBM Cloud Secrets Manager

   Per utilizzare il gateway del modello, occorre fornire e collegare un'istanza IBM Secrets Manager istanza.

• Per la configurazione tramite l'interfaccia utente, vedere Creazione di un'istanza di Secrets Manager nell'interfaccia utente.

• Per configurare utilizzando la CLI, utilizzare il seguente comando.
  Sostituire <region> con ca-tor. Sostituire <plan> con uno dei seguenti ID di piano tariffario:
  • Processo : 869c191a-3c2a-4faf-98be-18d48f95ba1f
  • Piano standard : 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.

Per ulteriori informazioni, vedere Creazione di un'istanza di Secrets Manager dalla CLI.

3. Autorizzare Secrets Manager

   Prima di autorizzare, assicurarsi di avere il ruolo di servizio SecretsReader o superiore sulla propria istanza Secrets Manager. Per ulteriori informazioni, vedere Autorizzazione di un servizio IBM Cloud ad accedere a Secrets Manager.

   • Per autorizzare utilizzando l'interfaccia utente, vedere Creazione di un'autorizzazione nella console.
   • Per autorizzare utilizzando la CLI di IBM Cloud, è possibile utilizzare i seguenti comandi:

  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 è il nome del servizio per il runtime watsonx.ai.

Per ulteriori informazioni, vedere Uso delle autorizzazioni per garantire l'accesso tra i servizi.

Ora è possibile utilizzare IBM_CLOUD_APIKEY come un token portatore valido per il gateway modello su IBM Cloud.

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

Esempio

 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. È possibile configurare i provider LLM per il proprio account. Per configurare ciascun provider, inviare una richiesta a
   POST /v1/providers/<PROVIDER TYPE>. Il corpo della richiesta includerà:

   • name - Un identificatore personalizzato definito dall'utente per questa credenziale del provider LLM. Questo identificatore può essere qualsiasi cosa, ma deve essere unico. Gli esempi di questo argomento utilizzano "my-xxxx-provider" per ogni tipo di fornitore.
   • data - Contiene gli argomenti di configurazione forniti per l'impostazione della connessione al provider. In genere è richiesta una forma di apiKey . Alcuni fornitori possono richiedere o fornire opzionalmente parametri di configurazione aggiuntivi.

   La risposta a questa richiesta include un UUID per il provider, che deve essere annotato per essere utilizzato nelle fasi successive per abilitare i modelli sul provider.

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

Per maggiori dettagli ed esempi per ciascuno dei provider supportati, vedere Scelta di un provider LLM.

3. Per recuperare le informazioni sui fornitori di modelli configurati, chiamare GET /v1/providers fornendo il nome della credenziale.

   L'esempio seguente mostra come recuperare l'UUID del provider my-openai-provider OpenAI esportando l'UUID dalla risposta in una variabile d'ambiente. Gli UUID dei fornitori saranno utilizzati nella fase successiva per abilitare i modelli.

  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. Dopo aver aggiunto un fornitore di modelli, si possono abilitare i modelli che si vogliono usare attraverso tale fornitore, chiamando POST /v1/providers/{provider_id}/models con l'UUID del fornitore e fornendo l'ID del modello nella richiesta. L'ID del modello deve essere un identificatore univoco esistente per un modello noto al provider LLM. Spesso i modelli sono forniti da più fornitori; gli alias dei modelli sono nomi personalizzati definiti dall'utente che possono essere usati per identificare il modello al posto dell'ID. Per esempi, vedere Modelli di abilitazione per i fornitori di LLM.

Scegliere un provider di LLM

Il modello di gateway può essere utilizzato da qualsiasi provider che supporti un endpoint OpenAI-compatible :

1. Selezione di OpenAI come provider
2. Sostituzione di base_url con il nuovo url

Esempio

Per eseguire il provisioning di un endpoint OpenAI-compatible di Gemini, utilizzare il seguente 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 certifica solo i seguenti tipi di provider 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}}')"

Modelli di abilitazione per i fornitori di LLM

I seguenti esempi dimostrano come abilitare i modelli per i fornitori:

Abilitare il modello OpenAI's GPT-4o per il provider Azure OpenAI dell'utente

  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"}'

Abilitare il modello Claude 3.7 Sonnet di Anthropic per il provider AWS Bedrock dell'utente :

  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"}'

Fornitori e modelli di elenchi

È possibile elencare sia i provider che i modelli configurati. Di seguito sono riportati gli esempi per elencare tutti i provider configurati, tutti i modelli per un determinato provider e tutti i modelli tra i provider configurati.

Per elencare tutti i fornitori di modelli configurati, usare il seguente comando:

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

Per elencare tutti i modelli abilitati per il provider Azure OpenAI configurato, utilizzare il seguente comando:

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

Per elencare tutti i modelli abilitati (su tutti i provider configurati), utilizzare il seguente comando:

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

Esempi

Completamenti della 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?"
      }
    ]
  }'

Completamento del testo/Generazione - /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
  }'

Generazione di incorporazioni - /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)