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

개방형 모델의 MaaS API 호출

Vertex AI의 많은 개방형 모델은 Vertex AI Chat Completions API를 사용하여 완전 관리형 서버리스 모델을 API로 제공합니다. 이러한 모델의 경우 인프라를 프로비저닝하거나 관리할 필요가 없습니다.

대답을 스트리밍하여 최종 사용자의 지연 시간 인식을 줄일 수 있습니다. 스트리밍된 응답은 서버 전송 이벤트(SSE)를 사용하여 응답을 점진적으로 스트리밍합니다.

이 페이지에서는 OpenAI Chat Completions API를 지원하는 공개 모델에 스트리밍 및 비스트리밍 호출을 하는 방법을 보여줍니다. Llama 관련 고려사항은 Llama 예측 요청을 참고하세요.

시작하기 전에

Vertex AI에서 개방형 모델을 사용하려면 다음 단계를 실행해야 합니다. Vertex AI를 사용하려면 Vertex AI API(aiplatform.googleapis.com)를 사용 설정해야 합니다. Vertex AI API가 사용 설정된 기존 프로젝트가 이미 있는 경우 새 프로젝트를 만드는 대신 해당 프로젝트를 사용할 수 있습니다.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

사용하려는 모델의 Model Garden 모델 카드로 이동한 다음 사용 설정을 클릭하여 프로젝트에서 사용할 모델을 사용 설정합니다.
Model Garden으로 이동

개방형 모델에 스트리밍 호출 수행

다음 샘플은 오픈 모델을 스트리밍 호출합니다.

Python

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

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

이 샘플을 실행하기 전에 OPENAI_BASE_URL 환경 변수를 설정해야 합니다. 자세한 내용은 인증 및 사용자 인증 정보를 참고하세요.

from openai import OpenAI
client = OpenAI()

