Caching

컨텍스트 캐싱을 사용하면 반복적으로 사용하고 싶은 미리 계산된 입력 토큰을 저장하고 재사용할 수 있습니다(예: 동일한 미디어 파일에 대해 서로 다른 질문을 하는 경우). 사용량에 따라 비용과 속도를 절약할 수 있습니다. 자세한 소개는 컨텍스트 캐싱 가이드를 참고하세요.

메서드: cachedContents.create

CachedContent 리소스를 만듭니다.

엔드포인트

게시 https://generativelanguage.googleapis.com/v1beta/cachedContents

요청 본문

요청 본문에 CachedContent의 인스턴스가 포함됩니다.

필드
contents[] object (Content)

선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 캐시할 콘텐츠입니다.

tools[] object (Tool)

선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 모델이 다음 응답을 생성하는 데 사용할 수 있는 Tools 목록

통합 필드 expiration. 이 리소스가 만료되는 시기를 지정합니다. expiration은 다음 중 하나여야 합니다.
expireTime string (Timestamp format)

이 리소스가 만료된 것으로 간주되는 시간의 타임스탬프(UTC)입니다. 이 필드는 입력으로 전송된 항목에 관계없이 항상 출력으로 제공됩니다.

RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"입니다.

ttl string (Duration format)

입력 전용입니다. 이 리소스의 새 TTL입니다(입력만 가능).

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.

name string

선택사항입니다. 식별자. 캐시된 콘텐츠를 참조하는 리소스 이름입니다. 형식: cachedContents/{id}

displayName string

선택사항입니다. 변경할 수 없습니다. 캐시된 콘텐츠의 의미 있는 사용자 생성 표시 이름입니다. 최대 128자(유니코드 기준)

model string

필수 항목입니다. 변경할 수 없습니다. 캐시된 콘텐츠에 사용할 Model의 이름입니다. 형식: models/{model}

systemInstruction object (Content)

선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 개발자가 설정한 시스템 안내 현재 텍스트 전용입니다.

toolConfig object (ToolConfig)

선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 도구 구성 이 구성은 모든 도구에서 공유됩니다.

요청 예시

기본

Python

import google.generativeai as genai

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)
print(cache)

model = genai.GenerativeModel.from_cached_content(cache)
response = model.generate_content("Please summarize this transcript")
print(response.text)

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
// import { GoogleGenerativeAI } from "@google/generative-ai";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});

console.log(cacheResult);

const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModelFromCachedContent(cacheResult);
const result = await model.generateContent(
  "Please summarize this transcript.",
);
console.log(result.response.text());

Go

file, err := client.UploadFileFromPath(ctx,
	filepath.Join(testDataDir, "a11.txt"),
	&genai.UploadFileOptions{MIMEType: "text/plain"})
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)
fd := genai.FileData{URI: file.URI}

argcc := &genai.CachedContent{
	Model:             "gemini-1.5-flash-001",
	SystemInstruction: genai.NewUserContent(genai.Text("You are an expert analyzing transcripts.")),
	Contents:          []*genai.Content{genai.NewUserContent(fd)},
}
cc, err := client.CreateCachedContent(ctx, argcc)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteCachedContent(ctx, cc.Name)

modelWithCache := client.GenerativeModelFromCachedContent(cc)
prompt := "Please summarize this transcript"
resp, err := modelWithCache.GenerateContent(ctx, genai.Text(prompt))
if err != nil {
	log.Fatal(err)
}

printResponse(resp)

Shell

wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-1.5-flash-001",
  "contents":[
    {
      "parts":[
        {
          "inline_data": {
            "mime_type":"text/plain",
            "data": "'$(base64 $B64FLAGS a11.txt)'"
          }
        }
      ],
    "role": "user"
    }
  ],
  "systemInstruction": {
    "parts": [
      {
        "text": "You are an expert at analyzing transcripts."
      }
    ]
  },
  "ttl": "300s"
}' > request.json

curl -X POST "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GOOGLE_API_KEY" \
 -H 'Content-Type: application/json' \
 -d @request.json \
 > cache.json

CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash-001:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "Please summarize this transcript"
          }],
          "role": "user"
        },
      ],
      "cachedContent": "'$CACHE_NAME'"
    }'

발신자 이름

Python

import google.generativeai as genai

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)
cache_name = cache.name  # Save the name for later

