Caching

Tính năng lưu vào bộ nhớ đệm theo ngữ cảnh cho phép bạn lưu và sử dụng lại những mã thông báo đầu vào đã tính toán sẵn mà bạn muốn dùng nhiều lần, chẳng hạn như khi đặt nhiều câu hỏi về cùng một tệp nội dung nghe nhìn. Điều này có thể giúp tiết kiệm chi phí và tốc độ, tuỳ thuộc vào mức sử dụng. Để biết thông tin giới thiệu chi tiết, hãy xem hướng dẫn Lưu bối cảnh vào bộ nhớ đệm.

Phương thức: cachedContents.create

Tạo tài nguyên CachedContent.

Điểm cuối

đăng https://generativelanguage.googleapis.com/v1beta/cachedContents

Nội dung yêu cầu

Nội dung yêu cầu chứa một bản sao của CachedContent.

Trường
contents[] object (Content)

Không bắt buộc. Chỉ nhập. Không thể thay đổi. Nội dung được lưu vào bộ nhớ đệm.

tools[] object (Tool)

Không bắt buộc. Chỉ nhập. Không thể thay đổi. Danh sách Tools mà mô hình có thể dùng để tạo phản hồi tiếp theo

Trường kết hợp expiration. Chỉ định thời điểm tài nguyên này hết hạn. expiration chỉ có thể là một trong những giá trị sau:
expireTime string (Timestamp format)

Dấu thời gian theo giờ UTC của thời điểm tài nguyên này được xem là hết hạn. Giá trị này luôn được cung cấp ở đầu ra, bất kể giá trị nào được gửi ở đầu vào.

Dấu thời gian ở định dạng "Zulu" RFC3339 UTC, có độ phân giải nano giây và tối đa 9 chữ số thập phân. Ví dụ: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z".

ttl string (Duration format)

Chỉ nhập. TTL mới cho tài nguyên này, chỉ nhập.

Thời lượng tính bằng giây, có tối đa 9 chữ số thập phân, kết thúc bằng "s". Ví dụ: "3.5s".

name string

Không bắt buộc. Giá trị nhận dạng. Tên tài nguyên tham chiếu đến nội dung được lưu vào bộ nhớ đệm. Định dạng cachedContents/{id}

displayName string

Không bắt buộc. Không thể thay đổi. Tên hiển thị có ý nghĩa do người dùng tạo cho nội dung được lưu vào bộ nhớ đệm. Tối đa 128 ký tự Unicode.

model string

Bắt buộc. Không thể thay đổi. Tên của Model để sử dụng cho nội dung được lưu vào bộ nhớ đệm Định dạng: models/{model}

systemInstruction object (Content)

Không bắt buộc. Chỉ nhập. Không thể thay đổi. Hướng dẫn hệ thống do nhà phát triển đặt. Hiện chỉ có văn bản.

toolConfig object (ToolConfig)

Không bắt buộc. Chỉ nhập. Bất biến. Cấu hình công cụ. Cấu hình này được dùng chung cho tất cả công cụ.

Yêu cầu mẫu

Cơ bản

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)

Vỏ

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'"
    }'

Tên người gửi

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)

Trong cuộc trò chuyện

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)

Nội dung phản hồi

Nếu thành công, nội dung phản hồi sẽ chứa một thực thể mới tạo của CachedContent.

Phương thức: cachedContents.list

Liệt kê CachedContents.

Điểm cuối

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

Tham số truy vấn

pageSize integer

Không bắt buộc. Số lượng nội dung tối đa được lưu vào bộ nhớ đệm để trả về. Dịch vụ có thể trả về ít hơn giá trị này. Nếu không chỉ định, một số số lượng mặt hàng mặc định (dưới mức tối đa) sẽ được trả về. Giá trị tối đa là 1000; các giá trị trên 1000 sẽ được chuyển đổi thành 1000.

pageToken string

