로그와 데이터셋(Logs and datasets)

로그와 데이터셋(Logs and datasets)

이 가이드에서는 Google AI Studio 대시보드에서 Gemini API 사용 로그를 보는 방법을 배워요. 이를 통해 모델 동작과 사용자가 애플리케이션과 상호작용하는 방식을 더 잘 이해할 수 있어요. 로깅을 사용해 관찰하고 디버깅하며, 선택적으로 사용 피드백을 Google과 공유해 개발자 사용 사례 전반에서 Gemini를 개선하는 데 도움을 줄 수 있어요.

모든 GenerateContent, BatchGenerateContent, StreamGenerateContent API 호출과 Managed Agents를 제외한 Interactions API 호출이 지원돼요. OpenAI 호환 엔드포인트를 통한 호출도 포함돼요.

참고: Gemini API 로그 저장은 Gemini API 유료 티어의 프로젝트에서만 사용할 수 있어요.

출처: 원문

본문

프로젝트 로깅 구성

기본적으로 API는 서버 측 상태 관리 기능을 단순화하기 위해 모든 상호작용 객체를 저장해요(store=true). 반면 Generate Content API는 기본적으로 요청을 저장하지 않으며, 요청별 또는 AI Studio에서 프로젝트 수준으로 저장을 활성화해야 해요.

Google AI Studio에서 모든 프로젝트 또는 특정 프로젝트의 로깅을 활성화하거나 비활성화할 수 있고, Logs and Datasets 페이지의 Settings 패널을 통해 언제든지 이 기본 설정을 변경할 수 있어요. generateContent API와 Interactions API에 대해 로깅을 독립적으로 켜고 끄며 프로젝트의 기본 저장 동작을 변경할 수 있어요.

경고: AI Studio의 Settings 패널에서 Interactions API 로깅을 끄면, 요청별로 명시적으로 재정의하지 않는 한 API가 대화 기록을 자동으로 저장하고 검색하지 못하게 돼요.

요청 수준 로깅

저장 및 로깅 동작은 API별로 달라요:

  • Interactions API: 서버 측 상태 관리를 단순화하기 위해 기본적으로 요청을 저장해요(store=true).
  • Generate Content API(generateContent): 기본적으로 요청을 저장하지 않아요(store=false).

store 속성을 설정하는 방법은 다음과 같아요:

GenerateContent API

Python

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents='Explain quantum entanglement in simple terms.',
    config={'store': False} # Set to True to enable logging of this request
)

print(response.text)

JavaScript

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const response = await client.models.generateContent({
    model: 'gemini-3.8-flash',
    contents: 'Explain quantum entanglement in simple terms.',
    config: {
        store: false // Set to true to enable logging of this request
    }
});

console.log(response.text);

Java

import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;

Client client = new Client();

// The GenerateContent API does not store requests by default
GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash",
        "Explain quantum entanglement in simple terms.",
        GenerateContentConfig.builder().build());

System.out.println(response.text());

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // The GenerateContent API does not store requests by default
    response, err := client.Models.GenerateContent(
        ctx,
        "gemini-3.8-flash",
        genai.Text("Explain quantum entanglement in simple terms."),
        &genai.GenerateContentConfig{},
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(response.Text())
}

Interactions API

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain quantum entanglement in simple terms.",
    store=True # Set to False to disable logging of this request
)

print(interaction.outputs[-1].text)

JavaScript

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Explain quantum entanglement in simple terms.',
    store: true // Set to false to disable logging of this request
});

console.log(interaction.outputs[interaction.outputs.length - 1].text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Explain quantum entanglement in simple terms."))
        .store(true) // Set to false to disable logging of this request
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Explain quantum entanglement in simple terms."),
            Store: genai.Ptr(true), // Set to false to disable logging of this request
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

AI Studio에서 프로젝트 로그 보기

  1. AI Studio의 Logs 페이지로 가요.
  2. 드롭다운에서 프로젝트를 선택해요.
  3. Interactions API 로그가 있으면 역시간순으로 표에 나타나요.
  4. Generate Content API의 프로젝트 로그를 보려면 먼저 설정 패널에서 이를 활성화해요.

참고: 로그가 표시되려면 프로젝트에 활성 API 키가 하나 이상 필요해요. 프로젝트의 모든 API 키가 삭제되면(예: 유출된 키가 삭제된 경우) API 키가 생길 때까지 프로젝트 로그를 볼 수 없어요.

항목을 클릭하면 페이로드 미리보기가 나와요. Gemini의 전체 프롬프트와 응답, 이전 턴의 컨텍스트를 검사할 수 있어요. Interactions API 요청의 경우 로그에는 previous_interaction_id에 대한 직접 링크도 포함돼요.

프로젝트 저장 보존 기간 구성

로그는 기본 보존 기간인 55일 후에 만료되어 삭제 대상으로 표시돼요(데이터셋에 저장하지 않으면, 이 경우 만료되지 않아요). 프로젝트 로그의 보존 기간을 최대 7, 14, 28 또는 55일로 구성할 수 있어요.

데이터셋 생성 및 공유

로그를 데이터셋에 저장해서 더 효과적으로 구성하고 내보낼 수 있어요.

  • Logs 페이지에서 상단의 필터 바를 찾아 필터링할 속성을 선택해요.
  • 필터링된 보기에서 체크박스를 사용해 개별 로그 또는 전체를 선택해요.
  • 목록 상단에 나타나는 Create dataset 버튼을 클릭해요.
  • 새 데이터셋에 이름과 선택적 설명을 지정해요.
  • 방금 만든 데이터셋과 선별된 로그 세트를 볼 수 있어요.
  • 추가 분석을 위해 데이터셋을 CSV, JSONL 파일로 또는 Google Sheets로 내보내요.

데이터셋은 여러 사용 사례에 유용할 수 있어요.

  • 챌린지 세트 선별: AI를 개선하고 싶은 영역을 겨냥한 향후 개선을 추진해요.
  • 샘플 세트 선별: 예를 들어 다른 모델에서 응답을 생성하기 위한 실제 사용 샘플, 또는 배포 전 일상 점검을 위한 엣지 케이스 모음.
  • 평가 세트(Evaluation sets): 다른 모델 또는 시스템 지침 반복과 비교하기 위한 중요 기능 전반의 실제 사용을 대표하는 세트.

데이터셋을 데모 예시로 Google과 공유하기로 선택함으로써 Gemini 연구 개발에 기여할 수 있어요.

제한 사항(Limitations)

다음에는 로깅이 현재 지원되지 않아요:

  • Imagen 및 Veo 모델
  • Gemini 임베딩 모델
  • Gemini Robotics 모델
  • 비디오, GIF, PDF를 포함하는 입력
  • Gemini API의 Public Preview Agents

더 알아보기 (Learn more)

  • 세션 기록으로 프로토타이핑: AI Studio Build를 사용해 바이브 코딩 앱을 만들고 API 키를 추가해 AI 기능의 Gemini API 로그 기록을 활성화해요.
  • Gemini Batch API로 로그 재실행: Gemini Batch API로 로그를 재실행해 응답 샘플링과 모델·애플리케이션 로직 평가에 데이터셋을 사용해요.