stream = client.chat.completions.create(
    model="MODEL",
    messages=[{"role": "ROLE", "content": "CONTENT"}],
    max_tokens=MAX_OUTPUT_TOKENS,
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

MODEL: 사용할 모델 이름(예: deepseek-ai/deepseek-v3.1-maas)
ROLE: 메시지와 연결된 역할. user 또는 assistant를 지정할 수 있습니다. 첫 번째 메시지는 user 역할을 사용해야 합니다. 모델이 user와 assistant의 턴을 번갈아가며 작동합니다. 최종 메시지에서 assistant 역할을 사용하는 경우 이 메시지의 콘텐츠에서 곧바로 대답 콘텐츠가 계속됩니다. 이를 사용하여 모델 대답의 일부를 제한할 수 있습니다.
CONTENT: user 또는 assistant 메시지의 콘텐츠(예: 텍스트).
MAX_OUTPUT_TOKENS: 대답에서 생성될 수 있는 토큰의 최대 개수. 토큰은 약 4자(영문 기준)입니다. 토큰 100개는 단어 약 60~80개에 해당합니다.
응답이 짧을수록 낮은 값을 지정하고 잠재적으로 응답이 길면 높은 값을 지정합니다.

REST

환경을 설정하면 REST를 사용하여 텍스트 프롬프트를 테스트할 수 있습니다. 다음 샘플은 요청을 게시자 모델 엔드포인트에 전송합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

LOCATION: 개방형 모델을 지원하는 리전입니다.
MODEL: 사용할 모델 이름(예: deepseek-ai/deepseek-v2)
ROLE: 메시지와 연결된 역할. user 또는 assistant를 지정할 수 있습니다. 첫 번째 메시지는 user 역할을 사용해야 합니다. 모델이 user와 assistant의 턴을 번갈아가며 작동합니다. 최종 메시지에서 assistant 역할을 사용하는 경우 이 메시지의 콘텐츠에서 곧바로 대답 콘텐츠가 계속됩니다. 이를 사용하여 모델 대답의 일부를 제한할 수 있습니다.
CONTENT: user 또는 assistant 메시지의 콘텐츠(예: 텍스트).
MAX_OUTPUT_TOKENS: 대답에서 생성될 수 있는 토큰의 최대 개수. 토큰은 약 4자(영문 기준)입니다. 토큰 100개는 단어 약 60~80개에 해당합니다.
응답이 짧을수록 낮은 값을 지정하고 잠재적으로 응답이 길면 높은 값을 지정합니다.
STREAM: 대답 스트리밍 여부를 지정하는 불리언. 응답을 스트리밍하여 최종 사용자 지연 시간 인식을 줄입니다. 대답을 스트리밍하려면 true로 설정하고 대답을 한 번에 반환하려면 false로 설정합니다.

HTTP 메서드 및 URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions

JSON 요청 본문:

{
  "model": "MODEL",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_OUTPUT_TOKENS,
  "stream": true
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions"

PowerShell

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 수신됩니다.

응답

data: {
  "choices": [
    {
      "delta": {
        "content": "CONTENT",
        "role": "assistant"
      },
      "index": 0,
      "logprobs": null
    }
  ],
  "created": 1234567890,
  "id": "2025-06-11|10:00:00.292195-07|9.7.144.202|-123456789",
  "model": "MODEL",
  "object": "chat.completion.chunk",
  "system_fingerprint": ""
}

data: {
  "choices": [
    {
      "delta": {
        "content": "CONTENT",
        "role": "assistant"
      },
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null
    }
  ],
  "created": 1234567890,
  "id": "2025-06-11|10:00:00.292195-07|9.7.144.202|-123456789",
  "model": "MODEL",
  "object": "chat.completion.chunk",
  "system_fingerprint": "",
  "usage": {
    "completion_tokens": 131,
    "prompt_tokens": 14,
    "total_tokens": 145
  }
}

data: [DONE]

개방형 모델에 비스트리밍 호출 수행

다음 샘플은 공개 모델을 비스트리밍 방식으로 호출합니다.

Python

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

이 샘플을 실행하기 전에 OPENAI_BASE_URL 환경 변수를 설정해야 합니다. 자세한 내용은 인증 및 사용자 인증 정보를 참고하세요.

from openai import OpenAI
client = OpenAI()

completion = client.chat.completions.create(
    model="MODEL",
    messages=[{"role": "ROLE", "content": "CONTENT"}],
    max_tokens=MAX_OUTPUT_TOKENS,
    stream=False,
)
print(completion.choices[0].message)

MODEL: 사용할 모델 이름(예: deepseek-ai/deepseek-v3.1-maas)
ROLE: 메시지와 연결된 역할. user 또는 assistant를 지정할 수 있습니다. 첫 번째 메시지는 user 역할을 사용해야 합니다. 모델이 user와 assistant의 턴을 번갈아가며 작동합니다. 최종 메시지에서 assistant 역할을 사용하는 경우 이 메시지의 콘텐츠에서 곧바로 대답 콘텐츠가 계속됩니다. 이를 사용하여 모델 대답의 일부를 제한할 수 있습니다.
CONTENT: user 또는 assistant 메시지의 콘텐츠(예: 텍스트).
MAX_OUTPUT_TOKENS: 대답에서 생성될 수 있는 토큰의 최대 개수. 토큰은 약 4자(영문 기준)입니다. 토큰 100개는 단어 약 60~80개에 해당합니다.
응답이 짧을수록 낮은 값을 지정하고 잠재적으로 응답이 길면 높은 값을 지정합니다.

REST

환경을 설정하면 REST를 사용하여 텍스트 프롬프트를 테스트할 수 있습니다. 다음 샘플은 요청을 게시자 모델 엔드포인트에 전송합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

LOCATION: 개방형 모델을 지원하는 리전입니다.
MODEL: 사용할 모델 이름(예: deepseek-ai/deepseek-v2)
ROLE: 메시지와 연결된 역할. user 또는 assistant를 지정할 수 있습니다. 첫 번째 메시지는 user 역할을 사용해야 합니다. 모델이 user와 assistant의 턴을 번갈아가며 작동합니다. 최종 메시지에서 assistant 역할을 사용하는 경우 이 메시지의 콘텐츠에서 곧바로 대답 콘텐츠가 계속됩니다. 이를 사용하여 모델 대답의 일부를 제한할 수 있습니다.
CONTENT: user 또는 assistant 메시지의 콘텐츠(예: 텍스트).
MAX_OUTPUT_TOKENS: 대답에서 생성될 수 있는 토큰의 최대 개수. 토큰은 약 4자(영문 기준)입니다. 토큰 100개는 단어 약 60~80개에 해당합니다.
응답이 짧을수록 낮은 값을 지정하고 잠재적으로 응답이 길면 높은 값을 지정합니다.
STREAM: 대답 스트리밍 여부를 지정하는 불리언. 응답을 스트리밍하여 최종 사용자 지연 시간 인식을 줄입니다. 대답을 스트리밍하려면 true로 설정하고 대답을 한 번에 반환하려면 false로 설정합니다.

HTTP 메서드 및 URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions

JSON 요청 본문:

{
  "model": "MODEL",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_OUTPUT_TOKENS,
  "stream": false
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 수신됩니다.

응답

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "CONTENT",
        "role": "assistant"
      }
    }
  ],
  "created": 1234567890,
  "id": "2025-06-11|10:00:00.292195-07|9.7.144.202|-123456789",
  "model": "MODEL",
  "object": "chat.completion",
  "system_fingerprint": "",
  "usage": {
    "completion_tokens": 367,
    "prompt_tokens": 14,
    "total_tokens": 381
  }
}