Không bắt buộc. Mã thông báo trang, nhận được từ lệnh gọi cachedContents.list trước đó. Cung cấp mã này để truy xuất trang tiếp theo.

Khi phân trang, tất cả các tham số khác được cung cấp cho cachedContents.list phải khớp với lệnh gọi đã cung cấp mã thông báo trang.

Nội dung yêu cầu

Nội dung yêu cầu phải trống.

Nội dung phản hồi

Phản hồi bằng danh sách CachedContents.

Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:

Trường
cachedContents[] object (CachedContent)

Danh sách nội dung được lưu trong bộ nhớ đệm.

nextPageToken string

Mã thông báo có thể được gửi dưới dạng pageToken để truy xuất trang tiếp theo. Nếu bạn bỏ qua trường này, thì sẽ không có trang tiếp theo.

Biểu diễn dưới dạng JSON
{
  "cachedContents": [
    {
      object (CachedContent)
    }
  ],
  "nextPageToken": string
}

Phương thức: cachedContents.get

Đọc tài nguyên CachedContent.

Điểm cuối

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

Tham số đường dẫn

name string

Bắt buộc. Tên tài nguyên tham chiếu đến mục trong bộ nhớ đệm nội dung. Định dạng: cachedContents/{id}. Định dạng này có dạng cachedContents/{cachedcontent}.

Nội dung yêu cầu

Nội dung yêu cầu phải trống.

Yêu cầu mẫu

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)

Vỏ

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

Nội dung phản hồi

Nếu thành công, nội dung phản hồi sẽ chứa một phiên bản của CachedContent.

Phương thức: cachedContents.patch

Cập nhật tài nguyên Nội dung được lưu vào bộ nhớ đệm (chỉ có thể cập nhật khi hết hạn).

Điểm cuối

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

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

Tham số đường dẫn

cachedContent.name string

Không bắt buộc. Giá trị nhận dạng. Tên tài nguyên tham chiếu đến nội dung được lưu vào bộ nhớ đệm. Định dạng: cachedContents/{id}. Định dạng này có dạng cachedContents/{cachedcontent}.

Tham số truy vấn

updateMask string (FieldMask format)

Danh sách các trường cần cập nhật.

Đây là danh sách các tên trường đủ điều kiện được phân tách bằng dấu phẩy. Ví dụ: "user.displayName,photo"

Nội dung yêu cầu

Nội dung yêu cầu chứa một bản sao của CachedContent.

Các trường
Trường hợp hợp nhất expiration. Chỉ định thời điểm tài nguyên này hết hạn. expiration chỉ có thể là một trong những giá trị sau:
expireTime string (Timestamp format)

Dấu thời gian theo giờ UTC của thời điểm tài nguyên này được xem là hết hạn. Giá trị này luôn được cung cấp ở đầu ra, bất kể giá trị nào được gửi ở đầu vào.

Dấu thời gian ở định dạng "Zulu" RFC3339 UTC, có độ phân giải nano giây và tối đa 9 chữ số thập phân. Ví dụ: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z".

ttl string (Duration format)

Chỉ nhập. TTL mới cho tài nguyên này, chỉ nhập.

Thời lượng tính bằng giây, có tối đa 9 chữ số thập phân, kết thúc bằng "s". Ví dụ: "3.5s".

name string

Không bắt buộc. Giá trị nhận dạng. Tên tài nguyên tham chiếu đến nội dung được lưu vào bộ nhớ đệm. Định dạng cachedContents/{id}

Yêu cầu mẫu

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)

Vỏ

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

Nội dung phản hồi

Nếu thành công, nội dung phản hồi sẽ chứa một phiên bản của CachedContent.

Phương thức: cachedContents.delete

Xoá tài nguyên CachedContent.

Điểm cuối

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

Tham số đường dẫn

name string

Bắt buộc. Tên tài nguyên tham chiếu đến mục nhập bộ nhớ đệm nội dung Định dạng: cachedContents/{id} Tên này có dạng cachedContents/{cachedcontent}.

