코드 실행

Gemini API 코드 실행 기능을 통해 모델은 Python 코드를 생성 및 실행하고 최종 출력을 도출할 때까지 결과를 반복적으로 학습합니다. 이 코드 실행 기능을 사용하면 코드 기반 추론의 이점을 활용하며 텍스트 출력을 생성하는 애플리케이션을 빌드할 수 있습니다. 예를 들어 방정식을 풀거나 텍스트를 처리하는 애플리케이션에서 코드 실행을 사용할 수 있습니다.

Gemini API는 함수 호출과 유사하게 도구로서 코드 실행을 제공합니다. 코드 실행을 도구로 추가하면 모델은 이를 사용할 시점을 결정합니다.

코드 실행 환경에는 다음 라이브러리가 포함됩니다. 사용자의 고유 라이브러리는 설치할 수 없습니다.

지원되는 모델

다음 모델은 코드 실행 지원을 제공합니다.

코드 실행 시작하기

이 섹션에서는 Gemini API 빠른 시작에 표시된 설정 및 구성 단계를 완료했다고 가정합니다.

모델에서 코드 실행 사용 설정

여기에 표시된 것처럼 기본 코드 실행을 사용 설정할 수 있습니다.

REST

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

GENERATE_RESPONSE_METHOD: 모델에서 생성하려는 응답 유형입니다. 모델의 응답을 반환할 방법을 생성하는 메서드를 선택합니다.
- streamGenerateContent: 지연 시간에 대한 인식을 줄이기 위해 응답이 생성되는 동안 스트리밍됩니다.
- generateContent: 응답은 완전히 생성된 후에 반환됩니다.
LOCATION: 요청을 처리하는 리전입니다. 사용 가능한 옵션은 다음과 같습니다.
클릭하여 사용 가능한 리전의 일부 목록 펼치기
- us-central1
- us-west4
- northamerica-northeast1
- us-east4
- us-west1
- asia-northeast3
- asia-southeast1
- asia-northeast1
PROJECT_ID: 프로젝트 ID입니다.
MODEL_ID: 사용하려는 모델의 모델 ID입니다.
ROLE: 콘텐츠와 연결된 대화의 역할입니다. 싱글턴 사용 사례에서도 역할을 지정해야 합니다. 허용되는 값은 다음과 같습니다.
- USER: 전송한 콘텐츠를 지정합니다.
- MODEL: 모델의 응답을 지정합니다.
```
TEXT
```
프롬프트에 포함할 텍스트 요청 사항입니다.

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

curl

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

요청 본문을 request.json 파일에 저장합니다. 터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.

cat > request.json << 'EOF'
{
  "tools": [{'codeExecution': {}}],
  "contents": {
    "role": "ROLE",
    "parts": { "text": "TEXT" }
  },
}
EOF

그런 후 다음 명령어를 실행하여 REST 요청을 전송합니다.

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/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD"

PowerShell

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

요청 본문을 request.json 파일에 저장합니다. 터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.

@'
{
  "tools": [{'codeExecution': {}}],
  "contents": {
    "role": "ROLE",
    "parts": { "text": "TEXT" }
  },
}
'@  | Out-File -FilePath request.json -Encoding utf8

그런 후 다음 명령어를 실행하여 REST 요청을 전송합니다.

$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/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content

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

응답

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Okay, I understand. You want me to calculate the sum of the first 10 positive integers and to use code to do so. Here's my plan: I will use a loop to add the numbers from 1 to 10 and then return the final sum.\n\n"
          },
          {
            "executableCode": {
              "language": "PYTHON",
              "code": "\ntotal = 0\nfor i in range(1, 11):\n    total += i\nprint(f'{total=}')\n"
            }
          },
          {
            "codeExecutionResult": {
              "outcome": "OUTCOME_OK",
              "output": "total=55\n"
            }
          },
          {
            "text": "The sum of the first 10 positive numbers is 55.\n"
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.19436789,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.17441037
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.0685376,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.14903527
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.23231025,
          "severity": "HARM_SEVERITY_LOW",
          "severityScore": 0.2436427
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.08269742,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.10818888
        }
      ],
      "score": -0.50845032930374146,
      "avgLogprobs": -0.0046222757209431042
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 34,
    "candidatesTokenCount": 110,
    "totalTokenCount": 144,
    "billablePromptUsage": {
      "textCount": 119
    },
    "trafficType": "ON_DEMAND"
  },
  "modelVersion": "gemini-2.0-flash-001",
  "createTime": "2024-12-09T23:33:47.842964Z",
  "responseId": "W35XZ9S5M6acmecP3vDFkQU"
}

Gen AI SDK for Python

설치

pip install --upgrade google-genai

자세한 내용은 SDK 참고 문서를 참조하세요.

Vertex AI에서 생성형 AI SDK를 사용하도록 환경 변수를 설정합니다.

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import (
    HttpOptions,
    Tool,
    ToolCodeExecution,
    GenerateContentConfig,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))
model_id = "gemini-2.0-flash-001"

