이 가이드에서는 Gemini 모델과 함께 OpenAI 호환 Chat Completions API를 사용하는 방법을 예시와 함께 설명하며 다음 주제를 다룹니다.
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."
}]
}'
스트리밍 요청 보내기
다음 샘플은 "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."
}]
}'
Vertex AI의 Gemini API에 프롬프트와 이미지 보내기
다음 샘플은 텍스트와 이미지가 포함된 멀티모달 요청을 전송하는 방법을 보여줍니다.
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."
}]
}'
스트리밍 요청 보내기
다음 샘플은 자체 배포 모델에 스트리밍 요청을 보내는 방법을 보여줍니다.
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."
}]
}'
extra_body 예시
extra_body 필드를 사용하여 요청에서 Google 관련 매개변수를 전달할 수 있습니다.
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" }] }] }'
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)
다음 단계