Nội dung yêu cầu

Nội dung yêu cầu phải trống.

Yêu cầu mẫu

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)

Vỏ

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

Nội dung phản hồi

Nếu thành công, nội dung phản hồi sẽ trống.

Tài nguyên REST: cachedContents

Tài nguyên: CachedContent

Nội dung đã được xử lý trước và có thể được dùng trong yêu cầu tiếp theo cho GenerativeService.

Bạn chỉ có thể sử dụng nội dung được lưu vào bộ nhớ đệm với mô hình mà nội dung đó được tạo.

Trường
contents[] object (Content)

Không bắt buộc. Chỉ nhập. Không thể thay đổi. Nội dung được lưu vào bộ nhớ đệm.

tools[] object (Tool)

Không bắt buộc. Chỉ nhập. Không thể thay đổi. Danh sách Tools mà mô hình có thể sử dụng để tạo phản hồi tiếp theo

createTime string (Timestamp format)

Chỉ có đầu ra. Thời gian tạo mục nhập bộ nhớ đệm.

Dấu thời gian ở định dạng "Zulu" RFC3339 UTC, có độ phân giải nano giây và tối đa 9 chữ số thập phân. Ví dụ: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z".

updateTime string (Timestamp format)

Chỉ có đầu ra. Lần cập nhật gần đây nhất của mục trong bộ nhớ đệm theo giờ UTC.

Dấu thời gian ở định dạng "Zulu" RFC3339 UTC, có độ phân giải nano giây và tối đa 9 chữ số thập phân. Ví dụ: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z".

usageMetadata object (UsageMetadata)

Chỉ có đầu ra. Siêu dữ liệu về việc sử dụng nội dung được lưu vào bộ nhớ đệm.

Trường hợp hợp nhất expiration. Chỉ định thời điểm tài nguyên này hết hạn. expiration chỉ có thể là một trong những giá trị sau:
expireTime string (Timestamp format)

Dấu thời gian theo giờ UTC của thời điểm tài nguyên này được xem là hết hạn. Giá trị này luôn được cung cấp ở đầu ra, bất kể giá trị nào được gửi ở đầu vào.

Dấu thời gian ở định dạng "Zulu" RFC3339 UTC, có độ phân giải nano giây và tối đa 9 chữ số thập phân. Ví dụ: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z".

ttl string (Duration format)

Chỉ nhập. TTL mới cho tài nguyên này, chỉ nhập.

Thời lượng tính bằng giây, có tối đa 9 chữ số thập phân, kết thúc bằng "s". Ví dụ: "3.5s".

name string

Không bắt buộc. Giá trị nhận dạng. Tên tài nguyên tham chiếu đến nội dung được lưu vào bộ nhớ đệm. Định dạng cachedContents/{id}

displayName string

Không bắt buộc. Không thể thay đổi. Tên hiển thị có ý nghĩa do người dùng tạo cho nội dung được lưu vào bộ nhớ đệm. Tối đa 128 ký tự Unicode.

model string

Bắt buộc. Không thể thay đổi. Tên của Model để sử dụng cho nội dung được lưu vào bộ nhớ đệm Định dạng: models/{model}

systemInstruction object (Content)

Không bắt buộc. Chỉ nhập. Không thể thay đổi. Hướng dẫn hệ thống do nhà phát triển đặt. Hiện chỉ có văn bản.

toolConfig object (ToolConfig)

Không bắt buộc. Chỉ nhập. Không thể thay đổi. Cấu hình công cụ. Cấu hình này được chia sẻ cho tất cả các công cụ.

Biểu diễn dưới dạng 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)
  }
}

Nội dung

Loại dữ liệu có cấu trúc cơ sở chứa nội dung nhiều phần của một thông báo.

Content bao gồm một trường role chỉ định nhà sản xuất của Content và một trường parts chứa dữ liệu nhiều phần chứa nội dung của lượt gửi tin nhắn.