code_execution_tool = Tool(code_execution=ToolCodeExecution())
response = client.models.generate_content(
    model=model_id,
    contents="Calculate 20th fibonacci number. Then find the nearest palindrome to it.",
    config=GenerateContentConfig(
        tools=[code_execution_tool],
        temperature=0,
    ),
)
print("# Code:")
print(response.executable_code)
print("# Outcome:")
print(response.code_execution_result)

# Example response:
# # Code:
# def fibonacci(n):
#     if n <= 0:
#         return 0
#     elif n == 1:
#         return 1
#     else:
#         a, b = 0, 1
#         for _ in range(2, n + 1):
#             a, b = b, a + b
#         return b
#
# fib_20 = fibonacci(20)
# print(f'{fib_20=}')
#
# # Outcome:
# fib_20=6765

채팅에서 코드 실행 사용

채팅의 일부로 코드 실행을 사용할 수 있습니다.

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/test-project/locations/us-central1/publishers/google/models/gemini-2.0-flash-001:generateContent -d \
$'{
    "tools": [{'code_execution': {}}],
    "contents": [
      {
        "role": "user",
        "parts": {
          "text": "Can you print \"Hello world!\"?"
        }
      },
      {
        "role": "model",
        "parts": [
          {
            "text": ""
          },
          {
            "executable_code": {
              "language": "PYTHON",
              "code": "\nprint(\"hello world!\")\n"
            }
          },
          {
            "code_execution_result": {
              "outcome": "OUTCOME_OK",
              "output": "hello world!\n"
            }
          },
          {
            "text": "I have printed \"hello world!\" using the provided python code block. \n"
          }
        ],
      },
      {
        "role": "user",
        "parts": {
          "text": "What is the sum of the first 50 prime numbers? Generate and run code for the calculation, and make sure you get all 50."
        }
      }
    ]
  }'

코드 실행과 함수 호출 비교

코드 실행과 함수 호출은 비슷한 특성을 지닙니다.

코드 실행을 사용하면 모델이 고정되고 격리된 환경의 API 백엔드에서 코드를 실행할 수 있습니다.
함수 호출을 사용하면 무엇이든 원하는 환경에서 모델이 요청하는 함수를 실행할 수 있습니다.

일반적으로 사용 사례에 적합하면 코드 실행을 사용하는 것이 좋습니다. 코드 실행은 사용 설정만 하면 되므로 사용하기에 간편하고 단일 GenerateContent 요청으로 처리됩니다. 함수 호출에서는 각 함수 호출에서 출력을 다시 보내기 위한 추가 GenerateContent 요청이 사용됩니다.

대부분의 경우 로컬로 실행하려는 자체 함수가 있으면 함수 호출을 사용하고, API가 자동으로 Python 코드를 작성하여 실행하고 결과를 반환하도록 하려면 코드 실행을 사용합니다.

청구

Gemini API에서 코드 실행을 사용 설정하는 데에는 추가 비용이 발생하지 않습니다. 사용 중인 Gemini 모델이 무엇인지에 따라 입력 및 출력 토큰의 현재 요율로 비용이 청구됩니다.

코드 실행의 청구에 대해 몇 가지 중요한 사항은 다음과 같습니다.

모델에 전달하는 입력 토큰과 코드 실행 도구를 사용하여 생성된 중간 입력 토큰에 대해서는 비용이 한 번만 청구됩니다.
API 응답에서 사용자에게 반환된 최종 출력 토큰에 대해 비용이 청구됩니다.

아래에 설명된 대로 코드 실행 도구 사용의 청구 흐름을 보여주는 다이어그램

사용 중인 Gemini 모델이 무엇인지에 따라 입력 및 출력 토큰의 현재 요율로 비용이 청구됩니다.
응답을 생성할 때 Gemini에 코드 실행이 사용되는 경우 원본 프롬프트, 생성된 코드, 실행된 코드 결과가 중간 토큰 라벨로 표시되고 입력 토큰으로 청구됩니다.
그런 후 Gemini가 요약을 생성하고 생성된 코드, 실행된 코드 결과, 최종 요약을 반환합니다. 이것들은 출력 토큰으로 청구됩니다.
Gemini API에는 API 응답에 중간 토큰 수가 포함되기 때문에 초기 프롬프트로 전달된 것 이상으로 추가된 입력 토큰을 추적할 수 있습니다.

생성된 코드에는 텍스트 및 멀티모달 출력(예: 이미지)이 모두 포함될 수 있습니다.

제한사항

모델은 코드를 생성 및 실행할 수만 있습니다. 미디어 파일과 같은 다른 아티팩트는 반환할 수 없습니다.
이 기능은 비텍스트 출력(예: 데이터 플롯 또는 CSV 파일 업로드)이 관련된 사용 사례 또는 파일 I/O를 지원하지 않습니다.
코드 실행은 타임아웃되기 전까지 최대 30초 동안 실행될 수 있습니다.
일부 경우에 코드 실행을 사용 설정하면 모델 출력의 다른 영역(예: 스토리 작성)에서 성능이 저하될 수 있습니다.

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

지원되는 모델

코드 실행 시작하기

모델에서 코드 실행 사용 설정

REST

curl

PowerShell

응답

Gen AI SDK for Python

설치

채팅에서 코드 실행 사용

REST

코드 실행과 함수 호출 비교

청구

제한사항

코드 실행