# Later
cache = genai.caching.CachedContent.get(cache_name)
apollo_model = genai.GenerativeModel.from_cached_content(cache)
response = apollo_model.generate_content("Find a lighthearted moment from this transcript")
print(response.text)

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
// import { GoogleGenerativeAI } from "@google/generative-ai";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});
const cacheName = cacheResult.name; // Save the name for later.

// Later
const getCacheResult = await cacheManager.get(cacheName);
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModelFromCachedContent(getCacheResult);
model.generateContent("Please summarize this transcript.");

Go

file, err := client.UploadFileFromPath(ctx, filepath.Join(testDataDir, "a11.txt"), nil)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)
fd := genai.FileData{URI: file.URI}

argcc := &genai.CachedContent{
	Model:             "gemini-1.5-flash-001",
	SystemInstruction: genai.NewUserContent(genai.Text("You are an expert analyzing transcripts.")),
	Contents:          []*genai.Content{genai.NewUserContent(fd)},
}
cc, err := client.CreateCachedContent(ctx, argcc)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteCachedContent(ctx, cc.Name)

// Save the name for later
cacheName := cc.Name

// ... Later
cc2, err := client.GetCachedContent(ctx, cacheName)
if err != nil {
	log.Fatal(err)
}
modelWithCache := client.GenerativeModelFromCachedContent(cc2)
prompt := "Find a lighthearted moment from this transcript"
resp, err := modelWithCache.GenerateContent(ctx, genai.Text(prompt))
if err != nil {
	log.Fatal(err)
}

printResponse(resp)

채팅에서 생성된 할 일

Python

import google.generativeai as genai

model_name = "gemini-1.5-flash-001"
system_instruction = "You are an expert analyzing transcripts."

model = genai.GenerativeModel(model_name=model_name, system_instruction=system_instruction)
chat = model.start_chat()
document = genai.upload_file(path=media / "a11.txt")
response = chat.send_message(["Hi, could you summarize this transcript?", document])
print("\n\nmodel:  ", response.text)
response = chat.send_message(
    ["Okay, could you tell me more about the trans-lunar injection"]
)
print("\n\nmodel:  ", response.text)

# To cache the conversation so far, pass the chat history as the list of "contents".
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction=system_instruction,
    contents=chat.history,
)
model = genai.GenerativeModel.from_cached_content(cached_content=cache)

# Continue the chat where you left off.
chat = model.start_chat()
response = chat.send_message(
    "I didn't understand that last part, could you explain it in simpler language?"
)
print("\n\nmodel:  ", response.text)

Node.js

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash-001" });
const chat = model.startChat();

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

let result = await chat.sendMessage([
  "Hi, could you summarize this transcript?",
  {
    fileData: {
      fileUri: uploadResult.file.uri,
      mimeType: uploadResult.file.mimeType,
    },
  },
]);
console.log(`\n\nmodel: ${result.response.text()}`);
result = await chat.sendMessage(
  "Okay, could you tell me more about the trans-lunar injection",
);
console.log(`\n\nmodel: ${result.response.text()}`);

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: await chat.getHistory(),
});

const newModel = genAI.getGenerativeModelFromCachedContent(cacheResult);

const newChat = newModel.startChat();
result = await newChat.sendMessage(
  "I didn't understand that last part, could you explain it in simpler language?",
);
console.log(`\n\nmodel: ${result.response.text()}`);

Go

file, err := client.UploadFileFromPath(ctx, filepath.Join(testDataDir, "a11.txt"), nil)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)
fd := genai.FileData{URI: file.URI}

modelName := "gemini-1.5-flash-001"
model := client.GenerativeModel(modelName)
model.SystemInstruction = genai.NewUserContent(genai.Text("You are an expert analyzing transcripts."))

cs := model.StartChat()
resp, err := cs.SendMessage(ctx, genai.Text("Hi, could you summarize this transcript?"), fd)
if err != nil {
	log.Fatal(err)
}

resp, err = cs.SendMessage(ctx, genai.Text("Okay, could you tell me more about the trans-lunar injection"))
if err != nil {
	log.Fatal(err)
}

// To cache the conversation so far, pass the chat history as the list of
// contents.