Trường
parts[] object (Part)

Parts đã sắp xếp tạo thành một thông báo duy nhất. Các phần có thể có nhiều loại MIME.

role string

Không bắt buộc. Nhà sản xuất nội dung. Phải là "user" hoặc "model".

Hữu ích khi thiết lập cho các cuộc trò chuyện nhiều lượt, nếu không có thể để trống hoặc không đặt.

Biểu diễn dưới dạng JSON
{
  "parts": [
    {
      object (Part)
    }
  ],
  "role": string
}

Phần

Loại dữ liệu chứa nội dung đa phương tiện là một phần của tin nhắn Content nhiều phần.

Part bao gồm dữ liệu có kiểu dữ liệu được liên kết. Part chỉ có thể chứa một trong các kiểu được chấp nhận trong Part.data.

Part phải có loại MIME IANA cố định xác định loại và loại phụ của nội dung nghe nhìn nếu trường inlineData được điền bằng các byte thô.

Các trường

Trường hợp hợp nhất data.

data chỉ có thể là một trong những giá trị sau:

text string

Văn bản nội tuyến.

inlineData object (Blob)

Byte nội dung nghe nhìn cùng dòng.

functionCall object (FunctionCall)

FunctionCall được dự đoán được trả về từ mô hình chứa một chuỗi đại diện cho FunctionDeclaration.name với các đối số và giá trị của các đối số đó.

functionResponse object (FunctionResponse)

Kết quả đầu ra của FunctionCall chứa một chuỗi đại diện cho FunctionDeclaration.name và một đối tượng JSON có cấu trúc chứa bất kỳ đầu ra nào từ hàm được dùng làm ngữ cảnh cho mô hình.

fileData object (FileData)

Dữ liệu dựa trên URI.

executableCode object (ExecutableCode)

Mã do mô hình tạo ra và sẽ được thực thi.

codeExecutionResult object (CodeExecutionResult)

Kết quả của việc thực thi ExecutableCode.

Biểu diễn dưới dạng 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

Byte nội dung nghe nhìn thô.

Không được gửi văn bản dưới dạng byte thô, hãy sử dụng trường "text".

Trường
mimeType string

Loại MIME tiêu chuẩn IANA của dữ liệu nguồn. Ví dụ: – image/png – image/jpeg Nếu bạn cung cấp loại MIME không được hỗ trợ, hệ thống sẽ trả về lỗi. Để biết danh sách đầy đủ các loại được hỗ trợ, hãy xem Định dạng tệp được hỗ trợ.

data string (bytes format)

Byte thô cho các định dạng nội dung nghe nhìn.

Chuỗi được mã hoá base64.

Biểu diễn dưới dạng JSON
{
  "mimeType": string,
  "data": string
}

FunctionCall

FunctionCall được dự đoán được trả về từ mô hình chứa một chuỗi đại diện cho FunctionDeclaration.name với các đối số và giá trị của các đối số đó.

Trường
name string

Bắt buộc. Tên của hàm cần gọi. Phải là a-z, A-Z, 0-9 hoặc chứa dấu gạch dưới và dấu gạch ngang, với độ dài tối đa là 63.

args object (Struct format)

Không bắt buộc. Các tham số và giá trị hàm ở định dạng đối tượng JSON.

Biểu diễn dưới dạng JSON
{
  "name": string,
  "args": {
    object
  }
}

FunctionResponse

Kết quả đầu ra từ FunctionCall chứa một chuỗi đại diện cho FunctionDeclaration.name và một đối tượng JSON có cấu trúc chứa bất kỳ đầu ra nào từ hàm được dùng làm ngữ cảnh cho mô hình. Tệp này phải chứa kết quả của FunctionCall được tạo dựa trên dự đoán của mô hình.

Trường
name string

