Oracle Cloud Infrastructure

Oracle Cloud Infrastructure (OCI)

OCI의 온디맨드 GenAI API에서 LiteLLM이 지원하는 모델을 사용하는 방법을 알아봐요.

출처: 문서

본문

LiteLLM은 OCI 온디맨드 GenAI API의 다음 모델들을 지원해요.

리전에 모델이 있는지 OCI 모델 목록을 확인하세요.

지원 모델

모델 수명 주기, 폐기 날짜, 권장 대체 모델은 OCI의 온디맨드 모델 폐기 페이지를 참고해요. Oracle이 권위 있는 출처이에요.

채팅 / 텍스트 생성

Meta Llama 모델:

meta.llama-4-maverick-17b-128e-instruct-fp8 (multimodal)
meta.llama-4-scout-17b-16e-instruct (multimodal)
meta.llama-3.3-70b-instruct
meta.llama-3.3-70b-instruct-fp8-dynamic
meta.llama-3.2-90b-vision-instruct (multimodal)
meta.llama-3.2-11b-vision-instruct (multimodal)

xAI Grok 모델:

xai.grok-4.3
xai.grok-4.20
xai.grok-4.20-multi-agent
xai.grok-4
xai.grok-4-fast
xai.grok-4.1-fast
xai.grok-3
xai.grok-3-fast
xai.grok-3-mini
xai.grok-3-mini-fast
xai.grok-code-fast-1

Cohere 모델:

cohere.command-latest
cohere.command-a-03-2025
cohere.command-a-reasoning-08-2025
cohere.command-a-vision-07-2025 (multimodal)
cohere.command-a-translate-08-2025
cohere.command-plus-latest
cohere.command-r-plus-08-2024
cohere.command-r-08-2024

Google Gemini 모델 (OCI 경유):

google.gemini-2.5-pro (multimodal)
google.gemini-2.5-flash (multimodal)
google.gemini-2.5-flash-lite (multimodal)

OpenAI 오픈소스 모델 (OCI 경유):

openai.gpt-oss-120b
openai.gpt-oss-20b

임베딩 모델

cohere.embed-v4.0 (1536 차원, multimodal)
cohere.embed-english-v3.0 (1024 차원)
cohere.embed-english-light-v3.0 (384 차원)
cohere.embed-multilingual-v3.0 (1024 차원)
cohere.embed-multilingual-light-v3.0 (384 차원)
cohere.embed-english-image-v3.0 (1024 차원, multimodal)
cohere.embed-english-light-image-v3.0 (384 차원, multimodal)
cohere.embed-multilingual-image-v3.0 (1024 차원, multimodal)
cohere.embed-multilingual-light-image-v3.0 (384 차원, multimodal)

인증

LiteLLM은 OCI에 대해 두 가지 인증 방법을 지원해요.

방법 1: 수동 자격 증명

개별 OCI 자격 증명을 LiteLLM에 직접 제공해요. 공식 Oracle 튜토리얼을 따라 서명 키를 만들고 다음 파라미터를 얻으세요:

user
fingerprint
tenancy
region
key_file 또는 key
compartment_id

이것이 AI Gateway(LLM Proxy)의 OCI GenAI 모델 접근 기본 방법이에요.

환경 변수:

코드로 자격 증명을 전달하는 대신 환경 변수를 설정하면 LiteLLM이 자동으로 읽어요:

export OCI_REGION="us-chicago-1"
export OCI_USER="ocid1.user.oc1.."
export OCI_FINGERPRINT="xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
export OCI_TENANCY="ocid1.tenancy.oc1.."
export OCI_COMPARTMENT_ID="ocid1.compartment.oc1.."
# Provide either the private key content OR the path to the key file:
export OCI_KEY_FILE="/path/to/oci_api_key.pem"
# export OCI_KEY="-----BEGIN PRIVATE KEY-----\n..."

방법 2: OCI SDK Signer

인증을 위해 OCI SDK Signer 객체를 사용해요. 이 방법은:

공식 OCI SDK로 서명
추가 인증 방법 지원 (인스턴스 프린시펄, 워크로드 아이덴티티 등)

설치:

uv add oci

이 방법은 Oracle Cloud Infrastructure(인스턴스 또는 Oracle Kubernetes Engine)에서 LiteLLM SDK를 사용할 때의 대안이에요.

사용법

수동 자격 증명:

from litellm import completion