argcc := &genai.CachedContent{
	Model:             modelName,
	SystemInstruction: model.SystemInstruction,
	Contents:          cs.History,
}
cc, err := client.CreateCachedContent(ctx, argcc)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteCachedContent(ctx, cc.Name)

modelWithCache := client.GenerativeModelFromCachedContent(cc)
cs = modelWithCache.StartChat()
resp, err = cs.SendMessage(ctx, genai.Text("I didn't understand that last part, could you please explain it in simpler language?"))
if err != nil {
	log.Fatal(err)
}
printResponse(resp)

응답 본문

성공한 경우 응답 본문에 새로 생성된 CachedContent의 인스턴스가 포함됩니다.

메서드: cachedContents.list

CachedContents를 나열합니다.

엔드포인트

get https://generativelanguage.googleapis.com/v1beta/cachedContents

쿼리 매개변수

pageSize integer

선택사항입니다. 반환할 최대 캐시된 콘텐츠 수입니다. 서비스가 이 값보다 더 적게 반환할 수 있습니다. 지정하지 않으면 일부 기본 항목 (최대 이하)이 반환됩니다. 최댓값은 1,000이며, 1,000을 초과하는 값은 1,000으로 변환됩니다.

pageToken string

선택사항입니다. 이전 cachedContents.list 호출에서 받은 페이지 토큰입니다. 후속 페이지를 검색하려면 이를 입력합니다.

페이지를 매길 때 cachedContents.list에 제공된 다른 모든 매개변수는 페이지 토큰을 제공한 호출과 일치해야 합니다.

요청 본문

요청 본문은 비어 있어야 합니다.

응답 본문

CachedContents 목록이 포함된 응답입니다.

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

필드
cachedContents[] object (CachedContent)

캐시된 콘텐츠의 목록입니다.

nextPageToken string

다음 페이지를 검색하기 위해 pageToken으로 전송할 수 있는 토큰입니다. 이 필드를 생략하면 후속 페이지가 표시되지 않습니다.

JSON 표현
{
  "cachedContents": [
    {
      object (CachedContent)
    }
  ],
  "nextPageToken": string
}

메서드: cachedContents.get

CachedContent 리소스를 읽습니다.

엔드포인트

get https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}

경로 매개변수

name string

필수 항목입니다. 콘텐츠 캐시 항목을 참조하는 리소스 이름입니다. 형식: cachedContents/{id} cachedContents/{cachedcontent} 형식을 취합니다.

요청 본문

요청 본문은 비어 있어야 합니다.

요청 예시

Python

import google.generativeai as genai

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)
print(genai.caching.CachedContent.get(name=cache.name))

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});
const cacheGetResult = await cacheManager.get(cacheResult.name);
console.log(cacheGetResult);

Go

file, err := client.UploadFileFromPath(ctx, filepath.Join(testDataDir, "a11.txt"), nil)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)
fd := genai.FileData{URI: file.URI}

argcc := &genai.CachedContent{
	Model:             "gemini-1.5-flash-001",
	SystemInstruction: genai.NewUserContent(genai.Text("You are an expert analyzing transcripts.")),
	Contents:          []*genai.Content{genai.NewUserContent(fd)},
}
cc, err := client.CreateCachedContent(ctx, argcc)
if err != nil {
	log.Fatal(err)
}
defer client.DeleteCachedContent(ctx, cc.Name)

// Save the name for later
cacheName := cc.Name

// ... Later
cc2, err := client.GetCachedContent(ctx, cacheName)
if err != nil {
	log.Fatal(err)
}
modelWithCache := client.GenerativeModelFromCachedContent(cc2)
prompt := "Find a lighthearted moment from this transcript"
resp, err := modelWithCache.GenerateContent(ctx, genai.Text(prompt))
if err != nil {
	log.Fatal(err)
}

printResponse(resp)

Shell

curl "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GOOGLE_API_KEY"

응답 본문

성공한 경우 응답 본문에 CachedContent의 인스턴스가 포함됩니다.

메서드: CacheContents.patch

CachedContent 리소스를 업데이트합니다 (만료만 업데이트 가능).

엔드포인트

패치 https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}

PATCH https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}

경로 매개변수

cachedContent.name string

선택사항입니다. 식별자. 캐시된 콘텐츠를 참조하는 리소스 이름입니다. 형식: cachedContents/{id} cachedContents/{cachedcontent} 형식이 사용됩니다.