Bắt buộc. Tên hàm cần gọi. Phải là a-z, A-Z, 0-9 hoặc chứa dấu gạch dưới và dấu gạch ngang, với độ dài tối đa là 63.

response object (Struct format)

Bắt buộc. Phản hồi hàm ở định dạng đối tượng JSON.

Biểu diễn dưới dạng JSON
{
  "name": string,
  "response": {
    object
  }
}

FileData

Dữ liệu dựa trên URI.

Trường
mimeType string

Không bắt buộc. Loại MIME theo tiêu chuẩn IANA của dữ liệu nguồn.

fileUri string

Bắt buộc. URI.

Biểu diễn dưới dạng JSON
{
  "mimeType": string,
  "fileUri": string
}

ExecutableCode

Mã do mô hình tạo ra để thực thi và kết quả được trả về cho mô hình.

Chỉ được tạo khi sử dụng công cụ CodeExecution, trong đó mã sẽ được tự động thực thi và CodeExecutionResult tương ứng cũng sẽ được tạo.

Trường
language enum (Language)

Bắt buộc. Ngôn ngữ lập trình của code.

code string

Bắt buộc. Mã cần thực thi.

Biểu diễn dưới dạng JSON
{
  "language": enum (Language),
  "code": string
}

Ngôn ngữ

Ngôn ngữ lập trình được hỗ trợ cho mã được tạo.

Enum
LANGUAGE_UNSPECIFIED Ngôn ngữ không xác định. Không nên sử dụng giá trị này.
PYTHON Python >= 3.10, có numpy và simpy.

CodeExecutionResult

Kết quả của việc thực thi ExecutableCode.

Chỉ được tạo khi sử dụng CodeExecution và luôn tuân theo part chứa ExecutableCode.

Trường
outcome enum (Outcome)

Bắt buộc. Kết quả của quá trình thực thi mã.

output string

Không bắt buộc. Chứa stdout khi thực thi mã thành công, stderr hoặc các nội dung mô tả khác.

Biểu diễn dưới dạng JSON
{
  "outcome": enum (Outcome),
  "output": string
}

Kết quả

Liệt kê các kết quả có thể xảy ra khi thực thi mã.

Enum
OUTCOME_UNSPECIFIED Trạng thái không xác định. Không nên sử dụng giá trị này.
OUTCOME_OK Đã thực thi mã thành công.
OUTCOME_FAILED Quá trình thực thi mã đã kết thúc nhưng có lỗi. stderr phải chứa lý do.
OUTCOME_DEADLINE_EXCEEDED Quá trình thực thi mã đã chạy quá lâu và bị huỷ. Có thể có hoặc không có kết quả một phần.

Công cụ

Thông tin chi tiết về công cụ mà mô hình có thể sử dụng để tạo phản hồi.

Tool là một đoạn mã cho phép hệ thống tương tác với các hệ thống bên ngoài để thực hiện một hành động hoặc một tập hợp hành động nằm ngoài kiến thức và phạm vi của mô hình.

Trường
functionDeclarations[] object (FunctionDeclaration)

Không bắt buộc. Danh sách FunctionDeclarations có sẵn cho mô hình có thể dùng để gọi hàm.

Mô hình hoặc hệ thống không thực thi hàm. Thay vào đó, hàm đã xác định có thể được trả về dưới dạng FunctionCall với các đối số cho phía máy khách để thực thi. Mô hình có thể quyết định gọi một tập hợp con của các hàm này bằng cách điền FunctionCall vào phản hồi. Lượt trò chuyện tiếp theo có thể chứa FunctionResponse với ngữ cảnh tạo "hàm" Content.role cho lượt mô hình tiếp theo.

googleSearchRetrieval object (GoogleSearchRetrieval)

Không bắt buộc. Công cụ truy xuất do Google Tìm kiếm cung cấp.

codeExecution object (CodeExecution)

Không bắt buộc. Cho phép mô hình thực thi mã trong quá trình tạo.