messages = [{"role": "user", "content": "Hey! how's it going?"}]
response = completion(
    model="oci/xai.grok-4",
    messages=messages,
    oci_region="",
    oci_user="",
    oci_fingerprint="",
    oci_tenancy="",
    oci_serving_mode="ON_DEMAND",  # Optional, default is "ON_DEMAND". Other option is "DEDICATED"
    # Provide either the private key string OR the path to the key file:
    # Option 1: pass the private key as a string
    oci_key="",
    # Option 2: pass the private key file path
    # oci_key_file="",
    oci_compartment_id="",
)
print(response)

OCI SDK Signer:

from litellm import completion
from oci.signer import Signer

# Create an OCI Signer
signer = Signer(
    tenancy="ocid1.tenancy.oc1..",
    user="ocid1.user.oc1..",
    fingerprint="xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx",
    private_key_file_location="~/.oci/key.pem",
    # Or use private_key_content=""
)

messages = [{"role": "user", "content": "Hey! how's it going?"}]
response = completion(
    model="oci/xai.grok-4",
    messages=messages,
    oci_signer=signer,
    oci_region="us-chicago-1",  # Optional, defaults to us-ashburn-1
    oci_serving_mode="ON_DEMAND",  # Optional, default is "ON_DEMAND". Other option is "DEDICATED"
    oci_compartment_id="",
)
print(response)

OCI 설정 파일 사용: OCI SDK가 ~/.oci/config에서 자동으로 자격 증명을 불러올 수 있어요:

from litellm import completion
from oci.config import from_file
from oci.signer import Signer

# Load config from file
config = from_file("~/.oci/config", "DEFAULT")  # "DEFAULT" is the profile name
signer = Signer(
    tenancy=config["tenancy"],
    user=config["user"],
    fingerprint=config["fingerprint"],
    private_key_file_location=config["key_file"],
    pass_phrase=config.get("pass_phrase")  # Optional if key is encrypted
)

messages = [{"role": "user", "content": "Hey! how's it going?"}]
response = completion(
    model="oci/xai.grok-4",
    messages=messages,
    oci_signer=signer,
    oci_region=config["region"],
    oci_compartment_id="",
)
print(response)

인스턴스 프린시펄 인증 (OCI 컴퓨트 인스턴스에서 실행되는 애플리케이션):

from litellm import completion
from oci.auth.signers import InstancePrincipalsSecurityTokenSigner

# Use instance principal authentication
signer = InstancePrincipalsSecurityTokenSigner()

messages = [{"role": "user", "content": "Hey! how's it going?"}]
response = completion(
    model="oci/xai.grok-4",
    messages=messages,
    oci_signer=signer,
    oci_region="us-chicago-1",
    oci_compartment_id="",
)
print(response)

워크로드 아이덴티티 인증 (Oracle Kubernetes Engine(OKE)에서 실행되는 애플리케이션):

from litellm import completion
from oci.auth.signers import get_oke_workload_identity_resource_principal_signer

# Use workload identity authentication
signer = get_oke_workload_identity_resource_principal_signer()

messages = [{"role": "user", "content": "Hey! how's it going?"}]
response = completion(
    model="oci/xai.grok-4",
    messages=messages,
    oci_signer=signer,
    oci_region="us-chicago-1",
    oci_compartment_id="",
)
print(response)

LiteLLM Proxy 사용법

1. config.yaml 설정

model_list:
  - model_name: oci-grok-4
    litellm_params:
      model: oci/xai.grok-4
      oci_region: os.environ/OCI_REGION
      oci_user: os.environ/OCI_USER
      oci_fingerprint: os.environ/OCI_FINGERPRINT
      oci_tenancy: os.environ/OCI_TENANCY
      oci_key_file: os.environ/OCI_KEY_FILE
      oci_compartment_id: os.environ/OCI_COMPARTMENT_ID

  - model_name: oci-cohere-command
    litellm_params:
      model: oci/cohere.command-latest
      oci_region: os.environ/OCI_REGION
      oci_user: os.environ/OCI_USER
      oci_fingerprint: os.environ/OCI_FINGERPRINT
      oci_tenancy: os.environ/OCI_TENANCY
      oci_key_file: os.environ/OCI_KEY_FILE
      oci_compartment_id: os.environ/OCI_COMPARTMENT_ID

가능한 모든 인증 파라미터:

oci_region: Optional[str],
oci_user: Optional[str],
oci_fingerprint: Optional[str],
oci_tenancy: Optional[str],
oci_key: Optional[str],          # private key content as string
oci_key_file: Optional[str],     # path to .pem file
oci_compartment_id: Optional[str],
oci_serving_mode: Optional[str], # "ON_DEMAND" (default) or "DEDICATED"
oci_endpoint_id: Optional[str],  # only used with DEDICATED

