IBM Cloud でモデルゲートウェイを使う（プレビュー）

環境変数とキー

IBM Cloud でモデル・ゲートウェイを使用するには、使用する予定のサポートされた LLM プロバイダーの API キーを提供する必要があります。 すべてのキーに環境変数を設定することを推奨する。

LLMプロバイダーAPIキーの他に、他のAPIキー（ IBM Cloud IAM用など）の追跡や、URLなどの他の設定値のために、環境変数を使用することを推奨する。 このトピックの例では、 IBM Cloud モデル・ゲートウェイのホスト URL を環境変数 GATEWAY_URL に、IAM API キーを 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.

認証のセットアップ

リクエストを認証するには、 IBM Cloud Identity and Access Management (IAM) を使う。

API を使用するには、 IBM Cloud IAM アクセストークンを API リクエストに含めることで、アプリケーションまたはサービスを認証します。

1. 新しいIAM APIキーを作成する

   • IBM Cloud UI で IAM API キーを作成するには、 UI でのユーザー API キーの作成を参照してください。
   • IBM Cloud CLI で IAM API キーを作成するには、以下のコマンドを使用する：

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

詳細については、 ユーザーAPIキーの管理を参照してください

2. を作成する。 IBM Cloud Secrets Manager

   モデル・ゲートウェイを使用するには、インスタンスのプロビジョニングとリンクを行います。 IBM Secrets Manager インスタンスを作成します。

• UIを使用して設定するには、 UIで Secrets Manager インスタンスを作成するを参照してください。

• CLIを使用して設定するには、以下のコマンドを使用します。
  <region> を に置き換える。 ca-tor <plan> を以下の料金プランIDのいずれかに置き換えてください：
  • 裁判だ： 869c191a-3c2a-4faf-98be-18d48f95ba1f
  • スタンダードプラン ： 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.

詳細については、 CLIから Secrets Manager インスタンスを作成するを参照してください。

3. 認可する Secrets Manager

   認証する前に、 Secrets Manager インスタンスで SecretsReader サービス・ロール以上を持っていることを確認してください。 詳細については、 IBM Cloud サービスが Secrets Manager にアクセスすることを許可するを参照してください。

   • UIを使用して認証するには、 コンソールで認証を作成するを参照してください。
   • IBM Cloud CLIを使用して認証するには、以下のコマンドを使用できる：

  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

注： pm-20 は、 watsonx.ai ランタイムのサービス名である。

詳細については、「 認可を使用してサービス間のアクセスを許可する 」を参照してください。

これで、 IBM Cloud のモデルゲートウェイの有効なベアラートークンとして IBM_CLOUD_APIKEY を使用できるようになりました。

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

例

 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. アカウントにLLMプロバイダーを設定することができます。 各プロバイダーを設定するには、
   POST /v1/providers/<PROVIDER TYPE> にリクエストを送る。 リクエストの本文には

   • name - この LLM プロバイダ・クレデンシャルのカスタム・ユーザ定義識別子。 この識別子は何でも良いが、ユニークでなければならない。 このトピックの例では、各プロバイダー・タイプに "my-xxxx-provider" 。
   • data - プロバイダ接続を設定するために提供されるすべての設定引数が含まれる。 通常、 apiKey 。 プロバイダーによっては、追加の設定パラメーターを要求したり、オプションで提供したりする場合がある。

   このリクエストに対する応答は、プロバイダーのUUIDを含む。このUUIDは、 プロバイダー上でモデルを有効にするために、後のステップで使用するために記録して おくべきである。

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

各プロバイダーの詳細と例については、「 LLMプロバイダーの選択 」を参照。

3. 設定されたモデル・プロバイダの情報を取得するには、 GET /v1/providers にクレデンシャル名を指定して呼び出す。

   以下の例では、レスポンスからUUIDを環境変数にエクスポートすることで、 my-openai-provider OpenAI プロバイダーのUUIDを取得する例を示している。 プロバイダーのUUIDは、次のステップでモデルを有効にするために使用される。

  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. モデルプロバイダーが追加された後、プロバイダーのUUIDで POST /v1/providers/{provider_id}/models 、リクエストにモデルのIDを与えることで、そのプロバイダーを通して使いたいモデルを有効にすることができます。 モデルIDは、LLMプロバイダが知っているモデルの既存の一意識別子でなければならない。 多くの場合、モデルは複数のプロバイダーから提供されています。モデルエイリアスは、IDの代わりにモデルを識別するために使用できる、ユーザー定義のカスタム名です。 例については、「 LLMプロバイダーの実現モデル 」を参照のこと。

LLMプロバイダーの選択

このモデル・ゲートウェイは、 OpenAI-compatible のエンドポイントをサポートするプロバイダーであれば、どのプロバイダーでも使用することができる：

1. OpenAI をプロバイダーとして選択
2. base_urlを新しいurlに置き換える

例

Gemini の OpenAI-compatible エンドポイントをプロビジョニングするには、以下のコマンドを使用する：

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 は、以下のLLMプロバイダー・タイプのみを認証する：

• OpenAI
• IBM watsonx.ai
• Azure OpenAI
• アンソロピック
• AWS 岩盤
• セレブラ
• NVIDIA エヌアイエム

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

LLMプロバイダーのためのモデル

以下の例は、プロバイダーがモデルを有効にする方法を示している：

ユーザーの OpenAI's GPT-4o モデル 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"}'

AnthropicのClaude 3.7 Sonnetモデルを、ユーザーの AWS Bedrockプロバイダーに対して有効にする：

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

掲載プロバイダーとモデル

設定したプロバイダーとモデルの両方をリストアップできます。 以下は、設定されているすべてのプロバイダー、指定されたプロバイダーのすべてのモデル、および設定されているプロバイダー全体のすべてのモデルを一覧表示する例です。

設定されているすべてのモデル・プロバイダの一覧を表示するには、以下のコマンドを使用する：

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

設定されている Azure OpenAI プロバイダーで有効になっているすべてのモデルを一覧表示するには、以下のコマンドを使用します：

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

有効になっているすべてのモデル（設定されているすべてのプロバイダーにわたって）を一覧表示するには、以下のコマンドを使用する：

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

例

チャット完了 /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?"
      }
    ]
  }'

テキスト補完／生成 /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
  }'

エンベッディング生成 /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)