Biểu diễn dưới dạng JSON
{
  "functionDeclarations": [
    {
      object (FunctionDeclaration)
    }
  ],
  "googleSearchRetrieval": {
    object (GoogleSearchRetrieval)
  },
  "codeExecution": {
    object (CodeExecution)
  }
}

FunctionDeclaration

Biểu diễn có cấu trúc của nội dung khai báo hàm theo định nghĩa của quy cách OpenAPI 3.03. Tên hàm và tham số có trong phần khai báo này. FunctionDeclaration này là một bản trình bày của một khối mã mà mô hình có thể sử dụng làm Tool và ứng dụng thực thi.

Trường
name string

Bắt buộc. Tên của hàm. Phải là a-z, A-Z, 0-9 hoặc chứa dấu gạch dưới và dấu gạch ngang, với độ dài tối đa là 63.

description string

Bắt buộc. Nội dung mô tả ngắn gọn về hàm.

parameters object (Schema)

Không bắt buộc. Mô tả các tham số cho hàm này. Phản ánh khoá chuỗi Đối tượng tham số Open API 3.03: tên của tham số. Tên tham số phân biệt chữ hoa chữ thường. Giá trị giản đồ: Giản đồ xác định loại được dùng cho tham số.

Biểu diễn dưới dạng JSON
{
  "name": string,
  "description": string,
  "parameters": {
    object (Schema)
  }
}

Lược đồ

Đối tượng Schema cho phép định nghĩa các kiểu dữ liệu đầu vào và đầu ra. Các loại này có thể là đối tượng, nhưng cũng có thể là dữ liệu gốc và mảng. Biểu thị một tập hợp con chọn lọc của đối tượng giản đồ OpenAPI 3.0.

Trường
type enum (Type)

Bắt buộc. Loại dữ liệu.

format string

Không bắt buộc. Định dạng của dữ liệu. Phương thức này chỉ dùng cho các kiểu dữ liệu gốc. Các định dạng được hỗ trợ: cho loại NUMBER: số thực, gấp đôi cho loại INTEGER: int32, int64 cho loại CHUỖI: enum

description string

Không bắt buộc. Nội dung mô tả ngắn gọn về thông số. Ví dụ về cách sử dụng. Phần mô tả tham số có thể được định dạng dưới dạng Markdown.

nullable boolean

Không bắt buộc. Cho biết liệu giá trị có thể rỗng hay không.

enum[] string

Không bắt buộc. Các giá trị có thể có của phần tử Type.STRING có định dạng enum. Ví dụ: chúng ta có thể xác định một Enum Direction như sau: {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

maxItems string (int64 format)

Không bắt buộc. Số lượng phần tử tối đa cho Type.ARRAY.

minItems string (int64 format)

Không bắt buộc. Số lượng phần tử tối thiểu cho Type.ARRAY.

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

Không bắt buộc. Thuộc tính của Type.OBJECT.

Một đối tượng chứa danh sách các cặp "key": value. Ví dụ: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

required[] string

Không bắt buộc. Các thuộc tính bắt buộc của Type.OBJECT.

items object (Schema)

Không bắt buộc. Giản đồ của các phần tử của Type.ARRAY.

Biểu diễn dưới dạng 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)
  }
}

Loại

Type chứa danh sách các loại dữ liệu OpenAPI do https://spec.openapis.org/oas/v3.0.3#data-types xác định

Enum
TYPE_UNSPECIFIED Không được chỉ định, không nên sử dụng.
STRING Loại chuỗi.
NUMBER Loại số.
INTEGER Loại số nguyên.
BOOLEAN Loại boolean.
ARRAY Loại mảng.
OBJECT Loại đối tượng.

GoogleSearchRetrieval

Công cụ do Google cung cấp để truy xuất dữ liệu công khai trên web nhằm xác minh thông tin.

Trường
dynamicRetrievalConfig object (DynamicRetrievalConfig)