리전 및 전역 엔드포인트

리전 엔드포인트의 경우 요청은 지정된 리전에서 처리됩니다. 데이터 상주 요구사항이 있거나 모델이 전역 엔드포인트를 지원하지 않는 경우 리전 엔드포인트를 사용하세요.

전역 엔드포인트를 사용하면 사용 중인 모델이 지원하는 모든 리전에서 요청을 처리하고 제공할 수 있습니다. 이로 인해 경우에 따라 지연 시간이 길어질 수 있습니다. 전역 엔드포인트는 전반적인 가용성을 개선하고 오류를 줄이는 데 도움이 됩니다.

전역 엔드포인트를 사용하는 경우 리전 엔드포인트 사용 가격과 차이가 없습니다. 하지만 전역 엔드포인트 할당량과 지원되는 모델 기능은 리전 엔드포인트와 다를 수 있습니다. 자세한 내용은 관련 서드 파티 모델 페이지를 참조하세요.

전역 엔드포인트 지정

전역 엔드포인트를 사용하려면 리전을 global로 설정합니다.

예를 들어 curl 명령어의 요청 URL은 다음 형식을 사용합니다. https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi

Vertex AI SDK의 경우 리전 엔드포인트가 기본값입니다. 전역 엔드포인트를 사용하려면 리전을 GLOBAL로 설정합니다.

전역 API 엔드포인트 사용 제한

리전 엔드포인트 사용을 강제하려면 constraints/gcp.restrictEndpointUsage 조직 정책 제약조건을 사용하여 전역 API 엔드포인트에 대한 요청을 차단하세요. 자세한 내용은 엔드포인트 사용 제한을 참조하세요.

다음 단계

함수 호출 사용 방법을 알아봅니다.
정형 출력에 대해 알아봅니다.
일괄 예측에 대해 알아봅니다.

개방형 모델의 MaaS API 호출 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

개방형 모델에 스트리밍 호출 수행

Python

REST

curl

PowerShell

응답

개방형 모델에 비스트리밍 호출 수행

Python

REST

curl

PowerShell

응답

리전 및 전역 엔드포인트

전역 엔드포인트 지정

전역 API 엔드포인트 사용 제한

다음 단계

개방형 모델의 MaaS API 호출