쿼리 매개변수

updateMask string (FieldMask format)

업데이트할 필드 목록입니다.

정규화된 필드 이름의 쉼표로 구분된 목록입니다. 예: "user.displayName,photo"

요청 본문

요청 본문에 CachedContent의 인스턴스가 포함됩니다.

필드
통합 필드 expiration. 이 리소스가 만료되는 시기를 지정합니다. expiration은 다음 중 하나여야 합니다.
expireTime string (Timestamp format)

이 리소스가 만료된 것으로 간주되는 시간의 타임스탬프(UTC)입니다. 이 필드는 입력으로 전송된 항목에 관계없이 항상 출력으로 제공됩니다.

RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"입니다.

ttl string (Duration format)

입력 전용입니다. 이 리소스의 새 TTL입니다(입력만 가능).

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.

name string

선택사항입니다. 식별자. 캐시된 콘텐츠를 참조하는 리소스 이름입니다. 형식: cachedContents/{id}

요청 예시

Python

import google.generativeai as genai

import datetime

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)

# You can update the ttl
cache.update(ttl=datetime.timedelta(hours=2))
print(f"After update:\n {cache}")

# Or you can update the expire_time
cache.update(expire_time=datetime.datetime.now() + datetime.timedelta(minutes=15))

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});
console.log("initial cache data:", cacheResult);
const cacheUpdateResult = await cacheManager.update(cacheResult.name, {
  cachedContent: {
    // 2 hours
    ttlSeconds: 60 * 60 * 2,
  },
});
console.log("updated cache data:", cacheUpdateResult);

Go

file, err := client.UploadFileFromPath(ctx,
	filepath.Join(testDataDir, "a11.txt"),
	&genai.UploadFileOptions{MIMEType: "text/plain"})
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)

Shell

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GOOGLE_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'

응답 본문

성공한 경우 응답 본문에 CachedContent의 인스턴스가 포함됩니다.

메서드: cachedContents.delete

CachedContent 리소스를 삭제합니다.

엔드포인트

삭제 https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}

경로 매개변수

name string

필수 항목입니다. 콘텐츠 캐시 항목을 참조하는 리소스 이름 형식: cachedContents/{id} cachedContents/{cachedcontent} 형식입니다.

요청 본문

요청 본문은 비어 있어야 합니다.

요청 예시

Python

import google.generativeai as genai

document = genai.upload_file(path=media / "a11.txt")
model_name = "gemini-1.5-flash-001"
cache = genai.caching.CachedContent.create(
    model=model_name,
    system_instruction="You are an expert analyzing transcripts.",
    contents=[document],
)
cache.delete()

Node.js

// Make sure to include these imports:
// import { GoogleAICacheManager, GoogleAIFileManager } from "@google/generative-ai/server";
const cacheManager = new GoogleAICacheManager(process.env.API_KEY);
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
});

const cacheResult = await cacheManager.create({
  model: "models/gemini-1.5-flash-001",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: uploadResult.file.uri,
            mimeType: uploadResult.file.mimeType,
          },
        },
      ],
    },
  ],
});
await cacheManager.delete(cacheResult.name);

Go

file, err := client.UploadFileFromPath(ctx,
	filepath.Join(testDataDir, "a11.txt"),
	&genai.UploadFileOptions{MIMEType: "text/plain"})
if err != nil {
	log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)

Shell

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GOOGLE_API_KEY"

응답 본문

성공한 경우 응답 본문은 비어 있습니다.

REST 리소스: cacheContents

리소스: CachedContent

사전 처리되었으며 이후 GenerativeService 요청에 사용할 수 있는 콘텐츠입니다.

캐시된 콘텐츠는 생성된 모델과 함께만 사용할 수 있습니다.

필드
contents[] object (Content)

선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 캐시할 콘텐츠입니다.

tools[] object (Tool)

선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 모델이 다음 응답을 생성하는 데 사용할 수 있는 Tools 목록

createTime string (Timestamp format)

출력 전용입니다. 캐시 항목의 생성 시간입니다.

RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"입니다.

updateTime string (Timestamp format)

출력 전용입니다. 캐시 항목이 마지막으로 업데이트된 시간(UTC 시간)입니다.

RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"입니다.

usageMetadata object (UsageMetadata)

출력 전용입니다. 캐시된 콘텐츠의 사용에 관한 메타데이터입니다.

