코드 실행

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

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

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

지원되는 모델

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

모델 버전 코드 실행 출시 단계
Gemini 2.0 Flash 모든 버전 정식 버전

코드 실행 시작하기

이 섹션에서는 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

요청 본문을 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

요청 본문을 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 응답이 수신됩니다.

Python용 생성형 AI SDK

Python용 Google Gen AI SDK를 설치하거나 업데이트하는 방법을 알아보세요.
자세한 내용은 Python용 Gen AI SDK API 참고 문서 또는 python-genai GitHub 저장소를 참고하세요.
Vertex AI에서 Gen 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,
    ),
)
for part in response.candidates[0].content.parts:
    if part.executable_code:
        print(part.executable_code)
    if part.code_execution_result:
        print(part.code_execution_result)
# Example response:
# code='...' language='PYTHON'
# outcome='OUTCOME_OK' output='The 20th Fibonacci number is: 6765\n'
# code='...' language='PYTHON'
# outcome='OUTCOME_OK' output='Lower Palindrome: 6666\nHigher Palindrome: 6776\nNearest Palindrome to 6765: 6776\n'

Chat에서 코드 실행 사용하기

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

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 응답에 중간 토큰 수를 포함하므로 초기 프롬프트에서 전달된 토큰 외에도 추가 입력 토큰을 추적할 수 있습니다.

생성된 코드에는 텍스트와 이미지와 같은 멀티모달 출력이 모두 포함될 수 있습니다.

제한사항

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