이 페이지는 Cloud Translation API를 통해 번역되었습니다.

예

이 가이드에서는 Gemini 모델과 함께 OpenAI 호환 Chat Completions API를 사용하는 방법을 예시와 함께 설명하며 다음 주제를 다룹니다.

Chat Completions API로 Gemini 호출: 관리형 Gemini 모델에 스트리밍 및 비스트리밍 요청을 보내는 방법을 보여줍니다.
Chat Completions API로 자체 배포된 모델 호출: 자체 배포된 모델에 요청을 보내는 예를 제공합니다.
extra_body 예시: 요청에서 Google 관련 추가 매개변수를 전달하는 방법을 설명합니다.
extra_content 예시: 메시지 또는 도구 호출에 추가 콘텐츠를 추가하는 방법을 보여줍니다.
샘플 curl 요청: 멀티모달 입력과 같은 고급 사용 사례를 위한 직접 curl 예시를 제공합니다.
구조화된 출력: 모델에서 구조화된 JSON 출력을 요청하는 방법을 보여줍니다.

Chat Completions API는 다음 두 가지 방법으로 호출할 수 있습니다.

메서드	설명	사용 사례
관리형 Gemini 모델 호출	특정 Gemini 모델의 Google 관리형 엔드포인트에 요청을 전송합니다.	일반적인 사용 사례, 빠른 설정, 인프라 관리 없이 최신 Google 모델에 액세스하는 데 적합합니다.
자체 배포 모델 호출	Vertex AI에 모델을 배포하여 만든 엔드포인트에 요청을 보냅니다.	미세 조정된 모델을 위한 전용 엔드포인트가 필요하거나 기본 엔드포인트에서 사용할 수 없는 특정 구성이 필요한 경우에 적합합니다.

Chat Completions API로 Gemini 호출

비스트리밍 또는 스트리밍으로 요청을 보낼 수 있습니다.

요청 유형	설명	장점	단점
비스트리밍	전체 응답이 생성된 후 단일 청크로 다시 전송됩니다.	구현이 더 간단하며 전체 응답을 한 번에 사용할 수 있습니다.	사용자가 전체 응답이 생성될 때까지 기다리므로 인지된 지연 시간이 더 깁니다.
스트리밍	응답은 생성되는 대로 작은 청크로 다시 전송됩니다. 스트리밍을 사용 설정하려면 요청 본문에서 `"stream": true`을 설정하세요.	인지된 지연 시간이 짧아집니다. 대답이 점진적으로 표시되므로 더 상호작용적인 환경을 제공합니다.	수신되는 데이터 스트림을 처리하기 위해 더 복잡한 클라이언트 측 로직이 필요합니다.

스트리밍이 아닌 요청 보내기

다음 샘플은 비스트리밍 요청을 보내는 방법을 보여줍니다.

REST

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/endpoints/openapi/chat/completions \
  -d '{
    "model": "google/${MODEL_ID}",
    "messages": [{
      "role": "user",
      "content": "Write a story about a magic backpack."
    }]
  }'

Python

이 샘플을 사용해 보기 전에 Vertex AI 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 Vertex AI Python API 참고 문서를 참조하세요.

Vertex AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

from google.auth import default
import google.auth.transport.requests

import openai

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# location = "us-central1"

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
credentials.refresh(google.auth.transport.requests.Request())

# OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/openapi",
    api_key=credentials.token,
)

response = client.chat.completions.create(
    model="google/gemini-2.0-flash-001",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
)

print(response)

스트리밍 요청 보내기

다음 샘플은 "stream": true를 설정하여 스트리밍 요청을 보내는 방법을 보여줍니다.

REST

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/endpoints/openapi/chat/completions \
  -d '{
    "model": "google/${MODEL_ID}",
    "stream": true,
    "messages": [{
      "role": "user",
      "content": "Write a story about a magic backpack."
    }]
  }'

Python

Vertex AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

from google.auth import default
import google.auth.transport.requests

import openai

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# location = "us-central1"

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
credentials.refresh(google.auth.transport.requests.Request())

# OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/openapi",
    api_key=credentials.token,
)

response = client.chat.completions.create(
    model="google/gemini-2.0-flash-001",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
    stream=True,
)
for chunk in response:
    print(chunk)

Vertex AI의 Gemini API에 프롬프트와 이미지 보내기

다음 샘플은 텍스트와 이미지가 포함된 멀티모달 요청을 전송하는 방법을 보여줍니다.

Python

Vertex AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.


from google.auth import default
import google.auth.transport.requests

import openai

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# location = "us-central1"

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
credentials.refresh(google.auth.transport.requests.Request())

# OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/openapi",
    api_key=credentials.token,
)

response = client.chat.completions.create(
    model="google/gemini-2.0-flash-001",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe the following image:"},
                {
                    "type": "image_url",
                    "image_url": "gs://cloud-samples-data/generative-ai/image/scones.jpg",
                },
            ],
        }
    ],
)

print(response)

Chat Completions API로 자체 배포된 모델 호출

스트리밍이 아닌 요청 보내기

다음 샘플은 자체 배포 모델에 비스트리밍 요청을 보내는 방법을 보여줍니다.

REST

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/endpoints/${ENDPOINT}/chat/completions \
  -d '{
    "messages": [{
      "role": "user",
      "content": "Write a story about a magic backpack."
    }]
  }'

Python

Vertex AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

from google.auth import default
import google.auth.transport.requests

import openai

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# location = "us-central1"
# model_id = "gemma-2-9b-it"
# endpoint_id = "YOUR_ENDPOINT_ID"

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
credentials.refresh(google.auth.transport.requests.Request())

# OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/{endpoint_id}",
    api_key=credentials.token,
)

response = client.chat.completions.create(
    model=model_id,
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
)
print(response)