통합 필드 expiration. 이 리소스가 만료되는 시점을 지정합니다. expiration은 다음 중 하나여야 합니다.
expireTime string (Timestamp format)

이 리소스가 만료된 것으로 간주되는 시간의 타임스탬프(UTC)입니다. 이 필드는 입력으로 전송된 항목에 관계없이 항상 출력으로 제공됩니다.

RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"입니다.

ttl string (Duration format)

입력 전용입니다. 이 리소스의 새 TTL입니다(입력만 가능).

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.

name string

선택사항입니다. 식별자. 캐시된 콘텐츠를 참조하는 리소스 이름입니다. 형식: cachedContents/{id}

displayName string

선택사항입니다. 변경할 수 없습니다. 캐시된 콘텐츠의 의미 있는 사용자 생성 표시 이름입니다. 최대 128자(유니코드 기준)

model string

필수 항목입니다. 변경할 수 없습니다. 캐시된 콘텐츠에 사용할 Model의 이름입니다. 형식: models/{model}

systemInstruction object (Content)

선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 개발자가 설정한 시스템 안내 현재 텍스트 전용입니다.

toolConfig object (ToolConfig)

선택사항입니다. 입력 전용입니다. 변경할 수 없습니다. 도구 구성 이 구성은 모든 도구에 공유됩니다.

JSON 표현
{
  "contents": [
    {
      object (Content)
    }
  ],
  "tools": [
    {
      object (Tool)
    }
  ],
  "createTime": string,
  "updateTime": string,
  "usageMetadata": {
    object (UsageMetadata)
  },

  // Union field expiration can be only one of the following:
  "expireTime": string,
  "ttl": string
  // End of list of possible types for union field expiration.
  "name": string,
  "displayName": string,
  "model": string,
  "systemInstruction": {
    object (Content)
  },
  "toolConfig": {
    object (ToolConfig)
  }
}

콘텐츠

메시지의 여러 부분으로 구성된 콘텐츠를 포함하는 구조화된 데이터의 기본 유형입니다.

Content에는 Content의 생산자를 지정하는 role 필드와 메시지 대화의 콘텐츠가 포함된 멀티파트 데이터가 포함된 parts 필드가 포함됩니다.

필드
parts[] object (Part)

단일 메시지를 구성하는 순서가 지정된 Parts입니다. 부분마다 MIME 유형이 다를 수 있습니다.

role string

선택사항입니다. 콘텐츠 제작자 'user' 또는 'model'이어야 합니다.

멀티턴 대화에 설정하면 유용하며, 그렇지 않은 경우에는 비워 두거나 설정하지 않아도 됩니다.

JSON 표현
{
  "parts": [
    {
      object (Part)
    }
  ],
  "role": string
}

부품

멀티 파트 Content 메시지의 일부인 미디어를 포함하는 데이터 유형입니다.

Part는 연결된 데이터 유형이 있는 데이터로 구성됩니다. PartPart.data에서 허용되는 유형 중 하나만 포함할 수 있습니다.

inlineData 필드가 원시 바이트로 채워진 경우 Part에는 미디어의 유형과 하위유형을 식별하는 고정된 IANA MIME 유형이 있어야 합니다.

필드

통합 필드 data.

data는 다음 중 하나여야 합니다.

text string

인라인 텍스트

inlineData object (Blob)

인라인 미디어 바이트.

functionCall object (FunctionCall)

모델에서 반환한 예측된 FunctionCall로, 인수와 그 값과 함께 FunctionDeclaration.name를 나타내는 문자열이 포함됩니다.

functionResponse object (FunctionResponse)

FunctionDeclaration.name을 나타내는 문자열과 함수의 출력이 포함된 구조화된 JSON 객체가 포함된 FunctionCall의 결과 출력은 모델의 컨텍스트로 사용됩니다.

fileData object (FileData)

URI 기반 데이터

executableCode object (ExecutableCode)

실행할 모델에서 생성한 코드입니다.

codeExecutionResult object (CodeExecutionResult)

ExecutableCode 실행 결과

JSON 표현
{

  // Union field data can be only one of the following:
  "text": string,
  "inlineData": {
    object (Blob)
  },
  "functionCall": {
    object (FunctionCall)
  },
  "functionResponse": {
    object (FunctionResponse)
  },
  "fileData": {
    object (FileData)
  },
  "executableCode": {
    object (ExecutableCode)
  },
  "codeExecutionResult": {
    object (CodeExecutionResult)
  }
  // End of list of possible types for union field data.
}