2. Proxy 시작

litellm --config /path/to/config.yaml

3. 테스트

curl --location 'http://0.0.0.0:4000/chat/completions' \
--header 'Content-Type: application/json' \
--data '{
  "model": "oci-grok-4",
  "messages": [
    {"role": "user", "content": "what llm are you"}
  ]
}'

import openai

client = openai.OpenAI(
    api_key="anything",
    base_url="http://0.0.0.0:4000"
)

response = client.chat.completions.create(
    model="oci-grok-4",
    messages=[{"role": "user", "content": "write a short poem"}],
)
print(response)

사용법 - 스트리밍

completion 호출 시 stream=True만 설정하면 돼요.

from litellm import completion

messages = [{"role": "user", "content": "Hey! how's it going?"}]
response = completion(
    model="oci/xai.grok-4",
    messages=messages,
    stream=True,
    oci_region="",
    oci_user="",
    oci_fingerprint="",
    oci_tenancy="",
    oci_serving_mode="ON_DEMAND",  # Optional, default is "ON_DEMAND". Other option is "DEDICATED"
    oci_key="",
    oci_compartment_id="",
)
for chunk in response:
    print(chunk["choices"][0]["delta"]["content"])  # same as openai format

전용 엔드포인트 사용

OCI는 모델 호스팅을 위한 전용 엔드포인트를 지원해요. oci_serving_mode="DEDICATED" 파라미터와 함께 oci_endpoint_id로 엔드포인트 ID를 지정해요.

from litellm import completion

messages = [{"role": "user", "content": "Hey! how's it going?"}]
response = completion(
    model="oci/xai.grok-4",  # Must match the model type hosted on the endpoint
    messages=messages,
    oci_region="",
    oci_user="",
    oci_fingerprint="",
    oci_tenancy="",
    oci_serving_mode="DEDICATED",
    oci_endpoint_id="ocid1.generativeaiendpoint.oc1...",  # Your dedicated endpoint OCID
    oci_key="",
    oci_compartment_id="",
)
print(response)

중요: oci_serving_mode="DEDICATED" 사용 시:

model 파라미터는 전용 엔드포인트에 호스팅된 모델 유형과 일치해야 함 (예: Cohere 모델은 "oci/cohere.command-latest", Grok 모델은 "oci/xai.grok-4")
모델 이름이 API 형식과 제공사별 처리(Cohere vs Generic)를 결정
oci_endpoint_id 파라미터가 전용 엔드포인트의 OCID를 지정
oci_endpoint_id가 없으면 model 파라미터가 엔드포인트 ID로 사용됨 (하위 호환용)

사용법 - 함수 호출 / 도구 호출

OCI GenAI는 OpenAI 호환 함수 호출을 지원해요. LiteLLM이 요청·응답 형태를 정규화하므로 OpenAI를 대상으로 하는 동일한 코드가 OCI Cohere 및 Generic(xAI Grok, Meta Llama, Google Gemini) 모델에서 동작해요.

from litellm import completion

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "Get the current weather in a given location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["location"],
            },
        },
    }
]

response = completion(
    model="oci/xai.grok-4",
    messages=[{"role": "user", "content": "What's the weather in Boston today?"}],
    tools=tools,
    tool_choice="auto",
    oci_region="us-chicago-1",
    oci_user="",
    oci_fingerprint="",
    oci_tenancy="",
    oci_key_file="",
    oci_compartment_id="",
)

# Inspect the tool call
print(response.choices[0].message.tool_calls)

도구 호출은 Cohere(cohere.command-*)와 Generic(xai.grok-*, meta.llama-*, google.gemini-*) 모델 패밀리 모두에서 동작해요. LiteLLM은 내부적으로 OpenAI 도구 스키마를 각 제공사의 네이티브 형식에 맞춥니다.

사용법 - 비전 / 멀티모달

OCI GenAI가 텍스트와 함께 이미지를 받는 비전 가능 모델을 노출해요. 표준 OpenAI image_url 콘텐츠 블록으로 이미지를 전달해요.

from litellm import completion

response = completion(
    model="oci/meta.llama-4-maverick-17b-128e-instruct-fp8",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What is in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
                    },
                },
            ],
        }
    ],
    oci_region="us-chicago-1",
    oci_user="",
    oci_fingerprint="",
    oci_tenancy="",
    oci_key_file="",
    oci_compartment_id="",
)
print(response.choices[0].message.content)

