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로 작업하려면 API 요청에 IBM Cloud IAM 액세스 토큰을 포함하여 애플리케이션 또는 서비스를 인증하세요.

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": "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
• Anthropic
• AWS 암반
• 뇌
• 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}}')"

LLM 제공업체를 위한 모델 활성화

다음 예는 제공업체를 위한 모델을 활성화하는 방법을 보여줍니다:

사용자의 Azure OpenAI 공급자에 대해 OpenAI's GPT-4o 모델 활성화

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

사용자의 AWS 베드락 공급자에 대해 Anthropic의 클로드 3.7 소네트 모델을 사용하도록 설정합니다:

  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)