blob

원시 미디어 바이트입니다.

텍스트는 원시 바이트로 전송해서는 안 되며 'text' 필드를 사용해야 합니다.

필드
mimeType string

소스 데이터의 IANA 표준 MIME 유형입니다. 예: - image/png - image/jpeg 지원되지 않는 MIME 유형을 제공하면 오류가 반환됩니다. 지원되는 유형의 전체 목록은 지원되는 파일 형식을 참고하세요.

data string (bytes format)

미디어 형식의 원시 바이트입니다.

base64 인코딩 문자열입니다.

JSON 표현
{
  "mimeType": string,
  "data": string
}

FunctionCall

인수와 해당 값이 포함된 FunctionDeclaration.name을 나타내는 문자열을 포함하는 모델에서 반환된 예측된 FunctionCall입니다.

필드
name string

필수 항목입니다. 호출하려는 함수의 이름입니다. a~z, A~Z, 0~9이거나 밑줄과 대시를 포함해야 하며 최대 길이는 63자(영문 기준)입니다.

args object (Struct format)

선택사항입니다. JSON 객체 형식의 함수 매개변수와 값입니다.

JSON 표현
{
  "name": string,
  "args": {
    object
  }
}

FunctionResponse

FunctionDeclaration.name을 나타내는 문자열과 함수의 출력이 포함된 구조화된 JSON 객체가 포함된 FunctionCall의 결과 출력은 모델의 컨텍스트로 사용됩니다. 여기에는 모델 예측을 기반으로 한 FunctionCall의 결과가 포함되어야 합니다.

필드
name string

필수 항목입니다. 호출하려는 함수의 이름입니다. a~z, A~Z, 0~9이거나 밑줄과 대시를 포함해야 하며 최대 63자 길이입니다.

response object (Struct format)

필수 항목입니다. JSON 객체 형식의 함수 응답입니다.

JSON 표현
{
  "name": string,
  "response": {
    object
  }
}

FileData

URI 기반 데이터

필드
mimeType string

선택사항입니다. 소스 데이터의 IANA 표준 MIME 유형입니다.

fileUri string

필수 항목입니다. URI

JSON 표현
{
  "mimeType": string,
  "fileUri": string
}

ExecutableCode

실행될 목적으로 모델에서 생성된 코드와 모델에 반환된 결과입니다.

CodeExecution 도구를 사용할 때만 생성되며, 이때 코드가 자동으로 실행되고 상응하는 CodeExecutionResult도 생성됩니다.

필드
language enum (Language)

필수 항목입니다. code의 프로그래밍 언어

code string

필수 항목입니다. 실행할 코드입니다.

JSON 표현
{
  "language": enum (Language),
  "code": string
}

언어

생성된 코드에 지원되는 프로그래밍 언어입니다.

열거형
LANGUAGE_UNSPECIFIED 지정되지 않은 언어 이 값은 사용하면 안 됩니다.
PYTHON Python 3.10 이상, NumPy 및 Simpy 사용 가능

CodeExecutionResult

ExecutableCode 실행 결과입니다.

CodeExecution를 사용할 때만 생성되며 항상 ExecutableCode가 포함된 part 뒤에 옵니다.

필드
outcome enum (Outcome)

필수 항목입니다. 코드 실행의 결과입니다.

output string

선택사항입니다. 코드 실행이 성공하면 stdout을, 그렇지 않으면 stderr 또는 기타 설명을 포함합니다.

JSON 표현
{
  "outcome": enum (Outcome),
  "output": string
}

결과

코드 실행의 가능한 결과의 열거형입니다.

열거형
OUTCOME_UNSPECIFIED 지정되지 않은 상태입니다. 이 값은 사용하면 안 됩니다.
OUTCOME_OK 코드 실행이 완료되었습니다.
OUTCOME_FAILED 코드 실행이 완료되었지만 오류가 발생했습니다. stderr에는 이유가 포함되어야 합니다.
OUTCOME_DEADLINE_EXCEEDED 코드 실행이 너무 오래 실행되어 취소되었습니다. 부분적인 출력이 표시될 수도 있고 아닐 수도 있습니다.