OCI의 비전 가능 모델:

meta.llama-4-maverick-17b-128e-instruct-fp8
meta.llama-4-scout-17b-16e-instruct
meta.llama-3.2-11b-vision-instruct
meta.llama-3.2-90b-vision-instruct
cohere.command-a-vision-07-2025
google.gemini-2.5-pro, google.gemini-2.5-flash, google.gemini-2.5-flash-lite

URL과 base64 인코딩 data URI 모두 지원돼요.

사용법 - 추론 / Thinking

OCI Generic-vendor 모델(xAI Grok 추론 변형, Google Gemini 등)은 추론 단계를 지원해요. LiteLLM은 OpenAI 호환 reasoning_effort 파라미터로 이를 노출하며, 허용 값은 "low", "medium", "high", "disable"(OCI의 NONE에 매핑)이에요.

반환된 추론 토큰은 usage.completion_tokens_details.reasoning_tokens에서 확인할 수 있으며, OpenAI 형태와 일치해요.

from litellm import completion

response = completion(
    model="oci/xai.grok-3-mini",
    messages=[{"role": "user", "content": "If 3x + 7 = 22, what is x? Show your reasoning."}],
    reasoning_effort="high",  # "low" | "medium" | "high" | "disable"
    oci_region="us-chicago-1",
    oci_user="",
    oci_fingerprint="",
    oci_tenancy="",
    oci_key_file="",
    oci_compartment_id="",
)

print(response.choices[0].message.content)
print("Reasoning tokens:", response.usage.completion_tokens_details.reasoning_tokens)

note: reasoning_effort는 Generic-vendor 추론 모델(예: xai.grok-3-mini, xai.grok-4, google.gemini-2.5-pro)에서만 적용돼요. 추론 모델이 아닌 OCI Cohere 모델에서는 조용히 무시돼요.

선택 파라미터

파라미터	타입	기본값	환경 변수	설명
`oci_region`	string	`us-ashburn-1`	`OCI_REGION`	GenAI 서비스가 배포된 OCI 리전
`oci_serving_mode`	string	`ON_DEMAND`	–	서비스 모드: 관리형 모델은 `ON_DEMAND`, 전용 엔드포인트는 `DEDICATED`
`oci_endpoint_id`	string	`model`과 동일	–	(DEDICATED 모드) 전용 엔드포인트의 OCID
`oci_compartment_id`	string	필수	`OCI_COMPARTMENT_ID`	리소스를 담은 OCI 컴파트먼트의 OCID
`oci_user`	string	–	`OCI_USER`	(Manual auth) OCI 사용자의 OCID
`oci_fingerprint`	string	–	`OCI_FINGERPRINT`	(Manual auth) API 서명 키의 지문
`oci_tenancy`	string	–	`OCI_TENANCY`	(Manual auth) OCI 테넌시의 OCID
`oci_key`	string	–	`OCI_KEY`	(Manual auth) 개인 키 콘텐츠(문자열)
`oci_key_file`	string	–	`OCI_KEY_FILE`	(Manual auth) 개인 키 파일 경로
`oci_signer`	object	–	–	(SDK auth) 인증용 OCI SDK Signer 객체
`reasoning_effort`	string	–	–	Generic-vendor 추론 모델의 추론 수준: `low`, `medium`, `high`, `disable`

임베딩

LiteLLM은 OCI Generative AI 임베딩 모델을 지원해요. 위에서 설명한 것과 동일한 인증 방법을 사용해요.

from litellm import embedding

response = embedding(
    model="oci/cohere.embed-english-v3.0",
    input=["Hello world", "Goodbye world"],
    oci_region="us-ashburn-1",
    oci_user="",
    oci_fingerprint="",
    oci_tenancy="",
    oci_key="",
    oci_compartment_id="",
)
print(response)

임베딩 선택 파라미터

파라미터	타입	기본값	설명
`input_type`	string	–	입력 타입: `search_document`, `search_query`, `classification`, `clustering`
`truncate`	string	`END`	입력이 최대 토큰을 초과할 때 잘라내기 전략: `END` 또는 `START`

전용 임베딩 엔드포인트 사용

response = embedding(
    model="oci/cohere.embed-english-v3.0",
    input=["Hello world"],
    oci_serving_mode="DEDICATED",
    oci_endpoint_id="ocid1.generativeaiendpoint.oc1...",
    oci_region="us-ashburn-1",
    oci_compartment_id="",
    # ... auth params
)

더 알아보기 (Learn more)

OCI GenAI 공식 문서
OCI 온디맨드 모델 목록