스트리밍 요청 보내기

다음 샘플은 자체 배포 모델에 스트리밍 요청을 보내는 방법을 보여줍니다.

REST

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
    https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/endpoints/${ENDPOINT}/chat/completions \
    -d '{
      "stream": true,
      "messages": [{
        "role": "user",
        "content": "Write a story about a magic backpack."
      }]
    }'

Python

Vertex AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

from google.auth import default
import google.auth.transport.requests

import openai

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# location = "us-central1"
# model_id = "gemma-2-9b-it"
# endpoint_id = "YOUR_ENDPOINT_ID"

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
credentials.refresh(google.auth.transport.requests.Request())

# OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/{endpoint_id}",
    api_key=credentials.token,
)

response = client.chat.completions.create(
    model=model_id,
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
    stream=True,
)
for chunk in response:
    print(chunk)

`extra_body` 예시

extra_body 필드를 사용하여 요청에서 Google 관련 매개변수를 전달할 수 있습니다.

REST API: REST API를 사용하여 매개변수를 전달하려면 google 객체 내에 추가합니다.

{
  ...,
  "extra_body": {
     "google": {
       ...,
       "thought_tag_marker": "..."
     }
   }
}

Python SDK: Python SDK를 사용하여 매개변수를 전달하려면 extra_body 인수에 사전을 제공합니다.

client.chat.completions.create(
  ...,
  extra_body = {
    'extra_body': { 'google': { ... } }
  },
)

`extra_content` 예시

REST API와 함께 extra_content 필드를 사용하여 메시지 또는 도구 호출에 추가 정보를 추가할 수 있습니다.

문자열 content 필드 사용

{
  "messages": [
    { "role": "...", "content": "...", "extra_content": { "google": { ... } } }
  ]
}

멀티파트 content 필드의 메시지별

{
  "messages": [
    {
      "role": "...",
      "content": [
        { "type": "...", ..., "extra_content": { "google": { ... } } }
      ]
    }
}

도구 호출당

{
  "messages": [
    {
      "role": "...",
      "tool_calls": [
        {
          ...,
          "extra_content": { "google": { ... } }
        }
      ]
    }
  ]
}

샘플 `curl` 요청

이러한 curl 요청을 사용하여 SDK를 사용하지 않고 API와 직접 상호작용할 수 있습니다.

`extra_body`에서 `thinking_config` 사용하기

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/endpoints/openapi/chat/completions \
  -d '{ \
    "model": "google/gemini-2.5-flash-preview-04-17", \
    "messages": [ \
      { "role": "user", \
      "content": [ \
        { "type": "text", \
          "text": "Are there any primes number of the form n*ceil(log(n))" \
        }] }], \
    "extra_body": { \
      "google": { \
          "thinking_config": { \
          "include_thoughts": true, "thinking_budget": 10000 \
        }, \
        "thought_tag_marker": "think" } }, \
    "stream": true }'

멀티모달 요청

Chat Completions API는 오디오와 동영상을 비롯한 다양한 멀티모달 입력을 지원합니다.

`image_url`를 사용하여 이미지 데이터 전달

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT}/locations/us-central1/endpoints/openapi/chat/completions \
  -d '{ \
    "model": "google/gemini-2.0-flash-001", \
    "messages": [{ "role": "user", "content": [ \
      { "type": "text", "text": "Describe this image" }, \
      { "type": "image_url", "image_url": "gs://cloud-samples-data/generative-ai/image/scones.jpg" }] }] }'

`input_audio`로 오디오 데이터 전달

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT}/locations/us-central1/endpoints/openapi/chat/completions \
  -d '{ \
    "model": "google/gemini-2.0-flash-001", \
    "messages": [ \
      { "role": "user", \
        "content": [ \
          { "type": "text", "text": "Describe this: " }, \
          { "type": "input_audio", "input_audio": { \
            "format": "audio/mp3", \
            "data": "gs://cloud-samples-data/generative-ai/audio/pixel.mp3" } }] }] }'

구조화된 출력

response_format 매개변수를 사용하여 모델에서 구조화된 JSON 출력을 요청할 수 있습니다.

Python SDK를 사용한 예

from pydantic import BaseModel
from openai import OpenAI

client = OpenAI()

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

completion = client.beta.chat.completions.parse(
    model="google/gemini-2.5-flash-preview-04-17",
    messages=[
        {"role": "system", "content": "Extract the event information."},
        {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
    ],
    response_format=CalendarEvent,
)

print(completion.choices[0].message.parsed)

다음 단계

OpenAI 호환 구문으로 Inference API를 호출하는 방법을 알아봅니다.
OpenAI 호환 구문으로 Function Calling API를 호출하는 방법을 알아봅니다.
Gemini API 자세히 알아보기
Azure OpenAI에서 Gemini API로 마이그레이션에 대해 자세히 알아보기

예 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

Chat Completions API로 Gemini 호출

스트리밍이 아닌 요청 보내기

REST

Python

스트리밍 요청 보내기

REST

Python

Vertex AI의 Gemini API에 프롬프트와 이미지 보내기

Python

Chat Completions API로 자체 배포된 모델 호출

스트리밍이 아닌 요청 보내기

REST

Python

스트리밍 요청 보내기

REST

Python

extra_body 예시

extra_content 예시

샘플 curl 요청

extra_body에서 thinking_config 사용하기

멀티모달 요청

image_url를 사용하여 이미지 데이터 전달

input_audio로 오디오 데이터 전달

구조화된 출력

Python SDK를 사용한 예

다음 단계

예

`extra_body` 예시

`extra_content` 예시

샘플 `curl` 요청

`extra_body`에서 `thinking_config` 사용하기

`image_url`를 사용하여 이미지 데이터 전달

`input_audio`로 오디오 데이터 전달