도구

모델이 응답을 생성하는 데 사용할 수 있는 도구 세부정보입니다.

Tool는 시스템이 모델의 지식과 범위를 벗어나 외부 시스템과 상호작용하여 작업 또는 작업 집합을 수행할 수 있도록 하는 코드 조각입니다.

필드
functionDeclarations[] object (FunctionDeclaration)

선택사항입니다. 모델에서 사용할 수 있고 함수 호출에 사용할 수 있는 FunctionDeclarations 목록입니다.

모델 또는 시스템이 함수를 실행하지 않습니다. 대신 정의된 함수는 실행을 위해 클라이언트 측에 인수가 있는 FunctionCall로 반환될 수 있습니다. 모델은 응답에 FunctionCall를 채움으로써 이러한 함수의 하위 집합을 호출하기로 결정할 수 있습니다. 다음 대화 턴에는 다음 모델 턴의 Content.role '함수' 생성 컨텍스트가 포함된 FunctionResponse가 포함될 수 있습니다.

googleSearchRetrieval object (GoogleSearchRetrieval)

선택사항입니다. Google 검색을 기반으로 하는 검색 도구입니다.

codeExecution object (CodeExecution)

선택사항입니다. 모델이 생성의 일부로 코드를 실행하도록 합니다.

JSON 표현
{
  "functionDeclarations": [
    {
      object (FunctionDeclaration)
    }
  ],
  "googleSearchRetrieval": {
    object (GoogleSearchRetrieval)
  },
  "codeExecution": {
    object (CodeExecution)
  }
}

FunctionDeclaration

OpenAPI 3.03 사양에서 정의된 함수 선언의 구조화된 표현입니다. 이 선언에는 함수 이름과 매개변수가 포함됩니다. 이 FunctionDeclaration은 모델에서 Tool로 사용하고 클라이언트에서 실행할 수 있는 코드 블록을 나타냅니다.

필드
name string

필수 항목입니다. 함수 이름입니다. a~z, A~Z, 0~9이거나 밑줄과 대시를 포함해야 하며 최대 길이는 63자(영문 기준)입니다.

description string

필수 항목입니다. 함수에 대한 간단한 설명입니다.

parameters object (Schema)

선택사항입니다. 이 함수의 매개변수를 설명합니다. Open API 3.03 매개변수 객체 문자열 키를 반영합니다. 매개변수의 이름입니다. 매개변수 이름은 대소문자를 구분합니다. 스키마 값: 매개변수에 사용되는 유형을 정의하는 스키마입니다.

JSON 표현
{
  "name": string,
  "description": string,
  "parameters": {
    object (Schema)
  }
}

스키마

Schema 객체를 사용하면 입력 및 출력 데이터 유형을 정의할 수 있습니다. 이러한 유형은 객체일 수 있지만 원시 유형과 배열도 될 수 있습니다. OpenAPI 3.0 스키마 객체의 선택된 하위 집합을 나타냅니다.

필드
type enum (Type)

필수 항목입니다. 데이터 유형

format string

선택사항입니다. 데이터 형식입니다. 이는 기본 데이터 유형에만 사용됩니다. 지원되는 형식: NUMBER 유형: float, double의 경우 INTEGER 유형: int32, 문자열의 경우 int64 유형: enum

description string

선택사항입니다. 매개변수에 대한 간단한 설명입니다. 여기에는 사용 예시가 포함될 수 있습니다. 매개변수 설명은 마크다운 형식일 수 있습니다.

nullable boolean

선택사항입니다. null 값을 나타냅니다.

enum[] string