Chỉ định cấu hình truy xuất động cho nguồn đã cho.

Biểu diễn dưới dạng JSON
{
  "dynamicRetrievalConfig": {
    object (DynamicRetrievalConfig)
  }
}

DynamicRetrievalConfig

Mô tả các lựa chọn để tuỳ chỉnh tính năng truy xuất động.

Trường
mode enum (Mode)

Chế độ của trình dự đoán sẽ được dùng trong quá trình truy xuất động.

dynamicThreshold number

Ngưỡng sẽ được sử dụng trong quá trình truy xuất động. Nếu bạn không đặt giá trị này, hệ thống sẽ sử dụng giá trị mặc định.

Biểu diễn dưới dạng JSON
{
  "mode": enum (Mode),
  "dynamicThreshold": number
}

Chế độ

Chế độ của trình dự đoán sẽ được dùng trong quá trình truy xuất động.

Enum
MODE_UNSPECIFIED Luôn kích hoạt quá trình truy xuất.
MODE_DYNAMIC Chỉ chạy quá trình truy xuất khi hệ thống quyết định cần thiết.

CodeExecution

Loại này không có trường nào.

Công cụ thực thi mã do mô hình tạo ra và tự động trả về kết quả cho mô hình.

Xem thêm ExecutableCodeCodeExecutionResult chỉ được tạo khi sử dụng công cụ này.

ToolConfig

Cấu hình công cụ chứa các tham số để chỉ định việc sử dụng Tool trong yêu cầu.

Trường
functionCallingConfig object (FunctionCallingConfig)

Không bắt buộc. Cấu hình gọi hàm.

Biểu diễn dưới dạng JSON
{
  "functionCallingConfig": {
    object (FunctionCallingConfig)
  }
}

FunctionCallingConfig

Cấu hình để chỉ định hành vi gọi hàm.

Trường
mode enum (Mode)

Không bắt buộc. Chỉ định chế độ thực thi lệnh gọi hàm. Nếu bạn không chỉ định, giá trị mặc định sẽ được đặt thành AUTO.

allowedFunctionNames[] string

Không bắt buộc. Một tập hợp tên hàm (khi được cung cấp) sẽ giới hạn các hàm mà mô hình sẽ gọi.

Bạn chỉ nên đặt giá trị này khi Chế độ là BẤT KỲ. Tên hàm phải khớp với [FunctionDeclaration.name]. Khi chế độ được đặt thành BẤT KỲ, mô hình sẽ dự đoán lệnh gọi hàm từ tập hợp tên hàm được cung cấp.

Biểu diễn dưới dạng JSON
{
  "mode": enum (Mode),
  "allowedFunctionNames": [
    string
  ]
}

Chế độ

Xác định hành vi thực thi cho lệnh gọi hàm bằng cách xác định chế độ thực thi.

Enum
MODE_UNSPECIFIED Chế độ gọi hàm không xác định. Không nên sử dụng giá trị này.
AUTO Hành vi mặc định của mô hình, mô hình quyết định dự đoán lệnh gọi hàm hoặc câu trả lời bằng ngôn ngữ tự nhiên.
ANY Mô hình bị ràng buộc để luôn chỉ dự đoán một lệnh gọi hàm. Nếu bạn đặt " allowedFunctionNames", thì lệnh gọi hàm dự đoán sẽ bị giới hạn ở bất kỳ một trong số "".
NONE Mô hình sẽ không dự đoán bất kỳ lệnh gọi hàm nào. Hành vi của mô hình cũng giống như khi không truyền bất kỳ nội dung khai báo hàm nào.

UsageMetadata

Siêu dữ liệu về việc sử dụng nội dung được lưu vào bộ nhớ đệm.

Trường
totalTokenCount integer

Tổng số mã thông báo mà nội dung lưu vào bộ nhớ đệm sử dụng.

Biểu diễn dưới dạng JSON
{
  "totalTokenCount": integer
}