선택사항입니다. enum 형식의 가능한 Type.STRING 요소 값입니다. 예를 들어 열거형 방향을 다음과 같이 정의할 수 있습니다. {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

maxItems string (int64 format)

선택사항입니다. Type.ARRAY의 최대 요소 수입니다.

minItems string (int64 format)

선택사항입니다. Type.ARRAY의 요소 최솟값입니다.

properties map (key: string, value: object (Schema))

선택사항입니다. Type.OBJECT의 속성입니다.

"key": value 쌍 목록을 포함하는 객체입니다. 예: { "name": "wrench", "mass": "1.3kg", "count": "3" }

required[] string

선택사항입니다. Type.OBJECT의 필수 속성입니다.

items object (Schema)

선택사항입니다. Type.ARRAY 요소의 스키마입니다.

JSON 표현
{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": string,
  "minItems": string,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "items": {
    object (Schema)
  }
}

유형

Type에는 https://spec.openapis.org/oas/v3.0.3#data-types에 정의된 OpenAPI 데이터 유형 목록이 포함됩니다.

열거형
TYPE_UNSPECIFIED 지정되지 않았으며 사용해서는 안 됩니다.
STRING 문자열 유형입니다.
NUMBER 숫자 유형입니다.
INTEGER 정수 유형입니다.
BOOLEAN 불리언 유형입니다.
ARRAY 배열 유형입니다.
OBJECT 객체 유형입니다.

GoogleSearchRetrieval

그라운딩을 위해 공개 웹 데이터를 검색하는 도구로, Google에서 제공합니다.

필드
dynamicRetrievalConfig object (DynamicRetrievalConfig)

지정된 소스의 동적 검색 구성을 지정합니다.

JSON 표현
{
  "dynamicRetrievalConfig": {
    object (DynamicRetrievalConfig)
  }
}

DynamicRetrievalConfig

동적 검색을 맞춤설정하는 옵션을 설명합니다.

필드
mode enum (Mode)

동적 검색에 사용할 예측자의 모드입니다.

dynamicThreshold number

동적 검색에 사용할 임계값입니다. 설정하지 않으면 시스템 기본값이 사용됩니다.

JSON 표현
{
  "mode": enum (Mode),
  "dynamicThreshold": number
}

모드

동적 검색에 사용할 예측자의 모드입니다.

열거형
MODE_UNSPECIFIED 항상 검색을 트리거합니다.
MODE_DYNAMIC 시스템에서 필요하다고 판단하는 경우에만 검색을 실행합니다.

CodeExecution

이 유형에는 필드가 없습니다.

모델에서 생성된 코드를 실행하고 결과를 모델에 자동으로 반환하는 도구입니다.

이 도구를 사용할 때만 생성되는 ExecutableCodeCodeExecutionResult도 참고하세요.

ToolConfig

요청에서 Tool 사용을 지정하기 위한 매개변수가 포함된 도구 구성입니다.

필드
functionCallingConfig object (FunctionCallingConfig)

선택사항입니다. 함수 호출 구성

JSON 표현
{
  "functionCallingConfig": {
    object (FunctionCallingConfig)
  }
}

FunctionCallingConfig

함수 호출 동작을 지정하기 위한 구성입니다.

필드
mode enum (Mode)

선택사항입니다. 함수 호출을 실행해야 하는 모드를 지정합니다. 지정하지 않으면 기본값은 AUTO로 설정됩니다.

allowedFunctionNames[] string

선택사항입니다. 제공된 경우 모델이 호출할 함수를 제한하는 함수 이름 집합입니다.

모드가 ANY인 경우에만 설정해야 합니다. 함수 이름은 [FunctionDeclaration.name]과 일치해야 합니다. 모드를 ANY로 설정하면 모델이 제공된 함수 이름 세트에서 함수 호출을 예측합니다.

JSON 표현
{
  "mode": enum (Mode),
  "allowedFunctionNames": [
    string
  ]
}

모드

실행 모드를 정의하여 함수 호출의 실행 동작을 정의합니다.

열거형
MODE_UNSPECIFIED 지정되지 않은 함수 호출 모드입니다. 이 값은 사용하면 안 됩니다.
AUTO 기본 모델 동작으로, 모델이 함수 호출 또는 자연어 응답을 예측하도록 결정합니다.
ANY 모델이 항상 함수 호출만 예측하도록 제한됩니다. 'allowedFunctionNames'가 설정되면 예측 함수 호출이 'allowedFunctionNames' 중 하나로 제한됩니다. 그러지 않으면 예측 함수 호출은 제공된 'functionDeclarations' 중 하나가 됩니다.
NONE 모델이 함수 호출을 예측하지 않습니다. 모델 동작은 함수 선언을 전달하지 않는 경우와 동일합니다.

UsageMetadata

캐시된 콘텐츠 사용에 관한 메타데이터입니다.

필드
totalTokenCount integer

캐시된 콘텐츠에서 사용하는 총 토큰 수입니다.

JSON 표현
{
  "totalTokenCount": integer
}